From 0cbe1502da84fde4fbee65faf0a9a4c5ed738f30 Mon Sep 17 00:00:00 2001 From: priyanshuhaldar007 Date: Thu, 23 Jul 2026 19:48:53 +0530 Subject: [PATCH 1/4] feat: add semantic search experiment to AI plugin --- includes/Experiments/Experiments.php | 1 + .../Semantic_Search/Embedding_Api.php | 383 ++++++++++++++++++ .../Semantic_Search/Embedding_Store.php | 166 ++++++++ .../Semantic_Search/Index_Page.php | 266 ++++++++++++ .../Experiments/Semantic_Search/Indexer.php | 131 ++++++ .../List_Table_Integration.php | 148 +++++++ .../Semantic_Search/REST_Controller.php | 215 ++++++++++ .../Semantic_Search/Semantic_Search.php | 270 ++++++++++++ .../Semantic_Search/Vector_Search.php | 177 ++++++++ 9 files changed, 1757 insertions(+) create mode 100644 includes/Experiments/Semantic_Search/Embedding_Api.php create mode 100644 includes/Experiments/Semantic_Search/Embedding_Store.php create mode 100644 includes/Experiments/Semantic_Search/Index_Page.php create mode 100644 includes/Experiments/Semantic_Search/Indexer.php create mode 100644 includes/Experiments/Semantic_Search/List_Table_Integration.php create mode 100644 includes/Experiments/Semantic_Search/REST_Controller.php create mode 100644 includes/Experiments/Semantic_Search/Semantic_Search.php create mode 100644 includes/Experiments/Semantic_Search/Vector_Search.php diff --git a/includes/Experiments/Experiments.php b/includes/Experiments/Experiments.php index 4799075ec..58b70921c 100644 --- a/includes/Experiments/Experiments.php +++ b/includes/Experiments/Experiments.php @@ -27,6 +27,7 @@ final class Experiments { * @var array> */ private const EXPERIMENT_CLASSES = array( // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is used as an array const. + \WordPress\AI\Experiments\Semantic_Search\Semantic_Search::class, \WordPress\AI\Experiments\Abilities_Explorer\Abilities_Explorer::class, \WordPress\AI\Experiments\AI_Request_Logging\AI_Request_Logging::class, \WordPress\AI\Experiments\Connector_Approval\Connector_Approval::class, diff --git a/includes/Experiments/Semantic_Search/Embedding_Api.php b/includes/Experiments/Semantic_Search/Embedding_Api.php new file mode 100644 index 000000000..e547d61cd --- /dev/null +++ b/includes/Experiments/Semantic_Search/Embedding_Api.php @@ -0,0 +1,383 @@ +generateEmbeddingResult() + * and let the registered connector handle authentication + transport. + * + * @package WordPress\AI\Experiments\Semantic_Search + */ + +declare( strict_types=1 ); + +namespace WordPress\AI\Experiments\Semantic_Search; + +// Exit if accessed directly. +defined( 'ABSPATH' ) || exit; + +/** + * Sends text to an embedding API and returns a float vector. + * + * Supports four providers out of the box: OpenAI, Jina AI, Ollama (local), + * and Google Gemini. Provider selection and credentials are read from the + * namespaced WordPress options registered by the Semantic_Search experiment. + * + * @internal + * @since x.x.x + */ +class Embedding_Api { + + /** + * Per-provider configuration defaults. + * + * Each entry contains: + * - label: Human-readable provider name. + * - default_url: API base URL used when no override is saved. + * - default_model: Model identifier used when no override is saved. + * - dimensions: Output vector length. Source: official model documentation. + * - score_threshold: Cosine similarity cut-off. These are heuristics — no + * authoritative published benchmarks exist. Tune via Settings. + * + * @since x.x.x + * @var array + */ + public const PROVIDERS = array( + 'openai' => array( + 'label' => 'OpenAI', + 'default_url' => 'https://api.openai.com/v1/embeddings', + 'default_model' => 'text-embedding-3-small', + 'dimensions' => 1536, + 'score_threshold' => 0.60, + ), + 'jina' => array( + 'label' => 'Jina AI', + 'default_url' => 'https://api.jina.ai/v1/embeddings', + 'default_model' => 'jina-embeddings-v3', + 'dimensions' => 1024, + 'score_threshold' => 0.55, + ), + 'ollama' => array( + 'label' => 'Ollama (local)', + 'default_url' => 'http://localhost:11434/v1/embeddings', + 'default_model' => 'nomic-embed-text', + 'dimensions' => 768, + 'score_threshold' => 0.50, + ), + 'google' => array( + 'label' => 'Google Gemini', + 'default_url' => 'https://generativelanguage.googleapis.com/v1/models', + 'default_model' => 'gemini-embedding-001', + 'dimensions' => 3072, + 'score_threshold' => 0.45, + ), + ); + + /** + * Active provider key (e.g. 'openai', 'google'). + * + * @since x.x.x + * @var string + */ + private string $provider; + + /** + * API key for the active provider. Empty for Ollama. + * + * @since x.x.x + * @var string + */ + private string $api_key; + + /** + * Embedding model identifier (e.g. 'text-embedding-3-small'). + * + * @since x.x.x + * @var string + */ + private string $model; + + /** + * API base URL for the active provider. + * + * @since x.x.x + * @var string + */ + private string $base_url; + + /** + * Human-readable description of the last API error, or empty string if none. + * + * @since x.x.x + * @var string + */ + private string $last_error = ''; + + /** + * Reads all provider configuration from the saved experiment options. + * + * @since x.x.x + */ + public function __construct() { + $this->provider = (string) get_option( Semantic_Search::get_field_option_name( 'provider' ), 'openai' ); + $this->api_key = (string) get_option( Semantic_Search::get_field_option_name( 'api_key' ), '' ); + $this->model = (string) get_option( Semantic_Search::get_field_option_name( 'model' ), 'text-embedding-3-small' ); + $this->base_url = (string) get_option( Semantic_Search::get_field_option_name( 'base_url' ), 'https://api.openai.com/v1/embeddings' ); + } + + /** + * Returns the active model identifier. + * + * @since x.x.x + * + * @return string Model identifier string (e.g. 'gemini-embedding-001'). + */ + public function get_model(): string { + return $this->model; + } + + /** + * Returns the active provider key. + * + * @since x.x.x + * + * @return string Provider key (e.g. 'openai', 'google'). + */ + public function get_provider(): string { + return $this->provider; + } + + /** + * Returns the human-readable error message from the most recent API call. + * + * Returns an empty string when the last call succeeded. + * + * @since x.x.x + * + * @return string Error description, or empty string on success. + */ + public function get_last_error(): string { + return $this->last_error; + } + + /** + * Returns whether the provider is ready to accept embedding requests. + * + * Ollama requires only a non-empty model name (no key). All other providers + * require a non-empty API key. + * + * @since x.x.x + * + * @return bool True when the minimum required credentials are present. + */ + public function is_configured(): bool { + if ( 'ollama' === $this->provider ) { + return '' !== $this->model; + } + + return '' !== $this->api_key; + } + + /** + * Returns the cosine similarity score threshold for the active provider. + * + * Reads the user-saved option first; falls back to the per-provider default + * from PROVIDERS when the option is empty. An empty string means "use the + * provider default" and is backward-compatible with existing installs that + * predate the user-editable threshold field. + * + * @since x.x.x + * + * @return float Cosine similarity cut-off in the range [0, 1]. + */ + public function get_score_threshold(): float { + $cfg = self::PROVIDERS[ $this->provider ] ?? self::PROVIDERS['openai']; + $saved = (string) get_option( Semantic_Search::get_field_option_name( 'score_threshold' ), '' ); + + return '' !== $saved ? (float) $saved : $cfg['score_threshold']; + } + + /** + * Sends text to the configured embedding provider and returns a float vector. + * + * Dispatches to the Google-specific or OpenAI-compatible implementation + * depending on the active provider. Returns null on any API error; call + * get_last_error() to retrieve the reason. + * + * @since x.x.x + * + * @param string $text The text to embed. + * @return float[]|null Float vector on success, null on failure. + */ + public function generate( string $text ): ?array { + $this->last_error = ''; + + if ( 'google' === $this->provider ) { + return $this->generate_google( $text ); + } + + return $this->generate_openai_compatible( $text ); + } + + /** + * Generates an embedding using the OpenAI-compatible request format. + * + * Used for OpenAI, Jina AI, and Ollama. The Authorization header is omitted + * for Ollama since it requires no API key. + * + * @since x.x.x + * + * @param string $text The text to embed. + * @return float[]|null Float vector on success, null on failure. + */ + private function generate_openai_compatible( string $text ): ?array { + $headers = array( 'Content-Type' => 'application/json' ); + + if ( 'ollama' !== $this->provider ) { + $headers['Authorization'] = 'Bearer ' . $this->api_key; + } + + $response = wp_remote_post( + $this->base_url, + array( + 'timeout' => 30, + 'headers' => $headers, + 'body' => wp_json_encode( + array( + 'input' => $text, + 'model' => $this->model, + ) + ), + ) + ); + + return $this->parse_openai_response( $response ); + } + + /** + * Generates an embedding using the Google Gemini embedContent API. + * + * Google's API differs from the OpenAI-compatible format in three ways: + * - The model name is appended to the URL path, not sent in the body. + * - The API key is passed as a query parameter, not an Authorization header. + * - The request body uses `content.parts[].text` instead of `input`. + * + * @since x.x.x + * + * @param string $text The text to embed. + * @return float[]|null Float vector on success, null on failure. + */ + private function generate_google( string $text ): ?array { + $endpoint = rtrim( $this->base_url, '/' ) . '/' . $this->model . ':embedContent?key=' . $this->api_key; + + $response = wp_remote_post( + $endpoint, + array( + 'timeout' => 30, + 'headers' => array( 'Content-Type' => 'application/json' ), + 'body' => wp_json_encode( + array( + 'content' => array( + 'parts' => array( + array( 'text' => $text ), + ), + ), + ) + ), + ) + ); + + if ( is_wp_error( $response ) ) { + $this->last_error = $response->get_error_message(); + return null; + } + + $code = wp_remote_retrieve_response_code( $response ); + $body = json_decode( wp_remote_retrieve_body( $response ), true ); + + if ( 200 !== $code ) { + $this->last_error = sprintf( 'HTTP %d: %s', $code, $body['error']['message'] ?? 'unknown error' ); + return null; + } + + $values = $body['embedding']['values'] ?? null; + + if ( ! is_array( $values ) ) { + $this->last_error = 'Unexpected response format from Google API.'; + return null; + } + + return array_map( 'floatval', $values ); + } + + /** + * Parses an OpenAI-compatible embedding response into a float vector. + * + * Handles WP_Error from wp_remote_post, non-200 HTTP status codes, and + * unexpected response shapes. On any failure, sets last_error and returns null. + * + * @since x.x.x + * + * @param \WP_Error|array $response Response from wp_remote_post(). + * @return float[]|null Float vector on success, null on failure. + */ + private function parse_openai_response( $response ): ?array { + if ( is_wp_error( $response ) ) { + $this->last_error = $response->get_error_message(); + return null; + } + + $code = wp_remote_retrieve_response_code( $response ); + $body = json_decode( wp_remote_retrieve_body( $response ), true ); + + if ( 200 !== $code ) { + $this->last_error = sprintf( 'HTTP %d: %s', $code, $body['error']['message'] ?? 'unknown error' ); + return null; + } + + $values = $body['data'][0]['embedding'] ?? null; + + if ( ! is_array( $values ) ) { + $this->last_error = 'Unexpected response format from provider.'; + return null; + } + + return array_map( 'floatval', $values ); + } + + /** + * Fetches the names of embedding-capable models available for the current Google API key. + * + * Calls the Google ListModels endpoint and filters to models that support the + * `embedContent` method. Used only by the test-connection REST endpoint to + * surface actionable context when the configured model name returns a 404. + * + * @since x.x.x + * + * @return string[] Model name strings (e.g. ['gemini-embedding-001']), empty on error. + */ + public function list_google_embedding_models(): array { + $endpoint = 'https://generativelanguage.googleapis.com/v1/models?key=' . $this->api_key; + $response = wp_remote_get( $endpoint, array( 'timeout' => 15 ) ); + + if ( is_wp_error( $response ) ) { + return array(); + } + + $body = json_decode( wp_remote_retrieve_body( $response ), true ); + $models = $body['models'] ?? array(); + $names = array(); + + foreach ( $models as $m ) { + $supported = $m['supportedGenerationMethods'] ?? array(); + if ( in_array( 'embedContent', $supported, true ) ) { + $names[] = str_replace( 'models/', '', $m['name'] ?? '' ); + } + } + + return array_filter( $names ); + } +} diff --git a/includes/Experiments/Semantic_Search/Embedding_Store.php b/includes/Experiments/Semantic_Search/Embedding_Store.php new file mode 100644 index 000000000..2a95fa280 --- /dev/null +++ b/includes/Experiments/Semantic_Search/Embedding_Store.php @@ -0,0 +1,166 @@ +get_col( + $wpdb->prepare( + // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared + "SELECT p.ID FROM {$wpdb->posts} p + LEFT JOIN {$wpdb->postmeta} pm + ON p.ID = pm.post_id AND pm.meta_key = %s + WHERE p.post_status = 'publish' + AND p.post_type IN ($types_placeholders) + AND pm.meta_value IS NULL + LIMIT %d", + array_merge( + array( self::META_EMBEDDING ), + $post_types, + array( $limit ) + ) + ) + ); + + return array_map( 'intval', $rows ?: array() ); + } + + /** + * Returns total and indexed post/page counts for the current site. + * + * @since x.x.x + * + * @return array{total:int, indexed:int} Counts of total published posts and indexed posts. + */ + public function get_stats(): array { + global $wpdb; + + // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching + $total = (int) $wpdb->get_var( + "SELECT COUNT(*) FROM {$wpdb->posts} + WHERE post_status = 'publish' + AND post_type IN ('post', 'page')" + ); + + // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching + $indexed = (int) $wpdb->get_var( + $wpdb->prepare( + "SELECT COUNT(DISTINCT post_id) FROM {$wpdb->postmeta} + WHERE meta_key = %s", + self::META_EMBEDDING + ) + ); + + return array( + 'total' => $total, + 'indexed' => $indexed, + ); + } + + /** + * Removes the stored embedding and model meta for a post. + * + * @since x.x.x + * + * @param int $post_id Post ID whose index entry should be removed. + * @return void + */ + public function delete( int $post_id ): void { + delete_post_meta( $post_id, self::META_EMBEDDING ); + delete_post_meta( $post_id, self::META_MODEL ); + } +} diff --git a/includes/Experiments/Semantic_Search/Index_Page.php b/includes/Experiments/Semantic_Search/Index_Page.php new file mode 100644 index 000000000..e10d54bef --- /dev/null +++ b/includes/Experiments/Semantic_Search/Index_Page.php @@ -0,0 +1,266 @@ + rest_url( 'ai/v1/semantic-search/index' ), + 'statusUrl' => rest_url( 'ai/v1/semantic-search/index/status' ), + 'testUrl' => rest_url( 'ai/v1/semantic-search/index/test' ), + 'nonce' => wp_create_nonce( 'wp_rest' ), + ) + ); + } + + /** + * Renders the indexing admin page. + * + * Shows a notice with a link to Settings → AI when no embedding provider is + * configured. When a provider is configured, shows the current indexed/total + * counts, a Test Connection button, and an Index All Posts button. All button + * interactions are handled by the inline script at the bottom of the page. + * + * @since x.x.x + * + * @return void + */ + public function render_page(): void { + if ( ! current_user_can( 'manage_options' ) ) { + wp_die( esc_html__( 'You do not have sufficient permissions to access this page.', 'ai' ) ); + } + + $api = new Embedding_Api(); + $store = new Embedding_Store(); + $stats = $store->get_stats(); + ?> +
+

+ + is_configured() ) : ?> +
+

+ Settings → AI and enable the Semantic Search experiment, then fill in your provider, model, and API key.', 'ai' ), + array( 'a' => array( 'href' => array() ) ) + ), + esc_url( admin_url( 'options-general.php?page=ai-wp-admin' ) ) + ); + ?> +

+
+ + +

+ +

+ +
+ + + +
+ +

+ + +
+ + + api = new Embedding_Api(); + $this->store = new Embedding_Store(); + } + + /** + * Generates and persists an embedding for a single post. + * + * Builds the post text from title + stripped content, requests an embedding + * from the configured provider, and writes the result to post meta via the + * embedding store. Returns false if the post does not exist or the API call fails. + * + * @since x.x.x + * + * @param int $post_id Post ID to index. + * @return bool True on success, false if the post is missing or the API fails. + */ + public function index_post( int $post_id ): bool { + $post = get_post( $post_id ); + + if ( ! $post ) { + return false; + } + + $text = $this->get_post_text( $post ); + $embedding = $this->api->generate( $text ); + + if ( null === $embedding ) { + return false; + } + + $this->store->save( $post_id, $embedding, $this->api->get_model() ); + + return true; + } + + /** + * Indexes a batch of posts, stopping on the first API error. + * + * Iterates over the supplied post IDs and calls index_post() for each. + * If any call fails, the loop breaks immediately and the error string from + * Embedding_Api::get_last_error() is included in the return value so the + * caller can surface it to the user instead of silently continuing. + * + * @since x.x.x + * + * @param int[] $ids Post IDs to index. + * @return array{success:int, failed:int, error:string} Counts and the first error message, if any. + */ + public function index_batch( array $ids ): array { + $success = 0; + $failed = 0; + $error = ''; + + foreach ( $ids as $id ) { + if ( $this->index_post( $id ) ) { + ++$success; + } else { + ++$failed; + $error = $this->api->get_last_error(); + break; + } + } + + return compact( 'success', 'failed', 'error' ); + } + + /** + * Builds the text string to embed for a post. + * + * Combines the post title and stripped post content, separated by two + * newlines, so that the embedding captures both the title semantics and + * the body content. + * + * @since x.x.x + * + * @param \WP_Post $post Post object to extract text from. + * @return string Concatenated title and stripped content. + */ + private function get_post_text( \WP_Post $post ): string { + return trim( $post->post_title . "\n\n" . wp_strip_all_tags( $post->post_content ) ); + } +} diff --git a/includes/Experiments/Semantic_Search/List_Table_Integration.php b/includes/Experiments/Semantic_Search/List_Table_Integration.php new file mode 100644 index 000000000..5fa75c11f --- /dev/null +++ b/includes/Experiments/Semantic_Search/List_Table_Integration.php @@ -0,0 +1,148 @@ + + + is_main_query() ) { + return; + } + + // phpcs:ignore WordPress.Security.NonceVerification.Recommended + if ( empty( $_GET[ self::PARAM ] ) ) { + return; + } + + $search_term = $query->get( 's' ); + + if ( ! $search_term ) { + return; + } + + $vector_search = new Vector_Search(); + + if ( ! $vector_search->is_available() ) { + return; + } + + $results = $vector_search->search( + $search_term, + array( + 'limit' => 50, + 'post_type' => (array) $query->get( 'post_type' ) ?: array( 'post', 'page' ), + ) + ); + + if ( empty( $results ) ) { + return; + } + + $ids = array_column( $results, 'id' ); + + $query->set( 's', '' ); + $query->set( 'post__in', $ids ); + $query->set( 'orderby', 'post__in' ); + } +} diff --git a/includes/Experiments/Semantic_Search/REST_Controller.php b/includes/Experiments/Semantic_Search/REST_Controller.php new file mode 100644 index 000000000..0ccf61191 --- /dev/null +++ b/includes/Experiments/Semantic_Search/REST_Controller.php @@ -0,0 +1,215 @@ + 'GET', + 'callback' => array( $this, 'handle_search' ), + 'permission_callback' => static fn() => current_user_can( 'edit_posts' ), + 'args' => array( + 'q' => array( + 'required' => true, + 'type' => 'string', + 'sanitize_callback' => 'sanitize_text_field', + ), + ), + ) + ); + + register_rest_route( + 'ai/v1', + '/semantic-search/index', + array( + 'methods' => 'POST', + 'callback' => array( $this, 'handle_index_batch' ), + 'permission_callback' => static fn() => current_user_can( 'manage_options' ), + ) + ); + + register_rest_route( + 'ai/v1', + '/semantic-search/index/status', + array( + 'methods' => 'GET', + 'callback' => array( $this, 'handle_index_status' ), + 'permission_callback' => static fn() => current_user_can( 'manage_options' ), + ) + ); + + register_rest_route( + 'ai/v1', + '/semantic-search/index/test', + array( + 'methods' => 'GET', + 'callback' => array( $this, 'handle_test_connection' ), + 'permission_callback' => static fn() => current_user_can( 'manage_options' ), + ) + ); + } + + /** + * Handles GET /ai/v1/semantic-search. + * + * Runs a semantic search for the `q` parameter and returns a ranked list of + * posts. Returns `available: false` when the embedding provider is not + * configured so the command palette JS can gracefully suppress the loader. + * + * @since x.x.x + * + * @param \WP_REST_Request $request The incoming REST request. + * @return \WP_REST_Response Response containing `available` flag and `results` array. + */ + public function handle_search( \WP_REST_Request $request ): \WP_REST_Response { + $query = $request->get_param( 'q' ); + $search = new Vector_Search(); + + if ( ! $search->is_available() ) { + return new \WP_REST_Response( array( 'available' => false, 'results' => array() ), 200 ); + } + + $results = $search->search( $query, array( 'limit' => 10 ) ); + + return new \WP_REST_Response( + array( + 'available' => true, + 'results' => $results, + ), + 200 + ); + } + + /** + * Handles POST /ai/v1/semantic-search/index. + * + * Retrieves the next batch of up to 5 unindexed posts and generates their + * embeddings. Returns progress counters (`indexed`, `total`) and a `done` + * flag so the JS loop on the Index_Page knows when to stop. If all attempts + * in the batch fail and an error string is present, `done` is forced to true + * to prevent the client from retrying with a broken API key or network. + * + * @since x.x.x + * + * @return \WP_REST_Response Response containing success/failed counts, progress stats, and done flag. + */ + public function handle_index_batch(): \WP_REST_Response { + $store = new Embedding_Store(); + $indexer = new Indexer(); + + $ids = $store->get_unindexed_ids( array( 'post', 'page' ), 5 ); + $result = $indexer->index_batch( $ids ); + $stats = $store->get_stats(); + + $payload = array_merge( + $result, + array( + 'indexed' => $stats['indexed'], + 'total' => $stats['total'], + 'done' => empty( $store->get_unindexed_ids( array( 'post', 'page' ), 1 ) ), + ) + ); + + if ( 0 === $result['success'] && '' !== $result['error'] ) { + $payload['done'] = true; + } + + return new \WP_REST_Response( $payload, 200 ); + } + + /** + * Handles GET /ai/v1/semantic-search/index/status. + * + * Returns the current indexed/total post counts without triggering any + * indexing work. + * + * @since x.x.x + * + * @return \WP_REST_Response Response containing `total` and `indexed` integer counts. + */ + public function handle_index_status(): \WP_REST_Response { + return new \WP_REST_Response( ( new Embedding_Store() )->get_stats(), 200 ); + } + + /** + * Handles GET /ai/v1/semantic-search/index/test. + * + * Generates an embedding for the string "test" using the current provider + * configuration and returns the model name and vector dimensions on success. + * On failure, returns the exact error string. For Google 404 errors caused by + * an incorrect model name, also returns the list of embedding-capable models + * available for the configured API key so the user knows what to type. + * + * @since x.x.x + * + * @return \WP_REST_Response Response containing `ok`, and either `model`/`dimensions` or `error`. + */ + public function handle_test_connection(): \WP_REST_Response { + $api = new Embedding_Api(); + $embedding = $api->generate( 'test' ); + + if ( null !== $embedding ) { + return new \WP_REST_Response( + array( + 'ok' => true, + 'model' => $api->get_model(), + 'dimensions' => count( $embedding ), + ), + 200 + ); + } + + $payload = array( + 'ok' => false, + 'error' => $api->get_last_error(), + ); + + if ( 'google' === $api->get_provider() ) { + $available = $api->list_google_embedding_models(); + if ( ! empty( $available ) ) { + $payload['available_models'] = $available; + } + } + + return new \WP_REST_Response( $payload, 200 ); + } +} diff --git a/includes/Experiments/Semantic_Search/Semantic_Search.php b/includes/Experiments/Semantic_Search/Semantic_Search.php new file mode 100644 index 000000000..f2963fd91 --- /dev/null +++ b/includes/Experiments/Semantic_Search/Semantic_Search.php @@ -0,0 +1,270 @@ + __( 'Semantic Search', 'ai' ), + 'description' => __( 'Adds AI-powered semantic search to the posts list and command palette. Uses embedding models to find conceptually related content even when keywords don\'t match.', 'ai' ), + 'category' => Experiment_Category::ADMIN, + 'capability' => 'embedding_generation', + ); + } + + /** + * Registers all WordPress hooks for the experiment. + * + * Called by the Features Loader once the experiment is confirmed enabled. + * Initialises the posts list integration and indexing admin page, and adds + * actions for the command palette JS, REST routes, and save_post reindexing. + * + * @since x.x.x + * + * @return void + */ + public function register(): void { + ( new List_Table_Integration() )->register(); + ( new Index_Page() )->init(); + + add_action( 'enqueue_block_editor_assets', array( $this, 'enqueue_command_palette' ) ); + add_action( 'rest_api_init', array( $this, 'register_rest_routes' ) ); + add_action( 'save_post', array( $this, 'on_save_post' ), 10, 2 ); + } + + /** + * Registers each settings field as a WordPress option with REST API exposure. + * + * Called by Settings_Registration::register_settings() for every registered + * feature. Each option is registered with show_in_rest: true so the React + * settings page can read and write values via the WordPress settings REST API + * (/wp/v2/settings). Without this flag, saves from the UI are silently dropped. + * + * @since x.x.x + * + * @return void + */ + public function register_settings(): void { + foreach ( $this->get_settings_fields() as $field ) { + $option_name = static::get_field_option_name( $field['id'] ); + register_setting( + Settings_Registration::OPTION_GROUP, + $option_name, + array( + 'type' => 'string', + 'sanitize_callback' => 'sanitize_text_field', + 'default' => $field['default'] ?? '', + 'show_in_rest' => true, + ) + ); + } + } + + /** + * Returns the field definitions rendered by the React settings DataForm. + * + * IDs use short names (e.g. 'provider'). Abstract_Feature::get_settings_fields_metadata() + * expands them to full option names (e.g. 'wpai_feature_semantic-search_field_provider') + * before passing them to the settings page script module. + * + * @since x.x.x + * + * @return array, + * }> Field definitions for the settings DataForm. + */ + public function get_settings_fields(): array { + return array( + array( + 'id' => 'provider', + 'label' => __( 'Provider', 'ai' ), + 'type' => 'select', + 'default' => 'openai', + 'elements' => array( + array( 'value' => 'openai', 'label' => 'OpenAI' ), + array( 'value' => 'jina', 'label' => 'Jina AI' ), + array( 'value' => 'ollama', 'label' => 'Ollama (local)' ), + array( 'value' => 'google', 'label' => 'Google Gemini' ), + ), + ), + array( + 'id' => 'base_url', + 'label' => __( 'Endpoint URL', 'ai' ), + 'type' => 'text', + 'default' => 'https://api.openai.com/v1/embeddings', + ), + array( + 'id' => 'model', + 'label' => __( 'Model', 'ai' ), + 'type' => 'text', + 'default' => 'text-embedding-3-small', + ), + array( + 'id' => 'score_threshold', + 'label' => __( 'Score Threshold', 'ai' ), + 'type' => 'text', + 'default' => '', + ), + array( + 'id' => 'api_key', + 'label' => __( 'API Key', 'ai' ), + 'type' => 'text', + 'default' => '', + ), + ); + } + + /** + * Enqueues the command palette JS in the block editor. + * + * Reads the asset manifest from build-scripts/experiments/semantic-search.asset.php + * for dependency and version data. Falls back to an empty dependency list if + * the manifest is missing. The script is only enqueued when the embedding + * provider is configured, to avoid registering a no-op command loader. + * + * @since x.x.x + * + * @return void + */ + public function enqueue_command_palette(): void { + $api = new Embedding_Api(); + + if ( ! $api->is_configured() ) { + return; + } + + $handle = 'wpai-semantic-search-command-palette'; + $asset_file = WPAI_PLUGIN_DIR . 'build-scripts/experiments/semantic-search.asset.php'; + $asset = file_exists( $asset_file ) ? require $asset_file : array( 'dependencies' => array(), 'version' => WPAI_VERSION ); // phpcs:ignore WordPressVIPMinimum.Files.IncludingFile.UsingVariable + + wp_enqueue_script( + $handle, + WPAI_PLUGIN_URL . 'build-scripts/experiments/semantic-search.js', + $asset['dependencies'], + $asset['version'], + array( 'in_footer' => true ) + ); + + wp_localize_script( + $handle, + 'wpaiSemanticSearch', + array( + 'restUrl' => rest_url( 'ai/v1/semantic-search' ), + 'nonce' => wp_create_nonce( 'wp_rest' ), + ) + ); + } + + /** + * Delegates REST route registration to REST_Controller. + * + * Hooked to rest_api_init so routes are only registered when the REST API + * is initialised, not on every admin page load. + * + * @since x.x.x + * + * @return void + */ + public function register_rest_routes(): void { + ( new REST_Controller() )->register_routes(); + } + + /** + * Re-indexes a post immediately when it is published or updated. + * + * Skips autosaves, revisions, and non-published posts. Runs synchronously + * which is acceptable for single-post saves; bulk indexing goes through + * POST /ai/v1/semantic-search/index in batches of 5. Does nothing when the + * embedding provider is not configured. + * + * @since x.x.x + * + * @param int $post_id Post ID being saved. + * @param \WP_Post $post Post object being saved. + * @return void + */ + public function on_save_post( int $post_id, \WP_Post $post ): void { + if ( wp_is_post_autosave( $post_id ) || wp_is_post_revision( $post_id ) ) { + return; + } + + if ( 'publish' !== $post->post_status ) { + return; + } + + $api = new Embedding_Api(); + + if ( ! $api->is_configured() ) { + return; + } + + ( new Indexer() )->index_post( $post_id ); + } +} diff --git a/includes/Experiments/Semantic_Search/Vector_Search.php b/includes/Experiments/Semantic_Search/Vector_Search.php new file mode 100644 index 000000000..339eb4959 --- /dev/null +++ b/includes/Experiments/Semantic_Search/Vector_Search.php @@ -0,0 +1,177 @@ +api = new Embedding_Api(); + $this->store = new Embedding_Store(); + } + + /** + * Returns whether the embedding provider is configured and ready to search. + * + * Delegates to Embedding_Api::is_configured(). When this returns false, + * callers should fall back to default WordPress search rather than calling + * search() and receiving an empty result. + * + * @since x.x.x + * + * @return bool True when the provider has the minimum required credentials. + */ + public function is_available(): bool { + return $this->api->is_configured(); + } + + /** + * Returns posts ranked by cosine similarity to the query string. + * + * Generates an embedding for $query, then scores every published post that + * has a stored embedding. Posts scoring below the provider threshold are + * excluded. The remaining results are sorted by score descending and the top + * $args['limit'] entries are returned. + * + * @since x.x.x + * + * @param string $query Search query string. + * @param array{limit?:int, post_type?:string[]} $args { + * @type int $limit Maximum results to return. Default 10. + * @type string[] $post_type Post types to search. Default ['post', 'page']. + * } + * @return array + * Ranked result entries, or an empty array if the query embedding failed. + */ + public function search( string $query, array $args = array() ): array { + $query_embedding = $this->api->generate( $query ); + + if ( null === $query_embedding ) { + return array(); + } + + $limit = $args['limit'] ?? 10; + $post_types = $args['post_type'] ?? array( 'post', 'page' ); + $score_threshold = $this->api->get_score_threshold(); + + $wq = new \WP_Query( + array( + 'post_type' => $post_types, + 'post_status' => 'publish', + 'posts_per_page' => -1, + 'no_found_rows' => true, + 'fields' => 'ids', + ) + ); + + $results = array(); + + foreach ( $wq->posts as $post_id ) { + $embedding = $this->store->get( (int) $post_id ); + + if ( null === $embedding ) { + continue; + } + + $score = $this->cosine_similarity( $query_embedding, $embedding ); + + if ( $score < $score_threshold ) { + continue; + } + + $post = get_post( $post_id ); + + $results[] = array( + 'id' => (int) $post_id, + 'title' => $post->post_title, + 'type' => $post->post_type, + 'url' => (string) ( get_edit_post_link( $post_id, '' ) ?: '#' ), + 'excerpt' => wp_trim_words( wp_strip_all_tags( $post->post_content ), 20 ), + 'score' => round( $score, 4 ), + ); + } + + usort( $results, static fn( $a, $b ) => $b['score'] <=> $a['score'] ); + + return array_slice( $results, 0, $limit ); + } + + /** + * Computes the cosine similarity between two float vectors. + * + * Returns a value in the range [-1, 1] where 1 means the vectors point in + * the same direction (identical semantics) and -1 means opposite directions. + * Returns 0.0 when either vector has zero magnitude to avoid division by zero. + * + * If the two vectors differ in length, only the shorter length is used so + * that mismatched dimensions (e.g. from a model change) don't cause errors. + * + * @since x.x.x + * + * @param float[] $a First embedding vector. + * @param float[] $b Second embedding vector. + * @return float Cosine similarity score in [-1, 1]. + */ + private function cosine_similarity( array $a, array $b ): float { + $dot = 0.0; + $norm_a = 0.0; + $norm_b = 0.0; + $len = min( count( $a ), count( $b ) ); + + for ( $i = 0; $i < $len; $i++ ) { + $dot += $a[ $i ] * $b[ $i ]; + $norm_a += $a[ $i ] ** 2; + $norm_b += $b[ $i ] ** 2; + } + + if ( 0.0 === $norm_a || 0.0 === $norm_b ) { + return 0.0; + } + + return $dot / ( sqrt( $norm_a ) * sqrt( $norm_b ) ); + } +} From 36da8b0d85362b1dd3adc17dedf399129ba4b340 Mon Sep 17 00:00:00 2001 From: priyanshuhaldar007 Date: Wed, 12 Aug 2026 15:44:59 +0530 Subject: [PATCH 2/4] refactor: generate embeddings via PHP AI Client instead of provider integrations --- .../Semantic_Search/Embedding_Api.php | 383 ------------------ .../Semantic_Search/Embedding_Generator.php | 147 +++++++ .../Semantic_Search/Embedding_Store.php | 37 +- .../Semantic_Search/Index_Page.php | 19 +- .../Experiments/Semantic_Search/Indexer.php | 24 +- .../List_Table_Integration.php | 16 +- .../Semantic_Search/REST_Controller.php | 53 ++- .../Semantic_Search/Semantic_Search.php | 76 +--- .../Semantic_Search/Vector_Search.php | 58 ++- includes/REST/Models_Controller.php | 8 +- src/experiments/semantic-search/index.ts | 132 ++++++ .../Semantic_Search/Semantic_SearchTest.php | 279 +++++++++++++ .../Includes/REST/Models_ControllerTest.php | 2 +- webpack.config.js | 5 + 14 files changed, 709 insertions(+), 530 deletions(-) delete mode 100644 includes/Experiments/Semantic_Search/Embedding_Api.php create mode 100644 includes/Experiments/Semantic_Search/Embedding_Generator.php create mode 100644 src/experiments/semantic-search/index.ts create mode 100644 tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php diff --git a/includes/Experiments/Semantic_Search/Embedding_Api.php b/includes/Experiments/Semantic_Search/Embedding_Api.php deleted file mode 100644 index e547d61cd..000000000 --- a/includes/Experiments/Semantic_Search/Embedding_Api.php +++ /dev/null @@ -1,383 +0,0 @@ -generateEmbeddingResult() - * and let the registered connector handle authentication + transport. - * - * @package WordPress\AI\Experiments\Semantic_Search - */ - -declare( strict_types=1 ); - -namespace WordPress\AI\Experiments\Semantic_Search; - -// Exit if accessed directly. -defined( 'ABSPATH' ) || exit; - -/** - * Sends text to an embedding API and returns a float vector. - * - * Supports four providers out of the box: OpenAI, Jina AI, Ollama (local), - * and Google Gemini. Provider selection and credentials are read from the - * namespaced WordPress options registered by the Semantic_Search experiment. - * - * @internal - * @since x.x.x - */ -class Embedding_Api { - - /** - * Per-provider configuration defaults. - * - * Each entry contains: - * - label: Human-readable provider name. - * - default_url: API base URL used when no override is saved. - * - default_model: Model identifier used when no override is saved. - * - dimensions: Output vector length. Source: official model documentation. - * - score_threshold: Cosine similarity cut-off. These are heuristics — no - * authoritative published benchmarks exist. Tune via Settings. - * - * @since x.x.x - * @var array - */ - public const PROVIDERS = array( - 'openai' => array( - 'label' => 'OpenAI', - 'default_url' => 'https://api.openai.com/v1/embeddings', - 'default_model' => 'text-embedding-3-small', - 'dimensions' => 1536, - 'score_threshold' => 0.60, - ), - 'jina' => array( - 'label' => 'Jina AI', - 'default_url' => 'https://api.jina.ai/v1/embeddings', - 'default_model' => 'jina-embeddings-v3', - 'dimensions' => 1024, - 'score_threshold' => 0.55, - ), - 'ollama' => array( - 'label' => 'Ollama (local)', - 'default_url' => 'http://localhost:11434/v1/embeddings', - 'default_model' => 'nomic-embed-text', - 'dimensions' => 768, - 'score_threshold' => 0.50, - ), - 'google' => array( - 'label' => 'Google Gemini', - 'default_url' => 'https://generativelanguage.googleapis.com/v1/models', - 'default_model' => 'gemini-embedding-001', - 'dimensions' => 3072, - 'score_threshold' => 0.45, - ), - ); - - /** - * Active provider key (e.g. 'openai', 'google'). - * - * @since x.x.x - * @var string - */ - private string $provider; - - /** - * API key for the active provider. Empty for Ollama. - * - * @since x.x.x - * @var string - */ - private string $api_key; - - /** - * Embedding model identifier (e.g. 'text-embedding-3-small'). - * - * @since x.x.x - * @var string - */ - private string $model; - - /** - * API base URL for the active provider. - * - * @since x.x.x - * @var string - */ - private string $base_url; - - /** - * Human-readable description of the last API error, or empty string if none. - * - * @since x.x.x - * @var string - */ - private string $last_error = ''; - - /** - * Reads all provider configuration from the saved experiment options. - * - * @since x.x.x - */ - public function __construct() { - $this->provider = (string) get_option( Semantic_Search::get_field_option_name( 'provider' ), 'openai' ); - $this->api_key = (string) get_option( Semantic_Search::get_field_option_name( 'api_key' ), '' ); - $this->model = (string) get_option( Semantic_Search::get_field_option_name( 'model' ), 'text-embedding-3-small' ); - $this->base_url = (string) get_option( Semantic_Search::get_field_option_name( 'base_url' ), 'https://api.openai.com/v1/embeddings' ); - } - - /** - * Returns the active model identifier. - * - * @since x.x.x - * - * @return string Model identifier string (e.g. 'gemini-embedding-001'). - */ - public function get_model(): string { - return $this->model; - } - - /** - * Returns the active provider key. - * - * @since x.x.x - * - * @return string Provider key (e.g. 'openai', 'google'). - */ - public function get_provider(): string { - return $this->provider; - } - - /** - * Returns the human-readable error message from the most recent API call. - * - * Returns an empty string when the last call succeeded. - * - * @since x.x.x - * - * @return string Error description, or empty string on success. - */ - public function get_last_error(): string { - return $this->last_error; - } - - /** - * Returns whether the provider is ready to accept embedding requests. - * - * Ollama requires only a non-empty model name (no key). All other providers - * require a non-empty API key. - * - * @since x.x.x - * - * @return bool True when the minimum required credentials are present. - */ - public function is_configured(): bool { - if ( 'ollama' === $this->provider ) { - return '' !== $this->model; - } - - return '' !== $this->api_key; - } - - /** - * Returns the cosine similarity score threshold for the active provider. - * - * Reads the user-saved option first; falls back to the per-provider default - * from PROVIDERS when the option is empty. An empty string means "use the - * provider default" and is backward-compatible with existing installs that - * predate the user-editable threshold field. - * - * @since x.x.x - * - * @return float Cosine similarity cut-off in the range [0, 1]. - */ - public function get_score_threshold(): float { - $cfg = self::PROVIDERS[ $this->provider ] ?? self::PROVIDERS['openai']; - $saved = (string) get_option( Semantic_Search::get_field_option_name( 'score_threshold' ), '' ); - - return '' !== $saved ? (float) $saved : $cfg['score_threshold']; - } - - /** - * Sends text to the configured embedding provider and returns a float vector. - * - * Dispatches to the Google-specific or OpenAI-compatible implementation - * depending on the active provider. Returns null on any API error; call - * get_last_error() to retrieve the reason. - * - * @since x.x.x - * - * @param string $text The text to embed. - * @return float[]|null Float vector on success, null on failure. - */ - public function generate( string $text ): ?array { - $this->last_error = ''; - - if ( 'google' === $this->provider ) { - return $this->generate_google( $text ); - } - - return $this->generate_openai_compatible( $text ); - } - - /** - * Generates an embedding using the OpenAI-compatible request format. - * - * Used for OpenAI, Jina AI, and Ollama. The Authorization header is omitted - * for Ollama since it requires no API key. - * - * @since x.x.x - * - * @param string $text The text to embed. - * @return float[]|null Float vector on success, null on failure. - */ - private function generate_openai_compatible( string $text ): ?array { - $headers = array( 'Content-Type' => 'application/json' ); - - if ( 'ollama' !== $this->provider ) { - $headers['Authorization'] = 'Bearer ' . $this->api_key; - } - - $response = wp_remote_post( - $this->base_url, - array( - 'timeout' => 30, - 'headers' => $headers, - 'body' => wp_json_encode( - array( - 'input' => $text, - 'model' => $this->model, - ) - ), - ) - ); - - return $this->parse_openai_response( $response ); - } - - /** - * Generates an embedding using the Google Gemini embedContent API. - * - * Google's API differs from the OpenAI-compatible format in three ways: - * - The model name is appended to the URL path, not sent in the body. - * - The API key is passed as a query parameter, not an Authorization header. - * - The request body uses `content.parts[].text` instead of `input`. - * - * @since x.x.x - * - * @param string $text The text to embed. - * @return float[]|null Float vector on success, null on failure. - */ - private function generate_google( string $text ): ?array { - $endpoint = rtrim( $this->base_url, '/' ) . '/' . $this->model . ':embedContent?key=' . $this->api_key; - - $response = wp_remote_post( - $endpoint, - array( - 'timeout' => 30, - 'headers' => array( 'Content-Type' => 'application/json' ), - 'body' => wp_json_encode( - array( - 'content' => array( - 'parts' => array( - array( 'text' => $text ), - ), - ), - ) - ), - ) - ); - - if ( is_wp_error( $response ) ) { - $this->last_error = $response->get_error_message(); - return null; - } - - $code = wp_remote_retrieve_response_code( $response ); - $body = json_decode( wp_remote_retrieve_body( $response ), true ); - - if ( 200 !== $code ) { - $this->last_error = sprintf( 'HTTP %d: %s', $code, $body['error']['message'] ?? 'unknown error' ); - return null; - } - - $values = $body['embedding']['values'] ?? null; - - if ( ! is_array( $values ) ) { - $this->last_error = 'Unexpected response format from Google API.'; - return null; - } - - return array_map( 'floatval', $values ); - } - - /** - * Parses an OpenAI-compatible embedding response into a float vector. - * - * Handles WP_Error from wp_remote_post, non-200 HTTP status codes, and - * unexpected response shapes. On any failure, sets last_error and returns null. - * - * @since x.x.x - * - * @param \WP_Error|array $response Response from wp_remote_post(). - * @return float[]|null Float vector on success, null on failure. - */ - private function parse_openai_response( $response ): ?array { - if ( is_wp_error( $response ) ) { - $this->last_error = $response->get_error_message(); - return null; - } - - $code = wp_remote_retrieve_response_code( $response ); - $body = json_decode( wp_remote_retrieve_body( $response ), true ); - - if ( 200 !== $code ) { - $this->last_error = sprintf( 'HTTP %d: %s', $code, $body['error']['message'] ?? 'unknown error' ); - return null; - } - - $values = $body['data'][0]['embedding'] ?? null; - - if ( ! is_array( $values ) ) { - $this->last_error = 'Unexpected response format from provider.'; - return null; - } - - return array_map( 'floatval', $values ); - } - - /** - * Fetches the names of embedding-capable models available for the current Google API key. - * - * Calls the Google ListModels endpoint and filters to models that support the - * `embedContent` method. Used only by the test-connection REST endpoint to - * surface actionable context when the configured model name returns a 404. - * - * @since x.x.x - * - * @return string[] Model name strings (e.g. ['gemini-embedding-001']), empty on error. - */ - public function list_google_embedding_models(): array { - $endpoint = 'https://generativelanguage.googleapis.com/v1/models?key=' . $this->api_key; - $response = wp_remote_get( $endpoint, array( 'timeout' => 15 ) ); - - if ( is_wp_error( $response ) ) { - return array(); - } - - $body = json_decode( wp_remote_retrieve_body( $response ), true ); - $models = $body['models'] ?? array(); - $names = array(); - - foreach ( $models as $m ) { - $supported = $m['supportedGenerationMethods'] ?? array(); - if ( in_array( 'embedContent', $supported, true ) ) { - $names[] = str_replace( 'models/', '', $m['name'] ?? '' ); - } - } - - return array_filter( $names ); - } -} diff --git a/includes/Experiments/Semantic_Search/Embedding_Generator.php b/includes/Experiments/Semantic_Search/Embedding_Generator.php new file mode 100644 index 000000000..eb08beaaf --- /dev/null +++ b/includes/Experiments/Semantic_Search/Embedding_Generator.php @@ -0,0 +1,147 @@ +last_error; + } + + /** + * Returns whether embeddings can currently be generated. + * + * Requires both an environment that exposes the embedding API and at least + * one connector with credentials. When this returns false, callers should + * fall back to default WordPress search rather than attempting a request. + * + * @since x.x.x + * + * @return bool True when embedding generation is possible. + */ + public function is_available(): bool { + return supports_embedding_generation() && has_ai_credentials(); + } + + /** + * Returns the cosine similarity threshold below which results are discarded. + * + * Reads the user-saved option and falls back to DEFAULT_SCORE_THRESHOLD when + * it is empty or out of the [0, 1] range. + * + * @since x.x.x + * + * @return float Cosine similarity cut-off in the range [0, 1]. + */ + public function get_score_threshold(): float { + $saved = (string) get_option( Semantic_Search::get_field_option_name( 'score_threshold' ), '' ); + + if ( '' === trim( $saved ) || ! is_numeric( $saved ) ) { + return self::DEFAULT_SCORE_THRESHOLD; + } + + $threshold = (float) $saved; + + if ( $threshold < 0.0 || $threshold > 1.0 ) { + return self::DEFAULT_SCORE_THRESHOLD; + } + + return $threshold; + } + + /** + * Generates an embedding vector for a single string of text. + * + * Returns null on any failure; call get_last_error() for the reason. + * + * @since x.x.x + * + * @param string $text The text to embed. + * @return float[]|null Float vector on success, null on failure. + */ + public function generate( string $text ): ?array { + $this->last_error = ''; + + $model = $this->get_model(); + $args = '' !== $model ? array( 'model_preference' => array( $model ) ) : array(); + + $result = generate_embeddings( $text, $args ); + + if ( is_wp_error( $result ) ) { + $this->last_error = $result->get_error_message(); + return null; + } + + $values = $result->getEmbedding()->getValues(); + + if ( empty( $values ) ) { + $this->last_error = __( 'The embedding provider returned an empty vector.', 'ai' ); + return null; + } + + return array_map( 'floatval', $values ); + } +} diff --git a/includes/Experiments/Semantic_Search/Embedding_Store.php b/includes/Experiments/Semantic_Search/Embedding_Store.php index 2a95fa280..bbdc4e704 100644 --- a/includes/Experiments/Semantic_Search/Embedding_Store.php +++ b/includes/Experiments/Semantic_Search/Embedding_Store.php @@ -95,28 +95,29 @@ public function get( int $post_id ): ?array { public function get_unindexed_ids( array $post_types, int $limit = 5 ): array { global $wpdb; + if ( empty( $post_types ) ) { + return array(); + } + $types_placeholders = implode( ', ', array_fill( 0, count( $post_types ), '%s' ) ); - // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching - $rows = $wpdb->get_col( - $wpdb->prepare( - // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared - "SELECT p.ID FROM {$wpdb->posts} p - LEFT JOIN {$wpdb->postmeta} pm - ON p.ID = pm.post_id AND pm.meta_key = %s - WHERE p.post_status = 'publish' - AND p.post_type IN ($types_placeholders) - AND pm.meta_value IS NULL - LIMIT %d", - array_merge( - array( self::META_EMBEDDING ), - $post_types, - array( $limit ) - ) - ) + $sql = "SELECT p.ID FROM {$wpdb->posts} p + LEFT JOIN {$wpdb->postmeta} pm + ON p.ID = pm.post_id AND pm.meta_key = %s + WHERE p.post_status = 'publish' + AND p.post_type IN ( {$types_placeholders} ) + AND pm.meta_value IS NULL + LIMIT %d"; + + $values = array_merge( + array( self::META_EMBEDDING ), + array_values( $post_types ), + array( $limit ) ); - return array_map( 'intval', $rows ?: array() ); + $rows = $wpdb->get_col( $wpdb->prepare( $sql, $values ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared -- $sql is built from a fixed template with generated placeholders; all values are passed through prepare(). + + return array_map( 'intval', is_array( $rows ) ? $rows : array() ); } /** diff --git a/includes/Experiments/Semantic_Search/Index_Page.php b/includes/Experiments/Semantic_Search/Index_Page.php index e10d54bef..9c1d43af3 100644 --- a/includes/Experiments/Semantic_Search/Index_Page.php +++ b/includes/Experiments/Semantic_Search/Index_Page.php @@ -43,7 +43,7 @@ class Index_Page { * @return void */ public function init(): void { - add_action( 'admin_menu', array( $this, 'add_menu' ) ); + add_action( 'admin_menu', array( $this, 'add_menu' ) ); add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_assets' ) ); } @@ -111,23 +111,22 @@ public function render_page(): void { wp_die( esc_html__( 'You do not have sufficient permissions to access this page.', 'ai' ) ); } - $api = new Embedding_Api(); - $store = new Embedding_Store(); - $stats = $store->get_stats(); + $generator = new Embedding_Generator(); + $store = new Embedding_Store(); + $stats = $store->get_stats(); ?>

- is_configured() ) : ?> + is_available() ) : ?>

Settings → AI and connect a provider that supports embedding generation.', 'ai' ); + printf( - /* translators: %s: URL to the AI settings page */ - wp_kses( - __( 'No embedding provider configured. Go to Settings → AI and enable the Semantic Search experiment, then fill in your provider, model, and API key.', 'ai' ), - array( 'a' => array( 'href' => array() ) ) - ), + wp_kses( $notice, array( 'a' => array( 'href' => array() ) ) ), esc_url( admin_url( 'options-general.php?page=ai-wp-admin' ) ) ); ?> diff --git a/includes/Experiments/Semantic_Search/Indexer.php b/includes/Experiments/Semantic_Search/Indexer.php index c11337567..78307c724 100644 --- a/includes/Experiments/Semantic_Search/Indexer.php +++ b/includes/Experiments/Semantic_Search/Indexer.php @@ -15,10 +15,10 @@ /** * Generates and stores embeddings for individual posts and batches. * - * Coordinates between Embedding_Api (which calls the external API) and + * Coordinates between Embedding_Generator (which calls the PHP AI Client) and * Embedding_Store (which persists the resulting vectors). On the first API * error within a batch, indexing stops immediately rather than continuing - * through a broken key or network connection. + * through a broken connector or network connection. * * @internal * @since x.x.x @@ -26,18 +26,18 @@ class Indexer { /** - * Embedding API instance used to generate vectors. + * Embedding generator instance used to generate vectors. * * @since x.x.x - * @var Embedding_Api + * @var \WordPress\AI\Experiments\Semantic_Search\Embedding_Generator */ - private Embedding_Api $api; + private Embedding_Generator $api; /** * Embedding store instance used to persist vectors. * * @since x.x.x - * @var Embedding_Store + * @var \WordPress\AI\Experiments\Semantic_Search\Embedding_Store */ private Embedding_Store $store; @@ -47,7 +47,7 @@ class Indexer { * @since x.x.x */ public function __construct() { - $this->api = new Embedding_Api(); + $this->api = new Embedding_Generator(); $this->store = new Embedding_Store(); } @@ -87,8 +87,8 @@ public function index_post( int $post_id ): bool { * * Iterates over the supplied post IDs and calls index_post() for each. * If any call fails, the loop breaks immediately and the error string from - * Embedding_Api::get_last_error() is included in the return value so the - * caller can surface it to the user instead of silently continuing. + * Embedding_Generator::get_last_error() is included in the return value so + * the caller can surface it to the user instead of silently continuing. * * @since x.x.x * @@ -101,13 +101,13 @@ public function index_batch( array $ids ): array { $error = ''; foreach ( $ids as $id ) { - if ( $this->index_post( $id ) ) { - ++$success; - } else { + if ( ! $this->index_post( $id ) ) { ++$failed; $error = $this->api->get_last_error(); break; } + + ++$success; } return compact( 'success', 'failed', 'error' ); diff --git a/includes/Experiments/Semantic_Search/List_Table_Integration.php b/includes/Experiments/Semantic_Search/List_Table_Integration.php index 5fa75c11f..9489bdf65 100644 --- a/includes/Experiments/Semantic_Search/List_Table_Integration.php +++ b/includes/Experiments/Semantic_Search/List_Table_Integration.php @@ -49,7 +49,7 @@ class List_Table_Integration { */ public function register(): void { add_action( 'restrict_manage_posts', array( $this, 'render_checkbox' ) ); - add_action( 'pre_get_posts', array( $this, 'maybe_apply_semantic_search' ) ); + add_action( 'pre_get_posts', array( $this, 'maybe_apply_semantic_search' ) ); } /** @@ -127,11 +127,19 @@ public function maybe_apply_semantic_search( \WP_Query $query ): void { return; } + $post_types = array_values( + array_filter( array_map( 'strval', (array) $query->get( 'post_type' ) ) ) + ); + + if ( empty( $post_types ) ) { + $post_types = array( 'post', 'page' ); + } + $results = $vector_search->search( $search_term, array( 'limit' => 50, - 'post_type' => (array) $query->get( 'post_type' ) ?: array( 'post', 'page' ), + 'post_type' => $post_types, ) ); @@ -141,8 +149,8 @@ public function maybe_apply_semantic_search( \WP_Query $query ): void { $ids = array_column( $results, 'id' ); - $query->set( 's', '' ); + $query->set( 's', '' ); $query->set( 'post__in', $ids ); - $query->set( 'orderby', 'post__in' ); + $query->set( 'orderby', 'post__in' ); } } diff --git a/includes/Experiments/Semantic_Search/REST_Controller.php b/includes/Experiments/Semantic_Search/REST_Controller.php index 0ccf61191..fed87e367 100644 --- a/includes/Experiments/Semantic_Search/REST_Controller.php +++ b/includes/Experiments/Semantic_Search/REST_Controller.php @@ -105,7 +105,13 @@ public function handle_search( \WP_REST_Request $request ): \WP_REST_Response { $search = new Vector_Search(); if ( ! $search->is_available() ) { - return new \WP_REST_Response( array( 'available' => false, 'results' => array() ), 200 ); + return new \WP_REST_Response( + array( + 'available' => false, + 'results' => array(), + ), + 200 + ); } $results = $search->search( $query, array( 'limit' => 10 ) ); @@ -173,43 +179,46 @@ public function handle_index_status(): \WP_REST_Response { /** * Handles GET /ai/v1/semantic-search/index/test. * - * Generates an embedding for the string "test" using the current provider - * configuration and returns the model name and vector dimensions on success. - * On failure, returns the exact error string. For Google 404 errors caused by - * an incorrect model name, also returns the list of embedding-capable models - * available for the configured API key so the user knows what to type. + * Generates an embedding for the string "test" through the configured + * connector and returns the model preference and vector dimensions on + * success. On failure, returns the error reported by the AI Client. * * @since x.x.x * * @return \WP_REST_Response Response containing `ok`, and either `model`/`dimensions` or `error`. */ public function handle_test_connection(): \WP_REST_Response { - $api = new Embedding_Api(); - $embedding = $api->generate( 'test' ); + $generator = new Embedding_Generator(); - if ( null !== $embedding ) { + if ( ! $generator->is_available() ) { return new \WP_REST_Response( array( - 'ok' => true, - 'model' => $api->get_model(), - 'dimensions' => count( $embedding ), + 'ok' => false, + 'error' => __( 'No connector with embedding support is configured.', 'ai' ), ), 200 ); } - $payload = array( - 'ok' => false, - 'error' => $api->get_last_error(), - ); + $embedding = $generator->generate( 'test' ); - if ( 'google' === $api->get_provider() ) { - $available = $api->list_google_embedding_models(); - if ( ! empty( $available ) ) { - $payload['available_models'] = $available; - } + if ( null === $embedding ) { + return new \WP_REST_Response( + array( + 'ok' => false, + 'error' => $generator->get_last_error(), + ), + 200 + ); } - return new \WP_REST_Response( $payload, 200 ); + return new \WP_REST_Response( + array( + 'ok' => true, + 'model' => $generator->get_model(), + 'dimensions' => count( $embedding ), + ), + 200 + ); } } diff --git a/includes/Experiments/Semantic_Search/Semantic_Search.php b/includes/Experiments/Semantic_Search/Semantic_Search.php index f2963fd91..b9d018ace 100644 --- a/includes/Experiments/Semantic_Search/Semantic_Search.php +++ b/includes/Experiments/Semantic_Search/Semantic_Search.php @@ -10,13 +10,10 @@ * 2. Command palette (Cmd/Ctrl+K in the block editor) — a live REST call * fetches semantically ranked posts and injects them as clickable commands. * - * Blocked upstream on: - * - WordPress/php-ai-client#244 (embedding generation API) - * - WordPress/ai#683 (native vector index / MariaDB VECTOR INDEX) - * - * All embedding HTTP calls are in Embedding_Api (swap for php-ai-client once - * #244 merges). Storage is in Embedding_Store (swap for VECTOR column once - * #683 merges). Everything in this class and the UI layer is permanent. + * Embedding generation goes through the PHP AI Client via Embedding_Generator, + * so provider selection and credentials are owned by the connector settings. + * Storage is in Embedding_Store (swap for the VECTOR column once + * WordPress/ai#683 merges). Everything in this class and the UI layer is permanent. * * @package WordPress\AI\Experiments\Semantic_Search */ @@ -26,6 +23,7 @@ namespace WordPress\AI\Experiments\Semantic_Search; use WordPress\AI\Abstracts\Abstract_Feature; +use WordPress\AI\Asset_Loader; use WordPress\AI\Experiments\Experiment_Category; use WordPress\AI\Settings\Settings_Registration; @@ -91,8 +89,8 @@ public function register(): void { ( new Index_Page() )->init(); add_action( 'enqueue_block_editor_assets', array( $this, 'enqueue_command_palette' ) ); - add_action( 'rest_api_init', array( $this, 'register_rest_routes' ) ); - add_action( 'save_post', array( $this, 'on_save_post' ), 10, 2 ); + add_action( 'rest_api_init', array( $this, 'register_rest_routes' ) ); + add_action( 'save_post', array( $this, 'on_save_post' ), 10, 2 ); } /** @@ -142,29 +140,11 @@ public function register_settings(): void { */ public function get_settings_fields(): array { return array( - array( - 'id' => 'provider', - 'label' => __( 'Provider', 'ai' ), - 'type' => 'select', - 'default' => 'openai', - 'elements' => array( - array( 'value' => 'openai', 'label' => 'OpenAI' ), - array( 'value' => 'jina', 'label' => 'Jina AI' ), - array( 'value' => 'ollama', 'label' => 'Ollama (local)' ), - array( 'value' => 'google', 'label' => 'Google Gemini' ), - ), - ), - array( - 'id' => 'base_url', - 'label' => __( 'Endpoint URL', 'ai' ), - 'type' => 'text', - 'default' => 'https://api.openai.com/v1/embeddings', - ), array( 'id' => 'model', 'label' => __( 'Model', 'ai' ), 'type' => 'text', - 'default' => 'text-embedding-3-small', + 'default' => '', ), array( 'id' => 'score_threshold', @@ -172,47 +152,31 @@ public function get_settings_fields(): array { 'type' => 'text', 'default' => '', ), - array( - 'id' => 'api_key', - 'label' => __( 'API Key', 'ai' ), - 'type' => 'text', - 'default' => '', - ), ); } /** * Enqueues the command palette JS in the block editor. * - * Reads the asset manifest from build-scripts/experiments/semantic-search.asset.php - * for dependency and version data. Falls back to an empty dependency list if - * the manifest is missing. The script is only enqueued when the embedding - * provider is configured, to avoid registering a no-op command loader. + * Delegates to Asset_Loader, which resolves the generated asset manifest and + * reports a clear error if the build output is missing. The script is only + * enqueued when embedding generation is available, to avoid registering a + * no-op command loader. * * @since x.x.x * * @return void */ public function enqueue_command_palette(): void { - $api = new Embedding_Api(); - - if ( ! $api->is_configured() ) { + if ( ! ( new Embedding_Generator() )->is_available() ) { return; } - $handle = 'wpai-semantic-search-command-palette'; - $asset_file = WPAI_PLUGIN_DIR . 'build-scripts/experiments/semantic-search.asset.php'; - $asset = file_exists( $asset_file ) ? require $asset_file : array( 'dependencies' => array(), 'version' => WPAI_VERSION ); // phpcs:ignore WordPressVIPMinimum.Files.IncludingFile.UsingVariable + $handle = 'semantic_search'; - wp_enqueue_script( - $handle, - WPAI_PLUGIN_URL . 'build-scripts/experiments/semantic-search.js', - $asset['dependencies'], - $asset['version'], - array( 'in_footer' => true ) - ); + Asset_Loader::enqueue_script( $handle, 'experiments/semantic-search' ); - wp_localize_script( + Asset_Loader::localize_script( $handle, 'wpaiSemanticSearch', array( @@ -241,8 +205,8 @@ public function register_rest_routes(): void { * * Skips autosaves, revisions, and non-published posts. Runs synchronously * which is acceptable for single-post saves; bulk indexing goes through - * POST /ai/v1/semantic-search/index in batches of 5. Does nothing when the - * embedding provider is not configured. + * POST /ai/v1/semantic-search/index in batches of 5. Does nothing when + * embedding generation is unavailable. * * @since x.x.x * @@ -259,9 +223,7 @@ public function on_save_post( int $post_id, \WP_Post $post ): void { return; } - $api = new Embedding_Api(); - - if ( ! $api->is_configured() ) { + if ( ! ( new Embedding_Generator() )->is_available() ) { return; } diff --git a/includes/Experiments/Semantic_Search/Vector_Search.php b/includes/Experiments/Semantic_Search/Vector_Search.php index 339eb4959..807a838ae 100644 --- a/includes/Experiments/Semantic_Search/Vector_Search.php +++ b/includes/Experiments/Semantic_Search/Vector_Search.php @@ -18,9 +18,9 @@ /** * Runs a semantic search against stored post embeddings. * - * Generates a query embedding via Embedding_Api, then iterates over all + * Generates a query embedding via Embedding_Generator, then iterates over all * published posts that have a stored embedding, computing cosine similarity - * against each. Results below the provider's score threshold are excluded. + * against each. Results below the configured score threshold are excluded. * Surviving results are sorted by score descending and sliced to the limit. * * @internal @@ -29,18 +29,18 @@ class Vector_Search { /** - * Embedding API instance used to generate the query vector. + * Embedding generator instance used to generate the query vector. * * @since x.x.x - * @var Embedding_Api + * @var \WordPress\AI\Experiments\Semantic_Search\Embedding_Generator */ - private Embedding_Api $api; + private Embedding_Generator $api; /** * Embedding store instance used to retrieve stored post vectors. * * @since x.x.x - * @var Embedding_Store + * @var \WordPress\AI\Experiments\Semantic_Search\Embedding_Store */ private Embedding_Store $store; @@ -50,23 +50,23 @@ class Vector_Search { * @since x.x.x */ public function __construct() { - $this->api = new Embedding_Api(); + $this->api = new Embedding_Generator(); $this->store = new Embedding_Store(); } /** - * Returns whether the embedding provider is configured and ready to search. + * Returns whether embedding generation is available and ready to search. * - * Delegates to Embedding_Api::is_configured(). When this returns false, + * Delegates to Embedding_Generator::is_available(). When this returns false, * callers should fall back to default WordPress search rather than calling * search() and receiving an empty result. * * @since x.x.x * - * @return bool True when the provider has the minimum required credentials. + * @return bool True when embeddings can be generated. */ public function is_available(): bool { - return $this->api->is_configured(); + return $this->api->is_available(); } /** @@ -79,12 +79,12 @@ public function is_available(): bool { * * @since x.x.x * - * @param string $query Search query string. - * @param array{limit?:int, post_type?:string[]} $args { - * @type int $limit Maximum results to return. Default 10. - * @type string[] $post_type Post types to search. Default ['post', 'page']. - * } - * @return array + * @param string $query Search query string. + * @param array{limit?: int, post_type?: list} $args Optional. Accepts `limit` (maximum + * results, default 10) and `post_type` + * (post types to search, default + * `['post', 'page']`). + * @return list * Ranked result entries, or an empty array if the query embedding failed. */ public function search( string $query, array $args = array() ): array { @@ -110,8 +110,11 @@ public function search( string $query, array $args = array() ): array { $results = array(); - foreach ( $wq->posts as $post_id ) { - $embedding = $this->store->get( (int) $post_id ); + foreach ( $wq->posts as $found_post ) { + // WP_Query is queried with 'fields' => 'ids', but the return type also allows objects. + $post_id = $found_post instanceof \WP_Post ? $found_post->ID : (int) $found_post; + + $embedding = $this->store->get( $post_id ); if ( null === $embedding ) { continue; @@ -125,17 +128,28 @@ public function search( string $query, array $args = array() ): array { $post = get_post( $post_id ); + if ( ! $post instanceof \WP_Post ) { + continue; + } + + $edit_link = (string) get_edit_post_link( $post_id, '' ); + $results[] = array( - 'id' => (int) $post_id, + 'id' => $post_id, 'title' => $post->post_title, 'type' => $post->post_type, - 'url' => (string) ( get_edit_post_link( $post_id, '' ) ?: '#' ), + 'url' => '' !== $edit_link ? $edit_link : '#', 'excerpt' => wp_trim_words( wp_strip_all_tags( $post->post_content ), 20 ), 'score' => round( $score, 4 ), ); } - usort( $results, static fn( $a, $b ) => $b['score'] <=> $a['score'] ); + usort( + $results, + static function ( array $a, array $b ): int { + return $b['score'] <=> $a['score']; + } + ); return array_slice( $results, 0, $limit ); } diff --git a/includes/REST/Models_Controller.php b/includes/REST/Models_Controller.php index fe2ee8988..59b7647d5 100644 --- a/includes/REST/Models_Controller.php +++ b/includes/REST/Models_Controller.php @@ -55,7 +55,7 @@ final class Models_Controller { * * @var list */ - private const VALID_CAPABILITIES = array( 'text_generation', 'image_generation', 'vision' ); // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is a single array constant. + private const VALID_CAPABILITIES = array( 'text_generation', 'image_generation', 'vision', 'embedding_generation' ); // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is a single array constant. /** * Initializes the REST routes. @@ -167,6 +167,12 @@ private function build_requirements( string $capability ): ModelRequirements { array() ); + case 'embedding_generation': + return new ModelRequirements( + array( CapabilityEnum::embeddingGeneration() ), + array() + ); + case 'vision': return new ModelRequirements( array( CapabilityEnum::textGeneration() ), diff --git a/src/experiments/semantic-search/index.ts b/src/experiments/semantic-search/index.ts new file mode 100644 index 000000000..f14ab95cb --- /dev/null +++ b/src/experiments/semantic-search/index.ts @@ -0,0 +1,132 @@ +/** + * Semantic search command loader for the block editor command palette. + * + * Registers a command loader with `core/commands` so that typing in the + * Cmd/Ctrl+K palette surfaces semantically ranked posts alongside the + * built-in commands. Results come from GET /ai/v1/semantic-search?q={query}. + */ + +/** + * WordPress dependencies + */ +import apiFetch from '@wordpress/api-fetch'; +import { dispatch } from '@wordpress/data'; +import { useEffect, useState } from '@wordpress/element'; + +interface SemanticSearchResult { + id: number; + title: string; + type: string; + url: string; + excerpt: string; + score: number; +} + +interface SemanticSearchResponse { + available: boolean; + results: SemanticSearchResult[]; +} + +interface CommandLoaderCommand { + name: string; + label: string; + callback: ( extras?: { close?: () => void } ) => void; +} + +declare global { + interface Window { + wpaiSemanticSearch?: { + restUrl: string; + nonce: string; + }; + } +} + +const config = window.wpaiSemanticSearch; + +/** + * Command palette hook that fetches semantically ranked posts as the user types. + * + * @param {Object} props Hook props supplied by the command palette. + * @param {string} props.search The current palette search string. + * @return {{ commands: CommandLoaderCommand[], isLoading: boolean }} Commands and loading state. + */ +function useSemanticSearchLoader( { search }: { search: string } ): { + commands: CommandLoaderCommand[]; + isLoading: boolean; +} { + const [ commands, setCommands ] = useState< CommandLoaderCommand[] >( [] ); + const [ isLoading, setIsLoading ] = useState( false ); + + useEffect( () => { + if ( ! search || ! config?.restUrl ) { + setCommands( [] ); + return; + } + + const controller = new AbortController(); + setIsLoading( true ); + + apiFetch< SemanticSearchResponse >( { + url: `${ config.restUrl }?q=${ encodeURIComponent( search ) }`, + signal: controller.signal, + headers: { 'X-WP-Nonce': config.nonce }, + } ) + .then( ( response ) => { + if ( ! response?.available ) { + setCommands( [] ); + return; + } + + setCommands( + response.results.map( ( result ) => ( { + // The search term is embedded in `name` so it is always part of the + // string the palette filters on. Gutenberg versions differ on whether + // `keywords` is forwarded, and `name` is never rendered to the user. + name: `wpai/semantic-search/${ encodeURIComponent( + search + ) }/${ result.id }`, + label: `${ result.title } (${ result.type })`, + callback: ( extras ) => { + window.location.href = result.url; + extras?.close?.(); + }, + } ) ) + ); + } ) + .catch( () => { + // Aborted or failed requests simply yield no semantic results. + setCommands( [] ); + } ) + .finally( () => { + setIsLoading( false ); + } ); + + return () => { + controller.abort(); + }; + }, [ search ] ); + + return { commands, isLoading }; +} + +if ( config?.restUrl ) { + // The store is resolved by name rather than by importing @wordpress/commands, + // which is not a declared dependency and is absent on older WordPress versions. + // Looking it up at runtime lets the palette integration degrade quietly instead + // of breaking the editor bundle. + // eslint-disable-next-line @wordpress/data-no-store-string-literals + const commandStore = dispatch( 'core/commands' ) as unknown as + | { + registerCommandLoader?: ( loader: { + name: string; + hook: typeof useSemanticSearchLoader; + } ) => void; + } + | undefined; + + commandStore?.registerCommandLoader?.( { + name: 'wpai/semantic-search', + hook: useSemanticSearchLoader, + } ); +} diff --git a/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php b/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php new file mode 100644 index 000000000..dca09fb66 --- /dev/null +++ b/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php @@ -0,0 +1,279 @@ + 'test-api-key' ) ); + add_filter( 'wpai_pre_has_valid_credentials_check', '__return_true' ); + + update_option( 'wpai_features_enabled', true ); + update_option( 'wpai_feature_semantic-search_enabled', true ); + } + + /** + * Tear down test case. + * + * @since x.x.x + */ + public function tearDown(): void { + delete_option( 'wpai_features_enabled' ); + delete_option( 'wpai_feature_semantic-search_enabled' ); + delete_option( 'wp_ai_client_provider_credentials' ); + delete_option( Semantic_Search::get_field_option_name( 'model' ) ); + delete_option( Semantic_Search::get_field_option_name( 'score_threshold' ) ); + remove_filter( 'wpai_pre_has_valid_credentials_check', '__return_true' ); + parent::tearDown(); + } + + /** + * Invokes a non-public method using reflection. + * + * @since x.x.x + * + * @param object $instance Object to invoke the method on. + * @param string $method_name Name of the method to invoke. + * @param array $args Arguments to pass to the method. + * @return mixed The value returned by the invoked method. + */ + private function invoke_method( object $instance, string $method_name, array $args = array() ) { + $reflection = new \ReflectionClass( $instance ); + $method = $reflection->getMethod( $method_name ); + $method->setAccessible( true ); + + return $method->invokeArgs( $instance, $args ); + } + + /** + * Test that the experiment exposes the expected identity metadata. + * + * @since x.x.x + */ + public function test_experiment_metadata() { + $experiment = new Semantic_Search(); + + $this->assertSame( 'semantic-search', $experiment->get_id() ); + $this->assertSame( 'Semantic Search', $experiment->get_label() ); + $this->assertSame( Experiment_Category::ADMIN, $experiment->get_category() ); + $this->assertSame( 'embedding_generation', $experiment->get_capability() ); + } + + /** + * Test that the settings fields no longer expose provider credentials. + * + * Provider selection and authentication belong to the connector settings, + * so this experiment must only own the model preference and threshold. + * + * @since x.x.x + */ + public function test_settings_fields_contain_no_provider_configuration() { + $fields = ( new Semantic_Search() )->get_settings_fields(); + $ids = wp_list_pluck( $fields, 'id' ); + + $this->assertSame( array( 'model', 'score_threshold' ), $ids ); + $this->assertNotContains( 'api_key', $ids ); + $this->assertNotContains( 'provider', $ids ); + $this->assertNotContains( 'base_url', $ids ); + } + + /** + * Test that the score threshold falls back to the default when unset. + * + * @since x.x.x + */ + public function test_score_threshold_defaults_when_option_is_empty() { + $generator = new Embedding_Generator(); + + $this->assertSame( + Embedding_Generator::DEFAULT_SCORE_THRESHOLD, + $generator->get_score_threshold() + ); + } + + /** + * Test that a saved score threshold is used when it is valid. + * + * @since x.x.x + */ + public function test_score_threshold_uses_saved_value() { + update_option( Semantic_Search::get_field_option_name( 'score_threshold' ), '0.72' ); + + $this->assertSame( 0.72, ( new Embedding_Generator() )->get_score_threshold() ); + } + + /** + * Test that out-of-range and non-numeric thresholds fall back to the default. + * + * @since x.x.x + */ + public function test_score_threshold_rejects_invalid_values() { + $generator = new Embedding_Generator(); + $option = Semantic_Search::get_field_option_name( 'score_threshold' ); + + foreach ( array( '-0.2', '1.4', 'not-a-number' ) as $invalid ) { + update_option( $option, $invalid ); + + $this->assertSame( + Embedding_Generator::DEFAULT_SCORE_THRESHOLD, + $generator->get_score_threshold(), + sprintf( 'Value "%s" should fall back to the default threshold.', $invalid ) + ); + } + } + + /** + * Test that the model preference is read from the saved option. + * + * @since x.x.x + */ + public function test_get_model_reads_saved_option() { + $generator = new Embedding_Generator(); + + $this->assertSame( '', $generator->get_model() ); + + update_option( Semantic_Search::get_field_option_name( 'model' ), ' text-embedding-3-small ' ); + + $this->assertSame( 'text-embedding-3-small', $generator->get_model() ); + } + + /** + * Test that the embedding store round-trips a vector for a post. + * + * @since x.x.x + */ + public function test_embedding_store_saves_and_retrieves_vector() { + $post_id = self::factory()->post->create(); + $store = new Embedding_Store(); + + $this->assertNull( $store->get( $post_id ), 'An unindexed post should have no vector.' ); + + $store->save( $post_id, array( 0.1, 0.2, 0.3 ), 'test-model' ); + + $this->assertSame( array( 0.1, 0.2, 0.3 ), $store->get( $post_id ) ); + + $store->delete( $post_id ); + + $this->assertNull( $store->get( $post_id ), 'A deleted vector should not be returned.' ); + } + + /** + * Test that stats report published posts and how many are indexed. + * + * @since x.x.x + */ + public function test_embedding_store_reports_stats() { + $store = new Embedding_Store(); + $baseline = $store->get_stats(); + + $indexed = self::factory()->post->create( array( 'post_status' => 'publish' ) ); + $unindexed = self::factory()->post->create( array( 'post_status' => 'publish' ) ); + + $store->save( $indexed, array( 0.5, 0.5 ), 'test-model' ); + + $stats = $store->get_stats(); + + $this->assertSame( $baseline['total'] + 2, $stats['total'] ); + $this->assertSame( $baseline['indexed'] + 1, $stats['indexed'] ); + $this->assertNotContains( $indexed, $store->get_unindexed_ids( array( 'post', 'page' ), 50 ) ); + $this->assertContains( $unindexed, $store->get_unindexed_ids( array( 'post', 'page' ), 50 ) ); + } + + /** + * Test that unindexed ID lookups honour the requested limit. + * + * @since x.x.x + */ + public function test_get_unindexed_ids_respects_limit() { + self::factory()->post->create_many( 3, array( 'post_status' => 'publish' ) ); + + $ids = ( new Embedding_Store() )->get_unindexed_ids( array( 'post', 'page' ), 2 ); + + $this->assertCount( 2, $ids ); + $this->assertContainsOnly( 'int', $ids ); + } + + /** + * Test that cosine similarity scores identical and orthogonal vectors correctly. + * + * @since x.x.x + */ + public function test_cosine_similarity_scores_known_vectors() { + $search = new Vector_Search(); + + $this->assertEqualsWithDelta( + 1.0, + $this->invoke_method( $search, 'cosine_similarity', array( array( 1.0, 0.0 ), array( 1.0, 0.0 ) ) ), + 0.0001, + 'Identical vectors should score 1.' + ); + + $this->assertEqualsWithDelta( + 0.0, + $this->invoke_method( $search, 'cosine_similarity', array( array( 1.0, 0.0 ), array( 0.0, 1.0 ) ) ), + 0.0001, + 'Orthogonal vectors should score 0.' + ); + + $this->assertEqualsWithDelta( + -1.0, + $this->invoke_method( $search, 'cosine_similarity', array( array( 1.0, 0.0 ), array( -1.0, 0.0 ) ) ), + 0.0001, + 'Opposing vectors should score -1.' + ); + } + + /** + * Test that a zero-magnitude vector scores 0 rather than dividing by zero. + * + * @since x.x.x + */ + public function test_cosine_similarity_handles_zero_vector() { + $score = $this->invoke_method( + new Vector_Search(), + 'cosine_similarity', + array( array( 0.0, 0.0 ), array( 1.0, 1.0 ) ) + ); + + $this->assertSame( 0.0, $score ); + } + + /** + * Test that mismatched vector lengths compare over the shorter length. + * + * @since x.x.x + */ + public function test_cosine_similarity_handles_mismatched_dimensions() { + $score = $this->invoke_method( + new Vector_Search(), + 'cosine_similarity', + array( array( 1.0, 0.0, 0.0 ), array( 1.0, 0.0 ) ) + ); + + $this->assertEqualsWithDelta( 1.0, $score, 0.0001 ); + } +} diff --git a/tests/Integration/Includes/REST/Models_ControllerTest.php b/tests/Integration/Includes/REST/Models_ControllerTest.php index bd49b1ae9..3ef9c437b 100644 --- a/tests/Integration/Includes/REST/Models_ControllerTest.php +++ b/tests/Integration/Includes/REST/Models_ControllerTest.php @@ -51,7 +51,7 @@ public function test_register_routes_declares_capability_argument_schema(): void $this->assertSame( 'string', $capability_argument['type'] ); $this->assertTrue( $capability_argument['required'] ); $this->assertSame( - array( 'text_generation', 'image_generation', 'vision' ), + array( 'text_generation', 'image_generation', 'vision', 'embedding_generation' ), $capability_argument['enum'] ); $this->assertSame( 'sanitize_key', $capability_argument['sanitize_callback'] ); diff --git a/webpack.config.js b/webpack.config.js index 35db526e5..b11f9628f 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -100,6 +100,11 @@ module.exports = { 'src/experiments/slug-generation', 'index.tsx' ), + 'experiments/semantic-search': path.resolve( + process.cwd(), + 'src/experiments/semantic-search', + 'index.ts' + ), 'experiments/type-ahead': path.resolve( process.cwd(), 'src/experiments/type-ahead', From 2c240c938916c846a9e30e25b1359123a4798260 Mon Sep 17 00:00:00 2001 From: Colin McDonough Date: Sun, 16 Aug 2026 13:18:41 -0400 Subject: [PATCH 3/4] Fix: bound semantic search to indexed posts (resolve posts_per_page=-1 VIP lint) Replace the unbounded WP_Query (posts_per_page => -1) in Vector_Search with a bounded, filterable lookup of only posts that have a stored embedding, via a new Embedding_Store::get_indexed_ids() using SELECT DISTINCT. Fixes the PHPCS VIP violation and avoids loading every published post into memory to score. Adds tests for the new method. --- .../Semantic_Search/Embedding_Store.php | 40 +++++++++++++++++++ .../Semantic_Search/Vector_Search.php | 29 ++++++++------ .../Semantic_Search/Semantic_SearchTest.php | 37 +++++++++++++++++ 3 files changed, 93 insertions(+), 13 deletions(-) diff --git a/includes/Experiments/Semantic_Search/Embedding_Store.php b/includes/Experiments/Semantic_Search/Embedding_Store.php index bbdc4e704..39e45f7ff 100644 --- a/includes/Experiments/Semantic_Search/Embedding_Store.php +++ b/includes/Experiments/Semantic_Search/Embedding_Store.php @@ -120,6 +120,46 @@ public function get_unindexed_ids( array $post_types, int $limit = 5 ): array { return array_map( 'intval', is_array( $rows ) ? $rows : array() ); } + /** + * Returns IDs of published posts that already have a stored embedding. + * + * Lets the vector search score only indexed content instead of loading + * every published post into memory. + * + * @since x.x.x + * + * @param string[] $post_types Post type slugs to include (e.g. ['post', 'page']). + * @param int $limit Maximum number of IDs to return. + * @return int[] Post IDs that have a stored embedding, newest first. + */ + public function get_indexed_ids( array $post_types, int $limit ): array { + global $wpdb; + + if ( empty( $post_types ) || $limit <= 0 ) { + return array(); + } + + $types_placeholders = implode( ', ', array_fill( 0, count( $post_types ), '%s' ) ); + + $sql = "SELECT DISTINCT p.ID FROM {$wpdb->posts} p + INNER JOIN {$wpdb->postmeta} pm + ON p.ID = pm.post_id AND pm.meta_key = %s + WHERE p.post_status = 'publish' + AND p.post_type IN ( {$types_placeholders} ) + ORDER BY p.ID DESC + LIMIT %d"; + + $values = array_merge( + array( self::META_EMBEDDING ), + array_values( $post_types ), + array( $limit ) + ); + + $rows = $wpdb->get_col( $wpdb->prepare( $sql, $values ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared -- $sql is built from a fixed template with generated placeholders; all values are passed through prepare(). + + return array_map( 'intval', is_array( $rows ) ? $rows : array() ); + } + /** * Returns total and indexed post/page counts for the current site. * diff --git a/includes/Experiments/Semantic_Search/Vector_Search.php b/includes/Experiments/Semantic_Search/Vector_Search.php index 807a838ae..2430a8624 100644 --- a/includes/Experiments/Semantic_Search/Vector_Search.php +++ b/includes/Experiments/Semantic_Search/Vector_Search.php @@ -98,22 +98,25 @@ public function search( string $query, array $args = array() ): array { $post_types = $args['post_type'] ?? array( 'post', 'page' ); $score_threshold = $this->api->get_score_threshold(); - $wq = new \WP_Query( - array( - 'post_type' => $post_types, - 'post_status' => 'publish', - 'posts_per_page' => -1, - 'no_found_rows' => true, - 'fields' => 'ids', - ) - ); + /** + * Filters the maximum number of indexed posts scored per semantic search. + * + * The vector search compares the query embedding against each candidate + * in memory, so this bounds the work (and memory) on large sites. Only + * posts that already have a stored embedding are considered. + * + * @since x.x.x + * + * @param int $max_candidates Maximum posts to score. Default 2000. + * @param string[] $post_types Post types being searched. + */ + $max_candidates = (int) apply_filters( 'wpai_semantic_search_max_candidates', 2000, $post_types ); + + $candidate_ids = $this->store->get_indexed_ids( $post_types, $max_candidates ); $results = array(); - foreach ( $wq->posts as $found_post ) { - // WP_Query is queried with 'fields' => 'ids', but the return type also allows objects. - $post_id = $found_post instanceof \WP_Post ? $found_post->ID : (int) $found_post; - + foreach ( $candidate_ids as $post_id ) { $embedding = $this->store->get( $post_id ); if ( null === $embedding ) { diff --git a/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php b/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php index dca09fb66..fecaaf796 100644 --- a/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php +++ b/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php @@ -217,6 +217,43 @@ public function test_get_unindexed_ids_respects_limit() { $this->assertContainsOnly( 'int', $ids ); } + /** + * Test that indexed ID lookups return only posts that have a stored embedding. + * + * @since x.x.x + */ + public function test_get_indexed_ids_returns_only_indexed_posts() { + $store = new Embedding_Store(); + $indexed = self::factory()->post->create( array( 'post_status' => 'publish' ) ); + $other = self::factory()->post->create( array( 'post_status' => 'publish' ) ); + + $store->save( $indexed, array( 0.1, 0.2, 0.3 ), 'test-model' ); + + $ids = $store->get_indexed_ids( array( 'post', 'page' ), 50 ); + + $this->assertContains( $indexed, $ids, 'A post with an embedding should be returned.' ); + $this->assertNotContains( $other, $ids, 'A post without an embedding should be excluded.' ); + $this->assertContainsOnly( 'int', $ids ); + } + + /** + * Test that indexed ID lookups honour the requested limit. + * + * @since x.x.x + */ + public function test_get_indexed_ids_respects_limit() { + $store = new Embedding_Store(); + + foreach ( self::factory()->post->create_many( 3, array( 'post_status' => 'publish' ) ) as $post_id ) { + $store->save( $post_id, array( 0.1, 0.2 ), 'test-model' ); + } + + $ids = $store->get_indexed_ids( array( 'post', 'page' ), 2 ); + + $this->assertCount( 2, $ids ); + $this->assertContainsOnly( 'int', $ids ); + } + /** * Test that cosine similarity scores identical and orthogonal vectors correctly. * From 9e69699e8c44599376120f95a20387c84a0fe367 Mon Sep 17 00:00:00 2001 From: Colin McDonough Date: Sun, 16 Aug 2026 13:02:01 -0700 Subject: [PATCH 4/4] Fix: make the posts-list "Search semantically" checkbox submit reliably MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The checkbox and the search field can live in separate admin forms, and the previous onchange auto-submit dropped the wpai_semantic flag — so checking the box and clicking "Search Posts" ran a plain keyword search instead of semantic. Bind the flag to whichever form owns the search input and keep it in sync with the checkbox so the search term and the flag always submit together. --- .../List_Table_Integration.php | 47 +++++++++++++++---- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/includes/Experiments/Semantic_Search/List_Table_Integration.php b/includes/Experiments/Semantic_Search/List_Table_Integration.php index 9489bdf65..4f8e2dd55 100644 --- a/includes/Experiments/Semantic_Search/List_Table_Integration.php +++ b/includes/Experiments/Semantic_Search/List_Table_Integration.php @@ -69,18 +69,49 @@ public function render_checkbox(): void { } // phpcs:ignore WordPress.Security.NonceVerification.Recommended - $checked = isset( $_GET[ self::PARAM ] ) ? ' checked' : ''; + $checked = isset( $_GET[ self::PARAM ] ); ?> +