feat: openrouter_slug override for OpenRouter provider listing (#740)

* feat: openrouter_slug override for OpenRouter provider listing

OpenRouter's provider spec requires the model `id` in GET /v1/models to
exactly match OpenRouter's canonical slug, or for the provider to supply an
explicit override. 8 of our 9 listed models do not match OR's slug.

Add an admin-settable per-model `openrouter_slug` field that surfaces on the
public GET /v1/models as a nested `openrouter: { slug }` object, emitted only
when set (omitted entirely when NULL). Mirrors the datacenters/is_ready/
deprecation_date precedent end-to-end:

- migration V0056: nullable `openrouter_slug TEXT` on models + model_history
- Model / ModelHistory / service structs + repository read/write round-trip
- UpdateModelApiRequest: `openrouterSlug` (camelCase), tri-state Nullable so
  JSON null clears it; omitted leaves it unchanged
- admin write-path validation: rejects non lowercase `author/slug` shape (400)
- public serializer model_with_pricing_to_info emits the nested object
- unit tests (slug validator + serializer emit/omit) and e2e tests
  (write+read round-trip, public nested object, clear via null, tri-state
  omit guard, invalid-slug rejection)

Post-merge admin backfill is a separate prod write step (see PR body).

* fix(db): renumber openrouter_slug migration V0056->V0057 (avoid collision with #737)

Author: Evrard-Nil

crates/api/src/models.rs

@@ -837,6 +837,24 @@ pub struct ModelInfo {
     /// `[{ "country_code": "US" }]`. Omitted when unset.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub datacenters: Option<Vec<Datacenter>>,
+    /// OpenRouter slug override: `{ "slug": "<value>" }`. Present only when an
+    /// override is set (our `id` does not match OpenRouter's canonical slug).
+    /// Omitted entirely when unset.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub openrouter: Option<OpenRouter>,
+}
+
+/// OpenRouter slug-override block.
+///
+/// OpenRouter's provider spec
+/// (https://openrouter.ai/docs/guides/community/for-providers) requires the
+/// model `id` to EXACTLY match OpenRouter's canonical slug, OR for the provider
+/// to supply an explicit override via a nested `openrouter` object carrying the
+/// canonical slug. We emit this object only when an override is configured.
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct OpenRouter {
+    /// OpenRouter's canonical slug for this model (lowercase `author/slug`).
+    pub slug: String,
 }
 
 /// OpenRouter `datacenters` entry: a single datacenter the model runs in.
@@ -3047,6 +3065,11 @@ pub struct ModelMetadata {
     /// string. Omitted when there is no planned deprecation.
     #[serde(rename = "deprecationDate", skip_serializing_if = "Option::is_none")]
     pub deprecation_date: Option<String>,
+    /// OpenRouter `openrouter.slug` override (lowercase `author/slug`). Omitted
+    /// when unset. On public `GET /v1/models` this surfaces as the nested
+    /// `openrouter: { slug }` object; the admin view exposes the raw value.
+    #[serde(rename = "openrouterSlug", skip_serializing_if = "Option::is_none")]
+    pub openrouter_slug: Option<String>,
 }
 
 /// Request to update model pricing (admin endpoint)
@@ -3151,6 +3174,24 @@ pub struct UpdateModelApiRequest {
     )]
     #[schema(value_type = Option<String>)]
     pub deprecation_date: Nullable<String>,
+    /// OpenRouter `openrouter.slug` override (lowercase `author/slug`, e.g.
+    /// `z-ai/glm-5.1`). Set when our canonical `model_name` does not match
+    /// OpenRouter's slug; surfaced as the nested `openrouter: { slug }` object
+    /// on `GET /v1/models`. Validated at the write path; rejected if it does
+    /// not match the `author/slug` shape.
+    ///
+    /// Tri-state PATCH semantics:
+    /// - omitted → leave unchanged
+    /// - `null` → clear back to "unset" (column set to NULL)
+    /// - a string → set verbatim
+    #[serde(
+        rename = "openrouterSlug",
+        default,
+        deserialize_with = "deserialize_nullable",
+        skip_serializing_if = "Option::is_none"
+    )]
+    #[schema(value_type = Option<String>)]
+    pub openrouter_slug: Nullable<String>,
     #[serde(rename = "changeReason", skip_serializing_if = "Option::is_none")]
     pub change_reason: Option<String>,
 }
@@ -3332,6 +3373,9 @@ pub struct ModelHistoryEntry {
     pub is_ready: Option<bool>,
     #[serde(rename = "deprecationDate", skip_serializing_if = "Option::is_none")]
     pub deprecation_date: Option<String>,
+    /// OpenRouter `openrouter.slug` override the model carried at this point.
+    #[serde(rename = "openrouterSlug", skip_serializing_if = "Option::is_none")]
+    pub openrouter_slug: Option<String>,
 }
 
 /// Model history response - complete history of model changes

crates/api/src/routes/admin.rs

@@ -90,6 +90,37 @@ pub(crate) fn format_deprecation_date(dt: &DateTime<Utc>) -> String {
     dt.format("%Y-%m-%dT%H:00:00Z").to_string()
 }
 
+/// Validate an OpenRouter `openrouter.slug` override.
+///
+/// OpenRouter's `/api/v1/models` ids are lowercase `author/slug` pairs (e.g.
+/// `z-ai/glm-5.1`, `qwen/qwen3.6-27b`). We accept exactly that shape: one `/`
+/// separator, each segment starting and ending with `[a-z0-9]` and containing
+/// only `[a-z0-9._-]` in between. This mirrors the regex
+/// `^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?/[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$`
+/// without pulling in a regex dependency.
+pub(crate) fn is_valid_openrouter_slug(slug: &str) -> bool {
+    fn is_valid_segment(seg: &str) -> bool {
+        let bytes = seg.as_bytes();
+        if bytes.is_empty() {
+            return false;
+        }
+        let is_boundary = |b: u8| b.is_ascii_lowercase() || b.is_ascii_digit();
+        let is_interior = |b: u8| is_boundary(b) || matches!(b, b'.' | b'_' | b'-');
+        // First and last must be boundary chars; interior may use . _ -
+        if !is_boundary(bytes[0]) || !is_boundary(bytes[bytes.len() - 1]) {
+            return false;
+        }
+        bytes.iter().all(|&b| is_interior(b))
+    }
+
+    let mut parts = slug.split('/');
+    match (parts.next(), parts.next(), parts.next()) {
+        // Exactly two non-empty, well-formed segments (no second `/`).
+        (Some(author), Some(name), None) => is_valid_segment(author) && is_valid_segment(name),
+        _ => false,
+    }
+}
+
 #[derive(Clone)]
 pub struct AdminAppState {
     pub admin_service: Arc<dyn AdminService + Send + Sync>,
@@ -301,6 +332,24 @@ pub async fn batch_upsert_models(
                 ));
             }
         }
+        // `openrouter.slug` override must be a lowercase `author/slug` (the
+        // canonical shape OpenRouter uses in its `/api/v1/models` ids, e.g.
+        // `z-ai/glm-5.1`). Reject anything else at the write path so the
+        // catalog can't emit a slug OpenRouter would refuse to match. An
+        // explicit `null` (clear) and an omitted field both skip this check.
+        if let Some(Some(slug)) = &request.openrouter_slug {
+            if !is_valid_openrouter_slug(slug) {
+                return Err((
+                    StatusCode::BAD_REQUEST,
+                    ResponseJson(ErrorResponse::new(
+                        format!(
+                            "model '{model_name}': openrouterSlug: '{slug}' is not a valid OpenRouter slug; expected lowercase 'author/slug' (e.g. 'z-ai/glm-5.1')"
+                        ),
+                        "invalid_request".to_string(),
+                    )),
+                ));
+            }
+        }
     }
 
     // Extract admin user context for audit tracking
@@ -353,6 +402,10 @@ pub async fn batch_upsert_models(
                         .deprecation_date
                         .as_ref()
                         .map(|inner| inner.as_deref().and_then(parse_deprecation_date)),
+                    // Tri-state passes straight through: outer None = leave
+                    // unchanged, Some(None) = clear, Some(Some(v)) = set. The
+                    // value was already shape-validated above.
+                    openrouter_slug: request.openrouter_slug.clone(),
                     change_reason: request.change_reason.clone(),
                     changed_by_user_id: Some(admin_user_id),
                     changed_by_user_email: Some(admin_user_email.clone()),
@@ -562,6 +615,7 @@ pub async fn batch_upsert_models(
                     .deprecation_date
                     .as_ref()
                     .map(format_deprecation_date),
+                openrouter_slug: updated_model.openrouter_slug,
             },
         })
         .collect();
@@ -668,6 +722,7 @@ pub async fn list_models(
                 datacenters: crate::models::Datacenter::from_codes(model.datacenters),
                 is_ready: model.is_ready,
                 deprecation_date: model.deprecation_date.as_ref().map(format_deprecation_date),
+                openrouter_slug: model.openrouter_slug,
             },
             is_active: model.is_active,
             created_at: model.created_at,
@@ -806,6 +861,7 @@ pub async fn get_model_history(
             datacenters: crate::models::Datacenter::from_codes(h.datacenters),
             is_ready: h.is_ready,
             deprecation_date: h.deprecation_date.as_ref().map(format_deprecation_date),
+            openrouter_slug: h.openrouter_slug,
         })
         .collect();
 
@@ -1313,6 +1369,7 @@ pub async fn deprecate_model(
             datacenters: crate::models::Datacenter::from_codes(m.datacenters),
             is_ready: m.is_ready,
             deprecation_date: m.deprecation_date.as_ref().map(format_deprecation_date),
+            openrouter_slug: m.openrouter_slug,
         },
     };
 
@@ -3143,3 +3200,55 @@ mod deprecation_date_tests {
         assert!(parse_deprecation_date("2025-13-01").is_none());
     }
 }
+
+#[cfg(test)]
+mod openrouter_slug_tests {
+    use super::is_valid_openrouter_slug;
+
+    #[test]
+    fn accepts_canonical_openrouter_slugs() {
+        // The real slugs we need to back-fill (per the OpenRouter for-providers
+        // spec) must all validate.
+        for slug in [
+            "z-ai/glm-5.1",
+            "deepseek/deepseek-v4-flash",
+            "google/gemma-4-31b-it",
+            "qwen/qwen3.5-122b-a10b",
+            "qwen/qwen3.6-27b",
+            "qwen/qwen3.6-35b-a3b",
+            "qwen/qwen3-vl-30b-a3b-instruct",
+            "qwen/qwen3-30b-a3b-instruct-2507",
+            "openai/gpt-oss-120b",
+            "a/b",         // minimal single-char segments
+            "a.b_c-d/e.f", // all interior punctuation classes
+        ] {
+            assert!(
+                is_valid_openrouter_slug(slug),
+                "expected '{slug}' to be a valid OpenRouter slug"
+            );
+        }
+    }
+
+    #[test]
+    fn rejects_malformed_slugs() {
+        for slug in [
+            "",              // empty
+            "glm-5.1",       // missing author/ segment
+            "Z-AI/glm-5.1",  // uppercase
+            "z-ai/GLM-5.1",  // uppercase in slug
+            "z-ai/",         // empty slug segment
+            "/glm-5.1",      // empty author segment
+            "z-ai/glm/5.1",  // more than one separator
+            "-z-ai/glm-5.1", // leading punctuation
+            "z-ai-/glm-5.1", // trailing punctuation on author
+            "z-ai/glm-5.1-", // trailing punctuation on slug
+            "z-ai/.glm",     // leading punctuation on slug
+            "z ai/glm-5.1",  // space is not allowed
+        ] {
+            assert!(
+                !is_valid_openrouter_slug(slug),
+                "expected '{slug}' to be rejected"
+            );
+        }
+    }
+}

crates/api/src/routes/completions.rs

@@ -2288,6 +2288,13 @@ fn model_with_pricing_to_info(model: services::models::ModelWithPricing) -> Mode
             is_moderated: false,
         }),
         datacenters: crate::models::Datacenter::from_codes(model.datacenters),
+        // OpenRouter requires `id` to match its canonical slug, or an explicit
+        // override via this nested object. Emit it only when an override is set
+        // (NULL/empty → omit the key entirely).
+        openrouter: model
+            .openrouter_slug
+            .filter(|s| !s.is_empty())
+            .map(|slug| crate::models::OpenRouter { slug }),
     }
 }
 
@@ -2376,6 +2383,7 @@ mod tests {
             datacenters: None,
             is_ready: None,
             deprecation_date: None,
+            openrouter_slug: None,
             created_at: chrono::Utc::now(),
         }
     }
@@ -2420,6 +2428,44 @@ mod tests {
         assert_eq!(architecture.output_modalities, vec!["text".to_string()]);
     }
 
+    #[test]
+    fn model_without_openrouter_slug_omits_nested_object() {
+        // No override set → the public ModelInfo must not carry the nested
+        // `openrouter` object at all (serde skips it when None).
+        let info = model_with_pricing_to_info(make_model_with_pricing(None, None));
+        assert!(
+            info.openrouter.is_none(),
+            "openrouter object must be omitted when no slug override is set"
+        );
+        // And it must not appear in the serialized JSON either.
+        let json = serde_json::to_value(&info).unwrap();
+        assert!(
+            json.get("openrouter").is_none(),
+            "serialized JSON must omit the openrouter key when unset"
+        );
+    }
+
+    #[test]
+    fn model_with_openrouter_slug_emits_nested_object() {
+        // Override set → the public ModelInfo must carry
+        // `openrouter: { slug: <value> }`.
+        let mut model = make_model_with_pricing(None, None);
+        model.openrouter_slug = Some("z-ai/glm-5.1".to_string());
+        let info = model_with_pricing_to_info(model);
+        let openrouter = info
+            .openrouter
+            .as_ref()
+            .expect("openrouter object must be present when slug override is set");
+        assert_eq!(openrouter.slug, "z-ai/glm-5.1");
+
+        let json = serde_json::to_value(&info).unwrap();
+        assert_eq!(
+            json["openrouter"]["slug"],
+            serde_json::json!("z-ai/glm-5.1"),
+            "serialized JSON must nest the slug under openrouter.slug"
+        );
+    }
+
     fn make_chat_chunk(id: &str) -> inference_providers::StreamChunk {
         inference_providers::StreamChunk::Chat(inference_providers::models::ChatCompletionChunk {
             id: id.to_string(),

crates/api/src/routes/models.rs

@@ -160,6 +160,7 @@ pub async fn list_models(
                     .deprecation_date
                     .as_ref()
                     .map(crate::routes::admin::format_deprecation_date),
+                openrouter_slug: model.openrouter_slug,
             },
         })
         .collect();
@@ -274,6 +275,7 @@ pub async fn get_model_by_name(
                 .deprecation_date
                 .as_ref()
                 .map(crate::routes::admin::format_deprecation_date),
+            openrouter_slug: model.openrouter_slug,
         },
     };