Integration: youcom search backend for 1broseidon/ketch

[mouse-value-add]

Source repo

https://github.com/1broseidon/ketch

Why selected

• 531 stars (mid-popular band), MIT licensed, Go, pushed within hours (very active: recent commits same day).
• ketch is a stateless CLI for agent web search — its entire purpose is federating web-search providers behind one Searcher interface. It has an explicit, documented provider abstraction with 9 existing backends (brave, ddg, searxng, exa, firecrawl, keenable, tavily, parallel, serpbase); the last two releases each added a keyed backend through the identical pattern (see CHANGELOG 0.14.0).
• Ships its own agent skill (skills/ketch/SKILL.md, skills.sh-compatible) and an MCP server (ketch mcp serve) — landing a youcom backend in the provider registry gives You.com visibility to the maintainer and every ketch user/agent.
• Clean implementation path: mirror the Tavily backend (keyed, Bearer/X-API-Key header auth, keyPool rotation, doctor probe, config set/discovery, multi/random federation). Tests use httptest servers — fully runnable offline.
• Not previously touched by this workflow (checked against all tracking issues + authored PRs).

Candidate evaluation summary

Candidate	Stars	Distribution surface	Activity	Verdict
1broseidon/ketch	531	Provider registry (Searcher iface) + agent skill + MCP server	same-day pushes	selected
ggozad/haiku.rag	586	MCP client config, agentic RAG	same-day	good, but search is a smaller part of its surface; ketch is search-native
szczyglis-dev/py-gpt	1898	plugin system	12 days	license NOASSERTION + large desktop app, higher risk

Proposed integration type

Provider adapter — new youcom web-search backend in ketch's existing provider registry (repo-native equivalent of a plugin listing).

Distribution surface leveraged

ketch's search.Searcher provider abstraction (search.NewFromConfig owns the backend switch; every backend is wired through config set/discovery, --multi/--random federation, the MCP search tool, and ketch doctor).

Planned setup / env vars

• ketch config set youcom_api_key <key> (get a key at https://you.com/platform/api-keys)
• Multi-key rotation: youcom_api_keys JSON array / KETCH_YOUCOM_API_KEY comma-separated env override
• Select: ketch search "q" -b youcom or ketch config set backend youcom; joins --multi=all federation automatically when a key is set
• API: POST https://ydc-index.io/v1/search with X-API-Key header auth (verified against You.com docs via the Docs MCP searchDocs tool)

Expected usage example

ketch config set youcom_api_key <key>
ketch search "golang generics" -b youcom
ketch search "golang generics" --multi=brave,youcom

Validation plan

• go test ./... (new search/youcom_test.go + updated config/cmd tests, httptest-based)
• golangci-lint run (repo standard, gocyclo max 15)
• Live check documented: ketch config set youcom_api_key <key> && ketch search "test" -b youcom
• Default behavior unchanged: brave stays default; youcom is inert unless explicitly selected or keyed

Branch / PR

• Branch: (pending)
• PR: (pending)

[mouse-value-add]

Status: PR opened ✅

• Branch: https://github.com/mouse-value-add/ketch/tree/feat/youcom-search-integration (commit 493e176)
• PR: feat: add optional you.com search backend 1broseidon/ketch#52 — feat: add optional you.com search backend

Integration type: Provider adapter (repo-native Searcher backend)
Distribution surface leveraged: ketch's existing backend/provider abstraction (search.Searcher interface + keyed-backend pattern, same as tavily/serpbase)

Scope of wiring:

• search/youcom.go — provider: POST https://ydc-index.io/v1/search, X-API-Key header auth, key-pool rotation with 401/429 retry, snippet→Description/Content mapping
• config/ — youcom_api_key / youcom_api_keys, KETCH_YOUCOM_API_KEY, YoucomKeys(), AvailableBackends()
• cmd/ — config set dispatch + discovery JSON + help text
• doctor/ — probeYoucom live health check
• mcp/ — backend enumeration in tool schema/description
• docs — README, AGENTS.md, CLAUDE.md, skills refs, site guide/reference, CHANGELOG (root + site mirror)

Env/config: youcom_api_key (single), youcom_api_keys (JSON pool), KETCH_YOUCOM_API_KEY (env override). Fully opt-in: default backend unchanged; --multi=all includes youcom only when a key is set.

Usage:

ketch config set youcom_api_key <key>
ketch search "query" -b youcom
ketch search "q" --multi=brave,youcom   # federated, RRF-fused
ketch doctor | grep youcom

Validation performed:

• go build ./..., go vet ./..., gofmt -l . clean; full go test ./... green (go1.25.7 toolchain)
• New tests: provider happy-path/limit/empty-URL/status-mapping/malformed-JSON, key rotation (401/429 rotate to second key), factory missing-key error, doctor probe (header auth, no-key stays off-network)
• Live manual check with an invalid key: correct actionable error naming the config command; ketch doctor correctly reports misconfigured; unset key fails fast with setup hint

Fallback/error behavior: 401/403 → "invalid API key" with fix hint; 429 → rate-limited error (retried with another key when a pool is set); 402 → credits-exhausted; unknown statuses → bounded body snippet, never the key.

Follow-up on review feedback is handled by the maintenance job.

[mouse-value-add]

2026-08-31: PR 1broseidon/ketch#52 mergeable, no CI checks configured, no comments — awaiting maintainer review. Repo active (pushed today).