diff --git a/includes/Experiments/Experiments.php b/includes/Experiments/Experiments.php index aedf63d87..fa0663674 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\Custom_Abilities\Custom_Abilities::class, \WordPress\AI\Experiments\AI_Request_Logging\AI_Request_Logging::class, 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 new file mode 100644 index 000000000..39e45f7ff --- /dev/null +++ b/includes/Experiments/Semantic_Search/Embedding_Store.php @@ -0,0 +1,207 @@ +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 ) + ); + + $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 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. + * + * @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..9c1d43af3 --- /dev/null +++ b/includes/Experiments/Semantic_Search/Index_Page.php @@ -0,0 +1,265 @@ + 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' ) ); + } + + $generator = new Embedding_Generator(); + $store = new Embedding_Store(); + $stats = $store->get_stats(); + ?> +
+

+ + is_available() ) : ?> +
+

+ Settings → AI and connect a provider that supports embedding generation.', 'ai' ); + + printf( + wp_kses( $notice, array( 'a' => array( 'href' => array() ) ) ), + esc_url( admin_url( 'options-general.php?page=ai-wp-admin' ) ) + ); + ?> +

+
+ + +

+ +

+ +
+ + + +
+ +

+ + +
+ + + api = new Embedding_Generator(); + $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_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 + * + * @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 ) ) { + ++$failed; + $error = $this->api->get_last_error(); + break; + } + + ++$success; + } + + 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..4f8e2dd55 --- /dev/null +++ b/includes/Experiments/Semantic_Search/List_Table_Integration.php @@ -0,0 +1,187 @@ + + + + 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; + } + + $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' => $post_types, + ) + ); + + 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..fed87e367 --- /dev/null +++ b/includes/Experiments/Semantic_Search/REST_Controller.php @@ -0,0 +1,224 @@ + '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" 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 { + $generator = new Embedding_Generator(); + + if ( ! $generator->is_available() ) { + return new \WP_REST_Response( + array( + 'ok' => false, + 'error' => __( 'No connector with embedding support is configured.', 'ai' ), + ), + 200 + ); + } + + $embedding = $generator->generate( 'test' ); + + if ( null === $embedding ) { + return new \WP_REST_Response( + array( + 'ok' => false, + 'error' => $generator->get_last_error(), + ), + 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 new file mode 100644 index 000000000..b9d018ace --- /dev/null +++ b/includes/Experiments/Semantic_Search/Semantic_Search.php @@ -0,0 +1,232 @@ + __( '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' => 'model', + 'label' => __( 'Model', 'ai' ), + 'type' => 'text', + 'default' => '', + ), + array( + 'id' => 'score_threshold', + 'label' => __( 'Score Threshold', 'ai' ), + 'type' => 'text', + 'default' => '', + ), + ); + } + + /** + * Enqueues the command palette JS in the block editor. + * + * 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 { + if ( ! ( new Embedding_Generator() )->is_available() ) { + return; + } + + $handle = 'semantic_search'; + + Asset_Loader::enqueue_script( $handle, 'experiments/semantic-search' ); + + Asset_Loader::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 + * embedding generation is unavailable. + * + * @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; + } + + if ( ! ( new Embedding_Generator() )->is_available() ) { + 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..2430a8624 --- /dev/null +++ b/includes/Experiments/Semantic_Search/Vector_Search.php @@ -0,0 +1,194 @@ +api = new Embedding_Generator(); + $this->store = new Embedding_Store(); + } + + /** + * Returns whether embedding generation is available and ready to search. + * + * 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 embeddings can be generated. + */ + public function is_available(): bool { + return $this->api->is_available(); + } + + /** + * 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?: 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 { + $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(); + + /** + * 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 ( $candidate_ids as $post_id ) { + $embedding = $this->store->get( $post_id ); + + if ( null === $embedding ) { + continue; + } + + $score = $this->cosine_similarity( $query_embedding, $embedding ); + + if ( $score < $score_threshold ) { + continue; + } + + $post = get_post( $post_id ); + + if ( ! $post instanceof \WP_Post ) { + continue; + } + + $edit_link = (string) get_edit_post_link( $post_id, '' ); + + $results[] = array( + 'id' => $post_id, + 'title' => $post->post_title, + 'type' => $post->post_type, + 'url' => '' !== $edit_link ? $edit_link : '#', + 'excerpt' => wp_trim_words( wp_strip_all_tags( $post->post_content ), 20 ), + 'score' => round( $score, 4 ), + ); + } + + usort( + $results, + static function ( array $a, array $b ): int { + return $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 ) ); + } +} 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..fecaaf796 --- /dev/null +++ b/tests/Integration/Includes/Experiments/Semantic_Search/Semantic_SearchTest.php @@ -0,0 +1,316 @@ + '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 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. + * + * @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',