Add your own search provider to AI Search
Add a search service of your own, such as a self-hosted embedding model, to the Provider list on Settings → AI Search. Register it with the benecaster_ai_search_providers filter and implement AISearchProviderInterface.
- A factory is
callable( string $api_key, array $settings ): AISearchProviderInterface.$settings['model']is the model the podcaster chose, or''for your default. Build the object only: never call your API from the factory. modelsis optional:[ model => [ 'label' => string, 'description' => string ] ], your default first. Leave it out, or pass[], and the screen offers no model choice. An entry with an empty label is dropped.- The built-ins’
modelsare the lists in use, not always the ones the add-on shipped: the licence server’s AI model catalogue when it lists models for this release (text models for Anthropic, embedding models for OpenAI and Cohere; Gemini has no model choice), otherwise the shipped list. Retired models are left out. Read them, don’t assume them. - You can add providers, never replace or remove a built-in. An entry that changes or drops
openai,gemini,cohereoranthropicis ignored, and the built-in stays. An entry is also ignored when its slug is not 1–32 characters ofa-z,0-9,_or-, or it has an empty label or a factory that cannot be called. A factory that throws, or returns anything but a provider whoseslug()is the entry’s slug, makes the provider fail with “The {label} provider could not be loaded.” Your exception’s message is never shown, since it could hold the key.
Two architectures behind one contract, and supports_indexing() is the only branch. Return true and yours is an embedding provider: episodes are embedded ahead of time into the add-on’s index, and a search embeds the query once and compares locally. Return false and it is an LLM provider: nothing is indexed, and each search calls rank(). Whichever you choose, the other method throws ProviderException( ProviderErrorKind::Unsupported, … ).
slug()(your entry’s slug),label(), andmodel_id():{slug}/{model}, stored on every index row. Vectors are compared only within onemodel_id(), so changing it re-indexes in the background.max_batch_size()is the most texts oneembed()call takes (at least 1).max_input_tokens()is the most tokens of one text you read; the add-on cuts longer text into pieces under it.embed( list<string> $texts, EmbeddingPurpose $purpose ): list<list<float>>returns one vector per text, in order, all the same length.$purposeisEmbeddingPurpose::Documentwhen indexing an episode andEmbeddingPurpose::Queryfor a search; ignore it if your model has no such notion.rank( string $query, list<RankCandidate> $candidates ): list<int>returns candidate ids (RankCandidate::$id; the text to read isRankCandidate::$text), most relevant first, each at most once. An empty list is a valid answer. Rank every candidate you are given: the add-on decides access per result afterwards.verify_credentials(): voidis the Test connection check: one cheap call that succeeds only with a valid key.- Throw
ProviderException( ProviderErrorKind $kind, string $message, ?int $http_status, ?int $retry_after )for every failure.RateLimitedandUnavailableare retried with backoff;Auth,InvalidRequest,InvalidResponseandUnsupportedare not. The message is shown to the podcaster on Test connection and logged otherwise, never to a subscriber. Never put the key in it.
Only embed() for one query, or rank(), is ever called while a visitor waits; indexing runs in the background. Use wp_safe_remote_post() with a timeout. The list is built once, on first use, so add your callback on or before init.
A model on your own server or network needs two WordPress filters. wp_safe_remote_post() refuses a local or private address (localhost, 127.0.0.1, 10.x, 192.168.x) and any port but 80, 443 and 8080, so a model running beside WordPress, such as Ollama on localhost:11434, fails before the request is sent. Allow only that host with WordPress’s http_request_host_is_external filter and only that port with http_allowed_safe_ports, rather than switching to wp_remote_post(), which drops the check for every address.
Code
<?php
use BenecasterAiSearch\Provider\{ AISearchProviderInterface, EmbeddingPurpose, ProviderErrorKind, ProviderException };
add_filter( 'benecaster_ai_search_providers', function ( array $providers ): array {
$providers['localembed'] = [
'label' => __( 'Local Embed', 'my-plugin' ),
'factory' => fn( string $api_key, array $settings ): AISearchProviderInterface => new My_Local_Embed_Provider( $api_key ),
];
return $providers;
} );
final class My_Local_Embed_Provider implements AISearchProviderInterface {
public function __construct( private string $key ) {}
public function slug(): string { return 'localembed'; }
public function label(): string { return __( 'Local Embed', 'my-plugin' ); }
public function supports_indexing(): bool { return true; }
public function model_id(): string { return 'localembed/mini-v1'; }
public function max_batch_size(): int { return 16; }
public function max_input_tokens(): int { return 512; }
public function embed( array $texts, EmbeddingPurpose $purpose ): array {
$response = wp_safe_remote_post( 'https://embed.example.internal/v1/embed', [
'timeout' => 30,
'headers' => [ 'Authorization' => 'Bearer ' . $this->key, 'Content-Type' => 'application/json' ],
'body' => wp_json_encode( [ 'input' => $texts, 'kind' => $purpose->value ] ),
] );
$code = (int) wp_remote_retrieve_response_code( $response );
if ( is_wp_error( $response ) || $code >= 500 ) {
throw new ProviderException( ProviderErrorKind::Unavailable, __( 'Local Embed could not be reached.', 'my-plugin' ) );
}
if ( 401 === $code ) {
throw new ProviderException( ProviderErrorKind::Auth, __( 'Local Embed did not accept the API key.', 'my-plugin' ), 401 );
}
$vectors = json_decode( wp_remote_retrieve_body( $response ), true )['vectors'] ?? null;
if ( ! is_array( $vectors ) || count( $vectors ) !== count( $texts ) ) {
throw new ProviderException( ProviderErrorKind::InvalidResponse, __( 'Local Embed sent an answer that could not be read.', 'my-plugin' ) );
}
return $vectors;
}
public function rank( string $query, array $candidates ): array {
throw new ProviderException( ProviderErrorKind::Unsupported, __( 'Local Embed builds an index; it does not rank.', 'my-plugin' ) );
}
public function verify_credentials(): void {
$this->embed( [ 'ping' ], EmbeddingPurpose::Query );
}
}
Hooks Used
Need this built rather than just documented? See our services →