Skip to main content

Add your own search provider to AI Search

Premium Advanced 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.
  • models is 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’ models are 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, cohere or anthropic is ignored, and the built-in stays. An entry is also ignored when its slug is not 1–32 characters of a-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 whose slug() 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(), and model_id(): {slug}/{model}, stored on every index row. Vectors are compared only within one model_id(), so changing it re-indexes in the background.
  • max_batch_size() is the most texts one embed() 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. $purpose is EmbeddingPurpose::Document when indexing an episode and EmbeddingPurpose::Query for 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 is RankCandidate::$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(): void is 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. RateLimited and Unavailable are retried with backoff; Auth, InvalidRequest, InvalidResponse and Unsupported are 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 );
    }
}

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →