systemprompt_api/routes/gateway/
models.rs

1//! `/v1/models` catalog endpoint: the whole advertised model catalog.
2//!
3//! Copyright (c) systemprompt.io — Business Source License 1.1.
4//! See <https://systemprompt.io> for licensing details.
5
6use axum::Json;
7use axum::http::{HeaderMap, StatusCode};
8use serde::Serialize;
9use std::collections::BTreeMap;
10use systemprompt_identifiers::headers::INFERENCE_PROTOCOL;
11use systemprompt_loader::ServicesBootstrap;
12use systemprompt_models::services::{ApiSurface, ProviderRegistry};
13
14#[derive(Debug, Serialize)]
15pub struct RootResponse {
16    pub service: &'static str,
17    pub version: &'static str,
18    pub endpoints: Vec<&'static str>,
19}
20
21pub async fn root() -> Json<RootResponse> {
22    Json(RootResponse {
23        service: "systemprompt-gateway",
24        version: env!("CARGO_PKG_VERSION"),
25        endpoints: vec![
26            "/v1/models",
27            "/v1/messages",
28            "/v1/responses",
29            "/v1/chat/completions",
30        ],
31    })
32}
33
34#[derive(Debug, Serialize)]
35pub struct ModelEntry {
36    #[serde(rename = "type")]
37    pub kind: &'static str,
38    pub id: String,
39    pub display_name: String,
40    pub created_at: String,
41}
42
43#[derive(Debug, Serialize)]
44pub struct ModelsResponse {
45    pub data: Vec<ModelEntry>,
46    pub has_more: bool,
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub first_id: Option<String>,
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub last_id: Option<String>,
51}
52
53/// Query parameters accepted by [`list`].
54///
55/// Gateway model discovery requests `/v1/models?limit=1000`. An unparseable or
56/// absent value returns the whole catalog rather than failing: discovery has a
57/// three-second budget and treats any non-success as "no models", so a strict
58/// parse would cost the developer their picker entries over a cosmetic input.
59#[derive(Debug, Default, Clone, serde::Deserialize)]
60pub struct ListQuery {
61    pub limit: Option<usize>,
62    pub format: Option<String>,
63}
64
65#[derive(Debug, Serialize)]
66pub struct OpenAiModelEntry {
67    pub id: String,
68    pub object: &'static str,
69    pub created: u64,
70    pub owned_by: &'static str,
71}
72
73#[derive(Debug, Serialize)]
74pub struct OpenAiModelsResponse {
75    pub object: &'static str,
76    pub data: Vec<OpenAiModelEntry>,
77}
78
79pub async fn list(
80    headers: HeaderMap,
81    axum::extract::Query(query): axum::extract::Query<ListQuery>,
82) -> Result<axum::response::Response, (StatusCode, String)> {
83    let services = ServicesBootstrap::get().map_err(|e| {
84        (
85            StatusCode::SERVICE_UNAVAILABLE,
86            format!("Services config not ready: {e}"),
87        )
88    })?;
89
90    services
91        .gateway_config()
92        .filter(|g| g.enabled)
93        .ok_or_else(|| (StatusCode::NOT_FOUND, "Gateway not enabled".to_owned()))?;
94
95    // Why: the `x-inference-protocol` header is advisory, not a filter. The
96    // gateway transcodes every inbound wire to every provider wire, so a client
97    // that speaks one family is still served every advertised model; narrowing
98    // the catalog by the header would hide models the caller can actually use.
99    // The header is still parsed and validated so an unknown tag (or `backend`)
100    // is rejected rather than silently accepted.
101    let _surfaces = surfaces_from_header(&headers)?;
102    let mut entries = model_entries(&services.providers, &[]);
103    let total = entries.len();
104    let has_more = match query.limit {
105        Some(limit) if limit < total => {
106            entries.truncate(limit);
107            true
108        },
109        _ => false,
110    };
111
112    if query.format.as_deref() == Some("openai") {
113        let data = entries
114            .into_iter()
115            .map(|e| OpenAiModelEntry {
116                id: e.id,
117                object: "model",
118                created: 0,
119                owned_by: "systemprompt",
120            })
121            .collect();
122        return Ok(axum::response::IntoResponse::into_response(Json(
123            OpenAiModelsResponse {
124                object: "list",
125                data,
126            },
127        )));
128    }
129
130    let first_id = entries.first().map(|e| e.id.clone());
131    let last_id = entries.last().map(|e| e.id.clone());
132
133    Ok(axum::response::IntoResponse::into_response(Json(
134        ModelsResponse {
135            data: entries,
136            has_more,
137            first_id,
138            last_id,
139        },
140    )))
141}
142
143pub fn surfaces_from_header(headers: &HeaderMap) -> Result<Vec<ApiSurface>, (StatusCode, String)> {
144    let Some(raw) = headers
145        .get(INFERENCE_PROTOCOL)
146        .and_then(|v| v.to_str().ok())
147    else {
148        return Ok(Vec::new());
149    };
150    let mut surfaces = Vec::new();
151    for tag in raw.split(',').map(str::trim).filter(|t| !t.is_empty()) {
152        let surface = ApiSurface::from_tag(tag)
153            .filter(|s| *s != ApiSurface::Backend)
154            .ok_or_else(|| {
155                (
156                    StatusCode::BAD_REQUEST,
157                    format!("unknown {INFERENCE_PROTOCOL} value: {tag}"),
158                )
159            })?;
160        surfaces.push(surface);
161    }
162    Ok(surfaces)
163}
164
165pub fn model_entries(registry: &ProviderRegistry, surfaces: &[ApiSurface]) -> Vec<ModelEntry> {
166    let mut by_id: BTreeMap<String, ModelEntry> = BTreeMap::new();
167    for id in registry.advertised_model_ids(surfaces) {
168        by_id.insert(
169            id.clone(),
170            ModelEntry {
171                kind: "model",
172                display_name: humanize_model_id(&id),
173                created_at: model_created_at(&id),
174                id,
175            },
176        );
177    }
178    by_id.into_values().collect()
179}
180
181// Why: consecutive numeric segments are a version (`4-5` is 4.5) and a
182// trailing eight-digit segment is the release date, which `model_created_at`
183// carries; the picker shows `Claude Haiku 4.5`, never `20251001`.
184pub fn humanize_model_id(id: &str) -> String {
185    let parts: Vec<&str> = id.split('-').filter(|p| !p.is_empty()).collect();
186    let parts = match parts.split_last() {
187        Some((last, rest)) if is_release_date(last) => rest,
188        _ => parts.as_slice(),
189    };
190    let mut out = String::with_capacity(id.len());
191    let mut prev_numeric = false;
192    for part in parts {
193        let numeric = part.bytes().all(|b| b.is_ascii_digit());
194        if !out.is_empty() {
195            out.push(if numeric && prev_numeric { '.' } else { ' ' });
196        }
197        if numeric {
198            out.push_str(part);
199        } else {
200            let mut chars = part.chars();
201            if let Some(c) = chars.next() {
202                out.extend(c.to_uppercase());
203                out.push_str(chars.as_str());
204            }
205        }
206        prev_numeric = numeric;
207    }
208    out
209}
210
211fn is_release_date(part: &str) -> bool {
212    part.len() == 8 && part.bytes().all(|b| b.is_ascii_digit())
213}
214
215// Why: the Unix epoch is the documented "unknown" value for this field.
216pub fn model_created_at(id: &str) -> String {
217    const EPOCH: &str = "1970-01-01T00:00:00Z";
218    let Some(date) = id.rsplit('-').next().filter(|p| is_release_date(p)) else {
219        return EPOCH.to_owned();
220    };
221    chrono::NaiveDate::parse_from_str(date, "%Y%m%d").map_or_else(
222        |_| EPOCH.to_owned(),
223        |d| format!("{}T00:00:00Z", d.format("%Y-%m-%d")),
224    )
225}
systemprompt_api/routes/gateway/models.rs

systemprompt_api/routes/gateway/
models.rs
