Skip to content

Search

Deep hub — prefer occam_search (verified from code) and configuration. This page maps providers; it is not a second schema.

Hub for open-web discovery. Occam does not index the web; providers return result URLs for later probe / transcode / digest.

Deep config: configuration.md (search section). Guide: guides/search-and-discover.md. Tool: tools/occam_search.md. Inventory: CAPABILITIES.

Default path

Both OCCAM_SEARCH_PROVIDER and OCCAM_SEARCH_PROVIDERS unset → cautious fan-out duckduckgo + mojeek (provider: fanout, providersUsed[]). Soft-failing arms are skipped; merge by URL consensus. Singular OCCAM_SEARCH_PROVIDER=duckduckgo keeps one arm. OCCAM_SEARCH_PROVIDERS=keyless expands to all built-in HTML SERPs (DDG+Mojeek+Qwant+Startpage+Bing).

MCP tool: occam_search (Tools/OccamSearchTool.cs:17–22) — query → {id, handle, title, url, snippet}. Handles S1 / H… bind into later tools via SourceHandleStore.

Providers

Interface: Search/ISearchProvider.cs:8. DI registration: Composition/OccamServiceCollectionExtensions.cs (search provider block).

Name API key? Base URL Notes
duckduckgo no built-in HTML/lite Default singular
mojeek no built-in HTML Keyless fan-out arm
qwant no built-in HTML Keyless fan-out arm
startpage no built-in HTML Keyless fan-out arm
bing no built-in HTML Keyless fan-out arm (may soft-fail)
searxng no required OCCAM_SEARCH_URL Self-hosted
brave yes (OCCAM_SEARCH_API_KEY) default api.search.brave.com
tavily yes (OCCAM_SEARCH_API_KEY) default api.tavily.com
external_cli no local binary Experimental — external CLI search provider (opt-in, not bundled); OCCAM_EXTERNAL_SEARCH_PATH or PATH (ExternalCliSearchProvider.cs:10–28)

OCCAM_SEARCH_PROVIDER=off|none → configured-off failure (SearchService.cs resolve path).

Fan-out + health

When OCCAM_SEARCH_PROVIDERS is set (CSV), it wins over the singular provider. Token keyless expands to every registered HTML SERP that needs neither API key nor base URL (today: duckduckgo, mojeek, qwant, startpage, bing; not external_cli). Healthy backends are polled; merge by URL consensus; provider=fanout + providersUsed[]. Individual arms may soft-fail — that is expected, not a claim that five providers always succeed.

Health / degrade / rate limits: Search/SearchProviderHealth.cs (env: OCCAM_SEARCH_DEGRADE_MINUTES, OCCAM_SEARCH_RATE_MAX, OCCAM_SEARCH_RATE_WINDOW_S, timeouts — see configuration.md).

OCCAM_SEARCH_PROVIDER  XOR  OCCAM_SEARCH_PROVIDERS (CSV wins)
  → skip providers missing required key/URL
  → poll healthy arms
  → merge / dedup by URL
  → degrade on 429 / CAPTCHA-like 202 / timeout

Honesty notes

  • Occam search is discovery, not a crawl index.
  • External CLI search provider is opt-in (BYO binary, not bundled) — do not imply it ships in the release tarball.
  • PDF OCR and translate are separate advanced env knobs (OCCAM_PDF_OCR*, OCCAM_TRANSLATE_*) — not search providers.