zoom-search 0.1.4

Two-phase AI-assisted search library with zoom-out and zoom-in workflows

Zoom Search

Better Answers, Bounded Extra Cost Direct search baseline vs Zoom Search workflow
Useful results	Answer quality	Extra budget
1-5 -> 4-12 more good sources	2.0-7.2 -> 7.8-8.7 stronger final answers	+5.9s to +12.2s +2.3k to +5.1k tokens

Quickstart · Providers · Streaming · Agents · Benchmarks · Advanced Configuration

Zoom Search is a search and evidence tool for AI agents. It helps agents rewrite search questions, gather broader web evidence, zoom into high-value source domains, and return sourced answers with metrics.

It is built for agentic applications that need stronger source discovery, traceability, and answer grounding than a single search call.

Why Zoom Search

• Agent search tool: expose structured answers, sources, warnings, and metrics for tool-calling agents.
• Better evidence gathering: rewrite agent questions into stronger search variants.
• Source-domain zoom-in: search broadly first, then focus on high-value domains.
• Traceable outputs: preserve source domains, duplicate provenance, warnings, and runtime metrics.
• MCP/LangGraph ready: use Zoom Search through MCP or LangGraph integrations.
• Provider-flexible: use built-in engines or custom OpenAI-compatible and native HTTP providers.

Install

pip install zoom-search

Quickstart

Run a deterministic local demo without API keys:

import asyncio

from zoom_search import search


async def main() -> None:
    response = await search(
        question="What hotels in Shenzhen have rooms with exercise bikes?",
        demo_mode=True,
        output_mode="answer_with_sources",
        seed=7,
    )
    print(response.answer)
    print(response.results)


asyncio.run(main())

Real Provider Example

import asyncio

from zoom_search import search


async def main() -> None:
    response = await search(
        question="Which vector databases support hybrid search and metadata filtering for Python apps?",
        llm_engine="gemini",
        llm_model="gemini-2.5-flash",
        llm_api_key="YOUR_GEMINI_API_KEY",
        search_engine="tavily",
        search_api_key="YOUR_TAVILY_API_KEY",
        output_mode="answer_with_sources",
    )
    print(response.answer)
    print(response.search_context)


asyncio.run(main())

Common Usage

Return only normalized search results:

response = await search(
    question="Latest SQLite performance improvements",
    demo_mode=True,
    output_mode="results_simple",
)

Use recent conversation context:

response = await search(
    question="What about hotels with in-room fitness equipment?",
    previous_conversation=[
        "I am planning a business trip to Shenzhen.",
        "I prefer hotels with wellness facilities.",
    ],
    demo_mode=True,
    output_mode="answer_with_sources",
)

Streaming

import asyncio

from zoom_search import astream_search


async def main() -> None:
    async for event in astream_search(
        question="What hotels in Shenzhen have rooms with exercise bikes?",
        demo_mode=True,
        output_mode="answer_with_sources",
        seed=7,
    ):
        if event.type == "answer_delta":
            print(event.text, end="")
        if event.type == "completed":
            print(event.response.request_id)


asyncio.run(main())

Benchmarks

Historical evaluations compare direct search against the Zoom Search agent workflow, showing better useful result coverage and stronger final answers with bounded extra time and token cost.

Case	Good results	Answer quality	Extra time	Extra tokens
Playwright authentication reuse	5 -> 7	6.6 -> 8.7	+5.89s	+2,324
GitHub Actions secrets inherit	1 -> 4	2.0 -> 7.8	+8.93s	+2,936
Hydrangea pruning comparison	4 -> 12	7.2 -> 8.4	+12.17s	+5,073

See the full benchmark notes in docs/benchmarks.md.

Examples

Runnable examples are available in the examples/ directory:

python examples/demo_mode.py
python examples/streaming.py
python examples/conversation_history.py

For MCP and LangGraph tool usage, see docs/agent-integration.md.

Documentation

• Advanced configuration: https://github.com/goofrey/zoom-search/blob/main/docs/advanced-configuration.md
• Agent integration: https://github.com/goofrey/zoom-search/blob/main/docs/agent-integration.md
• Development checks: https://github.com/goofrey/zoom-search/blob/main/docs/development.md
• Benchmarks: https://github.com/goofrey/zoom-search/blob/main/docs/benchmarks.md

License

Zoom Search is open source under the MIT License.