{ "markdown": "
\n

Zero-API-Key Web Search

\n

Search infrastructure for AI agents.

\n

Free by default. MCP-ready. LLM-context aware. Production-grade when you opt in.

\n\n [![PyPI](https://img.shields.io/pypi/v/zero-api-key-web-search?label=pypi&cache=20260503)](https://pypi.org/project/zero-api-key-web-search/)\n [![Python](https://img.shields.io/pypi/pyversions/zero-api-key-web-search?cache=20260503)](https://python.org)\n [![MCP](https://img.shields.io/badge/MCP-Ready-0f766e.svg)](https://modelcontextprotocol.io/)\n [![Tests](https://img.shields.io/badge/tests-98%20passing-22c55e.svg)](./tests)\n [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n

\n \"AI-agent\n
\n\n---\n\n## What It Does\n\nZero-API-Key Web Search is a local-first, MCP-native search and evidence-verification toolkit for AI agents. It gives your agent live web search, LLM-optimized context extraction, claim verification with weighted evidence scoring, and citation-ready evidence reports — all without requiring an API key by default.\n\nThe verification model (`evidence-aware-heuristic-v3`) classifies sources as supporting, conflicting, or neutral using keyword overlap, domain-quality heuristics, freshness, and optional page-aware rescoring. This project does not perform fact-level proof or logical entailment; it is a signal amplifier for agent grounding decisions.\n\n## 30-Second Setup\n\n```bash\npip install zero-api-key-web-search\n\n# Search the web — no API key needed\nzero-search \"Python 3.13 release\" --json\n\n# Build citation-ready LLM context\nzero-context \"Python 3.13 stable release\" --goggles docs-first\n\n# Read a page\nzero-browse \"https://docs.python.org/3/whatsnew/\" --json\n\n# Verify a claim\nzero-verify \"Python 3.13 is the latest stable release\" --deep --json\n\n# Full evidence report\nzero-report \"Python 3.13 stable release\" \\\n --claim \"Python 3.13 is the latest stable release\" --deep --json\n```\n\nLegacy CLI aliases (`search-web`, `browse-page`, `verify-claim`, `evidence-report`) also work.\n\n## Your Agent Gets\n\n| Agent job | Command | What the agent gets |\n| --- | --- | --- |\n| Ground an answer | `zero-context \"FastAPI lifespan docs\"` | compact Markdown context with citations |\n| Verify a claim | `zero-verify \"Python 3.13 is the latest stable release\"` | supported / contested / likely false verdict |\n| Build an evidence report | `zero-report \"AI regulation news\"` | rationale, source digest, warnings, next steps |\n| Read a blocked page | `zero-browse \"https://geo-restricted-site.com\"` | page content, auto-unlocked if Web Unlocker is configured |\n| Search with a specific engine | `zero-search \"news\" --engine bing --type news` | Bing SERP results via Bright Data |\n| Serve an MCP client | `zero-mcp` | 8 tools for Claude Code, Cursor, Copilot, and any MCP-compatible runtime |\n\n

\n \"zero-context\n

\n\n## Provider Paths: Free to Production\n\nStart free, scale when you're ready. Every path works out of the box — no configuration required for the default.\n\n### Path 1: Free (Zero Configuration)\n\nWorks immediately after `pip install`. Uses DuckDuckGo — no API key, no account.\n\n```bash\nzero-search \"Python 3.13 release\" --json\n```\n\n### Path 2: Free Cross-Validated\n\nAdd a self-hosted SearXNG instance for dual-provider cross-validation — still free, no API key.\n\n```bash\n# Start SearXNG locally\n./scripts/start-searxng.sh\nexport ZERO_SEARCH_SEARXNG_URL=\"http://127.0.0.1:8080\"\n\nzero-search \"AI regulation\" --profile free-verified --json\n```\n\nOr with Docker Compose:\n\n```bash\ncp .env.searxng.example .env\ndocker compose -f docker-compose.searxng.yml up -d\n```\n\nFull guide: [docs/searxng-self-hosted.md](docs/searxng-self-hosted.md).\n\n### Path 3: Production SERP\n\n[Bright Data](https://get.brightdata.com/h21j9xz4uxgd) provides professional-grade search across 7 engines with structured results, LLM-friendly markdown output, AI Overviews, mobile device emulation, and geo-targeting for 195 countries. New users get 5,000 free credits.\n\n```bash\n# Interactive setup wizard — tests your key and zone\nzero-setup\n\n# Or set environment variables directly\nexport ZERO_SEARCH_BRIGHTDATA_API_KEY=\"your-key\"\nexport ZERO_SEARCH_BRIGHTDATA_ZONE=\"serp_api1\"\n\n# Search across different engines\nzero-search \"news\" --provider brightdata --engine google --type news --region us-en --json\nzero-search \"news\" --provider brightdata --engine bing --type news --region gb-en --json\nzero-search \"news\" --provider brightdata --engine yandex --region ru-ru --json\n```\n\nSupported engines: `google`, `bing`, `duckduckgo`, `yandex`, `baidu`, `yahoo`, `naver`.\n\n### Path 4: Production + Web Unlocker\n\nAccess blocked, CAPTCHA-protected, or geo-restricted pages. Uses the same Bright Data API key — just create a Web Unlocker zone.\n\n```bash\n# Setup wizard handles zone creation guidance\nzero-setup\n\n# Or set the zone manually\nexport ZERO_SEARCH_BRIGHTDATA_API_KEY=\"your-key\"\nexport ZERO_SEARCH_BRIGHTDATA_ZONE=\"serp_api1\"\nexport ZERO_SEARCH_BRIGHTDATA_UNLOCKER_ZONE=\"web_unlocker1\"\n\n# Browse automatically falls back to Web Unlocker on 403/429\nzero-browse \"https://protected-site.com/article\" --json\n\n# Or force Web Unlocker\nzero-browse \"https://protected-site.com/article\" --use-unlocker always --json\n```\n\n### Path 5: Maximum Evidence\n\nAll providers active — DDGS, SearXNG, Bright Data, and Web Unlocker — for the strongest cross-validated evidence.\n\n```bash\nexport ZERO_SEARCH_BRIGHTDATA_API_KEY=\"your-key\"\nexport ZERO_SEARCH_SEARXNG_URL=\"http://127.0.0.1:8080\"\n\nzero-report \"AI regulation news\" --profile max-evidence --deep --json\n```\n\n## Provider Profiles\n\n| Profile | Providers | Best for |\n| --- | --- | --- |\n| `free` | `ddgs` | Zero-setup local search |\n| `free-verified` | `ddgs`, `searxng` | Free cross-validation |\n| `production` | `brightdata` | Production reliability and geo-targeting |\n| `production-unlock` | `brightdata`, `web_unlocker` | Production SERP + access blocked pages |\n| `max-evidence` | `ddgs`, `searxng`, `brightdata` | Maximum provider diversity |\n\n```bash\nzero-search \"FastAPI lifespan docs\" --profile free-verified --goggles docs-first\nzero-context \"FastAPI lifespan docs\" --profile free --goggles docs-first\nzero-report \"AI regulation news\" --profile production-unlock --json\n```\n\n## MCP Server\n\nWorks with Claude Code, Cursor, Copilot, and any MCP-compatible agent:\n\n```json\n{\n \"mcpServers\": {\n \"zero-api-key-web-search\": {\n \"command\": \"zero-mcp\"\n }\n }\n}\n```\n\nFor npm/npx-based MCP launchers:\n\n```json\n{\n \"mcpServers\": {\n \"zero-api-key-web-search\": {\n \"command\": \"npx\",\n \"args\": [\"zero-api-key-web-search\", \"zero-mcp\"]\n }\n }\n}\n```\n\nEight tools exposed:\n\n| Tool | What it does |\n| --- | --- |\n| `list_providers` | Show provider status, profiles, goggles, and setup hints |\n| `search_web` | Live web search with engine selection and region targeting |\n| `llm_context` | Compact, citation-ready Markdown context for LLMs |\n| `browse_page` | Fetch and extract page content (auto-unlocks blocked pages) |\n| `verify_claim` | Evaluate whether a claim is supported, contested, or under-evidenced |\n| `evidence_report` | Full evidence report with rationale, source digest, and next steps |\n| `clear_cache` | Clear the response cache |\n| `setup_providers` | Check provider status, test API keys, and get setup instructions |\n\n### MCP Tool Parameters\n\n`search_web` key parameters:\n- `query` (required) — search query\n- `type` — `text`, `news`, `images`, `videos`, `books` (default: `text`)\n- `engine` — `google`, `bing`, `duckduckgo`, `yandex`, `baidu`, `yahoo`, `naver` (Bright Data only)\n- `region` — region code, e.g. `us-en`, `zh-cn`, `wt-wt` (default: `wt-wt`)\n- `profile` — provider profile name\n- `goggles` — built-in reranking preset\n\n`browse_page` key parameters:\n- `url` (required) — page URL\n- `format` — `markdown` or `text` (default: `markdown`)\n- `use_unlocker` — `auto` (default), `always`, or `never`\n- `max_chars` — max content length (default: 50000)\n\n`setup_providers` key parameters:\n- `test_brightdata_key` — test a Bright Data API key\n- `test_brightdata_zone` — SERP zone name (default: `serp_api1`)\n- `test_brightdata_unlocker_zone` — Web Unlocker zone name\n- `test_searxng_url` — test a SearXNG instance URL\n\n## Interactive Setup Wizard\n\nThe `zero-setup` command guides you through provider configuration, validates API keys and zones, and writes `.env` files:\n\n```bash\n# Interactive wizard\nzero-setup\n\n# Quick status check\nzero-setup --status\n\n# Test a Bright Data API key\nzero-setup --test-brightdata YOUR_API_KEY\n\n# Test a Bright Data Web Unlocker zone\nzero-setup --test-brightdata-unlocker YOUR_API_KEY --unlocker-zone web_unlocker1\n\n# Test a SearXNG instance\nzero-setup --test-searxng http://localhost:8080\n```\n\n## Bright Data Integration\n\n[Bright Data](https://get.brightdata.com/h21j9xz4uxgd) powers two production-grade capabilities:\n\n### SERP API — Multi-Engine Search\n\nProfessional-grade search across 7 engines with structured results, LLM-friendly markdown output, AI Overviews, mobile device results, and geo-targeting for 195 countries.\n\n```python\nfrom zero_api_key_web_search.providers import BrightDataProvider\n\nprovider = BrightDataProvider(api_key=\"your-key\", zone=\"serp_api1\")\n\n# Google (default)\nresults = provider.search(\"Python 3.13\", search_type=\"text\", region=\"us-en\")\n\n# Bing, Yandex, Baidu, Yahoo, Naver, DuckDuckGo\nresults = provider.search(\"AI regulation\", search_type=\"news\", engine=\"bing\")\n\n# Markdown output for LLM consumption\nresults = provider.search(\"climate change\", data_format=\"markdown\")\n```\n\n### Web Unlocker — Access Blocked Pages\n\nAutomatically handles CAPTCHAs, anti-bot protection, IP rotation, and JavaScript rendering. Access pages that return 403, require login, or are geo-restricted.\n\n```python\nfrom zero_api_key_web_search.providers import WebUnlockerProvider\n\nprovider = WebUnlockerProvider(api_key=\"your-key\", zone=\"web_unlocker1\")\n\n# Get page content as markdown\nresult = provider.unlock(\"https://protected-site.com/article\", data_format=\"markdown\")\nprint(result[\"content\"]) # Clean markdown of the page\n\n# With country targeting\nresult = provider.unlock(\"https://geo-restricted.com\", country=\"us\")\n```\n\n### Auto-Fallback in browse_page\n\nWhen Web Unlocker is configured, `browse_page` automatically retries blocked pages (403/429) through the unlocker:\n\n```python\nfrom zero_api_key_web_search.browse_page import browse\n\n# Auto-fallback (default) — try direct, then unlocker on 403/429\nresult = browse(\"https://protected-site.com/article\")\n\n# Always use Web Unlocker\nresult = browse(\"https://protected-site.com/article\", use_unlocker=True)\n\n# Never use Web Unlocker\nresult = browse(\"https://protected-site.com/article\", use_unlocker=False)\n```\n\nNew Bright Data users can sign up with 5,000 free credits: \n\n## Why This Over a Plain Search Wrapper?\n\n| Feature | Plain search | Zero-API-Key Web Search |\n| --- | --- | --- |\n| Live search results | ✅ | ✅ |\n| Multi-engine SERP (7 engines) | ❌ | ✅ (Bright Data) |\n| News / images / videos / books | ❌ | ✅ |\n| Region & time filtering | ❌ | ✅ |\n| Blocked page unlocking | ❌ | ✅ (Web Unlocker) |\n| Full-page text extraction | ❌ | ✅ |\n| Claim verification with evidence scores | ❌ | ✅ |\n| Supporting vs. conflicting evidence | ❌ | ✅ |\n| Citation-ready evidence reports | ❌ | ✅ |\n| Dual-provider cross-validation | ❌ | ✅ |\n| API key required | Often | **Never by default** |\n| Cost | Sometimes | **Free by default** |\n\n## How Verification Works\n\n`zero-verify` uses the **evidence-aware heuristic v3** model:\n\n1. Search for the claim across available providers\n2. Score each source on keyword overlap, source quality, freshness\n3. Classify as supporting, conflicting, or neutral\n4. Optionally fetch top pages for deeper page-aware analysis\n5. Render a verdict with confidence and evidence breakdown\n\n| Verdict | Meaning |\n| --- | --- |\n| `supported` | Strong evidence, low conflict |\n| `likely_supported` | Leans positive, not decisive |\n| `contested` | Support and conflict both meaningful |\n| `likely_false` | Conflict strong, support weak |\n| `insufficient_evidence` | Too weak for any firmer verdict |\n\nThis is a heuristic evidence classifier, not a proof engine. See [docs/trust-model.md](docs/trust-model.md) for details and limitations, [docs/verification-model.md](docs/verification-model.md) for signal definitions, and [docs/benchmarks.md](docs/benchmarks.md) for regression results.\n\n## Built-in Goggles Presets\n\n| Goggles | Effect |\n| --- | --- |\n| `docs-first` | Boosts docs, API, support, release-note, and official-looking sources |\n| `research` | Boosts academic, institutional, paper, and study-oriented sources |\n| `news-balanced` | Boosts reporting/analysis signals and demotes low-context aggregators |\n\nYou can also pass a JSON file to `--goggles` with `boost_domains`, `block_domains`, `demote_domains`, and `boost_title_terms`.\n\nFull guide: [docs/agent-search-controls.md](docs/agent-search-controls.md).\n\n## Platform Support\n\n| Platform | Status | Entry point |\n| --- | --- | --- |\n| **CLI** | Ready | `zero-search`, `zero-context`, `zero-browse`, `zero-verify`, `zero-report`, `zero-setup` |\n| **MCP** | Ready | `zero-mcp` |\n| **Claude Code** | Ready | `.claude/skills/zero-api-key-web-search/SKILL.md` |\n| **Gemini** | Ready | `GEMINI.md` + `.gemini/SKILL.md` |\n| **Cursor** | Ready | `.cursor/rules/zero-api-key-web-search.md` |\n| **Copilot** | Ready | `.github/copilot/instructions.md` |\n| **Codex** | Ready | `.codex/SKILL.md` |\n| **Continue** | Ready | `.continue/skills/zero-api-key-web-search/SKILL.md` |\n| **Manus** | Ready | Root `SKILL.md` + `docs/manus.md` |\n| **Kiro** | Ready | `.kiro/steering/zero-api-key-web-search.md` |\n| **OpenClaw** | Ready | `zero_api_key_web_search/skills/SKILL.md` |\n\n## Architecture\n\n```\nzero_api_key_web_search/\n core.py # UltimateSearcher — search, verify, report engine\n browse_page.py # Readability-style page extraction + Web Unlocker fallback\n mcp_server.py # MCP server (8 tools)\n provider_setup.py # Interactive setup wizard (zero-setup)\n cache.py # Response caching\n transport.py # SSL/TLS helpers\n search_web.py # CLI: zero-search\n context.py # CLI: zero-context\n verify_claim.py # CLI: zero-verify\n evidence_report.py # CLI: zero-report\n providers/\n base.py # SearchProvider protocol (sync + async)\n ddgs.py # DuckDuckGo provider (free, zero-config)\n searxng.py # SearXNG provider (free, self-hosted)\n brightdata.py # Bright Data SERP — 7 engines, markdown, AI Overviews\n web_unlocker.py # Bright Data Web Unlocker — blocked/CAPTCHA/geo pages\n skills/\n SKILL.md # Bundled OpenClaw skill\n```\n\nKey engineering features:\n\n- **Circuit breaker**: Trips after 3 consecutive provider failures, auto-resets after 60s\n- **Async support**: `asearch()` for concurrent provider calls via `asyncio.gather`\n- **Auto-fallback**: `browse_page` retries 403/429 pages via Web Unlocker automatically\n- **Multi-engine SERP**: 7 search engines (Google, Bing, DuckDuckGo, Yandex, Baidu, Yahoo, Naver)\n- **Structured logging**: Configurable logging at search/verify/report entry points\n- **Readability heuristic**: Semantic HTML5 + ARIA roles + text density scoring\n- **Baseline comparison**: Majority-vote and keyword-count baselines in reports\n- **Sub-claim decomposition**: Targeted sub-queries for independent evidence gathering\n\n## Installation\n\n```bash\npip install zero-api-key-web-search\n```\n\nPython 3.10+ required. No API keys, no accounts, no configuration needed.\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npython -m pytest tests/ -q # 98 tests\nruff check zero_api_key_web_search/ tests/\npyright zero_api_key_web_search/ # 0 errors\ncoverage report --fail-under=80 # 85% coverage\n```\n\n## Evidence Report Example\n\n```json\n{\n \"verdict\": \"contested\",\n \"confidence\": \"MEDIUM\",\n \"executive_summary\": \"Evidence is split...\",\n \"verdict_rationale\": [\"Source A supports...\", \"Source B contradicts...\"],\n \"coverage_warnings\": [\"Single-provider evidence path.\"],\n \"source_digest\": [\n {\"title\": \"...\", \"url\": \"...\", \"classification\": \"supporting\", \"evidence_strength\": 3}\n ],\n \"next_steps\": [\"Add a second provider for cross-validation.\"]\n}\n```\n\n## Verification for Ecosystem Reviewers\n\n1. `zero-report \"Python 3.13 stable release\" --claim \"Python 3.13 is the latest stable release\" --deep --json`\n2. [docs/ecosystem-readiness.md](docs/ecosystem-readiness.md)\n3. [docs/gemini-submission-checklist.md](docs/gemini-submission-checklist.md)\n4. [docs/trust-model.md](docs/trust-model.md)\n\n## License\n\nMIT License.", "bytes": 16891, "sha": "b6e83b28ec1d7f0bd19453f0d839ac89d20a59b03a5c4c49f8255c0414d3eb28", "repo_slug": "wd041216-bit/zero-api-key-web-search", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_wd041216_bit_zero_api_key_web_search_ffae795f/readme" }