repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-ai/src/models.rs
Raw//! 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<Self> {
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<String, ModelEntry>,
/// Alias to model id or group name.
pub aliases: HashMap<String, String>,
/// Group name to ordered member model ids.
pub groups: HashMap<String, Vec<String>>,
}
/// 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> {
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<Self> {
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<Self> {
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<String> {
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<Vec<&ModelEntry>> {
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<ProviderKind> {
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<String, serde_json::Value>,
field: &str,
path: &str,
) -> Result<String> {
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<String, serde_json::Value>,
field: &str,
path: &str,
) -> Result<u64> {
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<String, serde_json::Value>, 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<_>>(),
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::<ProviderKind>(), 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:?}"
);
}
}
}