Merge pull request #798 from Routstr/fix/forwarded-model-id-semantics

docs: describe forwarded_model_id as the client-facing alias

routstr/core/db.py

@@ -435,7 +435,11 @@ class ModelRow(SQLModel, table=True):  # type: ignore
     enabled: bool = Field(default=True, description="Whether this model is enabled")
     forwarded_model_id: str | None = Field(
         default=None,
-        description="Model ID to use when forwarding requests to upstream provider. Defaults to id if not set.",
+        description=(
+            "Client-facing alias advertised by /v1/models and accepted on "
+            "requests in place of id. JSON request bodies sent upstream carry "
+            "id (via the provider's transform_model_name), not this value."
+        ),
     )
     upstream_provider: "UpstreamProviderRow" = Relationship(back_populates="models")
 

routstr/upstream/model_paths.py

@@ -228,10 +228,11 @@ def openrouter_author_slug(model: object) -> str | None:
     """Return a canonical ``author/slug`` for the OpenRouter endpoints API.
 
     Prefer ``canonical_slug``, then a slash-containing ``id``, then a
-    slash-containing ``forwarded_model_id``. The forwarded id is exactly what
+    slash-containing ``forwarded_model_id``. That field is the client-facing
-    the proxy sends upstream for admin-created alias rows (``base.py`` forwards
+    alias: JSON request bodies sent upstream carry
-    ``forwarded_model_id or id``), so it is a valid OpenRouter id when the
+    ``transform_model_name(model.id)``, not it (``base.py``). It is used here
-    bare ``id`` is a local alias with no slash.
+    only as a last-resort guess at an ``author/slug`` when neither
+    ``canonical_slug`` nor ``id`` carries one.
     """
     canonical = getattr(model, "canonical_slug", None)
     if canonical and "/" in canonical: