search-cli (Python)

Python port of search-cli. Async library for querying multiple search providers in parallel with result deduplication.

Requirements

• Python 3.11+

Installation

pip install -e .

# With dev dependencies (pytest, respx)
pip install -e ".[dev]"

Configuration

Set API keys as environment variables. Only providers with configured keys are used.

Usage

import asyncio
from search_cli import search, Mode

async def main():
    # General web search
    response = await search("python asyncio tutorial")
    for r in response.results:
        print(r.title, r.url)

    # News search
    response = await search("AI news", mode=Mode.NEWS, count=10)

    # Deep search (maximum coverage)
    response = await search("quantum computing", mode=Mode.DEEP)

    # JSON output
    print(response.model_dump_json(indent=2))

asyncio.run(main())

Modes

Advanced: Manage context lifecycle

from search_cli import search, Mode, SearchContext, AppConfig

async def main():
    # Reuse a single httpx client across multiple searches
    async with SearchContext(config=AppConfig()) as ctx:
        r1 = await search("query one", ctx=ctx)
        r2 = await search("query two", mode=Mode.NEWS, ctx=ctx)

Public API

Architecture

src/search_cli/
├── __init__.py          # Public exports
├── enums.py             # Mode enum
├── models.py            # Pydantic models (SearchResult, SearchResponse, etc.)
├── config.py            # ApiKeys + AppConfig (pydantic-settings, env vars)
├── context.py           # SearchContext (httpx.AsyncClient lifecycle)
├── engine.py            # Parallel search orchestration, URL dedup
├── errors.py            # SearchError hierarchy
└── providers/
    ├── __init__.py      # Registry: PROVIDERS_FOR_MODE, build_providers()
    ├── base.py          # BaseProvider ABC (resolve_key, retry_request)
    ├── brave.py         # Brave Search API
    ├── serper.py        # Serper (Google Search) API
    ├── exa.py           # Exa neural search API
    ├── jina.py          # Jina search API
    ├── tavily.py        # Tavily search API
    └── perplexity.py    # Perplexity chat completions API

How it works

1. search() receives a query + mode
2. providers_for_mode() selects providers mapped to that mode, filtered to those with configured API keys
3. asyncio.TaskGroup launches all provider searches in parallel, each with per-provider timeout
4. Individual provider failures are caught and recorded (other providers continue)
5. Results are deduplicated by normalized URL (first occurrence wins)
6. SearchResponse is returned with results + metadata (timing, provider stats)

Testing

pytest -v

23 tests covering models, engine, and all 6 providers. All tests use respx for HTTP mocking — no real API keys required.

Dependencies

Dev only