Skip to content
1 change: 1 addition & 0 deletions includes/Experiments/Experiments.php
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ final class Experiments {
* @var array<class-string<\WordPress\AI\Contracts\Feature>>
*/
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,
Expand Down
147 changes: 147 additions & 0 deletions includes/Experiments/Semantic_Search/Embedding_Generator.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
<?php
/**
* Embedding generation via the PHP AI Client.
*
* Provider selection, authentication and transport are all handled by the
* registered connectors, so this class contains no provider-specific code.
*
* @package WordPress\AI\Experiments\Semantic_Search
*/

declare( strict_types=1 );

namespace WordPress\AI\Experiments\Semantic_Search;

use function WordPress\AI\generate_embeddings;
use function WordPress\AI\has_ai_credentials;
use function WordPress\AI\supports_embedding_generation;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
* Turns text into embedding vectors using the PHP AI Client.
*
* The experiment only stores an optional model preference and a similarity
* threshold. Credentials and endpoints belong to the connector configuration
* under Settings → AI, not to this experiment.
*
* @internal
* @since x.x.x
*/
class Embedding_Generator {

/**
* Similarity score cut-off used when the user has not configured one.
*
* @since x.x.x
* @var float
*/
public const DEFAULT_SCORE_THRESHOLD = 0.5;

/**
* Human-readable description of the last failure, or empty string if none.
*
* @since x.x.x
* @var string
*/
private string $last_error = '';

/**
* Returns the configured embedding model preference.
*
* An empty string means "let the AI Client pick", which is the default.
*
* @since x.x.x
*
* @return string Model identifier, or empty string when unset.
*/
public function get_model(): string {
return trim( (string) get_option( Semantic_Search::get_field_option_name( 'model' ), '' ) );
}

/**
* Returns the human-readable error from the most recent generate() call.
*
* @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 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 );
}
}
207 changes: 207 additions & 0 deletions includes/Experiments/Semantic_Search/Embedding_Store.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
<?php
/**
* Reads and writes post embeddings stored in post meta.
*
* TODO: Replace this class once WordPress/ai#683 (native VECTOR INDEX) lands.
* At that point, write to the VECTOR column instead of postmeta and
* run retrieval via a MariaDB dot-product query instead of PHP iteration.
*
* @package WordPress\AI\Experiments\Semantic_Search
*/

declare( strict_types=1 );

namespace WordPress\AI\Experiments\Semantic_Search;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
* Postmeta-backed embedding store.
*
* Persists embedding vectors as serialised float arrays in wp_postmeta.
* Each indexed post receives two meta keys: one for the embedding vector
* and one for the model that produced it.
*
* @internal
* @since x.x.x
*/
class Embedding_Store {

/**
* Post meta key for the serialised float[] embedding vector.
*
* @since x.x.x
* @var string
*/
private const META_EMBEDDING = '_wpai_semantic_search_embedding';

/**
* Post meta key for the model identifier that produced the embedding.
*
* @since x.x.x
* @var string
*/
private const META_MODEL = '_wpai_semantic_search_embedding_model';

/**
* Persists an embedding vector and the model that produced it for a post.
*
* @since x.x.x
*
* @param int $post_id Post ID to index.
* @param float[] $embedding Float vector returned by the embedding API.
* @param string $model Model identifier (e.g. 'gemini-embedding-001').
* @return void
*/
public function save( int $post_id, array $embedding, string $model ): void {
update_post_meta( $post_id, self::META_EMBEDDING, $embedding );
update_post_meta( $post_id, self::META_MODEL, $model );
}

/**
* Retrieves the stored embedding vector for a post.
*
* Returns null when the post has not been indexed yet or when the stored
* value cannot be cast to a non-empty float array.
*
* @since x.x.x
*
* @param int $post_id Post ID to look up.
* @return float[]|null Float vector on success, null if not indexed.
*/
public function get( int $post_id ): ?array {
$value = get_post_meta( $post_id, self::META_EMBEDDING, true );

if ( ! is_array( $value ) || empty( $value ) ) {
return null;
}

return array_map( 'floatval', $value );
}

/**
* Returns the IDs of published posts that have not yet been indexed.
*
* Uses a LEFT JOIN between wp_posts and wp_postmeta so that the check is
* performed in SQL rather than loading all post IDs into PHP 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. Default 5.
* @return int[] Post IDs that have no stored embedding.
*/
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' ) );

$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 )
);

$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 );
}
}
Loading
Loading