agentic-search

#	Script	Intent
1	scripts/agentic_search.py	Research a topic — AI-reasoned answer with citations
2	scripts/agentic_fetch.py	Full page → Markdown, no summarization
3	scripts/agentic_map.py	Enumerate URLs under a site (Tavily-only)
4	scripts/agentic_extract.py	Verbatim title + 2–4 quotes from a URL
5	scripts/agentic_rank.py	Rerank session sources by a refined query
6	scripts/agentic_get_sources.py	Retrieve or list cached sessions

How to invoke

All scripts use PEP 723 inline deps — always invoke via uv run. Allow up to 3 minutes per call.

uv run scripts/agentic_search.py --query "..." [--extra-sources N] [--auto-fetch-top N] [--platform "..."]
uv run scripts/agentic_fetch.py --url "..." [--engine auto|tavily|firecrawl|grok]
uv run scripts/agentic_map.py --url "..." [--instructions "..."] [--limit N]
uv run scripts/agentic_extract.py --url "..." [--session-id S]
uv run scripts/agentic_rank.py --query "..." --session-id S
uv run scripts/agentic_get_sources.py --list | --session-id S

Session workflow

agentic_search generates a session_id persisted to disk — the connective tissue for composing steps:

agentic_search → session_id
     ├─→ agentic_rank --session-id S --query Q     (rerank in place; mutates session)
     ├─→ agentic_extract --session-id S --url U    (append verbatim quotes)
     └─→ agentic_get_sources --session-id S        (inspect full session)

Sessions survive between invocations but may be cleared on OS reboot.

Operating discipline

Load the relevant reference before composing a non-trivial query — don't load all four upfront.

• references/search-discipline.md — two-pass methodology, citation contract, time-context heuristic. Read for research tasks.
• references/fetch-fidelity.md — engine trade-offs, fidelity guarantees, when not to fetch. Read before presenting extracted content.
• references/extract-and-rank.md — extract vs fetch, when to rank, session composition patterns. Read for multi-step workflows.
• references/provider-quirks.md — env vars, provider schemas, retry policy, debugging. Read when configuring or debugging.

Failure modes

• No GROK_API_KEY / GROK_API_URL → config error on any Grok-using script.
• agentic_fetch --engine auto total failure → retry with --engine grok or fall back to built-in WebFetch.
• agentic_map without TAVILY_API_KEY → hard exit.
• agentic_rank --session-id S session expired → re-run agentic_search.
• sources_count: 0 with non-empty content → Grok used training data; check providers_used (grok-web-search = real citations, grok = heuristic fallback).