codewhale_runtime/config/search.rs
1//! Web-search provider configuration types.
2//!
3//! Self-contained `[search]` table types extracted verbatim from `config.rs`.
4//! Re-exported from `crate::config` via `pub use search::*;` so existing
5//! `crate::config::SearchProvider` (and sibling) paths resolve unchanged
6//! (#3311).
7
8use serde::{Deserialize, Serialize};
9
10/// Search provider enumeration — selects the first backend `web_search` uses.
11/// API-backed providers may visibly degrade through DuckDuckGo → Bing after
12/// runtime failure or an empty result. Configuration and
13/// network-policy errors fail closed without crossing providers.
14#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
15#[serde(rename_all = "snake_case")]
16pub enum SearchProvider {
17 /// Bing HTML scraping. No API key needed.
18 Bing,
19 /// DuckDuckGo HTML scraping with Bing fallback. No API key needed.
20 #[serde(alias = "duckduckgo")]
21 DuckDuckGo,
22 /// Firecrawl Search API. Works keyless on Firecrawl Cloud with a bounded
23 /// per-IP quota; `[search] api_key` or `FIRECRAWL_API_KEY` raises limits.
24 #[default]
25 Firecrawl,
26 /// Tavily AI Search API (<https://tavily.com>). Requires api_key.
27 Tavily,
28 /// Bocha AI Search API (<https://bochaai.com>). Requires api_key.
29 Bocha,
30 /// Metaso AI Search API (<https://metaso.cn>). Requires `[search] api_key`
31 /// or the `METASO_API_KEY` env var.
32 #[serde(alias = "metaso")]
33 Metaso,
34 /// SearXNG JSON search API. Requires a trusted/self-hosted `base_url`.
35 #[serde(alias = "searx", alias = "searx-ng", alias = "searx_ng")]
36 Searxng,
37 /// Baidu AI Search API (<https://qianfan.baidubce.com>). Requires api_key.
38 #[serde(
39 alias = "baidu-search",
40 alias = "baidu_ai_search",
41 alias = "baidu_search",
42 alias = "baidu-ai-search"
43 )]
44 Baidu,
45 /// Volcengine Ark web_search via Responses API. Requires api_key.
46 /// Free tier: 20K queries/month per API key. Falls back to
47 /// `VOLCENGINE_API_KEY` / `VOLCENGINE_ARK_API_KEY` / `ARK_API_KEY`
48 /// env vars when `[search] api_key` is not set.
49 #[serde(
50 alias = "volcengine",
51 alias = "ark",
52 alias = "volc",
53 alias = "volcengine-ark",
54 alias = "volcengine_ark",
55 alias = "volc-ark"
56 )]
57 Volcengine,
58 /// Sofya web search API (<https://sofya.co>). Requires api_key
59 /// (`ay_live_...`). Returns full extracted page content rather than
60 /// snippets; falls back to the `SOFYA_API_KEY` env var when
61 /// `[search] api_key` is not set.
62 Sofya,
63 /// Serply Google search API (<https://serply.io>). Requires api_key;
64 /// returns Google organic results with snippets. Falls back to the
65 /// `SERPLY_API_KEY` env var when `[search] api_key` is not set.
66 Serply,
67 /// DeepSeek Search API (<https://api-docs.deepseek.com/guides/search>). Requires api_key.
68 #[serde(rename = "deepseek", alias = "deep-seek", alias = "deepseek-search")]
69 DeepSeek,
70 /// SearchApi Google SERP API (<https://www.searchapi.io>). Requires api_key;
71 /// returns Google organic results with snippets. Falls back to the
72 /// `SEARCHAPI_API_KEY` env var when `[search] api_key` is not set.
73 #[serde(rename = "searchapi", alias = "search-api", alias = "search_api")]
74 SearchApi,
75}
76
77impl SearchProvider {
78 #[must_use]
79 pub fn parse(value: &str) -> Option<Self> {
80 match value.trim().to_ascii_lowercase().as_str() {
81 "bing" => Some(Self::Bing),
82 "duckduckgo" | "duck-duck-go" | "duck_duck_go" | "ddg" => Some(Self::DuckDuckGo),
83 "firecrawl" | "fire-crawl" | "fire_crawl" => Some(Self::Firecrawl),
84 "tavily" => Some(Self::Tavily),
85 "bocha" => Some(Self::Bocha),
86 "metaso" => Some(Self::Metaso),
87 "searxng" | "searx" | "searx-ng" | "searx_ng" => Some(Self::Searxng),
88 "baidu" | "baidu-search" | "baidu_search" | "baidu-ai-search" | "baidu_ai_search" => {
89 Some(Self::Baidu)
90 }
91 "volcengine" | "ark" | "volc" | "volcengine-ark" => Some(Self::Volcengine),
92 "sofya" => Some(Self::Sofya),
93 "serply" => Some(Self::Serply),
94 "deepseek" | "deep-seek" | "deepseek-search" => Some(Self::DeepSeek),
95 "searchapi" | "search-api" | "search_api" => Some(Self::SearchApi),
96 _ => None,
97 }
98 }
99
100 #[must_use]
101 pub fn as_str(self) -> &'static str {
102 match self {
103 Self::Bing => "bing",
104 Self::DuckDuckGo => "duckduckgo",
105 Self::Firecrawl => "firecrawl",
106 Self::Tavily => "tavily",
107 Self::Bocha => "bocha",
108 Self::Metaso => "metaso",
109 Self::Searxng => "searxng",
110 Self::Baidu => "baidu",
111 Self::Volcengine => "volcengine",
112 Self::Sofya => "sofya",
113 Self::Serply => "serply",
114 Self::DeepSeek => "deepseek",
115 Self::SearchApi => "searchapi",
116 }
117 }
118
119 #[must_use]
120 pub fn names_hint() -> &'static str {
121 "bing, duckduckgo, firecrawl, tavily, bocha, metaso, searxng, baidu, volcengine, sofya, serply, deepseek, searchapi"
122 }
123}
124
125#[derive(Debug, Clone, Copy, PartialEq, Eq)]
126pub enum SearchProviderSource {
127 Default,
128 Config,
129 EnvOverride,
130 /// Autodetected from a Tavily key signal: `TAVILY_API_KEY`, or a generic
131 /// `[search] api_key` / `CODEWHALE_SEARCH_API_KEY` value in the `tvly-`
132 /// family. Runtime-only — resolution never writes `[search] provider`.
133 TavilyKey,
134}
135
136impl SearchProviderSource {
137 /// One honest source token for doctor, `/config`, and the runtime GET
138 /// route. `tavily key` names where the signal came from without claiming a
139 /// disk pin or naming `TAVILY_API_KEY` when the winner was a `tvly-`
140 /// generic key.
141 #[must_use]
142 pub fn as_str(self) -> &'static str {
143 match self {
144 Self::Default => "default",
145 Self::Config => "config",
146 Self::EnvOverride => "env override",
147 Self::TavilyKey => "tavily key",
148 }
149 }
150}
151
152/// Tavily issues keys in the `tvly-` family; the Tavily error copy already
153/// says so. Applied to **generic** keys only — a dedicated `TAVILY_API_KEY`
154/// is honored as-is, however it is shaped.
155#[must_use]
156pub fn looks_like_tavily_key(value: &str) -> bool {
157 value.trim().starts_with("tvly-")
158}
159
160/// `TAVILY_API_KEY`, read at request time. Deliberately never merged into
161/// [`SearchConfig::api_key`]: that generic slot is shared by every provider,
162/// so merging would hand a Tavily key to Firecrawl (or the reverse) the moment
163/// the operator pins a different provider.
164#[must_use]
165pub fn tavily_env_key() -> Option<String> {
166 std::env::var("TAVILY_API_KEY")
167 .ok()
168 .map(|value| value.trim().to_string())
169 .filter(|value| !value.is_empty())
170}
171
172/// The key a Tavily request should send.
173///
174/// Dedicated env wins over the generic `[search] api_key` so resolution and
175/// the request agree on one key: `[search] api_key` is shared, and a
176/// Firecrawl `fc-` / sentinel generic value must never be POSTed to
177/// `api.tavily.com`. The generic fallback is prefix-gated, which is what
178/// stops `CODEWHALE_SEARCH_API_KEY=doctor-offline-search-sentinel` from
179/// autodetecting Tavily.
180#[must_use]
181pub fn tavily_key_from(search_api_key: Option<&str>) -> Option<String> {
182 if let Some(env_key) = tavily_env_key() {
183 return Some(env_key);
184 }
185 search_api_key
186 .map(str::trim)
187 .filter(|value| !value.is_empty() && looks_like_tavily_key(value))
188 .map(str::to_string)
189}
190
191#[derive(Debug, Clone, Copy, PartialEq, Eq)]
192pub struct SearchProviderResolution {
193 pub provider: SearchProvider,
194 pub source: SearchProviderSource,
195}
196
197/// Web search provider configuration (`[search]` table in config.toml).
198#[derive(Debug, Clone, Deserialize, Default)]
199pub struct SearchConfig {
200 /// Search provider. Default: keyless `firecrawl`.
201 #[serde(default)]
202 pub provider: Option<SearchProvider>,
203 /// Optional search endpoint. With `duckduckgo`, this is a
204 /// DuckDuckGo-compatible HTML endpoint. With `searxng`, this is the trusted
205 /// SearXNG instance root or `/search` endpoint.
206 #[serde(default)]
207 pub base_url: Option<String>,
208 /// Optional for Firecrawl; required for Tavily, Bocha, Metaso, Baidu, Volcengine, Sofya, Serply, DeepSeek, or SearchApi.
209 /// Metaso also falls back to the `METASO_API_KEY` env var.
210 /// Baidu also falls back to `BAIDU_SEARCH_API_KEY` env var.
211 /// Serply also falls back to the `SERPLY_API_KEY` env var.
212 /// SearchApi also falls back to the `SEARCHAPI_API_KEY` env var.
213 /// Volcengine also falls back to `VOLCENGINE_API_KEY` / `VOLCENGINE_ARK_API_KEY` / `ARK_API_KEY` env vars.
214 ///
215 /// This slot is shared across providers. `TAVILY_API_KEY` is **not**
216 /// merged into it — Tavily reads its dedicated env at request time
217 /// ([`tavily_key_from`]) so pinning another provider never forwards a
218 /// Tavily key, and a `tvly-` value here can autodetect Tavily without a
219 /// disk write.
220 #[serde(default)]
221 pub api_key: Option<String>,
222 /// Whether the active route's provider-native search runs ahead of the
223 /// search provider. Unset: native search leads only when no provider is
224 /// configured, so a pinned provider always wins; see
225 /// [`crate::config::Config::search_native`].
226 #[serde(default)]
227 pub native: Option<bool>,
228}