Podcast Discovery

Do not stop at metadata, search summaries, or candidate lists if a valid link can be constructed.

Link Templates

Episode (contentScope = podcast-episode): https://wherever.audio/listen?rssUrl={rss_url}&itemGuid={guid}&fallbackLink={fallback}

Show (contentScope = podcast-show): https://wherever.audio/show?rssUrl={rss_url}

All {placeholder} values must be URL-encoded.

Action Policy: Link-First, Ask-Last

Default behavior is to execute and return a link in the same response.

Only ask a follow-up question when one of these is true:

• You cannot determine whether the user wants a show vs episode.
• Clawsica returns no plausible show/RSS result after retries.
• Multiple episode candidates are similarly strong and no clear best match exists.

If none of the above apply, do not ask for confirmation. Return the link.

Token Budget Policy

• Run local tooling first and send only compact result fields to the model.
• Never send raw RSS XML, full feed dumps, or large metadata blobs to the model.
• For episode matching, pass only top-ranked candidate rows needed for decision-making and link construction.

Workflow

Step 1 — Classify the query

Before searching, classify the user's query along two dimensions:

intentType — what kind of request?

• specific-podcaster — user names a host or show (e.g. "Lex Fridman", "Radiolab")
• specific-topic — user describes a topic or guest (e.g. "Geoffrey Hinton interview about AI")
• discovery — broad exploration (e.g. "best science podcasts", "podcasts about space")

contentScope — what are they looking for?

• podcast-show — a show/feed (e.g. "find the Radiolab podcast")
• podcast-episode — a specific episode (e.g. "the Radiolab episode about colors")

Step 2 — Resolve the show

If intentType is specific-podcaster (show name is known): Go directly to Clawsica (step 3). The query likely contains the show title.

If intentType is specific-topic or discovery (show name is unknown): Search the web first to discover likely podcast titles, then proceed to Clawsica with those titles.

Step 3 — Clawsica show search

Search for podcast shows using the public Clawsica endpoint. This returns show metadata including RSS feed URLs.

curl -s "https://clawsica.wherever.audio/p?q=radiolab"

Returns a JSON array of show objects. Each object includes a url field containing the RSS feed URL.

Important: Only use the url field from Clawsica results as the RSS URL. Do NOT substitute web page URLs, Apple Podcasts links, Spotify links, or any other URL — Wherever.Audio only understands RSS feed URLs. If Clawsica returns no results and you cannot obtain a definitive RSS feed URL, tell the user you were unable to find the podcast rather than guessing with a non-RSS URL.

If Clawsica returns no results, try alternate spellings or broader terms. See references/CLAWSICA_API.md for the full API reference.

Step 4 — Branch by contentScope

If contentScope is podcast-show: Construct a show link using the RSS URL from step 3 and present it immediately. Do not ask for additional confirmation. Done.

Example: https://wherever.audio/show?rssUrl=https%3A%2F%2Ffeeds.feedburner.com%2Fradiolab

If contentScope is podcast-episode: Continue to step 5.

Step 5 — Run local feed tooling (required for episode lookup)

For episode lookup, use local tooling instead of manual XML parsing:

python scripts/search_feed_episodes.py --mode search --rss-url "https://feeds.feedburner.com/radiolab" --query "space stories" --limit 5

Optional semantic rerank:

python scripts/search_feed_episodes.py --mode search --rss-url "https://feeds.feedburner.com/radiolab" --query "space stories" --limit 5 --semantic

Compact search output contract:

• top-level keys: mode, rssUrl, query, semanticUsed, candidateCount, candidates
• candidate keys: guid, title, pubDate, fallbackLink, score

Use these candidate rows to select the best episode. Do not return feed-level metadata unless explicitly requested.

Selection policy:

• Auto-pick when the top score is clearly stronger than the second candidate.
• If top candidates are near-tied, ask one disambiguation question.

Step 6 — Construct the episode link

Build a wherever.audio episode link using values from the selected search candidate:

• rss_url — the feed URL from step 3
• guid — candidate guid
• fallback — candidate fallbackLink

Example: