AISearchProviderInterface
BenecasterAiSearch\Provider\AISearchProviderInterface
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) andQuery('query', a search).RankCandidate, with read-onlyint $id(map it back to the candidate) andstring $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_afteris 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) andUnsupported(the method does not exist for this architecture). OnlyRateLimitedandUnavailableare 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.