Skip to main content

rig_core/providers/
registry.rs

1//! Serializable provider selections, explicit configurations, and
2//! connecting to a model by reference.
3//!
4//! A model reference is `vendor/model`, split at the first `/`
5//! (`anthropic/claude-opus-5-5`, `ollama/qwen3:4b`). The protocol family it
6//! is reached by comes from the catalog row, and [`ConnectOptions`] can name
7//! another. [`Catalog::connect`] builds a model from a reference with the key
8//! from the environment; a [`ProviderConfig`] is the explicit, serializable
9//! configuration, which discards its credential when written.
10//!
11//! ```no_run
12//! use rig_core::catalog::Catalog;
13//! let model = Catalog::builtin().connect("deepseek/deepseek-chat")?; // DEEPSEEK_API_KEY
14//! # Ok::<(), Box<dyn std::error::Error>>(())
15//! ```
16
17use std::borrow::Cow;
18use std::fmt;
19use std::hash::{Hash, Hasher};
20
21use serde::de;
22use serde::{Deserialize, Deserializer, Serialize, Serializer};
23
24use crate::catalog::{Catalog, ModelFacts, ModelSpec, NotFound, Reference};
25use crate::client::env::{self, EnvError};
26use crate::driver::DynModel;
27use crate::http_client::{DynHttpClient, HttpClientExt};
28use crate::operation::Completion;
29use crate::providers::{anthropic, gemini, openai};
30use crate::serve::ErasedHandler;
31use crate::serve::adapters::ModelAdapter;
32use crate::wire::Secret;
33
34/// Every dialect this build knows, for
35/// [`openai::wire::Dialect`]'s [`Deserialize`](serde::Deserialize) lookup.
36///
37/// Keyed by [`openai::wire::Dialect::name`], so the regional and endpoint variants that
38/// share a provider name are not listed: a stored wire keeps its base URL,
39/// which is what distinguishes them.
40pub(crate) const OPENAI_DIALECTS: &[&openai::wire::Dialect] = &[
41    &openai::wire::OPENAI,
42    &openai::wire::AZURE,
43    &openai::wire::DEEPSEEK,
44    &openai::wire::GROQ,
45    &openai::wire::HYPERBOLIC,
46    &openai::wire::MIRA,
47    &openai::wire::PERPLEXITY,
48    &openai::wire::TOGETHER,
49    &openai::wire::HUGGINGFACE,
50    &openai::wire::LLAMACPP,
51    &openai::wire::MISTRAL,
52    &openai::wire::OPENROUTER,
53    &openai::wire::VENICE,
54    &openai::wire::DOUBLEWORD,
55    &openai::wire::ZAI,
56    &openai::wire::MINIMAX,
57    &openai::wire::MOONSHOT,
58    &openai::wire::XIAOMIMIMO,
59    &openai::wire::COHERE,
60    &openai::wire::OLLAMA,
61    &openai::wire::OPENCODE,
62    &openai::wire::OPENCODE_GO,
63    &crate::providers::xai::DIALECT,
64    &crate::providers::chatgpt::DIALECT,
65    &crate::providers::copilot::wire::DIALECT,
66];
67
68/// A provider's request grammar and configuration type.
69/// The OpenAI family includes Chat Completions and Responses; select the endpoint
70/// through [`openai::OpenAIConfig::with_route`].
71#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
72#[serde(rename_all = "lowercase")]
73pub enum Format {
74    /// OpenAI's grammar: Chat Completions and the Responses endpoint.
75    OpenAi,
76    /// Anthropic's Messages grammar.
77    Anthropic,
78    /// Gemini's GenerateContent grammar.
79    Gemini,
80}
81
82impl Format {
83    /// Every protocol family, in registration order.
84    pub const ALL: [Format; 3] = [Format::OpenAi, Format::Anthropic, Format::Gemini];
85
86    /// The family's stable serialized name.
87    pub fn as_str(self) -> &'static str {
88        match self {
89            Format::OpenAi => "openai",
90            Format::Anthropic => "anthropic",
91            Format::Gemini => "gemini",
92        }
93    }
94
95    /// The family `name` spells, or `None`.
96    pub fn named(name: &str) -> Option<Self> {
97        Self::ALL.into_iter().find(|format| format.as_str() == name)
98    }
99
100    /// Every family's name, for an error message.
101    fn names() -> String {
102        Self::ALL
103            .iter()
104            .map(|format| format.as_str())
105            .collect::<Vec<_>>()
106            .join(", ")
107    }
108}
109
110impl fmt::Display for Format {
111    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
112        f.write_str(self.as_str())
113    }
114}
115
116/// Registered dialect definition and its configuration family.
117#[derive(Debug, Clone, Copy)]
118enum Registered {
119    OpenAi(openai::wire::Dialect),
120    Anthropic(anthropic::wire::Dialect),
121    Gemini,
122}
123
124impl Registered {
125    fn vendor(&self) -> &'static str {
126        match self {
127            Self::OpenAi(dialect) => dialect.name,
128            Self::Anthropic(dialect) => dialect.name,
129            Self::Gemini => gemini::PROVIDER_NAME,
130        }
131    }
132
133    fn format(&self) -> Format {
134        match self {
135            Self::OpenAi(_) => Format::OpenAi,
136            Self::Anthropic(_) => Format::Anthropic,
137            Self::Gemini => Format::Gemini,
138        }
139    }
140
141    fn config(&self, api_key: impl Into<Secret>) -> ProviderConfig {
142        match self {
143            Self::OpenAi(dialect) => {
144                ProviderConfig::OpenAi(openai::wire::OpenAIConfig::with_key(dialect, api_key))
145            }
146            Self::Anthropic(dialect) => ProviderConfig::Anthropic(
147                anthropic::wire::AnthropicConfig::with_key(dialect, api_key),
148            ),
149            Self::Gemini => ProviderConfig::Gemini(gemini::GeminiConfig::new(api_key)),
150        }
151    }
152
153    /// This selection's preset, configured from the environment variables
154    /// its dialect names: the key from the first of
155    /// [`key_envs`](Self::key_envs) set to a non-empty value, and the base
156    /// URL and other settings the dialect reads.
157    fn config_from_env(&self) -> Result<ProviderConfig, ConnectError> {
158        let tried = self.key_envs();
159        let (api_key, name) = key_from_env(self.vendor(), tried, self.requires_credential())?;
160        Ok(match self {
161            Self::OpenAi(dialect) => {
162                let auth = openai_auth(dialect, name);
163                ProviderConfig::OpenAi(openai::wire::OpenAIConfig::from_env_with_credential(
164                    dialect, api_key, auth,
165                )?)
166            }
167            Self::Anthropic(dialect) => ProviderConfig::Anthropic(
168                anthropic::wire::AnthropicConfig::from_env_with_credential(dialect, api_key)?,
169            ),
170            Self::Gemini => ProviderConfig::Gemini(gemini::GeminiConfig::new(api_key)),
171        })
172    }
173
174    /// The variables this selection reads its key from, in order.
175    fn key_envs(&self) -> Vec<&'static str> {
176        match self {
177            Self::OpenAi(dialect) => openai_key_envs(dialect),
178            Self::Anthropic(dialect) => vec![dialect.api_key_env],
179            Self::Gemini => vec![gemini::API_KEY_ENV],
180        }
181    }
182
183    /// The variables that point this selection at a server: its base-URL
184    /// override and that override's alias.
185    fn base_url_envs(&self) -> Vec<&'static str> {
186        let envs = match self {
187            Self::OpenAi(dialect) => [dialect.base_url_env, dialect.quirks.base_url_env_alias],
188            Self::Anthropic(dialect) => [dialect.base_url_env, None],
189            Self::Gemini => [None, None],
190        };
191        envs.into_iter().flatten().collect()
192    }
193
194    /// Whether this selection's key expires within the hour.
195    fn short_lived_key(&self) -> bool {
196        matches!(self, Self::OpenAi(dialect) if dialect.quirks.short_lived_key)
197    }
198
199    /// Whether the catalog's API prices apply to this selection's replies.
200    fn catalog_priced(&self) -> bool {
201        match self {
202            Self::OpenAi(dialect) => dialect.quirks.catalog_priced,
203            Self::Anthropic(dialect) => dialect.quirks.catalog_priced,
204            Self::Gemini => true,
205        }
206    }
207
208    /// Whether this selection needs a credential at all.
209    fn requires_credential(&self) -> bool {
210        match self {
211            Self::OpenAi(dialect) => openai_requires_credential(dialect),
212            Self::Anthropic(dialect) => {
213                dialect.quirks.auth != anthropic::wire::Auth::OptionalBearer
214            }
215            Self::Gemini => true,
216        }
217    }
218}
219
220/// The variables an OpenAI-family `dialect` reads its key from: its own,
221/// then its alternative's.
222fn openai_key_envs(dialect: &openai::wire::Dialect) -> Vec<&'static str> {
223    std::iter::once(dialect.api_key_env)
224        .chain(
225            dialect
226                .alternate_auth
227                .map(|alternative| alternative.api_key_env),
228        )
229        .collect()
230}
231
232/// Whether an OpenAI-family `dialect` needs a credential: a local
233/// `llama-server` or Ollama daemon authenticates optionally.
234fn openai_requires_credential(dialect: &openai::wire::Dialect) -> bool {
235    !matches!(dialect.quirks.auth, openai::wire::Auth::OptionalBearer)
236}
237
238/// How an OpenAI-family `dialect` sends a key read from the variable
239/// `name`: its alternative's way for the alternative's variable, its own
240/// otherwise.
241fn openai_auth(dialect: &openai::wire::Dialect, name: Option<&'static str>) -> openai::wire::Auth {
242    match dialect.alternate_auth {
243        Some(alternative) if name == Some(alternative.api_key_env) => alternative.auth,
244        _ => dialect.quirks.auth,
245    }
246}
247
248/// The key the first of `tried` holds, and its name. An empty value counts
249/// as unset. When none is set, a vendor that needs no credential gets an
250/// empty key, and any other is [`ConnectError::MissingKey`].
251fn key_from_env(
252    vendor: &str,
253    tried: Vec<&'static str>,
254    required: bool,
255) -> Result<(String, Option<&'static str>), ConnectError> {
256    for name in &tried {
257        if let Some(value) = env::optional(name)?.filter(|value| !value.is_empty()) {
258            return Ok((value, Some(*name)));
259        }
260    }
261    if required {
262        return Err(ConnectError::MissingKey {
263            vendor: vendor.to_owned(),
264            tried: tried.into_iter().map(Cow::Borrowed).collect(),
265        });
266    }
267    Ok((String::new(), None))
268}
269
270/// A provider the model catalog files models under that the registry cannot
271/// configure: an SDK-backed or local provider in a companion crate, or one
272/// that serves no completions.
273#[derive(Debug)]
274struct CatalogOnly {
275    /// The provider's own descriptor name.
276    vendor: &'static str,
277    /// Where its models are served from, for the error `connect` returns.
278    home: &'static str,
279    /// Whether it needs a credential.
280    credential: bool,
281}
282
283/// Every catalog-only provider.
284static CATALOG_ONLY: [CatalogOnly; 5] = [
285    CatalogOnly {
286        vendor: "aws_bedrock",
287        home: "the `rig-bedrock` crate",
288        credential: true,
289    },
290    CatalogOnly {
291        vendor: "vertexai",
292        home: "the `rig-vertexai` crate",
293        credential: true,
294    },
295    CatalogOnly {
296        vendor: "gemini-grpc",
297        home: "the `rig-gemini-grpc` crate",
298        credential: true,
299    },
300    CatalogOnly {
301        vendor: "candle",
302        home: "the `rig-candle` crate",
303        credential: false,
304    },
305    CatalogOnly {
306        vendor: "voyageai",
307        home: "`rig_core::providers::voyageai`, which serves embeddings and reranking only",
308        credential: true,
309    },
310];
311
312/// What a [`ProviderId`] names.
313#[derive(Debug, Clone, Copy)]
314enum Kind {
315    /// A selection the registry configures.
316    Registered(Registered),
317    /// A provider only the model catalog names.
318    CatalogOnly(&'static CatalogOnly),
319    /// A vendor declared at run time ([`ProviderId::declare`]).
320    Declared(&'static str),
321}
322
323/// The vendors declared at run time, each name stored once for the life of
324/// the process, so a declared [`ProviderId`] stays `Copy` and names its
325/// vendor as `&'static str` like a built-in one.
326static DECLARED: std::sync::RwLock<Vec<&'static str>> = std::sync::RwLock::new(Vec::new());
327
328/// The declared vendor named `vendor`, if any.
329fn declared(vendor: &str) -> Option<&'static str> {
330    DECLARED
331        .read()
332        .unwrap_or_else(std::sync::PoisonError::into_inner)
333        .iter()
334        .copied()
335        .find(|name| *name == vendor)
336}
337
338/// Validated vendor and protocol-family pair from this build's dialect tables,
339/// a catalog-only provider the registry cannot configure, or a vendor
340/// declared at run time ([`Self::declare`]). Construction and
341/// deserialization reject unregistered pairs; only [`ProviderId::catalog`],
342/// [`ProviderId::declare`] and the model catalog produce a catalog-only or
343/// declared id, which has no format and no preset. Equality and hashing use
344/// the pair, not dialect options; display emits `vendor/format`, or the
345/// vendor alone for a catalog-only or declared id.
346#[derive(Debug, Clone, Copy)]
347pub struct ProviderId(Kind);
348
349/// Identity is the `(vendor, format)` pair, never the dialect's payload: two
350/// ids that name the same selection are the same id.
351impl PartialEq for ProviderId {
352    fn eq(&self, other: &Self) -> bool {
353        self.vendor() == other.vendor() && self.format() == other.format()
354    }
355}
356
357impl Eq for ProviderId {}
358
359impl Hash for ProviderId {
360    fn hash<H: Hasher>(&self, state: &mut H) {
361        self.vendor().hash(state);
362        self.format().hash(state);
363    }
364}
365
366impl ProviderId {
367    /// Every selection this build registers: one per OpenAI-shaped dialect,
368    /// one per Messages-format dialect, and Gemini. Catalog-only providers
369    /// are not selections.
370    pub fn all() -> impl Iterator<Item = ProviderId> {
371        openai::wire::all()
372            .map(|dialect| Registered::OpenAi(*dialect))
373            .chain(anthropic::wire::all().map(|dialect| Registered::Anthropic(*dialect)))
374            .chain(std::iter::once(Registered::Gemini))
375            .map(|registered| ProviderId(Kind::Registered(registered)))
376    }
377
378    /// The selection `vendor` names in `format`, or `None` when this build
379    /// registers no such pair.
380    pub fn new(vendor: &str, format: Format) -> Option<Self> {
381        let registered = match format {
382            Format::OpenAi => {
383                openai::wire::by_name(vendor).map(|dialect| Registered::OpenAi(*dialect))
384            }
385            Format::Anthropic => {
386                anthropic::wire::Dialect::by_name(vendor).map(Registered::Anthropic)
387            }
388            Format::Gemini => (vendor == gemini::PROVIDER_NAME).then_some(Registered::Gemini),
389        };
390        registered.map(|registered| Self(Kind::Registered(registered)))
391    }
392
393    /// The id the model catalog files `vendor`'s models under: its
394    /// primary selection, or a catalog-only id for a provider the registry
395    /// cannot configure (`aws_bedrock`, `vertexai`, `gemini-grpc`, `candle`,
396    /// `voyageai`). `None` for a vendor this build does not know.
397    ///
398    /// A vendor registered in one family has that family as its primary.
399    /// The vendors registered in two declare theirs: Anthropic's for
400    /// `minimax`, OpenAI's for `zai`, `moonshot`, `xiaomimimo`, `ollama`,
401    /// `opencode` and `opencode-go`. A model reference that names no family
402    /// is reached by its catalog row's, which is the primary unless the row
403    /// says otherwise.
404    pub fn catalog(vendor: &str) -> Option<Self> {
405        let primary = primary(vendor).and_then(|format| Self::new(vendor, format));
406        primary
407            .or_else(|| Self::vendor_selections(vendor).next())
408            .or_else(|| {
409                CATALOG_ONLY
410                    .iter()
411                    .find(|provider| provider.vendor == vendor)
412                    .map(|provider| Self(Kind::CatalogOnly(provider)))
413            })
414            .or_else(|| declared(vendor).map(|name| Self(Kind::Declared(name))))
415    }
416
417    /// Declare `vendor`, a provider this build has no preset for, such as a
418    /// company gateway (`corp`) or a local server under a name of its own,
419    /// and return the id the catalog files its models under. From then on
420    /// [`Self::catalog`] finds it, so `corp/big` resolves, parses and reads
421    /// back like a built-in reference once the catalog lists the model
422    /// ([`Catalog::insert`]). The registry cannot configure it: whoever
423    /// declares it says how its models are reached, such as with
424    /// [`Connector::provide`](crate::catalog::Connector::provide) or by
425    /// building a [`ProviderConfig`] from a dialect of its own.
426    ///
427    /// Declaring is idempotent and process-wide. A vendor this build already
428    /// knows comes back as [`Self::catalog`] gives it.
429    ///
430    /// ```
431    /// use rig_core::catalog::{Catalog, ModelSpec};
432    /// use rig_core::providers::registry::ProviderId;
433    ///
434    /// let corp = ProviderId::declare("corp")?;
435    /// let mut catalog = Catalog::builtin().clone();
436    /// catalog.insert(ModelSpec::new(corp, "big").with_tools(true));
437    /// assert_eq!(catalog.resolve("corp/big").map_err(|e| e.to_string())?.spec.provider, corp);
438    /// assert_eq!(ProviderId::declare("anthropic")?, ProviderId::catalog("anthropic").ok_or("known")?);
439    /// # Ok::<(), Box<dyn std::error::Error>>(())
440    /// ```
441    ///
442    /// # Errors
443    ///
444    /// [`SelectionError::Malformed`] for an empty name, or one with a `/`
445    /// or whitespace, which a `vendor/model` reference could not spell.
446    pub fn declare(vendor: &str) -> Result<Self, SelectionError> {
447        if vendor.is_empty() || vendor.contains('/') || vendor.contains(char::is_whitespace) {
448            return Err(SelectionError::Malformed {
449                selection: vendor.to_owned(),
450            });
451        }
452        if let Some(known) = Self::catalog(vendor) {
453            return Ok(known);
454        }
455        let mut names = DECLARED
456            .write()
457            .unwrap_or_else(std::sync::PoisonError::into_inner);
458        let name = match names.iter().copied().find(|name| *name == vendor) {
459            Some(name) => name,
460            None => {
461                let name: &'static str = Box::leak(vendor.to_owned().into_boxed_str());
462                names.push(name);
463                name
464            }
465        };
466        Ok(Self(Kind::Declared(name)))
467    }
468
469    /// Every vendor name [`Self::catalog`] knows, registered, catalog-only
470    /// or declared. A vendor registered in two families appears twice.
471    pub(crate) fn catalog_vendors() -> impl Iterator<Item = &'static str> {
472        let declared: Vec<&'static str> = DECLARED
473            .read()
474            .unwrap_or_else(std::sync::PoisonError::into_inner)
475            .clone();
476        Self::all()
477            .map(|id| id.vendor())
478            .chain(CATALOG_ONLY.iter().map(|provider| provider.vendor))
479            .chain(declared)
480    }
481
482    /// The vendor, spelled as the provider's own descriptor name.
483    pub fn vendor(&self) -> &'static str {
484        match &self.0 {
485            Kind::Registered(registered) => registered.vendor(),
486            Kind::CatalogOnly(provider) => provider.vendor,
487            Kind::Declared(vendor) => vendor,
488        }
489    }
490
491    /// The protocol family, or `None` for a catalog-only or declared
492    /// provider.
493    pub fn format(&self) -> Option<Format> {
494        match &self.0 {
495            Kind::Registered(registered) => Some(registered.format()),
496            Kind::CatalogOnly(_) | Kind::Declared(_) => None,
497        }
498    }
499
500    /// Whether the registry can configure this provider. A catalog-only
501    /// provider is served by its companion crate instead, and a declared one
502    /// by whoever declared it.
503    pub fn is_registered(&self) -> bool {
504        matches!(self.0, Kind::Registered(_))
505    }
506
507    /// Whether this is a vendor declared at run time ([`Self::declare`]).
508    pub fn is_declared(&self) -> bool {
509        matches!(self.0, Kind::Declared(_))
510    }
511
512    /// Every selection registered for `vendor`, in registration order.
513    pub fn vendor_selections(vendor: &str) -> impl Iterator<Item = ProviderId> + '_ {
514        Self::all().filter(move |id| id.vendor() == vendor)
515    }
516
517    /// Resolve `vendor` or `vendor/format`.
518    ///
519    /// A bare vendor is accepted only when this build registers exactly one
520    /// family for it; otherwise the error names the qualified alternatives,
521    /// each of which this resolver accepts. A catalog-only provider is not a
522    /// selection, so it does not resolve.
523    pub fn resolve(selection: &str) -> Result<Self, SelectionError> {
524        let malformed = || SelectionError::Malformed {
525            selection: selection.to_owned(),
526        };
527        let (vendor, format) = match selection.split_once('/') {
528            Some((_, rest)) if rest.contains('/') => return Err(malformed()),
529            Some((vendor, format)) => (vendor, Some(format)),
530            None => (selection, None),
531        };
532        if vendor.is_empty() {
533            return Err(malformed());
534        }
535        let Some(format) = format else {
536            let mut registered = Self::vendor_selections(vendor);
537            let first = registered.next().ok_or_else(|| SelectionError::Unknown {
538                vendor: vendor.to_owned(),
539            })?;
540            return match registered.next() {
541                None => Ok(first),
542                Some(_) => Err(SelectionError::Ambiguous {
543                    vendor: vendor.to_owned(),
544                    alternatives: alternatives(vendor),
545                }),
546            };
547        };
548        let Some(family) = Format::named(format) else {
549            return Err(SelectionError::UnknownFormat {
550                format: format.to_owned(),
551            });
552        };
553        Self::selection(vendor, family)
554    }
555
556    /// Build this selection's preset with `api_key`, or `None` for a
557    /// catalog-only or declared provider. Copilot requires an exchanged
558    /// session token, not a GitHub OAuth token.
559    pub fn config(&self, api_key: impl Into<Secret>) -> Option<ProviderConfig> {
560        match &self.0 {
561            Kind::Registered(registered) => Some(registered.config(api_key)),
562            Kind::CatalogOnly(_) | Kind::Declared(_) => None,
563        }
564    }
565
566    /// The environment variables tried for the key, in order: the
567    /// dialect's own, then its alternative credential's (Azure's
568    /// `AZURE_TOKEN`). An empty value counts as unset. Empty for a
569    /// catalog-only provider, whose companion crate reads its own
570    /// credentials, and for a declared one.
571    pub fn api_key_envs(&self) -> Vec<&'static str> {
572        match &self.0 {
573            Kind::Registered(registered) => registered.key_envs(),
574            Kind::CatalogOnly(_) | Kind::Declared(_) => Vec::new(),
575        }
576    }
577
578    /// Whether this selection needs a credential at all. `false` for a
579    /// declared provider: whoever reaches it holds what it needs.
580    ///
581    /// A local `llama-server` authenticates optionally, so naming its
582    /// variable is a hint rather than a requirement.
583    pub fn requires_credential(&self) -> bool {
584        match &self.0 {
585            Kind::Registered(registered) => registered.requires_credential(),
586            Kind::CatalogOnly(provider) => provider.credential,
587            Kind::Declared(_) => false,
588        }
589    }
590
591    /// Whether the environment sets this selection's key or base URL to a
592    /// non-empty value: what makes a provider that needs no credential,
593    /// such as a local server, configured rather than merely reachable at
594    /// its default address. `false` for a catalog-only or declared provider.
595    pub(crate) fn configured_in_env(&self) -> bool {
596        let Kind::Registered(registered) = &self.0 else {
597            return false;
598        };
599        let set = |name: &'static str| {
600            env::optional(name).is_ok_and(|value| value.is_some_and(|value| !value.is_empty()))
601        };
602        let mut envs = registered
603            .key_envs()
604            .into_iter()
605            .chain(registered.base_url_envs());
606        envs.any(set)
607    }
608
609    /// Whether this selection's key is a session token that expires within
610    /// the hour, so a key saved for later runs soon stops working.
611    pub fn short_lived_key(&self) -> bool {
612        matches!(&self.0, Kind::Registered(registered) if registered.short_lived_key())
613    }
614
615    /// Whether the catalog's API prices apply to this provider's replies: a
616    /// subscription backend or a usually local server has none.
617    pub(crate) fn catalog_priced(&self) -> bool {
618        match &self.0 {
619            Kind::Registered(registered) => registered.catalog_priced(),
620            Kind::CatalogOnly(_) | Kind::Declared(_) => true,
621        }
622    }
623
624    /// The registered selection, or [`ConnectError::CatalogOnly`].
625    fn registered(self) -> Result<Registered, ConnectError> {
626        match self.0 {
627            Kind::Registered(registered) => Ok(registered),
628            Kind::CatalogOnly(provider) => Err(ConnectError::CatalogOnly {
629                vendor: provider.vendor.to_owned(),
630                served_by: provider.home,
631            }),
632            Kind::Declared(vendor) => Err(ConnectError::CatalogOnly {
633                vendor: vendor.to_owned(),
634                served_by: "whoever declared it: provide it with `Connector::provide`",
635            }),
636        }
637    }
638
639    /// `vendor` in `format`, or why this build registers no such pair.
640    fn selection(vendor: &str, format: Format) -> Result<Self, SelectionError> {
641        Self::new(vendor, format).ok_or_else(|| {
642            let alternatives = alternatives(vendor);
643            match alternatives.is_empty() {
644                true => SelectionError::Unknown {
645                    vendor: vendor.to_owned(),
646                },
647                false => SelectionError::Unregistered {
648                    vendor: vendor.to_owned(),
649                    format,
650                    alternatives,
651                },
652            }
653        })
654    }
655}
656
657/// The primary family of `vendor` when it is registered in more than one,
658/// as models.dev lists the vendor's own API. [`ProviderId::catalog`] reads it.
659fn primary(vendor: &str) -> Option<Format> {
660    match vendor {
661        "minimax" => Some(Format::Anthropic),
662        "zai" | "moonshot" | "xiaomimimo" | "ollama" | "opencode" | "opencode-go" => {
663            Some(Format::OpenAi)
664        }
665        _ => None,
666    }
667}
668
669/// The qualified spellings registered for `vendor`, in registration order.
670fn alternatives(vendor: &str) -> Vec<String> {
671    ProviderId::vendor_selections(vendor)
672        .map(|id| id.to_string())
673        .collect()
674}
675
676impl fmt::Display for ProviderId {
677    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
678        match self.format() {
679            Some(format) => write!(f, "{}/{format}", self.vendor()),
680            None => f.write_str(self.vendor()),
681        }
682    }
683}
684
685impl Serialize for ProviderId {
686    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
687        serializer.collect_str(self)
688    }
689}
690
691/// Reads a selection as [`ProviderId::resolve`] does, and a catalog-only or
692/// declared provider by its vendor name, so a catalog id reads back. A
693/// declared vendor reads back only once this process declared it.
694impl<'de> Deserialize<'de> for ProviderId {
695    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
696        let selection = String::deserialize(deserializer)?;
697        Self::resolve(&selection)
698            .or_else(|error| {
699                Self::catalog(&selection)
700                    .filter(|id| !id.is_registered())
701                    .ok_or(error)
702            })
703            .map_err(de::Error::custom)
704    }
705}
706
707/// Why a provider selection did not resolve.
708#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
709pub enum SelectionError {
710    /// No registered provider goes by this vendor name.
711    #[error("no registered provider is named `{vendor}`")]
712    Unknown {
713        /// The vendor named.
714        vendor: String,
715    },
716    /// The vendor is registered, but not for this protocol family.
717    #[error(
718        "`{vendor}` speaks no {format} endpoint in this build (it speaks {})",
719        alternatives.join(", ")
720    )]
721    Unregistered {
722        /// The vendor named.
723        vendor: String,
724        /// The family named.
725        format: Format,
726        /// The vendor's registered selections, canonically spelled.
727        alternatives: Vec<String>,
728    },
729    /// A bare vendor with more than one registered family.
730    #[error(
731        "`{vendor}` names more than one registered selection: name one of {}",
732        alternatives.join(", ")
733    )]
734    Ambiguous {
735        /// The vendor named.
736        vendor: String,
737        /// The vendor's registered selections, canonically spelled.
738        alternatives: Vec<String>,
739    },
740    /// The family is not one this crate knows.
741    #[error("`{format}` is not a protocol family ({})", Format::names())]
742    UnknownFormat {
743        /// The family named.
744        format: String,
745    },
746    /// Not `vendor` or `vendor/format` at all.
747    #[error("`{selection}` is not a provider selection: expected `vendor` or `vendor/format`")]
748    Malformed {
749        /// What was given.
750        selection: String,
751    },
752}
753
754/// A provider configuration tagged by protocol family, such as `{"openai": {…}}`.
755/// Serialization rejects unregistered or modified dialect definitions. Set
756/// persistent hosts and typed options on the configuration, not the dialect.
757/// Deserialization reports unknown configuration fields by name.
758#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
759#[serde(rename_all = "lowercase")]
760pub enum ProviderConfig {
761    /// An OpenAI-shaped provider, on either of its two endpoints.
762    OpenAi(openai::wire::OpenAIConfig),
763    /// A Messages-format provider.
764    Anthropic(anthropic::wire::AnthropicConfig),
765    /// Gemini.
766    Gemini(gemini::GeminiConfig),
767}
768
769impl ProviderConfig {
770    /// The catalog selection with this dialect's name, if registered.
771    /// Host and option overrides do not change the selection; its preset
772    /// remains the catalog's, never a custom dialect's payload.
773    pub fn id(&self) -> Option<ProviderId> {
774        ProviderId::new(self.vendor(), self.format())
775    }
776
777    /// The configured dialect's name, including unregistered dialects.
778    pub fn vendor(&self) -> &'static str {
779        match self {
780            Self::OpenAi(provider) => provider.dialect.name,
781            Self::Anthropic(provider) => provider.dialect.name,
782            Self::Gemini(_) => gemini::PROVIDER_NAME,
783        }
784    }
785
786    /// The configuration family, independently of catalog membership.
787    pub fn format(&self) -> Format {
788        match self {
789            Self::OpenAi(_) => Format::OpenAi,
790            Self::Anthropic(_) => Format::Anthropic,
791            Self::Gemini(_) => Format::Gemini,
792        }
793    }
794
795    /// Whether the credential is empty, as it is after serialization round-trip
796    /// because [`Secret`] omits its value.
797    pub fn is_unauthenticated(&self) -> bool {
798        match self {
799            Self::OpenAi(provider) => provider.api_key.is_empty(),
800            Self::Anthropic(provider) => provider.api_key.is_empty(),
801            Self::Gemini(provider) => provider.api_key.is_empty(),
802        }
803    }
804
805    /// The same configuration with `api_key` as its credential: how a host
806    /// rehydrates a configuration it loaded from data.
807    pub fn with_credential(mut self, api_key: impl Into<Secret>) -> Self {
808        let api_key = api_key.into();
809        match &mut self {
810            Self::OpenAi(provider) => provider.api_key = api_key,
811            Self::Anthropic(provider) => provider.api_key = api_key,
812            Self::Gemini(provider) => provider.api_key = api_key,
813        }
814        self
815    }
816
817    /// The base URL this configuration sends requests to. Endpoint paths,
818    /// such as `/chat/completions` or `/v1/messages`, resolve against it.
819    /// A route the dialect serves at the server root drops a trailing `/v1`
820    /// from it first.
821    ///
822    /// A Copilot preset built with a session token holds the endpoint that
823    /// token names. [`with_credential`](Self::with_credential) keeps the URL
824    /// it finds.
825    pub fn base_url(&self) -> &str {
826        match self {
827            Self::OpenAi(provider) => &provider.base_url,
828            Self::Anthropic(provider) => &provider.base_url,
829            Self::Gemini(provider) => &provider.base_url,
830        }
831    }
832
833    /// The same configuration sending to `base_url`, such as a proxy, with
834    /// every other setting kept. A Messages-format configuration normalizes
835    /// the URL with [`anthropic::wire::normalize_base_url`].
836    pub fn with_base_url(self, base_url: impl Into<String>) -> Self {
837        let base_url = base_url.into();
838        match self {
839            Self::OpenAi(provider) => Self::OpenAi(provider.with_base_url(base_url)),
840            Self::Anthropic(provider) => Self::Anthropic(provider.with_base_url(base_url)),
841            Self::Gemini(provider) => Self::Gemini(provider.with_base_url(base_url)),
842        }
843    }
844
845    /// The completion wire for `model`, bound to `http` and encoding and
846    /// pricing with `facts`, erased behind a [`ModelAdapter`] labelled
847    /// `label`: [`Self::completion_model`] as an effect handler.
848    pub fn completion_handler(
849        &self,
850        label: &str,
851        model: &str,
852        http: DynHttpClient,
853        facts: ModelFacts,
854    ) -> ErasedHandler {
855        ErasedHandler::new(ModelAdapter::new(
856            label,
857            self.completion_model(model, http, facts),
858        ))
859    }
860
861    /// The provider's completion model for `model` on `http`, encoding with
862    /// `facts` and pricing its replies by them, erased: how a model the
863    /// catalog lists under a declared vendor ([`ProviderId::declare`]) is
864    /// reached on a gateway of its own, with its catalog prices. Pass
865    /// [`ModelFacts::new`] of the model's spec, or
866    /// [`Catalog::facts`](crate::catalog::Catalog::facts).
867    ///
868    /// The model uses the provider's own completion wire, including
869    /// Copilot's model-dependent routing and request envelope. Explicit
870    /// hosts, routes and typed options are preserved.
871    pub fn completion_model(
872        &self,
873        model: &str,
874        http: DynHttpClient,
875        facts: ModelFacts,
876    ) -> DynModel<Completion> {
877        match self {
878            Self::OpenAi(provider) => {
879                let wire = openai::wire::OpenAiWire::routed(provider.clone(), model, &facts)
880                    .with_facts(facts);
881                provider.clone().connect(http).model(wire).erase()
882            }
883            Self::Anthropic(provider) => {
884                let mut model = provider.clone().connect(http).completion(model);
885                model.wire = model.wire.with_facts(facts);
886                model.erase()
887            }
888            Self::Gemini(provider) => {
889                let mut model = provider.clone().connect(http).completion(model);
890                model.wire = model.wire.with_facts(facts);
891                model.erase()
892            }
893        }
894    }
895}
896
897/// What [`Catalog::connect`] connects to: a catalog entry, or a
898/// `vendor/model` reference, as [`Catalog::resolve`] reads one.
899#[non_exhaustive]
900#[derive(Clone, Copy, Debug)]
901pub enum ModelSelector<'a> {
902    /// A catalog entry: its provider, family and id.
903    Spec(&'a ModelSpec),
904    /// `vendor/model`, or the older `vendor/format:model`.
905    Reference(&'a str),
906}
907
908impl<'a> From<&'a ModelSpec> for ModelSelector<'a> {
909    fn from(spec: &'a ModelSpec) -> Self {
910        Self::Spec(spec)
911    }
912}
913
914impl<'a> From<&'a str> for ModelSelector<'a> {
915    fn from(reference: &'a str) -> Self {
916        Self::Reference(reference)
917    }
918}
919
920impl<'a> From<&'a String> for ModelSelector<'a> {
921    fn from(reference: &'a String) -> Self {
922        Self::Reference(reference)
923    }
924}
925
926/// How [`Catalog::connect_with`] connects: an explicit key and the account
927/// it belongs to, an HTTP client, a protocol family and a base URL. Each one
928/// left unset takes its default: the key from the environment, the shared
929/// reqwest client, the family the catalog row is reached by, and the
930/// dialect's base URL.
931///
932/// ```no_run
933/// use rig_core::catalog::Catalog;
934/// use rig_core::providers::registry::{ConnectOptions, Format};
935///
936/// let options = ConnectOptions::new().format(Format::Anthropic);
937/// let model = Catalog::builtin().connect_with("zai/glm-5", options)?;
938/// # Ok::<(), Box<dyn std::error::Error>>(())
939/// ```
940#[non_exhaustive]
941#[derive(Clone, Default)]
942pub struct ConnectOptions {
943    api_key: Option<Secret>,
944    account_id: Option<String>,
945    pub(crate) http: Option<DynHttpClient>,
946    format: Option<Format>,
947    base_url: Option<String>,
948}
949
950impl ConnectOptions {
951    /// No option set.
952    pub fn new() -> Self {
953        Self::default()
954    }
955
956    /// Credential with `api_key` instead of reading the environment. Only
957    /// the key is given: no other variable is read either.
958    pub fn api_key(mut self, api_key: impl Into<Secret>) -> Self {
959        self.api_key = Some(api_key.into());
960        self
961    }
962
963    /// Name `account_id` as the account the key belongs to, as a ChatGPT
964    /// subscription credential needs (the `ChatGPT-Account-Id` header).
965    /// Only the OpenAI family sends it; the others ignore it.
966    ///
967    /// ```no_run
968    /// use rig_core::catalog::Catalog;
969    /// use rig_core::providers::registry::ConnectOptions;
970    ///
971    /// let options = ConnectOptions::new().api_key("access-token").account_id("account");
972    /// let model = Catalog::builtin().connect_with("chatgpt/gpt-6.2-sol", options)?;
973    /// # Ok::<(), Box<dyn std::error::Error>>(())
974    /// ```
975    pub fn account_id(mut self, account_id: impl Into<String>) -> Self {
976        self.account_id = Some(account_id.into());
977        self
978    }
979
980    /// Send through `http` instead of the shared reqwest client.
981    pub fn http(mut self, http: impl HttpClientExt + 'static) -> Self {
982        self.http = Some(DynHttpClient::new(http));
983        self
984    }
985
986    /// Speak `format` instead of the family the catalog row is reached by.
987    /// The vendor must be registered for it.
988    pub fn format(mut self, format: Format) -> Self {
989        self.format = Some(format);
990        self
991    }
992
993    /// Send to `base_url`, such as a proxy, instead of the dialect's.
994    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
995        self.base_url = Some(base_url.into());
996        self
997    }
998}
999
1000/// Never shows the key.
1001impl fmt::Debug for ConnectOptions {
1002    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1003        f.debug_struct("ConnectOptions")
1004            .field("api_key", &self.api_key.as_ref().map(|_| "<set>"))
1005            .field("account_id", &self.account_id.as_ref().map(|_| "<set>"))
1006            .field("http", &self.http.as_ref().map(|_| "<set>"))
1007            .field("format", &self.format)
1008            .field("base_url", &self.base_url)
1009            .finish()
1010    }
1011}
1012
1013/// Why [`Catalog::connect`] built no model.
1014#[non_exhaustive]
1015#[derive(Debug, thiserror::Error)]
1016pub enum ConnectError {
1017    /// The reference is not `vendor/model`.
1018    #[error("`{reference}` names no model: expected `vendor/model`")]
1019    Malformed {
1020        /// What was given.
1021        reference: String,
1022    },
1023    /// The provider is one only the catalog knows; its companion crate
1024    /// serves its models.
1025    #[error("the registry cannot connect to `{vendor}`: its models are served by {served_by}")]
1026    CatalogOnly {
1027        /// The provider's vendor name.
1028        vendor: String,
1029        /// Where its models are served from.
1030        served_by: &'static str,
1031    },
1032    /// The reference names a vendor this build does not know. Its
1033    /// suggestions are close references the catalog lists.
1034    #[error(transparent)]
1035    NotFound(#[from] NotFound),
1036    /// The vendor is not registered for the family asked for.
1037    #[error(transparent)]
1038    Selection(#[from] SelectionError),
1039    /// No key was given and none of these variables is set to a non-empty
1040    /// value.
1041    #[error(
1042        "no key for `{vendor}`: set {} or pass one with `ConnectOptions::api_key`",
1043        tried.iter().map(|name| format!("`{name}`")).collect::<Vec<_>>().join(" or ")
1044    )]
1045    MissingKey {
1046        /// The vendor.
1047        vendor: String,
1048        /// The variables read, in order: built-in names, or names a
1049        /// provider reads at run time.
1050        tried: Vec<Cow<'static, str>>,
1051    },
1052    /// The provider serving the model failed, in its own words, such as a
1053    /// [`Provide`](crate::catalog::Provide) whose gateway is not configured.
1054    #[error("{0}")]
1055    Provider(String),
1056    /// A variable the dialect reads is set but unusable.
1057    #[error(transparent)]
1058    Env(#[from] EnvError),
1059    /// No HTTP client was given, and this build has no shared one (the
1060    /// `reqwest` feature is off).
1061    #[error("no HTTP client: pass one with `ConnectOptions::http`")]
1062    NoHttpClient,
1063}
1064
1065impl Catalog {
1066    /// The completion model `model` selects, with the key from the
1067    /// environment, on the shared reqwest client. See
1068    /// [`Self::connect_with`].
1069    ///
1070    /// ```no_run
1071    /// use rig_core::catalog::Catalog;
1072    ///
1073    /// let catalog = Catalog::builtin();
1074    /// let model = catalog.connect("anthropic/claude-opus-5-5")?; // ANTHROPIC_API_KEY
1075    /// let spec = catalog.resolve("openai/gpt-5.5")?.spec;
1076    /// let other = catalog.connect(spec)?; // OPENAI_API_KEY
1077    /// # Ok::<(), Box<dyn std::error::Error>>(())
1078    /// ```
1079    #[cfg(feature = "reqwest")]
1080    #[cfg_attr(docsrs, doc(cfg(feature = "reqwest")))]
1081    pub fn connect<'a>(
1082        &self,
1083        model: impl Into<ModelSelector<'a>>,
1084    ) -> Result<DynModel<Completion>, ConnectError> {
1085        self.connect_with(model, ConnectOptions::new())
1086    }
1087
1088    /// The completion model `model` selects, connected as `options` say.
1089    ///
1090    /// A reference is read as [`Self::resolve`] reads it, and the model id
1091    /// is sent as written. A model this catalog does not list still
1092    /// connects, on a vendor it knows. The family is `options`'s, else the
1093    /// one the older `vendor/format:model` spelling names, else the one the
1094    /// catalog row (or the spec) is reached by, else the vendor's primary.
1095    /// Unless `options` give a key, it is read from the first of the
1096    /// vendor's [`api_key_envs`](ProviderId::api_key_envs) set to a
1097    /// non-empty value, along with the base URL and other settings its
1098    /// dialect reads from the environment. An account `options` name
1099    /// replaces the one the dialect reads.
1100    ///
1101    /// The model encodes and prices with this catalog's facts: the spec it
1102    /// was connected from, and this catalog for any other model a request
1103    /// names, so the catalog's overrides reach its requests and reported
1104    /// cost.
1105    ///
1106    /// # Errors
1107    ///
1108    /// [`ConnectError::Malformed`] for a reference that is not
1109    /// `vendor/model`, [`ConnectError::NotFound`] for an unknown vendor,
1110    /// [`ConnectError::CatalogOnly`] for a provider a companion crate
1111    /// serves, [`ConnectError::Selection`] for a family the vendor is not
1112    /// registered for, [`ConnectError::MissingKey`] when no key is given or
1113    /// set, and [`ConnectError::NoHttpClient`] without the `reqwest`
1114    /// feature and an HTTP client.
1115    pub fn connect_with<'a>(
1116        &self,
1117        model: impl Into<ModelSelector<'a>>,
1118        options: ConnectOptions,
1119    ) -> Result<DynModel<Completion>, ConnectError> {
1120        let (provider, model, facts) = match model.into() {
1121            ModelSelector::Spec(spec) => (
1122                spec.provider,
1123                spec.id.as_str(),
1124                ModelFacts::new(spec.clone()).with_catalog(self),
1125            ),
1126            ModelSelector::Reference(text) => {
1127                let reference = Reference::parse(text).ok_or_else(|| ConnectError::Malformed {
1128                    reference: text.to_owned(),
1129                })?;
1130                let vendor =
1131                    ProviderId::catalog(reference.vendor).ok_or_else(|| self.not_found(text))?;
1132                let provider = self
1133                    .get_vendor(reference.vendor, reference.model)
1134                    .map_or(vendor, |resolved| resolved.spec.provider);
1135                let provider = match reference.format {
1136                    Some(format) if provider.is_registered() => {
1137                        ProviderId::selection(reference.vendor, format)?
1138                    }
1139                    _ => provider,
1140                };
1141                (
1142                    provider,
1143                    reference.model,
1144                    self.facts(provider, reference.model),
1145                )
1146            }
1147        };
1148        let provider = match options.format {
1149            Some(format) if provider.is_registered() => {
1150                ProviderId::selection(provider.vendor(), format)?
1151            }
1152            _ => provider,
1153        };
1154        let registered = provider.registered()?;
1155        let config = match options.api_key {
1156            Some(api_key) => registered.config(api_key),
1157            None => registered.config_from_env()?,
1158        };
1159        let config = match (config, options.account_id) {
1160            (ProviderConfig::OpenAi(provider), Some(account_id)) => {
1161                ProviderConfig::OpenAi(provider.with_account_id(account_id))
1162            }
1163            (config, _) => config,
1164        };
1165        let config = match options.base_url {
1166            Some(base_url) => config.with_base_url(base_url),
1167            None => config,
1168        };
1169        let http = match options.http {
1170            Some(http) => http,
1171            None => shared_http()?,
1172        };
1173        Ok(config.completion_model(model, http, facts))
1174    }
1175}
1176
1177/// The shared reqwest client.
1178#[cfg(feature = "reqwest")]
1179fn shared_http() -> Result<DynHttpClient, ConnectError> {
1180    Ok(rig_reqwest::shared())
1181}
1182
1183/// No shared client without the `reqwest` feature.
1184#[cfg(not(feature = "reqwest"))]
1185fn shared_http() -> Result<DynHttpClient, ConnectError> {
1186    Err(ConnectError::NoHttpClient)
1187}
1188
1189#[cfg(test)]
1190mod tests;