Skip to main content

AISearchProviderInterface

BenecasterAiSearch\Provider\AISearchProviderInterface

Interface Premium ai-search

The contract a search provider implements to appear in the AI Search add-on’s Provider list on Settings → AI Search. Register a factory that returns your instance through the benecaster_ai_search_providers filter; the built-in OpenAI, Google Gemini, Cohere and Anthropic providers implement the same interface.

Two architectures behind one contract, and supports_indexing() is the only branch. An embedding provider returns true: episodes are embedded ahead of time into the add-on’s own index with embed() and EmbeddingPurpose::Document, and a search embeds the query once with EmbeddingPurpose::Query and compares locally. An LLM provider returns false: nothing is indexed, and each search sends the query and the candidates’ text to rank(). Whichever you choose, the other method throws ProviderException( ProviderErrorKind::Unsupported, … ). A custom embedding provider gets the index, the background indexing and related episodes by meaning exactly as the built-ins do.

The types the methods use, all in BenecasterAiSearch\Provider:

  • EmbeddingPurpose, a string-backed enum: Document ('document', an episode’s text being indexed) and Query ('query', a search).
  • RankCandidate, with read-only int $id (map it back to the candidate) and string $text (what the model reads: title, description, show notes, and a transcript only when Transcription returned one).
  • ProviderException( ProviderErrorKind $kind, string $message, ?int $http_status = null, ?int $retry_after = null ), thrown for every failure. $retry_after is the provider’s Retry-After in seconds on a 429, when it sent one.
  • ProviderErrorKind, a string-backed enum: Auth (the key was refused), RateLimited (429), InvalidRequest (another 4xx), Unavailable (no answer, a timeout or a 5xx), InvalidResponse (an answer that could not be read, including the wrong number or shape of vectors) and Unsupported (the method does not exist for this architecture). Only RateLimited and Unavailable are retried, with backoff.

Methods

Method Visibility Since Description
slug(): string Public — Your provider's slug, the same as its key in benecaster_ai_search_providers: 1–32 characters of a-z, 0-9, _ or -. A provider whose slug() differs from its entry's key fails to load.
label(): string Public — The translated name for the provider dropdown on Settings → AI Search.
supports_indexing(): bool Public — true for an embedding provider, which builds an index; false for an LLM provider, which ranks each search. The one branch between the two architectures.
model_id(): string Public — Names the model whose output you return, unique across providers: {slug}/{model}, for example localembed/mini-v1. Stored on every index row, and vectors are compared only within one model_id(), so changing it re-indexes every episode in the background. For an LLM provider it names the ranking model and is stored nowhere.
max_batch_size(): int Public — The most texts one embed() call accepts, at least 1. The add-on never sends more in one call. An LLM provider returns 1.
max_input_tokens(): int Public — The most tokens of one text your provider reads, at least 1. The add-on cuts longer text into pieces under this limit, so nothing is cut off unseen. For an LLM provider, the most of one candidate's text worth sending.
embed( array $texts, EmbeddingPurpose $purpose ): array Public — Embeds a non-empty list of at most max_batch_size() strings and returns one vector (a list of floats) per text, in the order given, 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. An LLM provider throws ProviderErrorKind::Unsupported.
rank( string $query, array $candidates ): array Public — Ranks a list of RankCandidate against the searcher's words and returns candidate ids, most relevant first, each at most once. Return only the candidates you judge relevant; an empty list is a valid answer. Rank every candidate you are given: the add-on decides access per result afterwards. An embedding provider throws ProviderErrorKind::Unsupported.
verify_credentials(): void Public — The Test connection check on Settings → AI Search: one cheap call that succeeds only with a valid key. Throw ProviderException with ProviderErrorKind::Auth when the key is refused.

Notes

Throw ProviderException for every failure. Its message is shown to the podcaster on Test connection and written to the PHP error log otherwise, never to a subscriber, so never put the key in it. A visitor never sees your message: the search box says only that search isn't available right now.

Only one embed() for the query, or one rank(), is ever called while a visitor waits; indexing and related episodes run in the background. Use wp_safe_remote_post() with a timeout. Walkthrough: Add your own search provider to AI Search.