Skip to main content

graphrt_llm/
providers.rs

1//! Config-driven model providers.
2//!
3//! A providers file declares any number of OpenAI-compatible, Anthropic,
4//! Gemini or Bedrock endpoints without code:
5//!
6//! ```yaml
7//! providers:
8//!   - name: openrouter
9//!     kind: openai                       # openai | anthropic
10//!     base_url: https://openrouter.ai/api/v1
11//!     api_key_env: OPENROUTER_API_KEY    # read from the environment, never stored in the file
12//!     headers: { HTTP-Referer: "${SITE_URL}" }
13//!     aliases: [or]                      # extra provider names
14//!     models: { fast: meta-llama/llama-3.1-8b-instruct }   # model-name aliases
15//!     defaults: { temperature: 0.2, max_tokens: 1024 }     # applied when a node sets none
16//!   - name: azure
17//!     kind: openai
18//!     base_url: https://my.openai.azure.com/openai/deployments/gpt4o
19//!     api_key_env: AZURE_OPENAI_KEY
20//!     auth_header: api-key
21//!     query: { api-version: "2024-06-01" }
22//!   - name: gemini
23//!     kind: gemini
24//!     api_key_env: GEMINI_API_KEY
25//!   - name: vertex
26//!     kind: gemini
27//!     base_url: https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/publishers/google
28//!     api_key_env: VERTEX_ACCESS_TOKEN
29//!     auth: bearer                       # gemini: api-key (default) | bearer
30//!   - name: bedrock
31//!     kind: bedrock
32//!     region: us-east-1
33//!     access_key_id_env: AWS_ACCESS_KEY_ID          # SigV4 ...
34//!     secret_access_key_env: AWS_SECRET_ACCESS_KEY
35//!     session_token_env: AWS_SESSION_TOKEN          # optional
36//!     # ... or a Bedrock API key: api_key_env: AWS_BEARER_TOKEN_BEDROCK
37//! ```
38//!
39//! `${VAR}` in `base_url`, `headers` and `query` values is replaced with the
40//! environment variable `VAR`. Missing variables are errors that name the
41//! variable but never print values.
42
43#[cfg(feature = "http")]
44use std::sync::Arc;
45
46#[cfg(feature = "http")]
47use futures::future::BoxFuture;
48use indexmap::IndexMap;
49use serde::Deserialize;
50
51use crate::error::LlmError;
52use crate::registry::ModelRegistry;
53#[cfg(feature = "http")]
54use crate::types::{ChatModel, ChatRequest, ChatStream};
55
56/// Provider protocol.
57#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
58#[serde(rename_all = "lowercase")]
59#[non_exhaustive]
60pub enum ProviderKind {
61    /// OpenAI-compatible chat completions.
62    #[serde(alias = "openai-compatible", alias = "openai_compatible")]
63    Openai,
64    /// Anthropic Messages API.
65    Anthropic,
66    /// Google Gemini (Gemini API or Vertex AI).
67    Gemini,
68    /// AWS Bedrock Converse API.
69    Bedrock,
70}
71
72/// Default request parameters applied when the node does not set them.
73#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
74#[serde(deny_unknown_fields)]
75pub struct DefaultParams {
76    #[serde(default)]
77    pub temperature: Option<f64>,
78    #[serde(default)]
79    pub top_p: Option<f64>,
80    #[serde(default)]
81    pub max_tokens: Option<u32>,
82    #[serde(default)]
83    pub stop: Vec<String>,
84}
85
86/// One provider entry.
87#[derive(Clone, Debug, Deserialize)]
88#[serde(deny_unknown_fields)]
89pub struct ProviderConfig {
90    pub name: String,
91    pub kind: ProviderKind,
92    /// Endpoint base URL (provider default when omitted).
93    #[serde(default)]
94    pub base_url: Option<String>,
95    /// Environment variable holding the API key.
96    #[serde(default)]
97    pub api_key_env: Option<String>,
98    /// When true, a missing `api_key_env` variable is not an error (e.g. local servers).
99    #[serde(default)]
100    pub api_key_optional: bool,
101    /// OpenAI-compatible only: send the key in this header instead of `Authorization: Bearer`.
102    #[serde(default)]
103    pub auth_header: Option<String>,
104    #[serde(default)]
105    pub headers: IndexMap<String, String>,
106    /// OpenAI-compatible only: query parameters added to every request.
107    #[serde(default)]
108    pub query: IndexMap<String, String>,
109    /// Additional provider names resolving to this provider.
110    #[serde(default)]
111    pub aliases: Vec<String>,
112    /// Model-name aliases: `alias -> real model id`.
113    #[serde(default)]
114    pub models: IndexMap<String, String>,
115    #[serde(default)]
116    pub defaults: DefaultParams,
117    /// Gemini only: how the key is sent, `api-key` (default) or `bearer`.
118    #[serde(default)]
119    pub auth: Option<String>,
120    /// Bedrock only: AWS region (`${VAR}` allowed).
121    #[serde(default)]
122    pub region: Option<String>,
123    /// Bedrock only: environment variable holding the access key id (SigV4).
124    #[serde(default)]
125    pub access_key_id_env: Option<String>,
126    /// Bedrock only: environment variable holding the secret access key (SigV4).
127    #[serde(default)]
128    pub secret_access_key_env: Option<String>,
129    /// Bedrock only: environment variable holding a session token (optional).
130    #[serde(default)]
131    pub session_token_env: Option<String>,
132}
133
134/// A providers file: either `{providers: [...]}` or a bare list.
135#[derive(Clone, Debug, Default, Deserialize)]
136#[serde(from = "ProvidersRepr")]
137pub struct ProvidersConfig {
138    pub providers: Vec<ProviderConfig>,
139    /// Providers authenticated by a dynamic credential source (token broker, env var
140    /// read per request, or host-supplied), keyed by provider name. Entries replace
141    /// same-named providers. See `docs/credentials.md`.
142    pub credentials: IndexMap<String, crate::credential_config::ProviderCredentialConfig>,
143}
144
145#[derive(Deserialize)]
146#[serde(untagged)]
147enum ProvidersRepr {
148    Wrapped {
149        #[serde(default)]
150        providers: Vec<ProviderConfig>,
151        #[serde(default)]
152        credentials: IndexMap<String, crate::credential_config::ProviderCredentialConfig>,
153    },
154    List(Vec<ProviderConfig>),
155}
156
157impl From<ProvidersRepr> for ProvidersConfig {
158    fn from(repr: ProvidersRepr) -> Self {
159        match repr {
160            ProvidersRepr::Wrapped { providers, credentials } => Self { providers, credentials },
161            ProvidersRepr::List(providers) => Self { providers, credentials: IndexMap::new() },
162        }
163    }
164}
165
166impl ProvidersConfig {
167    /// Decode from a JSON value (hosts decode YAML into JSON first).
168    pub fn from_value(value: serde_json::Value) -> Result<Self, LlmError> {
169        // Decode through a strict wrapper first so typos produce a precise message
170        // instead of the generic "did not match any variant" of the untagged enum.
171        let mut credentials = IndexMap::new();
172        let entries = match value {
173            serde_json::Value::Object(mut map) => {
174                let providers = map.remove("providers").unwrap_or(serde_json::Value::Array(Vec::new()));
175                if let Some(raw) = map.remove("credentials") {
176                    credentials = serde_json::from_value(raw)
177                        .map_err(|e| LlmError::Config(format!("providers config `credentials`: {e}")))?;
178                }
179                if let Some(key) = map.keys().next() {
180                    return Err(LlmError::Config(format!("unknown key `{key}` in providers config")));
181                }
182                providers
183            }
184            other => other,
185        };
186        let serde_json::Value::Array(items) = entries else {
187            return Err(LlmError::Config("providers config must be a list of providers".into()));
188        };
189        let mut providers = Vec::with_capacity(items.len());
190        for (i, item) in items.into_iter().enumerate() {
191            let label = item.get("name").and_then(serde_json::Value::as_str).map(str::to_owned);
192            let cfg: ProviderConfig = serde_json::from_value(item).map_err(|e| {
193                LlmError::Config(format!("provider #{} ({}): {e}", i + 1, label.as_deref().unwrap_or("unnamed")))
194            })?;
195            providers.push(cfg);
196        }
197        Ok(Self { providers, credentials })
198    }
199
200    /// Decode from JSON text.
201    pub fn from_json(text: &str) -> Result<Self, LlmError> {
202        let value: serde_json::Value =
203            serde_json::from_str(text).map_err(|e| LlmError::Config(format!("invalid providers JSON: {e}")))?;
204        Self::from_value(value)
205    }
206}
207
208impl ModelRegistry {
209    /// Build a registry from a providers config, reading secrets and `${VAR}`
210    /// references from the process environment.
211    #[cfg(feature = "http")]
212    pub fn from_config(config: &ProvidersConfig) -> Result<Self, LlmError> {
213        let vars: Vec<(String, String)> = std::env::vars().collect();
214        Self::from_config_with_vars(config, &vars)
215    }
216
217    /// Like [`ModelRegistry::from_config`] with explicit variables.
218    ///
219    /// A `typesafe` entry in the `credentials` section is not a chat model; use
220    /// [`ProvidersConfig::load`] to get its System One client as well.
221    #[cfg(feature = "http")]
222    pub fn from_config_with_vars(config: &ProvidersConfig, vars: &[(String, String)]) -> Result<Self, LlmError> {
223        config.load(vars).map(|loaded| loaded.models)
224    }
225}
226
227/// Everything a providers file configures.
228#[derive(Debug, Default)]
229#[non_exhaustive]
230pub struct LoadedProviders {
231    pub models: ModelRegistry,
232    /// The TypeSafe System One client from a `typesafe` credentials entry.
233    #[cfg(feature = "typesafe")]
234    pub system_one: Option<crate::typesafe::SystemOneClient>,
235}
236
237impl ProvidersConfig {
238    /// Build the chat models (and the System One client of a `typesafe`
239    /// credentials entry), reading secrets and `${VAR}` references from `vars`.
240    ///
241    /// Providers files have no host app, so `credentials` entries cannot use
242    /// `source: external` or `app_auth: external`, and a credentials entry may not
243    /// share its name with a `providers` entry (it would silently replace its
244    /// aliases, model map and defaults).
245    #[cfg(feature = "http")]
246    pub fn load(&self, vars: &[(String, String)]) -> Result<LoadedProviders, LlmError> {
247        let config = self;
248        for (name, entry) in &config.credentials {
249            if entry.needs_host() {
250                return Err(LlmError::Config(format!(
251                    "credentials for `{name}`: `source: external` / `app_auth: external` need a host app that \
252                     registers credentials at run time (e.g. graphrt-ffi); in a providers file use `env` or \
253                     `token_broker`"
254                )));
255            }
256            if config.providers.iter().any(|p| &p.name == name || p.aliases.iter().any(|a| a == name)) {
257                return Err(LlmError::Config(format!(
258                    "credentials entry `{name}` has the same name as a `providers` entry; rename one of them"
259                )));
260            }
261        }
262        // An alias must not shadow a provider of the same file, and must name exactly
263        // one provider: either mistake would silently route requests elsewhere.
264        let names: std::collections::HashSet<&str> = config.providers.iter().map(|p| p.name.as_str()).collect();
265        let mut aliases: std::collections::HashMap<&str, &str> = std::collections::HashMap::new();
266        for provider in &config.providers {
267            for alias in &provider.aliases {
268                if names.contains(alias.as_str()) {
269                    return Err(LlmError::Config(format!(
270                        "provider `{}`: alias `{alias}` is also the name of a provider",
271                        provider.name
272                    )));
273                }
274                if let Some(other) = aliases.insert(alias.as_str(), provider.name.as_str()) {
275                    return Err(LlmError::Config(format!(
276                        "alias `{alias}` is declared by both `{other}` and `{}`",
277                        provider.name
278                    )));
279                }
280            }
281        }
282        let mut registry = ModelRegistry::new();
283        for provider in &config.providers {
284            let model = build_provider(provider, vars)?;
285            registry.try_add(provider.name.clone(), Arc::clone(&model))?;
286            for alias in &provider.aliases {
287                registry.alias(alias.clone(), provider.name.clone());
288            }
289        }
290        let host = crate::credential_config::HostCredentials::new();
291        #[allow(unused_variables)]
292        let applied = crate::credential_config::apply(&mut registry, &config.credentials, &host)?;
293        Ok(LoadedProviders {
294            models: registry,
295            #[cfg(feature = "typesafe")]
296            system_one: applied.system_one,
297        })
298    }
299}
300
301impl ModelRegistry {
302    /// Add every provider and alias of `other`. `other` wins every conflict: a
303    /// same-named provider is replaced, and an alias of `other` shadows a provider
304    /// of `self` with that name (so a providers file can redirect `openai` to a
305    /// local server). Used to layer a providers file over [`ModelRegistry::from_env`].
306    pub fn merge(&mut self, other: ModelRegistry) -> &mut Self {
307        let (providers, aliases) = other.into_parts();
308        for (name, model) in providers {
309            self.remove(&name);
310            self.add(name, model);
311        }
312        for (alias, target) in aliases {
313            self.remove(&alias);
314            self.alias(alias, target);
315        }
316        self
317    }
318}
319
320#[cfg(feature = "http")]
321fn build_provider(p: &ProviderConfig, vars: &[(String, String)]) -> Result<Arc<dyn ChatModel>, LlmError> {
322    let ctx = |what: &str| format!("provider `{}`: {what}", p.name);
323    if p.name.trim().is_empty() {
324        return Err(LlmError::Config("provider `name` must not be empty".into()));
325    }
326    let api_key = match &p.api_key_env {
327        Some(var) => match lookup(vars, var) {
328            Some(v) => Some(v),
329            None if p.api_key_optional => None,
330            None => return Err(LlmError::Config(ctx(&format!("environment variable `{var}` is not set")))),
331        },
332        None => None,
333    };
334    let base_url = p.base_url.as_deref().map(|u| interpolate(u, vars)).transpose().map_err(|v| missing(&ctx, &v))?;
335    let mut headers = Vec::with_capacity(p.headers.len());
336    for (k, v) in &p.headers {
337        headers.push((k.clone(), interpolate(v, vars).map_err(|var| missing(&ctx, &var))?));
338    }
339
340    let protocol_only_fields = [
341        (p.auth.is_some() && p.kind != ProviderKind::Gemini, "auth"),
342        (p.region.is_some() && p.kind != ProviderKind::Bedrock, "region"),
343        (p.access_key_id_env.is_some() && p.kind != ProviderKind::Bedrock, "access_key_id_env"),
344        (p.secret_access_key_env.is_some() && p.kind != ProviderKind::Bedrock, "secret_access_key_env"),
345        (p.session_token_env.is_some() && p.kind != ProviderKind::Bedrock, "session_token_env"),
346    ];
347    if let Some((_, field)) = protocol_only_fields.iter().find(|(bad, _)| *bad) {
348        return Err(LlmError::Config(ctx(&format!("`{field}` is not supported for this provider kind"))));
349    }
350    let inner: Arc<dyn ChatModel> = match p.kind {
351        ProviderKind::Openai => openai_provider(p, base_url, api_key, headers, vars)?,
352        ProviderKind::Anthropic => anthropic_provider(p, base_url, api_key, headers)?,
353        ProviderKind::Gemini => gemini_provider(p, base_url, api_key, headers)?,
354        ProviderKind::Bedrock => bedrock_provider(p, base_url, api_key, headers, vars)?,
355    };
356    if p.models.is_empty() && p.defaults == DefaultParams::default() {
357        return Ok(inner);
358    }
359    Ok(Arc::new(Configured { inner, models: p.models.clone(), defaults: p.defaults.clone() }))
360}
361
362#[cfg(all(feature = "http", feature = "openai"))]
363fn openai_provider(
364    p: &ProviderConfig,
365    base_url: Option<String>,
366    api_key: Option<String>,
367    headers: Vec<(String, String)>,
368    vars: &[(String, String)],
369) -> Result<Arc<dyn ChatModel>, LlmError> {
370    use crate::openai::{AuthStyle, OpenAiConfig, OpenAiModel};
371    let mut cfg = OpenAiConfig::new(base_url.unwrap_or_else(|| OpenAiConfig::default().base_url), api_key);
372    cfg.use_max_completion_tokens = cfg.base_url.contains("api.openai.com");
373    if let Some(header) = &p.auth_header {
374        cfg.auth = AuthStyle::Header(header.clone());
375    }
376    cfg.headers = headers;
377    for (k, v) in &p.query {
378        let value =
379            interpolate(v, vars).map_err(|var| missing(&|w: &str| format!("provider `{}`: {w}", p.name), &var))?;
380        cfg.query.push((k.clone(), value));
381    }
382    Ok(Arc::new(OpenAiModel::new(cfg)?))
383}
384
385#[cfg(all(feature = "http", not(feature = "openai")))]
386fn openai_provider(
387    p: &ProviderConfig,
388    _base_url: Option<String>,
389    _api_key: Option<String>,
390    _headers: Vec<(String, String)>,
391    _vars: &[(String, String)],
392) -> Result<Arc<dyn ChatModel>, LlmError> {
393    Err(LlmError::Config(format!("provider `{}`: the `openai` feature is disabled in this build", p.name)))
394}
395
396#[cfg(all(feature = "http", feature = "anthropic"))]
397fn anthropic_provider(
398    p: &ProviderConfig,
399    base_url: Option<String>,
400    api_key: Option<String>,
401    headers: Vec<(String, String)>,
402) -> Result<Arc<dyn ChatModel>, LlmError> {
403    use crate::anthropic::{AnthropicConfig, AnthropicModel};
404    if !p.query.is_empty() || p.auth_header.is_some() {
405        return Err(LlmError::Config(format!(
406            "provider `{}`: `query` and `auth_header` are only supported for kind `openai`",
407            p.name
408        )));
409    }
410    let mut cfg = AnthropicConfig { api_key, ..AnthropicConfig::default() };
411    if let Some(base) = base_url {
412        cfg.base_url = base;
413    }
414    cfg.headers = headers;
415    Ok(Arc::new(AnthropicModel::new(cfg)?))
416}
417
418#[cfg(all(feature = "http", not(feature = "anthropic")))]
419fn anthropic_provider(
420    p: &ProviderConfig,
421    _base_url: Option<String>,
422    _api_key: Option<String>,
423    _headers: Vec<(String, String)>,
424) -> Result<Arc<dyn ChatModel>, LlmError> {
425    Err(LlmError::Config(format!("provider `{}`: the `anthropic` feature is disabled in this build", p.name)))
426}
427
428#[cfg(all(feature = "http", feature = "gemini"))]
429fn gemini_provider(
430    p: &ProviderConfig,
431    base_url: Option<String>,
432    api_key: Option<String>,
433    headers: Vec<(String, String)>,
434) -> Result<Arc<dyn ChatModel>, LlmError> {
435    use crate::gemini::{GeminiAuth, GeminiConfig, GeminiModel};
436    if !p.query.is_empty() || p.auth_header.is_some() {
437        return Err(LlmError::Config(format!(
438            "provider `{}`: `query` and `auth_header` are only supported for kind `openai`",
439            p.name
440        )));
441    }
442    let auth = match p.auth.as_deref() {
443        None | Some("api-key") => GeminiAuth::ApiKey,
444        Some("bearer") => GeminiAuth::Bearer,
445        Some(other) => {
446            return Err(LlmError::Config(format!(
447                "provider `{}`: unknown auth `{other}` (expected `api-key` or `bearer`)",
448                p.name
449            )));
450        }
451    };
452    let mut cfg = GeminiConfig { api_key, auth, headers, provider_name: p.name.clone(), ..GeminiConfig::default() };
453    if let Some(base) = base_url {
454        cfg.base_url = base;
455    }
456    Ok(Arc::new(GeminiModel::new(cfg)?))
457}
458
459#[cfg(all(feature = "http", not(feature = "gemini")))]
460fn gemini_provider(
461    p: &ProviderConfig,
462    _base_url: Option<String>,
463    _api_key: Option<String>,
464    _headers: Vec<(String, String)>,
465) -> Result<Arc<dyn ChatModel>, LlmError> {
466    Err(LlmError::Config(format!("provider `{}`: the `gemini` feature is disabled in this build", p.name)))
467}
468
469#[cfg(all(feature = "http", feature = "bedrock"))]
470fn bedrock_provider(
471    p: &ProviderConfig,
472    base_url: Option<String>,
473    api_key: Option<String>,
474    headers: Vec<(String, String)>,
475    vars: &[(String, String)],
476) -> Result<Arc<dyn ChatModel>, LlmError> {
477    use crate::bedrock::{AwsCredentials, BedrockAuth, BedrockConfig, BedrockModel};
478    let ctx = |w: &str| format!("provider `{}`: {w}", p.name);
479    if !p.query.is_empty() || p.auth_header.is_some() {
480        return Err(LlmError::Config(ctx("`query` and `auth_header` are only supported for kind `openai`")));
481    }
482    let region = match &p.region {
483        Some(r) => interpolate(r, vars).map_err(|v| missing(&ctx, &v))?,
484        None => lookup(vars, "AWS_REGION")
485            .or_else(|| lookup(vars, "AWS_DEFAULT_REGION"))
486            .ok_or_else(|| LlmError::Config(ctx("`region` is required (or set AWS_REGION)")))?,
487    };
488    let required = |var: &Option<String>, field: &str| -> Result<Option<String>, LlmError> {
489        match var {
490            Some(name) => lookup(vars, name)
491                .map(Some)
492                .ok_or_else(|| LlmError::Config(ctx(&format!("environment variable `{name}` ({field}) is not set")))),
493            None => Ok(None),
494        }
495    };
496    let access = required(&p.access_key_id_env, "access_key_id_env")?;
497    let secret = required(&p.secret_access_key_env, "secret_access_key_env")?;
498    let session_token = required(&p.session_token_env, "session_token_env")?;
499    if api_key.is_some() && session_token.is_some() {
500        return Err(LlmError::Config(ctx("`session_token_env` only applies to AWS access keys, not `api_key_env`")));
501    }
502    let auth = match (api_key, access, secret) {
503        (Some(_), Some(_), _) | (Some(_), _, Some(_)) => {
504            return Err(LlmError::Config(ctx("use either `api_key_env` or AWS access keys, not both")));
505        }
506        (Some(key), None, None) => BedrockAuth::ApiKey(key),
507        (None, Some(access_key_id), Some(secret_access_key)) => {
508            BedrockAuth::SigV4(AwsCredentials { access_key_id, secret_access_key, session_token })
509        }
510        _ => {
511            return Err(LlmError::Config(ctx(
512                "needs `api_key_env` (Bedrock API key) or both `access_key_id_env` and `secret_access_key_env`",
513            )));
514        }
515    };
516    let mut cfg = BedrockConfig::new(region, auth);
517    cfg.endpoint = base_url;
518    cfg.headers = headers;
519    cfg.provider_name.clone_from(&p.name);
520    Ok(Arc::new(BedrockModel::new(cfg)?))
521}
522
523#[cfg(all(feature = "http", not(feature = "bedrock")))]
524fn bedrock_provider(
525    p: &ProviderConfig,
526    _base_url: Option<String>,
527    _api_key: Option<String>,
528    _headers: Vec<(String, String)>,
529    _vars: &[(String, String)],
530) -> Result<Arc<dyn ChatModel>, LlmError> {
531    Err(LlmError::Config(format!("provider `{}`: the `bedrock` feature is disabled in this build", p.name)))
532}
533
534#[cfg(feature = "http")]
535fn missing(ctx: &dyn Fn(&str) -> String, var: &str) -> LlmError {
536    if var.ends_with("(unterminated `${`)") {
537        return LlmError::Config(ctx(&format!("invalid `${{...}}` reference: {var}")));
538    }
539    LlmError::Config(ctx(&format!("environment variable `{var}` referenced as ${{{var}}} is not set")))
540}
541
542fn lookup(vars: &[(String, String)], name: &str) -> Option<String> {
543    vars.iter().find(|(k, v)| k == name && !v.is_empty()).map(|(_, v)| v.clone())
544}
545
546/// Replace `${VAR}` references. Returns the name of the first missing variable on error.
547/// `$$` is a literal `$`.
548pub fn interpolate(text: &str, vars: &[(String, String)]) -> Result<String, String> {
549    let mut out = String::with_capacity(text.len());
550    let mut rest = text;
551    while let Some(pos) = rest.find('$') {
552        let (before, after) = rest.split_at(pos);
553        out.push_str(before);
554        let after = &after[1..];
555        if let Some(stripped) = after.strip_prefix('$') {
556            out.push('$');
557            rest = stripped;
558        } else if let Some(body) = after.strip_prefix('{') {
559            match body.find('}') {
560                Some(end) => {
561                    let name = &body[..end];
562                    let value = lookup(vars, name).ok_or_else(|| name.to_owned())?;
563                    out.push_str(&value);
564                    rest = &body[end + 1..];
565                }
566                None => {
567                    // An unterminated `${` would otherwise end up literally in a URL or header.
568                    return Err(format!("{} (unterminated `${{`)", body.chars().take(40).collect::<String>()));
569                }
570            }
571        } else {
572            out.push('$');
573            rest = after;
574        }
575    }
576    out.push_str(rest);
577    Ok(out)
578}
579
580/// Applies model-name aliases and default parameters before delegating.
581#[cfg(feature = "http")]
582#[derive(Debug)]
583struct Configured {
584    inner: Arc<dyn ChatModel>,
585    models: IndexMap<String, String>,
586    defaults: DefaultParams,
587}
588
589#[cfg(feature = "http")]
590impl ChatModel for Configured {
591    fn chat(&self, mut request: ChatRequest) -> BoxFuture<'_, Result<ChatStream, LlmError>> {
592        if let Some(real) = self.models.get(&request.model) {
593            request.model.clone_from(real);
594        }
595        if request.temperature.is_none() {
596            request.temperature = self.defaults.temperature;
597        }
598        if request.top_p.is_none() {
599            request.top_p = self.defaults.top_p;
600        }
601        if request.max_tokens.is_none() {
602            request.max_tokens = self.defaults.max_tokens;
603        }
604        if request.stop.is_empty() {
605            request.stop.clone_from(&self.defaults.stop);
606        }
607        self.inner.chat(request)
608    }
609}
610
611#[cfg(all(test, feature = "openai"))]
612mod credentials_section_tests {
613    use super::*;
614
615    #[test]
616    fn credentials_section_registers_dynamic_providers() {
617        let config = ProvidersConfig::from_value(serde_json::json!({
618            "providers": [],
619            "credentials": {
620                "proxy": {"source": "env", "kind": "openai", "var": "PROXY_TOKEN", "base_url": "https://proxy.example.com/v1"}
621            }
622        }))
623        .unwrap();
624        assert_eq!(config.credentials.len(), 1);
625        let registry = ModelRegistry::from_config_with_vars(&config, &[]).unwrap();
626        assert!(registry.get("proxy").is_ok());
627
628        let typo = ProvidersConfig::from_value(serde_json::json!({"credentials": {"p": {"source": "env", "vr": "X"}}}));
629        assert!(typo.is_err());
630    }
631
632    #[test]
633    fn host_sources_and_name_clashes_are_rejected_in_files() {
634        let load = |v: serde_json::Value| ProvidersConfig::from_value(v).unwrap().load(&[]);
635        let external = load(serde_json::json!({"credentials": {"openai": {"source": "external"}}}));
636        assert!(external.unwrap_err().to_string().contains("host app"));
637        let clash = load(serde_json::json!({
638            "providers": [{"name": "router", "kind": "openai", "api_key_env": "K", "api_key_optional": true}],
639            "credentials": {"router": {"source": "env", "var": "X", "kind": "openai"}}
640        }));
641        assert!(clash.unwrap_err().to_string().contains("same name"));
642    }
643
644    #[cfg(feature = "typesafe")]
645    #[test]
646    fn typesafe_credentials_build_the_system_one_client() {
647        let config = ProvidersConfig::from_value(
648            serde_json::json!({"credentials": {"typesafe": {"source": "env", "var": "TYPESAFE_API_KEY"}}}),
649        )
650        .unwrap();
651        let loaded = config.load(&[]).unwrap();
652        assert!(loaded.system_one.is_some());
653        assert!(loaded.models.get("typesafe").is_err());
654    }
655
656    #[test]
657    fn unterminated_interpolation_is_an_error() {
658        assert!(interpolate("https://x/${HOST", &[]).is_err());
659        let config = ProvidersConfig::from_value(serde_json::json!({
660            "providers": [{"name": "a", "kind": "openai", "base_url": "https://${HOST/v1", "api_key_optional": true}]
661        }))
662        .unwrap();
663        let err = ModelRegistry::from_config_with_vars(&config, &[]).unwrap_err().to_string();
664        assert!(err.contains("unterminated"), "{err}");
665    }
666}
667
668#[cfg(test)]
669mod tests {
670    use super::*;
671    #[cfg(feature = "mock")]
672    use crate::types::ChatModel;
673    #[cfg(feature = "mock")]
674    use std::sync::Arc;
675
676    fn vars() -> Vec<(String, String)> {
677        vec![("OR_KEY".into(), "sk-or-secret".into()), ("SITE".into(), "https://example.com".into())]
678    }
679
680    #[test]
681    fn interpolation() {
682        let v = vars();
683        assert_eq!(interpolate("${SITE}/x", &v).unwrap(), "https://example.com/x");
684        assert_eq!(interpolate("a$$b $x", &v).unwrap(), "a$b $x");
685        assert!(interpolate("a ${", &v).is_err(), "an unterminated `${{` is an error, not literal text");
686        assert_eq!(interpolate("${NOPE}", &v).unwrap_err(), "NOPE");
687    }
688
689    #[test]
690    fn parses_wrapped_and_list_forms() {
691        let wrapped = ProvidersConfig::from_json(r#"{"providers":[{"name":"a","kind":"openai"}]}"#).unwrap();
692        let list = ProvidersConfig::from_json(r#"[{"name":"a","kind":"openai-compatible"}]"#).unwrap();
693        assert_eq!(wrapped.providers.len(), 1);
694        assert_eq!(list.providers[0].kind, ProviderKind::Openai);
695    }
696
697    #[test]
698    fn typos_are_reported() {
699        let err = ProvidersConfig::from_json(r#"[{"name":"a","kind":"openai","api_key_evn":"X"}]"#).unwrap_err();
700        assert!(err.to_string().contains("api_key_evn"), "{err}");
701        let err = ProvidersConfig::from_json(r#"{"provider":[]}"#).unwrap_err();
702        assert!(err.to_string().contains("provider"), "{err}");
703    }
704
705    #[cfg(all(feature = "openai", feature = "anthropic"))]
706    #[test]
707    fn builds_registry_with_aliases_and_no_secret_leaks() {
708        let cfg = ProvidersConfig::from_json(
709            r#"{"providers":[
710                {"name":"openrouter","kind":"openai","base_url":"https://openrouter.ai/api/v1","api_key_env":"OR_KEY",
711                 "headers":{"HTTP-Referer":"${SITE}"},"aliases":["or"],"models":{"fast":"x/y"},"defaults":{"temperature":0.2}},
712                {"name":"claude","kind":"anthropic","api_key_env":"OR_KEY"},
713                {"name":"local","kind":"openai","base_url":"http://localhost:11434/v1","api_key_env":"NONE","api_key_optional":true}
714            ]}"#,
715        )
716        .unwrap();
717        let registry = ModelRegistry::from_config_with_vars(&cfg, &vars()).unwrap();
718        assert!(registry.get("openrouter").is_ok());
719        assert!(registry.get("or").is_ok());
720        assert!(registry.get("claude").is_ok());
721        assert!(registry.get("local").is_ok());
722        let debug = format!("{registry:?} {:?}", registry.get("openrouter").unwrap());
723        assert!(!debug.contains("sk-or-secret"), "{debug}");
724    }
725
726    #[cfg(feature = "openai")]
727    #[test]
728    fn conflicting_aliases_are_rejected() {
729        let shadow = ProvidersConfig::from_json(
730            r#"[{"name":"a","kind":"openai","base_url":"http://x/v1","aliases":["b"]},
731                {"name":"b","kind":"openai","base_url":"http://y/v1"}]"#,
732        )
733        .unwrap();
734        let err = ModelRegistry::from_config_with_vars(&shadow, &[]).unwrap_err().to_string();
735        assert!(err.contains("alias `b`"), "{err}");
736        let twice = ProvidersConfig::from_json(
737            r#"[{"name":"a","kind":"openai","base_url":"http://x/v1","aliases":["fast"]},
738                {"name":"c","kind":"openai","base_url":"http://y/v1","aliases":["fast"]}]"#,
739        )
740        .unwrap();
741        let err = ModelRegistry::from_config_with_vars(&twice, &[]).unwrap_err().to_string();
742        assert!(err.contains("`fast`") && err.contains("both"), "{err}");
743    }
744
745    #[cfg(feature = "openai")]
746    #[test]
747    fn missing_key_variable_names_the_variable() {
748        let cfg = ProvidersConfig::from_json(r#"[{"name":"a","kind":"openai","api_key_env":"MISSING_KEY"}]"#).unwrap();
749        let err = ModelRegistry::from_config_with_vars(&cfg, &[]).unwrap_err().to_string();
750        assert!(err.contains("MISSING_KEY") && err.contains("`a`"), "{err}");
751        let cfg = ProvidersConfig::from_json(r#"[{"name":"a","kind":"openai","headers":{"X":"${GONE}"}}]"#).unwrap();
752        let err = ModelRegistry::from_config_with_vars(&cfg, &[]).unwrap_err().to_string();
753        assert!(err.contains("GONE"), "{err}");
754    }
755
756    #[cfg(all(feature = "mock", feature = "http"))]
757    #[test]
758    fn model_aliases_and_defaults_are_applied() {
759        use crate::mock::MockModel;
760        use crate::types::Message;
761
762        let mock = Arc::new(MockModel::new(vec![MockModel::text("ok")]));
763        let configured = Configured {
764            inner: Arc::clone(&mock) as Arc<dyn ChatModel>,
765            models: IndexMap::from([("fast".to_owned(), "real-model".to_owned())]),
766            defaults: DefaultParams { temperature: Some(0.3), max_tokens: Some(50), ..DefaultParams::default() },
767        };
768        let request = ChatRequest::new("fast", vec![Message::user("hi")]).with_temperature(0.9);
769        let rt = tokio::runtime::Builder::new_current_thread().build().unwrap();
770        let _stream = rt.block_on(configured.chat(request)).unwrap();
771        let seen = mock.requests();
772        let req = seen.first().unwrap();
773        assert_eq!(req.model, "real-model");
774        assert_eq!(req.temperature, Some(0.9));
775        assert_eq!(req.max_tokens, Some(50));
776    }
777
778    #[cfg(all(feature = "mock", feature = "openai"))]
779    #[test]
780    fn provider_alias_redirects_a_model_to_another_provider() {
781        use crate::mock::MockModel;
782        // A providers file mapping `openai/gpt-4o-mini` to a local `ollama/qwen2.5:14b`.
783        let cfg = ProvidersConfig::from_json(
784            r#"[{"name":"ollama","kind":"openai","base_url":"http://localhost:11434/v1",
785                 "aliases":["openai"],"models":{"gpt-4o-mini":"qwen2.5:14b"}}]"#,
786        )
787        .unwrap();
788        let overlay = ModelRegistry::from_config_with_vars(&cfg, &[]).unwrap();
789        let env_openai: Arc<dyn ChatModel> = Arc::new(MockModel::new(vec![MockModel::text("from env")]));
790        let mut registry = ModelRegistry::new().with("openai", Arc::clone(&env_openai));
791        registry.merge(overlay);
792        let resolved = registry.get("openai").unwrap();
793        assert!(!Arc::ptr_eq(&resolved, &env_openai), "the providers file alias must win");
794        assert!(format!("{resolved:?}").contains("qwen2.5:14b"), "{resolved:?}");
795    }
796
797    #[cfg(all(feature = "gemini", feature = "bedrock"))]
798    #[test]
799    fn gemini_and_bedrock_entries() {
800        let vars: Vec<(String, String)> = [
801            ("GKEY", "AIza-secret"),
802            ("REGION", "ap-southeast-1"),
803            ("AK", "AKID"),
804            ("SK", "aws-secret"),
805            ("BKEY", "bedrock-key"),
806        ]
807        .iter()
808        .map(|(k, v)| ((*k).to_owned(), (*v).to_owned()))
809        .collect();
810        let cfg = ProvidersConfig::from_json(
811            r#"[{"name":"g","kind":"gemini","api_key_env":"GKEY"},
812                {"name":"vertex","kind":"gemini","api_key_env":"GKEY","auth":"bearer","base_url":"https://x/v1/projects/p/locations/l/publishers/google"},
813                {"name":"b","kind":"bedrock","region":"${REGION}","access_key_id_env":"AK","secret_access_key_env":"SK"},
814                {"name":"bk","kind":"bedrock","region":"us-east-1","api_key_env":"BKEY"}]"#,
815        )
816        .unwrap();
817        let reg = ModelRegistry::from_config_with_vars(&cfg, &vars).unwrap();
818        let debug = format!("{:?} {:?} {:?}", reg.get("g").unwrap(), reg.get("vertex").unwrap(), reg.get("b").unwrap());
819        assert!(debug.contains("ap-southeast-1") && debug.contains("Bearer"), "{debug}");
820        assert!(!debug.contains("AIza-secret") && !debug.contains("aws-secret"), "{debug}");
821        assert!(reg.get("bk").is_ok());
822
823        let bad = |json: &str| {
824            let cfg = ProvidersConfig::from_json(json).unwrap();
825            ModelRegistry::from_config_with_vars(&cfg, &vars).unwrap_err().to_string()
826        };
827        assert!(bad(r#"[{"name":"x","kind":"bedrock","region":"us-east-1"}]"#).contains("needs"));
828        assert!(
829            bad(
830                r#"[{"name":"x","kind":"bedrock","region":"us-east-1","api_key_env":"BKEY","access_key_id_env":"AK"}]"#
831            )
832            .contains("either")
833        );
834        assert!(bad(r#"[{"name":"x","kind":"gemini","api_key_env":"GKEY","auth":"oauth"}]"#).contains("auth"));
835        assert!(bad(r#"[{"name":"x","kind":"openai","base_url":"http://x","region":"us-east-1"}]"#).contains("region"));
836        assert!(bad(r#"[{"name":"x","kind":"bedrock","region":"us-east-1","access_key_id_env":"NOPE","secret_access_key_env":"SK"}]"#)
837            .contains("NOPE"));
838    }
839
840    #[cfg(feature = "mock")]
841    #[test]
842    fn merge_replaces_same_named_providers() {
843        use crate::mock::MockModel;
844        let a: Arc<dyn ChatModel> = Arc::new(MockModel::new(vec![MockModel::text("a")]));
845        let b: Arc<dyn ChatModel> = Arc::new(MockModel::new(vec![MockModel::text("b")]));
846        let mut base = ModelRegistry::new().with("openai", Arc::clone(&a));
847        let mut overlay = ModelRegistry::new().with("openai", Arc::clone(&b));
848        overlay.alias("oai", "openai");
849        base.merge(overlay);
850        assert!(Arc::ptr_eq(&base.get("openai").unwrap(), &b));
851        assert!(base.get("oai").is_ok());
852    }
853}