zoom-search 0.1.5

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 · Agent Tool · 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())

Agent Tool Example

Install the MCP extra:

pip install "zoom-search[mcp]"

Add Zoom Search to your MCP client:

{
  "mcpServers": {
    "zoom-search": {
      "command": "zoom-search-mcp",
      "env": {
        "ZOOM_SEARCH_LLM_ENGINE": "gemini",
        "ZOOM_SEARCH_LLM_MODEL": "gemini-2.5-flash",
        "ZOOM_SEARCH_LLM_API_KEY": "YOUR_GEMINI_API_KEY",
        "ZOOM_SEARCH_SEARCH_ENGINE": "tavily",
        "ZOOM_SEARCH_SEARCH_API_KEY": "YOUR_TAVILY_API_KEY"
      }
    }
  }
}

Your agent can then call the zoom_search tool with a question argument:

{
  "question": "Which vector databases support hybrid search and metadata filtering for Python apps?",
  "output_mode": "answer_with_sources"
}

The tool returns sourced answers, source-domain zoom-in, warnings, and runtime metrics.

Or wrap it as a LangGraph/LangChain tool:

import os

from langchain.tools import tool

from zoom_search import search


@tool
async def zoom_search_evidence(query: str) -> dict:
    response = await search(
        question=query,
        llm_engine=os.environ["ZOOM_SEARCH_LLM_ENGINE"],
        llm_model=os.environ["ZOOM_SEARCH_LLM_MODEL"],
        llm_api_key=os.environ["ZOOM_SEARCH_LLM_API_KEY"],
        search_engine=os.environ["ZOOM_SEARCH_SEARCH_ENGINE"],
        search_api_key=os.environ["ZOOM_SEARCH_SEARCH_API_KEY"],
        output_mode="answer_with_sources",
    )
    return response.to_dict()

See docs/agent-integration.md for MCP client configuration and provider environment variables.

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.

Runnable examples for demo mode, streaming, conversation history, and LangGraph are available in the examples/ directory.

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.