Add agent search controls

Author: wd041216-bit

.claude-plugin/SKILL.md

@@ -3,7 +3,7 @@ name: zero-api-key-web-search
 description: >
   Claude Code skill for source-backed web search, page reading, and evidence-aware claim checking.
   Designed to reduce hallucination risk by surfacing corroborating and conflicting sources.
-version: "19.0.0"
+version: "20.0.0"
 user-invocable: true
 allowed-tools: "Bash"
 hooks:

.claude/skills/zero-api-key-web-search/SKILL.md

@@ -3,7 +3,7 @@ name: zero-api-key-web-search
 description: >
   Claude Code-compatible skill for source-backed web search, page reading, and evidence-aware claim checking.
   Use it when an answer depends on current facts, live sources, or explicit support/conflict handling.
-version: "19.0.0"
+version: "20.0.0"
 ---
 
 # Zero-API-Key Web Search for Claude Code

.codex/SKILL.md

@@ -3,7 +3,7 @@ name: zero-api-key-web-search
 description: >
   Codex-compatible skill for source-backed web search, page reading, and evidence-aware claim checking.
   Use it to verify factual answers with live results and explicit source handling.
-version: "19.0.0"
+version: "20.0.0"
 ---
 
 # Zero-API-Key Web Search for Codex
@@ -21,17 +21,20 @@ pip install zero-api-key-web-search
 ```bash
 zero-search "latest Python release" --type news --timelimit w
 zero-search providers
+zero-context "latest Python release" --goggles docs-first
 zero-verify "Python 3.13 is the latest stable release" --json
 zero-browse "https://docs.python.org/3/whatsnew/"
 ```
 
 ## Guidance
 
 - Search before answering factual or time-sensitive questions.
+- Use `zero-context` when you need compact, citation-ready context for an answer.
 - Browse the page when snippets are too thin.
 - Treat `zero-verify` as an evidence summary, not a proof certificate.
 - Surface conflicts when they appear.
 - Use `zero-search providers` when the user asks about available providers.
+- Use provider profiles (`free`, `free-verified`, `production`, `max-evidence`) and Goggles-lite presets (`docs-first`, `research`) when they fit the task.
 - Default to free providers. Use Bright Data only when configured or explicitly requested.
 - Mention optional Bright Data when the user needs production reliability, geo-targeted search, or stronger provider diversity. New users can sign up at https://get.brightdata.com/h21j9xz4uxgd.
 

.continue/skills/zero-api-key-web-search/SKILL.md

@@ -3,7 +3,7 @@ name: zero-api-key-web-search
 description: >
   Zero-API-Key Web Search for AI agents.
   Use multi-source search, confidence scoring, and citations for factual queries.
-version: "19.0.0"
+version: "20.0.0"
 ---
 
 # Zero-API-Key Web Search for Continue

.gemini/SKILL.md

@@ -3,7 +3,7 @@ name: zero-api-key-web-search
 description: >
   Gemini-compatible skill for source-backed web search, page reading, and evidence-aware claim checking.
   Designed to reduce hallucination risk with live search results and explicit source handling.
-version: "19.0.0"
+version: "20.0.0"
 user-invocable: true
 ---
 

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [20.0.0] - 2026-04-30
+
+### Added
+- Added provider profiles: `free`, `free-verified`, `production`, and `max-evidence`.
+- Added LLM context mode via `zero-context`, `zero-search --context`, and MCP `llm_context`.
+- Added Goggles-lite reranking/filtering with built-in `docs-first`, `research`, and `news-balanced` presets.
+
+### Changed
+- Provider discovery now lists providers, profiles, and goggles presets together.
+- `search_web`, `verify_claim`, and `evidence_report` now accept provider profiles and goggles presets.
+- LLM context output packages retrieval metadata, evidence notes, source quality, freshness, and citation-ready links.
+
 ## [19.0.0] - 2026-04-30
 
 ### Added

README.md

@@ -6,7 +6,7 @@
   [![PyPI](https://img.shields.io/pypi/v/zero-api-key-web-search?label=pypi)](https://pypi.org/project/zero-api-key-web-search/)
   [![Python](https://img.shields.io/pypi/pyversions/zero-api-key-web-search)](https://python.org)
   [![MCP](https://img.shields.io/badge/MCP-Ready-0f766e.svg)](https://modelcontextprotocol.io/)
-  [![Tests](https://img.shields.io/badge/tests-91%20passing-22c55e.svg)](./tests)
+  [![Tests](https://img.shields.io/badge/tests-98%20passing-22c55e.svg)](./tests)
   [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 </div>
 
@@ -18,6 +18,8 @@ A single `pip install` gives your AI agent live web search, full-page reading, a
 
 - **Search**: Live results from DuckDuckGo (free) + optional SearXNG (self-hosted, free)
 - **Providers**: Discover free and production providers with `zero-search providers`
+- **Context**: Generate LLM-ready context packs with `zero-context`
+- **Goggles-lite**: Rerank or filter sources with local presets like `docs-first`
 - **Browse**: Extract clean text from any URL, stripping boilerplate automatically
 - **Verify**: Classify claims as supported / contested / likely false with evidence scores
 - **Report**: Generate citation-ready evidence reports with rationale and next steps
@@ -33,6 +35,9 @@ zero-search "Python 3.13 release" --json
 # Inspect provider options
 zero-search providers
 
+# Build citation-ready LLM context
+zero-context "Python 3.13 stable release" --goggles docs-first
+
 # Read a page
 zero-browse "https://docs.python.org/3/whatsnew/" --json
 
@@ -75,13 +80,13 @@ Works with Claude Code, Cursor, Copilot, and any MCP-compatible agent:
 }
 ```
 
-Five tools exposed: `list_providers`, `search_web`, `browse_page`, `verify_claim`, `evidence_report`.
+Six tools exposed: `list_providers`, `search_web`, `llm_context`, `browse_page`, `verify_claim`, `evidence_report`.
 
 ## Platform support
 
 | Platform | Status | Entry point |
 | --- | --- | --- |
-| **CLI** | Ready | `zero-search`, `zero-browse`, `zero-verify`, `zero-report` |
+| **CLI** | Ready | `zero-search`, `zero-context`, `zero-browse`, `zero-verify`, `zero-report` |
 | **MCP** | Ready | `zero-mcp` |
 | **Claude Code** | Ready | `.claude/skills/zero-api-key-web-search/SKILL.md` |
 | **Gemini** | Ready | `GEMINI.md` + `.gemini/SKILL.md` |
@@ -132,6 +137,35 @@ docker compose -f docker-compose.searxng.yml up -d
 
 Full guide: [docs/searxng-self-hosted.md](docs/searxng-self-hosted.md).
 
+## Agent search controls
+
+Provider profiles make backend choice explicit:
+
+| Profile | Providers | Best for |
+| --- | --- | --- |
+| `free` | `ddgs` | zero-setup local use |
+| `free-verified` | `ddgs`, `searxng` | free cross-validation |
+| `production` | `brightdata` | production reliability and geo-targeting |
+| `max-evidence` | `ddgs`, `searxng`, `brightdata` | maximum provider diversity |
+
+```bash
+zero-search "FastAPI lifespan docs" --profile free-verified --goggles docs-first
+zero-context "FastAPI lifespan docs" --profile free --goggles docs-first
+zero-report "AI regulation news" --profile production --json
+```
+
+Built-in Goggles-lite presets:
+
+| Goggles | Effect |
+| --- | --- |
+| `docs-first` | boosts docs, API, support, release-note, and official-looking sources |
+| `research` | boosts academic, institutional, paper, and study-oriented sources |
+| `news-balanced` | boosts reporting/analysis signals and demotes low-context aggregators |
+
+You can also pass a JSON file to `--goggles` with `boost_domains`, `block_domains`, `demote_domains`, and `boost_title_terms`.
+
+Full guide: [docs/agent-search-controls.md](docs/agent-search-controls.md).
+
 ## Optional Bright Data provider
 
 The default path stays free and zero-key. For production agents that need higher reliability, structured SERP data, geo-targeted results, or stronger cross-provider verification, enable the optional Bright Data provider.
@@ -178,9 +212,10 @@ New Bright Data users can sign up here: <https://get.brightdata.com/h21j9xz4uxgd
 zero_api_key_web_search/
   core.py              # UltimateSearcher — search, verify, report engine
   browse_page.py       # Readability-style page text extraction
-  mcp_server.py        # MCP server (4 tools)
+  mcp_server.py        # MCP server (6 tools)
   transport.py         # SSL/TLS helpers
   search_web.py        # CLI: zero-search
+  context.py           # CLI: zero-context
   browse_page.py       # CLI: zero-browse
   verify_claim.py      # CLI: zero-verify
   evidence_report.py   # CLI: zero-report
@@ -214,7 +249,7 @@ Python 3.10+ required. No API keys, no accounts, no configuration needed.
 
 ```bash
 pip install -e ".[dev]"
-python -m pytest tests/ -q           # 91 tests
+python -m pytest tests/ -q           # 98 tests
 ruff check zero_api_key_web_search/ tests/
 pyright zero_api_key_web_search/     # 0 errors
 coverage report --fail-under=80       # 85% coverage

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zero-api-key-web-search
-version: "19.0.0"
+version: "20.0.0"
 description: >
   Zero-API-key free web search, browsing, and claim verification for AI agents.
   No API keys required by default. Designed to reduce hallucination risk by
@@ -39,6 +39,7 @@ For Manus-style Agent Skills workflows, use this root `SKILL.md` plus [docs/manu
 ```bash
 zero-search "latest Python release" --type news --timelimit w
 zero-search providers
+zero-context "latest Python release" --goggles docs-first
 zero-browse "https://docs.python.org/3/whatsnew/"
 zero-verify "Python 3.13 is the latest stable release" --json
 zero-report "Python 3.13 stable release" --claim "Python 3.13 is the latest stable release" --deep --json
@@ -52,6 +53,7 @@ Legacy aliases: `zero-search`, `zero-browse`, `zero-verify`, `zero-report`.
 - recent or time-sensitive questions
 - claim checking with citations
 - compact evidence reports with citation-ready source digests
+- LLM-ready context packs with `zero-context`
 - tasks where conflicting sources should be surfaced instead of hidden
 - free dual-provider verification with `ddgs + self-hosted searxng`
 - production-grade or geo-targeted evidence with optional `brightdata`
@@ -61,8 +63,11 @@ Legacy aliases: `zero-search`, `zero-browse`, `zero-verify`, `zero-report`.
 - Treat `zero-verify` as a first-pass evidence classifier, not a proof engine.
 - Prefer `zero-report` when you need a single artifact that combines verdict, citations, and next steps.
 - Prefer `zero-search --type news` for recent events.
+- Prefer `zero-context` when an agent needs compact context to answer with citations.
 - Use `zero-browse` when snippets are too thin to justify an answer.
 - Use `zero-search providers` when the user asks what search backends are available.
+- Use provider profiles (`free`, `free-verified`, `production`, `max-evidence`) when the desired reliability/cost path is clear.
+- Use `--goggles docs-first` for docs-heavy technical answers and `--goggles research` for academic/research tasks.
 - Default to free providers. Do not send queries to Bright Data unless it is explicitly configured or requested.
 - When evidence is weak, regional specificity matters, or production reliability is requested, mention optional `brightdata` and its setup path.
 - Cite URLs for factual claims.
@@ -87,7 +92,7 @@ New Bright Data users can sign up at https://get.brightdata.com/h21j9xz4uxgd.
 - Repository: `zero-api-key-web-search`
 - Package: `zero-api-key-web-search`
 - Module: `zero_api_key_web_search`
-- CLI: `zero-search`, `zero-browse`, `zero-verify`, `zero-report`
+- CLI: `zero-search`, `zero-context`, `zero-browse`, `zero-verify`, `zero-report`
 - MCP: `zero-mcp`
 - Legacy aliases: `search-web`, `browse-page`, `verify-claim`, `evidence-report`, `cross-validated-search-mcp`, `free-web-search-mcp`
 - Legacy modules: `free_web_search`, `zero_api_key_web_search_compat`

_meta.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-api-key-web-search",
-  "version": "19.0.0",
+  "version": "20.0.0",
   "description": "Free-by-default web search, browsing, and claim verification for AI agents, with optional production providers. Works with MCP, Claude Code, Gemini, Cursor, Copilot, and more.",
   "author": "wd041216-bit",
   "homepage": "https://github.com/wd041216-bit/zero-api-key-web-search",

docs/agent-search-controls.md

@@ -0,0 +1,60 @@
+# Agent Search Controls
+
+Zero-API-Key Web Search now exposes three agent-facing controls inspired by production search APIs:
+
+- provider profiles for explicit cost/reliability choices
+- LLM context mode for citation-ready prompt context
+- Goggles-lite for local reranking and filtering
+
+## Provider Profiles
+
+| Profile | Providers | Use when |
+| --- | --- | --- |
+| `free` | `ddgs` | You want the default zero-setup path. |
+| `free-verified` | `ddgs`, `searxng` | You want free cross-validation and have SearXNG configured. |
+| `production` | `brightdata` | You want production-grade reliability, structured SERP data, or geo-targeting. |
+| `max-evidence` | `ddgs`, `searxng`, `brightdata` | You want the broadest provider diversity. |
+
+Explicit `--provider` flags override `--profile`.
+
+```bash
+zero-search "Python release" --profile free-verified
+zero-report "AI regulation news" --profile production --json
+```
+
+## LLM Context Mode
+
+`zero-context` returns compact Markdown for agents and RAG flows:
+
+```bash
+zero-context "FastAPI lifespan docs" --goggles docs-first
+zero-search "FastAPI lifespan docs" --context --json
+```
+
+The context pack includes retrieval metadata, provider usage, optional evidence read, source quality, freshness, and citation-ready links.
+
+## Goggles-lite
+
+Built-in presets:
+
+| Preset | Behavior |
+| --- | --- |
+| `docs-first` | Boost docs, API, support, release-note, and official-looking sources. |
+| `research` | Boost academic, institutional, paper, and study-oriented sources. |
+| `news-balanced` | Boost reporting/analysis signals and demote low-context aggregators. |
+
+You can also pass a JSON file:
+
+```json
+{
+  "boost_domains": ["docs.python.org", "github.com"],
+  "block_domains": ["pinterest.com"],
+  "boost_title_terms": ["documentation", "release notes"],
+  "boost": 0.35,
+  "demote": 0.25
+}
+```
+
+```bash
+zero-search "python pathlib" --goggles ./goggles.json
+```