Imported from cjangrist/jasa (src/jasa/search/providers/AGENTS.md). Install upstream with npx skills add cjangrist/jasa --skill providers. Copyright stays with the author.

AGENTS.md — src/jasa/search/providers/

Eighteen search adapters normalize unrelated upstream APIs into SearchResult(title, url, snippet, source_provider, score?). The registry adds adapters with a non-empty provider-native secret and preserves the canonical tuple order used by deterministic fan-out and RRF.

Registry and base

• __init__.py defines PROVIDER_CLASSES, CANONICAL_PROVIDER_ORDER, KNOWN_SEARCH_SECRET_ENVS, KNOWN_SEARCH_SETTING_ENVS, and load_search_providers().
• base.py defines SearchRequest and abstract SearchProvider. _fetch() delegates to omnifetch's shared HTTP JSON helper so size limits, status mapping, transport errors, and the shared ProviderError taxonomy stay consistent. It also redacts raw and quote-stripped credentials.
• setting_envs declares optional non-secret deployment knobs. The registry resolves them from the same environment snapshot it gates on and passes them to the constructor; _setting() reads one with a fallback. A setting never activates an adapter, and KNOWN_SEARCH_SETTING_ENVS is derived from the registry so .env.example parity and the test isolation fixture cannot drift.

Provider matrix

Muse uses MODEL_API_KEY to POST /responses at Meta with muse-spark-1.2-contributor by default. MUSE_BASE_URL and MUSE_SEARCH_MODEL override that pair; Muse rejects non-HTTPS or malformed endpoints before HTTP. The hosted web_search tool returns raw text_result entries when include requests web_search_call.results; these supply source snippets when supplied (empty in live 1.2 responses). Citation-only URLs follow with empty snippets, never model prose. Results deduplicate by URL in retrieval order. All operators stay rendered in the query because Meta documents no structural domain filters. A completed answer without search results or citations is an empty successful list; explicit failures and unfinished turns without hits remain provider errors.

Adapter contract

1. Set non-empty name, base_url, and timeout class attrs. Set secret_env to a provider-native name and declare optional deployment knobs in setting_envs.
2. Credentialed adapters call _validated_key() before any request.
3. Use _fetch() instead of direct httpx calls.
4. Map a missing result collection to an empty successful list unless the provider contract has an explicit failure flag.
5. Set source_provider to the registered name for every row.
6. Preserve native score when useful; otherwise leave it None and let array order carry rank.
7. Never include a credential in exception text or logs.
8. Do not retry inside an adapter; fanout.py owns retry policy.
9. Override allows_cache() only when the provider's response semantics move independently of the exact query, such as Keenable's relative date window. The search service passes the same reference_datetime to cache eligibility and the provider's SearchRequest; use it instead of sampling another clock.

Fast failure diagnosis

The current shared secret snapshot tests raw truthiness. A whitespace-only or empty quoted value can therefore appear in /health before request-time validation rejects it or the upstream receives a blank key. Treat that state as misconfiguration; never use quoted placeholders in .env.

Adding a provider

• Read all adapters to select the closest request/response pattern.
• Add the module, then append the class in __init__.py at the intentional canonical position. Its non-None secret is derived into the known set.
• Add .env.example only for a secret or setting, and add the README provider entry with a documented default for every declared setting.
• Add focused tests for exact outbound request, mapping, empty/missing data, auth/rate-limit/5xx behavior as applicable, missing key, and redaction.
• Update the environment-isolation invariant through the registry source, not a second hand-maintained list.
• Verify a real provider with the one-request integration harness before adding its INTEGRATION_CASES entry.

Tests

Provider tests are named tests/test_provider_<name>.py; registry invariants are in tests/test_providers.py. Tavily has the broad reference error matrix. Run all with:

conda run -n base uv run pytest tests/test_provider_*.py tests/test_providers.py