$records The records to store. * @return list<\WordPress\AI\Embeddings\Embedding_Record> The stored records, carrying their row IDs. * * The returned list is positionally aligned with $records, so callers may pair them by index. * * @throws \InvalidArgumentException If any entry is not an Embedding_Record. The batch is * validated in full before anything is written, so a rejected * batch writes nothing. * @throws \RuntimeException If a record could not be written. Records are written in * multi-row batches of 100 that are not rolled back, so a * failure part-way through leaves earlier batches stored. */ public function save_many( array $records ): array; /** * Returns the stored vectors for an object, in chunk order. * * @since 1.4.0 * * @param string $object_type Object type. * @param int $object_id Object ID. * @param string $provider Provider ID. * @param string $model Model ID. * @return list<\WordPress\AI\Embeddings\Embedding_Record> Records, empty if the object is not indexed for this model. */ public function get( string $object_type, int $object_id, string $provider, string $model ): array; /** * Returns a record by its row ID. * * @since 1.4.0 * * @param int $id Row ID. * @return \WordPress\AI\Embeddings\Embedding_Record|null The record, or null if it does not exist. */ public function get_by_id( int $id ): ?Embedding_Record; /** * Returns the content hash stored for an object, if any. * * Lets callers decide whether an object needs re-embedding without loading its vectors. * The hash is object-level: every chunk of an object stores the same hash, covering the whole * source content. * * @since 1.4.0 * * @param string $object_type Object type. * @param int $object_id Object ID. * @param string $provider Provider ID. * @param string $model Model ID. * @return string|null The hash, or null if the object is not indexed for this model. */ public function get_content_hash( string $object_type, int $object_id, string $provider, string $model ): ?string; /** * Returns the stored content hashes for the given objects, keyed by object ID. * * @since 1.5.0 * * @param string $object_type Object type. * @param list $object_ids Candidate object IDs. Keep to a few hundred per call. * @param string $provider Provider ID. * @param string $model Model ID. * @return array Map of object ID to content hash. */ public function get_indexed_hashes( string $object_type, array $object_ids, string $provider, string $model ): array; /** * Replaces every stored chunk of one object for one model. * * @since 1.5.0 * * @param string $object_type Object type. * @param int $object_id Object ID. * @param string $provider Provider ID. * @param string $model Model ID. * @param list<\WordPress\AI\Embeddings\Embedding_Record> $records Every chunk for the object and model, chunk_index 0..n-1 in * order. An empty list deletes the object's vectors for the model. * @return list<\WordPress\AI\Embeddings\Embedding_Record> The stored records, carrying their row IDs, in chunk order. * * @throws \InvalidArgumentException If a record is not an Embedding_Record, belongs to another object or model, or the chunk * indexes are not 0..n-1 in order. Nothing is written. * @throws \RuntimeException If a write failed. */ public function replace_for_object( string $object_type, int $object_id, string $provider, string $model, array $records ): array; /** * Replaces every stored chunk of one object for one model, without reading the rows back. * * @since 1.5.0 * * @param string $object_type Object type. * @param int $object_id Object ID. * @param string $provider Provider ID. * @param string $model Model ID. * @param list<\WordPress\AI\Embeddings\Embedding_Record> $records Every chunk for the object and model, chunk_index 0..n-1 in * order. An empty list deletes the object's vectors for the model. * * @throws \InvalidArgumentException If a record is not an Embedding_Record, belongs to another object or model, or the chunk * indexes are not 0..n-1 in order. Nothing is written. * @throws \RuntimeException If a write failed. */ public function store_for_object( string $object_type, int $object_id, string $provider, string $model, array $records ): void; /** * Returns the IDs of objects that have stored vectors for a model, newest first. * * @since 1.4.0 * * @param string $object_type Object type. * @param string $provider Provider ID. * @param string $model Model ID. * @param int $limit Maximum number of IDs to return. * @param int $offset Optional. Number of IDs to skip. Default 0. * @return list Distinct object IDs. */ public function get_object_ids( string $object_type, string $provider, string $model, int $limit, int $offset = 0 ): array; /** * Returns the IDs of objects that have stored vectors for a model, after a cursor, ascending. * * @since 1.5.0 * * @param string $object_type Object type. * @param string $provider Provider ID. * @param string $model Model ID. * @param int $after_id Return IDs greater than this. * @param int $limit Maximum number of IDs to return. * @return list Distinct object IDs in ascending order. * * @throws \RuntimeException If the IDs could not be read, so a failure is never mistaken for the end. */ public function get_object_ids_after( string $object_type, string $provider, string $model, int $after_id, int $limit ): array; /** * Counts the objects that have stored vectors for a model. * * @since 1.4.0 * * @param string $object_type Object type. * @param string $provider Provider ID. * @param string $model Model ID. * @return int Number of distinct objects. */ public function count_objects( string $object_type, string $provider, string $model ): int; /** * Counts indexed objects per subtype for one model and object type. * * @since 1.5.0 * * @param string $object_type Object type. * @param string $provider Provider ID. * @param string $model Model ID. * @return array Map of object subtype to the number of objects with vectors. */ public function count_objects_by_subtype( string $object_type, string $provider, string $model ): array; /** * Iterates over every record for a model, in batches. * * @since 1.4.0 * * @param string $provider Provider ID. * @param string $model Model ID. * @param string|null $object_type Optional. Restrict to one object type. Default null. * @param int $batch_size Optional. Rows fetched per query. Default 200. * @return iterable<\WordPress\AI\Embeddings\Embedding_Record> The records. * * @throws \RuntimeException If a batch could not be read. Normal completion therefore means * every matching record was yielded, which is what lets a caller * rebuilding an index over the whole corpus trust the scan. */ public function iterate( string $provider, string $model, ?string $object_type = null, int $batch_size = 200 ): iterable; /** * Deletes the stored vectors for an object. * * @since 1.4.0 * * @param string $object_type Object type. * @param int $object_id Object ID. * @param string|null $provider Optional. Restrict to one provider. Default null, all providers. * @param string|null $model Optional. Restrict to one model. Default null, all models. * @return int Number of rows deleted. */ public function delete_for_object( string $object_type, int $object_id, ?string $provider = null, ?string $model = null ): int; /** * Deletes every stored vector produced by a model. * * @since 1.4.0 * * @param string $provider Provider ID. * @param string $model Model ID. * @return int Number of rows deleted. */ public function delete_for_model( string $provider, string $model ): int; }