//! Offline model catalog, capabilities, and deterministic resolution //! (`SMH-SPEC-SPEC0001`, Providers). //! //! The reviewed catalog ships as checked-in JSON. Resolution is pure data //! navigation with no network: aliases recurse, groups expand to ordered //! failover plans, and cycles or dangling references fail at load with the //! field path that caused them. use serde::{Deserialize, Serialize}; use smith::error::{ProviderFault, Result, SmithError}; use smith::provider::{ProviderParams, ProviderRequest}; use std::collections::{HashMap, HashSet}; /// Which adapter family serves a model. #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Serialize, Deserialize)] pub enum ProviderKind { /// OpenAI-compatible chat completions. OpenAiCompatible, /// Anthropic Messages. Anthropic, /// Google Gemini. Google, /// Z.ai component provider. Zai, /// Plugin-provided. Plugin, } impl ProviderKind { /// Stable lowercase file name for this provider. #[must_use] pub const fn slug(self) -> &'static str { match self { Self::OpenAiCompatible => "openai", Self::Anthropic => "anthropic", Self::Google => "google", Self::Zai => "zai", Self::Plugin => "plugin", } } /// Parse a provider from its slug. #[must_use] pub fn from_slug(slug: &str) -> Option { match slug { "openai" => Some(Self::OpenAiCompatible), "anthropic" => Some(Self::Anthropic), "google" => Some(Self::Google), "zai" => Some(Self::Zai), "plugin" => Some(Self::Plugin), _ => None, } } } /// What a model explicitly supports, used to validate requests. #[expect( clippy::struct_excessive_bools, reason = "capabilities are independent advertised switches" )] #[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)] pub struct ModelCapabilities { /// Context window in tokens. pub context_window: u64, /// Output limit in tokens. #[serde(rename = "max_output_tokens")] pub output_tokens_max: u64, /// Accepts image inputs. pub input_images: bool, /// Accepts tool definitions. pub tool_use: bool, /// Supports thinking output. pub thinking: bool, /// Supports strict or grammar-constrained tool input. pub strict_tool_input: bool, /// Supports provider-side prompt caching. pub cache_control: bool, } /// One catalog model entry. #[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)] pub struct ModelEntry { /// Model identifier used in requests. pub id: String, /// Adapter family. pub provider: ProviderKind, /// Advertised capabilities. pub capabilities: ModelCapabilities, } /// A reviewed offline catalog plus its resolution tables. #[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)] pub struct Catalog { /// Model entries by provider-qualified key, preserving colliding provider IDs. pub models: HashMap, /// Alias to model id or group name. pub aliases: HashMap, /// Group name to ordered member model ids. pub groups: HashMap>, } /// The reviewed offline catalog, checked in as data. const BUILTIN: &str = include_str!("catalog.json"); /// Largest accepted models.dev source document. pub const MODELS_DEV_BYTES_MAX: usize = 16 * 1024 * 1024; /// Largest number of supported-provider entries admitted from one snapshot. const MODELS_DEV_MODELS_MAX: usize = 8192; /// Largest number of provider sections inspected from one snapshot. const MODELS_DEV_PROVIDERS_MAX: usize = 256; impl Catalog { /// Load the reviewed bundled models.dev snapshot for offline startup. /// /// # Errors /// /// Returns a configuration error when the reviewed source no longer /// satisfies the bounded models.dev schema. pub fn builtin() -> Result { Self::from_models_dev_json(BUILTIN) } /// Normalize a bounded models.dev provider document into Smith's catalog. /// /// Only provider identities with a host-supported connection survive. /// Unknown providers grant neither executable support nor authority. /// /// # Errors /// /// Returns a configuration error for malformed supported-provider data, /// duplicate model ids, or an exceeded source or item bound. pub fn from_models_dev_json(json: &str) -> Result { if json.len() > MODELS_DEV_BYTES_MAX { return Err(invalid( "models.dev", &format!("snapshot exceeds {MODELS_DEV_BYTES_MAX} bytes"), )); } let root: serde_json::Value = serde_json::from_str(json) .map_err(|error| invalid("models.dev", &error.to_string()))?; let providers = root .as_object() .ok_or_else(|| invalid("models.dev", "root must be an object"))?; if providers.len() > MODELS_DEV_PROVIDERS_MAX { return Err(invalid( "models.dev", &format!("provider count exceeds {MODELS_DEV_PROVIDERS_MAX}"), )); } let mut models = HashMap::new(); for (provider_id, provider) in providers { let Some(kind) = models_dev_provider_kind(provider_id) else { continue; }; let provider_path = format!("models.dev.{provider_id}"); let provider = provider .as_object() .ok_or_else(|| invalid(&provider_path, "provider must be an object"))?; let entries = provider .get("models") .and_then(serde_json::Value::as_object) .ok_or_else(|| invalid(&provider_path, "models must be an object"))?; for (model_key, entry) in entries { if models.len() == MODELS_DEV_MODELS_MAX { return Err(invalid( "models.dev", &format!("model count exceeds {MODELS_DEV_MODELS_MAX}"), )); } let path = format!("{provider_path}.models.{model_key}"); let entry = entry .as_object() .ok_or_else(|| invalid(&path, "model must be an object"))?; let id = models_dev_string(entry, "id", &path)?; let limits = entry .get("limit") .and_then(serde_json::Value::as_object) .ok_or_else(|| invalid(&path, "limit must be an object"))?; let context_window = models_dev_u64(limits, "context", &path)?; let output_tokens_max = models_dev_u64(limits, "output", &path)?; // models.dev also describes image, audio, embedding, and // generation-only endpoints. Smith currently dispatches text // conversations only, so zero-limit entries have no admitted // connection and cannot become runnable through catalog data. if context_window == 0 || output_tokens_max == 0 { continue; } let advertised = ModelCapabilities { context_window, output_tokens_max, input_images: models_dev_bool(entry, "attachment"), tool_use: models_dev_bool(entry, "tool_call"), thinking: models_dev_bool(entry, "reasoning"), strict_tool_input: models_dev_bool(entry, "structured_output"), cache_control: entry .get("cost") .and_then(serde_json::Value::as_object) .is_some_and(|cost| cost.contains_key("cache_read")), }; let capabilities = supported_capabilities(kind, advertised); let previous = models.insert( catalog_model_key(kind, &id), ModelEntry { id: id.clone(), provider: kind, capabilities, }, ); if previous.is_some() { return Err(invalid( &path, &format!("duplicate supported model id '{id}' for {}", kind.slug()), )); } } } Ok(Self { models, aliases: HashMap::new(), groups: HashMap::new(), }) } /// Parse and validate catalog JSON. /// /// # Errors /// /// Same failures as [`Catalog::builtin`]. pub fn from_json(json: &str) -> Result { let catalog: Self = serde_json::from_str(json).map_err(|e| invalid("catalog", &e.to_string()))?; // Deterministic diagnostics: validation walks map keys in sorted order. let mut model_names: Vec<&String> = catalog.models.keys().collect(); model_names.sort(); let mut admitted = HashSet::with_capacity(model_names.len()); for name in model_names { let entry = &catalog.models[name]; if !admitted.insert((entry.provider, entry.id.as_str())) { return Err(invalid( &format!("catalog.models.{name}"), &format!( "duplicate model id '{}' for {}", entry.id, entry.provider.slug() ), )); } } let mut alias_names: Vec<&String> = catalog.aliases.keys().collect(); alias_names.sort(); for alias in &alias_names { let target = &catalog.aliases[*alias]; if !catalog.models.contains_key(target) && !catalog.groups.contains_key(target) && !catalog.aliases.contains_key(target) { return Err(invalid( &format!("catalog.aliases.{alias}"), &format!("target '{target}' is neither a model nor a group"), )); } } for (group, members) in &catalog.groups { for (position, member) in members.iter().enumerate() { if !catalog.models.contains_key(member) { return Err(invalid( &format!("catalog.groups.{group}[{position}]"), &format!("member '{member}' is not a model"), )); } } } for alias in &alias_names { catalog.resolve_alias(alias)?; } Ok(catalog) } /// Find an admitted model for one selected provider connection. /// /// # Errors /// /// Returns a configuration error when this provider does not admit the /// requested model. pub fn model_for_provider(&self, provider: ProviderKind, id: &str) -> Result<&ModelEntry> { self.models .values() .find(|entry| entry.provider == provider && entry.id == id) .ok_or_else(|| { invalid( &format!("catalog.models.{}.{}", provider.slug(), id), "model is not admitted by this provider", ) }) } fn resolve_alias(&self, alias: &str) -> Result { let mut chain = vec![alias.to_string()]; let mut current = alias; while let Some(next) = self.aliases.get(current) { if chain.iter().any(|step| step == next) { chain.push(next.clone()); return Err(invalid( &format!("catalog.aliases.{alias}"), &format!("alias cycle: {}", chain.join(" -> ")), )); } chain.push(next.clone()); current = next; } Ok(current.to_string()) } /// Resolve an unambiguous request target into an ordered failover plan. /// /// A model id resolves to itself when it belongs to one provider; an alias resolves to its referent; a /// group resolves to its members in declared order. Resolution performs /// no network access. /// /// # Errors /// /// Returns a [`SmithError::Config`] naming the target when it is unknown /// or cyclic. pub fn resolve_plan(&self, requested: &str) -> Result> { let resolved = self.resolve_alias(requested)?; let ids: Vec<&String> = self .groups .get(&resolved) .map_or_else(|| vec![&resolved], |members| members.iter().collect()); ids.into_iter() .map(|id| self.model_for_id(id, requested)) .collect() } /// Validate that a request uses only capabilities the model advertises. /// /// # Errors /// /// Returns a [`SmithError::Provider`] with fault /// [`ProviderFault::Invalid`] naming the offending request field when the /// model does not advertise what the request asks for. pub fn validate_request(&self, model: &str, request: &ProviderRequest) -> Result<()> { let entry = self.resolve_plan(model)?.first().copied().ok_or_else(|| { invalid(&format!("catalog.resolve.{model}"), "empty resolution plan") })?; let caps = &entry.capabilities; if !request.tools.is_empty() && !caps.tool_use { return Err(invalid_request( "tools", &format!("{} does not advertise tool use", entry.id), )); } let ProviderParams { output_tokens_max, temperature, thinking, } = request.params; if let Some(requested) = output_tokens_max && requested > caps.output_tokens_max { return Err(invalid_request( "params.max_output_tokens", &format!( "{requested} exceeds the advertised limit of {}", caps.output_tokens_max ), )); } if let Some(requested) = temperature && requested > 2 { return Err(invalid_request( "params.temperature", "temperature above 2 is not a valid sampling value", )); } if thinking && !caps.thinking { return Err(invalid_request( "params.thinking", &format!("{} does not advertise thinking", entry.id), )); } Ok(()) } fn model_for_id(&self, id: &str, requested: &str) -> Result<&ModelEntry> { if let Some(entry) = self.models.get(id) { return Ok(entry); } let mut entries = self.models.values().filter(|entry| entry.id == id); let entry = entries.next().ok_or_else(|| { invalid( &format!("catalog.resolve.{requested}"), &format!("'{id}' is not a model"), ) })?; if entries.next().is_some() { return Err(invalid( &format!("catalog.resolve.{requested}"), &format!("'{id}' is ambiguous across providers"), )); } Ok(entry) } } fn catalog_model_key(provider: ProviderKind, id: &str) -> String { format!("{}:{id}", provider.slug()) } /// Intersect upstream metadata with the selected host binding's protocol support. fn supported_capabilities( kind: ProviderKind, mut capabilities: ModelCapabilities, ) -> ModelCapabilities { // Every current protocol codec carries text conversations, output limits, // and tool declarations only. Do not advertise upstream switches absent // from the neutral request or its selected wire codec. capabilities.input_images = false; capabilities.thinking = false; capabilities.strict_tool_input = false; capabilities.cache_control = false; if kind == ProviderKind::Plugin { capabilities.tool_use = false; } capabilities } fn models_dev_provider_kind(provider: &str) -> Option { match provider { "openai" => Some(ProviderKind::OpenAiCompatible), "anthropic" => Some(ProviderKind::Anthropic), "google" => Some(ProviderKind::Google), "zai" => Some(ProviderKind::Zai), _ => None, } } fn models_dev_string( entry: &serde_json::Map, field: &str, path: &str, ) -> Result { let value = entry .get(field) .and_then(serde_json::Value::as_str) .filter(|value| !value.is_empty()) .ok_or_else(|| invalid(path, &format!("{field} must be a non-empty string")))?; Ok(value.to_string()) } fn models_dev_u64( entry: &serde_json::Map, field: &str, path: &str, ) -> Result { entry .get(field) .and_then(serde_json::Value::as_u64) .ok_or_else(|| invalid(path, &format!("limit.{field} must be an integer"))) } fn models_dev_bool(entry: &serde_json::Map, field: &str) -> bool { entry .get(field) .and_then(serde_json::Value::as_bool) .unwrap_or(false) } fn invalid(field: &str, message: &str) -> SmithError { SmithError::Config { field: field.to_string(), message: message.to_string(), } } fn invalid_request(field: &str, message: &str) -> SmithError { SmithError::Provider { fault: ProviderFault::Invalid { field: Some(field.to_string()), message: message.to_string(), }, } } #[cfg(test)] mod tests { use super::*; use smith::message::{Message, Role}; use smith::provider::ProviderParams; use smith::tool::ToolMetadata; const TEST_CATALOG: &str = r#"{ "models": { "mock-smith": { "id": "mock-smith", "provider": "OpenAiCompatible", "capabilities": { "context_window": 8192, "max_output_tokens": 1024, "input_images": false, "tool_use": true, "thinking": false, "strict_tool_input": false, "cache_control": false } }, "thinker": { "id": "thinker", "provider": "Anthropic", "capabilities": { "context_window": 200000, "max_output_tokens": 8192, "input_images": true, "tool_use": true, "thinking": true, "strict_tool_input": false, "cache_control": true } }, "no-tools": { "id": "no-tools", "provider": "Google", "capabilities": { "context_window": 8192, "max_output_tokens": 1024, "input_images": false, "tool_use": false, "thinking": false, "strict_tool_input": false, "cache_control": false } } }, "aliases": { "smart": "thinker" }, "groups": { "default": ["thinker", "mock-smith"] } }"#; #[expect( clippy::unwrap_used, reason = "catalog fixtures are valid by construction" )] fn catalog() -> Catalog { Catalog::from_json(TEST_CATALOG).unwrap() } #[test] fn builtin_catalog_loads_and_resolves() { let catalog = Catalog::builtin().unwrap(); let _plan = catalog.resolve_plan("default"); // Every builtin id resolves to itself. for id in catalog.models.keys() { assert!(catalog.resolve_plan(id).is_ok(), "id {id}"); } } #[test] fn alias_resolves_to_model_and_group_expands_in_order() { let catalog = catalog(); let plan = catalog.resolve_plan("smart").unwrap(); assert_eq!(plan.len(), 1); assert_eq!(plan[0].id, "thinker"); let plan = catalog.resolve_plan("default").unwrap(); assert_eq!( plan.iter() .map(|entry| entry.id.as_str()) .collect::>(), vec!["thinker", "mock-smith"] ); } #[test] fn unknown_targets_and_cycles_fail_with_field_paths() { let catalog = catalog(); let error = catalog.resolve_plan("nope").unwrap_err(); assert_eq!(error.code(), "CONFIG"); let cyclic = r#"{ "models": {}, "aliases": { "a": "b", "b": "a" }, "groups": {} }"#; let error = Catalog::from_json(cyclic).unwrap_err(); assert_eq!( error.to_string(), "config [catalog.aliases.a]: alias cycle: a -> b -> a" ); let dangling = r#"{ "models": {}, "aliases": { "smart": "ghost" }, "groups": {} }"#; let error = Catalog::from_json(dangling).unwrap_err(); assert!(error.to_string().contains("catalog.aliases.smart")); } #[test] fn requests_cannot_use_unadvertised_capabilities() { let catalog = catalog(); let tools = vec![ToolMetadata::new("read", "Read a file")]; let mut request = ProviderRequest::new("mock-smith", vec![Message::with_text(Role::User, "hi")]) .with_tools(tools); // mock-smith advertises tools: allowed. assert!(catalog.validate_request("mock-smith", &request).is_ok()); let tools = vec![ToolMetadata::new("read", "Read a file")]; let _ = tools; // Thinking not advertised: rejected with the field path. request.params = ProviderParams { thinking: true, ..ProviderParams::default() }; let error = catalog .validate_request("mock-smith", &request) .unwrap_err(); assert_eq!(error.code(), "PROVIDER_INVALID"); assert!(error.to_string().contains("params.thinking")); // Output limit exceeded: rejected. request.params = ProviderParams { output_tokens_max: Some(999_999), thinking: false, ..ProviderParams::default() }; assert!(catalog.validate_request("mock-smith", &request).is_err()); // thinker advertises thinking but not an unlimited budget: also rejected. assert!(catalog.validate_request("thinker", &request).is_err()); request.params = ProviderParams { output_tokens_max: Some(4096), thinking: true, ..ProviderParams::default() }; assert!(catalog.validate_request("thinker", &request).is_ok()); } #[test] fn catalog_json_rejects_ambiguous_provider_model_entries() { let error = Catalog::from_json( r#"{ "models": { "first": { "id": "shared", "provider": "Zai", "capabilities": { "context_window": 8, "max_output_tokens": 4, "input_images": false, "tool_use": true, "thinking": false, "strict_tool_input": false, "cache_control": false } }, "second": { "id": "shared", "provider": "Zai", "capabilities": { "context_window": 16, "max_output_tokens": 8, "input_images": false, "tool_use": true, "thinking": false, "strict_tool_input": false, "cache_control": false } } }, "aliases": {}, "groups": {} }"#, ) .unwrap_err(); assert_eq!( error.to_string(), "config [catalog.models.second]: duplicate model id 'shared' for zai" ); } #[test] fn models_dev_normalization_keeps_same_model_id_per_provider() { let catalog = Catalog::from_models_dev_json( r#"{ "openai": {"models": {"shared": { "id": "shared", "limit": {"context": 8, "output": 4} }}}, "zai": {"models": {"shared": { "id": "shared", "limit": {"context": 16, "output": 8} }}} }"#, ) .unwrap(); assert_eq!(catalog.models.len(), 2); assert_eq!( catalog .model_for_provider(ProviderKind::OpenAiCompatible, "shared") .unwrap() .capabilities .context_window, 8 ); assert_eq!( catalog .model_for_provider(ProviderKind::Zai, "shared") .unwrap() .capabilities .context_window, 16 ); } #[test] fn models_dev_normalization_intersects_protocol_capabilities() { let catalog = Catalog::from_models_dev_json( r#"{ "anthropic": {"models": {"claude": { "id": "claude", "limit": {"context": 200000, "output": 8192}, "attachment": true, "tool_call": true, "reasoning": true, "structured_output": true, "cost": {"cache_read": 1} }}} }"#, ) .unwrap(); let model = catalog .model_for_provider(ProviderKind::Anthropic, "claude") .unwrap(); assert!(!model.capabilities.input_images); assert!(model.capabilities.tool_use); assert!(!model.capabilities.thinking); assert!(!model.capabilities.strict_tool_input); assert!(!model.capabilities.cache_control); } #[test] fn models_dev_normalization_keeps_supported_provider_capabilities() { let source = r#"{ "zai": {"models": {"glm-4.7": { "id": "glm-4.7", "attachment": true, "reasoning": true, "tool_call": true, "structured_output": true, "limit": {"context": 200000, "output": 8192} }}}, "unsupported": {"models": {"ghost": { "id": "ghost", "limit": {"context": 1, "output": 1} }}} }"#; let catalog = Catalog::from_models_dev_json(source).unwrap(); let model = catalog .model_for_provider(ProviderKind::Zai, "glm-4.7") .unwrap(); assert_eq!(model.provider, ProviderKind::Zai); assert_eq!(model.capabilities.context_window, 200_000); assert_eq!(model.capabilities.output_tokens_max, 8192); assert!(!model.capabilities.input_images); assert!(model.capabilities.tool_use); assert!(!model.capabilities.thinking); assert!(!model.capabilities.strict_tool_input); assert!(!catalog.models.contains_key("ghost")); } #[test] fn model_capabilities_keep_legacy_output_limit_serde_key() { let capabilities = ModelCapabilities { context_window: 8192, output_tokens_max: 1024, input_images: false, tool_use: false, thinking: false, strict_tool_input: false, cache_control: false, }; let value = serde_json::to_value(capabilities).unwrap(); assert_eq!(value["max_output_tokens"], 1024); assert!(value.get("output_tokens_max").is_none()); } #[cfg(target_arch = "x86_64")] #[test] fn provider_kind_stays_one_byte() { assert_eq!(std::mem::size_of::(), 1); } #[test] fn provider_slugs_round_trip() { for (kind, slug) in [ (ProviderKind::OpenAiCompatible, "openai"), (ProviderKind::Anthropic, "anthropic"), (ProviderKind::Google, "google"), (ProviderKind::Zai, "zai"), (ProviderKind::Plugin, "plugin"), ] { assert_eq!(kind.slug(), slug); assert_eq!(ProviderKind::from_slug(slug), Some(kind)); } assert_eq!(ProviderKind::from_slug("xyzzy"), None); } #[test] fn validation_holds_exactly_at_each_limit() { let catalog = catalog(); let params = |output_tokens_max, temperature| ProviderParams { output_tokens_max, temperature, thinking: false, }; let none = ProviderParams::default(); // (model, with tools, params, rejected field) let cases = [ ("mock-smith", false, params(Some(1024), None), None), ( "mock-smith", false, params(Some(1025), None), Some("params.max_output_tokens"), ), ("mock-smith", false, params(None, Some(0)), None), ("mock-smith", false, params(None, Some(2)), None), ( "mock-smith", false, params(None, Some(3)), Some("params.temperature"), ), ("no-tools", false, none, None), ("no-tools", true, none, Some("tools")), ]; for (model, with_tools, params, rejected) in cases { let mut request = ProviderRequest::new(model, vec![Message::with_text(Role::User, "hi")]); if with_tools { request = request.with_tools(vec![ToolMetadata::new("read", "Read a file")]); } request.params = params; let field = match catalog.validate_request(model, &request) { Ok(()) => None, Err(SmithError::Provider { fault: ProviderFault::Invalid { field, .. }, }) => field, Err(other) => Some(other.to_string()), }; assert_eq!( field.as_deref(), rejected, "{model} tools={with_tools} {params:?}" ); } } }