Skip to main content

Search a podcaster’s catalog from the admin, as the AI Search production panel does

Premium Intermediate AI Search

Search a podcaster’s whole back catalog by meaning from your own admin tool, or keep a record of the podcaster’s own lookups, using the route behind the AI Search production panel.

The production panel is a side panel beside every Benecaster admin screen (see Open your own panel beside every Benecaster screen with a shortcut), declared with id ai-search-backend, scope any_show and the shortcut alt+shift+s (Option+Shift+S on a Mac). Its slot is BenecasterShellPanel_ai-search-backend. It is closed on every admin load until the podcaster opens it.

GET /wp-json/benecaster-ai-search/v1/panel/search?q={query}&show_ids={id},{id} is the panel’s search. Admin only: manage_options, through benecaster_rest_permission_admin(), with the X-WP-Nonce header.

  • show_ids is a comma-separated list. Each show is checked again: one with AI Search switched off is dropped silently, and with none left (or AI Search on for no show at all) the answer is 403 benecaster_ai_search_not_active.
  • q is 2 to 200 characters after trimming, or 400 benecaster_ai_search_query_invalid.
  • Not a visitor’s search. No per-visitor rate limit, and it is never counted toward the daily limit on paid searches, nor stopped by it, though each search that reaches the provider is still billed to the podcaster. No access check per result and no result_visibility: every published episode of the searched shows can be returned, members-only ones included, and a transcript match always counts.
  • With an embedding provider the query is sent once however many shows are searched; with Anthropic each show’s episode list is ranked by its own call.
  • The answer is 200 { results: [ { id, show_id, show_title, title, episode_number, season_number, date, excerpt, excerpt_source } ], unavailable, reason }, best first across all the shows, at most 20.
    • episode_number and season_number are the episode’s own numbers, null when not set; date is the publish date in the site’s date format.
    • excerpt is one line (about 140 characters) of the content that matched: the sentence sharing most of the search’s words, from the piece of text that scored best. excerpt_source says where it came from: episode (title, description, show notes), transcript, or '' with no text. A transcript line is quoted only for a user benecaster_user_can_see_transcript() allows (true for anyone who can edit the episode); otherwise, or once the transcript is Hidden, the line comes from the episode’s own text. With Anthropic the line is always from the episode’s own text. Building the excerpt calls no provider.
    • unavailable is true with reason not_configured (no provider or key saved) or failed (a provider call failed; the results are whatever was ranked before it). The provider’s own message goes to the PHP error log only. reason is '' otherwise.
    • Fields may be added to a result in later versions; none will be removed.
  • guests, with the Guest Manager add-on: [ { id, name, title, organization, matched, profile_url, record_url, appearance_count, appearances: [ { id, show_id, show_title, title, date } ] } ], at most 10.
    • Read from Guest Manager’s whole roster (benecaster_guest_manager_get_guests() and benecaster_guest_manager_get_guest_episodes()), so a guest on no published episode of the searched shows yet is listed too, with appearance_count 0. [] when Guest Manager is off on every searched show.
    • matched says why: name, organization or title (the search is part of that field, or the whole field is inside the search at word boundaries; letter case, accents and punctuation ignored; at least 3 characters either way), in that order, each A to Z by name; then bio (by its words, whole words of four letters or more, and with OpenAI, Google Gemini or Cohere by meaning, at most three per search, each at least as close as the fifth-best episode result); then episodes, guests of the five best episode results, in the order of those episodes. Text matching calls no provider, so guests can be filled while unavailable is true.
    • appearances are the guest’s newest five episodes among the searched shows, newest first, and appearance_count counts them all. record_url is Guest Manager’s own address for the guest’s record ('' when it gives none); profile_url is their public page.
    • [] when nothing matches. Each show’s list is cached for up to an hour and cleared whenever a guest, an episode’s guests, an episode’s published state or an add-on’s per-show switch changes.

The hooks:

  • benecaster_ai_search_before_panel_search( string $query, int[] $show_ids ), with only the shows that passed the check. Fires before the provider is asked; not for a refused request.
  • benecaster_ai_search_panel_results( array $results, string $query, int[] $show_ids ): array filters the list above. Admin only, so it may add anything the podcaster may see.
  • benecaster_ai_search_panel_guest_results( array $guests, string $query, int[] $show_ids ): array filters the guests list above; a non-array becomes []. It runs after benecaster_ai_search_panel_results, and the episodes guests come from that filter’s output.
  • benecaster_ai_search_after_panel_search( string $query, int[] $show_ids, array $results ), with the filtered episode results (not the guests).

Code

<?php
// Keep a short history of the podcaster's own lookups, for the team's prep notes.
add_action( 'benecaster_ai_search_after_panel_search', function ( string $query, array $show_ids, array $results ): void {
    $log   = (array) get_option( 'my_prep_lookups', [] );
    $log[] = [ 'q' => $query, 'shows' => $show_ids, 'found' => array_column( $results, 'id' ), 'at' => gmdate( 'Y-m-d H:i:s' ) ];
    update_option( 'my_prep_lookups', array_slice( $log, -50 ), false );
}, 10, 3 );

View on GitHub →

Hooks Used

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