From 92e182b898a557849f374ba66af708999626806d Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 12:29:03 -0700
Subject: [PATCH 01/67] fix(mcp): persist OAuth credentials for validated JWT
 users

---
 .../mcp_server/bridge_token_flow.py           |  56 ++++
 .../mcp_server/discoverable_endpoints.py      |   5 +-
 .../mcp_server/test_discoverable_endpoints.py | 277 +++++++++++++++++-
 3 files changed, 335 insertions(+), 3 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 35a30127e27..8dcc49c2fd8 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -306,12 +306,68 @@ async def _extract_user_id_from_request(request: Request) -> str | None:
     (including a transient DB outage) collapses to ``None`` here and the caller simply skips the store;
     the bridge mint, which must status those outcomes differently, consumes
     :func:`_resolve_active_litellm_key` directly."""
+    from litellm.proxy.auth.handle_jwt import JWTHandler  # noqa: PLC0415  # proxy import cycle
+
+    token: Final = _litellm_key_from_request(request)
+    if token is not None and JWTHandler.is_jwt(token):
+        return await _extract_jwt_user_id(token)
     resolved: Final = await _resolve_active_litellm_key(request)
     if not isinstance(resolved, _ResolvedKey):
         return None
     return _active_key_user_id(resolved.key)
 
 
+async def _extract_jwt_user_id(token: str) -> str | None:
+    from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.handle_jwt import JWTAuthManager  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
+        _resolve_jwt_to_virtual_key,  # pyright: ignore[reportPrivateUsage]  # reuse admission mapping policy without provisioning a new key
+    )
+    from litellm.proxy.proxy_server import (  # noqa: PLC0415  # proxy globals initialized at startup
+        general_settings,
+        jwt_handler,
+        premium_user,
+        prisma_client,
+        proxy_logging_obj,
+        user_api_key_cache,
+    )
+
+    if general_settings.get("enable_jwt_auth") is not True or premium_user is not True:
+        return None
+    try:
+        claims: Final = await jwt_handler.auth_jwt(token=token)
+        validate: Final = jwt_handler.litellm_jwtauth.custom_validate
+        if validate is not None and not validate(claims):
+            return None
+        if jwt_handler.litellm_jwtauth.is_virtual_key_mapping_configured():
+            mapped: Final = await _resolve_jwt_to_virtual_key(
+                jwt_claims=claims,
+                jwt_handler=jwt_handler,
+                prisma_client=prisma_client,
+                user_api_key_cache=user_api_key_cache,
+                parent_otel_span=None,
+                proxy_logging_obj=proxy_logging_obj,
+            )
+            if isinstance(mapped, UserAPIKeyAuth):
+                return None if await _key_owner_scim_deactivated(mapped) else _active_key_user_id(mapped)
+            if mapped is not None:
+                return None
+        user_id, _, valid_email = await JWTAuthManager.get_user_info(jwt_handler, claims)
+        object_id: Final = jwt_handler.get_object_id(token=claims, default_value=None)
+        owner_id: Final = (
+            object_id
+            if jwt_handler.get_rbac_role(token=claims) == LitellmUserRoles.INTERNAL_USER and object_id
+            else user_id
+        )
+        if not owner_id or valid_email is False:
+            return None
+        owner: Final = await load_active_user_by_id(owner_id)
+        return None if isinstance(owner, str) else owner.user_id
+    except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
+        verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
+        return None
+
+
 _UpstreamGrantRejection = Literal["no_access_token", "expired_lifetime"]
 """Why an upstream token response cannot back a bridge envelope:
 - ``no_access_token``: the response carries no usable ``access_token``
diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index bafe33d0a6b..94b6348b0f0 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -1236,8 +1236,9 @@ async def exchange_token_with_server(
                 "exchange_token_with_server: could not resolve a LiteLLM user_id for the request, "
                 "so the per-user token for server=%s was NOT stored. The authorization_code egress "
                 "requires the stored token, so the client will be challenged with 401 on reconnect. "
-                "Ensure the request carries a valid LiteLLM key (x-litellm-api-key or Authorization), "
-                "or store it via POST /mcp/server/{id}/oauth-user-credential.",
+                "Ensure the request carries a valid LiteLLM key or enabled JWT identity "
+                "(x-litellm-api-key or Authorization), "
+                "or store it via POST /v1/mcp/server/{id}/oauth-user-credential.",
                 resolved_server.server_id,
             )
 
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index 9ea870d3210..af4c9eea770 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -5,7 +5,7 @@ import json
 import time
 from base64 import urlsafe_b64encode
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Final
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -15,6 +15,9 @@ from litellm.types.mcp import MCPAuth
 
 if TYPE_CHECKING:
     import httpx
+    from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+
+    from litellm.proxy.auth.handle_jwt import JWTHandler
 
     from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
@@ -11374,3 +11377,275 @@ with TestClient(app) as client:
         assert responses[path]["status"] == 200, responses[path]
         assert responses[path]["body"]["issuer"] == f"http://testserver/gateway/{path}"
     assert responses["example/mcp"]["body"]["token_endpoint"] == "http://testserver/gateway/example/token"
+
+
+@pytest.fixture
+def jwt_oauth_identity(monkeypatch: pytest.MonkeyPatch) -> tuple["JWTHandler", "RSAPrivateKey"]:
+    import jwt
+    from cryptography.hazmat.primitives.asymmetric import rsa
+
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._types import LiteLLM_JWTAuth
+    from litellm.proxy.auth.handle_jwt import JWTHandler
+    from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
+
+    signing_key: Final = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    cache: Final = UserApiKeyCache()
+    cache.set_cache(
+        "litellm_jwt_auth_keys_https://idp.example.test/jwks",
+        [json.loads(jwt.algorithms.RSAAlgorithm.to_jwk(signing_key.public_key()))],
+    )
+    cache.set_cache("jwt-owner", LiteLLM_UserTable(user_id="jwt-owner", user_email="owner@example.test"))
+    handler: Final = JWTHandler()
+    handler.update_environment(
+        prisma_client=None,
+        user_api_key_cache=cache,
+        litellm_jwtauth=LiteLLM_JWTAuth(user_id_jwt_field="identity.user_id"),
+    )
+    monkeypatch.setenv("JWT_PUBLIC_KEY_URL", "https://idp.example.test/jwks")
+    monkeypatch.setenv("JWT_ISSUER", "https://idp.example.test")
+    monkeypatch.setenv("JWT_AUDIENCE", "litellm-proxy")
+    monkeypatch.setattr(proxy_server, "jwt_handler", handler)
+    monkeypatch.setattr(proxy_server, "general_settings", {"enable_jwt_auth": True})
+    monkeypatch.setattr(proxy_server, "premium_user", True)
+    monkeypatch.setattr(proxy_server, "user_api_key_cache", cache)
+    monkeypatch.setattr(proxy_server, "prisma_client", MagicMock())
+    return handler, signing_key
+
+
+def _oauth_identity_jwt(
+    signing_key: "RSAPrivateKey",
+    *,
+    expires_in: int = 300,
+    audience: str = "litellm-proxy",
+    issuer: str = "https://idp.example.test",
+    owner: str | None = "jwt-owner",
+) -> str:
+    import jwt
+
+    return jwt.encode(
+        {
+            "sub": "not-the-configured-user-id",
+            "identity": {"user_id": owner},
+            "iss": issuer,
+            "aud": audience,
+            "exp": int(time.time()) + expires_in,
+        },
+        signing_key,
+        algorithm="RS256",
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("header", ["Authorization", "x-litellm-api-key"])
+async def test_oauth_exchange_stores_token_for_validated_jwt_user(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    header: str,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import httpx
+
+    from litellm.proxy._experimental.mcp_server import discoverable_endpoints
+    from litellm.proxy._types import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+    _, signing_key = jwt_oauth_identity
+    bearer: Final = _oauth_identity_jwt(signing_key)
+    request: Final = _token_request({header: f"Bearer {bearer}"})
+    server: Final = MCPServer(
+        server_id="jwt-oauth-server",
+        name="jwt-oauth-server",
+        transport=MCPTransport.http,
+        auth_type=MCPAuth.oauth2,
+        oauth2_flow="authorization_code",
+        authorization_url="https://upstream.example.test/authorize",
+        token_url="https://upstream.example.test/token",
+        client_id="registered-client",
+    )
+    import litellm
+    from litellm.caching.llm_caching_handler import LLMClientCache
+    from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
+    from litellm.proxy import proxy_server
+    from litellm.proxy.common_utils.encrypt_decrypt_utils import decrypt_value_helper
+    from litellm.types.llms.custom_http import httpxSpecialProvider
+
+    def upstream_response(outbound: httpx.Request) -> httpx.Response:
+        assert outbound.url == server.token_url
+        assert bearer not in str(outbound.headers)
+        assert bearer.encode() not in outbound.content
+        return httpx.Response(200, json={"access_token": "upstream-token", "token_type": "Bearer"})
+
+    database: Final = MagicMock()
+    table: Final = database.db.litellm_mcpusercredentials
+    table.find_unique = AsyncMock(return_value=None)
+    table.upsert = AsyncMock()
+    monkeypatch.setattr(proxy_server, "prisma_client", database)
+    monkeypatch.setenv("LITELLM_SALT_KEY", "oauth-jwt-test-encryption-key")
+    clients: Final = LLMClientCache()
+    monkeypatch.setattr(litellm, "in_memory_llm_clients_cache", clients)
+    async with httpx.AsyncClient(transport=httpx.MockTransport(upstream_response)) as transport:
+        upstream: Final = AsyncHTTPHandler()
+        await upstream.client.aclose()
+        upstream.client = transport
+        clients.set_cache("async_httpx_client" + httpxSpecialProvider.Oauth2Check, upstream)
+        response: Final = await discoverable_endpoints.exchange_token_with_server(
+            request=request,
+            mcp_server=server,
+            grant_type="authorization_code",
+            code="upstream-code",
+            redirect_uri="http://localhost/callback",
+            client_id="registered-client",
+            client_secret=None,
+            code_verifier=None,
+        )
+    assert response.status_code == 200
+    table.upsert.assert_awaited_once()
+    stored: Final = table.upsert.call_args.kwargs
+    assert stored["where"] == {"user_id_server_id": {"user_id": "jwt-owner", "server_id": server.server_id}}
+    credential: Final = stored["data"]["create"]["credential_b64"]
+    assert "upstream-token" not in credential
+    decoded: Final = decrypt_value_helper(credential, key="mcp_user_credential")
+    assert json.loads(decoded)["access_token"] == "upstream-token"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "rejection",
+    [
+        "expired",
+        "audience",
+        "issuer",
+        "signature",
+        "missing_user",
+        "unknown_user",
+        "disabled",
+        "not_premium",
+        "scim_inactive",
+        "custom_validate",
+        "missing_database",
+    ],
+)
+async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    rejection: str,
+) -> None:
+    from cryptography.hazmat.primitives.asymmetric import rsa
+
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+
+    handler, signing_key = jwt_oauth_identity
+    key: Final = (
+        rsa.generate_private_key(public_exponent=65537, key_size=2048) if rejection == "signature" else signing_key
+    )
+    bearer: Final = _oauth_identity_jwt(
+        key,
+        expires_in=-60 if rejection == "expired" else 300,
+        audience="upstream-only" if rejection == "audience" else "litellm-proxy",
+        issuer="https://untrusted.example.test" if rejection == "issuer" else "https://idp.example.test",
+        owner=None if rejection == "missing_user" else "unknown" if rejection == "unknown_user" else "jwt-owner",
+    )
+    if rejection == "disabled":
+        monkeypatch.setattr(proxy_server, "general_settings", {"enable_jwt_auth": False})
+    if rejection == "not_premium":
+        monkeypatch.setattr(proxy_server, "premium_user", False)
+    if rejection == "missing_database":
+        monkeypatch.setattr(proxy_server, "prisma_client", None)
+    if rejection == "scim_inactive":
+        handler.user_api_key_cache.set_cache(
+            "jwt-owner", LiteLLM_UserTable(user_id="jwt-owner", metadata={"scim_active": False})
+        )
+    if rejection == "custom_validate":
+        handler.litellm_jwtauth.custom_validate = lambda claims: False
+    assert await _extract_user_id_from_request(_token_request({"Authorization": f"Bearer {bearer}"})) is None
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("blocked", [False, True])
+async def test_oauth_jwt_cannot_override_explicit_litellm_key(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    blocked: bool,
+) -> None:
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._types import UserAPIKeyAuth, hash_token
+
+    handler, signing_key = jwt_oauth_identity
+    key: Final = "sk-explicit-key"
+    handler.user_api_key_cache.set_cache(hash_token(key), UserAPIKeyAuth(user_id="key-owner", blocked=blocked))
+    request: Final = _token_request(
+        {
+            "Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}",
+            "x-litellm-api-key": key,
+        }
+    )
+    assert await _extract_user_id_from_request(request) == (None if blocked else "key-owner")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mapping", ["active", "blocked", "inactive_owner", "fallback", "pending", "reject"])
+async def test_oauth_jwt_uses_configured_virtual_key_owner(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    mapping: str,
+) -> None:
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._types import UserAPIKeyAuth, UnregisteredJWTClientBehavior, hash_token
+    from litellm.proxy.auth.auth_checks import jwt_key_mapping_cache_key
+
+    handler, signing_key = jwt_oauth_identity
+    handler.litellm_jwtauth.virtual_key_claim_field = "sub"
+    handler.litellm_jwtauth.unregistered_jwt_client_behavior = (
+        UnregisteredJWTClientBehavior.AUTO_REGISTER
+        if mapping == "pending"
+        else UnregisteredJWTClientBehavior.REJECT
+        if mapping == "reject"
+        else UnregisteredJWTClientBehavior.FALLBACK_TEAM_MAPPING
+    )
+    key_hash: Final = hash_token("sk-mapped-oauth-owner")
+    handler.user_api_key_cache.set_cache(
+        jwt_key_mapping_cache_key("sub", "not-the-configured-user-id"),
+        "__NO_MAPPING__" if mapping in ("fallback", "pending", "reject") else key_hash,
+    )
+    handler.user_api_key_cache.set_cache(
+        key_hash, UserAPIKeyAuth(token=key_hash, user_id="mapped-owner", blocked=mapping == "blocked")
+    )
+    handler.user_api_key_cache.set_cache(
+        "mapped-owner", LiteLLM_UserTable(user_id="mapped-owner", metadata={"scim_active": mapping != "inactive_owner"})
+    )
+    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
+    expected: Final = "jwt-owner" if mapping == "fallback" else "mapped-owner" if mapping == "active" else None
+    assert await _extract_user_id_from_request(request) == expected
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("allowed_domain", [None, "allowed.example.test"])
+async def test_oauth_jwt_respects_custom_validation_and_email_policy(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    allowed_domain: str | None,
+) -> None:
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+
+    handler, signing_key = jwt_oauth_identity
+    handler.litellm_jwtauth.custom_validate = lambda claims: True
+    handler.litellm_jwtauth.user_allowed_email_domain = allowed_domain
+    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
+    assert await _extract_user_id_from_request(request) == (None if allowed_domain else "jwt-owner")
+
+
+@pytest.mark.asyncio
+async def test_oauth_jwt_uses_rbac_user_object_id(jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"]) -> None:
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._types import LitellmUserRoles, RoleMapping
+
+    handler, signing_key = jwt_oauth_identity
+    handler.litellm_jwtauth.user_id_jwt_field = "sub"
+    handler.litellm_jwtauth.roles_jwt_field = "aud"
+    handler.litellm_jwtauth.object_id_jwt_field = "identity.user_id"
+    handler.litellm_jwtauth.role_mappings = [
+        RoleMapping(role="litellm-proxy", internal_role=LitellmUserRoles.INTERNAL_USER)
+    ]
+    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
+    assert await _extract_user_id_from_request(request) == "jwt-owner"

From eda98f38d940ecd065aee71d4b0b34ba1be98a06 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 12:41:12 -0700
Subject: [PATCH 02/67] fix(mcp): preserve canonical JWT owner lookup without
 cached identity

---
 .../mcp_server/bridge_token_flow.py           | 10 ++++--
 .../mcp_server/test_discoverable_endpoints.py | 36 +++++++++++++++++++
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 8dcc49c2fd8..3817935bf71 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -198,7 +198,9 @@ async def _reload_active_user_by_id(user_id: str) -> "_KeyResolutionFailure | No
     return loaded if isinstance(loaded, str) else None
 
 
-async def load_active_user_by_id(user_id: str) -> "LiteLLM_UserTable | _KeyResolutionFailure":
+async def load_active_user_by_id(
+    user_id: str, *, sso_user_id: str | None = None, user_email: str | None = None
+) -> "LiteLLM_UserTable | _KeyResolutionFailure":
     """Load a live litellm user by id, returning the record when the user is active or a precise
     failure otherwise. The interactive DCR client authenticates via SSO, so its refresh envelope seals a
     user subject; renewing it must re-check the user is still live (present and not SCIM-deactivated) so a
@@ -232,6 +234,8 @@ async def load_active_user_by_id(user_id: str) -> "LiteLLM_UserTable | _KeyResol
             prisma_client=prisma_client,
             user_api_key_cache=user_api_key_cache,
             user_id_upsert=False,
+            sso_user_id=sso_user_id,
+            user_email=user_email,
         )
     except (ProxyException, HTTPException):
         return "no_active_key"
@@ -352,7 +356,7 @@ async def _extract_jwt_user_id(token: str) -> str | None:
                 return None if await _key_owner_scim_deactivated(mapped) else _active_key_user_id(mapped)
             if mapped is not None:
                 return None
-        user_id, _, valid_email = await JWTAuthManager.get_user_info(jwt_handler, claims)
+        user_id, user_email, valid_email = await JWTAuthManager.get_user_info(jwt_handler, claims)
         object_id: Final = jwt_handler.get_object_id(token=claims, default_value=None)
         owner_id: Final = (
             object_id
@@ -361,7 +365,7 @@ async def _extract_jwt_user_id(token: str) -> str | None:
         )
         if not owner_id or valid_email is False:
             return None
-        owner: Final = await load_active_user_by_id(owner_id)
+        owner: Final = await load_active_user_by_id(owner_id, sso_user_id=owner_id, user_email=user_email)
         return None if isinstance(owner, str) else owner.user_id
     except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
         verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index af4c9eea770..ce985064eb0 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -11428,6 +11428,7 @@ def _oauth_identity_jwt(
         {
             "sub": "not-the-configured-user-id",
             "identity": {"user_id": owner},
+            "email": "owner@example.test",
             "iss": issuer,
             "aud": audience,
             "exp": int(time.time()) + expires_in,
@@ -11649,3 +11650,38 @@ async def test_oauth_jwt_uses_rbac_user_object_id(jwt_oauth_identity: tuple["JWT
     ]
     request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
     assert await _extract_user_id_from_request(request) == "jwt-owner"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("identity", ["sso", "email"])
+@pytest.mark.parametrize("inactive", [False, True])
+async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    identity: str,
+    inactive: bool,
+) -> None:
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+
+    handler, signing_key = jwt_oauth_identity
+    external_id: Final = f"external-{identity}-{inactive}"
+    handler.litellm_jwtauth.user_email_jwt_field = "email"
+    owner: Final = LiteLLM_UserTable(
+        user_id="canonical-oauth-owner",
+        user_email="owner@example.test",
+        metadata={"scim_active": not inactive},
+        organization_memberships=[],
+    )
+    database: Final = MagicMock()
+    table: Final = database.db.litellm_usertable
+    table.find_unique = AsyncMock(side_effect=[None, owner if identity == "sso" else None])
+    table.find_first = AsyncMock(return_value=owner)
+    table.update = AsyncMock(return_value=owner)
+    monkeypatch.setattr(proxy_server, "prisma_client", database)
+    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key, owner=external_id)}"})
+    assert await _extract_user_id_from_request(request) == (None if inactive else "canonical-oauth-owner")
+    assert table.find_unique.await_count == 2
+    if identity == "email":
+        table.find_first.assert_awaited_once()

From 5b0fa890568d2fd154d202297200a4ff61085933 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 22:16:12 +0000
Subject: [PATCH 03/67] feat(ui): show average response time per model in usage
 model activity

Roll request_duration_ms of successful, non-internal requests into the
daily spend tables as total_response_time_ms plus timed_requests, expose
both through the daily activity endpoints, and derive the average in the
Usage -> Model Activity view of the Admin UI

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../migration.sql                             |  23 ++++
 .../litellm_proxy_extras/schema.prisma        |  12 ++
 litellm/proxy/_lazy_openapi_snapshot.json     |  20 +++
 litellm/proxy/_types.py                       |   2 +
 litellm/proxy/db/daily_spend_bulk_upsert.py   |   2 +
 litellm/proxy/db/db_spend_update_writer.py    |  16 +++
 .../daily_spend_update_queue.py               |   8 ++
 .../common_daily_activity.py                  |  24 +++-
 litellm/proxy/schema.prisma                   |  12 ++
 .../common_daily_activity.py                  |   6 +
 schema.prisma                                 |  12 ++
 .../test_daily_spend_update_queue.py          |  12 +-
 .../proxy/db/test_daily_spend_bulk_upsert.py  |  17 ++-
 .../proxy/db/test_db_spend_update_writer.py   |  70 ++++++++++
 .../test_common_daily_activity.py             |  79 +++++++++++
 .../hooks/usePaginatedDailyActivity.test.ts   |   2 +
 .../hooks/usePaginatedDailyActivity.ts        |   4 +
 .../src/components/UsagePage/types.ts         |   5 +
 .../UsagePage/utils/value_formatters.test.ts  |  33 ++++-
 .../UsagePage/utils/value_formatters.tsx      |  11 ++
 .../src/components/activity_metrics.test.tsx  | 127 ++++++++++++++++++
 .../src/components/activity_metrics.tsx       |  52 ++++++-
 ui/litellm-dashboard/src/lib/http/schema.d.ts |  20 +++
 23 files changed, 557 insertions(+), 12 deletions(-)
 create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260915000000_add_daily_response_time/migration.sql

diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260915000000_add_daily_response_time/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260915000000_add_daily_response_time/migration.sql
new file mode 100644
index 00000000000..79382ef9d63
--- /dev/null
+++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260915000000_add_daily_response_time/migration.sql
@@ -0,0 +1,23 @@
+-- AlterTable
+ALTER TABLE "LiteLLM_DailyUserSpend" ADD COLUMN IF NOT EXISTS "total_response_time_ms" BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE "LiteLLM_DailyUserSpend" ADD COLUMN IF NOT EXISTS "timed_requests" BIGINT NOT NULL DEFAULT 0;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_DailyOrganizationSpend" ADD COLUMN IF NOT EXISTS "total_response_time_ms" BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE "LiteLLM_DailyOrganizationSpend" ADD COLUMN IF NOT EXISTS "timed_requests" BIGINT NOT NULL DEFAULT 0;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_DailyEndUserSpend" ADD COLUMN IF NOT EXISTS "total_response_time_ms" BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE "LiteLLM_DailyEndUserSpend" ADD COLUMN IF NOT EXISTS "timed_requests" BIGINT NOT NULL DEFAULT 0;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_DailyAgentSpend" ADD COLUMN IF NOT EXISTS "total_response_time_ms" BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE "LiteLLM_DailyAgentSpend" ADD COLUMN IF NOT EXISTS "timed_requests" BIGINT NOT NULL DEFAULT 0;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_DailyTeamSpend" ADD COLUMN IF NOT EXISTS "total_response_time_ms" BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE "LiteLLM_DailyTeamSpend" ADD COLUMN IF NOT EXISTS "timed_requests" BIGINT NOT NULL DEFAULT 0;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_DailyTagSpend" ADD COLUMN IF NOT EXISTS "total_response_time_ms" BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE "LiteLLM_DailyTagSpend" ADD COLUMN IF NOT EXISTS "timed_requests" BIGINT NOT NULL DEFAULT 0;
diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
index 8072df5aa5b..754614d03ea 100644
--- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
+++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
@@ -797,6 +797,8 @@ model LiteLLM_DailyUserSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
@@ -833,6 +835,8 @@ model LiteLLM_DailyOrganizationSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
@@ -869,6 +873,8 @@ model LiteLLM_DailyEndUserSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
   @@unique([end_user_id, date, api_key, model, custom_llm_provider, mcp_namespaced_tool_name, endpoint])
@@ -904,6 +910,8 @@ model LiteLLM_DailyAgentSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
   @@unique([agent_id, date, api_key, model, custom_llm_provider, mcp_namespaced_tool_name, endpoint])
@@ -939,6 +947,8 @@ model LiteLLM_DailyTeamSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   ptu_flat_cost       Float    @default(0.0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
@@ -977,6 +987,8 @@ model LiteLLM_DailyTagSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json
index f3b579d22c7..fdb84a043e4 100644
--- a/litellm/proxy/_lazy_openapi_snapshot.json
+++ b/litellm/proxy/_lazy_openapi_snapshot.json
@@ -3125,6 +3125,11 @@
               "title": "Total Prompt Tokens",
               "type": "integer"
             },
+            "total_response_time_ms": {
+              "default": 0,
+              "title": "Total Response Time Ms",
+              "type": "integer"
+            },
             "total_spend": {
               "default": 0.0,
               "title": "Total Spend",
@@ -3135,6 +3140,11 @@
               "title": "Total Successful Requests",
               "type": "integer"
             },
+            "total_timed_requests": {
+              "default": 0,
+              "title": "Total Timed Requests",
+              "type": "integer"
+            },
             "total_tokens": {
               "default": 0,
               "title": "Total Tokens",
@@ -3643,6 +3653,16 @@
               "title": "Successful Requests",
               "type": "integer"
             },
+            "timed_requests": {
+              "default": 0,
+              "title": "Timed Requests",
+              "type": "integer"
+            },
+            "total_response_time_ms": {
+              "default": 0,
+              "title": "Total Response Time Ms",
+              "type": "integer"
+            },
             "total_tokens": {
               "default": 0,
               "title": "Total Tokens",
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index afc2150934e..6b177460e30 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -5214,6 +5214,8 @@ class BaseDailySpendTransaction(TypedDict):
     api_requests: int
     successful_requests: int
     failed_requests: int
+    total_response_time_ms: NotRequired[int]  # writable-ok: the rollup queue accumulates into this key in place
+    timed_requests: NotRequired[int]  # writable-ok: the rollup queue accumulates into this key in place
 
 
 class DailyTeamSpendTransaction(BaseDailySpendTransaction):
diff --git a/litellm/proxy/db/daily_spend_bulk_upsert.py b/litellm/proxy/db/daily_spend_bulk_upsert.py
index a143643577e..108b0e884ba 100644
--- a/litellm/proxy/db/daily_spend_bulk_upsert.py
+++ b/litellm/proxy/db/daily_spend_bulk_upsert.py
@@ -57,6 +57,8 @@ _COUNTER_COLUMNS: Final = (
     "cache_read_input_tokens",
     "cache_creation_input_tokens",
     "compression_saved_tokens",
+    "total_response_time_ms",
+    "timed_requests",
 )
 _SPEND_COLUMNS: Final = (
     "spend",
diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index eaa03c5d7f7..52e4a645d51 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -131,6 +131,19 @@ class _SpendTransactionManager(Protocol):
     async def __aexit__(self, exc_type: object, exc_value: object, traceback: object) -> bool | None: ...
 
 
+def _timed_request_duration_ms(
+    payload: dict | SpendLogsPayload,
+    request_status: Literal["success", "failure"],
+    is_internal_call: bool,
+) -> int | None:
+    if is_internal_call or request_status != "success":
+        return None
+    duration_ms: Final = payload.get("request_duration_ms")
+    if not isinstance(duration_ms, int) or duration_ms < 0:
+        return None
+    return duration_ms
+
+
 def _spend_update_tx(prisma_client: PrismaClient) -> _SpendTransactionManager:
     tx: Final[_SpendTransactionManager] = prisma_client.db.tx(timeout=timedelta(seconds=60))
     return tx
@@ -2191,6 +2204,7 @@ class DBSpendUpdateWriter:
                 recorded_autorouter_savings=_metadata.get("autorouter_savings"),
                 billed_at=payload.get("endTime"),
             )
+            timed_duration_ms: Final = _timed_request_duration_ms(payload, request_status, is_internal_call)
 
             daily_transaction: Final = BaseDailySpendTransaction(
                 date=date,
@@ -2218,6 +2232,8 @@ class DBSpendUpdateWriter:
                 prompt_caching_savings_spend=savings_spend.prompt_caching,
                 gateway_injected_caching_savings_spend=savings_spend.gateway_injected_caching,
                 autorouter_savings_spend=0.0 if is_internal_call else savings_spend.autorouter,
+                total_response_time_ms=timed_duration_ms or 0,
+                timed_requests=0 if timed_duration_ms is None else 1,
             )
             return daily_transaction
         except Exception as e:
diff --git a/litellm/proxy/db/db_transaction_queue/daily_spend_update_queue.py b/litellm/proxy/db/db_transaction_queue/daily_spend_update_queue.py
index 70a529900b2..c6381cd070b 100644
--- a/litellm/proxy/db/db_transaction_queue/daily_spend_update_queue.py
+++ b/litellm/proxy/db/db_transaction_queue/daily_spend_update_queue.py
@@ -142,6 +142,14 @@ class DailySpendUpdateQueue(BaseUpdateQueue):
                         payload.get("autorouter_savings_spend", 0) or 0
                     ) + daily_transaction.get("autorouter_savings_spend", 0)
 
+                    daily_transaction["total_response_time_ms"] = (
+                        payload.get("total_response_time_ms", 0) or 0
+                    ) + daily_transaction.get("total_response_time_ms", 0)
+
+                    daily_transaction["timed_requests"] = (
+                        payload.get("timed_requests", 0) or 0
+                    ) + daily_transaction.get("timed_requests", 0)
+
                 else:
                     aggregated_daily_spend_update_transactions[_key] = deepcopy(payload)
         return aggregated_daily_spend_update_transactions
diff --git a/litellm/proxy/management_endpoints/common_daily_activity.py b/litellm/proxy/management_endpoints/common_daily_activity.py
index 44ed0017e42..cac7a9b6d98 100644
--- a/litellm/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/proxy/management_endpoints/common_daily_activity.py
@@ -114,6 +114,12 @@ class DailySpendRecord(Protocol):
     @property
     def failed_requests(self) -> int: ...
 
+    @property
+    def total_response_time_ms(self) -> int: ...
+
+    @property
+    def timed_requests(self) -> int: ...
+
 
 class _KeyMetadataDict(TypedDict, total=False):
     key_alias: ReadOnly[str | None]
@@ -162,6 +168,8 @@ class _GroupingSetsRow(SimpleNamespace):
     api_requests: int | None
     successful_requests: int | None
     failed_requests: int | None
+    total_response_time_ms: int | None
+    timed_requests: int | None
 
 
 class _EntityRollupRow(_GroupingSetsRow):
@@ -217,6 +225,8 @@ def update_metrics(existing_metrics: SpendMetrics, record: DailySpendRecord) ->
     existing_metrics.api_requests += record.api_requests or 0
     existing_metrics.successful_requests += record.successful_requests or 0
     existing_metrics.failed_requests += record.failed_requests or 0
+    existing_metrics.total_response_time_ms += record.total_response_time_ms or 0
+    existing_metrics.timed_requests += record.timed_requests or 0
     return existing_metrics
 
 
@@ -767,7 +777,9 @@ def _build_aggregated_sql_query(
             SUM(autorouter_savings_spend)::float AS autorouter_savings_spend,
             SUM(api_requests)::bigint AS api_requests,
             SUM(successful_requests)::bigint AS successful_requests,
-            SUM(failed_requests)::bigint AS failed_requests
+            SUM(failed_requests)::bigint AS failed_requests,
+            SUM(total_response_time_ms)::bigint AS total_response_time_ms,
+            SUM(timed_requests)::bigint AS timed_requests
         FROM "{pg_table}"
         WHERE {where_clause}
         GROUP BY GROUPING SETS (
@@ -846,7 +858,9 @@ def _build_entity_rollup_sql_query(
             SUM(autorouter_savings_spend)::float AS autorouter_savings_spend,
             SUM(api_requests)::bigint AS api_requests,
             SUM(successful_requests)::bigint AS successful_requests,
-            SUM(failed_requests)::bigint AS failed_requests
+            SUM(failed_requests)::bigint AS failed_requests,
+            SUM(total_response_time_ms)::bigint AS total_response_time_ms,
+            SUM(timed_requests)::bigint AS timed_requests
         FROM "{pg_table}"
         WHERE {where_clause}
         GROUP BY GROUPING SETS (
@@ -985,6 +999,8 @@ def _record_to_spend_metrics(record: _GroupingSetsRow) -> SpendMetrics:
         api_requests=record.api_requests or 0,
         successful_requests=record.successful_requests or 0,
         failed_requests=record.failed_requests or 0,
+        total_response_time_ms=record.total_response_time_ms or 0,
+        timed_requests=record.timed_requests or 0,
     )
 
 
@@ -1246,6 +1262,8 @@ async def get_daily_activity(
                 total_prompt_caching_savings_spend=metadata_metrics.prompt_caching_savings_spend,
                 total_gateway_injected_caching_savings_spend=metadata_metrics.gateway_injected_caching_savings_spend,
                 total_autorouter_savings_spend=metadata_metrics.autorouter_savings_spend,
+                total_response_time_ms=metadata_metrics.total_response_time_ms,
+                total_timed_requests=metadata_metrics.timed_requests,
                 page=page,
                 total_pages=-(-total_count // page_size),  # Ceiling division
                 has_more=(page * page_size) < total_count,
@@ -1423,6 +1441,8 @@ async def get_daily_activity_aggregated(
                     "totals"
                 ].gateway_injected_caching_savings_spend,
                 total_autorouter_savings_spend=aggregated["totals"].autorouter_savings_spend,
+                total_response_time_ms=aggregated["totals"].total_response_time_ms,
+                total_timed_requests=aggregated["totals"].timed_requests,
                 page=1,
                 total_pages=1,
                 has_more=False,
diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma
index 8072df5aa5b..754614d03ea 100644
--- a/litellm/proxy/schema.prisma
+++ b/litellm/proxy/schema.prisma
@@ -797,6 +797,8 @@ model LiteLLM_DailyUserSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
@@ -833,6 +835,8 @@ model LiteLLM_DailyOrganizationSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
@@ -869,6 +873,8 @@ model LiteLLM_DailyEndUserSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
   @@unique([end_user_id, date, api_key, model, custom_llm_provider, mcp_namespaced_tool_name, endpoint])
@@ -904,6 +910,8 @@ model LiteLLM_DailyAgentSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
   @@unique([agent_id, date, api_key, model, custom_llm_provider, mcp_namespaced_tool_name, endpoint])
@@ -939,6 +947,8 @@ model LiteLLM_DailyTeamSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   ptu_flat_cost       Float    @default(0.0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
@@ -977,6 +987,8 @@ model LiteLLM_DailyTagSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
diff --git a/litellm/types/proxy/management_endpoints/common_daily_activity.py b/litellm/types/proxy/management_endpoints/common_daily_activity.py
index 090e5c42376..278af61a117 100644
--- a/litellm/types/proxy/management_endpoints/common_daily_activity.py
+++ b/litellm/types/proxy/management_endpoints/common_daily_activity.py
@@ -32,6 +32,8 @@ class SpendMetrics(BaseModel):
     successful_requests: int = Field(default=0)
     failed_requests: int = Field(default=0)
     api_requests: int = Field(default=0)
+    total_response_time_ms: int = Field(default=0)
+    timed_requests: int = Field(default=0)
 
 
 class MetricBase(BaseModel):
@@ -93,6 +95,8 @@ class DailySpendMetadata(BaseModel):
     total_prompt_caching_savings_spend: float = Field(default=0.0)
     total_gateway_injected_caching_savings_spend: float = Field(default=0.0)
     total_autorouter_savings_spend: float = Field(default=0.0)
+    total_response_time_ms: int = Field(default=0)
+    total_timed_requests: int = Field(default=0)
     page: int = Field(default=1)
     total_pages: int = Field(default=1)
     has_more: bool = Field(default=False)
@@ -125,6 +129,8 @@ class LiteLLM_DailyUserSpend(BaseModel):
     api_requests: int = 0
     successful_requests: int = 0
     failed_requests: int = 0
+    total_response_time_ms: int = 0
+    timed_requests: int = 0
 
 
 class GroupedData(TypedDict):
diff --git a/schema.prisma b/schema.prisma
index 8072df5aa5b..754614d03ea 100644
--- a/schema.prisma
+++ b/schema.prisma
@@ -797,6 +797,8 @@ model LiteLLM_DailyUserSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
@@ -833,6 +835,8 @@ model LiteLLM_DailyOrganizationSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
@@ -869,6 +873,8 @@ model LiteLLM_DailyEndUserSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
   @@unique([end_user_id, date, api_key, model, custom_llm_provider, mcp_namespaced_tool_name, endpoint])
@@ -904,6 +910,8 @@ model LiteLLM_DailyAgentSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
   @@unique([agent_id, date, api_key, model, custom_llm_provider, mcp_namespaced_tool_name, endpoint])
@@ -939,6 +947,8 @@ model LiteLLM_DailyTeamSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   ptu_flat_cost       Float    @default(0.0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
@@ -977,6 +987,8 @@ model LiteLLM_DailyTagSpend {
   api_requests        BigInt      @default(0)
   successful_requests BigInt      @default(0)
   failed_requests     BigInt      @default(0)
+  total_response_time_ms BigInt   @default(0)
+  timed_requests      BigInt      @default(0)
   created_at          DateTime @default(now())
   updated_at          DateTime @updatedAt
 
diff --git a/tests/test_litellm/proxy/db/db_transaction_queue/test_daily_spend_update_queue.py b/tests/test_litellm/proxy/db/db_transaction_queue/test_daily_spend_update_queue.py
index 681132105ad..c17ba75db03 100644
--- a/tests/test_litellm/proxy/db/db_transaction_queue/test_daily_spend_update_queue.py
+++ b/tests/test_litellm/proxy/db/db_transaction_queue/test_daily_spend_update_queue.py
@@ -209,6 +209,8 @@ async def test_get_aggregated_daily_spend_update_transactions_same_key():
         "prompt_caching_savings_spend": 0,
         "gateway_injected_caching_savings_spend": 0,
         "autorouter_savings_spend": 0,
+        "total_response_time_ms": 0,
+        "timed_requests": 0,
     }
 
     updates = [{test_key: test_transaction1}, {test_key: test_transaction2}]
@@ -261,6 +263,8 @@ async def test_flush_and_get_aggregated_daily_spend_update_transactions(
         "prompt_caching_savings_spend": 0,
         "gateway_injected_caching_savings_spend": 0,
         "autorouter_savings_spend": 0,
+        "total_response_time_ms": 0,
+        "timed_requests": 0,
     }
 
     # Add updates to queue
@@ -550,7 +554,7 @@ async def test_every_optional_daily_metric_aggregates(daily_spend_update_queue):
     numeric_fields = [
         name for name, annotation in BaseDailySpendTransaction.__annotations__.items() if _numeric(annotation)
     ]
-    assert "autorouter_savings_spend" in numeric_fields
+    assert {"autorouter_savings_spend", "total_response_time_ms", "timed_requests"} <= set(numeric_fields)
     increments = {field: index + 1 for index, field in enumerate(numeric_fields)}
 
     await daily_spend_update_queue.add_update({test_key: dict(increments)})
@@ -579,8 +583,12 @@ async def test_optional_metric_missing_from_an_older_payload_still_aggregates(
     }
 
     await daily_spend_update_queue.add_update({test_key: dict(base)})
-    await daily_spend_update_queue.add_update({test_key: {**base, "autorouter_savings_spend": 0.25}})
+    await daily_spend_update_queue.add_update(
+        {test_key: {**base, "autorouter_savings_spend": 0.25, "total_response_time_ms": 900, "timed_requests": 1}}
+    )
     await daily_spend_update_queue.aggregate_queue_updates()
     updates = await daily_spend_update_queue.flush_all_updates_from_in_memory_queue()
 
     assert updates[0][test_key]["autorouter_savings_spend"] == pytest.approx(0.25)
+    assert updates[0][test_key]["total_response_time_ms"] == 900
+    assert updates[0][test_key]["timed_requests"] == 1
diff --git a/tests/test_litellm/proxy/db/test_daily_spend_bulk_upsert.py b/tests/test_litellm/proxy/db/test_daily_spend_bulk_upsert.py
index c1efb3e7220..510f77cecec 100644
--- a/tests/test_litellm/proxy/db/test_daily_spend_bulk_upsert.py
+++ b/tests/test_litellm/proxy/db/test_daily_spend_bulk_upsert.py
@@ -85,10 +85,10 @@ def test_one_statement_carries_every_row_in_the_batch():
 
     assert sql.count("INSERT INTO") == 1
     assert len(re.findall(r"ON CONFLICT", sql)) == 1
-    # 23 bound columns per row plus the inlined updated_at, so the row count is what
+    # 25 bound columns per row plus the inlined updated_at, so the row count is what
     # separates one multi-row statement from a hundred single-row ones.
-    assert len(params) == 100 * 23
-    assert "$2300::text" in sql
+    assert len(params) == 100 * 25
+    assert "$2500::text" in sql
     assert sql.count("(NOW() AT TIME ZONE 'UTC')") == 100 + 1
 
 
@@ -104,7 +104,16 @@ def test_conflict_target_is_the_full_unique_constraint():
 
 @pytest.mark.parametrize(
     "column",
-    ["prompt_tokens", "completion_tokens", "spend", "api_requests", "successful_requests", "failed_requests"],
+    [
+        "prompt_tokens",
+        "completion_tokens",
+        "spend",
+        "api_requests",
+        "successful_requests",
+        "failed_requests",
+        "total_response_time_ms",
+        "timed_requests",
+    ],
 )
 def test_counters_increment_rather_than_overwrite(column):
     """An overwrite would silently discard every earlier flush's spend for that row."""
diff --git a/tests/test_litellm/proxy/db/test_db_spend_update_writer.py b/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
index 5e977712a1e..82b8b5c55c5 100644
--- a/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
+++ b/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
@@ -2748,6 +2748,76 @@ async def test_daily_transaction_internal_call_keeps_spend_but_not_request_count
     assert user_sent["successful_requests"] == 1
 
 
+def _response_time_payload(request_duration_ms: object, metadata: dict | None = None) -> dict:
+    return {
+        "request_id": "req-timed-1",
+        "user": "test-user",
+        "startTime": "2026-09-15T00:00:00",
+        "api_key": "test-key",
+        "model": "gpt-5.5",
+        "custom_llm_provider": "openai",
+        "model_group": "gpt-5.5",
+        "call_type": "acompletion",
+        "prompt_tokens": 10,
+        "completion_tokens": 5,
+        "spend": 0.01,
+        "request_duration_ms": request_duration_ms,
+        "metadata": json.dumps(metadata or {}),
+    }
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("request_duration_ms", [1234, 0])
+async def test_daily_transaction_rolls_up_response_time_for_successful_requests(request_duration_ms: int):
+    """A successful user-sent request contributes its request_duration_ms to the daily
+    response-time sum and counts as one timed request, including a 0 ms duration."""
+    writer = DBSpendUpdateWriter()
+    mock_prisma = MagicMock()
+    mock_prisma.get_request_status = MagicMock(return_value="success")
+
+    transaction = await writer._common_add_spend_log_transaction_to_daily_transaction(
+        payload=_response_time_payload(request_duration_ms),
+        prisma_client=mock_prisma,
+        type="user",
+    )
+
+    assert transaction is not None
+    assert transaction["total_response_time_ms"] == request_duration_ms
+    assert transaction["timed_requests"] == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("request_status", "request_duration_ms", "metadata"),
+    [
+        ("failure", 1234, {}),
+        ("success", None, {}),
+        ("success", -5, {}),
+        ("success", "1234", {}),
+        ("success", 1234, {"internal_call_origin": "shadow_eval_judge"}),
+    ],
+    ids=["failed", "missing", "negative", "non_int", "internal_call"],
+)
+async def test_daily_transaction_excludes_untimed_requests_from_response_time(
+    request_status: str, request_duration_ms: object, metadata: dict
+):
+    """Failed, internal, and missing/invalid-duration requests never enter the response-time
+    average: both the duration sum and the timed_requests denominator stay at zero."""
+    writer = DBSpendUpdateWriter()
+    mock_prisma = MagicMock()
+    mock_prisma.get_request_status = MagicMock(return_value=request_status)
+
+    transaction = await writer._common_add_spend_log_transaction_to_daily_transaction(
+        payload=_response_time_payload(request_duration_ms, metadata),
+        prisma_client=mock_prisma,
+        type="user",
+    )
+
+    assert transaction is not None
+    assert transaction["total_response_time_ms"] == 0
+    assert transaction["timed_requests"] == 0
+
+
 def _deadlock_error():
     from prisma.errors import RawQueryError
 
diff --git a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
index 71896a18f48..b6dd5d04131 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py
@@ -157,6 +157,8 @@ async def test_get_daily_activity_aggregated_with_endpoint_breakdown():
         "prompt_caching_savings_spend": 0.0,
         "gateway_injected_caching_savings_spend": 0.0,
         "autorouter_savings_spend": 0.0,
+        "total_response_time_ms": 0,
+        "timed_requests": 0,
         "failed_requests": 0,
     }
     mock_rows = [
@@ -647,6 +649,8 @@ def test_update_breakdown_metrics_includes_user_email():
         prompt_caching_savings_spend=0,
         gateway_injected_caching_savings_spend=0,
         autorouter_savings_spend=0,
+        total_response_time_ms=0,
+        timed_requests=0,
         total_tokens=2,
         api_requests=1,
         successful_requests=1,
@@ -722,6 +726,8 @@ async def test_tag_daily_activity_metadata_totals_not_zero():
     mock_record_1.prompt_caching_savings_spend = 0.0
     mock_record_1.gateway_injected_caching_savings_spend = 0.0
     mock_record_1.autorouter_savings_spend = 0.0
+    mock_record_1.total_response_time_ms = 18_000
+    mock_record_1.timed_requests = 9
     mock_record_1.api_requests = 10
     mock_record_1.successful_requests = 9
     mock_record_1.failed_requests = 1
@@ -746,6 +752,8 @@ async def test_tag_daily_activity_metadata_totals_not_zero():
     mock_record_2.prompt_caching_savings_spend = 0.0
     mock_record_2.gateway_injected_caching_savings_spend = 0.0
     mock_record_2.autorouter_savings_spend = 0.0
+    mock_record_2.total_response_time_ms = 2_500
+    mock_record_2.timed_requests = 5
     mock_record_2.api_requests = 5
     mock_record_2.successful_requests = 5
     mock_record_2.failed_requests = 0
@@ -778,6 +786,8 @@ async def test_tag_daily_activity_metadata_totals_not_zero():
     assert result.metadata.total_successful_requests == 14  # 9 + 5
     assert result.metadata.total_failed_requests == 1
     assert result.metadata.total_tokens == 1100  # (500+200) + (300+100)
+    assert result.metadata.total_response_time_ms == 20_500
+    assert result.metadata.total_timed_requests == 14
 
     # Verify breakdown still works
     assert len(result.results) == 1
@@ -786,6 +796,10 @@ async def test_tag_daily_activity_metadata_totals_not_zero():
     assert "staging" in daily.breakdown.entities
     assert daily.breakdown.entities["production"].metrics.spend == 25.0
     assert daily.breakdown.entities["staging"].metrics.spend == 5.0
+    assert daily.breakdown.models["gpt-4"].metrics.total_response_time_ms == 18_000
+    assert daily.breakdown.models["gpt-4"].metrics.timed_requests == 9
+    assert daily.breakdown.models["gpt-3.5-turbo"].metrics.total_response_time_ms == 2_500
+    assert daily.breakdown.models["gpt-3.5-turbo"].metrics.timed_requests == 5
 
 
 @pytest.mark.asyncio
@@ -810,6 +824,8 @@ async def test_aggregated_activity_preserves_metadata_for_deleted_keys():
         "prompt_caching_savings_spend": 0.0,
         "gateway_injected_caching_savings_spend": 0.0,
         "autorouter_savings_spend": 0.0,
+        "total_response_time_ms": 0,
+        "timed_requests": 0,
         "failed_requests": 0,
     }
     mock_rows = [
@@ -900,6 +916,8 @@ def _daily_user_spend_record(*, user_id, api_key, spend, model="gpt-4", model_gr
         prompt_caching_savings_spend=0.0,
         gateway_injected_caching_savings_spend=0.0,
         autorouter_savings_spend=0.0,
+        total_response_time_ms=0,
+        timed_requests=0,
         api_requests=1,
         successful_requests=1,
         failed_requests=0,
@@ -1333,6 +1351,8 @@ async def test_get_daily_activity_aggregated_empty_result_set():
             "prompt_caching_savings_spend": None,
             "gateway_injected_caching_savings_spend": None,
             "autorouter_savings_spend": None,
+            "total_response_time_ms": None,
+            "timed_requests": None,
             "api_requests": None,
             "successful_requests": None,
             "failed_requests": None,
@@ -1378,6 +1398,8 @@ def _no_spend_record():
         prompt_caching_savings_spend=None,
         gateway_injected_caching_savings_spend=None,
         autorouter_savings_spend=None,
+        total_response_time_ms=None,
+        timed_requests=None,
         api_requests=None,
         successful_requests=None,
         failed_requests=None,
@@ -1465,6 +1487,55 @@ class TestEverySavingsDriverSurvivesTheReadPath:
             )
 
 
+class TestResponseTimeSurvivesTheReadPath:
+    """The dashboard averages total_response_time_ms over timed_requests, so both halves
+    of the pair must be summed by the rollup query, accumulated across rows, carried by
+    a single-row conversion, and coalesced when a NULL aggregate comes back."""
+
+    _FIELDS = ("total_response_time_ms", "timed_requests")
+
+    def test_both_halves_are_summed_by_the_rollup_query(self):
+        sql, _ = _build_aggregated_sql_query(
+            table_name="litellm_dailyuserspend",
+            entity_id_field="user_id",
+            entity_id="user-1",
+            start_date="2026-09-01",
+            end_date="2026-09-30",
+            model=None,
+            api_key=None,
+            timezone_offset_minutes=None,
+        )
+        for field in self._FIELDS:
+            assert f"SUM({field})" in sql, f"{field} is never summed, so the average reads as zero"
+
+    def test_accumulating_rows_keeps_sum_and_count_paired(self):
+        first = _no_spend_record()
+        first.total_response_time_ms = 1500
+        first.timed_requests = 2
+        second = _no_spend_record()
+        second.total_response_time_ms = 500
+        second.timed_requests = 1
+        metrics = update_metrics(update_metrics(SpendMetrics(), first), second)
+        assert metrics.total_response_time_ms == 2000
+        assert metrics.timed_requests == 3
+
+    def test_single_row_conversion_carries_both_halves(self):
+        record = _no_spend_record()
+        record.total_response_time_ms = 1234
+        record.timed_requests = 4
+        metrics = _record_to_spend_metrics(record)
+        assert metrics.total_response_time_ms == 1234
+        assert metrics.timed_requests == 4
+
+    def test_null_aggregates_read_as_zero(self):
+        metrics = _record_to_spend_metrics(_no_spend_record())
+        assert metrics.total_response_time_ms == 0
+        assert metrics.timed_requests == 0
+        accumulated = update_metrics(SpendMetrics(), _no_spend_record())
+        assert accumulated.total_response_time_ms == 0
+        assert accumulated.timed_requests == 0
+
+
 @pytest.fixture
 def ptu_cost_attribution_enabled(monkeypatch):
     monkeypatch.setenv(PTU_COST_ATTRIBUTION_ENV_VAR, "true")
@@ -1488,6 +1559,8 @@ def _spend_record(api_key, *, model="gpt-4o-mini-ptu", spend=0.0, ptu_flat_cost=
         prompt_caching_savings_spend=0,
         gateway_injected_caching_savings_spend=0,
         autorouter_savings_spend=0,
+        total_response_time_ms=0,
+        timed_requests=0,
         total_tokens=0,
         api_requests=0,
         successful_requests=0,
@@ -1554,6 +1627,8 @@ def _grouping_row(
         prompt_caching_savings_spend=0.0,
         gateway_injected_caching_savings_spend=0.0,
         autorouter_savings_spend=0.0,
+        total_response_time_ms=0,
+        timed_requests=0,
         api_requests=0,
         successful_requests=0,
         failed_requests=0,
@@ -1714,6 +1789,8 @@ def test_update_breakdown_metrics_covers_mcp_endpoint_and_entity(ptu_cost_attrib
         prompt_caching_savings_spend=0,
         gateway_injected_caching_savings_spend=0,
         autorouter_savings_spend=0,
+        total_response_time_ms=0,
+        timed_requests=0,
         total_tokens=0,
         api_requests=0,
         successful_requests=0,
@@ -2118,6 +2195,8 @@ async def test_get_daily_activity_aggregated_with_entity_breakdown():
         "prompt_caching_savings_spend": 0.0,
         "gateway_injected_caching_savings_spend": 0.0,
         "autorouter_savings_spend": 0.0,
+        "total_response_time_ms": 0,
+        "timed_requests": 0,
         "failed_requests": 0,
         "prompt_tokens": 0,
         "completion_tokens": 0,
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts
index 0537f469920..dd3a1238fb1 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.test.ts
@@ -43,6 +43,8 @@ describe("sumMetadata", () => {
       total_cache_read_input_tokens: 1,
       total_cache_creation_input_tokens: 1,
       total_flat_cost: 1,
+      total_response_time_ms: 1,
+      total_timed_requests: 1,
     };
     const merged = sumMetadata(page, page);
 
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts
index e023feda2e3..a666ddf6256 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/hooks/usePaginatedDailyActivity.ts
@@ -30,6 +30,8 @@ const SUMMABLE_METADATA_KEYS = [
   "total_cache_read_input_tokens",
   "total_cache_creation_input_tokens",
   "total_flat_cost",
+  "total_response_time_ms",
+  "total_timed_requests",
 ] as const;
 
 interface DailyActivityResponse {
@@ -76,6 +78,8 @@ const EMPTY_DATA: DailyActivityResponse = {
     total_failed_requests: 0,
     total_cache_read_input_tokens: 0,
     total_cache_creation_input_tokens: 0,
+    total_response_time_ms: 0,
+    total_timed_requests: 0,
     total_pages: 1,
     has_more: false,
     page: 1,
diff --git a/ui/litellm-dashboard/src/components/UsagePage/types.ts b/ui/litellm-dashboard/src/components/UsagePage/types.ts
index fd4f1350020..e8bd3cb3a87 100644
--- a/ui/litellm-dashboard/src/components/UsagePage/types.ts
+++ b/ui/litellm-dashboard/src/components/UsagePage/types.ts
@@ -14,6 +14,8 @@ export interface SpendMetrics {
   prompt_caching_savings_spend?: number;
   gateway_injected_caching_savings_spend?: number;
   autorouter_savings_spend?: number;
+  total_response_time_ms?: number;
+  timed_requests?: number;
 }
 
 export type DailyData = {
@@ -81,6 +83,8 @@ export interface ModelActivityData {
   prompt_tokens: number;
   completion_tokens: number;
   total_spend: number;
+  total_response_time_ms?: number;
+  total_timed_requests?: number;
   top_api_keys: TopApiKeyData[];
   top_models: TopModelData[];
   daily_data: {
@@ -95,6 +99,7 @@ export interface ModelActivityData {
       failed_requests: number;
       cache_read_input_tokens: number;
       cache_creation_input_tokens: number;
+      avg_response_time_ms?: number | null;
     };
   }[];
 }
diff --git a/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.test.ts b/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.test.ts
index 3d2504e6652..09e2529301f 100644
--- a/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.test.ts
+++ b/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.test.ts
@@ -1,5 +1,36 @@
 import { describe, expect, it } from "vitest";
-import { valueFormatter, valueFormatterSpend } from "./value_formatters";
+import { averageResponseTimeMs, formatResponseTime, valueFormatter, valueFormatterSpend } from "./value_formatters";
+
+describe("averageResponseTimeMs", () => {
+  it("divides the summed duration by the number of timed requests", () => {
+    expect(averageResponseTimeMs(6000, 4)).toBe(1500);
+    expect(averageResponseTimeMs(0, 3)).toBe(0);
+  });
+
+  it("returns null instead of dividing by zero when nothing was timed", () => {
+    expect(averageResponseTimeMs(0, 0)).toBeNull();
+    expect(averageResponseTimeMs(1200, 0)).toBeNull();
+  });
+});
+
+describe("formatResponseTime", () => {
+  it("shows sub-second durations in whole milliseconds", () => {
+    expect(formatResponseTime(0)).toBe("0ms");
+    expect(formatResponseTime(412.6)).toBe("413ms");
+    expect(formatResponseTime(999)).toBe("999ms");
+  });
+
+  it("shows durations of a second or more in seconds with two decimals", () => {
+    expect(formatResponseTime(1000)).toBe("1.00s");
+    expect(formatResponseTime(1500)).toBe("1.50s");
+    expect(formatResponseTime(12345)).toBe("12.35s");
+  });
+
+  it("shows a dash when there is no average to display", () => {
+    expect(formatResponseTime(null)).toBe("-");
+    expect(formatResponseTime(undefined)).toBe("-");
+  });
+});
 
 describe("valueFormatter", () => {
   it("should format numbers >= 1,000,000 as millions with 2 decimal places", () => {
diff --git a/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.tsx b/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.tsx
index a1fb3ec8bb4..b1373698965 100644
--- a/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.tsx
+++ b/ui/litellm-dashboard/src/components/UsagePage/utils/value_formatters.tsx
@@ -11,6 +11,17 @@ export function valueFormatter(number: number) {
   return number.toString();
 }
 
+export function averageResponseTimeMs(totalResponseTimeMs: number, timedRequests: number): number | null {
+  if (timedRequests <= 0) return null;
+  return totalResponseTimeMs / timedRequests;
+}
+
+export function formatResponseTime(ms: number | null | undefined) {
+  if (ms == null) return "-";
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
 export function valueFormatterSpend(number: number) {
   if (number === 0) return "$0";
   if (number >= 1_000_000_000) {
diff --git a/ui/litellm-dashboard/src/components/activity_metrics.test.tsx b/ui/litellm-dashboard/src/components/activity_metrics.test.tsx
index 914fe1872b6..2b3e74d6fe6 100644
--- a/ui/litellm-dashboard/src/components/activity_metrics.test.tsx
+++ b/ui/litellm-dashboard/src/components/activity_metrics.test.tsx
@@ -1424,6 +1424,133 @@ describe("processActivityData", () => {
 
     expect(result).toEqual({});
   });
+
+  it("sums response time per model and derives a per-day average over timed requests", () => {
+    const dayWithModel = (date: string, metrics: Partial<typeof EMPTY_SPEND_METRICS> & Record<string, number>) =>
+      createMockDailyData(date, EMPTY_SPEND_METRICS, {
+        ...EMPTY_BREAKDOWN,
+        models: {
+          "gpt-5.5": { metrics: { ...EMPTY_SPEND_METRICS, ...metrics }, metadata: {}, api_key_breakdown: {} },
+        },
+      });
+    const fourTimedRequests = {
+      api_requests: 4,
+      successful_requests: 4,
+      total_response_time_ms: 6000,
+      timed_requests: 4,
+    };
+    const oneTimedOneFailed = {
+      api_requests: 2,
+      successful_requests: 1,
+      failed_requests: 1,
+      total_response_time_ms: 500,
+      timed_requests: 1,
+    };
+    const onlyFailures = { api_requests: 1, successful_requests: 0, failed_requests: 1 };
+    const activity: { results: DailyData[] } = {
+      results: [
+        dayWithModel("2025-01-02", fourTimedRequests),
+        dayWithModel("2025-01-01", oneTimedOneFailed),
+        dayWithModel("2025-01-03", onlyFailures),
+      ],
+    };
+
+    const result = processActivityData(activity, "models");
+
+    expect(result["gpt-5.5"].total_response_time_ms).toBe(6500);
+    expect(result["gpt-5.5"].total_timed_requests).toBe(5);
+    expect(result["gpt-5.5"].daily_data.map((day) => day.metrics.avg_response_time_ms)).toEqual([500, 1500, null]);
+  });
+
+  it("treats rollups written before response time existed as zero timed requests", () => {
+    const activity: { results: DailyData[] } = {
+      results: [
+        createMockDailyData("2025-01-01", EMPTY_SPEND_METRICS, {
+          ...EMPTY_BREAKDOWN,
+          models: {
+            "gpt-5.5": {
+              metrics: { ...EMPTY_SPEND_METRICS, api_requests: 3, successful_requests: 3 },
+              metadata: {},
+              api_key_breakdown: {},
+            },
+          },
+        }),
+      ],
+    };
+
+    const result = processActivityData(activity, "models");
+
+    expect(result["gpt-5.5"].total_response_time_ms).toBe(0);
+    expect(result["gpt-5.5"].total_timed_requests).toBe(0);
+    expect(result["gpt-5.5"].daily_data[0].metrics.avg_response_time_ms).toBeNull();
+  });
+});
+
+describe("ActivityMetrics response time", () => {
+  const timedModel = createMockModelActivityData("GPT-5.5", {
+    total_response_time_ms: 6000,
+    total_timed_requests: 4,
+    daily_data: [
+      {
+        date: "2025-01-01",
+        metrics: {
+          prompt_tokens: 10,
+          completion_tokens: 5,
+          total_tokens: 15,
+          api_requests: 3,
+          spend: 1,
+          successful_requests: 3,
+          failed_requests: 0,
+          cache_read_input_tokens: 0,
+          cache_creation_input_tokens: 0,
+          avg_response_time_ms: 2000,
+        },
+      },
+      {
+        date: "2025-01-02",
+        metrics: {
+          prompt_tokens: 10,
+          completion_tokens: 5,
+          total_tokens: 15,
+          api_requests: 1,
+          spend: 1,
+          successful_requests: 1,
+          failed_requests: 0,
+          cache_read_input_tokens: 0,
+          cache_creation_input_tokens: 0,
+          avg_response_time_ms: 1000,
+        },
+      },
+    ],
+  });
+
+  it("shows the model's average response time in the summary card and the collapsed header", () => {
+    render(<ActivityMetrics modelMetrics={{ "gpt-5.5": timedModel }} />);
+
+    expect(screen.getByText("Avg Response Time")).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "1.50s" })).toBeInTheDocument();
+    expect(screen.getByText("over 4 timed successful requests")).toBeInTheDocument();
+    expect(screen.getByText("1.50s avg response")).toBeInTheDocument();
+  });
+
+  it("renders the per-day response time chart with duration-formatted axis ticks", () => {
+    render(<ActivityMetrics modelMetrics={{ "gpt-5.5": timedModel }} />);
+
+    expect(screen.getByText("Avg Response Time per day")).toBeInTheDocument();
+    expect(screen.getByText("Avg Response Time Ms")).toBeInTheDocument();
+    expect(screen.getAllByText(/^\d+(\.\d+)?(ms|s)$/).length).toBeGreaterThan(1);
+  });
+
+  it("shows a dash and no response time chart when the model has no timed requests", () => {
+    render(<ActivityMetrics modelMetrics={{ "gpt-5.5": createMockModelActivityData("GPT-5.5") }} />);
+
+    expect(screen.getByText("Avg Response Time")).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "-" })).toBeInTheDocument();
+    expect(screen.getByText("over 0 timed successful requests")).toBeInTheDocument();
+    expect(screen.queryByText(/avg response$/)).not.toBeInTheDocument();
+    expect(screen.queryByText("Avg Response Time per day")).not.toBeInTheDocument();
+    expect(screen.queryByText("Avg Response Time Ms")).not.toBeInTheDocument();
+  });
 });
 
 describe("formatKeyLabel", () => {
diff --git a/ui/litellm-dashboard/src/components/activity_metrics.tsx b/ui/litellm-dashboard/src/components/activity_metrics.tsx
index 7c40a91be29..b1df2b598e2 100644
--- a/ui/litellm-dashboard/src/components/activity_metrics.tsx
+++ b/ui/litellm-dashboard/src/components/activity_metrics.tsx
@@ -1,4 +1,4 @@
-import { AreaChart, BarChart, CustomLegend, CustomTooltip } from "@/components/shared/charts";
+import { AreaChart, BarChart, CustomLegend, CustomTooltip, LineChart } from "@/components/shared/charts";
 import { formatNumberWithCommas } from "@/utils/dataUtils";
 import { resolveTeamAliasFromTeamID } from "@/utils/teamUtils";
 import { Card, CardContent } from "@/components/ui/card";
@@ -9,13 +9,16 @@ import { Team } from "./key_team_helpers/key_list";
 import KeyModelUsageView from "./UsagePage/components/KeyModelUsageView";
 import { keyActivityLabel } from "./UsagePage/keyActivityLabel";
 import { DailyData, KeyMetricWithMetadata, ModelActivityData, TopApiKeyData, TopModelData } from "./UsagePage/types";
-import { valueFormatter } from "./UsagePage/utils/value_formatters";
+import { averageResponseTimeMs, formatResponseTime, valueFormatter } from "./UsagePage/utils/value_formatters";
 
 interface ActivityMetricsProps {
   modelMetrics: Record<string, ModelActivityData>;
   hidePromptCachingMetrics?: boolean;
 }
 
+const modelAverageResponseTimeMs = (metrics: ModelActivityData): number | null =>
+  averageResponseTimeMs(metrics.total_response_time_ms ?? 0, metrics.total_timed_requests ?? 0);
+
 const ModelSection = ({
   modelName,
   metrics,
@@ -28,7 +31,7 @@ const ModelSection = ({
   return (
     <div className="space-y-2">
       {/* Summary Cards */}
-      <div className="grid grid-cols-4 gap-4">
+      <div className="grid grid-cols-5 gap-4">
         <Card>
           <CardContent>
             <p className="text-sm text-muted-foreground">Total Requests</p>
@@ -62,6 +65,17 @@ const ModelSection = ({
             </p>
           </CardContent>
         </Card>
+        <Card>
+          <CardContent>
+            <p className="text-sm text-muted-foreground">Avg Response Time</p>
+            <h3 className="text-lg font-medium text-foreground">
+              {formatResponseTime(modelAverageResponseTimeMs(metrics))}
+            </h3>
+            <p className="text-sm text-muted-foreground">
+              over {(metrics.total_timed_requests ?? 0).toLocaleString()} timed successful requests
+            </p>
+          </CardContent>
+        </Card>
       </div>
 
       {metrics.top_api_keys && metrics.top_api_keys.length > 0 && (
@@ -154,6 +168,27 @@ const ModelSection = ({
           </CardContent>
         </Card>
 
+        {(metrics.total_timed_requests ?? 0) > 0 && (
+          <Card>
+            <CardContent>
+              <div className="flex justify-between items-center">
+                <h3 className="text-lg font-medium text-foreground">Avg Response Time per day</h3>
+                <CustomLegend categories={["metrics.avg_response_time_ms"]} colors={["amber"]} />
+              </div>
+              <LineChart
+                className="mt-4"
+                data={metrics.daily_data}
+                index="date"
+                categories={["metrics.avg_response_time_ms"]}
+                colors={["amber"]}
+                valueFormatter={formatResponseTime}
+                connectNulls={true}
+                showLegend={false}
+              />
+            </CardContent>
+          </Card>
+        )}
+
         <Card>
           <CardContent>
             <div className="flex justify-between items-center">
@@ -416,6 +451,9 @@ export const ActivityMetrics: React.FC<ActivityMetricsProps> = ({ modelMetrics,
                 <div className="flex space-x-4 text-sm text-muted-foreground">
                   <span>${formatNumberWithCommas(modelMetrics[modelName].total_spend, 2)}</span>
                   <span>{modelMetrics[modelName].total_requests.toLocaleString()} requests</span>
+                  {modelAverageResponseTimeMs(modelMetrics[modelName]) != null && (
+                    <span>{formatResponseTime(modelAverageResponseTimeMs(modelMetrics[modelName]))} avg response</span>
+                  )}
                 </div>
               </div>
             }
@@ -471,11 +509,15 @@ export const processActivityData = (
           total_spend: 0,
           total_cache_read_input_tokens: 0,
           total_cache_creation_input_tokens: 0,
+          total_response_time_ms: 0,
+          total_timed_requests: 0,
           top_api_keys: [],
           top_models: [],
           daily_data: [],
         };
       }
+      const dayResponseTimeMs = modelData.metrics.total_response_time_ms || 0;
+      const dayTimedRequests = modelData.metrics.timed_requests || 0;
       // Update totals
       modelMetrics[model].total_requests += modelData.metrics.api_requests;
       modelMetrics[model].prompt_tokens += modelData.metrics.prompt_tokens;
@@ -486,6 +528,9 @@ export const processActivityData = (
       modelMetrics[model].total_failed_requests += modelData.metrics.failed_requests;
       modelMetrics[model].total_cache_read_input_tokens += modelData.metrics.cache_read_input_tokens || 0;
       modelMetrics[model].total_cache_creation_input_tokens += modelData.metrics.cache_creation_input_tokens || 0;
+      modelMetrics[model].total_response_time_ms =
+        (modelMetrics[model].total_response_time_ms ?? 0) + dayResponseTimeMs;
+      modelMetrics[model].total_timed_requests = (modelMetrics[model].total_timed_requests ?? 0) + dayTimedRequests;
 
       // Add daily data
       modelMetrics[model].daily_data.push({
@@ -500,6 +545,7 @@ export const processActivityData = (
           failed_requests: modelData.metrics.failed_requests,
           cache_read_input_tokens: modelData.metrics.cache_read_input_tokens || 0,
           cache_creation_input_tokens: modelData.metrics.cache_creation_input_tokens || 0,
+          avg_response_time_ms: averageResponseTimeMs(dayResponseTimeMs, dayTimedRequests),
         },
       });
     });
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 4c16a8613eb..3b4498c2a1d 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -27505,6 +27505,11 @@ export interface components {
              * @default 0
              */
             total_prompt_tokens: number;
+            /**
+             * Total Response Time Ms
+             * @default 0
+             */
+            total_response_time_ms: number;
             /**
              * Total Spend
              * @default 0
@@ -27515,6 +27520,11 @@ export interface components {
              * @default 0
              */
             total_successful_requests: number;
+            /**
+             * Total Timed Requests
+             * @default 0
+             */
+            total_timed_requests: number;
             /**
              * Total Tokens
              * @default 0
@@ -37045,6 +37055,16 @@ export interface components {
              * @default 0
              */
             successful_requests: number;
+            /**
+             * Timed Requests
+             * @default 0
+             */
+            timed_requests: number;
+            /**
+             * Total Response Time Ms
+             * @default 0
+             */
+            total_response_time_ms: number;
             /**
              * Total Tokens
              * @default 0

From be082013f7cef4c167a92fee621f0fe8e20e733f Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 22:38:55 +0000
Subject: [PATCH 04/67] fix(ui): label the response time chart tooltip with the
 series name

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../src/components/activity_metrics.test.tsx  | 14 ++++++++++++-
 .../src/components/activity_metrics.tsx       | 21 ++++++++++++++++++-
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/activity_metrics.test.tsx b/ui/litellm-dashboard/src/components/activity_metrics.test.tsx
index 2b3e74d6fe6..1bd7655b5e3 100644
--- a/ui/litellm-dashboard/src/components/activity_metrics.test.tsx
+++ b/ui/litellm-dashboard/src/components/activity_metrics.test.tsx
@@ -1,7 +1,8 @@
 import { fireEvent, render, screen } from "@testing-library/react";
 import React from "react";
 import { beforeAll, describe, expect, it, vi } from "vitest";
-import { ActivityMetrics, formatKeyLabel, processActivityData } from "./activity_metrics";
+import { ActivityMetrics, formatKeyLabel, processActivityData, ResponseTimeTooltip } from "./activity_metrics";
+import type { ChartTooltipProps } from "@/components/shared/charts";
 import { Team } from "./key_team_helpers/key_list";
 import { DailyData, KeyMetricWithMetadata, ModelActivityData } from "./UsagePage/types";
 
@@ -1541,6 +1542,17 @@ describe("ActivityMetrics response time", () => {
     expect(screen.getAllByText(/^\d+(\.\d+)?(ms|s)$/).length).toBeGreaterThan(1);
   });
 
+  it("labels the chart tooltip with the readable series name and a formatted duration", () => {
+    const payload = [
+      { dataKey: "metrics.avg_response_time_ms", value: 1500, color: "#f59e0b", payload: timedModel.daily_data[0] },
+    ] as NonNullable<ChartTooltipProps["payload"]>;
+    render(<ResponseTimeTooltip active={true} payload={payload} label="2025-01-01" />);
+
+    expect(screen.getByText("Avg Response Time Ms")).toBeInTheDocument();
+    expect(screen.getByText("1.50s")).toBeInTheDocument();
+    expect(screen.queryByText("metrics.avg_response_time_ms")).not.toBeInTheDocument();
+  });
+
   it("shows a dash and no response time chart when the model has no timed requests", () => {
     render(<ActivityMetrics modelMetrics={{ "gpt-5.5": createMockModelActivityData("GPT-5.5") }} />);
 
diff --git a/ui/litellm-dashboard/src/components/activity_metrics.tsx b/ui/litellm-dashboard/src/components/activity_metrics.tsx
index b1df2b598e2..95315f8ec27 100644
--- a/ui/litellm-dashboard/src/components/activity_metrics.tsx
+++ b/ui/litellm-dashboard/src/components/activity_metrics.tsx
@@ -1,4 +1,13 @@
-import { AreaChart, BarChart, CustomLegend, CustomTooltip, LineChart } from "@/components/shared/charts";
+import {
+  AreaChart,
+  BarChart,
+  type ChartTooltipProps,
+  CustomLegend,
+  CustomTooltip,
+  formatCategoryName,
+  LineChart,
+  ValueTooltip,
+} from "@/components/shared/charts";
 import { formatNumberWithCommas } from "@/utils/dataUtils";
 import { resolveTeamAliasFromTeamID } from "@/utils/teamUtils";
 import { Card, CardContent } from "@/components/ui/card";
@@ -19,6 +28,15 @@ interface ActivityMetricsProps {
 const modelAverageResponseTimeMs = (metrics: ModelActivityData): number | null =>
   averageResponseTimeMs(metrics.total_response_time_ms ?? 0, metrics.total_timed_requests ?? 0);
 
+export const ResponseTimeTooltip = ({ active, payload, label }: ChartTooltipProps) => (
+  <ValueTooltip
+    active={active}
+    payload={payload?.map((item) => ({ ...item, name: formatCategoryName(String(item.dataKey ?? "")) }))}
+    label={label}
+    valueFormatter={formatResponseTime}
+  />
+);
+
 const ModelSection = ({
   modelName,
   metrics,
@@ -182,6 +200,7 @@ const ModelSection = ({
                 categories={["metrics.avg_response_time_ms"]}
                 colors={["amber"]}
                 valueFormatter={formatResponseTime}
+                customTooltip={ResponseTimeTooltip}
                 connectNulls={true}
                 showLegend={false}
               />

From 88d0371a4670f57ca3e4c3824cb6846fe3fdacd7 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 16:50:55 -0700
Subject: [PATCH 05/67] fix(mcp): reuse the standard JWT auth builder for OAuth
 ownership

---
 .../mcp_server/bridge_token_flow.py           | 38 ++++++----
 .../mcp_server/test_discoverable_endpoints.py | 74 ++++++++++++++++---
 2 files changed, 88 insertions(+), 24 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 3817935bf71..2f3e50b803f 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -314,15 +314,15 @@ async def _extract_user_id_from_request(request: Request) -> str | None:
 
     token: Final = _litellm_key_from_request(request)
     if token is not None and JWTHandler.is_jwt(token):
-        return await _extract_jwt_user_id(token)
+        return await _extract_jwt_user_id(request, token)
     resolved: Final = await _resolve_active_litellm_key(request)
     if not isinstance(resolved, _ResolvedKey):
         return None
     return _active_key_user_id(resolved.key)
 
 
-async def _extract_jwt_user_id(token: str) -> str | None:
-    from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
+async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
+    from litellm.proxy._types import UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.handle_jwt import JWTAuthManager  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
         _resolve_jwt_to_virtual_key,  # pyright: ignore[reportPrivateUsage]  # reuse admission mapping policy without provisioning a new key
@@ -339,11 +339,11 @@ async def _extract_jwt_user_id(token: str) -> str | None:
     if general_settings.get("enable_jwt_auth") is not True or premium_user is not True:
         return None
     try:
-        claims: Final = await jwt_handler.auth_jwt(token=token)
-        validate: Final = jwt_handler.litellm_jwtauth.custom_validate
-        if validate is not None and not validate(claims):
-            return None
         if jwt_handler.litellm_jwtauth.is_virtual_key_mapping_configured():
+            claims: Final = await jwt_handler.auth_jwt(token=token)
+            validate: Final = jwt_handler.litellm_jwtauth.custom_validate
+            if validate is not None and not validate(claims):
+                return None
             mapped: Final = await _resolve_jwt_to_virtual_key(
                 jwt_claims=claims,
                 jwt_handler=jwt_handler,
@@ -356,16 +356,24 @@ async def _extract_jwt_user_id(token: str) -> str | None:
                 return None if await _key_owner_scim_deactivated(mapped) else _active_key_user_id(mapped)
             if mapped is not None:
                 return None
-        user_id, user_email, valid_email = await JWTAuthManager.get_user_info(jwt_handler, claims)
-        object_id: Final = jwt_handler.get_object_id(token=claims, default_value=None)
-        owner_id: Final = (
-            object_id
-            if jwt_handler.get_rbac_role(token=claims) == LitellmUserRoles.INTERNAL_USER and object_id
-            else user_id
+        identity: Final = await JWTAuthManager.auth_builder(
+            api_key=token,
+            jwt_handler=jwt_handler,
+            request_data={},
+            general_settings=general_settings,
+            route=request.url.path,
+            prisma_client=prisma_client,
+            user_api_key_cache=user_api_key_cache,
+            parent_otel_span=None,
+            proxy_logging_obj=proxy_logging_obj,
+            request_headers=dict(request.headers),
+            request_method=request.method,
         )
-        if not owner_id or valid_email is False:
+        owner_id: Final = identity["user_id"]
+        if not owner_id:
             return None
-        owner: Final = await load_active_user_by_id(owner_id, sso_user_id=owner_id, user_email=user_email)
+        # Admin JWTs can return before auth_builder loads the canonical database user.
+        owner: Final = await load_active_user_by_id(owner_id, sso_user_id=owner_id, user_email=identity["user_email"])
         return None if isinstance(owner, str) else owner.user_id
     except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
         verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index ce985064eb0..d1ab8809861 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -11421,6 +11421,7 @@ def _oauth_identity_jwt(
     audience: str = "litellm-proxy",
     issuer: str = "https://idp.example.test",
     owner: str | None = "jwt-owner",
+    scope: str = "",
 ) -> str:
     import jwt
 
@@ -11432,6 +11433,7 @@ def _oauth_identity_jwt(
             "iss": issuer,
             "aud": audience,
             "exp": int(time.time()) + expires_in,
+            "scope": scope,
         },
         signing_key,
         algorithm="RS256",
@@ -11440,9 +11442,11 @@ def _oauth_identity_jwt(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("header", ["Authorization", "x-litellm-api-key"])
+@pytest.mark.parametrize("policy_allowed", [False, True])
 async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     header: str,
+    policy_allowed: bool,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     import httpx
@@ -11451,7 +11455,8 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     from litellm.proxy._types import MCPTransport
     from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
-    _, signing_key = jwt_oauth_identity
+    handler, signing_key = jwt_oauth_identity
+    handler.litellm_jwtauth.enforce_team_based_model_access = not policy_allowed
     bearer: Final = _oauth_identity_jwt(signing_key)
     request: Final = _token_request({header: f"Bearer {bearer}"})
     server: Final = MCPServer(
@@ -11501,6 +11506,10 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
             code_verifier=None,
         )
     assert response.status_code == 200
+    assert json.loads(response.body)["access_token"] == "upstream-token"
+    if not policy_allowed:
+        table.upsert.assert_not_awaited()
+        return
     table.upsert.assert_awaited_once()
     stored: Final = table.upsert.call_args.kwargs
     assert stored["where"] == {"user_id_server_id": {"user_id": "jwt-owner", "server_id": server.server_id}}
@@ -11525,6 +11534,8 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
         "scim_inactive",
         "custom_validate",
         "missing_database",
+        "denied_route",
+        "required_team",
     ],
 )
 async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
@@ -11537,6 +11548,7 @@ async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
     from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._types import LitellmUserRoles, RoleBasedPermissions
 
     handler, signing_key = jwt_oauth_identity
     key: Final = (
@@ -11561,6 +11573,18 @@ async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
         )
     if rejection == "custom_validate":
         handler.litellm_jwtauth.custom_validate = lambda claims: False
+    if rejection == "denied_route":
+        handler.litellm_jwtauth.enforce_rbac = True
+        monkeypatch.setattr(
+            proxy_server,
+            "general_settings",
+            {
+                "enable_jwt_auth": True,
+                "role_permissions": [RoleBasedPermissions(role=LitellmUserRoles.INTERNAL_USER, routes=["/models"])],
+            },
+        )
+    if rejection == "required_team":
+        handler.litellm_jwtauth.enforce_team_based_model_access = True
     assert await _extract_user_id_from_request(_token_request({"Authorization": f"Bearer {bearer}"})) is None
 
 
@@ -11586,7 +11610,9 @@ async def test_oauth_jwt_cannot_override_explicit_litellm_key(
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("mapping", ["active", "blocked", "inactive_owner", "fallback", "pending", "reject"])
+@pytest.mark.parametrize(
+    "mapping", ["active", "blocked", "inactive_owner", "fallback", "pending", "reject", "custom_reject"]
+)
 async def test_oauth_jwt_uses_configured_virtual_key_owner(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     mapping: str,
@@ -11598,6 +11624,8 @@ async def test_oauth_jwt_uses_configured_virtual_key_owner(
 
     handler, signing_key = jwt_oauth_identity
     handler.litellm_jwtauth.virtual_key_claim_field = "sub"
+    if mapping == "custom_reject":
+        handler.litellm_jwtauth.custom_validate = lambda claims: False
     handler.litellm_jwtauth.unregistered_jwt_client_behavior = (
         UnregisteredJWTClientBehavior.AUTO_REGISTER
         if mapping == "pending"
@@ -11637,9 +11665,15 @@ async def test_oauth_jwt_respects_custom_validation_and_email_policy(
 
 
 @pytest.mark.asyncio
-async def test_oauth_jwt_uses_rbac_user_object_id(jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"]) -> None:
+@pytest.mark.parametrize("route_allowed", [False, True])
+async def test_oauth_jwt_uses_rbac_user_object_id(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    route_allowed: bool,
+) -> None:
+    from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
-    from litellm.proxy._types import LitellmUserRoles, RoleMapping
+    from litellm.proxy._types import LitellmUserRoles, RoleBasedPermissions, RoleMapping
 
     handler, signing_key = jwt_oauth_identity
     handler.litellm_jwtauth.user_id_jwt_field = "sub"
@@ -11648,26 +11682,43 @@ async def test_oauth_jwt_uses_rbac_user_object_id(jwt_oauth_identity: tuple["JWT
     handler.litellm_jwtauth.role_mappings = [
         RoleMapping(role="litellm-proxy", internal_role=LitellmUserRoles.INTERNAL_USER)
     ]
+    handler.litellm_jwtauth.enforce_rbac = True
+    monkeypatch.setattr(
+        proxy_server,
+        "general_settings",
+        {
+            "enable_jwt_auth": True,
+            "role_permissions": [
+                RoleBasedPermissions(
+                    role=LitellmUserRoles.INTERNAL_USER,
+                    routes=["/token"] if route_allowed else ["/models"],
+                )
+            ],
+        },
+    )
     request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
-    assert await _extract_user_id_from_request(request) == "jwt-owner"
+    assert await _extract_user_id_from_request(request) == ("jwt-owner" if route_allowed else None)
 
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("identity", ["sso", "email"])
 @pytest.mark.parametrize("inactive", [False, True])
+@pytest.mark.parametrize("admin", [False, True])
 async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     monkeypatch: pytest.MonkeyPatch,
     identity: str,
     inactive: bool,
+    admin: bool,
 ) -> None:
     from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
 
     handler, signing_key = jwt_oauth_identity
-    external_id: Final = f"external-{identity}-{inactive}"
+    external_id: Final = f"external-{identity}-{inactive}-{admin}"
     handler.litellm_jwtauth.user_email_jwt_field = "email"
+    handler.litellm_jwtauth.admin_allowed_routes = ["/token"]
     owner: Final = LiteLLM_UserTable(
         user_id="canonical-oauth-owner",
         user_email="owner@example.test",
@@ -11676,12 +11727,17 @@ async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
     )
     database: Final = MagicMock()
     table: Final = database.db.litellm_usertable
-    table.find_unique = AsyncMock(side_effect=[None, owner if identity == "sso" else None])
+    table.find_unique = AsyncMock(side_effect=[None, owner if identity == "sso" else None, owner])
     table.find_first = AsyncMock(return_value=owner)
     table.update = AsyncMock(return_value=owner)
     monkeypatch.setattr(proxy_server, "prisma_client", database)
-    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key, owner=external_id)}"})
+    bearer: Final = _oauth_identity_jwt(
+        signing_key, owner=external_id, scope="litellm_proxy_admin" if admin else ""
+    )
+    request: Final = _token_request({"Authorization": f"Bearer {bearer}"})
     assert await _extract_user_id_from_request(request) == (None if inactive else "canonical-oauth-owner")
-    assert table.find_unique.await_count == 2
+    assert table.find_unique.await_count == (2 if admin else 3)
+    if not admin:
+        assert table.find_unique.call_args.kwargs["where"] == {"user_id": "canonical-oauth-owner"}
     if identity == "email":
         table.find_first.assert_awaited_once()

From 53318796fd27d7e59bb86850f163836dda7a45e8 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 17:13:10 -0700
Subject: [PATCH 06/67] fix(mcp): separate JWT identity lookup from request
 authorization

---
 .../mcp_server/bridge_token_flow.py           |  22 +--
 litellm/proxy/auth/handle_jwt.py              |  71 ++++++++--
 .../mcp_server/test_discoverable_endpoints.py | 126 +++++++++++++-----
 .../proxy/auth/test_handle_jwt.py             |  71 +++++++++-
 4 files changed, 237 insertions(+), 53 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 2f3e50b803f..6d11a4d2607 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -198,9 +198,7 @@ async def _reload_active_user_by_id(user_id: str) -> "_KeyResolutionFailure | No
     return loaded if isinstance(loaded, str) else None
 
 
-async def load_active_user_by_id(
-    user_id: str, *, sso_user_id: str | None = None, user_email: str | None = None
-) -> "LiteLLM_UserTable | _KeyResolutionFailure":
+async def load_active_user_by_id(user_id: str) -> "LiteLLM_UserTable | _KeyResolutionFailure":
     """Load a live litellm user by id, returning the record when the user is active or a precise
     failure otherwise. The interactive DCR client authenticates via SSO, so its refresh envelope seals a
     user subject; renewing it must re-check the user is still live (present and not SCIM-deactivated) so a
@@ -234,8 +232,6 @@ async def load_active_user_by_id(
             prisma_client=prisma_client,
             user_api_key_cache=user_api_key_cache,
             user_id_upsert=False,
-            sso_user_id=sso_user_id,
-            user_email=user_email,
         )
     except (ProxyException, HTTPException):
         return "no_active_key"
@@ -247,6 +243,10 @@ async def load_active_user_by_id(
         return "no_active_key"
     if user_object is None:
         return "no_active_key"
+    return _active_user_record(user_object)
+
+
+def _active_user_record(user_object: "LiteLLM_UserTable") -> "LiteLLM_UserTable | Literal['no_active_key']":
     if isinstance(user_object.metadata, dict) and user_object.metadata.get("scim_active") is False:
         return "no_active_key"
     return user_object
@@ -336,7 +336,7 @@ async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
         user_api_key_cache,
     )
 
-    if general_settings.get("enable_jwt_auth") is not True or premium_user is not True:
+    if general_settings.get("enable_jwt_auth") is not True or premium_user is not True or prisma_client is None:
         return None
     try:
         if jwt_handler.litellm_jwtauth.is_virtual_key_mapping_configured():
@@ -368,13 +368,13 @@ async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
             proxy_logging_obj=proxy_logging_obj,
             request_headers=dict(request.headers),
             request_method=request.method,
+            identity_only=True,
         )
-        owner_id: Final = identity["user_id"]
-        if not owner_id:
+        resolved_user: Final = identity["user_object"]
+        if resolved_user is None:
             return None
-        # Admin JWTs can return before auth_builder loads the canonical database user.
-        owner: Final = await load_active_user_by_id(owner_id, sso_user_id=owner_id, user_email=identity["user_email"])
-        return None if isinstance(owner, str) else owner.user_id
+        owner: Final = _active_user_record(resolved_user)
+        return None if isinstance(owner, str) else identity["user_id"]
     except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
         verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
         return None
diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py
index 4304542fc83..678769b375b 100644
--- a/litellm/proxy/auth/handle_jwt.py
+++ b/litellm/proxy/auth/handle_jwt.py
@@ -1674,6 +1674,7 @@ class JWTAuthManager:
         proxy_logging_obj: ProxyLogging,
         route: str,
         org_alias: str | None = None,
+        user_id_upsert: bool | None = None,
     ) -> tuple[
         LiteLLM_UserTable | None,
         LiteLLM_OrganizationTable | None,
@@ -1737,7 +1738,11 @@ class JWTAuthManager:
                 user_id=user_id,
                 user_email=user_email,
                 sso_user_id=user_id,
-                upsert=jwt_handler.is_upsert_user_id(valid_user_email=valid_user_email),
+                upsert=(
+                    jwt_handler.is_upsert_user_id(valid_user_email=valid_user_email)
+                    if user_id_upsert is None
+                    else user_id_upsert
+                ),
             ),
             team_id=team_id,
         )
@@ -2209,8 +2214,14 @@ class JWTAuthManager:
         proxy_logging_obj: ProxyLogging,
         request_headers: dict | None = None,
         request_method: str | None = None,
+        identity_only: bool = False,
     ) -> JWTAuthBuilderResult:
-        """Main authentication and authorization builder"""
+        """Build JWT authentication and authorization context.
+
+        Public OAuth endpoints use identity_only to resolve an existing credential owner
+        without authorizing the OAuth route or provisioning users/teams. The returned
+        identity does not grant permission to execute an MCP or model request.
+        """
         # Check if OIDC UserInfo endpoint is enabled, but fall back to standard
         # JWT auth if the token itself is a well-formed JWT (3-part structure).
         if jwt_handler.litellm_jwtauth.oidc_userinfo_enabled and not jwt_handler.is_jwt(token=api_key):
@@ -2231,18 +2242,23 @@ class JWTAuthManager:
 
         # Check RBAC
         rbac_role: Final = jwt_handler.get_rbac_role(token=jwt_valid_token)
-        await JWTAuthManager.check_rbac_role(
-            jwt_handler,
-            jwt_valid_token,
-            general_settings,
-            request_data,
-            route,
-            rbac_role,
-        )
+        if not identity_only:
+            await JWTAuthManager.check_rbac_role(
+                jwt_handler,
+                jwt_valid_token,
+                general_settings,
+                request_data,
+                route,
+                rbac_role,
+            )
 
         # Check Scope Based Access
         scopes: Final = jwt_handler.get_scopes(token=jwt_valid_token)
-        if jwt_handler.litellm_jwtauth.enforce_scope_based_access and jwt_handler.litellm_jwtauth.scope_mappings:
+        if (
+            not identity_only
+            and jwt_handler.litellm_jwtauth.enforce_scope_based_access
+            and jwt_handler.litellm_jwtauth.scope_mappings
+        ):
             JWTAuthManager.check_scope_based_access(
                 scope_mappings=jwt_handler.litellm_jwtauth.scope_mappings,
                 scopes=scopes,
@@ -2268,6 +2284,39 @@ class JWTAuthManager:
             elif rbac_role == LitellmUserRoles.INTERNAL_USER:
                 user_id = object_id
 
+        if identity_only:
+            identity_user, _, _, _, identity_user_id = await JWTAuthManager.get_objects(
+                user_id=user_id,
+                user_email=user_email,
+                org_id=None,
+                end_user_id=None,
+                team_id=None,
+                valid_user_email=valid_user_email,
+                jwt_handler=jwt_handler,
+                prisma_client=prisma_client,
+                user_api_key_cache=user_api_key_cache,
+                parent_otel_span=parent_otel_span,
+                proxy_logging_obj=proxy_logging_obj,
+                route=route,
+                user_id_upsert=False,
+            )
+            return JWTAuthBuilderResult(
+                is_proxy_admin=False,
+                # Admin admission uses the claim ID; other callers use the canonical DB ID.
+                user_id=user_id if jwt_handler.is_admin(scopes=scopes) else identity_user_id,
+                user_email=identity_user.user_email if identity_user is not None else user_email,
+                user_object=identity_user,
+                team_id=None,
+                team_object=None,
+                org_id=None,
+                org_object=None,
+                end_user_id=None,
+                end_user_object=None,
+                team_membership=None,
+                token=api_key,
+                jwt_claims=jwt_valid_token,
+            )
+
         # Check admin access
         admin_result: Final = await JWTAuthManager.check_admin_access(
             jwt_handler, scopes, route, user_id, org_id, api_key, jwt_valid_token, user_email=user_email
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index d1ab8809861..bf557667892 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -7127,12 +7127,12 @@ async def test_build_oauth_protected_resource_response_obo_end_to_end():
         global_mcp_server_manager.registry.clear()
 
 
-def _token_request(headers):
+def _token_request(headers, path="/token"):
     """A real Starlette request with case-insensitive headers (matches production)."""
     from starlette.requests import Request
 
     raw = [(k.lower().encode(), v.encode()) for k, v in headers.items()]
-    return Request({"type": "http", "method": "POST", "path": "/token", "headers": raw, "query_string": b""})
+    return Request({"type": "http", "method": "POST", "path": path, "headers": raw, "query_string": b""})
 
 
 @pytest.fixture
@@ -11443,10 +11443,12 @@ def _oauth_identity_jwt(
 @pytest.mark.asyncio
 @pytest.mark.parametrize("header", ["Authorization", "x-litellm-api-key"])
 @pytest.mark.parametrize("policy_allowed", [False, True])
+@pytest.mark.parametrize("admin", [False, True])
 async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     header: str,
     policy_allowed: bool,
+    admin: bool,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     import httpx
@@ -11456,9 +11458,9 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
     handler, signing_key = jwt_oauth_identity
-    handler.litellm_jwtauth.enforce_team_based_model_access = not policy_allowed
-    bearer: Final = _oauth_identity_jwt(signing_key)
-    request: Final = _token_request({header: f"Bearer {bearer}"})
+    handler.litellm_jwtauth.custom_validate = lambda claims: policy_allowed
+    bearer: Final = _oauth_identity_jwt(signing_key, scope="litellm_proxy_admin" if admin else "")
+    request: Final = _token_request({header: f"Bearer {bearer}"}, path="/jwt-oauth-server/token")
     server: Final = MCPServer(
         server_id="jwt-oauth-server",
         name="jwt-oauth-server",
@@ -11534,8 +11536,6 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
         "scim_inactive",
         "custom_validate",
         "missing_database",
-        "denied_route",
-        "required_team",
     ],
 )
 async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
@@ -11548,7 +11548,6 @@ async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
     from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
-    from litellm.proxy._types import LitellmUserRoles, RoleBasedPermissions
 
     handler, signing_key = jwt_oauth_identity
     key: Final = (
@@ -11573,18 +11572,6 @@ async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
         )
     if rejection == "custom_validate":
         handler.litellm_jwtauth.custom_validate = lambda claims: False
-    if rejection == "denied_route":
-        handler.litellm_jwtauth.enforce_rbac = True
-        monkeypatch.setattr(
-            proxy_server,
-            "general_settings",
-            {
-                "enable_jwt_auth": True,
-                "role_permissions": [RoleBasedPermissions(role=LitellmUserRoles.INTERNAL_USER, routes=["/models"])],
-            },
-        )
-    if rejection == "required_team":
-        handler.litellm_jwtauth.enforce_team_based_model_access = True
     assert await _extract_user_id_from_request(_token_request({"Authorization": f"Bearer {bearer}"})) is None
 
 
@@ -11666,7 +11653,7 @@ async def test_oauth_jwt_respects_custom_validation_and_email_policy(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("route_allowed", [False, True])
-async def test_oauth_jwt_uses_rbac_user_object_id(
+async def test_oauth_jwt_identity_preserves_separate_mcp_route_authorization(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     monkeypatch: pytest.MonkeyPatch,
     route_allowed: bool,
@@ -11674,6 +11661,7 @@ async def test_oauth_jwt_uses_rbac_user_object_id(
     from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
     from litellm.proxy._types import LitellmUserRoles, RoleBasedPermissions, RoleMapping
+    from litellm.proxy.auth.handle_jwt import JWTAuthManager
 
     handler, signing_key = jwt_oauth_identity
     handler.litellm_jwtauth.user_id_jwt_field = "sub"
@@ -11691,13 +11679,32 @@ async def test_oauth_jwt_uses_rbac_user_object_id(
             "role_permissions": [
                 RoleBasedPermissions(
                     role=LitellmUserRoles.INTERNAL_USER,
-                    routes=["/token"] if route_allowed else ["/models"],
+                    routes=["mcp_routes"] if route_allowed else ["/models"],
                 )
             ],
         },
     )
-    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
-    assert await _extract_user_id_from_request(request) == ("jwt-owner" if route_allowed else None)
+    bearer: Final = _oauth_identity_jwt(signing_key)
+    request: Final = _token_request({"Authorization": f"Bearer {bearer}"}, path="/example/token")
+    assert await _extract_user_id_from_request(request) == "jwt-owner"
+    admission: Final = JWTAuthManager.auth_builder(
+        api_key=bearer,
+        jwt_handler=handler,
+        request_data={},
+        general_settings=proxy_server.general_settings,
+        route="/mcp/example",
+        prisma_client=proxy_server.prisma_client,
+        user_api_key_cache=handler.user_api_key_cache,
+        parent_otel_span=None,
+        proxy_logging_obj=proxy_server.proxy_logging_obj,
+        request_method="POST",
+    )
+    if route_allowed:
+        assert (await admission)["user_id"] == "jwt-owner"
+    else:
+        with pytest.raises(HTTPException) as denial:
+            await admission
+        assert denial.value.status_code == 403
 
 
 @pytest.mark.asyncio
@@ -11714,11 +11721,12 @@ async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
     from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy.auth.handle_jwt import JWTAuthManager
 
     handler, signing_key = jwt_oauth_identity
     external_id: Final = f"external-{identity}-{inactive}-{admin}"
     handler.litellm_jwtauth.user_email_jwt_field = "email"
-    handler.litellm_jwtauth.admin_allowed_routes = ["/token"]
+    handler.litellm_jwtauth.admin_allowed_routes = ["mcp_routes"]
     owner: Final = LiteLLM_UserTable(
         user_id="canonical-oauth-owner",
         user_email="owner@example.test",
@@ -11727,7 +11735,7 @@ async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
     )
     database: Final = MagicMock()
     table: Final = database.db.litellm_usertable
-    table.find_unique = AsyncMock(side_effect=[None, owner if identity == "sso" else None, owner])
+    table.find_unique = AsyncMock(side_effect=[None, owner if identity == "sso" else None])
     table.find_first = AsyncMock(return_value=owner)
     table.update = AsyncMock(return_value=owner)
     monkeypatch.setattr(proxy_server, "prisma_client", database)
@@ -11735,9 +11743,67 @@ async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
         signing_key, owner=external_id, scope="litellm_proxy_admin" if admin else ""
     )
     request: Final = _token_request({"Authorization": f"Bearer {bearer}"})
-    assert await _extract_user_id_from_request(request) == (None if inactive else "canonical-oauth-owner")
-    assert table.find_unique.await_count == (2 if admin else 3)
-    if not admin:
-        assert table.find_unique.call_args.kwargs["where"] == {"user_id": "canonical-oauth-owner"}
+    stored_owner: Final = await _extract_user_id_from_request(request)
+    assert stored_owner == (None if inactive else external_id if admin else "canonical-oauth-owner")
+    assert table.find_unique.await_count == 2
     if identity == "email":
         table.find_first.assert_awaited_once()
+    if not inactive:
+        admission: Final = await JWTAuthManager.auth_builder(
+            api_key=bearer,
+            jwt_handler=handler,
+            request_data={},
+            general_settings=proxy_server.general_settings,
+            route="/mcp/example",
+            prisma_client=database,
+            user_api_key_cache=handler.user_api_key_cache,
+            parent_otel_span=None,
+            proxy_logging_obj=proxy_server.proxy_logging_obj,
+        )
+        assert stored_owner == admission["user_id"]
+
+
+@pytest.mark.asyncio
+async def test_oauth_jwt_identity_does_not_provision_or_synchronize_teams(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+) -> None:
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+
+    handler, signing_key = jwt_oauth_identity
+    handler.litellm_jwtauth.enforce_team_based_model_access = True
+    handler.litellm_jwtauth.team_id_default = "new-team"
+    handler.litellm_jwtauth.team_id_upsert = True
+    handler.litellm_jwtauth.sync_user_role_and_teams = True
+    owner: Final = LiteLLM_UserTable(user_id="jwt-owner", teams=["existing-team"])
+    handler.user_api_key_cache.set_cache("jwt-owner", owner)
+    request: Final = _token_request(
+        {"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"}, path="/example/token"
+    )
+    assert await _extract_user_id_from_request(request) == "jwt-owner"
+    assert owner.teams == ["existing-team"]
+    proxy_server.prisma_client.db.litellm_teamtable.find_unique.assert_not_called()
+    proxy_server.prisma_client.db.litellm_teamtable.upsert.assert_not_called()
+    proxy_server.prisma_client.db.litellm_usertable.update.assert_not_called()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("state", ["active", "inactive", "missing_database"])
+async def test_oauth_refresh_revalidates_the_same_active_user_rule(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    state: str,
+) -> None:
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _reload_active_user_by_id
+
+    handler, _ = jwt_oauth_identity
+    handler.user_api_key_cache.set_cache(
+        "jwt-owner", LiteLLM_UserTable(user_id="jwt-owner", metadata={"scim_active": state != "inactive"})
+    )
+    if state == "missing_database":
+        monkeypatch.setattr(proxy_server, "prisma_client", None)
+    expected: Final = None if state == "active" else "no_active_key" if state == "inactive" else "unresolvable"
+    assert await _reload_active_user_by_id("jwt-owner") == expected
diff --git a/tests/test_litellm/proxy/auth/test_handle_jwt.py b/tests/test_litellm/proxy/auth/test_handle_jwt.py
index 94226b5404d..9e15a442a18 100644
--- a/tests/test_litellm/proxy/auth/test_handle_jwt.py
+++ b/tests/test_litellm/proxy/auth/test_handle_jwt.py
@@ -2,7 +2,7 @@ import asyncio
 import re
 import time
 from collections.abc import Mapping, Sequence
-from typing import Optional
+from typing import Final, Optional
 from unittest.mock import AsyncMock, MagicMock, patch
 
 from fastapi import HTTPException
@@ -6786,3 +6786,72 @@ async def test_sync_user_role_and_teams_singular_claim_only_recognized_under_fla
     }
     assert mock_patch.call_args.kwargs["teams_ids_to_add_user_to"] == []
     assert user.teams == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("identity_only", [False, True])
+@pytest.mark.parametrize("existing_user", [False, True])
+@pytest.mark.parametrize("model_allowed", [False, True])
+async def test_auth_builder_identity_lookup_does_not_provision_users(
+    monkeypatch: pytest.MonkeyPatch, identity_only: bool, existing_user: bool, model_allowed: bool
+) -> None:
+    from litellm.proxy._types import ScopeMapping
+    from litellm.proxy.auth.auth_checks import UserNotFoundError
+    from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
+
+    private_key, jwk = _get_rsa_key_and_jwk("identity-mode")
+    cache: Final = UserApiKeyCache()
+    cache.set_cache("litellm_jwt_auth_keys_https://identity.example/jwks", [jwk])
+    user_id: Final = f"identity-mode-{identity_only}-{existing_user}-{model_allowed}"
+    user: Final = LiteLLM_UserTable(user_id=user_id, organization_memberships=[])
+    if existing_user:
+        cache.set_cache(user_id, user)
+    database: Final = MagicMock()
+    users: Final = database.db.litellm_usertable
+    users.find_unique = AsyncMock(return_value=None)
+    users.find_first = AsyncMock(return_value=None)
+    users.create = AsyncMock(return_value=user)
+    handler: Final = JWTHandler()
+    handler.update_environment(
+        prisma_client=database,
+        user_api_key_cache=cache,
+        litellm_jwtauth=LiteLLM_JWTAuth(
+            user_id_jwt_field="sub",
+            user_id_upsert=True,
+            enforce_scope_based_access=True,
+            scope_mappings=[ScopeMapping(scope="allowed", models=["allowed-model"])],
+        ),
+    )
+    monkeypatch.setenv("JWT_PUBLIC_KEY_URL", "https://identity.example/jwks")
+    monkeypatch.setenv("JWT_ISSUER", "https://identity.example")
+    monkeypatch.setenv("JWT_AUDIENCE", "gateway")
+    token: Final = _encode_rsa_jwt(
+        private_key, "https://identity.example", "gateway", "identity-mode", {"sub": user_id, "scope": "allowed"}
+    )
+    pending: Final = JWTAuthManager.auth_builder(
+        api_key=token,
+        jwt_handler=handler,
+        request_data={"model": "allowed-model" if model_allowed else "forbidden-model"},
+        general_settings={},
+        route="/example/token" if identity_only else "/mcp/example",
+        prisma_client=database,
+        user_api_key_cache=cache,
+        parent_otel_span=None,
+        proxy_logging_obj=MagicMock(),
+        identity_only=identity_only,
+    )
+    if not identity_only and not model_allowed:
+        with pytest.raises(HTTPException) as denial:
+            await pending
+        assert denial.value.status_code == 403
+        users.create.assert_not_awaited()
+        return
+    if identity_only and not existing_user:
+        with pytest.raises(UserNotFoundError):
+            await pending
+    else:
+        result: Final = await pending
+        assert result["user_id"] == user_id
+        assert result["user_object"] is not None
+        assert result["user_object"].user_id == user_id
+    assert users.create.await_count == (0 if identity_only or existing_user else 1)

From 4657d43fb999972bc9c77f65a4ee5a40bb68b44c Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 00:27:09 +0000
Subject: [PATCH 07/67] fix(anthropic): tolerate message_delta chunks without
 usage in streams

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/llms/anthropic/chat/handler.py            |  4 +++-
 litellm/types/llms/anthropic.py                   |  2 +-
 .../anthropic/chat/test_anthropic_chat_handler.py | 15 +++++++++++++++
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/litellm/llms/anthropic/chat/handler.py b/litellm/llms/anthropic/chat/handler.py
index 5d3ae444b42..4dd0deeb62b 100644
--- a/litellm/llms/anthropic/chat/handler.py
+++ b/litellm/llms/anthropic/chat/handler.py
@@ -1167,7 +1167,9 @@ class ModelResponseIterator:
         # (matches OpenAI behavior and non-streaming Anthropic implementation)
         if self.converted_response_format_tool:
             finish_reason = "stop"
-        usage: Final = self._handle_usage(anthropic_usage_chunk=message_delta["usage"])
+        usage: Final = (
+            self._handle_usage(anthropic_usage_chunk=message_delta["usage"]) if "usage" in message_delta else None
+        )
         container: Final = message_delta["delta"].get("container")
         return finish_reason, usage, container
 
diff --git a/litellm/types/llms/anthropic.py b/litellm/types/llms/anthropic.py
index d56ada07ed5..ecb8dbb2502 100644
--- a/litellm/types/llms/anthropic.py
+++ b/litellm/types/llms/anthropic.py
@@ -586,7 +586,7 @@ class MessageBlockDelta(TypedDict):
 
     type: Literal["message_delta"]
     delta: MessageDelta
-    usage: UsageDelta
+    usage: NotRequired[UsageDelta]
     context_management: NotRequired[ContextManagementResponse]
 
 
diff --git a/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py b/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
index 83201aef143..ac05cdcf251 100644
--- a/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
+++ b/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
@@ -579,6 +579,21 @@ def test_text_only_streaming_has_index_zero():
             ), f"Expected index=0, got {parsed.choices[0].index}"
 
 
+def test_message_delta_without_usage_returns_chunk_with_no_usage():
+    """A message_delta event may carry no usage field; it must not raise."""
+    iterator = ModelResponseIterator(None, sync_stream=True)
+
+    model_response = iterator.chunk_parser(
+        {
+            "type": "message_delta",
+            "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+        }
+    )
+
+    assert model_response.choices[0].finish_reason == "stop"
+    assert model_response.usage is None
+
+
 def test_streaming_thinking_deltas_count_reasoning_tokens_in_usage():
     """Anthropic streaming usage should account for emitted thinking deltas."""
     chunks = [

From 61e3b5ddae1fdbbf12f6fa087b8bf0ee3e318d12 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 17:31:07 -0700
Subject: [PATCH 08/67] fix(mcp): persist OAuth credentials for rowless JWT
 admins

---
 .../mcp_server/bridge_token_flow.py           |  5 ++-
 litellm/proxy/auth/handle_jwt.py              | 36 +++++++++++--------
 .../mcp_server/test_discoverable_endpoints.py | 18 +++++++++-
 3 files changed, 40 insertions(+), 19 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 6d11a4d2607..b693cc046c8 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -371,10 +371,9 @@ async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
             identity_only=True,
         )
         resolved_user: Final = identity["user_object"]
-        if resolved_user is None:
+        if resolved_user is not None and isinstance(_active_user_record(resolved_user), str):
             return None
-        owner: Final = _active_user_record(resolved_user)
-        return None if isinstance(owner, str) else identity["user_id"]
+        return identity["user_id"]
     except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
         verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
         return None
diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py
index d5fcc578167..2d8cfb614ce 100644
--- a/litellm/proxy/auth/handle_jwt.py
+++ b/litellm/proxy/auth/handle_jwt.py
@@ -62,6 +62,7 @@ from litellm.proxy.common_utils.user_api_key_cache import (
 from litellm.proxy.utils import PrismaClient, ProxyLogging
 from litellm.repositories.user_repository import UserRepository
 from litellm.types.agents import AgentResponse
+from litellm.types.proxy.auth.auth_checks import UserNotFoundError
 
 from .auth_checks import (
     _allowed_routes_check,
@@ -2343,21 +2344,26 @@ class JWTAuthManager:
         )
 
         if identity_only:
-            identity_user, _, _, _, identity_user_id = await JWTAuthManager.get_objects(
-                user_id=user_id,
-                user_email=user_email,
-                org_id=None,
-                end_user_id=None,
-                team_id=None,
-                valid_user_email=valid_user_email,
-                jwt_handler=jwt_handler,
-                prisma_client=prisma_client,
-                user_api_key_cache=user_api_key_cache,
-                parent_otel_span=parent_otel_span,
-                proxy_logging_obj=proxy_logging_obj,
-                route=route,
-                user_id_upsert=False,
-            )
+            try:
+                identity_user, _, _, _, identity_user_id = await JWTAuthManager.get_objects(
+                    user_id=user_id,
+                    user_email=user_email,
+                    org_id=None,
+                    end_user_id=None,
+                    team_id=None,
+                    valid_user_email=valid_user_email,
+                    jwt_handler=jwt_handler,
+                    prisma_client=prisma_client,
+                    user_api_key_cache=user_api_key_cache,
+                    parent_otel_span=parent_otel_span,
+                    proxy_logging_obj=proxy_logging_obj,
+                    route=route,
+                    user_id_upsert=False,
+                )
+            except UserNotFoundError:
+                if not jwt_handler.is_admin(scopes=scopes):
+                    raise
+                identity_user, identity_user_id = None, user_id
             return JWTAuthBuilderResult(
                 is_proxy_admin=False,
                 # Admin admission uses the claim ID; other callers use the canonical DB ID.
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index bf557667892..f6dc7932e2f 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -11444,11 +11444,13 @@ def _oauth_identity_jwt(
 @pytest.mark.parametrize("header", ["Authorization", "x-litellm-api-key"])
 @pytest.mark.parametrize("policy_allowed", [False, True])
 @pytest.mark.parametrize("admin", [False, True])
+@pytest.mark.parametrize("owner_state", ["active", "missing", "inactive", "database_error"])
 async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     header: str,
     policy_allowed: bool,
     admin: bool,
+    owner_state: str,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     import httpx
@@ -11475,6 +11477,7 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     from litellm.caching.llm_caching_handler import LLMClientCache
     from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
     from litellm.proxy import proxy_server
+    from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy.common_utils.encrypt_decrypt_utils import decrypt_value_helper
     from litellm.types.llms.custom_http import httpxSpecialProvider
 
@@ -11485,6 +11488,18 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
         return httpx.Response(200, json={"access_token": "upstream-token", "token_type": "Bearer"})
 
     database: Final = MagicMock()
+    users: Final = database.db.litellm_usertable
+    users.find_unique = AsyncMock(return_value=None)
+    users.find_first = AsyncMock(return_value=None)
+    users.create = AsyncMock()
+    if owner_state in ("missing", "database_error"):
+        handler.user_api_key_cache.delete_cache("jwt-owner")
+    if owner_state == "database_error":
+        users.find_unique.side_effect = RuntimeError("database unavailable")
+    if owner_state == "inactive":
+        handler.user_api_key_cache.set_cache(
+            "jwt-owner", LiteLLM_UserTable(user_id="jwt-owner", metadata={"scim_active": False})
+        )
     table: Final = database.db.litellm_mcpusercredentials
     table.find_unique = AsyncMock(return_value=None)
     table.upsert = AsyncMock()
@@ -11509,7 +11524,8 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
         )
     assert response.status_code == 200
     assert json.loads(response.body)["access_token"] == "upstream-token"
-    if not policy_allowed:
+    users.create.assert_not_awaited()
+    if not policy_allowed or owner_state in ("inactive", "database_error") or (owner_state == "missing" and not admin):
         table.upsert.assert_not_awaited()
         return
     table.upsert.assert_awaited_once()

From f5c1c82f8175e42491c364dca3208eb5151b815b Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 00:32:24 +0000
Subject: [PATCH 09/67] fix(responses): estimate usage from text when streamed
 completed event omits usage

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 15 +++
 litellm/responses/utils.py                    | 16 ++++
 .../responses/test_streaming_iterator.py      | 96 ++++++++++++++++++-
 3 files changed, 124 insertions(+), 3 deletions(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 38874768ca8..52b50167190 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -420,6 +420,21 @@ class BaseResponsesAPIStreamingIterator:
                     openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED,
                 ):
                     self.completed_response = openai_responses_api_chunk
+                    _response_obj: Final[ResponsesAPIResponse | None] = getattr(
+                        openai_responses_api_chunk, "response", None
+                    )
+                    if (
+                        _chunk_type
+                        in (
+                            openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
+                            openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
+                        )
+                        and _response_obj is not None
+                        and _response_obj.usage is None
+                    ):
+                        _response_obj.usage = ResponseAPILoggingUtils.estimate_usage_from_text(
+                            self.model or "", self.request_data.get("input"), self._generated_content
+                        )
                     _stamp_responses_usage_cost(getattr(openai_responses_api_chunk, "response", None), self.logging_obj)
 
                     if _chunk_type == openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED:
diff --git a/litellm/responses/utils.py b/litellm/responses/utils.py
index 41a3ded7022..e523b3771af 100644
--- a/litellm/responses/utils.py
+++ b/litellm/responses/utils.py
@@ -1,4 +1,5 @@
 import base64
+import json
 import re
 from collections.abc import Iterable, Mapping, Sequence
 from typing import Any, Final, Optional, TypeVar, Union, cast, get_type_hints, overload
@@ -1239,3 +1240,18 @@ class ResponseAPILoggingUtils:
             setattr(chat_usage, "cost", response_api_usage.cost)
 
         return chat_usage
+
+    @staticmethod
+    def estimate_usage_from_text(model: str, request_input: object, generated_text: str) -> ResponseAPIUsage:
+        input_text: Final = request_input if isinstance(request_input, str) else json.dumps(request_input, default=str)
+        input_tokens: Final = litellm.token_counter(  # pyright: ignore[reportUnknownMemberType]  # token_counter's public signature is untyped
+            model=model, text=input_text
+        )
+        output_tokens: Final = litellm.token_counter(  # pyright: ignore[reportUnknownMemberType]  # token_counter's public signature is untyped
+            model=model, text=generated_text, count_response_tokens=True
+        )
+        return ResponseAPIUsage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=input_tokens + output_tokens,
+        )
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index 5e0e794d93e..c593946ac4a 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -31,8 +31,15 @@ def _sse_event(payload: dict) -> bytes:
 
 def _mock_config() -> Mock:
     mock_config = Mock(spec=BaseResponsesAPIConfig)
-    mock_responses_api_response = Mock(spec=ResponsesAPIResponse)
-    mock_responses_api_response.id = "resp_ttft"
+    mock_responses_api_response = ResponsesAPIResponse(
+        id="resp_ttft",
+        created_at=0,
+        status="completed",
+        model="gpt-4o-mini",
+        object="response",
+        output=[],
+        usage=ResponseAPIUsage(input_tokens=1, output_tokens=1, total_tokens=2),
+    )
 
     def _transform(model, parsed_chunk, logging_obj):
         evt_type = parsed_chunk.get("type")
@@ -54,6 +61,8 @@ def _make_iterator(
     sse_events: list[bytes],
     logging_obj: LiteLLMLoggingObj,
     trailing_error: Optional[Exception] = None,
+    config: Mock | None = None,
+    request_data: dict | None = None,
 ) -> ResponsesAPIStreamingIterator:
     async def aiter_bytes():
         for evt in sse_events:
@@ -68,10 +77,11 @@ def _make_iterator(
     return ResponsesAPIStreamingIterator(
         response=mock_response,
         model="gpt-4o-mini",
-        responses_api_provider_config=_mock_config(),
+        responses_api_provider_config=config or _mock_config(),
         logging_obj=logging_obj,
         litellm_metadata={},
         custom_llm_provider="openai",
+        request_data=request_data,
     )
 
 
@@ -329,6 +339,86 @@ def test_run_post_success_hooks_does_not_report_generation_time_as_overhead():
     assert "litellm_overhead_time_ms" not in iterator.completed_response._hidden_params
 
 
+def _mock_config_with_completed_response(response: ResponsesAPIResponse) -> Mock:
+    mock_config = Mock(spec=BaseResponsesAPIConfig)
+
+    def _transform(model, parsed_chunk, logging_obj):
+        evt_type = parsed_chunk.get("type")
+        if evt_type == "response.completed":
+            completed = Mock(spec=ResponseCompletedEvent)
+            completed.type = ResponsesAPIStreamEvents.RESPONSE_COMPLETED
+            completed.response = response
+            return completed
+        stub = Mock()
+        stub.type = evt_type
+        if evt_type == "response.output_text.delta":
+            stub.delta = parsed_chunk.get("delta")
+        return stub
+
+    mock_config.transform_streaming_response.side_effect = _transform
+    return mock_config
+
+
+def _responses_api_response_without_usage() -> ResponsesAPIResponse:
+    return ResponsesAPIResponse(
+        id="resp_no_usage",
+        created_at=int(datetime(2025, 1, 1).timestamp()),
+        status="completed",
+        model="gpt-4o-mini",
+        object="response",
+        output=[],
+        usage=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_completed_event_without_usage_gets_text_estimate():
+    """A response.completed event carrying usage: null still bills: the
+    iterator estimates usage from the request input and generated text."""
+    response = _responses_api_response_without_usage()
+    iterator = _make_iterator(
+        sse_events=[
+            _sse_event({"type": "response.output_text.delta", "delta": "hello world"}),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=_mock_config_with_completed_response(response),
+        request_data={"input": "count these input tokens please"},
+    )
+
+    async for _ in iterator:
+        pass
+
+    usage = iterator.completed_response.response.usage
+    assert usage is not None
+    assert usage.input_tokens > 0
+    assert usage.output_tokens > 0
+    assert usage.total_tokens == usage.input_tokens + usage.output_tokens
+
+
+@pytest.mark.asyncio
+async def test_completed_event_with_usage_is_left_untouched():
+    """Provider-reported usage on response.completed wins over the estimate."""
+    response = _responses_api_response_with_usage()
+    iterator = _make_iterator(
+        sse_events=[
+            _sse_event({"type": "response.output_text.delta", "delta": "hello world"}),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=_mock_config_with_completed_response(response),
+        request_data={"input": "count these input tokens please"},
+    )
+
+    async for _ in iterator:
+        pass
+
+    usage = iterator.completed_response.response.usage
+    assert usage.input_tokens == 20
+    assert usage.output_tokens == 60
+    assert usage.total_tokens == 80
+
+
 def _responses_api_response_with_usage() -> ResponsesAPIResponse:
     return ResponsesAPIResponse(
         id="resp_lit6427",

From d5a36eb2cabfbcd0530b4a43576c9ac7d6c530a7 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 00:36:07 +0000
Subject: [PATCH 10/67] fix(gemini): propagate provider modelVersion onto model
 responses

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../vertex_and_google_ai_studio_gemini.py     | 10 ++-
 ...test_vertex_and_google_ai_studio_gemini.py | 62 +++++++++++++++++++
 2 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py
index d113b2b4f6b..eb03b17435c 100644
--- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py
+++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py
@@ -2434,7 +2434,8 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig):
             completion_response = GenerateContentResponseBody(**completion_response)
 
         ## GET MODEL ##
-        model_response.model = model
+        model_version: Final = completion_response.get("modelVersion")
+        model_response.model = model_version if isinstance(model_version, str) else model
 
         ## CHECK IF RESPONSE FLAGGED
         if "promptFeedback" in completion_response and "blockReason" in completion_response["promptFeedback"]:
@@ -3264,7 +3265,12 @@ class ModelResponseIterator:
 
             processed_chunk: Final = GenerateContentResponseBody(**chunk)
             response_id: Final = processed_chunk.get("responseId")
-            model_response = ModelResponseStream(choices=[], id=response_id)
+            chunk_model_version: Final = processed_chunk.get("modelVersion")
+            model_response = ModelResponseStream(
+                choices=[],
+                id=response_id,
+                model=chunk_model_version if isinstance(chunk_model_version, str) else None,
+            )
 
             # Check if prompt is blocked due to content filtering
             blocked_response: Final = VertexGeminiConfig._check_prompt_level_content_filter(
diff --git a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
index 101f6e6fa5d..29a47cd54f2 100644
--- a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
+++ b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
@@ -5836,3 +5836,65 @@ def test_supported_reasoning_efforts_still_map(model):
             drop_params=False,
         )
         assert "thinkingConfig" in result
+
+
+def _generate_content_body() -> dict:
+    return {
+        "candidates": [
+            {
+                "content": {"role": "model", "parts": [{"text": "hi"}]},
+                "finishReason": "STOP",
+                "index": 0,
+            }
+        ],
+        "usageMetadata": {
+            "promptTokenCount": 5,
+            "candidatesTokenCount": 7,
+            "totalTokenCount": 12,
+        },
+    }
+
+
+def test_generate_content_transform_uses_reported_model_version():
+    """The served modelVersion must win over the requested name so downstream
+    pricing sees what actually ran."""
+    import httpx
+
+    body = {**_generate_content_body(), "modelVersion": "gemini-x-served"}
+    response: Final = VertexGeminiConfig()._transform_google_generate_content_to_openai_model_response(
+        completion_response=body,
+        model_response=ModelResponse(),
+        model="gemini-x",
+        logging_obj=MagicMock(),
+        raw_response=httpx.Response(200, headers={}),
+    )
+
+    assert response.model == "gemini-x-served"
+
+
+def test_generate_content_transform_falls_back_to_requested_model():
+    import httpx
+
+    response: Final = VertexGeminiConfig()._transform_google_generate_content_to_openai_model_response(
+        completion_response=_generate_content_body(),
+        model_response=ModelResponse(),
+        model="gemini-x",
+        logging_obj=MagicMock(),
+        raw_response=httpx.Response(200, headers={}),
+    )
+
+    assert response.model == "gemini-x"
+
+
+def test_streaming_chunk_carries_model_version():
+    from litellm.llms.vertex_ai.gemini.vertex_and_google_ai_studio_gemini import (
+        ModelResponseIterator,
+    )
+
+    chunk = {**_generate_content_body(), "modelVersion": "gemini-x-served"}
+    iterator: Final = ModelResponseIterator(
+        streaming_response=[], sync_stream=True, logging_obj=MagicMock()
+    )
+    streaming_chunk: Final = iterator.chunk_parser(chunk)
+
+    assert streaming_chunk.model == "gemini-x-served"

From 5eab1feb2011c800295fee5025a87402019baf0a Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 00:42:13 +0000
Subject: [PATCH 11/67] fix(fireworks-ai): bill cache-write, reasoning, and
 audio tokens via the shared cost calculator

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/llms/fireworks_ai/cost_calculator.py  | 64 +++++++-------
 .../test_fireworks_ai_cost_calculator.py      | 85 ++++++++++++++++---
 2 files changed, 105 insertions(+), 44 deletions(-)

diff --git a/litellm/llms/fireworks_ai/cost_calculator.py b/litellm/llms/fireworks_ai/cost_calculator.py
index 3c43075d940..7bd01115a94 100644
--- a/litellm/llms/fireworks_ai/cost_calculator.py
+++ b/litellm/llms/fireworks_ai/cost_calculator.py
@@ -2,9 +2,9 @@
 For calculating cost of fireworks ai serverless inference models.
 """
 
-import math
+from collections.abc import Mapping
 from datetime import datetime
-from typing import Final
+from typing import Final, cast
 
 from litellm.constants import (
     FIREWORKS_AI_4_B,
@@ -12,12 +12,10 @@ from litellm.constants import (
     FIREWORKS_AI_56_B_MOE,
     FIREWORKS_AI_176_B_MOE,
 )
-from litellm.litellm_core_utils.llm_cost_calc.utils import TokenRates, apply_off_peak_pricing
+from litellm.litellm_core_utils.llm_cost_calc.utils import generic_cost_per_token
 from litellm.types.utils import ModelInfo, Usage
 from litellm.utils import get_model_info
 
-NO_CACHE_READ_RATE: Final = float("nan")
-
 
 # Extract the number of billion parameters from the model name
 # only used for together_computer LLMs
@@ -67,6 +65,30 @@ def _resolve_model_info(model: str) -> ModelInfo:
         return get_model_info(model=base_model, custom_llm_provider="fireworks_ai")
 
 
+def _with_cache_read_fallback(model_info: ModelInfo) -> ModelInfo:
+    """Most fireworks_ai price-map entries publish no cache-read rate, and the provider bills
+    cached reads at the input rate. generic_cost_per_token prices a missing rate at $0, so the
+    fallback is written into a copy of the entry (the shared model-cost dict must not be
+    mutated), including inside off_peak_pricing so cached reads track the off-peak input rate
+    the way the previous calculator did."""
+    if model_info.get("cache_read_input_token_cost") is not None:
+        return model_info
+    input_rate: Final = model_info.get("input_cost_per_token")
+    if input_rate is None:
+        return model_info
+    effective: Final[dict[str, object]] = dict(model_info)
+    effective["cache_read_input_token_cost"] = input_rate
+    off_peak: Final = effective.get("off_peak_pricing")
+    if isinstance(off_peak, Mapping):
+        off_peak_map: Final[Mapping[str, object]] = cast(Mapping[str, object], off_peak)
+        if "cache_read_input_token_cost" not in off_peak_map:
+            effective["off_peak_pricing"] = {
+                **off_peak_map,
+                "cache_read_input_token_cost": off_peak_map.get("input_cost_per_token", input_rate),
+            }
+    return cast(ModelInfo, effective)
+
+
 def cost_per_token(model: str, usage: Usage, current_time: datetime | None = None) -> tuple[float, float]:
     """
     Calculates the cost per token for a given model, prompt tokens, and completion tokens,
@@ -80,29 +102,11 @@ def cost_per_token(model: str, usage: Usage, current_time: datetime | None = Non
     Returns:
         Tuple[float, float] - prompt_cost_in_usd, completion_cost_in_usd
     """
-    model_info: Final = _resolve_model_info(model)
-    standard_cache_read_rate: Final = model_info.get("cache_read_input_token_cost")
-    rates: Final = apply_off_peak_pricing(
-        model_info,
-        current_time,
-        TokenRates(
-            input_rate=model_info["input_cost_per_token"] or 0.0,
-            output_rate=model_info["output_cost_per_token"] or 0.0,
-            cache_read_rate=standard_cache_read_rate if standard_cache_read_rate is not None else NO_CACHE_READ_RATE,
-            cache_creation_rate=0.0,
-            reasoning_rate=None,
-        ),
+    model_info: Final = _with_cache_read_fallback(_resolve_model_info(model))
+    return generic_cost_per_token(
+        model=model,
+        usage=usage,
+        custom_llm_provider="fireworks_ai",
+        model_info=model_info,
+        current_time=current_time,
     )
-    cache_read_rate: Final[float] = rates.input_rate if math.isnan(rates.cache_read_rate) else rates.cache_read_rate
-
-    prompt_tokens_details: Final = usage.prompt_tokens_details
-    cached_tokens: Final[int] = (
-        prompt_tokens_details.cached_tokens
-        if prompt_tokens_details is not None and prompt_tokens_details.cached_tokens is not None
-        else 0
-    )
-    non_cached_prompt_tokens: Final[int] = max(usage.prompt_tokens - cached_tokens, 0)
-    prompt_cost: Final[float] = non_cached_prompt_tokens * rates.input_rate + cached_tokens * cache_read_rate
-    completion_cost: Final[float] = usage.completion_tokens * rates.output_rate
-
-    return prompt_cost, completion_cost
diff --git a/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py b/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
index c2e42da1b4c..40a07a10cfc 100644
--- a/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
+++ b/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
@@ -1,13 +1,16 @@
-
 import math
 from datetime import datetime, timezone
 
 import pytest
 
-
 import litellm
 from litellm.llms.fireworks_ai.cost_calculator import cost_per_token
-from litellm.types.utils import OffPeakPricing, PromptTokensDetailsWrapper, Usage
+from litellm.types.utils import (
+    CompletionTokensDetailsWrapper,
+    OffPeakPricing,
+    PromptTokensDetailsWrapper,
+    Usage,
+)
 
 MODEL = "accounts/fireworks/models/glm-5p2"
 INPUT_COST = 1.4e-06
@@ -47,12 +50,8 @@ def test_warm_call_cheaper_than_cold_call():
     prompt_tokens = 7036
     completion_tokens = 8
 
-    cold_prompt_cost, _ = cost_per_token(
-        model=MODEL, usage=_usage(prompt_tokens, 16, completion_tokens)
-    )
-    warm_prompt_cost, _ = cost_per_token(
-        model=MODEL, usage=_usage(prompt_tokens, 7020, completion_tokens)
-    )
+    cold_prompt_cost, _ = cost_per_token(model=MODEL, usage=_usage(prompt_tokens, 16, completion_tokens))
+    warm_prompt_cost, _ = cost_per_token(model=MODEL, usage=_usage(prompt_tokens, 7020, completion_tokens))
 
     assert warm_prompt_cost < cold_prompt_cost
 
@@ -61,9 +60,7 @@ def test_no_cached_tokens_matches_full_input_rate():
     prompt_tokens = 100
     completion_tokens = 10
 
-    prompt_cost, completion_cost = cost_per_token(
-        model=MODEL, usage=_usage(prompt_tokens, 0, completion_tokens)
-    )
+    prompt_cost, completion_cost = cost_per_token(model=MODEL, usage=_usage(prompt_tokens, 0, completion_tokens))
 
     assert prompt_cost == pytest.approx(prompt_tokens * INPUT_COST)
     assert completion_cost == pytest.approx(completion_tokens * OUTPUT_COST)
@@ -78,7 +75,9 @@ STANDARD_OUTPUT_COST = 6e-07
 STANDARD_CACHE_READ_COST = 1.5e-08
 
 
-def _register_off_peak_model(off_peak_pricing: OffPeakPricing, cache_read_cost: float | None = STANDARD_CACHE_READ_COST) -> None:
+def _register_off_peak_model(
+    off_peak_pricing: OffPeakPricing, cache_read_cost: float | None = STANDARD_CACHE_READ_COST
+) -> None:
     litellm.model_cost[f"fireworks_ai/{OFF_PEAK_MODEL}"] = {
         "litellm_provider": "fireworks_ai",
         "mode": "chat",
@@ -151,10 +150,68 @@ def test_off_peak_window_bills_cached_tokens_at_the_off_peak_input_rate_without_
 def test_off_peak_defaults_to_the_current_time():
     """The proxy's cost dispatch passes no clock, so an all-day window has to apply on the
     default current time."""
-    _register_off_peak_model({"hours_utc": "00:00-00:00", "input_cost_per_token": 1e-08, "output_cost_per_token": 2e-08})
+    _register_off_peak_model(
+        {"hours_utc": "00:00-00:00", "input_cost_per_token": 1e-08, "output_cost_per_token": 2e-08}
+    )
     usage = _usage(prompt_tokens=1000, cached_tokens=0, completion_tokens=200)
 
     prompt_cost, completion_cost = cost_per_token(model=OFF_PEAK_MODEL, usage=usage)
 
     assert math.isclose(prompt_cost, 1000 * 1e-08, rel_tol=1e-10)
     assert math.isclose(completion_cost, 200 * 2e-08, rel_tol=1e-10)
+
+
+COMPONENT_MODEL = "accounts/fireworks/models/cost-components-test"
+COMPONENT_INPUT_COST = 1e-06
+COMPONENT_OUTPUT_COST = 2e-06
+COMPONENT_CACHE_READ_COST = 1e-07
+COMPONENT_CACHE_CREATION_COST = 3e-06
+COMPONENT_REASONING_COST = 4e-06
+COMPONENT_AUDIO_IN_COST = 5e-06
+COMPONENT_AUDIO_OUT_COST = 6e-06
+
+
+def test_cache_write_reasoning_and_audio_tokens_are_billed_at_their_component_rates():
+    """Regression (LIT-7837): the hand-rolled fireworks_ai calculator billed every
+    cache-creation, reasoning and audio token at $0. The shared calculator treats the
+    prompt detail counts as subsets of prompt_tokens and the completion detail counts as
+    subsets of completion_tokens, billing each remainder at the text rate."""
+    litellm.model_cost[f"fireworks_ai/{COMPONENT_MODEL}"] = {
+        "litellm_provider": "fireworks_ai",
+        "mode": "chat",
+        "input_cost_per_token": COMPONENT_INPUT_COST,
+        "output_cost_per_token": COMPONENT_OUTPUT_COST,
+        "cache_read_input_token_cost": COMPONENT_CACHE_READ_COST,
+        "cache_creation_input_token_cost": COMPONENT_CACHE_CREATION_COST,
+        "output_cost_per_reasoning_token": COMPONENT_REASONING_COST,
+        "input_cost_per_audio_token": COMPONENT_AUDIO_IN_COST,
+        "output_cost_per_audio_token": COMPONENT_AUDIO_OUT_COST,
+    }
+    usage = Usage(
+        prompt_tokens=1000,
+        completion_tokens=500,
+        total_tokens=1500,
+        prompt_tokens_details=PromptTokensDetailsWrapper(
+            cached_tokens=300,
+            cache_creation_tokens=200,
+            audio_tokens=100,
+        ),
+        completion_tokens_details=CompletionTokensDetailsWrapper(
+            reasoning_tokens=200,
+            audio_tokens=50,
+        ),
+    )
+
+    prompt_cost, completion_cost = cost_per_token(model=COMPONENT_MODEL, usage=usage)
+
+    expected_prompt_cost = (
+        400 * COMPONENT_INPUT_COST
+        + 300 * COMPONENT_CACHE_READ_COST
+        + 200 * COMPONENT_CACHE_CREATION_COST
+        + 100 * COMPONENT_AUDIO_IN_COST
+    )
+    expected_completion_cost = (
+        250 * COMPONENT_OUTPUT_COST + 200 * COMPONENT_REASONING_COST + 50 * COMPONENT_AUDIO_OUT_COST
+    )
+    assert prompt_cost == pytest.approx(expected_prompt_cost)
+    assert completion_cost == pytest.approx(expected_completion_cost)

From 405a12783889945a314942a949a162f9186fca86 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 00:57:05 +0000
Subject: [PATCH 12/67] fix(fireworks-ai): drop banned typing.cast to a
 suppressed import for the copied pricing entry

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/llms/fireworks_ai/cost_calculator.py | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/litellm/llms/fireworks_ai/cost_calculator.py b/litellm/llms/fireworks_ai/cost_calculator.py
index 7bd01115a94..f323d78e22d 100644
--- a/litellm/llms/fireworks_ai/cost_calculator.py
+++ b/litellm/llms/fireworks_ai/cost_calculator.py
@@ -2,9 +2,11 @@
 For calculating cost of fireworks ai serverless inference models.
 """
 
-from collections.abc import Mapping
 from datetime import datetime
-from typing import Final, cast
+from typing import (
+    Final,
+    cast,  # noqa: TID251  # the fallback entry is a dict copy of a ReadOnly TypedDict; no cast-free way to retype it
+)
 
 from litellm.constants import (
     FIREWORKS_AI_4_B,
@@ -78,14 +80,11 @@ def _with_cache_read_fallback(model_info: ModelInfo) -> ModelInfo:
         return model_info
     effective: Final[dict[str, object]] = dict(model_info)
     effective["cache_read_input_token_cost"] = input_rate
-    off_peak: Final = effective.get("off_peak_pricing")
-    if isinstance(off_peak, Mapping):
-        off_peak_map: Final[Mapping[str, object]] = cast(Mapping[str, object], off_peak)
-        if "cache_read_input_token_cost" not in off_peak_map:
-            effective["off_peak_pricing"] = {
-                **off_peak_map,
-                "cache_read_input_token_cost": off_peak_map.get("input_cost_per_token", input_rate),
-            }
+    off_peak: Final = model_info.get("off_peak_pricing")
+    if off_peak is not None and "cache_read_input_token_cost" not in off_peak:
+        off_peak_copy: Final[dict[str, object]] = dict(off_peak)
+        off_peak_copy["cache_read_input_token_cost"] = off_peak_copy.get("input_cost_per_token", input_rate)
+        effective["off_peak_pricing"] = off_peak_copy
     return cast(ModelInfo, effective)
 
 

From 5aa2adbacd0244e8c6f0b22c6fb8dc02679e1bc0 Mon Sep 17 00:00:00 2001
From: Tin Chi Lo <tin@berri.ai>
Date: Tue, 15 Sep 2026 18:02:05 -0700
Subject: [PATCH 13/67] fix(proxy): preserve Anthropic pricing modifiers in
 router savings

---
 litellm/llms/anthropic/cost_calculation.py    | 20 ++++--
 litellm/proxy/spend_tracking/savings.py       | 62 +++++++++++--------
 .../proxy/spend_tracking/test_savings.py      | 29 +++++++++
 3 files changed, 79 insertions(+), 32 deletions(-)

diff --git a/litellm/llms/anthropic/cost_calculation.py b/litellm/llms/anthropic/cost_calculation.py
index 95615b8e748..4a935ac18b4 100644
--- a/litellm/llms/anthropic/cost_calculation.py
+++ b/litellm/llms/anthropic/cost_calculation.py
@@ -18,7 +18,9 @@ if TYPE_CHECKING:
 import litellm
 
 
-def cost_per_token(model: str, usage: "Usage", service_tier: str | None = None) -> tuple[float, float]:
+def cost_per_token(
+    model: str, usage: "Usage", service_tier: str | None = None, model_info: "ModelInfo | None" = None
+) -> tuple[float, float]:
     """
     Calculates the cost per token for a given model, prompt tokens, and completion tokens.
 
@@ -27,6 +29,7 @@ def cost_per_token(model: str, usage: "Usage", service_tier: str | None = None)
         - usage: LiteLLM Usage block, containing anthropic caching information
         - service_tier: the service tier the request was served at (e.g. "priority"),
           read from the Anthropic response usage and used to select tier-specific pricing
+        - model_info: effective deployment prices, when they override public rates
 
     Returns:
         Tuple[float, float] - prompt_cost_in_usd, completion_cost_in_usd
@@ -36,16 +39,23 @@ def cost_per_token(model: str, usage: "Usage", service_tier: str | None = None)
         usage=usage,
         custom_llm_provider="anthropic",
         service_tier=service_tier,
+        model_info=model_info,
     )
 
     # Apply provider_specific_entry multipliers for geo/speed routing
     try:
-        model_info: Final = litellm.get_model_info(model=model, custom_llm_provider="anthropic")
-        provider_specific_entry: Final[dict] = model_info.get("provider_specific_entry") or {}
+        effective_info: Final = (
+            model_info
+            if model_info is not None
+            else litellm.get_model_info(model=model, custom_llm_provider="anthropic")
+        )
+        provider_specific_entry: Final = effective_info.get("provider_specific_entry")
 
-        geo_multiplier: Final = get_provider_specific_geo_multiplier(model_info=model_info, usage=usage)
+        geo_multiplier: Final = get_provider_specific_geo_multiplier(model_info=effective_info, usage=usage)
         speed_multiplier: Final = (
-            provider_specific_entry.get("fast", 1.0) if getattr(usage, "speed", None) == "fast" else 1.0
+            provider_specific_entry.get("fast", 1.0)
+            if provider_specific_entry and getattr(usage, "speed", None) == "fast"
+            else 1.0
         )
 
         if speed_multiplier != 1.0:
diff --git a/litellm/proxy/spend_tracking/savings.py b/litellm/proxy/spend_tracking/savings.py
index 950fcca2039..7d9b6514a34 100644
--- a/litellm/proxy/spend_tracking/savings.py
+++ b/litellm/proxy/spend_tracking/savings.py
@@ -171,15 +171,25 @@ def _cost_of_usage(
 ) -> float | None:
     """What ``usage`` costs on ``model``, or ``None`` when the model has no pricing."""
     try:
-        prompt_cost, completion_cost = generic_cost_per_token(
-            model=model.model,
-            usage=usage,
-            custom_llm_provider=model.provider,
-            service_tier=basis.service_tier,
-            data_residency=basis.data_residency,
-            model_info=model_info,
-            vertex_location=basis.vertex_location,
-        )
+        if model.provider == "anthropic":
+            from litellm.llms.anthropic.cost_calculation import cost_per_token
+
+            prompt_cost, completion_cost = cost_per_token(
+                model=model.model,
+                usage=usage,
+                service_tier=basis.service_tier,
+                model_info=model_info,
+            )
+        else:
+            prompt_cost, completion_cost = generic_cost_per_token(
+                model=model.model,
+                usage=usage,
+                custom_llm_provider=model.provider,
+                service_tier=basis.service_tier,
+                data_residency=basis.data_residency,
+                model_info=model_info,
+                vertex_location=basis.vertex_location,
+            )
     except Exception as e:  # noqa: BLE001  # get_model_info raises bare Exception for unmapped models; degrade to zero savings
         verbose_proxy_logger.debug(
             "savings: cannot price usage for provider=%s model=%s (%s)", model.provider, model.model, e
@@ -198,11 +208,6 @@ def _cache_token_split(usage: Usage) -> tuple[int, int]:
     return int(read), int(created)
 
 
-_CACHE_SPLIT_FIELDS: Final = frozenset(
-    ("cached_tokens", "cache_creation_tokens", "cache_write_tokens", "cache_creation_token_details", "text_tokens")
-)
-
-
 def _baseline_cache_rate_keys(baseline_info: ModelInfo | None) -> tuple[bool, bool]:
     """Whether the baseline model has a ``(cache read, cache write)`` rate of its own.
 
@@ -274,19 +279,22 @@ def _baseline_usage(usage: Usage, conversation_continuing: bool, baseline_info:
         (getattr(details, field, 0) or 0) for field in ("audio_tokens", "image_tokens", "video_tokens")
     )
     return Usage(
-        prompt_tokens=usage.prompt_tokens,
-        completion_tokens=usage.completion_tokens,
-        total_tokens=usage.total_tokens,
-        completion_tokens_details=usage.completion_tokens_details,
-        prompt_tokens_details=PromptTokensDetailsWrapper(
-            **details.model_dump(exclude=_CACHE_SPLIT_FIELDS),
-            cached_tokens=reads,
-            cache_creation_tokens=writes,
-            cache_write_tokens=writes,
-            cache_creation_token_details=details.cache_creation_token_details if writes else None,
-            # Whatever no longer sits in a cache bucket is plain input on the baseline.
-            text_tokens=max(usage.prompt_tokens - reads - writes - other_modalities, 0),
-        ),
+        **{
+            **usage.model_dump(),
+            # Rebuild through Usage so private fallback counts agree with the public buckets.
+            "cache_read_input_tokens": reads,
+            "cache_creation_input_tokens": writes,
+            "prompt_tokens_details": PromptTokensDetailsWrapper(
+                **{
+                    **details.model_dump(),
+                    "cached_tokens": reads,
+                    "cache_creation_tokens": writes,
+                    "cache_write_tokens": writes,
+                    "cache_creation_token_details": details.cache_creation_token_details if writes else None,
+                    "text_tokens": max(usage.prompt_tokens - reads - writes - other_modalities, 0),
+                }
+            ),
+        },
     )
 
 
diff --git a/tests/test_litellm/proxy/spend_tracking/test_savings.py b/tests/test_litellm/proxy/spend_tracking/test_savings.py
index e466edab131..fa910671e88 100644
--- a/tests/test_litellm/proxy/spend_tracking/test_savings.py
+++ b/tests/test_litellm/proxy/spend_tracking/test_savings.py
@@ -4,6 +4,7 @@ import pytest
 
 import litellm
 from litellm.litellm_core_utils.llm_cost_calc.utils import generic_cost_per_token
+from litellm.llms.anthropic.cost_calculation import cost_per_token as anthropic_cost_per_token
 from litellm.proxy.spend_tracking.savings import (
     _baseline_usage,
     _resolve_model,
@@ -17,6 +18,34 @@ from litellm.types.utils import Usage
 pytestmark = pytest.mark.usefixtures("local_model_cost_map")
 
 
+@pytest.mark.parametrize("modifier", [{"speed": "fast"}, {"inference_geo": "us"}])
+@pytest.mark.parametrize("continuing", [False, True])
+def test_baseline_preserves_anthropic_pricing_fields(modifier: dict[str, str], continuing: bool) -> None:
+    usage: Final = _usage(1000, 0, 1000, 100).model_copy(update=modifier)
+    expected: Final = (_usage(1000, 1000, 0, 100) if continuing else usage).model_copy(update=modifier)
+    normalized: Final = _baseline_usage(usage, continuing)
+    cache_fields: Final = {"prompt_tokens_details", "cache_read_input_tokens", "cache_creation_input_tokens"}
+    assert normalized.model_dump(exclude=cache_fields) == usage.model_dump(exclude=cache_fields)
+    assert usage.prompt_tokens_details.cached_tokens == 0
+    selected_cost: Final = 0.013
+    assert compute_autorouter_savings(
+        "claude-opus-5", "claude-sonnet-5", "anthropic", usage, conversation_continuing=continuing,
+        cost_breakdown={"input_cost": 0.01, "output_cost": 0.003},
+    ) == pytest.approx(sum(anthropic_cost_per_token("claude-opus-5", expected)) - selected_cost)
+
+
+def test_anthropic_baseline_keeps_negotiated_prices_with_provider_multiplier() -> None:
+    info: Final = {
+        **litellm.get_model_info("claude-opus-5", "anthropic"),
+        "input_cost_per_token": 1e-6, "output_cost_per_token": 2e-6, "cache_read_input_token_cost": 3e-7,
+    }
+    usage: Final = _usage(1000, 1000, 0, 100).model_copy(update={"speed": "fast"})
+    assert compute_autorouter_savings(
+        "claude-opus-5", "claude-sonnet-5", "anthropic", usage, baseline_info=info,
+        cost_breakdown={"input_cost": 0.01, "output_cost": 0.003},
+    ) == pytest.approx(0.0015 * 2 - 0.013)
+
+
 def _anthropic_costs(model: str) -> tuple[float, float]:
     info = litellm.get_model_info(model=model, custom_llm_provider="anthropic")
     input_cost = info["input_cost_per_token"] or 0.0

From de9aa48cd62e73b5b291d6c5a2a952dd35f09f00 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:02:29 +0000
Subject: [PATCH 14/67] fix(responses): count multimodal input and tool-call
 output in the streamed usage fallback

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 38 ++++++++-
 litellm/responses/utils.py                    | 16 ----
 .../responses/test_streaming_iterator.py      | 78 ++++++++++++++++++-
 3 files changed, 112 insertions(+), 20 deletions(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 52b50167190..6cb0331620f 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -32,6 +32,9 @@ from litellm.litellm_core_utils.llm_response_utils.response_metadata import (
 )
 from litellm.litellm_core_utils.thread_pool_executor import executor
 from litellm.llms.base_llm.responses.transformation import BaseResponsesAPIConfig
+from litellm.responses.litellm_completion_transformation.transformation import (
+    LiteLLMCompletionResponsesConfig,
+)
 from litellm.responses.utils import ResponseAPILoggingUtils, ResponsesAPIRequestUtils
 from litellm.types.integrations.custom_logger import converted_stream_requested
 from litellm.types.llms.openai import (
@@ -257,6 +260,7 @@ class BaseResponsesAPIStreamingIterator:
         self._failure_handled = False  # Track if failure handler has been called
         self._yielded_first_chunk = False
         self._generated_content = ""
+        self._generated_tool_arguments = ""
         self._completed_response_cached = False
         self._completed_response_logged = False
         self._completed_response_cache_hit: bool | None = None
@@ -352,6 +356,10 @@ class BaseResponsesAPIStreamingIterator:
                     _delta: Final = getattr(openai_responses_api_chunk, "delta", None)
                     if isinstance(_delta, str):
                         self._generated_content += _delta
+                elif _event_type == ResponsesAPIStreamEvents.FUNCTION_CALL_ARGUMENTS_DELTA:
+                    _args_delta: Final = getattr(openai_responses_api_chunk, "delta", None)
+                    if isinstance(_args_delta, str):
+                        self._generated_tool_arguments += _args_delta
                 _stream_model_id: Final = _model_id_from_metadata(self.litellm_metadata)
                 if _event_type in (
                     ResponsesAPIStreamEvents.OUTPUT_ITEM_ADDED,
@@ -432,8 +440,11 @@ class BaseResponsesAPIStreamingIterator:
                         and _response_obj is not None
                         and _response_obj.usage is None
                     ):
-                        _response_obj.usage = ResponseAPILoggingUtils.estimate_usage_from_text(
-                            self.model or "", self.request_data.get("input"), self._generated_content
+                        _response_obj.usage = _estimate_usage_from_text(
+                            self.model or "",
+                            self.request_data.get("input"),
+                            self.request_data,
+                            self._generated_content + self._generated_tool_arguments,
                         )
                     _stamp_responses_usage_cost(getattr(openai_responses_api_chunk, "response", None), self.logging_obj)
 
@@ -1347,6 +1358,29 @@ def _usage_as_model(usage: object) -> ResponseAPIUsage | None:
         return None
 
 
+def _estimate_usage_from_text(
+    model: str,
+    request_input: object,
+    responses_api_request: Mapping[str, object],
+    generated_text: str,
+) -> ResponseAPIUsage:
+    messages: Final = LiteLLMCompletionResponsesConfig.transform_responses_api_input_to_messages(  # pyright: ignore[reportUnknownMemberType]  # the transformer's signature is partially untyped
+        input=request_input,  # pyright: ignore[reportArgumentType]  # the raw Responses API input is a str or ResponseInputParam list, matching the helper's declared union
+        responses_api_request=dict(responses_api_request),
+    )
+    input_tokens: Final = litellm.token_counter(  # pyright: ignore[reportUnknownMemberType]  # token_counter's public signature is untyped
+        model=model, messages=messages
+    )
+    output_tokens: Final = litellm.token_counter(  # pyright: ignore[reportUnknownMemberType]  # token_counter's public signature is untyped
+        model=model, text=generated_text, count_response_tokens=True
+    )
+    return ResponseAPIUsage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=input_tokens + output_tokens,
+    )
+
+
 def _stamp_responses_usage_cost(
     response_obj: ResponsesAPIResponse | None, logging_obj: LiteLLMLoggingObj | None
 ) -> None:
diff --git a/litellm/responses/utils.py b/litellm/responses/utils.py
index e523b3771af..41a3ded7022 100644
--- a/litellm/responses/utils.py
+++ b/litellm/responses/utils.py
@@ -1,5 +1,4 @@
 import base64
-import json
 import re
 from collections.abc import Iterable, Mapping, Sequence
 from typing import Any, Final, Optional, TypeVar, Union, cast, get_type_hints, overload
@@ -1240,18 +1239,3 @@ class ResponseAPILoggingUtils:
             setattr(chat_usage, "cost", response_api_usage.cost)
 
         return chat_usage
-
-    @staticmethod
-    def estimate_usage_from_text(model: str, request_input: object, generated_text: str) -> ResponseAPIUsage:
-        input_text: Final = request_input if isinstance(request_input, str) else json.dumps(request_input, default=str)
-        input_tokens: Final = litellm.token_counter(  # pyright: ignore[reportUnknownMemberType]  # token_counter's public signature is untyped
-            model=model, text=input_text
-        )
-        output_tokens: Final = litellm.token_counter(  # pyright: ignore[reportUnknownMemberType]  # token_counter's public signature is untyped
-            model=model, text=generated_text, count_response_tokens=True
-        )
-        return ResponseAPIUsage(
-            input_tokens=input_tokens,
-            output_tokens=output_tokens,
-            total_tokens=input_tokens + output_tokens,
-        )
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index c593946ac4a..c3721353d42 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -5,12 +5,13 @@ completion_start_time = end_time."""
 
 import json
 from datetime import datetime
-from typing import Optional
+from typing import Final, Optional
 from unittest.mock import Mock, patch
 
 import httpx
 import pytest
 
+import litellm
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
 from litellm.llms.base_llm.responses.transformation import BaseResponsesAPIConfig
 from litellm.responses.streaming_iterator import (
@@ -351,8 +352,10 @@ def _mock_config_with_completed_response(response: ResponsesAPIResponse) -> Mock
             return completed
         stub = Mock()
         stub.type = evt_type
-        if evt_type == "response.output_text.delta":
+        if "delta" in parsed_chunk:
             stub.delta = parsed_chunk.get("delta")
+        if "item" in parsed_chunk:
+            stub.item = parsed_chunk.get("item")
         return stub
 
     mock_config.transform_streaming_response.side_effect = _transform
@@ -718,3 +721,74 @@ async def test_streaming_logging_copy_keeps_client_usage_when_response_fails_val
     assert isinstance(client_usage, ResponseAPIUsage)
     assert client_usage.input_tokens == 29
     assert client_usage.cost == pytest.approx(0.0001)
+
+
+@pytest.mark.asyncio
+async def test_completed_event_without_usage_counts_tool_call_arguments():
+    """A function-call-only stream still bills output tokens: streamed
+    function_call_arguments deltas feed the text estimate."""
+    response = _responses_api_response_without_usage()
+    iterator = _make_iterator(
+        sse_events=[
+            _sse_event(
+                {
+                    "type": "response.output_item.added",
+                    "item": {"type": "function_call", "name": "get_weather", "call_id": "call_1"},
+                }
+            ),
+            _sse_event(
+                {
+                    "type": "response.function_call_arguments.delta",
+                    "delta": '{"location": "San Francisco", "unit": "celsius"}',
+                }
+            ),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=_mock_config_with_completed_response(response),
+        request_data={"input": "what is the weather in san francisco"},
+    )
+
+    async for _ in iterator:
+        pass
+
+    usage = iterator.completed_response.response.usage
+    assert usage is not None
+    assert usage.output_tokens > 0
+    assert usage.total_tokens == usage.input_tokens + usage.output_tokens
+
+
+@pytest.mark.asyncio
+async def test_completed_event_without_usage_counts_multimodal_input_as_messages():
+    """Multimodal request input is counted as chat messages, not as a JSON blob:
+    a huge base64 image must not inflate the estimated input tokens."""
+    image_input: Final = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "input_text", "text": "what is in this image"},
+                {
+                    "type": "input_image",
+                    "image_url": "data:image/png;base64," + "A" * 4000,
+                },
+            ],
+        }
+    ]
+    json_count: Final = litellm.token_counter(model="gpt-4o-mini", text=json.dumps(image_input))
+    response = _responses_api_response_without_usage()
+    iterator = _make_iterator(
+        sse_events=[
+            _sse_event({"type": "response.output_text.delta", "delta": "it is a cat"}),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=_mock_config_with_completed_response(response),
+        request_data={"input": image_input},
+    )
+
+    async for _ in iterator:
+        pass
+
+    usage = iterator.completed_response.response.usage
+    assert usage is not None
+    assert usage.input_tokens < json_count / 2

From 77a632767500f0c79ce2816584572df8147c7a94 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 21:04:32 +0000
Subject: [PATCH 15/67] feat(guardrails): support pre_call and during_call
 modes for llm_as_a_judge

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 65 +++++++++-----
 .../proxy/guardrails/test_llm_as_a_judge.py   | 85 +++++++++++++++++--
 .../_components/llm_judge/LLMJudgeFields.tsx  |  4 +-
 3 files changed, 125 insertions(+), 29 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 172b1440ca3..31be90f56ef 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -1,7 +1,8 @@
-"""LLM-as-a-Judge guardrail: uses an LLM to score responses against weighted criteria."""
+"""LLM-as-a-Judge guardrail: uses an LLM to score requests or responses against weighted criteria."""
 
 from collections.abc import Callable, Sequence
 from datetime import datetime
+from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, Generic, Literal, Optional, TypeVar
 
 from fastapi import HTTPException
@@ -26,15 +27,29 @@ if TYPE_CHECKING:
     from litellm.types.llms.openai import AllMessageValues
     from litellm.types.utils import StandardLoggingEvalInformation
 
-JUDGE_SYSTEM_PROMPT = """You are a quality judge. Evaluate the assistant's response against the criteria provided.
+JudgeInputType = Literal["request", "response"]
+
+_JUDGE_SYSTEM_PROMPT_TEMPLATE: Final = """You are a quality judge. Evaluate the {subject} against the criteria provided.
 For each criterion, assign a score from 0 to 100 and provide concise reasoning.
 Return ONLY valid JSON in this exact format:
-{
+{{
   "verdicts": [
-    {"criterion_name": "<name>", "score": <0-100>, "reasoning": "<one sentence>", "passed": <true|false>, "weight": <weight>}
+    {{"criterion_name": "<name>", "score": <0-100>, "reasoning": "<one sentence>", "passed": <true|false>, "weight": <weight>}}
   ],
   "overall_score": <weighted average 0-100>
-}"""
+}}"""
+
+JUDGE_SYSTEM_PROMPTS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
+    {
+        "request": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="user's request"),
+        "response": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="assistant's response"),
+    }
+)
+JUDGE_SYSTEM_PROMPT: Final = JUDGE_SYSTEM_PROMPTS["response"]
+
+_JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
+    {"request": "User request to evaluate", "response": "Assistant response to evaluate"}
+)
 
 _VALID_ON_FAILURE: Final = frozenset({"block", "log"})
 
@@ -89,7 +104,8 @@ def _get_litellm_param(
 def _build_judge_prompt(
     criteria: Sequence[JudgeCriterion],
     messages: Sequence[JudgeMessage],
-    response_text: str,
+    text_under_review: str,
+    input_type: JudgeInputType = "response",
 ) -> str:
     criteria_block: Final = "\n".join(
         f"- {c.get('name', '')} (weight {c.get('weight', 0)}%): {c.get('description', '')}" for c in criteria
@@ -99,15 +115,16 @@ def _build_judge_prompt(
         for m in messages
         if m.get("content") is not None
     )
+    conversation_block: Final = f"Conversation:\n{conversation}\n\n" if input_type == "response" else ""
     return (
         f"Criteria to evaluate:\n{criteria_block}\n\n"
-        f"Conversation:\n{conversation}\n\n"
-        f"Assistant response to evaluate:\n{response_text}"
+        f"{conversation_block}"
+        f"{_JUDGE_SUBJECT_LABELS[input_type]}:\n{text_under_review}"
     )
 
 
 class LLMAsAJudgeGuardrail(CustomGuardrail):
-    """Post-call guardrail that judges response quality via an LLM."""
+    """Guardrail that judges request (pre_call/during_call) or response (post_call) quality via an LLM."""
 
     def __init__(
         self,
@@ -143,18 +160,19 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
 
     @classmethod
     def get_supported_event_hooks(cls) -> list[GuardrailEventHooks]:
-        return [GuardrailEventHooks.post_call]
+        return [GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call, GuardrailEventHooks.post_call]
 
     async def _run_judge(
         self,
         messages: Sequence[JudgeMessage],
-        response_text: str,
+        text_under_review: str,
+        input_type: JudgeInputType = "response",
     ) -> dict[str, object]:
         judge_messages: Final[list[AllMessageValues]] = [
-            {"role": "system", "content": JUDGE_SYSTEM_PROMPT},
+            {"role": "system", "content": JUDGE_SYSTEM_PROMPTS[input_type]},
             {
                 "role": "user",
-                "content": _build_judge_prompt(self.criteria, messages, response_text),
+                "content": _build_judge_prompt(self.criteria, messages, text_under_review, input_type),
             },
         ]
         response: Final = await judge_acompletion(
@@ -174,13 +192,9 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         input_type: Literal["request", "response"],
         logging_obj: Optional["LiteLLMLoggingObj"] = None,
     ) -> GenericGuardrailAPIInputs:
-        # Only evaluate post-call (response text). Fail open on pre-call.
-        if input_type != "response":
-            return inputs
-
         texts: Final = inputs.get("texts") or []
-        response_text: Final = " ".join(texts)
-        if not response_text:
+        text_under_review: Final = " ".join(texts)
+        if not text_under_review:
             return inputs
 
         start_time: Final = datetime.now()
@@ -191,7 +205,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
             messages: Final[Sequence[JudgeMessage]] = request_data.get("messages") or []
 
             try:
-                judge_result = await self._run_judge(messages, response_text)
+                judge_result = await self._run_judge(messages, text_under_review, input_type)
             except Exception as judge_err:
                 verbose_logger.warning(
                     "llm_as_a_judge guardrail: judge call failed, failing open. Error: %s", judge_err
@@ -230,7 +244,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
                     raise HTTPException(
                         status_code=422,
                         detail={
-                            "error": "LLM judge rejected response: score below threshold",
+                            "error": f"LLM judge rejected {input_type}: score below threshold",
                             "overall_score": overall_score,
                             "threshold": self.overall_threshold,
                             "verdicts": judge_result.get("verdicts", []),
@@ -252,9 +266,16 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
                 guardrail_status=status,
                 start_time=start_time.timestamp(),
                 end_time=datetime.now().timestamp(),
-                event_type=GuardrailEventHooks.post_call,
+                event_type=self._event_type_for(input_type),
             )
 
+    def _event_type_for(self, input_type: JudgeInputType) -> GuardrailEventHooks:
+        if input_type == "response":
+            return GuardrailEventHooks.post_call
+        if self.event_hook is GuardrailEventHooks.during_call:
+            return GuardrailEventHooks.during_call
+        return GuardrailEventHooks.pre_call
+
 
 def initialize_guardrail(
     litellm_params: "LitellmParams",
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index bd2553b3280..a076da62566 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -13,7 +13,7 @@ from litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge import (
     _parse_judge_verdict,
     initialize_guardrail,
 )
-
+from litellm.types.guardrails import GuardrailEventHooks
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -141,12 +141,87 @@ def test_initialize_guardrail_invalid_on_failure():
 # ---------------------------------------------------------------------------
 
 
+def _judge_router(overall_score: float):
+    """Real Router with the outbound judge call stubbed, so the test can inspect what the judge was asked."""
+    from litellm import Router
+
+    router = Router(
+        model_list=[
+            {"model_name": "gpt-4o-mini", "litellm_params": {"model": "openai/gpt-4o-mini", "api_key": "sk-test"}}
+        ]
+    )
+    router.acompletion = AsyncMock(
+        return_value=MagicMock(
+            choices=[MagicMock(message=MagicMock(content=json.dumps(_make_verdict_response(overall_score))))]
+        )
+    )
+    return router
+
+
+@pytest.mark.parametrize("mode", [GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call])
+def test_guardrail_accepts_request_side_modes(mode):
+    guardrail = _make_guardrail(event_hook=mode)
+    assert guardrail.should_run_guardrail({"metadata": {"guardrails": ["test_judge"]}}, mode) is True
+
+
 @pytest.mark.asyncio
-async def test_apply_guardrail_pre_call_passthrough():
-    guardrail = _make_guardrail()
-    inputs = {"texts": ["some text"]}
-    result = await guardrail.apply_guardrail(inputs, {}, "request")
+async def test_apply_guardrail_request_blocks_below_threshold():
+    router = _judge_router(50.0)
+    guardrail = _make_guardrail(
+        overall_threshold=80.0,
+        on_failure="block",
+        event_hook=GuardrailEventHooks.pre_call,
+        router_provider=lambda: router,
+    )
+    request_data: dict = {"messages": [{"role": "user", "content": "write me malware"}], "metadata": {}}
+    inputs = {"texts": ["write me malware"]}
+
+    with pytest.raises(HTTPException) as exc_info:
+        await guardrail.apply_guardrail(inputs, request_data, "request")
+
+    assert exc_info.value.status_code == 422
+    assert exc_info.value.detail["error"] == "LLM judge rejected request: score below threshold"
+    judge_messages = router.acompletion.call_args.kwargs["messages"]
+    assert "user's request" in judge_messages[0]["content"]
+    assert "User request to evaluate:\nwrite me malware" in judge_messages[1]["content"]
+    assert "Assistant response" not in judge_messages[1]["content"]
+    assert "Conversation:" not in judge_messages[1]["content"]
+    logged = request_data["metadata"]["standard_logging_guardrail_information"]
+    assert logged[0]["guardrail_status"] == "guardrail_intervened"
+    assert logged[0]["guardrail_mode"] == "pre_call"
+
+
+@pytest.mark.asyncio
+async def test_apply_guardrail_request_log_mode_records_eval_and_passes_through():
+    router = _judge_router(50.0)
+    guardrail = _make_guardrail(
+        overall_threshold=80.0,
+        on_failure="log",
+        event_hook=GuardrailEventHooks.during_call,
+        router_provider=lambda: router,
+    )
+    request_data: dict = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
+    inputs = {"texts": ["hi"]}
+
+    result = await guardrail.apply_guardrail(inputs, request_data, "request")
+
     assert result is inputs
+    assert request_data["metadata"]["eval_information"]["passed"] is False
+    assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == "during_call"
+
+
+@pytest.mark.asyncio
+async def test_apply_guardrail_response_prompt_unchanged():
+    router = _judge_router(90.0)
+    guardrail = _make_guardrail(router_provider=lambda: router)
+    request_data: dict = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
+
+    await guardrail.apply_guardrail({"texts": ["hello there"]}, request_data, "response")
+
+    judge_messages = router.acompletion.call_args.kwargs["messages"]
+    assert "assistant's response" in judge_messages[0]["content"]
+    assert "Conversation:\nUSER: hi\n\nAssistant response to evaluate:\nhello there" in judge_messages[1]["content"]
+    assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == "post_call"
 
 
 @pytest.mark.asyncio
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/guardrails/_components/llm_judge/LLMJudgeFields.tsx b/ui/litellm-dashboard/src/app/(dashboard)/guardrails/_components/llm_judge/LLMJudgeFields.tsx
index 256049975d3..7d1df1497db 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/guardrails/_components/llm_judge/LLMJudgeFields.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/guardrails/_components/llm_judge/LLMJudgeFields.tsx
@@ -87,8 +87,8 @@ const LLMJudgeFields: React.FC<LLMJudgeFieldsProps> = ({ availableModels, contro
   return (
     <FieldGroup>
       <div className="rounded-md border border-success/20 bg-success/10 px-3.5 py-2.5 text-[13px] text-success">
-        After each LLM response, the <strong>Judge Model</strong> scores it 0–100 against your criteria. If the weighted
-        average falls below the threshold, the response is blocked (or logged).
+        The <strong>Judge Model</strong> scores the user request (pre_call, during_call) or the LLM response (post_call)
+        0–100 against your criteria. If the weighted average falls below the threshold, it is blocked (or logged).
       </div>
 
       <GuardrailField

From 0b348005013e7fa567eda5b65f6d0f64ac356a62 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 21:27:53 +0000
Subject: [PATCH 16/67] fix(guardrails): resolve llm_as_a_judge request-side
 log mode from event_hook lists, drop unused alias

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                |  7 +-
 .../proxy/guardrails/test_llm_as_a_judge.py   | 71 +++++++++++--------
 2 files changed, 46 insertions(+), 32 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 31be90f56ef..1693cf75882 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -45,7 +45,6 @@ JUDGE_SYSTEM_PROMPTS: Final[MappingProxyType[JudgeInputType, str]] = MappingProx
         "response": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="assistant's response"),
     }
 )
-JUDGE_SYSTEM_PROMPT: Final = JUDGE_SYSTEM_PROMPTS["response"]
 
 _JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
     {"request": "User request to evaluate", "response": "Assistant response to evaluate"}
@@ -272,9 +271,9 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
     def _event_type_for(self, input_type: JudgeInputType) -> GuardrailEventHooks:
         if input_type == "response":
             return GuardrailEventHooks.post_call
-        if self.event_hook is GuardrailEventHooks.during_call:
-            return GuardrailEventHooks.during_call
-        return GuardrailEventHooks.pre_call
+        if self._event_hook_is_event_type(GuardrailEventHooks.pre_call):
+            return GuardrailEventHooks.pre_call
+        return GuardrailEventHooks.during_call
 
 
 def initialize_guardrail(
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index a076da62566..dd42e137ba0 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -1,6 +1,7 @@
 """Unit tests for the LLM-as-a-Judge guardrail hook."""
 
 import json
+from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -141,15 +142,12 @@ def test_initialize_guardrail_invalid_on_failure():
 # ---------------------------------------------------------------------------
 
 
-def _judge_router(overall_score: float):
-    """Real Router with the outbound judge call stubbed, so the test can inspect what the judge was asked."""
+def _judge_router(overall_score: float) -> MagicMock:
+    """Router double, injected via router_provider, that serves the judge model and returns a canned verdict."""
     from litellm import Router
 
-    router = Router(
-        model_list=[
-            {"model_name": "gpt-4o-mini", "litellm_params": {"model": "openai/gpt-4o-mini", "api_key": "sk-test"}}
-        ]
-    )
+    router: Final = MagicMock(spec=Router)
+    router.resolved_litellm_models.return_value = ("openai/gpt-4o-mini",)
     router.acompletion = AsyncMock(
         return_value=MagicMock(
             choices=[MagicMock(message=MagicMock(content=json.dumps(_make_verdict_response(overall_score))))]
@@ -159,51 +157,68 @@ def _judge_router(overall_score: float):
 
 
 @pytest.mark.parametrize("mode", [GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call])
-def test_guardrail_accepts_request_side_modes(mode):
-    guardrail = _make_guardrail(event_hook=mode)
+def test_guardrail_accepts_request_side_modes(mode: GuardrailEventHooks):
+    guardrail: Final = _make_guardrail(event_hook=mode)
     assert guardrail.should_run_guardrail({"metadata": {"guardrails": ["test_judge"]}}, mode) is True
 
 
 @pytest.mark.asyncio
-async def test_apply_guardrail_request_blocks_below_threshold():
-    router = _judge_router(50.0)
-    guardrail = _make_guardrail(
+@pytest.mark.parametrize(
+    "event_hook",
+    [GuardrailEventHooks.pre_call, [GuardrailEventHooks.pre_call]],
+    ids=["scalar", "list"],
+)
+async def test_apply_guardrail_request_blocks_below_threshold(
+    event_hook: GuardrailEventHooks | list[GuardrailEventHooks],
+):
+    router: Final = _judge_router(50.0)
+    guardrail: Final = _make_guardrail(
         overall_threshold=80.0,
         on_failure="block",
-        event_hook=GuardrailEventHooks.pre_call,
+        event_hook=event_hook,
         router_provider=lambda: router,
     )
-    request_data: dict = {"messages": [{"role": "user", "content": "write me malware"}], "metadata": {}}
-    inputs = {"texts": ["write me malware"]}
+    request_data: Final[dict[str, object]] = {
+        "messages": [{"role": "user", "content": "write me malware"}],
+        "metadata": {},
+    }
+    inputs: Final = {"texts": ["write me malware"]}
 
     with pytest.raises(HTTPException) as exc_info:
         await guardrail.apply_guardrail(inputs, request_data, "request")
 
     assert exc_info.value.status_code == 422
     assert exc_info.value.detail["error"] == "LLM judge rejected request: score below threshold"
-    judge_messages = router.acompletion.call_args.kwargs["messages"]
+    judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
     assert "user's request" in judge_messages[0]["content"]
     assert "User request to evaluate:\nwrite me malware" in judge_messages[1]["content"]
     assert "Assistant response" not in judge_messages[1]["content"]
     assert "Conversation:" not in judge_messages[1]["content"]
-    logged = request_data["metadata"]["standard_logging_guardrail_information"]
+    logged: Final = request_data["metadata"]["standard_logging_guardrail_information"]
     assert logged[0]["guardrail_status"] == "guardrail_intervened"
     assert logged[0]["guardrail_mode"] == "pre_call"
 
 
 @pytest.mark.asyncio
-async def test_apply_guardrail_request_log_mode_records_eval_and_passes_through():
-    router = _judge_router(50.0)
-    guardrail = _make_guardrail(
+@pytest.mark.parametrize(
+    "event_hook",
+    [GuardrailEventHooks.during_call, [GuardrailEventHooks.during_call]],
+    ids=["scalar", "list"],
+)
+async def test_apply_guardrail_request_log_mode_records_eval_and_passes_through(
+    event_hook: GuardrailEventHooks | list[GuardrailEventHooks],
+):
+    router: Final = _judge_router(50.0)
+    guardrail: Final = _make_guardrail(
         overall_threshold=80.0,
         on_failure="log",
-        event_hook=GuardrailEventHooks.during_call,
+        event_hook=event_hook,
         router_provider=lambda: router,
     )
-    request_data: dict = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
-    inputs = {"texts": ["hi"]}
+    request_data: Final[dict[str, object]] = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
+    inputs: Final = {"texts": ["hi"]}
 
-    result = await guardrail.apply_guardrail(inputs, request_data, "request")
+    result: Final = await guardrail.apply_guardrail(inputs, request_data, "request")
 
     assert result is inputs
     assert request_data["metadata"]["eval_information"]["passed"] is False
@@ -212,13 +227,13 @@ async def test_apply_guardrail_request_log_mode_records_eval_and_passes_through(
 
 @pytest.mark.asyncio
 async def test_apply_guardrail_response_prompt_unchanged():
-    router = _judge_router(90.0)
-    guardrail = _make_guardrail(router_provider=lambda: router)
-    request_data: dict = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(router_provider=lambda: router)
+    request_data: Final[dict[str, object]] = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
 
     await guardrail.apply_guardrail({"texts": ["hello there"]}, request_data, "response")
 
-    judge_messages = router.acompletion.call_args.kwargs["messages"]
+    judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
     assert "assistant's response" in judge_messages[0]["content"]
     assert "Conversation:\nUSER: hi\n\nAssistant response to evaluate:\nhello there" in judge_messages[1]["content"]
     assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == "post_call"

From 6fccf00d931c4c6a891a3f23dafb12035befa6a7 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 21:46:52 +0000
Subject: [PATCH 17/67] fix(guardrails): keep list and tagged mode shapes for
 llm_as_a_judge

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 36 +++++++++---------
 .../proxy/guardrails/test_llm_as_a_judge.py   | 37 +++++++++++++++++--
 2 files changed, 53 insertions(+), 20 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 1693cf75882..863cff6827f 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -17,7 +17,7 @@ from litellm.litellm_core_utils.llm_judge import (
     judge_acompletion,
     parse_json_verdict,
 )
-from litellm.types.guardrails import GuardrailEventHooks, SupportedGuardrailIntegrations
+from litellm.types.guardrails import GuardrailEventHooks, Mode, SupportedGuardrailIntegrations
 from litellm.types.utils import GenericGuardrailAPIInputs, GuardrailStatus
 
 if TYPE_CHECKING:
@@ -28,6 +28,8 @@ if TYPE_CHECKING:
     from litellm.types.utils import StandardLoggingEvalInformation
 
 JudgeInputType = Literal["request", "response"]
+JudgeEventHook = GuardrailEventHooks | list[GuardrailEventHooks] | Mode
+JudgeModeParam = str | list[str] | Mode | GuardrailEventHooks | list[GuardrailEventHooks] | None
 
 _JUDGE_SYSTEM_PROMPT_TEMPLATE: Final = """You are a quality judge. Evaluate the {subject} against the criteria provided.
 For each criterion, assign a score from 0 to 100 and provide concise reasoning.
@@ -41,13 +43,13 @@ Return ONLY valid JSON in this exact format:
 
 JUDGE_SYSTEM_PROMPTS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
     {
-        "request": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="user's request"),
+        "request": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="request"),
         "response": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="assistant's response"),
     }
 )
 
 _JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
-    {"request": "User request to evaluate", "response": "Assistant response to evaluate"}
+    {"request": "Request text to evaluate", "response": "Assistant response to evaluate"}
 )
 
 _VALID_ON_FAILURE: Final = frozenset({"block", "log"})
@@ -100,6 +102,16 @@ def _get_litellm_param(
     return default
 
 
+def _coerce_event_hook(mode: JudgeModeParam) -> JudgeEventHook:
+    if mode is None:
+        return GuardrailEventHooks.post_call
+    if isinstance(mode, Mode):
+        return mode
+    if isinstance(mode, list):
+        return [GuardrailEventHooks(hook) for hook in mode]
+    return GuardrailEventHooks(mode)
+
+
 def _build_judge_prompt(
     criteria: Sequence[JudgeCriterion],
     messages: Sequence[JudgeMessage],
@@ -132,22 +144,15 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         criteria: Sequence[JudgeCriterion],
         overall_threshold: float = 80.0,
         on_failure: Literal["block", "log"] = "block",
-        event_hook: GuardrailEventHooks | list[GuardrailEventHooks] | None = None,
+        event_hook: JudgeModeParam = None,
         default_on: bool = False,
         router_provider: "Callable[[], Router | None] | None" = None,
         **kwargs: Any,
     ) -> None:
-        _event_hook: GuardrailEventHooks | list[GuardrailEventHooks] | None = None
-        if event_hook is not None:
-            if isinstance(event_hook, list):
-                _event_hook = [GuardrailEventHooks(h) if isinstance(h, str) else h for h in event_hook]
-            else:
-                _event_hook = GuardrailEventHooks(event_hook) if isinstance(event_hook, str) else event_hook
-
         super().__init__(
             guardrail_name=guardrail_name,
             supported_event_hooks=list(self.get_supported_event_hooks()),
-            event_hook=_event_hook or GuardrailEventHooks.post_call,
+            event_hook=_coerce_event_hook(event_hook),
             default_on=default_on,
             **kwargs,
         )
@@ -302,10 +307,7 @@ def initialize_guardrail(
 
     overall_threshold: Final = float(_get_litellm_param(litellm_params, guardrail, "overall_threshold", 80.0))
 
-    mode: Final[str | None] = _get_litellm_param(litellm_params, guardrail, "mode", None)
-    event_hook: GuardrailEventHooks | None = None
-    if isinstance(mode, str) and mode in {e.value for e in GuardrailEventHooks}:
-        event_hook = GuardrailEventHooks(mode)
+    mode: Final[JudgeModeParam] = _get_litellm_param(litellm_params, guardrail, "mode", None)
 
     instance: Final = LLMAsAJudgeGuardrail(
         guardrail_name=guardrail_name,
@@ -313,7 +315,7 @@ def initialize_guardrail(
         criteria=criteria,
         overall_threshold=overall_threshold,
         on_failure=on_failure,
-        event_hook=event_hook,
+        event_hook=mode,
         default_on=bool(_get_litellm_param(litellm_params, guardrail, "default_on", False)),
     )
     litellm.logging_callback_manager.add_litellm_callback(instance)
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index dd42e137ba0..cab24514844 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -14,7 +14,7 @@ from litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge import (
     _parse_judge_verdict,
     initialize_guardrail,
 )
-from litellm.types.guardrails import GuardrailEventHooks
+from litellm.types.guardrails import GuardrailEventHooks, Mode
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -137,6 +137,37 @@ def test_initialize_guardrail_invalid_on_failure():
         initialize_guardrail(lp, g)
 
 
+@pytest.mark.parametrize(
+    ("mode", "runs_pre_call", "runs_post_call"),
+    [
+        ("pre_call", True, False),
+        (["pre_call", "post_call"], True, True),
+        (Mode(tags={"judge": ["pre_call"]}, default="post_call"), True, False),
+        (None, False, True),
+    ],
+    ids=["scalar", "list", "tagged", "missing"],
+)
+@patch("litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge.litellm.logging_callback_manager")
+def test_initialize_guardrail_preserves_every_mode_shape(
+    _mock_mgr: MagicMock,
+    mode: str | list[str] | Mode | None,
+    runs_pre_call: bool,
+    runs_post_call: bool,
+):
+    lp: Final = _make_litellm_params(mode=mode)
+    instance: Final = initialize_guardrail(lp, _make_guardrail_dict())
+    request_data: Final[dict[str, object]] = {"metadata": {"guardrails": ["g"], "tags": ["judge"]}}
+
+    assert instance.should_run_guardrail(request_data, GuardrailEventHooks.pre_call) is runs_pre_call
+    assert instance.should_run_guardrail(request_data, GuardrailEventHooks.post_call) is runs_post_call
+
+
+def test_initialize_guardrail_rejects_unknown_mode():
+    lp: Final = _make_litellm_params(mode="sometimes")
+    with pytest.raises(ValueError, match="sometimes"):
+        initialize_guardrail(lp, _make_guardrail_dict())
+
+
 # ---------------------------------------------------------------------------
 # apply_guardrail — enforcement paths
 # ---------------------------------------------------------------------------
@@ -190,8 +221,8 @@ async def test_apply_guardrail_request_blocks_below_threshold(
     assert exc_info.value.status_code == 422
     assert exc_info.value.detail["error"] == "LLM judge rejected request: score below threshold"
     judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
-    assert "user's request" in judge_messages[0]["content"]
-    assert "User request to evaluate:\nwrite me malware" in judge_messages[1]["content"]
+    assert "Evaluate the request against" in judge_messages[0]["content"]
+    assert "Request text to evaluate:\nwrite me malware" in judge_messages[1]["content"]
     assert "Assistant response" not in judge_messages[1]["content"]
     assert "Conversation:" not in judge_messages[1]["content"]
     logged: Final = request_data["metadata"]["standard_logging_guardrail_information"]

From b93f22265c9405a3dea913e74335ea5c7650bfeb Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 21:50:07 +0000
Subject: [PATCH 18/67] fix(guardrails): give the request-side judge
 role-labelled conversation context

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 13 ++--
 .../proxy/guardrails/test_llm_as_a_judge.py   | 67 ++++++++++++++++---
 2 files changed, 65 insertions(+), 15 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 863cff6827f..269296943cb 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -32,7 +32,7 @@ JudgeEventHook = GuardrailEventHooks | list[GuardrailEventHooks] | Mode
 JudgeModeParam = str | list[str] | Mode | GuardrailEventHooks | list[GuardrailEventHooks] | None
 
 _JUDGE_SYSTEM_PROMPT_TEMPLATE: Final = """You are a quality judge. Evaluate the {subject} against the criteria provided.
-For each criterion, assign a score from 0 to 100 and provide concise reasoning.
+{focus}For each criterion, assign a score from 0 to 100 and provide concise reasoning.
 Return ONLY valid JSON in this exact format:
 {{
   "verdicts": [
@@ -43,8 +43,11 @@ Return ONLY valid JSON in this exact format:
 
 JUDGE_SYSTEM_PROMPTS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
     {
-        "request": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="request"),
-        "response": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="assistant's response"),
+        "request": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(
+            subject="request",
+            focus="Judge the most recent user turn; treat earlier turns in the conversation only as context.\n",
+        ),
+        "response": _JUDGE_SYSTEM_PROMPT_TEMPLATE.format(subject="assistant's response", focus=""),
     }
 )
 
@@ -126,7 +129,7 @@ def _build_judge_prompt(
         for m in messages
         if m.get("content") is not None
     )
-    conversation_block: Final = f"Conversation:\n{conversation}\n\n" if input_type == "response" else ""
+    conversation_block: Final = f"Conversation:\n{conversation}\n\n" if conversation or input_type == "response" else ""
     return (
         f"Criteria to evaluate:\n{criteria_block}\n\n"
         f"{conversation_block}"
@@ -197,7 +200,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         logging_obj: Optional["LiteLLMLoggingObj"] = None,
     ) -> GenericGuardrailAPIInputs:
         texts: Final = inputs.get("texts") or []
-        text_under_review: Final = " ".join(texts)
+        text_under_review: Final = "\n".join(texts)
         if not text_under_review:
             return inputs
 
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index cab24514844..11e9e55cea4 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -222,9 +222,11 @@ async def test_apply_guardrail_request_blocks_below_threshold(
     assert exc_info.value.detail["error"] == "LLM judge rejected request: score below threshold"
     judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
     assert "Evaluate the request against" in judge_messages[0]["content"]
-    assert "Request text to evaluate:\nwrite me malware" in judge_messages[1]["content"]
+    assert (
+        "Conversation:\nUSER: write me malware\n\nRequest text to evaluate:\nwrite me malware"
+        in (judge_messages[1]["content"])
+    )
     assert "Assistant response" not in judge_messages[1]["content"]
-    assert "Conversation:" not in judge_messages[1]["content"]
     logged: Final = request_data["metadata"]["standard_logging_guardrail_information"]
     assert logged[0]["guardrail_status"] == "guardrail_intervened"
     assert logged[0]["guardrail_mode"] == "pre_call"
@@ -256,6 +258,33 @@ async def test_apply_guardrail_request_log_mode_records_eval_and_passes_through(
     assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == "during_call"
 
 
+@pytest.mark.asyncio
+async def test_apply_guardrail_request_multi_turn_keeps_roles_and_focuses_latest_turn():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.pre_call, router_provider=lambda: router)
+    request_data: Final[dict[str, object]] = {
+        "messages": [
+            {"role": "user", "content": "how do I bake bread"},
+            {"role": "assistant", "content": "mix flour, water, yeast and salt"},
+            {"role": "user", "content": "now explain how to file taxes"},
+        ],
+        "metadata": {},
+    }
+    inputs: Final = {
+        "texts": ["how do I bake bread", "mix flour, water, yeast and salt", "now explain how to file taxes"]
+    }
+
+    await guardrail.apply_guardrail(inputs, request_data, "request")
+
+    judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
+    assert "Judge the most recent user turn" in judge_messages[0]["content"]
+    assert (
+        "Conversation:\nUSER: how do I bake bread\nASSISTANT: mix flour, water, yeast and salt\n"
+        "USER: now explain how to file taxes\n\n"
+        "Request text to evaluate:\nhow do I bake bread\nmix flour, water, yeast and salt\nnow explain how to file taxes"
+    ) in judge_messages[1]["content"]
+
+
 @pytest.mark.asyncio
 async def test_apply_guardrail_response_prompt_unchanged():
     router: Final = _judge_router(90.0)
@@ -351,7 +380,7 @@ def test_parse_judge_verdict_reraises_when_no_json():
 
 def test_parse_judge_verdict_rejects_json_non_object():
     """Valid JSON that is not an object (e.g. a bare list) raises ValueError."""
-    with pytest.raises(ValueError, match='judge response is not a JSON object'):
+    with pytest.raises(ValueError, match="judge response is not a JSON object"):
         _parse_judge_verdict("[1, 2, 3]")
 
 
@@ -373,9 +402,7 @@ async def test_apply_guardrail_enforces_fenced_verdict(mock_completion):
 @patch("litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge.litellm.acompletion")
 async def test_apply_guardrail_non_object_verdict_fails_open_with_status(mock_completion):
     """A non-object verdict fails open and logs guardrail_failed_to_respond."""
-    mock_completion.return_value = MagicMock(
-        choices=[MagicMock(message=MagicMock(content='[{"overall_score": 50}]'))]
-    )
+    mock_completion.return_value = MagicMock(choices=[MagicMock(message=MagicMock(content='[{"overall_score": 50}]'))])
     guardrail = _make_guardrail(overall_threshold=80.0, on_failure="block", router_provider=lambda: None)
     inputs = {"texts": ["response"]}
     request_data: dict = {"messages": [], "metadata": {}}
@@ -435,7 +462,12 @@ def _real_router(model_list, **router_kwargs):
     "model_list, router_kwargs, judge_model",
     [
         (
-            [{"model_name": "my-judge-alias", "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"}}],
+            [
+                {
+                    "model_name": "my-judge-alias",
+                    "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"},
+                }
+            ],
             {},
             "my-judge-alias",
         ),
@@ -445,12 +477,22 @@ def _real_router(model_list, **router_kwargs):
             "anthropic/claude-sonnet-4-6",
         ),
         (
-            [{"model_name": "backing-group", "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"}}],
+            [
+                {
+                    "model_name": "backing-group",
+                    "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"},
+                }
+            ],
             {"model_group_alias": {"my-judge-alias": "backing-group"}},
             "my-judge-alias",
         ),
         (
-            [{"model_name": "backing-group", "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"}}],
+            [
+                {
+                    "model_name": "backing-group",
+                    "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"},
+                }
+            ],
             {"model_group_alias": {"my-judge-alias": {"model": "backing-group", "hidden": True}}},
             "my-judge-alias",
         ),
@@ -533,7 +575,12 @@ async def test_judge_resolves_router_lazily_per_call(mock_sdk_completion):
     mock_sdk_completion.assert_awaited_once()
 
     holder["router"] = _real_router(
-        [{"model_name": "my-judge-alias", "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"}}]
+        [
+            {
+                "model_name": "my-judge-alias",
+                "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "api_key": "sk-ant-test"},
+            }
+        ]
     )
     await guardrail.apply_guardrail({"texts": ["r"]}, {"messages": [], "metadata": {}}, "response")
     holder["router"].acompletion.assert_awaited_once()

From 28bd00a004fca77f1608f8d42f07e136a0b14b2e Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 21:53:20 +0000
Subject: [PATCH 19/67] fix(guardrails): label llm_as_a_judge logging_only
 verdicts with their mode

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../guardrail_hooks/llm_as_a_judge/__init__.py |  2 ++
 .../proxy/guardrails/test_llm_as_a_judge.py    | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 269296943cb..9f0c7476b4c 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -277,6 +277,8 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
             )
 
     def _event_type_for(self, input_type: JudgeInputType) -> GuardrailEventHooks:
+        if self._event_hook_is_event_type(GuardrailEventHooks.logging_only):
+            return GuardrailEventHooks.logging_only
         if input_type == "response":
             return GuardrailEventHooks.post_call
         if self._event_hook_is_event_type(GuardrailEventHooks.pre_call):
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index 11e9e55cea4..fc877b323e0 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -285,6 +285,24 @@ async def test_apply_guardrail_request_multi_turn_keeps_roles_and_focuses_latest
     ) in judge_messages[1]["content"]
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("input_type", ["request", "response"])
+async def test_apply_guardrail_logging_only_labels_both_sides_logging_only(input_type: str):
+    router: Final = _judge_router(50.0)
+    guardrail: Final = _make_guardrail(
+        on_failure="log",
+        event_hook=GuardrailEventHooks.logging_only,
+        router_provider=lambda: router,
+    )
+    request_data: Final[dict[str, object]] = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
+
+    assert guardrail.should_run_guardrail(request_data, GuardrailEventHooks.pre_call) is False
+    assert guardrail.should_run_guardrail(request_data, GuardrailEventHooks.post_call) is False
+    await guardrail.apply_guardrail({"texts": ["hi"]}, request_data, input_type)
+
+    assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == "logging_only"
+
+
 @pytest.mark.asyncio
 async def test_apply_guardrail_response_prompt_unchanged():
     router: Final = _judge_router(90.0)

From 4d1330ea0b30fe50843a0d2e60c956905a4825c7 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 22:00:12 +0000
Subject: [PATCH 20/67] test(guardrails): drop callback-manager patch from
 llm_as_a_judge mode-shape test

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../proxy/guardrails/test_llm_as_a_judge.py           | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index fc877b323e0..21f58bcee4b 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -7,6 +7,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 from fastapi import HTTPException
 
+import litellm
 from litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge import (
     LLMAsAJudgeGuardrail,
     _build_judge_prompt,
@@ -147,9 +148,7 @@ def test_initialize_guardrail_invalid_on_failure():
     ],
     ids=["scalar", "list", "tagged", "missing"],
 )
-@patch("litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge.litellm.logging_callback_manager")
 def test_initialize_guardrail_preserves_every_mode_shape(
-    _mock_mgr: MagicMock,
     mode: str | list[str] | Mode | None,
     runs_pre_call: bool,
     runs_post_call: bool,
@@ -157,9 +156,11 @@ def test_initialize_guardrail_preserves_every_mode_shape(
     lp: Final = _make_litellm_params(mode=mode)
     instance: Final = initialize_guardrail(lp, _make_guardrail_dict())
     request_data: Final[dict[str, object]] = {"metadata": {"guardrails": ["g"], "tags": ["judge"]}}
-
-    assert instance.should_run_guardrail(request_data, GuardrailEventHooks.pre_call) is runs_pre_call
-    assert instance.should_run_guardrail(request_data, GuardrailEventHooks.post_call) is runs_post_call
+    try:
+        assert instance.should_run_guardrail(request_data, GuardrailEventHooks.pre_call) is runs_pre_call
+        assert instance.should_run_guardrail(request_data, GuardrailEventHooks.post_call) is runs_post_call
+    finally:
+        litellm.logging_callback_manager.remove_callback_from_all_lists(instance)
 
 
 def test_initialize_guardrail_rejects_unknown_mode():

From a658f200050f765325fbc2f1c5f3c046506c457e Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 22:14:24 +0000
Subject: [PATCH 21/67] test(guardrails): grant premium_user for the tagged
 Mode case in llm_as_a_judge mode-shape test

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index 21f58bcee4b..2c121022cd2 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -156,9 +156,11 @@ def test_initialize_guardrail_preserves_every_mode_shape(
     lp: Final = _make_litellm_params(mode=mode)
     instance: Final = initialize_guardrail(lp, _make_guardrail_dict())
     request_data: Final[dict[str, object]] = {"metadata": {"guardrails": ["g"], "tags": ["judge"]}}
+    premium: Final = patch("litellm.proxy.proxy_server.premium_user", True)  # test-quality-ok: no seam for Mode tags
     try:
-        assert instance.should_run_guardrail(request_data, GuardrailEventHooks.pre_call) is runs_pre_call
-        assert instance.should_run_guardrail(request_data, GuardrailEventHooks.post_call) is runs_post_call
+        with premium:
+            assert instance.should_run_guardrail(request_data, GuardrailEventHooks.pre_call) is runs_pre_call
+            assert instance.should_run_guardrail(request_data, GuardrailEventHooks.post_call) is runs_post_call
     finally:
         litellm.logging_callback_manager.remove_callback_from_all_lists(instance)
 

From e9357d9a6f1326852de2bb0c7db48deba1fb9cd8 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 22:41:04 +0000
Subject: [PATCH 22/67] fix(guardrails): stop logging_only llm_as_a_judge from
 judging its own judge calls

Judge sub-calls now carry the internal_call_origin metadata stamp and the
guardrail skips any logged call bearing it, so a logging_only judge no longer
recurses into an unbounded chain of judge requests

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 31 +++++++++++++++++--
 litellm/types/utils.py                        |  2 ++
 .../proxy/guardrails/test_llm_as_a_judge.py   | 16 ++++++++++
 3 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 9f0c7476b4c..d00bf86ed2b 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -1,15 +1,17 @@
 """LLM-as-a-Judge guardrail: uses an LLM to score requests or responses against weighted criteria."""
 
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from datetime import datetime
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, Generic, Literal, Optional, TypeVar
 
 from fastapi import HTTPException
+from pydantic import BaseModel, ConfigDict, ValidationError
 from typing_extensions import NotRequired, ReadOnly, TypedDict
 
 import litellm
 from litellm._logging import verbose_logger
+from litellm.constants import INTERNAL_CALL_ORIGIN_METADATA_KEY
 from litellm.integrations.custom_guardrail import CustomGuardrail
 from litellm.litellm_core_utils.llm_judge import (
     default_router_provider,
@@ -18,7 +20,7 @@ from litellm.litellm_core_utils.llm_judge import (
     parse_json_verdict,
 )
 from litellm.types.guardrails import GuardrailEventHooks, Mode, SupportedGuardrailIntegrations
-from litellm.types.utils import GenericGuardrailAPIInputs, GuardrailStatus
+from litellm.types.utils import LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN, GenericGuardrailAPIInputs, GuardrailStatus
 
 if TYPE_CHECKING:
     from litellm import Router
@@ -57,6 +59,25 @@ _JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingPro
 
 _VALID_ON_FAILURE: Final = frozenset({"block", "log"})
 
+_JUDGE_CALL_METADATA: Final = MappingProxyType(
+    {INTERNAL_CALL_ORIGIN_METADATA_KEY: LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN}
+)
+
+
+class _LoggedCallParams(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    metadata: Mapping[str, object] | None = None
+
+
+def _is_judge_call(data: Mapping[str, object]) -> bool:
+    try:
+        params: Final = _LoggedCallParams.model_validate(data.get("litellm_params") or {})
+    except ValidationError:
+        return False
+    return (params.metadata or {}).get(INTERNAL_CALL_ORIGIN_METADATA_KEY) == LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN
+
+
 _default_router_provider: Final = default_router_provider
 _parse_judge_verdict: Final = parse_json_verdict
 _extract_text_from_content: Final = extract_text_from_content
@@ -169,6 +190,11 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
     def get_supported_event_hooks(cls) -> list[GuardrailEventHooks]:
         return [GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call, GuardrailEventHooks.post_call]
 
+    def should_run_guardrail(self, data: Mapping[str, object], event_type: GuardrailEventHooks) -> bool:
+        if _is_judge_call(data):
+            return False
+        return super().should_run_guardrail(data, event_type)
+
     async def _run_judge(
         self,
         messages: Sequence[JudgeMessage],
@@ -188,6 +214,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
             judge_messages,
             response_format={"type": "json_object"},
             temperature=0,
+            metadata=dict(_JUDGE_CALL_METADATA),
         )
         raw: Final = response.choices[0].message.content or "{}"
         return _parse_judge_verdict(raw)
diff --git a/litellm/types/utils.py b/litellm/types/utils.py
index 298c30bbec2..aaa16fd2d44 100644
--- a/litellm/types/utils.py
+++ b/litellm/types/utils.py
@@ -2957,6 +2957,7 @@ InternalCallOrigin = Literal[
     "autorouter_classifier",
     "shadow_eval_router",
     "shadow_eval_judge",
+    "llm_as_a_judge_guardrail",
     "background_response_cost_poll",
 ]
 """Which internal litellm feature originated a billed sub-call, so a spend log row
@@ -2965,6 +2966,7 @@ records that it is not traffic the caller sent."""
 AUTOROUTER_CLASSIFIER_CALL_ORIGIN: Final[InternalCallOrigin] = "autorouter_classifier"
 SHADOW_EVAL_ROUTER_CALL_ORIGIN: Final[InternalCallOrigin] = "shadow_eval_router"
 SHADOW_EVAL_JUDGE_CALL_ORIGIN: Final[InternalCallOrigin] = "shadow_eval_judge"
+LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN: Final[InternalCallOrigin] = "llm_as_a_judge_guardrail"
 BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN: Final[InternalCallOrigin] = "background_response_cost_poll"
 
 
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index 2c121022cd2..643ccaa75f2 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -306,6 +306,22 @@ async def test_apply_guardrail_logging_only_labels_both_sides_logging_only(input
     assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == "logging_only"
 
 
+@pytest.mark.asyncio
+async def test_logging_only_judge_does_not_judge_its_own_judge_call():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.logging_only, router_provider=lambda: router)
+    client_call: Final[dict[str, object]] = {"litellm_params": {"metadata": {"user_api_key": "hashed"}}}
+
+    assert guardrail.should_run_guardrail(client_call, GuardrailEventHooks.logging_only) is True
+    await guardrail.apply_guardrail({"texts": ["hi"]}, {"messages": [{"role": "user", "content": "hi"}]}, "request")
+
+    judge_call: Final[dict[str, object]] = {
+        "litellm_params": {"metadata": router.acompletion.call_args.kwargs["metadata"]}
+    }
+    assert guardrail.should_run_guardrail(judge_call, GuardrailEventHooks.logging_only) is False
+    assert guardrail.should_run_guardrail(client_call, GuardrailEventHooks.logging_only) is True
+
+
 @pytest.mark.asyncio
 async def test_apply_guardrail_response_prompt_unchanged():
     router: Final = _judge_router(90.0)

From 1b8b17cc8a911e31be0522d8ab57e647e80069bc Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Mon, 14 Sep 2026 23:54:15 +0000
Subject: [PATCH 23/67] fix(guardrails): judge only the latest request turn in
 pre_call and during_call llm_as_a_judge

The request-side prompt told the judge to focus on the most recent user turn but the text under review was every extracted request message joined together, so a multi-turn request with an off-topic earlier turn and an on-topic latest turn scored 50 and was blocked. Request-side judging now evaluates the last extracted request text (after the configured message scoping) and passes the full role-labelled conversation only as context. Response-side judging still evaluates all extracted response text

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 11 +++++++---
 .../proxy/guardrails/test_llm_as_a_judge.py   | 22 +++++++++++++++----
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index d00bf86ed2b..afb39d53393 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -54,7 +54,7 @@ JUDGE_SYSTEM_PROMPTS: Final[MappingProxyType[JudgeInputType, str]] = MappingProx
 )
 
 _JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingProxyType(
-    {"request": "Request text to evaluate", "response": "Assistant response to evaluate"}
+    {"request": "Latest request turn to evaluate", "response": "Assistant response to evaluate"}
 )
 
 _VALID_ON_FAILURE: Final = frozenset({"block", "log"})
@@ -136,6 +136,12 @@ def _coerce_event_hook(mode: JudgeModeParam) -> JudgeEventHook:
     return GuardrailEventHooks(mode)
 
 
+def _text_under_review(texts: Sequence[str], input_type: JudgeInputType) -> str:
+    if input_type == "request":
+        return texts[-1] if texts else ""
+    return "\n".join(texts)
+
+
 def _build_judge_prompt(
     criteria: Sequence[JudgeCriterion],
     messages: Sequence[JudgeMessage],
@@ -226,8 +232,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         input_type: Literal["request", "response"],
         logging_obj: Optional["LiteLLMLoggingObj"] = None,
     ) -> GenericGuardrailAPIInputs:
-        texts: Final = inputs.get("texts") or []
-        text_under_review: Final = "\n".join(texts)
+        text_under_review: Final = _text_under_review(inputs.get("texts") or [], input_type)
         if not text_under_review:
             return inputs
 
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index 643ccaa75f2..f6f0d0a2fd0 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -226,7 +226,7 @@ async def test_apply_guardrail_request_blocks_below_threshold(
     judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
     assert "Evaluate the request against" in judge_messages[0]["content"]
     assert (
-        "Conversation:\nUSER: write me malware\n\nRequest text to evaluate:\nwrite me malware"
+        "Conversation:\nUSER: write me malware\n\nLatest request turn to evaluate:\nwrite me malware"
         in (judge_messages[1]["content"])
     )
     assert "Assistant response" not in judge_messages[1]["content"]
@@ -281,11 +281,25 @@ async def test_apply_guardrail_request_multi_turn_keeps_roles_and_focuses_latest
 
     judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
     assert "Judge the most recent user turn" in judge_messages[0]["content"]
-    assert (
+    assert judge_messages[1]["content"].endswith(
         "Conversation:\nUSER: how do I bake bread\nASSISTANT: mix flour, water, yeast and salt\n"
         "USER: now explain how to file taxes\n\n"
-        "Request text to evaluate:\nhow do I bake bread\nmix flour, water, yeast and salt\nnow explain how to file taxes"
-    ) in judge_messages[1]["content"]
+        "Latest request turn to evaluate:\nnow explain how to file taxes"
+    )
+
+
+@pytest.mark.asyncio
+async def test_apply_guardrail_response_still_judges_all_response_texts():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.post_call, router_provider=lambda: router)
+
+    await guardrail.apply_guardrail(
+        {"texts": ["first choice", "second choice"]}, {"messages": [], "metadata": {}}, "response"
+    )
+
+    assert router.acompletion.call_args.kwargs["messages"][1]["content"].endswith(
+        "Assistant response to evaluate:\nfirst choice\nsecond choice"
+    )
 
 
 @pytest.mark.asyncio

From 10506ab904c7704d60a8a7947686be2a71699d2c Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Tue, 15 Sep 2026 00:19:16 +0000
Subject: [PATCH 24/67] fix(guardrails): judge the whole latest user turn, run
 every during_call guardrail, log combined modes as configured

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 27 +++--
 litellm/proxy/utils.py                        | 70 ++++++++-----
 .../proxy/guardrails/test_llm_as_a_judge.py   | 98 +++++++++++++++++--
 .../proxy_logging/test_guardrail_pipeline.py  | 30 ++++++
 4 files changed, 178 insertions(+), 47 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index afb39d53393..4c047dbc988 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -19,6 +19,7 @@ from litellm.litellm_core_utils.llm_judge import (
     judge_acompletion,
     parse_json_verdict,
 )
+from litellm.litellm_core_utils.prompt_templates.common_utils import get_last_user_message
 from litellm.types.guardrails import GuardrailEventHooks, Mode, SupportedGuardrailIntegrations
 from litellm.types.utils import LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN, GenericGuardrailAPIInputs, GuardrailStatus
 
@@ -57,6 +58,8 @@ _JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingPro
     {"request": "Latest request turn to evaluate", "response": "Assistant response to evaluate"}
 )
 
+_REQUEST_EVENT_HOOKS: Final = (GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call)
+
 _VALID_ON_FAILURE: Final = frozenset({"block", "log"})
 
 _JUDGE_CALL_METADATA: Final = MappingProxyType(
@@ -136,10 +139,12 @@ def _coerce_event_hook(mode: JudgeModeParam) -> JudgeEventHook:
     return GuardrailEventHooks(mode)
 
 
-def _text_under_review(texts: Sequence[str], input_type: JudgeInputType) -> str:
-    if input_type == "request":
-        return texts[-1] if texts else ""
-    return "\n".join(texts)
+def _text_under_review(inputs: GenericGuardrailAPIInputs, input_type: JudgeInputType) -> str:
+    all_text: Final = "\n".join(inputs.get("texts") or [])
+    if input_type == "response":
+        return all_text
+    latest_user_turn: Final = get_last_user_message(inputs.get("structured_messages") or [])
+    return latest_user_turn if latest_user_turn is not None else all_text
 
 
 def _build_judge_prompt(
@@ -232,7 +237,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         input_type: Literal["request", "response"],
         logging_obj: Optional["LiteLLMLoggingObj"] = None,
     ) -> GenericGuardrailAPIInputs:
-        text_under_review: Final = _text_under_review(inputs.get("texts") or [], input_type)
+        text_under_review: Final = _text_under_review(inputs, input_type)
         if not text_under_review:
             return inputs
 
@@ -241,7 +246,9 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         judge_result: dict[str, object] = {}
 
         try:
-            messages: Final[Sequence[JudgeMessage]] = request_data.get("messages") or []
+            messages: Final[Sequence[JudgeMessage]] = (
+                inputs.get("structured_messages") or request_data.get("messages") or []
+            )
 
             try:
                 judge_result = await self._run_judge(messages, text_under_review, input_type)
@@ -308,14 +315,14 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
                 event_type=self._event_type_for(input_type),
             )
 
-    def _event_type_for(self, input_type: JudgeInputType) -> GuardrailEventHooks:
+    def _event_type_for(self, input_type: JudgeInputType) -> GuardrailEventHooks | None:
+        """Returns None (log the configured mode as-is) when the active request hook is ambiguous."""
         if self._event_hook_is_event_type(GuardrailEventHooks.logging_only):
             return GuardrailEventHooks.logging_only
         if input_type == "response":
             return GuardrailEventHooks.post_call
-        if self._event_hook_is_event_type(GuardrailEventHooks.pre_call):
-            return GuardrailEventHooks.pre_call
-        return GuardrailEventHooks.during_call
+        configured: Final = tuple(hook for hook in _REQUEST_EVENT_HOOKS if self._event_hook_is_event_type(hook))
+        return configured[0] if len(configured) == 1 else None
 
 
 def initialize_guardrail(
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index b6c487c0edf..23eb6cc2e87 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -2669,34 +2669,15 @@ class ProxyLogging:
                     user_api_key_auth_dict = self._convert_user_api_key_auth_to_dict(user_api_key_dict)
                 else:
                     user_api_key_auth_dict = user_api_key_dict
-                # Add task to list for parallel execution
-                if (
-                    "apply_guardrail" in type(callback).__dict__
-                    and not callback.use_native_lifecycle_hooks
-                    and user_api_key_dict is not None
-                    and not getattr(callback, "use_native_during_call_hook", False)
-                ):
-                    data["guardrail_to_apply"] = callback
-                    guardrail_task = self._run_guardrail_with_metrics(
-                        callback,
-                        unified_guardrail.async_moderation_hook(
-                            user_api_key_dict=user_api_key_dict,
-                            data=data,
-                            call_type=call_type,
-                        ),
-                        "during_call",
+                guardrail_tasks.append(
+                    self._run_during_call_guardrail(
+                        callback=callback,
+                        data=data,
+                        user_api_key_dict=user_api_key_dict,
+                        user_api_key_auth_dict=user_api_key_auth_dict,
+                        call_type=call_type,
                     )
-                else:
-                    guardrail_task = self._run_guardrail_with_metrics(
-                        callback,
-                        callback.async_moderation_hook(
-                            data=data,
-                            user_api_key_dict=user_api_key_auth_dict,
-                            call_type=call_type,
-                        ),
-                        "during_call",
-                    )
-                guardrail_tasks.append(guardrail_task)
+                )
 
         # Step 2: Run all guardrail tasks in parallel
         if guardrail_tasks:
@@ -2708,6 +2689,41 @@ class ProxyLogging:
 
         return data
 
+    async def _run_during_call_guardrail(
+        self,
+        callback: CustomGuardrail,
+        data: dict,
+        user_api_key_dict: UserAPIKeyAuth | None,
+        user_api_key_auth_dict: UserAPIKeyAuth | dict[str, object] | None,
+        call_type: CallTypesLiteral,
+    ) -> None:
+        if (
+            "apply_guardrail" in type(callback).__dict__
+            and not callback.use_native_lifecycle_hooks
+            and user_api_key_dict is not None
+            and not callback.use_native_during_call_hook
+        ):
+            data["guardrail_to_apply"] = callback
+            await self._run_guardrail_with_metrics(
+                callback,
+                unified_guardrail.async_moderation_hook(
+                    user_api_key_dict=user_api_key_dict,
+                    data=data,
+                    call_type=call_type,
+                ),
+                "during_call",
+            )
+            return
+        await self._run_guardrail_with_metrics(
+            callback,
+            callback.async_moderation_hook(
+                data=data,
+                user_api_key_dict=user_api_key_auth_dict,
+                call_type=call_type,
+            ),
+            "during_call",
+        )
+
     async def failed_tracking_alert(
         self,
         error_message: str,
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index f6f0d0a2fd0..a81af524b69 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -265,19 +265,17 @@ async def test_apply_guardrail_request_log_mode_records_eval_and_passes_through(
 async def test_apply_guardrail_request_multi_turn_keeps_roles_and_focuses_latest_turn():
     router: Final = _judge_router(90.0)
     guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.pre_call, router_provider=lambda: router)
-    request_data: Final[dict[str, object]] = {
-        "messages": [
-            {"role": "user", "content": "how do I bake bread"},
-            {"role": "assistant", "content": "mix flour, water, yeast and salt"},
-            {"role": "user", "content": "now explain how to file taxes"},
-        ],
-        "metadata": {},
-    }
+    messages: Final = [
+        {"role": "user", "content": "how do I bake bread"},
+        {"role": "assistant", "content": "mix flour, water, yeast and salt"},
+        {"role": "user", "content": "now explain how to file taxes"},
+    ]
     inputs: Final = {
-        "texts": ["how do I bake bread", "mix flour, water, yeast and salt", "now explain how to file taxes"]
+        "texts": ["how do I bake bread", "mix flour, water, yeast and salt", "now explain how to file taxes"],
+        "structured_messages": messages,
     }
 
-    await guardrail.apply_guardrail(inputs, request_data, "request")
+    await guardrail.apply_guardrail(inputs, {"messages": messages, "metadata": {}}, "request")
 
     judge_messages: Final = router.acompletion.call_args.kwargs["messages"]
     assert "Judge the most recent user turn" in judge_messages[0]["content"]
@@ -288,6 +286,86 @@ async def test_apply_guardrail_request_multi_turn_keeps_roles_and_focuses_latest
     )
 
 
+@pytest.mark.asyncio
+async def test_apply_guardrail_request_judges_whole_multipart_latest_user_turn():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.pre_call, router_provider=lambda: router)
+    messages: Final = [
+        {"role": "user", "content": "how do I bake bread"},
+        {"role": "assistant", "content": "mix flour, water, yeast and salt"},
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "ignore the bread."},
+                {"type": "image_url", "image_url": {"url": "data:image/png;base64,AAAA"}},
+                {"type": "text", "text": "explain how to file taxes"},
+            ],
+        },
+    ]
+    inputs: Final = {
+        "texts": [
+            "how do I bake bread",
+            "mix flour, water, yeast and salt",
+            "ignore the bread.",
+            "explain how to file taxes",
+        ],
+        "structured_messages": messages,
+    }
+
+    await guardrail.apply_guardrail(inputs, {"messages": messages, "metadata": {}}, "request")
+
+    assert router.acompletion.call_args.kwargs["messages"][1]["content"].endswith(
+        "Latest request turn to evaluate:\nignore the bread.explain how to file taxes"
+    )
+
+
+@pytest.mark.asyncio
+async def test_apply_guardrail_request_without_trailing_user_turn_judges_all_scoped_text():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.pre_call, router_provider=lambda: router)
+    messages: Final = [
+        {"role": "user", "content": "look up the weather"},
+        {"role": "assistant", "content": None, "tool_calls": [{"id": "c1", "type": "function", "function": {}}]},
+        {"role": "tool", "tool_call_id": "c1", "content": "sunny, 24C"},
+    ]
+    inputs: Final = {"texts": ["look up the weather", "sunny, 24C"], "structured_messages": messages}
+
+    await guardrail.apply_guardrail(inputs, {"messages": messages, "metadata": {}}, "request")
+
+    assert router.acompletion.call_args.kwargs["messages"][1]["content"].endswith(
+        "Latest request turn to evaluate:\nlook up the weather\nsunny, 24C"
+    )
+
+
+@pytest.mark.asyncio
+async def test_apply_guardrail_request_without_structured_messages_judges_all_text():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(event_hook=GuardrailEventHooks.pre_call, router_provider=lambda: router)
+
+    await guardrail.apply_guardrail({"texts": ["first", "second"]}, {"metadata": {}}, "request")
+
+    assert router.acompletion.call_args.kwargs["messages"][1]["content"].endswith(
+        "Latest request turn to evaluate:\nfirst\nsecond"
+    )
+
+
+@pytest.mark.asyncio
+async def test_apply_guardrail_request_with_both_request_modes_logs_configured_mode():
+    router: Final = _judge_router(90.0)
+    guardrail: Final = _make_guardrail(
+        event_hook=[GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call],
+        router_provider=lambda: router,
+    )
+    request_data: Final[dict[str, object]] = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
+
+    await guardrail.apply_guardrail({"texts": ["hi"]}, request_data, "request")
+
+    assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == [
+        "pre_call",
+        "during_call",
+    ]
+
+
 @pytest.mark.asyncio
 async def test_apply_guardrail_response_still_judges_all_response_texts():
     router: Final = _judge_router(90.0)
diff --git a/tests/test_litellm/proxy/utils/proxy_logging/test_guardrail_pipeline.py b/tests/test_litellm/proxy/utils/proxy_logging/test_guardrail_pipeline.py
index dfe106a3f52..077bf5a313e 100644
--- a/tests/test_litellm/proxy/utils/proxy_logging/test_guardrail_pipeline.py
+++ b/tests/test_litellm/proxy/utils/proxy_logging/test_guardrail_pipeline.py
@@ -689,6 +689,36 @@ async def test_during_call_hook_records_latency_metric(proxy_logging, make_user_
     assert recorded["status"] == "success"
 
 
+class _RecordingApplyGuardrail(CustomGuardrail):
+    def __init__(self, guardrail_name: str, applied: list[str]) -> None:
+        super().__init__(
+            guardrail_name=guardrail_name,
+            event_hook=GuardrailEventHooks.during_call,
+            default_on=True,
+        )
+        self._applied = applied
+
+    async def apply_guardrail(self, inputs, request_data, input_type, logging_obj=None):
+        await asyncio.sleep(0)
+        self._applied.append(self.guardrail_name or "")
+        return inputs
+
+
+@pytest.mark.asyncio
+async def test_during_call_hook_runs_every_unified_guardrail(proxy_logging, make_user_api_key_auth, monkeypatch):
+    applied: list[str] = []
+    guardrails = [_RecordingApplyGuardrail(f"judge-{i}", applied) for i in range(3)]
+    monkeypatch.setattr(litellm, "callbacks", guardrails)
+
+    await proxy_logging.during_call_hook(
+        data={"model": "m", "messages": [{"role": "user", "content": "hi"}], "metadata": {}},
+        user_api_key_dict=make_user_api_key_auth(),
+        call_type="completion",
+    )
+
+    assert sorted(applied) == ["judge-0", "judge-1", "judge-2"]
+
+
 @pytest.mark.asyncio
 async def test_post_call_success_hook_records_latency_metric(proxy_logging, make_user_api_key_auth, monkeypatch):
     cb = _moderation_guardrail()

From dd4829398a4c04d7ea8ed961d7d59d062fe66649 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Tue, 15 Sep 2026 00:23:20 +0000
Subject: [PATCH 25/67] fix(guardrails): log the configured mode when
 logging_only is mixed with an enforcing llm_as_a_judge mode

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llm_as_a_judge/__init__.py                | 14 ++++++------
 .../proxy/guardrails/test_llm_as_a_judge.py   | 22 ++++++++++++-------
 2 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 4c047dbc988..46fccc126e7 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -58,7 +58,12 @@ _JUDGE_SUBJECT_LABELS: Final[MappingProxyType[JudgeInputType, str]] = MappingPro
     {"request": "Latest request turn to evaluate", "response": "Assistant response to evaluate"}
 )
 
-_REQUEST_EVENT_HOOKS: Final = (GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call)
+_LIFECYCLE_HOOKS: Final[MappingProxyType[JudgeInputType, tuple[GuardrailEventHooks, ...]]] = MappingProxyType(
+    {
+        "request": (GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call, GuardrailEventHooks.logging_only),
+        "response": (GuardrailEventHooks.post_call, GuardrailEventHooks.logging_only),
+    }
+)
 
 _VALID_ON_FAILURE: Final = frozenset({"block", "log"})
 
@@ -316,12 +321,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
             )
 
     def _event_type_for(self, input_type: JudgeInputType) -> GuardrailEventHooks | None:
-        """Returns None (log the configured mode as-is) when the active request hook is ambiguous."""
-        if self._event_hook_is_event_type(GuardrailEventHooks.logging_only):
-            return GuardrailEventHooks.logging_only
-        if input_type == "response":
-            return GuardrailEventHooks.post_call
-        configured: Final = tuple(hook for hook in _REQUEST_EVENT_HOOKS if self._event_hook_is_event_type(hook))
+        configured: Final = tuple(hook for hook in _LIFECYCLE_HOOKS[input_type] if self._event_hook_is_event_type(hook))
         return configured[0] if len(configured) == 1 else None
 
 
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index a81af524b69..1646f730984 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -350,19 +350,25 @@ async def test_apply_guardrail_request_without_structured_messages_judges_all_te
 
 
 @pytest.mark.asyncio
-async def test_apply_guardrail_request_with_both_request_modes_logs_configured_mode():
+@pytest.mark.parametrize(
+    ("modes", "input_type"),
+    [
+        ([GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call], "request"),
+        ([GuardrailEventHooks.pre_call, GuardrailEventHooks.logging_only], "request"),
+        ([GuardrailEventHooks.post_call, GuardrailEventHooks.logging_only], "response"),
+    ],
+)
+async def test_apply_guardrail_with_ambiguous_modes_logs_configured_mode(
+    modes: list[GuardrailEventHooks], input_type: str
+):
     router: Final = _judge_router(90.0)
-    guardrail: Final = _make_guardrail(
-        event_hook=[GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call],
-        router_provider=lambda: router,
-    )
+    guardrail: Final = _make_guardrail(event_hook=modes, router_provider=lambda: router)
     request_data: Final[dict[str, object]] = {"messages": [{"role": "user", "content": "hi"}], "metadata": {}}
 
-    await guardrail.apply_guardrail({"texts": ["hi"]}, request_data, "request")
+    await guardrail.apply_guardrail({"texts": ["hi"]}, request_data, input_type)
 
     assert request_data["metadata"]["standard_logging_guardrail_information"][0]["guardrail_mode"] == [
-        "pre_call",
-        "during_call",
+        mode.value for mode in modes
     ]
 
 

From 801f6a92b4a2d0e55daa738ff9fd3db0098382c6 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:05:53 +0000
Subject: [PATCH 26/67] test(gemini): assert the served modelVersion reaches
 the assembled stream through CustomStreamWrapper

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ...test_vertex_and_google_ai_studio_gemini.py | 39 +++++++++++++++++--
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
index 29a47cd54f2..3fb00a7d962 100644
--- a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
+++ b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
@@ -5892,9 +5892,42 @@ def test_streaming_chunk_carries_model_version():
     )
 
     chunk = {**_generate_content_body(), "modelVersion": "gemini-x-served"}
-    iterator: Final = ModelResponseIterator(
-        streaming_response=[], sync_stream=True, logging_obj=MagicMock()
-    )
+    iterator: Final = ModelResponseIterator(streaming_response=[], sync_stream=True, logging_obj=MagicMock())
     streaming_chunk: Final = iterator.chunk_parser(chunk)
 
     assert streaming_chunk.model == "gemini-x-served"
+
+
+def test_served_model_version_reaches_assembled_stream_through_custom_stream_wrapper():
+    """Greptile claimed CustomStreamWrapper drops the served modelVersion before
+    pricing. It does not: chunk_creator stashes the parser chunk's model into each
+    yielded chunk's _hidden_params["provider_response_model"], and
+    stream_chunk_builder carries it onto the assembled response. The wrapper's
+    trailing bookkeeping chunk is the one emission that legitimately omits it."""
+    from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
+    from litellm.llms.vertex_ai.gemini.vertex_and_google_ai_studio_gemini import (
+        ModelResponseIterator,
+    )
+
+    served_model: Final = "gemini-3.8-flash-001"
+    iterator: Final = ModelResponseIterator(
+        streaming_response=iter(
+            [json.dumps({**_generate_content_body(), "modelVersion": served_model}) for _ in range(3)]
+        ),
+        sync_stream=True,
+        logging_obj=MagicMock(),
+    )
+    wrapper: Final = CustomStreamWrapper(
+        completion_stream=iter(iterator),
+        model="gemini/gemini-3.8-flash",
+        custom_llm_provider="gemini",
+        logging_obj=MagicMock(),
+    )
+
+    chunks: Final = list(wrapper)
+
+    assert len(chunks) >= 3
+    for chunk in chunks[:-1]:
+        assert chunk._hidden_params["provider_response_model"] == served_model
+    assembled: Final = litellm.stream_chunk_builder(chunks=list(chunks), messages=[{"role": "user", "content": "hi"}])
+    assert assembled._hidden_params["provider_response_model"] == served_model

From f66ffc387eac7ba3ae395348e0c5d087a349fe92 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Tue, 15 Sep 2026 01:58:24 +0000
Subject: [PATCH 27/67] fix(guardrails): only honor the judge call-origin stamp
 on logging_only in llm_as_a_judge

On pre_call, during_call and post_call the hook data is the client request body, so a
client-supplied litellm_params.metadata.internal_call_origin must not skip enforcement.
Type the during_call helper's request payload as dict[str, object]

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../guardrail_hooks/llm_as_a_judge/__init__.py   |  7 +++++--
 litellm/proxy/utils.py                           |  2 +-
 .../proxy/guardrails/test_llm_as_a_judge.py      | 16 ++++++++++++++++
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
index 46fccc126e7..8eac6b2ee53 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/llm_as_a_judge/__init__.py
@@ -78,7 +78,10 @@ class _LoggedCallParams(BaseModel):
     metadata: Mapping[str, object] | None = None
 
 
-def _is_judge_call(data: Mapping[str, object]) -> bool:
+def _is_logged_judge_call(data: Mapping[str, object], event_type: GuardrailEventHooks) -> bool:
+    """logging_only is the only event whose ``data`` is the SDK's model_call_details rather than the client body."""
+    if event_type is not GuardrailEventHooks.logging_only:
+        return False
     try:
         params: Final = _LoggedCallParams.model_validate(data.get("litellm_params") or {})
     except ValidationError:
@@ -207,7 +210,7 @@ class LLMAsAJudgeGuardrail(CustomGuardrail):
         return [GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call, GuardrailEventHooks.post_call]
 
     def should_run_guardrail(self, data: Mapping[str, object], event_type: GuardrailEventHooks) -> bool:
-        if _is_judge_call(data):
+        if _is_logged_judge_call(data, event_type):
             return False
         return super().should_run_guardrail(data, event_type)
 
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index 23eb6cc2e87..215fb143f7b 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -2692,7 +2692,7 @@ class ProxyLogging:
     async def _run_during_call_guardrail(
         self,
         callback: CustomGuardrail,
-        data: dict,
+        data: dict[str, object],  # mutable-ok: request payload dict, guardrail_to_apply is written in place
         user_api_key_dict: UserAPIKeyAuth | None,
         user_api_key_auth_dict: UserAPIKeyAuth | dict[str, object] | None,
         call_type: CallTypesLiteral,
diff --git a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
index 1646f730984..6e00958eba4 100644
--- a/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
+++ b/tests/test_litellm/proxy/guardrails/test_llm_as_a_judge.py
@@ -8,6 +8,7 @@ import pytest
 from fastapi import HTTPException
 
 import litellm
+from litellm.constants import INTERNAL_CALL_ORIGIN_METADATA_KEY
 from litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge import (
     LLMAsAJudgeGuardrail,
     _build_judge_prompt,
@@ -16,6 +17,7 @@ from litellm.proxy.guardrails.guardrail_hooks.llm_as_a_judge import (
     initialize_guardrail,
 )
 from litellm.types.guardrails import GuardrailEventHooks, Mode
+from litellm.types.utils import LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -420,6 +422,20 @@ async def test_logging_only_judge_does_not_judge_its_own_judge_call():
     assert guardrail.should_run_guardrail(client_call, GuardrailEventHooks.logging_only) is True
 
 
+@pytest.mark.parametrize(
+    "event_type", [GuardrailEventHooks.pre_call, GuardrailEventHooks.during_call, GuardrailEventHooks.post_call]
+)
+def test_client_supplied_judge_origin_does_not_bypass_enforcing_hooks(event_type: GuardrailEventHooks):
+    guardrail: Final = _make_guardrail(event_hook=event_type)
+    forged_request: Final[dict[str, object]] = {
+        "messages": [{"role": "user", "content": "hi"}],
+        "guardrails": [guardrail.guardrail_name],
+        "litellm_params": {"metadata": {INTERNAL_CALL_ORIGIN_METADATA_KEY: LLM_AS_A_JUDGE_GUARDRAIL_CALL_ORIGIN}},
+    }
+
+    assert guardrail.should_run_guardrail(forged_request, event_type) is True
+
+
 @pytest.mark.asyncio
 async def test_apply_guardrail_response_prompt_unchanged():
     router: Final = _judge_router(90.0)

From 1484fd76001fae494c31e186c079c92868ddd0c5 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:13:26 +0000
Subject: [PATCH 28/67] fix(responses): keep the usage estimate best-effort
 when token counting raises

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 20 +++++++++++++++-
 .../responses/test_streaming_iterator.py      | 24 +++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 6cb0331620f..6cf36e3e660 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -440,7 +440,7 @@ class BaseResponsesAPIStreamingIterator:
                         and _response_obj is not None
                         and _response_obj.usage is None
                     ):
-                        _response_obj.usage = _estimate_usage_from_text(
+                        _response_obj.usage = _estimate_usage_safely(
                             self.model or "",
                             self.request_data.get("input"),
                             self.request_data,
@@ -1381,6 +1381,24 @@ def _estimate_usage_from_text(
     )
 
 
+def _estimate_usage_safely(
+    model: str,
+    request_input: object,
+    responses_api_request: Mapping[str, object],
+    generated_text: str,
+) -> ResponseAPIUsage | None:
+    try:
+        return _estimate_usage_from_text(
+            model=model,
+            request_input=request_input,
+            responses_api_request=responses_api_request,
+            generated_text=generated_text,
+        )
+    except Exception as e:
+        verbose_logger.debug("Could not estimate usage from stream text, billing $0: %s", e)
+        return None
+
+
 def _stamp_responses_usage_cost(
     response_obj: ResponsesAPIResponse | None, logging_obj: LiteLLMLoggingObj | None
 ) -> None:
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index c3721353d42..234e63ca3be 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -792,3 +792,27 @@ async def test_completed_event_without_usage_counts_multimodal_input_as_messages
     usage = iterator.completed_response.response.usage
     assert usage is not None
     assert usage.input_tokens < json_count / 2
+
+
+@pytest.mark.asyncio
+async def test_completed_event_survives_a_failing_usage_estimate():
+    """A raising token_counter must not break a stream that previously completed:
+    the estimate is best-effort and falls back to usage None."""
+    response = _responses_api_response_without_usage()
+    iterator = _make_iterator(
+        sse_events=[
+            _sse_event({"type": "response.output_text.delta", "delta": "hello world"}),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=_mock_config_with_completed_response(response),
+        request_data={"input": "count these input tokens please"},
+    )
+
+    with patch.object(litellm, "token_counter", side_effect=RuntimeError("tokenizer exploded")):
+        yielded: list = []
+        async for chunk in iterator:
+            yielded.append(chunk)
+
+    assert yielded
+    assert iterator.completed_response.response.usage is None

From 4587dbeae98b798be6776e5b2a47d5eebea50705 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 18:14:12 -0700
Subject: [PATCH 29/67] feat(e2e): cache exact provider responses for 24 hours

---
 .github/workflows/test-provider-cache.yml     |  63 +++
 .../test_provider_cache.py                    | 409 ++++++++++++++++++
 tests/e2e/PROVIDER_CACHE.md                   |  27 ++
 tests/e2e/conftest.py                         |   6 +-
 tests/e2e/e2e_http.py                         |  41 +-
 .../e2e/llm_translation/test_messages_e2e.py  |   3 +-
 .../llm_translation/test_together_ai_e2e.py   |   1 +
 tests/e2e/provider_cache.py                   | 297 +++++++++++++
 tests/e2e/provider_cache_redis.py             | 154 +++++++
 tests/e2e/provider_cache_routing.py           |  23 +
 tests/e2e/provider_edge.py                    |  61 ++-
 tests/e2e/proxy_client.py                     |   8 +-
 12 files changed, 1077 insertions(+), 16 deletions(-)
 create mode 100644 .github/workflows/test-provider-cache.yml
 create mode 100644 tests/code_coverage_tests/test_provider_cache.py
 create mode 100644 tests/e2e/PROVIDER_CACHE.md
 create mode 100644 tests/e2e/provider_cache.py
 create mode 100644 tests/e2e/provider_cache_redis.py
 create mode 100644 tests/e2e/provider_cache_routing.py

diff --git a/.github/workflows/test-provider-cache.yml b/.github/workflows/test-provider-cache.yml
new file mode 100644
index 00000000000..29b9d08a267
--- /dev/null
+++ b/.github/workflows/test-provider-cache.yml
@@ -0,0 +1,63 @@
+name: Provider cache contracts
+
+on:
+  pull_request:
+    paths:
+      - 'tests/e2e/**'
+      - 'tests/code_coverage_tests/test_provider_cache.py'
+      - 'tests/code_coverage_tests/test_provider_replay_harness.py'
+      - '.github/workflows/test-provider-cache.yml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  provider-cache:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      redis:
+        image: redis@sha256:e2debfb7956fa12c7ddc79d7e645c8cf26b30c99a6e9161ea9bf4171e1668a5f
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd 'redis-cli ping'
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    env:
+      PYTHONDONTWRITEBYTECODE: '1'
+      PYTHONPATH: tests/e2e
+      E2E_CACHE_TEST_REDIS_URL: redis://127.0.0.1:6379/0
+      E2E_PROVIDER_CACHE: '0'
+      E2E_FIXTURE_MODE: live
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.13'
+      - uses: ./.github/actions/setup-uv-with-retries
+        with:
+          version: '0.10.9'
+      - uses: ./.github/actions/cache-cargo-build
+      - name: Install locked dependencies
+        run: .github/scripts/uv_sync_with_retries.sh --frozen --group proxy-dev --group e2e-dev
+      - name: Verify cache and existing edge contracts
+        run: >-
+          uv run --no-sync pytest -c /dev/null -p no:cacheprovider
+          tests/code_coverage_tests/test_provider_cache.py
+          tests/code_coverage_tests/test_provider_replay_harness.py
+          tests/e2e/test_provider_edge.py
+          -q --junitxml=provider-cache-results.xml
+      - name: Save test results
+        if: always()
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1
+        with:
+          name: provider-cache-results
+          path: provider-cache-results.xml
+          if-no-files-found: warn
diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
new file mode 100644
index 00000000000..7edca8151af
--- /dev/null
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -0,0 +1,409 @@
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import threading
+import time
+import uuid
+from collections.abc import Generator
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Final
+
+import pytest
+from e2e_http import NetworkError, PreparedForward, RawResponse, StreamChunk, StreamHead, forward, prepare_forward
+from models import LiteLLMParamsBody
+from provider_cache import CacheEdge, CacheHit, CaptureLease, exact_key, successful_response
+from provider_cache_redis import PUBLISH, RedisCommands, RedisResponseStore, configured_cache, redis_store
+from provider_cache_routing import LIVE_PROVIDER_REQUIRED, route_cache_model
+from provider_edge import configured_cache_backend, start_provider_edge
+from redis.exceptions import ConnectionError as RedisConnectionError
+
+SECRET: Final = b"synthetic-cache-hmac-key-for-tests"
+BODY: Final = b'{"model":"test","messages":[{"role":"user","content":"hello"}]}'
+SUCCESS: Final = b'{"id":"provider-fixed-id","choices":[{"message":{"content":"hello"},"finish_reason":"stop"}],"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}'
+HEADERS: Final = {"content-type": "application/json", "authorization": "Bearer synthetic-account-one"}
+
+
+class Provider(ThreadingHTTPServer):
+    hits: tuple[tuple[str, bytes], ...] = ()
+    response: bytes = SUCCESS
+    status: int = 200
+    delay: float = 0
+    stream: bool = False
+    truncated: bool = False
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def do_POST(self) -> None:
+        server: Final = self.server
+        assert isinstance(server, Provider)
+        body: Final = self.rfile.read(int(self.headers.get("content-length", "0")))
+        server.hits += ((self.path, body),)
+        time.sleep(server.delay)
+        self.send_response(server.status)
+        if server.stream:
+            self.send_header("content-type", "text/event-stream")
+            self.send_header("transfer-encoding", "chunked")
+            self.end_headers()
+            self.wfile.write(b"%x\r\n%s\r\n" % (len(server.response), server.response))
+            if server.truncated:
+                self.close_connection = True
+                return
+            self.wfile.write(b"0\r\n\r\n")
+            return
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(server.response)))
+        self.end_headers()
+        self.wfile.write(server.response)
+
+    def log_message(self, format: str, *args: object) -> None:
+        pass
+
+
+@pytest.fixture
+def provider() -> Generator[Provider, None, None]:
+    server: Final = Provider(("127.0.0.1", 0), Handler)
+    thread: Final = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield server
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+@pytest.fixture(scope="module")
+def redis_url(tmp_path_factory: pytest.TempPathFactory) -> Generator[str, None, None]:
+    configured: Final = os.environ.get("E2E_CACHE_TEST_REDIS_URL")
+    if configured:
+        yield configured
+        return
+    binary: Final = shutil.which("redis-server")
+    assert binary is not None, "Set E2E_CACHE_TEST_REDIS_URL or install Redis for cache integration checks"
+    root: Final = tmp_path_factory.mktemp("provider-cache-redis")
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        port: Final = probe.getsockname()[1]
+    with (root / "redis.log").open("wb") as log:
+        process: Final = subprocess.Popen(
+            [binary, "--bind", "127.0.0.1", "--port", str(port), "--save", "", "--appendonly", "no", "--dir", str(root)],
+            stdout=log, stderr=subprocess.STDOUT,
+        )
+        try:
+            deadline: Final = time.monotonic() + 5
+            while True:
+                try:
+                    with socket.create_connection(("127.0.0.1", port), timeout=0.1):
+                        break
+                except OSError:
+                    assert process.poll() is None and time.monotonic() < deadline
+                    time.sleep(0.02)
+            yield f"redis://127.0.0.1:{port}/0"
+        finally:
+            process.terminate()
+            process.wait(timeout=5)
+
+
+@pytest.fixture
+def store(redis_url: str) -> RedisResponseStore:
+    return redis_store(redis_url, "test-" + uuid.uuid4().hex)
+
+
+@contextmanager
+def edge(cache: CacheEdge, provider: Provider) -> Generator[str, None, None]:
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}"
+    running: Final = start_provider_edge(cache, mounts={"openai": upstream})
+    try:
+        yield running.edge.api_base("openai") + "/v1/chat/completions"
+    finally:
+        running.shutdown()
+
+
+def call(url: str, body: bytes = BODY, headers: dict[str, str] = HEADERS) -> RawResponse:
+    result: Final = forward("POST", url, headers=headers, body=body, timeout=5)
+    assert isinstance(result, RawResponse), result
+    return result
+
+
+def test_success_is_reusable_across_fresh_edges(store: RedisResponseStore, provider: Provider) -> None:
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        assert call(url).body == SUCCESS
+        assert call(url).body == SUCCESS
+    with edge(CacheEdge(store, SECRET), provider) as other:
+        assert call(other).body == SUCCESS
+    assert len(provider.hits) == 1
+
+
+@pytest.mark.parametrize("body", [BODY + b" ", BODY.replace(b"hello", b"Hello"), BODY.replace(b"test", b"test2")])
+def test_any_body_change_calls_live(store: RedisResponseStore, provider: Provider, body: bytes) -> None:
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        call(url)
+        call(url, body)
+        call(url, body)
+    assert len(provider.hits) == 2
+
+
+@pytest.mark.parametrize("name,value", [("authorization", "Bearer another-account"), ("x-request-id", "one"), ("anthropic-version", "new")])
+def test_changed_header_cannot_reuse(store: RedisResponseStore, provider: Provider, name: str, value: str) -> None:
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        call(url)
+        call(url, headers=HEADERS | {name: value})
+        call(url + "?x=1")
+    assert len(provider.hits) == 3
+
+
+@pytest.mark.parametrize("status,response", [(429, b'{"error":"rate limited"}'), (500, b'failed'), (200, b'{"error":"bad"}'), (200, b'not json')])
+def test_failed_provider_responses_never_enter_cache(store: RedisResponseStore, provider: Provider, status: int, response: bytes) -> None:
+    provider.status = status
+    provider.response = response
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        assert call(url).status_code == status
+        assert call(url).body == response
+    assert len(provider.hits) == 2
+
+
+def test_expiry_does_not_slide(store: RedisResponseStore, provider: Provider) -> None:
+    short: Final = replace(store, lifetime_ms=250)
+    with edge(CacheEdge(short, SECRET), provider) as url:
+        call(url)
+        call(url)
+        time.sleep(0.3)
+        call(url)
+        call(url)
+    assert len(provider.hits) == 2
+
+
+def test_concurrent_requests_publish_atomically(store: RedisResponseStore, provider: Provider) -> None:
+    provider.delay = 0.15
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        with ThreadPoolExecutor(max_workers=5) as executor:
+            replies: Final = tuple(executor.map(lambda _: call(url).body, range(5)))
+    assert replies == (SUCCESS,) * 5
+    assert len(provider.hits) == 1
+
+
+@pytest.mark.parametrize("truncated", [False, True])
+def test_stream_completion_controls_publication(store: RedisResponseStore, provider: Provider, truncated: bool) -> None:
+    provider.stream = True
+    provider.truncated = truncated
+    provider.response = b'data: {"choices":[{"index":0,"delta":{"content":"hello"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n'
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        for _ in range(2):
+            result: Final = forward("POST", url, headers=HEADERS, body=BODY, timeout=5)
+            if truncated:
+                assert isinstance(result, NetworkError)
+            else:
+                assert isinstance(result, RawResponse) and result.body == provider.response
+    assert len(provider.hits) == (2 if truncated else 1)
+
+
+def test_store_outage_preserves_provider_success(provider: Provider) -> None:
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        port: Final = probe.getsockname()[1]
+        unavailable: Final = redis_store(f"redis://127.0.0.1:{port}/0", "unavailable")
+        with edge(CacheEdge(unavailable, SECRET), provider) as url:
+            assert call(url).body == SUCCESS
+            assert call(url).body == SUCCESS
+    assert len(provider.hits) == 2
+
+
+def test_old_lease_cannot_overwrite_new_owner(store: RedisResponseStore) -> None:
+    short: Final = replace(store, lease_ms=50)
+    old: Final = short.lookup("key")
+    assert isinstance(old, CaptureLease)
+    time.sleep(0.08)
+    current: Final = short.lookup("key")
+    assert isinstance(current, CaptureLease)
+    assert not short.publish("key", old, b"old")
+    assert short.publish("key", current, b"new")
+    hit: Final = short.lookup("key")
+    assert isinstance(hit, CacheHit) and hit.payload == b"new"
+
+
+def test_identity_preserves_values_and_never_contains_credentials() -> None:
+    variants: Final = (b'{}', b'{"a":null}', b'{"a":false}', b'{"a":0}', b'{"a":0.0}', b'{"a":"0"}', b' { }', None, b'')
+    keys: Final = tuple(exact_key(SECRET, "POST", "https://example.invalid/v1/chat/completions", HEADERS, body) for body in variants)
+    assert len(set(keys)) == len(variants)
+    assert all(len(key) == 64 and "synthetic-account" not in key for key in keys)
+
+
+@pytest.mark.parametrize("payload", [b"corrupt response", '{"response":"{}","signature":"é"}'.encode()])
+def test_corrupt_entry_is_replaced_by_same_successful_request(store: RedisResponseStore, provider: Provider, payload: bytes) -> None:
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
+    prepared: Final = prepare_forward("POST", upstream, HEADERS, BODY)
+    assert isinstance(prepared, PreparedForward)
+    key: Final = exact_key(SECRET, "POST", upstream, prepared.headers, BODY)
+    lease: Final = store.lookup(key)
+    assert isinstance(lease, CaptureLease)
+    assert store.publish(key, lease, payload)
+    cache: Final = CacheEdge(store, SECRET)
+    for _ in range(2):
+        head = cache.forward("POST", upstream, HEADERS, BODY, 5)
+        assert isinstance(head, StreamHead)
+        assert b"".join(step.data for step in head.steps if isinstance(step, StreamChunk)) == SUCCESS
+    assert len(provider.hits) == 1
+    assert dict(cache.counters.counts) == {
+        "corrupt": 1, "misses": 1, "upstream_attempts": 1, "writes": 1, "hits": 1,
+    }
+
+
+@pytest.mark.parametrize("payload", [
+    b'data: {}\n\ndata: [DONE]\n\n',
+    b'data: {"choices":[{"index":0,"delta":{}}]}\n\ndata: [DONE]\n\n',
+    b'data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\ndata: [DONE]',
+    b'data: {"error":{"message":"failed"}}\n\ndata: [DONE]\n\n',
+])
+def test_malformed_success_stream_is_never_cached(store: RedisResponseStore, provider: Provider, payload: bytes) -> None:
+    provider.stream = True
+    provider.response = payload
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        assert call(url).body == payload
+        assert call(url).body == payload
+    assert len(provider.hits) == 2
+
+
+def test_anthropic_stream_requires_start_finish_and_stop() -> None:
+    start: Final = b'data: {"type":"message_start","message":{}}\n\n'
+    finish: Final = b'data: {"type":"message_delta","delta":{"stop_reason":"end_turn"}}\n\n'
+    stop: Final = b'data: {"type":"message_stop"}\n\n'
+    url: Final = "https://example.invalid/v1/messages"
+    headers: Final = {"content-type": "text/event-stream"}
+    assert successful_response(url, 200, headers, start + finish + stop)
+    assert not successful_response(url, 200, headers, start + stop)
+    assert not successful_response(url, 200, headers, finish + stop)
+    assert not successful_response(url, 200, headers, start + finish)
+
+
+@pytest.mark.parametrize("provider,suffix", [("openai", "/v1"), ("anthropic", "")])
+def test_normal_registration_routes_supported_providers(provider: str, suffix: str) -> None:
+    params: Final = LiteLLMParamsBody(model=f"{provider}/test", api_key="os.environ/SYNTHETIC_KEY", timeout=12)
+    routed: Final = route_cache_model(params, lambda mount: f"http://edge.invalid/{mount}", enabled=True)
+    assert routed.api_base == f"http://edge.invalid/{provider}{suffix}"
+    assert routed.model_dump(exclude={"api_base"}) == params.model_dump(exclude={"api_base"})
+    assert params.api_base is None
+
+
+@pytest.mark.parametrize("params", [
+    LiteLLMParamsBody(model="bedrock/test"),
+    LiteLLMParamsBody(model="azure/test"),
+    LiteLLMParamsBody(model="openai/test", api_base="https://custom.invalid/v1"),
+    LiteLLMParamsBody(model="openai/test", api_base=""),
+    LiteLLMParamsBody(model="openai/test", litellm_credential_name="named-credential"),
+    LiteLLMParamsBody(model="openai/test", mock_response="synthetic"),
+])
+def test_registration_preserves_unsupported_or_explicit_routes(params: LiteLLMParamsBody) -> None:
+    def unexpected_edge(mount: str) -> str:
+        pytest.fail(f"should not start edge for {mount}")
+    assert route_cache_model(params, unexpected_edge, enabled=True) is params
+
+
+def test_rollback_and_live_only_policy_keep_direct_provider_route() -> None:
+    params: Final = LiteLLMParamsBody(model="openai/test")
+    assert route_cache_model(params, lambda _: "http://edge.invalid", enabled=False) is params
+    assert route_cache_model(params, lambda _: "http://edge.invalid", enabled=True, mode="realtime") is params
+    token: Final = LIVE_PROVIDER_REQUIRED.set(True)
+    try:
+        assert route_cache_model(params, lambda _: "http://edge.invalid", enabled=True) is params
+    finally:
+        LIVE_PROVIDER_REQUIRED.reset(token)
+    assert route_cache_model(params, lambda _: "http://edge.invalid", enabled=True).api_base == "http://edge.invalid/v1"
+
+
+@dataclass(frozen=True)
+class PublishOutage:
+    client: RedisCommands
+
+    def eval(self, script: str, numkeys: int, *args: str | bytes | int) -> object:
+        if script == PUBLISH:
+            raise RedisConnectionError("synthetic publication outage")
+        return self.client.eval(script, numkeys, *args)
+
+
+def test_write_outage_preserves_success_without_hidden_retry(store: RedisResponseStore, provider: Provider) -> None:
+    unavailable: Final = replace(store, client=PublishOutage(store.client))
+    cache: Final = CacheEdge(unavailable, SECRET)
+    with edge(cache, provider) as url:
+        assert call(url).body == SUCCESS
+        assert call(url).body == SUCCESS
+    assert len(provider.hits) == 2
+    assert dict(cache.counters.counts)["write_failures"] == 2
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        assert call(url).body == SUCCESS
+        assert call(url).body == SUCCESS
+    assert len(provider.hits) == 3
+
+
+def test_connection_failure_releases_capture_lease(store: RedisResponseStore) -> None:
+    with socket.socket() as unavailable:
+        unavailable.bind(("127.0.0.1", 0))
+        url: Final = f"http://127.0.0.1:{unavailable.getsockname()[1]}/v1/chat/completions"
+        cache: Final = CacheEdge(store, SECRET)
+        assert isinstance(cache.forward("POST", url, HEADERS, BODY, 0.2), NetworkError)
+        prepared: Final = prepare_forward("POST", url, HEADERS, BODY)
+        assert isinstance(prepared, PreparedForward)
+        key: Final = exact_key(SECRET, "POST", url, prepared.headers, BODY)
+        slot: Final = store.lookup(key)
+        assert isinstance(slot, CaptureLease)
+        assert store.release(key, slot)
+        assert dict(cache.counters.counts)["rejected"] == 1
+
+
+def test_close_before_first_chunk_releases_lease(store: RedisResponseStore, provider: Provider) -> None:
+    url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
+    cache: Final = CacheEdge(store, SECRET)
+    head: Final = cache.forward("POST", url, HEADERS, BODY, 5)
+    assert isinstance(head, StreamHead)
+    head.steps.close()
+    prepared: Final = prepare_forward("POST", url, HEADERS, BODY)
+    assert isinstance(prepared, PreparedForward)
+    key: Final = exact_key(SECRET, "POST", url, prepared.headers, BODY)
+    slot: Final = store.lookup(key)
+    assert isinstance(slot, CaptureLease)
+    assert store.release(key, slot)
+
+
+def test_effective_account_change_cannot_reuse_cache(
+    store: RedisResponseStore, provider: Provider, monkeypatch: pytest.MonkeyPatch, tmp_path,
+) -> None:
+    url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
+    cache: Final = CacheEdge(store, SECRET)
+    for account in ("account-a", "account-b", "account-b"):
+        netrc = tmp_path / account
+        netrc.write_text(f"machine 127.0.0.1 login {account} password synthetic\n")
+        monkeypatch.setenv("NETRC", str(netrc))
+        head = cache.forward("POST", url, HEADERS, BODY, 5)
+        assert isinstance(head, StreamHead)
+        assert b"".join(step.data for step in head.steps if isinstance(step, StreamChunk)) == SUCCESS
+    assert len(provider.hits) == 2
+    assert dict(cache.counters.counts)["hits"] == 1
+
+
+def test_enabled_environment_reuses_store_across_fresh_backends(
+    redis_url: str, provider: Provider, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("E2E_PROVIDER_CACHE", "1")
+    monkeypatch.setenv("E2E_PROVIDER_CACHE_REDIS_URL", redis_url)
+    monkeypatch.setenv("E2E_PROVIDER_CACHE_HMAC_KEY", SECRET.decode())
+    monkeypatch.setenv("E2E_PROVIDER_CACHE_NAMESPACE", "environment-" + uuid.uuid4().hex)
+    configured_cache.cache_clear()
+    try:
+        for _ in range(2):
+            backend = configured_cache_backend()
+            assert isinstance(backend, CacheEdge)
+            with edge(backend, provider) as url:
+                assert call(url).body == SUCCESS
+            configured_cache.cache_clear()
+        assert len(provider.hits) == 1
+        monkeypatch.setenv("E2E_PROVIDER_CACHE", "0")
+        assert configured_cache_backend() is None
+    finally:
+        configured_cache.cache_clear()
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
new file mode 100644
index 00000000000..280132d0940
--- /dev/null
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -0,0 +1,27 @@
+# Shared provider-response cache
+
+`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
+
+The edge caches complete successful POST responses for `/v1/chat/completions` and `/v1/messages`, including streams. Unsupported endpoints pass through. It matches the method, original URL, effective outbound headers (including authentication and HTTP-library defaults), body presence and exact body bytes using a full keyed digest. It sends the same prepared request used for matching. No prompts, random markers, JSON values or credentials are normalized away
+
+An eligible miss calls the provider. A complete successful response is stored immediately even if a later test assertion fails. Provider errors, malformed responses, truncated streams and cancelled captures are not stored. Cache reads, writes and lease failures fall through to normal provider behavior; they introduce no provider retry. An already-started response cannot be restarted after a delivery failure
+
+Recordings are shared across workers and builds through dedicated Redis, separate from the candidate's own cache. They expire 86,400 seconds after capture starts, based on Redis time. Reads never extend expiry. There is no scheduled recapture: the next miss calls the provider again. Bounded coordination reduces duplicate concurrent calls, but slow or failed captures may lead to extra live calls after the wait expires
+
+## Configuration
+
+The trusted runner receives:
+
+- `E2E_PROVIDER_CACHE`: `1` to enable, `0` to use the normal live path
+- `E2E_PROVIDER_CACHE_REDIS_URL`: authenticated dedicated Redis URL
+- `E2E_PROVIDER_CACHE_HMAC_KEY`: dedicated secret containing at least 32 bytes
+- `E2E_PROVIDER_CACHE_NAMESPACE`: shared environment namespace, independent of build and candidate revision
+- `E2E_PROVIDER_CACHE_METRICS_DIR`: optional per-process counter artifact directory
+
+Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
+
+Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
+
+## Qualification
+
+`tests/code_coverage_tests/test_provider_cache.py` exercises local HTTP providers and disposable real Redis. CI runs these checks with the existing provider-edge and replay harness tests. These component checks do not establish Buildkite deployment, full-suite cross-build reuse or a genuine 24-hour expiry observation; those require separate runtime evidence
diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py
index b1a75d5f862..829c84910a9 100644
--- a/tests/e2e/conftest.py
+++ b/tests/e2e/conftest.py
@@ -22,7 +22,6 @@ from typing import Final
 
 import pytest
 import requests
-
 from e2e_config import (
     CONTROL_PLANE_BASE_URL,
     FIXTURE_DIR,
@@ -41,6 +40,7 @@ from idp import Identity, Keycloak, keycloak_from_env
 from junit_properties import attach_result_properties
 from lifecycle import ProxyClientProvider, ResourceManager
 from models import TeamNewBody, UserNewBody, UserNewResponse
+from provider_cache_routing import LIVE_PROVIDER_REQUIRED
 from provider_edge import replay_leftover_error
 from proxy_client import ProxyClient, build_proxy_client
 
@@ -85,6 +85,7 @@ def jwt_identity(idp: Keycloak, resources: ResourceManager, proxy: ProxyClient)
 
 
 def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line("markers", "provider_live: requires actual provider timing, limits or state; bypass shared cache")
     config.addinivalue_line(
         "markers",
         "e2e: live test that requires a running proxy and real provider keys",
@@ -192,11 +193,13 @@ def _proxy_fail_reason() -> str | None:
     return None
 
 
+@pytest.hookimpl(tryfirst=True)
 def pytest_runtest_setup(item: pytest.Item) -> None:
     """Hard-fail `e2e`-marked tests unless a proxy answers its liveness probe.
     Unmarked tests (unit coverage of the harness) don't touch the proxy, so they
     run even when none is up. Never skip for a missing proxy. Replay mode needs
     the proxy too: only provider-bound traffic replays from the bundle."""
+    LIVE_PROVIDER_REQUIRED.set(item.get_closest_marker("provider_live") is not None)
     if item.get_closest_marker("e2e") is None:
         return
     reason = _proxy_fail_reason()
@@ -235,6 +238,7 @@ def pytest_runtest_teardown(item: pytest.Item) -> Generator[None, None, None]:
     yield so fixture finalizers replay their recorded calls first. Failed tests
     are left alone - their own failure already explains any unconsumed tail."""
     result = yield
+    LIVE_PROVIDER_REQUIRED.set(False)
     if not item.stash.get(_CALL_PASSED, False):
         return result
     reason = replay_leftover_error(
diff --git a/tests/e2e/e2e_http.py b/tests/e2e/e2e_http.py
index 1992f419823..4184b6cbefc 100644
--- a/tests/e2e/e2e_http.py
+++ b/tests/e2e/e2e_http.py
@@ -853,6 +853,7 @@ def _stream_steps(resp: requests.Response) -> Generator[StreamStep, None, None]:
     the chunks already delivered are exactly what makes a mid-stream failure
     different from a request that never streamed at all."""
     try:
+        yield StreamChunk(b"")
         for piece in cast("Iterator[bytes]", resp.iter_content(chunk_size=None)):
             if piece:
                 yield StreamChunk(data=piece)
@@ -862,6 +863,44 @@ def _stream_steps(resp: requests.Response) -> Generator[StreamStep, None, None]:
         resp.close()
 
 
+def primed_steps(steps: Generator[StreamStep, None, None]) -> Generator[StreamStep, None, None]:
+    first: Final = next(steps)
+    assert isinstance(first, StreamChunk) and first.data == b""
+    return steps
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class PreparedForward:
+    request: requests.PreparedRequest
+    url: str
+    headers: dict[str, str]
+
+
+def prepare_forward(
+    method: str, url: str, headers: dict[str, str], body: bytes | None,
+) -> PreparedForward | NetworkError:
+    try:
+        with requests.Session() as session:
+            request: Final = session.prepare_request(requests.Request(method, url, headers=headers, data=body))
+    except requests.RequestException as exc:
+        return NetworkError(message=str(exc))
+    assert request.url is not None
+    return PreparedForward(request, request.url, dict(request.headers))
+
+
+def forward_prepared_stream(prepared: PreparedForward, timeout: float) -> StreamHead | NetworkError:
+    try:
+        with requests.Session() as session:
+            settings: Final = session.merge_environment_settings(prepared.url, {}, True, None, None)
+            resp: Final = session.send(prepared.request, timeout=timeout, allow_redirects=False, **settings)
+    except requests.RequestException as exc:
+        return NetworkError(message=str(exc))
+    return StreamHead(
+        resp.status_code, {name.lower(): value for name, value in resp.headers.items()},
+        primed_steps(_stream_steps(resp)),
+    )
+
+
 def open_stream(url: URL, *, headers: BaseModel, json: BaseModel, timeout: float = 60.0) -> StreamHead | NetworkError:
     """POST a streaming request and return the moment its response head arrives,
     leaving the body unread behind ``StreamHead.steps``. For a test that must keep
@@ -907,5 +946,5 @@ def forward_stream(
     return StreamHead(
         status_code=resp.status_code,
         headers={name.lower(): value for name, value in resp.headers.items()},
-        steps=_stream_steps(resp),
+        steps=primed_steps(_stream_steps(resp)),
     )
diff --git a/tests/e2e/llm_translation/test_messages_e2e.py b/tests/e2e/llm_translation/test_messages_e2e.py
index ca58c30d40c..44c416a3e78 100644
--- a/tests/e2e/llm_translation/test_messages_e2e.py
+++ b/tests/e2e/llm_translation/test_messages_e2e.py
@@ -24,10 +24,10 @@ from models import (
     AnthropicAssistantTurn,
     AnthropicContentBlock,
     AnthropicCustomTool,
+    AnthropicMessagesBody,
     AnthropicToolChoice,
     AnthropicToolResultBlock,
     AnthropicToolResultTurn,
-    AnthropicMessagesBody,
     ChatMessage,
     JsonSchemaProperty,
     LiteLLMParamsBody,
@@ -165,6 +165,7 @@ class TestAnthropicMessages:
         )
 
     @pytest.mark.covers("llm.messages.anthropic.basic.stream.works")
+    @pytest.mark.provider_live
     def test_messages_streams_completion(
         self, endpoints_client: EndpointsClient, resources: ResourceManager
     ) -> None:
diff --git a/tests/e2e/llm_translation/test_together_ai_e2e.py b/tests/e2e/llm_translation/test_together_ai_e2e.py
index 31e74c22e17..8dd7e7c1a31 100644
--- a/tests/e2e/llm_translation/test_together_ai_e2e.py
+++ b/tests/e2e/llm_translation/test_together_ai_e2e.py
@@ -744,6 +744,7 @@ class TestTogetherMessages:
         assert "22" in text, f"the model never saw the tool result: {response.content}"
 
     @pytest.mark.covers("llm.messages.together_ai.basic.stream.works")
+    @pytest.mark.provider_live
     def test_streams_text_deltas(
         self, client: PassthroughClient, resources: ResourceManager, reasoning_tool_backend: str
     ) -> None:
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
new file mode 100644
index 00000000000..50b336f5263
--- /dev/null
+++ b/tests/e2e/provider_cache.py
@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import io
+import threading
+import time
+from collections.abc import Callable, Generator, Mapping
+from contextlib import closing
+from dataclasses import dataclass, field
+from typing import Final, Literal, Protocol
+from urllib.parse import urlsplit
+
+from e2e_http import (
+    NetworkError,
+    StreamChunk,
+    StreamHead,
+    StreamStep,
+    StreamTruncation,
+    forward_prepared_stream,
+    forward_stream,
+    prepare_forward,
+    primed_steps,
+)
+from pydantic import BaseModel, ConfigDict, JsonValue, TypeAdapter, ValidationError
+
+LIFETIME_SECONDS: Final = 86_400
+MAX_REQUEST_BYTES: Final = 256 * 1024
+MAX_RESPONSE_BYTES: Final = 8 * 1024 * 1024
+JSON_VALUE: Final[TypeAdapter[JsonValue]] = TypeAdapter(JsonValue)
+
+
+@dataclass(frozen=True, slots=True)
+class CacheHit:
+    payload: bytes
+    valid_until: float
+
+
+@dataclass(frozen=True, slots=True)
+class CaptureLease:
+    token: str
+    captured_at_ms: int
+    expires_at_ms: int
+
+
+@dataclass(frozen=True, slots=True)
+class CacheBusy:
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class CacheUnavailable:
+    pass
+
+
+type CacheLookup = CacheHit | CaptureLease | CacheBusy | CacheUnavailable
+
+
+class ResponseStore(Protocol):
+    def lookup(self, key: str) -> CacheLookup: ...
+
+    def publish(self, key: str, lease: CaptureLease, payload: bytes) -> bool: ...
+
+    def release(self, key: str, lease: CaptureLease) -> bool: ...
+
+    def discard(self, key: str, payload: bytes) -> bool: ...
+
+
+class CachedResponse(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+    format_version: Literal[1] = 1
+    request_key: str
+    status_code: int
+    headers: dict[str, str]
+    chunks: tuple[str, ...]
+
+
+class SignedResponse(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+    response: str
+    signature: str
+
+
+def exact_key(secret: bytes, method: str, url: str, headers: Mapping[str, str], body: bytes | None) -> str:
+    fields: Final = (
+        b"provider-cache-exact-v1", method.encode(), url.encode(),
+        *(part.encode() for pair in sorted(headers.items()) for part in pair),
+        b"no-body" if body is None else b"body", b"" if body is None else body,
+    )
+    encoded: Final = b"".join(len(part).to_bytes(8, "big") + part for part in fields)
+    return hmac.new(secret, encoded, hashlib.sha256).hexdigest()
+
+
+def cacheable_endpoint(method: str, url: str, body: bytes | None) -> bool:
+    return (
+        method == "POST"
+        and urlsplit(url).path in {"/v1/chat/completions", "/v1/messages"}
+        and body is not None
+        and len(body) <= MAX_REQUEST_BYTES
+    )
+
+
+def successful_response(url: str, status: int, headers: Mapping[str, str], body: bytes) -> bool:
+    if not 200 <= status < 300 or len(body) > MAX_RESPONSE_BYTES:
+        return False
+    if any(name.lower() == "set-cookie" for name in headers):
+        return False
+    streaming: Final = "text/event-stream" in headers.get("content-type", "").lower()
+    if streaming:
+        try:
+            text: Final = body.decode("utf-8").replace("\r\n", "\n")
+            if not text.endswith("\n\n"):
+                return False
+            events: Final = tuple(
+                "\n".join(line[5:].removeprefix(" ") for line in event.split("\n") if line.startswith("data:"))
+                for event in text.split("\n\n") if any(line.startswith("data:") for line in event.split("\n"))
+            )
+            values: Final = tuple(JSON_VALUE.validate_json(event) for event in events if event != "[DONE]")
+        except (UnicodeDecodeError, ValidationError):
+            return False
+        if not values or any(not isinstance(value, dict) or "error" in value or value.get("type") == "error" for value in values):
+            return False
+        if urlsplit(url).path == "/v1/chat/completions":
+            return events[-1] == "[DONE]" and "[DONE]" not in events[:-1] and complete_chat_stream(values)
+        return (
+            "[DONE]" not in events
+            and isinstance(values[0], dict) and values[0].get("type") == "message_start"
+            and isinstance(values[-1], dict) and values[-1].get("type") == "message_stop"
+            and any(
+                isinstance(value, dict) and value.get("type") == "message_delta"
+                and isinstance(delta := value.get("delta"), dict) and isinstance(delta.get("stop_reason"), str)
+                for value in values
+            )
+        )
+    try:
+        value: Final = JSON_VALUE.validate_json(body)
+    except ValidationError:
+        return False
+    if not isinstance(value, dict) or "error" in value:
+        return False
+    if urlsplit(url).path == "/v1/messages":
+        return value.get("type") == "message" and isinstance(value.get("content"), list) and isinstance(value.get("stop_reason"), str)
+    choices: Final = value.get("choices")
+    return isinstance(choices, list) and bool(choices) and all(
+        isinstance(choice, dict) and isinstance(choice.get("message"), dict) and isinstance(choice.get("finish_reason"), str)
+        for choice in choices
+    )
+
+
+def complete_chat_stream(values: tuple[JsonValue, ...]) -> bool:
+    if any(not isinstance(value, dict) or not isinstance(value.get("choices"), list) for value in values):
+        return False
+    choices: Final = tuple(
+        choice for value in values if isinstance(value, dict)
+        if isinstance(items := value.get("choices"), list) for choice in items
+    )
+    if not choices or any(
+        not isinstance(choice, dict) or type(choice.get("index")) is not int
+        or not isinstance(choice.get("delta"), dict)
+        for choice in choices
+    ):
+        return False
+    indices: Final = frozenset(choice["index"] for choice in choices if isinstance(choice, dict))
+    return all(
+        isinstance(tuple(choice for choice in choices if isinstance(choice, dict) and choice["index"] == index)[-1].get("finish_reason"), str)
+        for index in indices
+    )
+
+
+def encode_response(secret: bytes, response: CachedResponse) -> bytes:
+    raw: Final = response.model_dump_json()
+    return SignedResponse(response=raw, signature=hmac.new(secret, raw.encode(), hashlib.sha256).hexdigest()).model_dump_json().encode()
+
+
+def decode_response(secret: bytes, key: str, payload: bytes, url: str) -> CachedResponse | None:
+    if len(payload) > 2 * MAX_RESPONSE_BYTES:
+        return None
+    try:
+        signed: Final = SignedResponse.model_validate_json(payload)
+        if not hmac.compare_digest(signed.signature.encode(), hmac.new(secret, signed.response.encode(), hashlib.sha256).hexdigest().encode()):
+            return None
+        response: Final = CachedResponse.model_validate_json(signed.response)
+        chunks: Final = tuple(base64.b64decode(chunk, validate=True) for chunk in response.chunks)
+    except (ValidationError, ValueError):
+        return None
+    if response.request_key != key or not successful_response(url, response.status_code, response.headers, b"".join(chunks)):
+        return None
+    return response
+
+
+@dataclass(slots=True)
+class CacheCounters:
+    counts: tuple[tuple[str, int], ...] = ()
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def increment(self, name: str) -> None:
+        with self.lock:
+            current: Final = dict(self.counts)
+            self.counts = tuple((current | {name: current.get(name, 0) + 1}).items())
+
+
+@dataclass(slots=True)
+class ResponseCapture:
+    buffer: io.BytesIO = field(default_factory=io.BytesIO)
+    size: int = 0
+    eligible: bool = True
+
+    def observe(self, step: StreamStep) -> None:
+        if not self.eligible:
+            return
+        if isinstance(step, StreamTruncation) or self.size + len(step.data) + 8 > MAX_RESPONSE_BYTES:
+            self.eligible = False
+            self.buffer.close()
+            return
+        self.buffer.write(len(step.data).to_bytes(8, "big"))
+        self.buffer.write(step.data)
+        self.size += len(step.data) + 8
+
+    def chunks(self) -> tuple[bytes, ...]:
+        self.buffer.seek(0)
+        return tuple(self.buffer.read(int.from_bytes(size, "big")) for size in iter(lambda: self.buffer.read(8), b""))
+
+
+def response_steps(response: CachedResponse) -> Generator[StreamStep, None, None]:
+    for chunk in response.chunks:
+        yield StreamChunk(base64.b64decode(chunk, validate=True))
+
+
+@dataclass(frozen=True, slots=True)
+class CacheEdge:
+    store: ResponseStore
+    secret: bytes = field(repr=False)
+    counters: CacheCounters = field(default_factory=CacheCounters)
+    wait_seconds: float = 2.0
+    clock: Callable[[], float] = time.monotonic
+    sleep: Callable[[float], None] = time.sleep
+
+    def lookup(self, key: str) -> CacheLookup:
+        deadline: Final = self.clock() + self.wait_seconds
+        while isinstance(result := self.store.lookup(key), CacheBusy) and self.clock() < deadline:
+            self.sleep(min(0.05, max(0, deadline - self.clock())))
+        return result
+
+    def forward(self, method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float) -> StreamHead | NetworkError:
+        if not cacheable_endpoint(method, url, body):
+            self.counters.increment("bypass")
+            self.counters.increment("upstream_attempts")
+            return forward_stream(method, url, headers=headers, body=body, timeout=timeout)
+        prepared: Final = prepare_forward(method, url, headers, body)
+        if isinstance(prepared, NetworkError):
+            self.counters.increment("rejected")
+            return prepared
+        key: Final = exact_key(self.secret, method, url, prepared.headers, body)
+        found: Final = self.lookup(key)
+        if isinstance(found, CacheHit):
+            response: Final = decode_response(self.secret, key, found.payload, url)
+            if response is not None and self.clock() < found.valid_until:
+                self.counters.increment("hits")
+                return StreamHead(response.status_code, response.headers, response_steps(response))
+            self.counters.increment("corrupt" if response is None else "expired")
+            self.store.discard(key, found.payload)
+        capture_slot: Final = self.lookup(key) if isinstance(found, CacheHit) else found
+        self.counters.increment("misses")
+        if isinstance(capture_slot, CacheUnavailable):
+            self.counters.increment("cache_errors")
+        self.counters.increment("upstream_attempts")
+        head: Final = forward_prepared_stream(prepared, timeout)
+        if not isinstance(capture_slot, CaptureLease):
+            return head
+        if isinstance(head, NetworkError):
+            self.store.release(key, capture_slot)
+            self.counters.increment("rejected")
+            return head
+        return StreamHead(head.status_code, head.headers, primed_steps(self.capture(key, capture_slot, url, head)))
+
+    def capture(self, key: str, lease: CaptureLease, url: str, head: StreamHead) -> Generator[StreamStep, None, None]:
+        capture: Final = ResponseCapture()
+        try:
+            with closing(head.steps):
+                yield StreamChunk(b"")
+                for step in head.steps:
+                    yield step
+                    capture.observe(step)
+            chunks: Final = capture.chunks() if capture.eligible else ()
+            if not capture.eligible or not successful_response(url, head.status_code, head.headers, b"".join(chunks)):
+                self.counters.increment("rejected")
+                return
+            response: Final = CachedResponse(
+                request_key=key, status_code=head.status_code, headers=head.headers,
+                chunks=tuple(base64.b64encode(chunk).decode("ascii") for chunk in chunks),
+            )
+            published: Final = self.store.publish(key, lease, encode_response(self.secret, response))
+            self.counters.increment("writes" if published else "write_failures")
+        finally:
+            self.store.release(key, lease)
+            capture.buffer.close()
diff --git a/tests/e2e/provider_cache_redis.py b/tests/e2e/provider_cache_redis.py
new file mode 100644
index 00000000000..be4e31b2c49
--- /dev/null
+++ b/tests/e2e/provider_cache_redis.py
@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import atexit
+import functools
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, Protocol, cast
+
+from provider_cache import LIFETIME_SECONDS, CacheBusy, CacheEdge, CacheHit, CacheLookup, CacheUnavailable, CaptureLease
+from pydantic import TypeAdapter, ValidationError
+from redis import Redis
+from redis.exceptions import RedisError
+
+REDIS_ARRAY: Final[TypeAdapter[list[bytes]]] = TypeAdapter(list[bytes])
+
+LOOKUP: Final = """
+local clock = redis.call('TIME')
+local now = clock[1] * 1000 + math.floor(clock[2] / 1000)
+local row = redis.call('HMGET', KEYS[1], 'captured', 'expires', 'payload')
+if row[3] then
+  local captured = tonumber(row[1])
+  local expires = tonumber(row[2])
+  if captured and expires and captured <= now and expires > now
+     and expires - captured == tonumber(ARGV[2]) then
+    return {'hit', row[3], tostring(expires - now)}
+  end
+  redis.call('DEL', KEYS[1])
+end
+if redis.call('SET', KEYS[2], ARGV[1], 'NX', 'PX', ARGV[3]) then
+  return {'lease', tostring(now), tostring(now + tonumber(ARGV[2]))}
+end
+return {'busy'}
+"""
+
+PUBLISH: Final = """
+if redis.call('GET', KEYS[2]) ~= ARGV[1] then return 0 end
+local clock = redis.call('TIME')
+local now = clock[1] * 1000 + math.floor(clock[2] / 1000)
+local captured = tonumber(ARGV[2])
+local expires = tonumber(ARGV[3])
+if captured > now or expires <= now or expires - captured ~= tonumber(ARGV[5]) then return 0 end
+if redis.call('EXISTS', KEYS[1]) == 1 then return 0 end
+redis.call('HSET', KEYS[1], 'captured', ARGV[2], 'expires', ARGV[3], 'payload', ARGV[4])
+redis.call('PEXPIREAT', KEYS[1], expires)
+redis.call('DEL', KEYS[2])
+return 1
+"""
+
+RELEASE: Final = """
+if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
+return redis.call('DEL', KEYS[1])
+"""
+
+DISCARD: Final = """
+if redis.call('HGET', KEYS[1], 'payload') ~= ARGV[1] then return 0 end
+return redis.call('DEL', KEYS[1])
+"""
+
+
+class RedisCommands(Protocol):
+    def eval(self, script: str, numkeys: int, *args: str | bytes | int) -> object: ...
+
+
+@dataclass(frozen=True, slots=True)
+class RedisResponseStore:
+    client: RedisCommands
+    namespace: str
+    lifetime_ms: int = LIFETIME_SECONDS * 1000
+    lease_ms: int = 120_000
+
+    def keys(self, key: str) -> tuple[str, str]:
+        prefix: Final = f"e2e-provider-cache:v1:{self.namespace}:{{{key}}}"
+        return prefix + ":response", prefix + ":lease"
+
+    def lookup(self, key: str) -> CacheLookup:
+        token: Final = uuid.uuid4().hex
+        started: Final = time.monotonic()
+        try:
+            result: Final = self.client.eval(LOOKUP, 2, *self.keys(key), token, self.lifetime_ms, self.lease_ms)
+        except (RedisError, OSError):
+            return CacheUnavailable()
+        try:
+            parts: Final = tuple(REDIS_ARRAY.validate_python(result, strict=True))
+        except ValidationError:
+            return CacheUnavailable()
+        if len(parts) == 3 and parts[0] == b"hit" and parts[2].isdigit():
+            return CacheHit(parts[1], started + int(parts[2]) / 1000)
+        if len(parts) == 3 and parts[0] == b"lease" and parts[1].isdigit() and parts[2].isdigit():
+            return CaptureLease(token, int(parts[1]), int(parts[2]))
+        if parts == (b"busy",):
+            return CacheBusy()
+        return CacheUnavailable()
+
+    def publish(self, key: str, lease: CaptureLease, payload: bytes) -> bool:
+        try:
+            result: Final = self.client.eval(
+                PUBLISH, 2, *self.keys(key), lease.token, lease.captured_at_ms, lease.expires_at_ms, payload, self.lifetime_ms,
+            )
+        except (RedisError, OSError):
+            return False
+        return result == 1
+
+    def release(self, key: str, lease: CaptureLease) -> bool:
+        try:
+            result: Final = self.client.eval(RELEASE, 1, self.keys(key)[1], lease.token)
+        except (RedisError, OSError):
+            return False
+        return result == 1
+
+    def discard(self, key: str, payload: bytes) -> bool:
+        try:
+            result: Final = self.client.eval(DISCARD, 1, self.keys(key)[0], payload)
+        except (RedisError, OSError):
+            return False
+        return result == 1
+
+
+def redis_store(url: str, namespace: str) -> RedisResponseStore:
+    client: Final = Redis.from_url(url, socket_timeout=0.25, socket_connect_timeout=0.25, decode_responses=False)
+    return RedisResponseStore(cast(RedisCommands, client), namespace)
+
+
+def write_metrics(cache: CacheEdge) -> None:
+    report: Final = json.dumps({"provider_cache": dict(cache.counters.counts)})
+    directory: Final = os.environ.get("E2E_PROVIDER_CACHE_METRICS_DIR")
+    if directory:
+        try:
+            root: Final = Path(directory)
+            root.mkdir(parents=True, exist_ok=True)
+            (root / f"{os.getpid()}.json").write_text(report + "\n")
+        except OSError:
+            logging.getLogger(__name__).warning("provider cache metrics artifact unavailable")
+    logging.getLogger(__name__).info("%s", report)
+
+
+@functools.lru_cache(maxsize=1)
+def configured_cache() -> CacheEdge | None:
+    if os.environ.get("E2E_PROVIDER_CACHE", "0") == "0":
+        return None
+    if os.environ.get("E2E_PROVIDER_CACHE") != "1":
+        raise ValueError("E2E_PROVIDER_CACHE must be 0 or 1")
+    secret: Final = os.environ.get("E2E_PROVIDER_CACHE_HMAC_KEY", "").encode()
+    namespace: Final = os.environ.get("E2E_PROVIDER_CACHE_NAMESPACE", "")
+    if len(secret) < 32 or re.fullmatch(r"[a-zA-Z0-9_-]{1,64}", namespace) is None:
+        raise ValueError("provider cache requires a dedicated key and namespace")
+    cache: Final = CacheEdge(redis_store(os.environ["E2E_PROVIDER_CACHE_REDIS_URL"], namespace), secret)
+    atexit.register(write_metrics, cache)
+    return cache
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
new file mode 100644
index 00000000000..24599b5a313
--- /dev/null
+++ b/tests/e2e/provider_cache_routing.py
@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextvars import ContextVar
+from typing import Final
+
+from models import LiteLLMParamsBody, ModelMode
+
+LIVE_PROVIDER_REQUIRED: Final[ContextVar[bool]] = ContextVar("live_provider_required", default=False)
+
+
+def route_cache_model(
+    params: LiteLLMParamsBody, base_for: Callable[[str], str | None], *, enabled: bool, mode: ModelMode | None = None,
+) -> LiteLLMParamsBody:
+    if not enabled or mode == "realtime" or LIVE_PROVIDER_REQUIRED.get() or params.api_base is not None or params.mock_response is not None:
+        return params
+    provider: Final = params.model.partition("/")[0]
+    if provider not in {"openai", "anthropic"} or params.litellm_credential_name is not None:
+        return params
+    base: Final = base_for(provider)
+    if base is None:
+        return params
+    return params.model_copy(update={"api_base": f"{base}/v1" if provider == "openai" else base})
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index de36895ebb6..49d574ee957 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -42,6 +42,7 @@ import base64
 import difflib
 import functools
 import hashlib
+import os
 import re
 import threading
 from collections import deque
@@ -93,6 +94,8 @@ from fixture_mode import (
     parse_fixture_mode,
 )
 from fixture_profile import IneligibleRequest, MatchProfile, match_profile, strict_identity
+from provider_cache import CacheEdge
+from provider_cache_routing import LIVE_PROVIDER_REQUIRED
 from pydantic import JsonValue, TypeAdapter
 
 EDGE_MOUNTS: Final[Mapping[str, str]] = MappingProxyType(
@@ -506,7 +509,7 @@ class LiveEdge:
     pass
 
 
-type EdgeBackend = RecordEdge | ReplayEdge | LiveEdge
+type EdgeBackend = RecordEdge | ReplayEdge | LiveEdge | CacheEdge
 
 
 @dataclass(slots=True)
@@ -750,12 +753,16 @@ def _handle_record(
 
 
 def _handle_live(
-    method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float
+    method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float,
+    cache: CacheEdge | None = None,
 ) -> EdgeOutcome:
     forwarded: Final = {
         name: value for name, value in headers.items() if name.lower() not in _REQUEST_DROPPED_HEADERS
     }
-    head: Final = forward_stream(method, url, headers=forwarded, body=body, timeout=timeout)
+    head: Final = (
+        forward_stream(method, url, headers=forwarded, body=body, timeout=timeout)
+        if cache is None else cache.forward(method, url, forwarded, body, timeout)
+    )
     match head:
         case NetworkError(message=message):
             return _recorded_outcome(_network_error_response(message))
@@ -821,6 +828,10 @@ def handle_edge_request(
         else edge_request(method, split.path, split.query, body, _header_value(headers, "content-type"))
     )
     match backend:
+        case CacheEdge():
+            return _handle_live(
+                method, _upstream_url(upstream_base, upstream_path, split.query), headers, body, timeout, backend,
+            )
         case LiveEdge():
             return _handle_live(
                 method, _upstream_url(upstream_base, upstream_path, split.query), headers, body, timeout
@@ -871,11 +882,17 @@ class _EdgeHandler(BaseHTTPRequestHandler):
             or isinstance(edge_server.backend, ReplayEdge)
             and edge_server.backend.source.bundle.manifest.match_profile == "stateless_v1"
         )
-        if strict and len({name.lower() for name in self.headers.keys()}) != len(self.headers):
+        if strict and len({name.lower() for name in self.headers}) != len(self.headers):
             self._write_reply(_text_reply(REPLAY_MISS_STATUS, "stateless_v1 eligibility error: duplicate headers"))
             return
+        duplicate_headers: Final = len({name.lower() for name in self.headers}) != len(self.headers)
+        selected_backend: Final = (
+            LiveEdge() if isinstance(edge_server.backend, CacheEdge) and duplicate_headers else edge_server.backend
+        )
+        if isinstance(edge_server.backend, CacheEdge) and duplicate_headers:
+            edge_server.backend.counters.increment("duplicate_header_bypass")
         outcome: Final = handle_edge_request(
-            edge_server.backend,
+            selected_backend,
             edge_server.mounts,
             self.command,
             self.path,
@@ -908,12 +925,12 @@ class _EdgeHandler(BaseHTTPRequestHandler):
         shuts down write-side first: the proxy sees a graceful close mid-message,
         which is the incomplete chunked read a provider hanging up produces, and not
         the reset that could discard the chunks already in flight."""
-        self.send_response(stream.status_code)
-        for name, value in stream.headers.items():
-            self.send_header(name, value)
-        self.send_header("transfer-encoding", "chunked")
-        self.end_headers()
         with closing(stream.steps) as steps:
+            self.send_response(stream.status_code)
+            for name, value in stream.headers.items():
+                self.send_header(name, value)
+            self.send_header("transfer-encoding", "chunked")
+            self.end_headers()
             for step in steps:
                 match step:
                     case StreamChunk(data=data):
@@ -923,7 +940,7 @@ class _EdgeHandler(BaseHTTPRequestHandler):
                         return
                     case _:
                         assert_never(step)
-        self.wfile.write(b"0\r\n\r\n")
+            self.wfile.write(b"0\r\n\r\n")
 
     def log_message(self, format: str, *args: object) -> None:
         """Silence the per-request stderr line BaseHTTPRequestHandler emits."""
@@ -1056,6 +1073,8 @@ def provider_edge_api_base(
         case InvalidFixtureMode(value=value):
             raise ValueError(f"E2E_FIXTURE_MODE={value!r} is not one of {', '.join(FIXTURE_MODES)}")
         case "live":
+            if configured_cache_backend() is not None:
+                return _shared_cache_edge(bind_host, advertise_host, forward_timeout).api_base(mount)
             return None
         case "record" | "replay":
             if mount not in EDGE_MOUNTS:
@@ -1073,7 +1092,7 @@ def _observed_backend(mode_raw: str, bundle_dir: Path) -> EdgeBackend:
         case InvalidFixtureMode(value=value):
             raise ValueError(f"E2E_FIXTURE_MODE={value!r} is not one of {', '.join(FIXTURE_MODES)}")
         case "live":
-            return LiveEdge()
+            return configured_cache_backend() or LiveEdge()
         case "record":
             return RecordEdge(_shared_recorder(bundle_dir, match_profile()), threading.Lock())
         case "replay":
@@ -1082,6 +1101,24 @@ def _observed_backend(mode_raw: str, bundle_dir: Path) -> EdgeBackend:
             assert_never(mode)
 
 
+def configured_cache_backend() -> CacheEdge | None:
+    if LIVE_PROVIDER_REQUIRED.get() or os.environ.get("E2E_PROVIDER_CACHE", "0") == "0":
+        return None
+    from provider_cache_redis import configured_cache
+
+    return configured_cache()
+
+
+@functools.lru_cache(maxsize=8)
+def _shared_cache_edge(bind_host: str, advertise_host: str, forward_timeout: float) -> ProviderEdge:
+    backend: Final = configured_cache_backend()
+    assert backend is not None
+    return start_provider_edge(
+        backend, mounts=EDGE_MOUNTS, bind_host=bind_host,
+        advertise_host=advertise_host, forward_timeout=forward_timeout,
+    ).edge
+
+
 @contextmanager
 def observed_provider_edge(
     observation: ProviderRequestObservation,
diff --git a/tests/e2e/proxy_client.py b/tests/e2e/proxy_client.py
index 3f7fba5ffec..f8ed8843461 100644
--- a/tests/e2e/proxy_client.py
+++ b/tests/e2e/proxy_client.py
@@ -8,6 +8,7 @@ ProxyClient's key/customer methods for cleanup. Read-backs are eventually consis
 
 from __future__ import annotations
 
+import os
 import time
 import warnings
 from collections.abc import Callable, Mapping
@@ -26,6 +27,7 @@ from e2e_config import (
     PROXY_REPLICA_URLS,
     REQUEST_TIMEOUT,
     SLOW_PROVIDER_TIMEOUT_SECONDS,
+    provider_edge_base,
     settle_propagation,
 )
 from e2e_http import (
@@ -93,6 +95,7 @@ from models import (
     UserDeleteBody,
     UserDeleteResponse,
 )
+from provider_cache_routing import route_cache_model
 from pydantic import BaseModel
 from transport import HttpTransport, SplitTransport, Transport, is_control_plane_path
 
@@ -645,7 +648,10 @@ class ProxyClient:
             self.transport.post(
                 "/model/new",
                 headers=self.management_headers(),
-                json=body,
+                json=body.model_copy(update={"litellm_params": route_cache_model(
+                    body.litellm_params, provider_edge_base,
+                    enabled=os.environ.get("E2E_PROVIDER_CACHE", "0") == "1", mode=body.model_info.mode,
+                )}),
                 response_type=ModelNewResponse,
             )
         ).model_id

From 44a6d1988958d3614f602d49746e83ae603ccb3b Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:14:37 +0000
Subject: [PATCH 30/67] test(gemini): drop review narration from the wrapper
 test docstring

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../gemini/test_vertex_and_google_ai_studio_gemini.py        | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
index 3fb00a7d962..cd0ed0057c0 100644
--- a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
+++ b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
@@ -5899,11 +5899,6 @@ def test_streaming_chunk_carries_model_version():
 
 
 def test_served_model_version_reaches_assembled_stream_through_custom_stream_wrapper():
-    """Greptile claimed CustomStreamWrapper drops the served modelVersion before
-    pricing. It does not: chunk_creator stashes the parser chunk's model into each
-    yielded chunk's _hidden_params["provider_response_model"], and
-    stream_chunk_builder carries it onto the assembled response. The wrapper's
-    trailing bookkeeping chunk is the one emission that legitimately omits it."""
     from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper
     from litellm.llms.vertex_ai.gemini.vertex_and_google_ai_studio_gemini import (
         ModelResponseIterator,

From f2145550680b85ed7f9b67826467125077cc8e8c Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 18:21:43 -0700
Subject: [PATCH 31/67] fix(e2e): expect models filters to persist after reload

---
 .../tests/internal-user/modelsByTeam.spec.ts  | 21 ++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/tests/e2e/ui/tests/internal-user/modelsByTeam.spec.ts b/tests/e2e/ui/tests/internal-user/modelsByTeam.spec.ts
index 5e2c80b5845..736c352e3ee 100644
--- a/tests/e2e/ui/tests/internal-user/modelsByTeam.spec.ts
+++ b/tests/e2e/ui/tests/internal-user/modelsByTeam.spec.ts
@@ -7,6 +7,7 @@ import {
 import {
   E2E_TEAM_CRUD_ALIAS,
   E2E_TEAM_ORG_ALIAS,
+  E2E_TEAM_ORG_ID,
   INTERNAL_USER_STORAGE_PATH,
 } from "../../constants";
 import { Page } from "../../fixtures/pages";
@@ -179,18 +180,28 @@ test.describe("Models and Endpoints for an internal user", () => {
       `switching to ${ALL_MODELS_VIEW} leaves the table populated rather than blanking it`,
     ).toHaveCount(1, { timeout: 15_000 });
 
+    await expect(page).toHaveURL((url) =>
+      url.searchParams.get("filter_team") === E2E_TEAM_ORG_ID &&
+      url.searchParams.get("view_mode") === "all",
+    );
     await page.reload();
     await expect(
       teamSelector(page),
-      "the team selection is not persisted across a reload, so the table returns to the personal view",
-    ).toContainText(PERSONAL_TEAM, { timeout: 15_000 });
+      "the selected team is restored from the URL after a reload",
+    ).toContainText(E2E_TEAM_ORG_ALIAS, { timeout: 15_000 });
     await expect(
       viewSelector(page),
-      "the view selection is not persisted across a reload either",
-    ).toContainText(CURRENT_TEAM_VIEW, { timeout: 15_000 });
+      "the selected view is restored from the URL after a reload",
+    ).toContainText(ALL_MODELS_VIEW, { timeout: 15_000 });
+    await expect(modelRow(page, CHAT_MODEL_A)).toHaveCount(1, { timeout: 15_000 });
+    await expect(page.getByTestId("pagination-range")).toHaveText("Showing 1-1 of 1");
+    await expect(modelRow(page, CHAT_MODEL_B)).toHaveCount(0);
+    await expect(modelRow(page, ungrantedModelName)).toHaveCount(0);
+
+    await chooseOption(page, teamSelector(page), PERSONAL_TEAM);
     await expect(
       modelRow(page, ungrantedModelName),
-      "the personal view still renders models after a reload rather than coming back empty",
+      "switching back to the personal team restores models outside the selected team",
     ).toHaveCount(1, { timeout: 30_000 });
   });
 });

From 5a9fe56aff9ac8e3136f7faeb40891718262e3a3 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:24:05 +0000
Subject: [PATCH 32/67] fix(responses): count custom-tool and MCP argument
 deltas in the streamed usage fallback

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 11 +++++++-
 .../responses/test_streaming_iterator.py      | 28 +++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 6cf36e3e660..df3c26c1a4f 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -356,7 +356,7 @@ class BaseResponsesAPIStreamingIterator:
                     _delta: Final = getattr(openai_responses_api_chunk, "delta", None)
                     if isinstance(_delta, str):
                         self._generated_content += _delta
-                elif _event_type == ResponsesAPIStreamEvents.FUNCTION_CALL_ARGUMENTS_DELTA:
+                elif _event_type in _TOOL_ARGUMENTS_DELTA_EVENTS:
                     _args_delta: Final = getattr(openai_responses_api_chunk, "delta", None)
                     if isinstance(_args_delta, str):
                         self._generated_tool_arguments += _args_delta
@@ -1358,6 +1358,15 @@ def _usage_as_model(usage: object) -> ResponseAPIUsage | None:
         return None
 
 
+_TOOL_ARGUMENTS_DELTA_EVENTS: Final = frozenset(
+    {
+        ResponsesAPIStreamEvents.FUNCTION_CALL_ARGUMENTS_DELTA,
+        ResponsesAPIStreamEvents.CUSTOM_TOOL_CALL_INPUT_DELTA,
+        ResponsesAPIStreamEvents.MCP_CALL_ARGUMENTS_DELTA,
+    }
+)
+
+
 def _estimate_usage_from_text(
     model: str,
     request_input: object,
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index 234e63ca3be..7bd03863717 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -816,3 +816,31 @@ async def test_completed_event_survives_a_failing_usage_estimate():
 
     assert yielded
     assert iterator.completed_response.response.usage is None
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "tool_delta_event_type",
+    ["response.custom_tool_call_input.delta", "response.mcp_call_arguments.delta"],
+)
+async def test_completed_event_without_usage_counts_tool_input_deltas(tool_delta_event_type):
+    """Custom-tool and MCP argument deltas feed the streamed usage fallback the
+    same way function_call_arguments deltas do."""
+    response = _responses_api_response_without_usage()
+    iterator = _make_iterator(
+        sse_events=[
+            _sse_event({"type": tool_delta_event_type, "delta": '{"query": "weather in sf"}'}),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=_mock_config_with_completed_response(response),
+        request_data={"input": "what is the weather in san francisco"},
+    )
+
+    async for _ in iterator:
+        pass
+
+    usage = iterator.completed_response.response.usage
+    assert usage is not None
+    assert usage.output_tokens > 0
+    assert usage.total_tokens == usage.input_tokens + usage.output_tokens

From a6d2332f7a19822ada77c4fd2cc13b853d1f9cad Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:24:35 +0000
Subject: [PATCH 33/67] test(responses): drive the usage-estimate failure path
 without patching litellm

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../responses/test_streaming_iterator.py      | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index 7bd03863717..d3849e6ffce 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -17,6 +17,7 @@ from litellm.llms.base_llm.responses.transformation import BaseResponsesAPIConfi
 from litellm.responses.streaming_iterator import (
     ResponsesAPIStreamingIterator,
     SyncResponsesAPIStreamingIterator,
+    _estimate_usage_from_text,
 )
 from litellm.types.llms.openai import (
     ResponseAPIUsage,
@@ -796,8 +797,13 @@ async def test_completed_event_without_usage_counts_multimodal_input_as_messages
 
 @pytest.mark.asyncio
 async def test_completed_event_survives_a_failing_usage_estimate():
-    """A raising token_counter must not break a stream that previously completed:
-    the estimate is best-effort and falls back to usage None."""
+    """A malformed request input that makes the message transformer raise must not
+    break a stream that previously completed: the estimate is best-effort and
+    falls back to usage None."""
+    malformed_input: Final = [{"type": "message", "role": "user", "content": 42}]
+    with pytest.raises(ValueError):
+        _estimate_usage_from_text("gpt-4o-mini", malformed_input, {"input": malformed_input}, "hello world")
+
     response = _responses_api_response_without_usage()
     iterator = _make_iterator(
         sse_events=[
@@ -806,13 +812,12 @@ async def test_completed_event_survives_a_failing_usage_estimate():
         ],
         logging_obj=_logging_obj_stub(),
         config=_mock_config_with_completed_response(response),
-        request_data={"input": "count these input tokens please"},
+        request_data={"input": malformed_input},
     )
 
-    with patch.object(litellm, "token_counter", side_effect=RuntimeError("tokenizer exploded")):
-        yielded: list = []
-        async for chunk in iterator:
-            yielded.append(chunk)
+    yielded: list = []
+    async for chunk in iterator:
+        yielded.append(chunk)
 
     assert yielded
     assert iterator.completed_response.response.usage is None

From 45d5e6b8336fa4383e0615d2c1020ebeca34aab6 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 18:26:44 -0700
Subject: [PATCH 34/67] fix(e2e): start cache CI service and count bypass calls

---
 .github/workflows/test-provider-cache.yml     |  8 +++----
 .../test_provider_cache.py                    | 23 +++++++++++++++++++
 tests/e2e/provider_edge.py                    |  1 +
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/test-provider-cache.yml b/.github/workflows/test-provider-cache.yml
index 29b9d08a267..0507f90cf89 100644
--- a/.github/workflows/test-provider-cache.yml
+++ b/.github/workflows/test-provider-cache.yml
@@ -24,7 +24,7 @@ jobs:
         ports:
           - 6379:6379
         options: >-
-          --health-cmd 'redis-cli ping'
+          --health-cmd "redis-cli ping"
           --health-interval 5s
           --health-timeout 3s
           --health-retries 10
@@ -35,10 +35,10 @@ jobs:
       E2E_PROVIDER_CACHE: '0'
       E2E_FIXTURE_MODE: live
     steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           persist-credentials: false
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: '3.13'
       - uses: ./.github/actions/setup-uv-with-retries
@@ -56,7 +56,7 @@ jobs:
           -q --junitxml=provider-cache-results.xml
       - name: Save test results
         if: always()
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
         with:
           name: provider-cache-results
           path: provider-cache-results.xml
diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 7edca8151af..d0e8c5296dc 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -11,8 +11,10 @@ from collections.abc import Generator
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
 from dataclasses import dataclass, replace
+from http.client import HTTPConnection
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import Final
+from urllib.parse import urlsplit
 
 import pytest
 from e2e_http import NetworkError, PreparedForward, RawResponse, StreamChunk, StreamHead, forward, prepare_forward
@@ -407,3 +409,24 @@ def test_enabled_environment_reuses_store_across_fresh_backends(
         assert configured_cache_backend() is None
     finally:
         configured_cache.cache_clear()
+
+
+def test_duplicate_headers_bypass_cache_and_count_live_calls(store: RedisResponseStore, provider: Provider) -> None:
+    cache: Final = CacheEdge(store, SECRET)
+    with edge(cache, provider) as url:
+        parsed: Final = urlsplit(url)
+        for _ in range(2):
+            connection = HTTPConnection(str(parsed.hostname), parsed.port, timeout=5)
+            try:
+                connection.putrequest("POST", parsed.path)
+                connection.putheader("content-length", str(len(BODY)))
+                connection.putheader("content-type", "application/json")
+                connection.putheader("x-duplicate", "first")
+                connection.putheader("x-duplicate", "second")
+                connection.endheaders(BODY)
+                assert connection.getresponse().read() == SUCCESS
+            finally:
+                connection.close()
+    assert len(provider.hits) == 2
+    assert dict(cache.counters.counts)["duplicate_header_bypass"] == 2
+    assert dict(cache.counters.counts)["upstream_attempts"] == 2
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index 49d574ee957..053a2b5c0d3 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -891,6 +891,7 @@ class _EdgeHandler(BaseHTTPRequestHandler):
         )
         if isinstance(edge_server.backend, CacheEdge) and duplicate_headers:
             edge_server.backend.counters.increment("duplicate_header_bypass")
+            edge_server.backend.counters.increment("upstream_attempts")
         outcome: Final = handle_edge_request(
             selected_backend,
             edge_server.mounts,

From 10aef224e7acc6a5f47c77d63c7a98f81728f377 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:34:28 +0000
Subject: [PATCH 35/67] style(anthropic): apply repository conventions to the
 missing-usage change

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/types/llms/anthropic.py                              | 2 +-
 .../llms/anthropic/chat/test_anthropic_chat_handler.py       | 5 ++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/litellm/types/llms/anthropic.py b/litellm/types/llms/anthropic.py
index ecb8dbb2502..bcdee86360e 100644
--- a/litellm/types/llms/anthropic.py
+++ b/litellm/types/llms/anthropic.py
@@ -586,7 +586,7 @@ class MessageBlockDelta(TypedDict):
 
     type: Literal["message_delta"]
     delta: MessageDelta
-    usage: NotRequired[UsageDelta]
+    usage: NotRequired[ReadOnly[UsageDelta]]
     context_management: NotRequired[ContextManagementResponse]
 
 
diff --git a/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py b/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
index ac05cdcf251..32c98a83948 100644
--- a/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
+++ b/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
@@ -580,10 +580,9 @@ def test_text_only_streaming_has_index_zero():
 
 
 def test_message_delta_without_usage_returns_chunk_with_no_usage():
-    """A message_delta event may carry no usage field; it must not raise."""
-    iterator = ModelResponseIterator(None, sync_stream=True)
+    iterator: Final = ModelResponseIterator(None, sync_stream=True)
 
-    model_response = iterator.chunk_parser(
+    model_response: Final = iterator.chunk_parser(
         {
             "type": "message_delta",
             "delta": {"stop_reason": "end_turn", "stop_sequence": None},

From 8d625d0400befd2043806d71caec103c68489be0 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 25 Aug 2026 19:43:01 +0000
Subject: [PATCH 36/67] fix(xai): keep 'instructions' on the xAI Responses API
 so system messages survive web_search bridging

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/llms/xai/responses/transformation.py  | 29 ++--------
 .../test_xai_responses_transformation.py      | 12 ++--
 .../xai/xai_responses/test_transformation.py  | 12 ++--
 .../test_xai_responses_auto_routing.py        | 56 ++++++++++++++++++-
 4 files changed, 71 insertions(+), 38 deletions(-)

diff --git a/litellm/llms/xai/responses/transformation.py b/litellm/llms/xai/responses/transformation.py
index 1f977a66186..2f638da49c8 100644
--- a/litellm/llms/xai/responses/transformation.py
+++ b/litellm/llms/xai/responses/transformation.py
@@ -49,7 +49,6 @@ class XAIResponsesAPIConfig(OpenAIResponsesAPIConfig):
 
     Inherits from OpenAIResponsesAPIConfig since XAI's Responses API is largely
     compatible with OpenAI's, with a few differences:
-    - Does not support the 'instructions' parameter
     - Requires code_interpreter tools to have 'container' field removed
     - Recommends store=false when sending images
 
@@ -60,20 +59,6 @@ class XAIResponsesAPIConfig(OpenAIResponsesAPIConfig):
     def custom_llm_provider(self) -> LlmProviders:
         return LlmProviders.XAI
 
-    def get_supported_openai_params(self, model: str) -> list:
-        """
-        Get supported parameters for XAI Responses API.
-
-        XAI supports most OpenAI Responses API params except 'instructions'.
-        """
-        supported_params: Final = super().get_supported_openai_params(model)
-
-        # Remove 'instructions' as it's not supported by XAI
-        if "instructions" in supported_params:
-            supported_params.remove("instructions")
-
-        return supported_params
-
     def _transform_web_search_tool(self, tool: Mapping[str, object]) -> Mapping[str, object]:
         """
         Transform web_search tool to XAI format.
@@ -158,19 +143,13 @@ class XAIResponsesAPIConfig(OpenAIResponsesAPIConfig):
         Map parameters for XAI Responses API.
 
         Handles XAI-specific transformations:
-        1. Drops 'instructions' parameter (not supported)
-        2. Transforms code_interpreter tools to remove 'container' field
-        3. Transforms web_search tools to XAI format (removes search_context_size, adds filters)
-        4. Transforms x_search tools to XAI format
-        5. Sets store=false when images are detected (recommended by XAI)
+        1. Transforms code_interpreter tools to remove 'container' field
+        2. Transforms web_search tools to XAI format (removes search_context_size, adds filters)
+        3. Transforms x_search tools to XAI format
+        4. Sets store=false when images are detected (recommended by XAI)
         """
         params: Final = dict(response_api_optional_params)
 
-        # Drop instructions parameter (not supported by XAI)
-        if "instructions" in params:
-            verbose_logger.debug("XAI Responses API does not support 'instructions' parameter. Dropping it.")
-            params.pop("instructions")
-
         if "metadata" in params:
             verbose_logger.debug("XAI Responses API does not support 'metadata' parameter. Dropping it.")
             params.pop("metadata")
diff --git a/tests/test_litellm/llms/xai/responses/test_xai_responses_transformation.py b/tests/test_litellm/llms/xai/responses/test_xai_responses_transformation.py
index e3feb7d5342..34ad4b9075d 100644
--- a/tests/test_litellm/llms/xai/responses/test_xai_responses_transformation.py
+++ b/tests/test_litellm/llms/xai/responses/test_xai_responses_transformation.py
@@ -51,23 +51,23 @@ class TestXAIResponsesAPITransformation:
         assert result["tools"][0]["type"] == "code_interpreter"
         assert "container" not in result["tools"][0], "Container field should be removed"
 
-    def test_instructions_parameter_dropped(self):
-        """Test that instructions parameter is dropped for XAI"""
+    def test_instructions_parameter_forwarded(self):
+        """xAI supports 'instructions' on /v1/responses, so it must survive param mapping"""
         config = XAIResponsesAPIConfig()
 
         params = ResponsesAPIOptionalRequestParams(instructions="You are a helpful assistant.", temperature=0.7)
 
         result = config.map_openai_params(response_api_optional_params=params, model="grok-4-fast", drop_params=False)
 
-        assert "instructions" not in result, "Instructions should be dropped"
+        assert result.get("instructions") == "You are a helpful assistant."
         assert result.get("temperature") == 0.7, "Other params should be preserved"
 
-    def test_supported_params_excludes_instructions(self):
-        """Test that get_supported_openai_params excludes instructions"""
+    def test_supported_params_includes_instructions(self):
+        """A system message bridged to 'instructions' must not be rejected for xAI"""
         config = XAIResponsesAPIConfig()
         supported = config.get_supported_openai_params("grok-4-fast")
 
-        assert "instructions" not in supported, "instructions should not be supported"
+        assert "instructions" in supported, "instructions should be supported"
         assert "tools" in supported, "tools should be supported"
         assert "temperature" in supported, "temperature should be supported"
         assert "model" in supported, "model should be supported"
diff --git a/tests/test_litellm/llms/xai/xai_responses/test_transformation.py b/tests/test_litellm/llms/xai/xai_responses/test_transformation.py
index c783918ca06..3ea3fe631bd 100644
--- a/tests/test_litellm/llms/xai/xai_responses/test_transformation.py
+++ b/tests/test_litellm/llms/xai/xai_responses/test_transformation.py
@@ -53,8 +53,8 @@ class TestXAIResponsesAPITransformation:
             "container" not in result["tools"][0]
         ), "Container field should be removed"
 
-    def test_instructions_parameter_dropped(self):
-        """Test that instructions parameter is dropped for XAI"""
+    def test_instructions_parameter_forwarded(self):
+        """xAI supports 'instructions' on /v1/responses, so it must survive param mapping"""
         config = XAIResponsesAPIConfig()
 
         params = ResponsesAPIOptionalRequestParams(
@@ -65,15 +65,15 @@ class TestXAIResponsesAPITransformation:
             response_api_optional_params=params, model="grok-4-fast", drop_params=False
         )
 
-        assert "instructions" not in result, "Instructions should be dropped"
+        assert result.get("instructions") == "You are a helpful assistant."
         assert result.get("temperature") == 0.7, "Other params should be preserved"
 
-    def test_supported_params_excludes_instructions(self):
-        """Test that get_supported_openai_params excludes instructions"""
+    def test_supported_params_includes_instructions(self):
+        """A system message bridged to 'instructions' must not be rejected for xAI"""
         config = XAIResponsesAPIConfig()
         supported = config.get_supported_openai_params("grok-4-fast")
 
-        assert "instructions" not in supported, "instructions should not be supported"
+        assert "instructions" in supported, "instructions should be supported"
         assert "tools" in supported, "tools should be supported"
         assert "temperature" in supported, "temperature should be supported"
         assert "model" in supported, "model should be supported"
diff --git a/tests/test_litellm/test_xai_responses_auto_routing.py b/tests/test_litellm/test_xai_responses_auto_routing.py
index fbf2453d7fb..d405ea1e6c6 100644
--- a/tests/test_litellm/test_xai_responses_auto_routing.py
+++ b/tests/test_litellm/test_xai_responses_auto_routing.py
@@ -2,14 +2,30 @@
 Test automatic routing to xAI Responses API when tools are present
 """
 
+import json
+from collections.abc import Mapping
+from typing import Final
 from unittest.mock import MagicMock, patch
 
-
+import httpx
 import pytest
 import litellm
+from litellm.llms.custom_httpx.http_handler import HTTPHandler
 from litellm.main import responses_api_bridge_check
 
 
+class _RecordingResponsesHandler:
+    """MockTransport handler that serves a canned /responses reply and keeps the body xAI would have received"""
+
+    def __init__(self, reply: Mapping[str, object]) -> None:
+        self.reply: Final = reply
+        self.request_body: Mapping[str, object] | None = None
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.request_body = json.loads(request.content)
+        return httpx.Response(200, json=dict(self.reply), request=request)
+
+
 class TestXAIResponsesAutoRouting:
     """Test that xAI requests with tools automatically route to Responses API"""
 
@@ -254,6 +270,44 @@ class TestXAIResponsesAutoRouting:
         # Note: This test may need adjustment based on actual mock_response behavior
         # The key is that the responses_api_bridge_check logic routes correctly
 
+    def test_system_message_survives_web_search_bridge(self):
+        """A system message becomes 'instructions' on the bridged /responses call, and xAI accepts it"""
+        handler: Final = _RecordingResponsesHandler(
+            reply={
+                "id": "resp_test",
+                "object": "response",
+                "created_at": 0,
+                "status": "completed",
+                "model": "grok-4.6",
+                "output": [
+                    {
+                        "type": "message",
+                        "id": "msg_test",
+                        "status": "completed",
+                        "role": "assistant",
+                        "content": [{"type": "output_text", "text": "1.0.0", "annotations": []}],
+                    }
+                ],
+                "usage": {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
+            }
+        )
+
+        response: Final = litellm.completion(
+            model="xai/grok-4.6",
+            messages=[
+                {"role": "system", "content": "Answer briefly."},
+                {"role": "user", "content": "newest litellm version?"},
+            ],
+            web_search_options={"search_context_size": "medium"},
+            api_key="fake-key",
+            client=HTTPHandler(client=httpx.Client(transport=httpx.MockTransport(handler))),
+        )
+
+        assert response.choices[0].message.content == "1.0.0"
+        assert handler.request_body is not None
+        assert handler.request_body["instructions"] == "Answer briefly."
+        assert handler.request_body["tools"] == [{"type": "web_search"}]
+
 
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

From 8352045f32840642f2dd89d9e39a5bd41c6d6bd2 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:39:24 +0000
Subject: [PATCH 37/67] style(fireworks-ai): apply repository conventions to
 the cost component change

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/llms/fireworks_ai/cost_calculator.py  | 31 +++++-----
 .../test_fireworks_ai_cost_calculator.py      | 62 ++++++++++++-------
 2 files changed, 57 insertions(+), 36 deletions(-)

diff --git a/litellm/llms/fireworks_ai/cost_calculator.py b/litellm/llms/fireworks_ai/cost_calculator.py
index f323d78e22d..a92e5208471 100644
--- a/litellm/llms/fireworks_ai/cost_calculator.py
+++ b/litellm/llms/fireworks_ai/cost_calculator.py
@@ -68,24 +68,25 @@ def _resolve_model_info(model: str) -> ModelInfo:
 
 
 def _with_cache_read_fallback(model_info: ModelInfo) -> ModelInfo:
-    """Most fireworks_ai price-map entries publish no cache-read rate, and the provider bills
-    cached reads at the input rate. generic_cost_per_token prices a missing rate at $0, so the
-    fallback is written into a copy of the entry (the shared model-cost dict must not be
-    mutated), including inside off_peak_pricing so cached reads track the off-peak input rate
-    the way the previous calculator did."""
-    if model_info.get("cache_read_input_token_cost") is not None:
-        return model_info
+    """Most fireworks_ai price-map entries publish no cache-read rate though the provider bills
+    cached reads at the input rate; the shared map is never mutated, so a copy carries the fallback."""
     input_rate: Final = model_info.get("input_cost_per_token")
-    if input_rate is None:
+    if model_info.get("cache_read_input_token_cost") is not None or input_rate is None:
         return model_info
-    effective: Final[dict[str, object]] = dict(model_info)
-    effective["cache_read_input_token_cost"] = input_rate
     off_peak: Final = model_info.get("off_peak_pricing")
-    if off_peak is not None and "cache_read_input_token_cost" not in off_peak:
-        off_peak_copy: Final[dict[str, object]] = dict(off_peak)
-        off_peak_copy["cache_read_input_token_cost"] = off_peak_copy.get("input_cost_per_token", input_rate)
-        effective["off_peak_pricing"] = off_peak_copy
-    return cast(ModelInfo, effective)
+    if off_peak is None or "cache_read_input_token_cost" in off_peak:
+        return cast(ModelInfo, {**model_info, "cache_read_input_token_cost": input_rate})
+    return cast(
+        ModelInfo,
+        {
+            **model_info,
+            "cache_read_input_token_cost": input_rate,
+            "off_peak_pricing": {
+                **off_peak,
+                "cache_read_input_token_cost": off_peak.get("input_cost_per_token", input_rate),
+            },
+        },
+    )
 
 
 def cost_per_token(model: str, usage: Usage, current_time: datetime | None = None) -> tuple[float, float]:
diff --git a/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py b/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
index 0ad5eddcc7a..f461f17b627 100644
--- a/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
+++ b/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
@@ -1,5 +1,6 @@
 import math
 from datetime import datetime, timezone
+from typing import Final
 
 import pytest
 
@@ -51,13 +52,16 @@ STANDARD_CACHE_READ_COST = 1.5e-08
 def _register_off_peak_model(
     off_peak_pricing: OffPeakPricing, cache_read_cost: float | None = STANDARD_CACHE_READ_COST
 ) -> None:
-    litellm.model_cost[f"fireworks_ai/{OFF_PEAK_MODEL}"] = {
-        "litellm_provider": "fireworks_ai",
-        "mode": "chat",
-        "input_cost_per_token": STANDARD_INPUT_COST,
-        "output_cost_per_token": STANDARD_OUTPUT_COST,
-        "off_peak_pricing": off_peak_pricing,
-        **({} if cache_read_cost is None else {"cache_read_input_token_cost": cache_read_cost}),
+    litellm.model_cost = {  # test-quality-ok: the save/restore conftest returns litellm.model_cost to the original object after each test, so replacing the map for this entry leaks nothing
+        **litellm.model_cost,
+        f"fireworks_ai/{OFF_PEAK_MODEL}": {
+            "litellm_provider": "fireworks_ai",
+            "mode": "chat",
+            "input_cost_per_token": STANDARD_INPUT_COST,
+            "output_cost_per_token": STANDARD_OUTPUT_COST,
+            "off_peak_pricing": off_peak_pricing,
+            **({} if cache_read_cost is None else {"cache_read_input_token_cost": cache_read_cost}),
+        },
     }
 
 
@@ -145,20 +149,19 @@ COMPONENT_AUDIO_OUT_COST = 6e-06
 
 
 def test_cache_write_reasoning_and_audio_tokens_are_billed_at_their_component_rates():
-    """Regression (LIT-7837): the hand-rolled fireworks_ai calculator billed every
-    cache-creation, reasoning and audio token at $0. The shared calculator treats the
-    prompt detail counts as subsets of prompt_tokens and the completion detail counts as
-    subsets of completion_tokens, billing each remainder at the text rate."""
-    litellm.model_cost[f"fireworks_ai/{COMPONENT_MODEL}"] = {
-        "litellm_provider": "fireworks_ai",
-        "mode": "chat",
-        "input_cost_per_token": COMPONENT_INPUT_COST,
-        "output_cost_per_token": COMPONENT_OUTPUT_COST,
-        "cache_read_input_token_cost": COMPONENT_CACHE_READ_COST,
-        "cache_creation_input_token_cost": COMPONENT_CACHE_CREATION_COST,
-        "output_cost_per_reasoning_token": COMPONENT_REASONING_COST,
-        "input_cost_per_audio_token": COMPONENT_AUDIO_IN_COST,
-        "output_cost_per_audio_token": COMPONENT_AUDIO_OUT_COST,
+    litellm.model_cost = {  # test-quality-ok: the save/restore conftest returns litellm.model_cost to the original object after each test, so replacing the map for this entry leaks nothing
+        **litellm.model_cost,
+        f"fireworks_ai/{COMPONENT_MODEL}": {
+            "litellm_provider": "fireworks_ai",
+            "mode": "chat",
+            "input_cost_per_token": COMPONENT_INPUT_COST,
+            "output_cost_per_token": COMPONENT_OUTPUT_COST,
+            "cache_read_input_token_cost": COMPONENT_CACHE_READ_COST,
+            "cache_creation_input_token_cost": COMPONENT_CACHE_CREATION_COST,
+            "output_cost_per_reasoning_token": COMPONENT_REASONING_COST,
+            "input_cost_per_audio_token": COMPONENT_AUDIO_IN_COST,
+            "output_cost_per_audio_token": COMPONENT_AUDIO_OUT_COST,
+        },
     }
     usage = Usage(
         prompt_tokens=1000,
@@ -188,3 +191,20 @@ def test_cache_write_reasoning_and_audio_tokens_are_billed_at_their_component_ra
     )
     assert prompt_cost == pytest.approx(expected_prompt_cost)
     assert completion_cost == pytest.approx(expected_completion_cost)
+
+
+def test_an_entry_without_an_input_rate_gets_no_cache_read_fallback():
+    litellm.model_cost = {  # test-quality-ok: the save/restore conftest returns litellm.model_cost to the original object after each test, so replacing the map for this entry leaks nothing
+        **litellm.model_cost,  # pyright: ignore[reportUnknownMemberType]  # the SDK types model_cost as dict[Unknown, Unknown]
+        "fireworks_ai/accounts/fireworks/models/no-input-rate-test": {
+            "litellm_provider": "fireworks_ai",
+            "mode": "chat",
+            "output_cost_per_token": 2e-06,
+        },
+    }
+    usage: Final = _usage(prompt_tokens=1000, cached_tokens=300, completion_tokens=200)
+
+    prompt_cost, completion_cost = cost_per_token(model="accounts/fireworks/models/no-input-rate-test", usage=usage)
+
+    assert prompt_cost == 0
+    assert completion_cost == 200 * 2e-06

From c4c96180e301179259236953ab0a62e3008fcd95 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:42:36 +0000
Subject: [PATCH 38/67] fix(gemini): strip version suffix from modelVersion and
 keep it on blocked streams

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../vertex_and_google_ai_studio_gemini.py     | 18 +++++++---
 ...test_vertex_and_google_ai_studio_gemini.py | 33 +++++++++++++++++++
 2 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py
index eb03b17435c..b4712fd376b 100644
--- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py
+++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py
@@ -124,6 +124,12 @@ def _unsupported_reasoning_effort(reasoning_effort: str) -> UnsupportedParamsErr
     )
 
 
+def _served_model_name(model_version: object) -> str | None:
+    if not isinstance(model_version, str) or not model_version:
+        return None
+    return model_version.split("@", 1)[0]
+
+
 class VertexAIBaseConfig:
     def get_mapped_special_auth_params(self) -> dict:
         """
@@ -1951,6 +1957,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig):
     def _check_prompt_level_content_filter(
         processed_chunk: GenerateContentResponseBody,
         response_id: str | None,
+        model: str | None = None,
     ) -> Optional["ModelResponseStream"]:
         """
         Check if prompt is blocked due to content filtering at the prompt level.
@@ -1990,7 +1997,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig):
                 enhancements=None,
             )
 
-            model_response: Final = ModelResponseStream(choices=[choice], id=response_id)
+            model_response: Final = ModelResponseStream(choices=[choice], id=response_id, model=model)
             return model_response
 
         return None
@@ -2434,8 +2441,8 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig):
             completion_response = GenerateContentResponseBody(**completion_response)
 
         ## GET MODEL ##
-        model_version: Final = completion_response.get("modelVersion")
-        model_response.model = model_version if isinstance(model_version, str) else model
+        served: Final = _served_model_name(completion_response.get("modelVersion"))
+        model_response.model = served if served is not None else model
 
         ## CHECK IF RESPONSE FLAGGED
         if "promptFeedback" in completion_response and "blockReason" in completion_response["promptFeedback"]:
@@ -3265,17 +3272,18 @@ class ModelResponseIterator:
 
             processed_chunk: Final = GenerateContentResponseBody(**chunk)
             response_id: Final = processed_chunk.get("responseId")
-            chunk_model_version: Final = processed_chunk.get("modelVersion")
+            served: Final = _served_model_name(processed_chunk.get("modelVersion"))
             model_response = ModelResponseStream(
                 choices=[],
                 id=response_id,
-                model=chunk_model_version if isinstance(chunk_model_version, str) else None,
+                model=served,
             )
 
             # Check if prompt is blocked due to content filtering
             blocked_response: Final = VertexGeminiConfig._check_prompt_level_content_filter(
                 processed_chunk=processed_chunk,
                 response_id=response_id,
+                model=served,
             )
             if blocked_response is not None:
                 model_response = blocked_response
diff --git a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
index cd0ed0057c0..001105fc53d 100644
--- a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
+++ b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py
@@ -5926,3 +5926,36 @@ def test_served_model_version_reaches_assembled_stream_through_custom_stream_wra
         assert chunk._hidden_params["provider_response_model"] == served_model
     assembled: Final = litellm.stream_chunk_builder(chunks=list(chunks), messages=[{"role": "user", "content": "hi"}])
     assert assembled._hidden_params["provider_response_model"] == served_model
+
+
+def test_generate_content_transform_strips_version_suffix_from_model_version():
+    import httpx
+
+    body: Final = {**_generate_content_body(), "modelVersion": "gemini-3.8-flash-001@default"}
+    response: Final = VertexGeminiConfig()._transform_google_generate_content_to_openai_model_response(
+        completion_response=body,
+        model_response=ModelResponse(),
+        model="gemini-3.8-flash",
+        logging_obj=MagicMock(),
+        raw_response=httpx.Response(200, headers={}),
+    )
+
+    assert response.model == "gemini-3.8-flash-001"
+
+
+def test_prompt_blocked_chunk_keeps_served_model_version():
+    from litellm.llms.vertex_ai.gemini.vertex_and_google_ai_studio_gemini import (
+        ModelResponseIterator,
+    )
+
+    chunk: Final = {
+        "promptFeedback": {"blockReason": "SAFETY", "blockReasonMessage": "prompt was blocked"},
+        "modelVersion": "gemini-3.8-flash-001",
+        "responseId": "resp-1",
+    }
+    iterator: Final = ModelResponseIterator(streaming_response=[], sync_stream=True, logging_obj=MagicMock())
+
+    streaming_chunk: Final = iterator.chunk_parser(chunk)
+
+    assert streaming_chunk.model == "gemini-3.8-flash-001"
+    assert streaming_chunk.choices[0].finish_reason == "content_filter"

From 091a38cce6b569439e116e8be5f493f06a0974de Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:43:08 +0000
Subject: [PATCH 39/67] test(anthropic): import Final for the annotated locals

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llms/anthropic/chat/test_anthropic_chat_handler.py           | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py b/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
index 32c98a83948..c3400dc40c3 100644
--- a/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
+++ b/tests/test_litellm/llms/anthropic/chat/test_anthropic_chat_handler.py
@@ -1,6 +1,7 @@
 import json
 import threading
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx

From 91c7f758640b5d60c3fcfd9e51bcd1770a74fd25 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:44:30 +0000
Subject: [PATCH 40/67] docs(fireworks-ai): describe the cache-read fallback
 without asserting provider billing

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/llms/fireworks_ai/cost_calculator.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/litellm/llms/fireworks_ai/cost_calculator.py b/litellm/llms/fireworks_ai/cost_calculator.py
index a92e5208471..1795a700d25 100644
--- a/litellm/llms/fireworks_ai/cost_calculator.py
+++ b/litellm/llms/fireworks_ai/cost_calculator.py
@@ -68,8 +68,8 @@ def _resolve_model_info(model: str) -> ModelInfo:
 
 
 def _with_cache_read_fallback(model_info: ModelInfo) -> ModelInfo:
-    """Most fireworks_ai price-map entries publish no cache-read rate though the provider bills
-    cached reads at the input rate; the shared map is never mutated, so a copy carries the fallback."""
+    """Entries without a cache-read rate keep the previous calculator's input-rate fallback for cached
+    reads (LIT-7845 tracks the documented discount); the shared map is never mutated, so a copy carries it."""
     input_rate: Final = model_info.get("input_cost_per_token")
     if model_info.get("cache_read_input_token_cost") is not None or input_rate is None:
         return model_info

From aa15e9f23f2d5a1fe46ed782d1605c3840a28d04 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 18:45:43 -0700
Subject: [PATCH 41/67] test(e2e): reject expired cache entries before physical
 eviction

---
 .../test_provider_cache.py                    | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index d0e8c5296dc..9a4cba7f322 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -192,6 +192,29 @@ def test_concurrent_requests_publish_atomically(store: RedisResponseStore, provi
     assert len(provider.hits) == 1
 
 
+@pytest.mark.parametrize("age_past_expiry_ms", [0, 1])
+def test_expired_response_is_rejected_without_physical_eviction(
+    store: RedisResponseStore, age_past_expiry_ms: int,
+) -> None:
+    response_key: Final = store.keys("expired")[0]
+    retained: Final = store.client.eval(
+        """
+local clock = redis.call('TIME')
+local expires = clock[1] * 1000 + math.floor(clock[2] / 1000) - tonumber(ARGV[1])
+redis.call('HSET', KEYS[1], 'captured', expires - 86400000, 'expires', expires, 'payload', 'old-response')
+return redis.call('PTTL', KEYS[1])
+""",
+        1, response_key, age_past_expiry_ms,
+    )
+    assert retained == -1
+    replacement: Final = store.lookup("expired")
+    assert isinstance(replacement, CaptureLease)
+    assert replacement.expires_at_ms - replacement.captured_at_ms == 86_400_000
+    assert store.publish("expired", replacement, b"fresh-response")
+    hit: Final = store.lookup("expired")
+    assert isinstance(hit, CacheHit) and hit.payload == b"fresh-response"
+
+
 @pytest.mark.parametrize("truncated", [False, True])
 def test_stream_completion_controls_publication(store: RedisResponseStore, provider: Provider, truncated: bool) -> None:
     provider.stream = True

From 7ed20406d7c2f7df3ebfce179769dd6ce26a5383 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 01:47:45 +0000
Subject: [PATCH 42/67] test(responses): narrow the ValueError assertion to
 satisfy PT011

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/test_litellm/responses/test_streaming_iterator.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index d3849e6ffce..8a76b0bedff 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -801,7 +801,7 @@ async def test_completed_event_survives_a_failing_usage_estimate():
     break a stream that previously completed: the estimate is best-effort and
     falls back to usage None."""
     malformed_input: Final = [{"type": "message", "role": "user", "content": 42}]
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match="Invalid content type"):
         _estimate_usage_from_text("gpt-4o-mini", malformed_input, {"input": malformed_input}, "hello world")
 
     response = _responses_api_response_without_usage()

From 97211bc356d47d39214311e7cea432f858d28445 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 19:00:47 -0700
Subject: [PATCH 43/67] fix(mcp): authorize per-user OAuth credential writes

---
 .../mcp_server/bridge_token_flow.py           |  64 +++++--
 .../mcp_server/discoverable_endpoints.py      |  24 ++-
 .../mcp_server/ui_session_utils.py            |  13 ++
 litellm/proxy/auth/handle_jwt.py              | 172 +++++++++++++-----
 litellm/proxy/auth/user_api_key_auth.py       |  37 +---
 .../mcp_management_endpoints.py               |  10 +-
 .../mcp_server/test_discoverable_endpoints.py | 157 +++++++++++++++-
 .../proxy/auth/test_handle_jwt.py             |   8 +-
 8 files changed, 369 insertions(+), 116 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index b693cc046c8..962e39d7dd6 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -304,24 +304,55 @@ async def _revalidate_active_subject(identity: "EnvelopeIdentity") -> "_KeyResol
             assert_never(identity.subject_type)
 
 
-async def _extract_user_id_from_request(request: Request) -> str | None:
-    """The litellm ``user_id`` for the token request, so a per-user token is stored under the same
-    identity the egress later reads it by. Storage is best-effort, so every non-resolved outcome
-    (including a transient DB outage) collapses to ``None`` here and the caller simply skips the store;
-    the bridge mint, which must status those outcomes differently, consumes
-    :func:`_resolve_active_litellm_key` directly."""
+async def _extract_user_id_from_request(request: Request, server_id: str | None = None) -> str | None:
+    """Resolve identity for binding, or authorize the credential-write action for a target server."""
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import (  # noqa: PLC0415  # registry imports auth helpers
+        global_mcp_server_manager,
+    )
+    from litellm.proxy._experimental.mcp_server.ui_session_utils import (
+        can_access_mcp_server,  # noqa: PLC0415  # proxy import cycle
+    )
+    from litellm.proxy._types import UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.handle_jwt import JWTHandler  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.route_checks import RouteChecks  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
+        _run_centralized_common_checks,  # pyright: ignore[reportPrivateUsage]  # reuse admission policy for the credential-write action
+    )
 
     token: Final = _litellm_key_from_request(request)
-    if token is not None and JWTHandler.is_jwt(token):
-        return await _extract_jwt_user_id(request, token)
-    resolved: Final = await _resolve_active_litellm_key(request)
-    if not isinstance(resolved, _ResolvedKey):
+    # The OAuth relay is public; the optional server-side write is the same protected action
+    # as the direct credential endpoint. Authorize that action without rewriting the Request.
+    write_route: Final = f"/v1/mcp/server/{server_id}/oauth-user-credential" if server_id is not None else None
+    resolved: Final = (
+        await _resolve_jwt_auth(request, token, write_route)
+        if token is not None and JWTHandler.is_jwt(token)
+        else await _resolve_active_litellm_key(request)
+    )
+    auth: Final = resolved.key if isinstance(resolved, _ResolvedKey) else resolved
+    if not isinstance(auth, UserAPIKeyAuth) or not _active_key_user_id(auth):
         return None
-    return _active_key_user_id(resolved.key)
+    if write_route is not None and server_id is not None:
+        try:
+            RouteChecks.is_virtual_key_allowed_to_call_route(route=write_route, valid_token=auth, request=request)
+            await _run_centralized_common_checks(
+                user_api_key_auth_obj=auth,
+                request=request,
+                request_data={},
+                route=write_route,
+            )
+            if not await can_access_mcp_server(auth, server_id, global_mcp_server_manager.get_allowed_mcp_servers):
+                return None
+        except Exception as exc:  # noqa: BLE001  # authorization failure must never write credentials
+            verbose_logger.debug("OAuth credential write not authorized (%s)", type(exc).__name__)
+            return None
+    return auth.user_id
 
 
-async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
+async def _resolve_jwt_auth(
+    request: Request,
+    token: str,
+    write_route: str | None,
+) -> "UserAPIKeyAuth | None":
     from litellm.proxy._types import UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.handle_jwt import JWTAuthManager  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
@@ -353,7 +384,7 @@ async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
                 proxy_logging_obj=proxy_logging_obj,
             )
             if isinstance(mapped, UserAPIKeyAuth):
-                return None if await _key_owner_scim_deactivated(mapped) else _active_key_user_id(mapped)
+                return None if await _key_owner_scim_deactivated(mapped) or not _active_key_user_id(mapped) else mapped
             if mapped is not None:
                 return None
         identity: Final = await JWTAuthManager.auth_builder(
@@ -361,19 +392,20 @@ async def _extract_jwt_user_id(request: Request, token: str) -> str | None:
             jwt_handler=jwt_handler,
             request_data={},
             general_settings=general_settings,
-            route=request.url.path,
+            route=write_route or request.url.path,
             prisma_client=prisma_client,
             user_api_key_cache=user_api_key_cache,
             parent_otel_span=None,
             proxy_logging_obj=proxy_logging_obj,
             request_headers=dict(request.headers),
             request_method=request.method,
-            identity_only=True,
+            identity_only=write_route is None,
+            allow_provisioning=False,
         )
         resolved_user: Final = identity["user_object"]
         if resolved_user is not None and isinstance(_active_user_record(resolved_user), str):
             return None
-        return identity["user_id"]
+        return JWTAuthManager.user_api_key_auth_from_result(identity)
     except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
         verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
         return None
diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index 94b6348b0f0..56968745ea9 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -1218,12 +1218,26 @@ async def exchange_token_with_server(
         user_id: Final = resolved_user_id
         if user_id:
             try:
-                await _store_per_user_token_server_side(
-                    server=resolved_server,
-                    user_id=user_id,
-                    token_response=token_response,
-                    identity_binding_proof=binding_proof,
+                # Identity binding above must retain the verified caller even when a write is
+                # denied. Authorize persistence separately, immediately before its side effect.
+                can_store: Final = (
+                    await _user_can_reach_mcp_server(user_id, resolved_server.server_id)
+                    if bridge_identity is not None
+                    else await _extract_user_id_from_request(request, resolved_server.server_id) == user_id
                 )
+                if can_store:
+                    await _store_per_user_token_server_side(
+                        server=resolved_server,
+                        user_id=user_id,
+                        token_response=token_response,
+                        identity_binding_proof=binding_proof,
+                    )
+                else:
+                    verbose_logger.warning(
+                        "OAuth credential storage not authorized for user=%s server=%s",
+                        user_id,
+                        resolved_server.server_id,
+                    )
             except Exception as exc:
                 verbose_logger.warning(
                     "exchange_token_with_server: server-side storage failed for user=%s server=%s: %s",
diff --git a/litellm/proxy/_experimental/mcp_server/ui_session_utils.py b/litellm/proxy/_experimental/mcp_server/ui_session_utils.py
index 188bfce1484..107a4818de1 100644
--- a/litellm/proxy/_experimental/mcp_server/ui_session_utils.py
+++ b/litellm/proxy/_experimental/mcp_server/ui_session_utils.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Awaitable, Callable
 from typing import Final
 
 from fastapi import HTTPException
@@ -137,3 +138,15 @@ async def build_effective_auth_contexts(
     if admitted_context is None:
         return team_contexts
     return [*team_contexts, admitted_context]
+
+
+async def can_access_mcp_server(
+    user_api_key_auth: UserAPIKeyAuth,
+    server_id: str,
+    allowed_servers: Callable[[UserAPIKeyAuth], Awaitable[list[str]]],
+) -> bool:
+    """Resolve server access through the same credential contexts as MCP management."""
+    for context in await build_effective_auth_contexts(user_api_key_auth):
+        if server_id in await allowed_servers(context):
+            return True
+    return False
diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py
index 2d8cfb614ce..f2bdbdd9341 100644
--- a/litellm/proxy/auth/handle_jwt.py
+++ b/litellm/proxy/auth/handle_jwt.py
@@ -9,6 +9,7 @@ JWT token must have 'litellm_proxy_admin' in scope.
 from __future__ import annotations
 
 import asyncio
+import copy
 import fnmatch
 import hashlib
 import os
@@ -54,7 +55,7 @@ from litellm.proxy._types import (
 from litellm.proxy.auth.auth_checks import can_team_access_model
 from litellm.proxy.auth.resolvers.grants import GrantResolver, UserLookup, canonical_user_id
 from litellm.proxy.auth.route_checks import RouteChecks
-from litellm.proxy.auth.team_grants import team_model_aliases
+from litellm.proxy.auth.team_grants import team_grants, team_model_aliases
 from litellm.proxy.common_utils.user_api_key_cache import (
     UserApiKeyCache,
     get_management_object_ttl,
@@ -2268,36 +2269,49 @@ class JWTAuthManager:
         request_headers: dict | None = None,
         request_method: str | None = None,
         identity_only: bool = False,
+        allow_provisioning: bool = True,
     ) -> JWTAuthBuilderResult:
         """Build JWT authentication and authorization context.
 
-        Public OAuth endpoints use identity_only to resolve an existing credential owner
-        without authorizing the OAuth route or provisioning users/teams. The returned
-        identity does not grant permission to execute an MCP or model request.
+        identity_only resolves the caller for OAuth identity binding and grants no permission.
+        Credential writes use full authorization with allow_provisioning=False: resolve the
+        existing policy context without creating users/teams or synchronizing membership.
+        A private handler configuration keeps that restriction out of concurrent normal requests.
         """
+        handler: Final = jwt_handler if allow_provisioning else copy.copy(jwt_handler)
+        if not allow_provisioning:
+            handler.update_environment(
+                prisma_client=jwt_handler.prisma_client,
+                user_api_key_cache=jwt_handler.user_api_key_cache,
+                litellm_jwtauth=jwt_handler.litellm_jwtauth.model_copy(
+                    update={"user_id_upsert": False, "team_id_upsert": False, "sync_user_role_and_teams": False}
+                ),
+                leeway=jwt_handler.leeway,
+            )
+
         # Check if OIDC UserInfo endpoint is enabled, but fall back to standard
         # JWT auth if the token itself is a well-formed JWT (3-part structure).
-        if jwt_handler.litellm_jwtauth.oidc_userinfo_enabled and not jwt_handler.is_jwt(token=api_key):
+        if handler.litellm_jwtauth.oidc_userinfo_enabled and not handler.is_jwt(token=api_key):
             verbose_proxy_logger.debug("OIDC UserInfo is enabled. Fetching user info from UserInfo endpoint.")
             # Use the access token to fetch user info from OIDC UserInfo endpoint
-            jwt_valid_token: dict = await jwt_handler.get_oidc_userinfo(token=api_key)
+            jwt_valid_token: dict = await handler.get_oidc_userinfo(token=api_key)
         else:
             # Default behavior: decode and validate the JWT token
-            jwt_valid_token = await jwt_handler.auth_jwt(token=api_key)
+            jwt_valid_token = await handler.auth_jwt(token=api_key)
 
         # Check custom validate
-        if jwt_handler.litellm_jwtauth.custom_validate:
-            if not jwt_handler.litellm_jwtauth.custom_validate(jwt_valid_token):
+        if handler.litellm_jwtauth.custom_validate:
+            if not handler.litellm_jwtauth.custom_validate(jwt_valid_token):
                 raise HTTPException(
                     status_code=403,
                     detail="Invalid JWT token",
                 )
 
         # Check RBAC
-        rbac_role: Final = jwt_handler.get_rbac_role(token=jwt_valid_token)
+        rbac_role: Final = handler.get_rbac_role(token=jwt_valid_token)
         if not identity_only:
             await JWTAuthManager.check_rbac_role(
-                jwt_handler,
+                handler,
                 jwt_valid_token,
                 general_settings,
                 request_data,
@@ -2306,30 +2320,30 @@ class JWTAuthManager:
             )
 
         # Check Scope Based Access
-        scopes: Final = jwt_handler.get_scopes(token=jwt_valid_token)
+        scopes: Final = handler.get_scopes(token=jwt_valid_token)
         if (
             not identity_only
-            and jwt_handler.litellm_jwtauth.enforce_scope_based_access
-            and jwt_handler.litellm_jwtauth.scope_mappings
+            and handler.litellm_jwtauth.enforce_scope_based_access
+            and handler.litellm_jwtauth.scope_mappings
         ):
             JWTAuthManager.check_scope_based_access(
-                scope_mappings=jwt_handler.litellm_jwtauth.scope_mappings,
+                scope_mappings=handler.litellm_jwtauth.scope_mappings,
                 scopes=scopes,
                 request_data=request_data,
                 general_settings=general_settings,
             )
 
-        object_id = jwt_handler.get_object_id(token=jwt_valid_token, default_value=None)
+        object_id = handler.get_object_id(token=jwt_valid_token, default_value=None)
 
         # Get basic user info
-        user_id, user_email, valid_user_email = await JWTAuthManager.get_user_info(jwt_handler, jwt_valid_token)
+        user_id, user_email, valid_user_email = await JWTAuthManager.get_user_info(handler, jwt_valid_token)
 
         # Get IDs
-        org_id: Final = jwt_handler.get_org_id(token=jwt_valid_token, default_value=None)
-        end_user_id: Final = jwt_handler.get_end_user_id(token=jwt_valid_token, default_value=None)
+        org_id: Final = handler.get_org_id(token=jwt_valid_token, default_value=None)
+        end_user_id: Final = handler.get_end_user_id(token=jwt_valid_token, default_value=None)
         team_id: str | None = None
         team_object: LiteLLM_TeamTable | None = None
-        object_id = jwt_handler.get_object_id(token=jwt_valid_token, default_value=None)
+        object_id = handler.get_object_id(token=jwt_valid_token, default_value=None)
 
         if rbac_role and object_id:
             if rbac_role == LitellmUserRoles.TEAM:
@@ -2338,12 +2352,12 @@ class JWTAuthManager:
                 user_id = object_id
 
         agent_id: Final = JWTAuthManager.resolve_agent_id(
-            jwt_handler=jwt_handler,
+            jwt_handler=handler,
             jwt_valid_token=jwt_valid_token,
-            agent_registry=jwt_handler.agent_lookup,
+            agent_registry=handler.agent_lookup,
         )
 
-        if identity_only:
+        if identity_only or (not allow_provisioning and handler.is_admin(scopes=scopes)):
             try:
                 identity_user, _, _, _, identity_user_id = await JWTAuthManager.get_objects(
                     user_id=user_id,
@@ -2352,7 +2366,7 @@ class JWTAuthManager:
                     end_user_id=None,
                     team_id=None,
                     valid_user_email=valid_user_email,
-                    jwt_handler=jwt_handler,
+                    jwt_handler=handler,
                     prisma_client=prisma_client,
                     user_api_key_cache=user_api_key_cache,
                     parent_otel_span=parent_otel_span,
@@ -2361,13 +2375,37 @@ class JWTAuthManager:
                     user_id_upsert=False,
                 )
             except UserNotFoundError:
-                if not jwt_handler.is_admin(scopes=scopes):
+                if not handler.is_admin(scopes=scopes):
                     raise
                 identity_user, identity_user_id = None, user_id
+            if not identity_only:
+                admin: Final = await JWTAuthManager.check_admin_access(
+                    handler,
+                    scopes,
+                    route,
+                    user_id,
+                    org_id,
+                    api_key,
+                    jwt_valid_token,
+                    user_email=user_email,
+                    agent_id=agent_id,
+                )
+                if admin is not None:
+                    await JWTAuthManager._attach_team_from_header_for_admin(
+                        admin_result=admin,
+                        route=route,
+                        request_headers=request_headers,
+                        jwt_handler=handler,
+                        prisma_client=prisma_client,
+                        user_api_key_cache=user_api_key_cache,
+                        parent_otel_span=parent_otel_span,
+                        proxy_logging_obj=proxy_logging_obj,
+                    )
+                    return {**admin, "user_object": identity_user}
             return JWTAuthBuilderResult(
                 is_proxy_admin=False,
                 # Admin admission uses the claim ID; other callers use the canonical DB ID.
-                user_id=user_id if jwt_handler.is_admin(scopes=scopes) else identity_user_id,
+                user_id=user_id if handler.is_admin(scopes=scopes) else identity_user_id,
                 user_email=identity_user.user_email if identity_user is not None else user_email,
                 user_object=identity_user,
                 team_id=None,
@@ -2384,7 +2422,7 @@ class JWTAuthManager:
 
         # Check admin access
         admin_result: Final = await JWTAuthManager.check_admin_access(
-            jwt_handler,
+            handler,
             scopes,
             route,
             user_id,
@@ -2399,7 +2437,7 @@ class JWTAuthManager:
                 admin_result=admin_result,
                 route=route,
                 request_headers=request_headers,
-                jwt_handler=jwt_handler,
+                jwt_handler=handler,
                 prisma_client=prisma_client,
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
@@ -2409,8 +2447,8 @@ class JWTAuthManager:
 
         # Get team with model access
         ## Check if team_id is specified via x-litellm-team-id header
-        all_team_ids: Final = JWTAuthManager.get_all_team_ids(jwt_handler, jwt_valid_token)
-        specific_team_id: Final = jwt_handler.get_team_id(token=jwt_valid_token, default_value=None)
+        all_team_ids: Final = JWTAuthManager.get_all_team_ids(handler, jwt_valid_token)
+        specific_team_id: Final = handler.get_team_id(token=jwt_valid_token, default_value=None)
 
         # The DB fallback only applies when the token carries no team identity at
         # all. `get_all_jwt_team_ids` ignores `team_id_default` so a configured
@@ -2420,9 +2458,9 @@ class JWTAuthManager:
         # the RBAC team-role path (which already set `team_id`); otherwise a
         # provisional x-litellm-team-id header could override an RBAC-asserted team.
         db_team_fallback: Final = (
-            jwt_handler.litellm_jwtauth.fallback_to_db_teams
-            and not jwt_handler.get_all_jwt_team_ids(token=jwt_valid_token)
-            and not jwt_handler.get_team_alias(token=jwt_valid_token, default_value=None)
+            handler.litellm_jwtauth.fallback_to_db_teams
+            and not handler.get_all_jwt_team_ids(token=jwt_valid_token)
+            and not handler.get_team_alias(token=jwt_valid_token, default_value=None)
             and team_id is None
         )
         if specific_team_id and not db_team_fallback:
@@ -2447,7 +2485,7 @@ class JWTAuthManager:
                     user_api_key_cache=user_api_key_cache,
                     parent_otel_span=parent_otel_span,
                     proxy_logging_obj=proxy_logging_obj,
-                    team_id_upsert=(jwt_handler.litellm_jwtauth.team_id_upsert and not db_team_fallback),
+                    team_id_upsert=(handler.litellm_jwtauth.team_id_upsert and not db_team_fallback),
                 )
             except HTTPException:
                 if not db_team_fallback:
@@ -2459,7 +2497,7 @@ class JWTAuthManager:
                 team_id,
                 team_object,
             ) = await JWTAuthManager.find_and_validate_specific_team_id(
-                jwt_handler,
+                handler,
                 jwt_valid_token,
                 prisma_client,
                 user_api_key_cache,
@@ -2474,7 +2512,7 @@ class JWTAuthManager:
                 requested_model=request_data.get("model"),
                 route=route,
                 request_method=request_method,
-                jwt_handler=jwt_handler,
+                jwt_handler=handler,
                 prisma_client=prisma_client,
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
@@ -2498,7 +2536,7 @@ class JWTAuthManager:
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
                 proxy_logging_obj=proxy_logging_obj,
-                team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert,
+                team_id_upsert=handler.litellm_jwtauth.team_id_upsert,
             )
 
         if team_id and not JWTAuthManager._team_has_passthrough_route_access(
@@ -2509,7 +2547,7 @@ class JWTAuthManager:
             JWTAuthManager._raise_team_passthrough_route_denial(route=route)
 
         # Extract alias fields for resolution (if configured)
-        org_alias: Final = jwt_handler.get_org_alias(token=jwt_valid_token, default_value=None)
+        org_alias: Final = handler.get_org_alias(token=jwt_valid_token, default_value=None)
 
         # get_objects returns effective_user_id for downstream spend attribution (GH #26789).
         (
@@ -2525,7 +2563,7 @@ class JWTAuthManager:
             end_user_id=end_user_id,
             team_id=team_id,
             valid_user_email=valid_user_email,
-            jwt_handler=jwt_handler,
+            jwt_handler=handler,
             prisma_client=prisma_client,
             user_api_key_cache=user_api_key_cache,
             parent_otel_span=parent_otel_span,
@@ -2538,7 +2576,7 @@ class JWTAuthManager:
         resolved_org_id: Final = org_object.organization_id if org_object else org_id
 
         await JWTAuthManager.sync_user_role_and_teams(
-            jwt_handler=jwt_handler,
+            jwt_handler=handler,
             jwt_valid_token=jwt_valid_token,
             user_object=user_object,
             prisma_client=prisma_client,
@@ -2556,9 +2594,9 @@ class JWTAuthManager:
                 user_id=user_id,
                 requested_model=request_data.get("model"),
                 route=route,
-                jwt_handler=jwt_handler,
-                enforce_team_based_model_access=jwt_handler.litellm_jwtauth.enforce_team_based_model_access,
-                team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert,
+                jwt_handler=handler,
+                enforce_team_based_model_access=handler.litellm_jwtauth.enforce_team_based_model_access,
+                team_id_upsert=handler.litellm_jwtauth.team_id_upsert,
                 prisma_client=prisma_client,
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
@@ -2586,7 +2624,7 @@ class JWTAuthManager:
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
                 proxy_logging_obj=proxy_logging_obj,
-                team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert,
+                team_id_upsert=handler.litellm_jwtauth.team_id_upsert,
             )
         elif db_team_fallback and team_id == header_team_id:
             JWTAuthManager._validate_header_team_in_db_membership(
@@ -2596,7 +2634,7 @@ class JWTAuthManager:
             if not JWTAuthManager._is_team_route_allowed(
                 route=route,
                 request_method=request_method,
-                jwt_handler=jwt_handler,
+                jwt_handler=handler,
             ):
                 raise HTTPException(
                     status_code=403,
@@ -2606,10 +2644,11 @@ class JWTAuthManager:
                 )
 
         ## MAP USER TO TEAMS
-        await JWTAuthManager.map_user_to_teams(
-            user_object=user_object,
-            team_object=team_object,
-        )
+        if allow_provisioning:
+            await JWTAuthManager.map_user_to_teams(
+                user_object=user_object,
+                team_object=team_object,
+            )
 
         # Validate that a valid rbac id is returned for spend tracking
         JWTAuthManager.validate_object_id(
@@ -2638,3 +2677,38 @@ class JWTAuthManager:
             jwt_claims=jwt_valid_token,
             agent_id=agent_id,
         )
+
+    @staticmethod
+    def user_api_key_auth_from_result(
+        result: JWTAuthBuilderResult,
+        parent_otel_span: Span | None = None,
+    ) -> UserAPIKeyAuth:
+        """Keep JWT identity and permission attribution identical across consumers."""
+        user: Final = result["user_object"]
+        admin: Final = result["is_proxy_admin"]
+        return UserAPIKeyAuth(
+            api_key=None,
+            user_role=(
+                LitellmUserRoles.PROXY_ADMIN
+                if admin
+                else LitellmUserRoles(user.user_role)
+                if user is not None and user.user_role is not None
+                else LitellmUserRoles.INTERNAL_USER
+            ),
+            user_id=result["user_id"],
+            user_email=result["user_email"],
+            team_id=result["team_id"],
+            org_id=result["org_id"],
+            end_user_id=result["end_user_id"],
+            parent_otel_span=parent_otel_span,
+            jwt_claims=result["jwt_claims"],
+            agent_id=result.get("agent_id"),
+            user_tpm_limit=user.tpm_limit if user is not None and not admin else None,
+            user_rpm_limit=user.rpm_limit if user is not None and not admin else None,
+            user_model_max_budget=user.model_max_budget if user is not None and not admin else None,
+            **team_grants(
+                team_object=result["team_object"],
+                team_membership=result.get("team_membership"),
+                user_id=result["user_id"],
+            ),
+        )
diff --git a/litellm/proxy/auth/user_api_key_auth.py b/litellm/proxy/auth/user_api_key_auth.py
index c5297ac83dc..ba267114bac 100644
--- a/litellm/proxy/auth/user_api_key_auth.py
+++ b/litellm/proxy/auth/user_api_key_auth.py
@@ -1669,13 +1669,11 @@ async def _user_api_key_auth_builder(
 
                     is_proxy_admin: Final = result["is_proxy_admin"]
                     team_id: Final = result["team_id"]
-                    team_object: Final = result["team_object"]
                     user_id: Final = result["user_id"]
                     user_email: Final = result["user_email"]
                     user_object: Final = result["user_object"]
                     end_user_id = result["end_user_id"]
                     org_id: Final = result["org_id"]
-                    team_membership: Final[LiteLLM_TeamMembership | None] = result.get("team_membership", None)
                     jwt_claims = result.get("jwt_claims", None)
                     agent_id: Final[str | None] = result.get("agent_id")
 
@@ -1693,40 +1691,9 @@ async def _user_api_key_auth_builder(
                                 value=_JWT_PROXY_ADMIN_SENTINEL,
                                 ttl=jwt_handler.litellm_jwtauth.virtual_key_mapping_cache_ttl,
                             )
-                        return UserAPIKeyAuth(
-                            api_key=None,
-                            user_role=LitellmUserRoles.PROXY_ADMIN,
-                            user_id=user_id,
-                            user_email=user_email,
-                            team_id=team_id,
-                            org_id=org_id,
-                            end_user_id=end_user_id,
-                            parent_otel_span=parent_otel_span,
-                            jwt_claims=jwt_claims,
-                            agent_id=agent_id,
-                            **team_grants(team_object=team_object, team_membership=team_membership, user_id=user_id),
-                        )
+                        return JWTAuthManager.user_api_key_auth_from_result(result, parent_otel_span)
 
-                    valid_token = UserAPIKeyAuth(
-                        api_key=None,
-                        team_id=team_id,
-                        user_role=(
-                            LitellmUserRoles(user_object.user_role)
-                            if user_object is not None and user_object.user_role is not None
-                            else LitellmUserRoles.INTERNAL_USER
-                        ),
-                        user_id=user_id,
-                        user_email=user_email,
-                        org_id=org_id,
-                        parent_otel_span=parent_otel_span,
-                        end_user_id=end_user_id,
-                        user_tpm_limit=(user_object.tpm_limit if user_object is not None else None),
-                        user_rpm_limit=(user_object.rpm_limit if user_object is not None else None),
-                        user_model_max_budget=(user_object.model_max_budget if user_object is not None else None),
-                        jwt_claims=jwt_claims,
-                        agent_id=agent_id,
-                        **team_grants(team_object=team_object, team_membership=team_membership, user_id=user_id),
-                    )
+                    valid_token = JWTAuthManager.user_api_key_auth_from_result(result, parent_otel_span)
 
                     # AUTO_REGISTER deferred from _resolve_jwt_to_virtual_key.
                     # JWT policy (RBAC, scope, custom_validate, email-domain)
diff --git a/litellm/proxy/management_endpoints/mcp_management_endpoints.py b/litellm/proxy/management_endpoints/mcp_management_endpoints.py
index 4c97bbaf5de..918a55bb9ce 100644
--- a/litellm/proxy/management_endpoints/mcp_management_endpoints.py
+++ b/litellm/proxy/management_endpoints/mcp_management_endpoints.py
@@ -170,6 +170,7 @@ if MCP_AVAILABLE:
     from litellm.proxy._experimental.mcp_server.ui_session_utils import (
         admitted_user_context,
         build_effective_auth_contexts,
+        can_access_mcp_server,
         is_ui_session_credential,
     )
     from litellm.proxy._types import (
@@ -2483,10 +2484,11 @@ if MCP_AVAILABLE:
                 )
             return server
 
-        allowed_server_ids: Final[set[str]] = set()
-        for auth_context in await build_effective_auth_contexts(user_api_key_dict):
-            allowed_server_ids.update(await global_mcp_server_manager.get_allowed_mcp_servers(auth_context))
-        if server is None or server.server_id not in allowed_server_ids:
+        if server is None or not await can_access_mcp_server(
+            user_api_key_dict,
+            server.server_id,
+            global_mcp_server_manager.get_allowed_mcp_servers,
+        ):
             raise HTTPException(
                 status_code=status.HTTP_403_FORBIDDEN,
                 detail={
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index f6dc7932e2f..8c179eea4cb 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -11422,6 +11422,7 @@ def _oauth_identity_jwt(
     issuer: str = "https://idp.example.test",
     owner: str | None = "jwt-owner",
     scope: str = "",
+    claims: dict[str, object] | None = None,
 ) -> str:
     import jwt
 
@@ -11434,6 +11435,7 @@ def _oauth_identity_jwt(
             "aud": audience,
             "exp": int(time.time()) + expires_in,
             "scope": scope,
+            **(claims or {}),
         },
         signing_key,
         algorithm="RS256",
@@ -11443,12 +11445,14 @@ def _oauth_identity_jwt(
 @pytest.mark.asyncio
 @pytest.mark.parametrize("header", ["Authorization", "x-litellm-api-key"])
 @pytest.mark.parametrize("policy_allowed", [False, True])
+@pytest.mark.parametrize("server_allowed", [False, True])
 @pytest.mark.parametrize("admin", [False, True])
 @pytest.mark.parametrize("owner_state", ["active", "missing", "inactive", "database_error"])
 async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     header: str,
     policy_allowed: bool,
+    server_allowed: bool,
     admin: bool,
     owner_state: str,
     monkeypatch: pytest.MonkeyPatch,
@@ -11461,6 +11465,12 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
 
     handler, signing_key = jwt_oauth_identity
     handler.litellm_jwtauth.custom_validate = lambda claims: policy_allowed
+    from litellm.proxy._experimental.mcp_server import mcp_server_manager
+
+    manager: Final = MagicMock()
+    manager.get_allowed_mcp_servers = AsyncMock(return_value=["jwt-oauth-server"] if server_allowed else [])
+    manager.invalidate_user_oauth_token_cache = AsyncMock()
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
     bearer: Final = _oauth_identity_jwt(signing_key, scope="litellm_proxy_admin" if admin else "")
     request: Final = _token_request({header: f"Bearer {bearer}"}, path="/jwt-oauth-server/token")
     server: Final = MCPServer(
@@ -11525,7 +11535,12 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
     assert response.status_code == 200
     assert json.loads(response.body)["access_token"] == "upstream-token"
     users.create.assert_not_awaited()
-    if not policy_allowed or owner_state in ("inactive", "database_error") or (owner_state == "missing" and not admin):
+    if (
+        not server_allowed
+        or not policy_allowed
+        or owner_state in ("inactive", "database_error")
+        or (owner_state == "missing" and not admin)
+    ):
         table.upsert.assert_not_awaited()
         return
     table.upsert.assert_awaited_once()
@@ -11755,9 +11770,7 @@ async def test_oauth_jwt_resolves_canonical_owner_without_cached_identity(
     table.find_first = AsyncMock(return_value=owner)
     table.update = AsyncMock(return_value=owner)
     monkeypatch.setattr(proxy_server, "prisma_client", database)
-    bearer: Final = _oauth_identity_jwt(
-        signing_key, owner=external_id, scope="litellm_proxy_admin" if admin else ""
-    )
+    bearer: Final = _oauth_identity_jwt(signing_key, owner=external_id, scope="litellm_proxy_admin" if admin else "")
     request: Final = _token_request({"Authorization": f"Bearer {bearer}"})
     stored_owner: Final = await _extract_user_id_from_request(request)
     assert stored_owner == (None if inactive else external_id if admin else "canonical-oauth-owner")
@@ -11823,3 +11836,139 @@ async def test_oauth_refresh_revalidates_the_same_active_user_rule(
         monkeypatch.setattr(proxy_server, "prisma_client", None)
     expected: Final = None if state == "active" else "no_active_key" if state == "inactive" else "unresolvable"
     assert await _reload_active_user_by_id("jwt-owner") == expected
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mapped", [False, True])
+@pytest.mark.parametrize("state", ["allowed", "route_denied", "server_denied", "blocked", "expired", "lookup_error", "cancelled"])
+async def test_oauth_credential_write_keeps_virtual_key_permissions(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    mapped: bool,
+    state: str,
+) -> None:
+    import asyncio
+
+    from litellm.proxy._experimental.mcp_server import mcp_server_manager
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._types import UserAPIKeyAuth, hash_token
+    from litellm.proxy.auth.auth_checks import jwt_key_mapping_cache_key
+
+    handler, signing_key = jwt_oauth_identity
+    key: Final = "sk-oauth-permission-test"
+    hashed: Final = hash_token(key)
+    credential: Final = UserAPIKeyAuth(
+        token=hashed,
+        user_id="jwt-owner",
+        blocked=state == "blocked",
+        expires=datetime.now(timezone.utc) - timedelta(seconds=60) if state == "expired" else None,
+        allowed_routes=["openai_routes"] if state == "route_denied" else ["mcp_routes"],
+        agent_id="agent-scope",
+        org_id="org-scope",
+        end_user_id="end-user-scope",
+    )
+    handler.user_api_key_cache.set_cache(hashed, credential)
+    if mapped:
+        handler.litellm_jwtauth.virtual_key_claim_field = "sub"
+        handler.user_api_key_cache.set_cache(jwt_key_mapping_cache_key("sub", "not-the-configured-user-id"), hashed)
+    manager: Final = MagicMock()
+    manager.get_allowed_mcp_servers = AsyncMock(
+        return_value=[] if state == "server_denied" else ["server-a"],
+        side_effect=(asyncio.CancelledError() if state == "cancelled" else RuntimeError("permission lookup unavailable") if state == "lookup_error" else None),
+    )
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
+    bearer: Final = _oauth_identity_jwt(signing_key) if mapped else key
+    request: Final = _token_request({"Authorization": f"Bearer {bearer}"}, path="/server-a/token")
+    if state == "cancelled":
+        with pytest.raises(asyncio.CancelledError):
+            await _extract_user_id_from_request(request, "server-a")
+        manager.get_allowed_mcp_servers.assert_awaited_once()
+        return
+    assert await _extract_user_id_from_request(request, "server-a") == ("jwt-owner" if state == "allowed" else None)
+    if state in ("allowed", "server_denied", "lookup_error"):
+        manager.get_allowed_mcp_servers.assert_awaited_once()
+        writer: Final = manager.get_allowed_mcp_servers.call_args.args[0]
+        assert (writer.user_id, writer.token, writer.org_id, writer.agent_id, writer.end_user_id) == (
+            "jwt-owner",
+            hashed,
+            "org-scope",
+            "agent-scope",
+            "end-user-scope",
+        )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("server_id", ["team-a-server", "team-b-server"])
+async def test_oauth_writer_preserves_claimed_team_instead_of_expanding_user_roster(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    server_id: str,
+) -> None:
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server import mcp_server_manager
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._types import LiteLLM_TeamTable, Member
+
+    handler, signing_key = jwt_oauth_identity
+    handler.litellm_jwtauth.team_id_jwt_field = "team"
+    handler.litellm_jwtauth.team_id_upsert = True
+    handler.litellm_jwtauth.user_id_upsert = True
+    handler.litellm_jwtauth.sync_user_role_and_teams = True
+    handler.user_api_key_cache.set_cache("jwt-owner", LiteLLM_UserTable(user_id="jwt-owner", teams=["a", "b"]))
+    handler.user_api_key_cache.set_cache(
+        "team_id:a",
+        LiteLLM_TeamTable(team_id="a", models=[], members_with_roles=[Member(user_id="jwt-owner", role="user")]),
+    )
+    manager: Final = MagicMock()
+    manager.get_allowed_mcp_servers = AsyncMock(return_value=["team-a-server"])
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
+    bearer: Final = _oauth_identity_jwt(signing_key, claims={"team": "a"})
+    request: Final = _token_request({"Authorization": f"Bearer {bearer}"}, path=f"/{server_id}/token")
+    assert await _extract_user_id_from_request(request, server_id) == (
+        "jwt-owner" if server_id == "team-a-server" else None
+    )
+    manager.get_allowed_mcp_servers.assert_awaited_once()
+    writer: Final = manager.get_allowed_mcp_servers.call_args.args[0]
+    assert writer.team_id == "a"
+    assert not writer.mcp_admitted_user_subject
+    proxy_server.prisma_client.db.litellm_teamtable.create.assert_not_called()
+    proxy_server.prisma_client.db.litellm_usertable.create.assert_not_called()
+    proxy_server.prisma_client.db.litellm_usertable.update.assert_not_called()
+    assert handler.litellm_jwtauth.user_id_upsert and handler.litellm_jwtauth.team_id_upsert
+    assert handler.litellm_jwtauth.sync_user_role_and_teams
+
+
+@pytest.mark.asyncio
+async def test_oauth_write_denial_does_not_erase_identity_binding(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"], monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from litellm.proxy._experimental.mcp_server import discoverable_endpoints, mcp_server_manager
+    from litellm.proxy._types import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPOAuthIdentityBinding, MCPServer
+
+    _, signing_key = jwt_oauth_identity
+    monkeypatch.setenv("LITELLM_SALT_KEY", "oauth-identity-binding-test-salt")
+    manager: Final = MagicMock()
+    manager.get_allowed_mcp_servers = AsyncMock(return_value=[])
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
+    server: Final = MCPServer(
+        server_id="bound-server", name="bound-server", transport=MCPTransport.http,
+        auth_type=MCPAuth.oauth2, oauth2_flow="authorization_code", client_id="client",
+        token_url="https://upstream.example.test/token",
+        oauth_identity_binding=MCPOAuthIdentityBinding(
+            mode="enforce", issuer="https://upstream.example.test", audiences=["client"],
+        ),
+    )
+    request: Final = _token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"})
+    code: Final = discoverable_endpoints.seal_bridge_authorization_code(
+        "upstream-code", "another-owner", server.server_id, "bound-nonce",
+    )
+    with pytest.raises(HTTPException) as denied:
+        await discoverable_endpoints.exchange_token_with_server(
+            request=request, mcp_server=server, grant_type="authorization_code", code=code,
+            redirect_uri="http://localhost/callback", client_id="client", client_secret=None, code_verifier="verifier",
+        )
+    assert denied.value.status_code == 403
+    assert denied.value.detail == {"error": "oauth_principal_mismatch"}
+    manager.get_allowed_mcp_servers.assert_not_awaited()
diff --git a/tests/test_litellm/proxy/auth/test_handle_jwt.py b/tests/test_litellm/proxy/auth/test_handle_jwt.py
index 4d86e395358..babbf88dc29 100644
--- a/tests/test_litellm/proxy/auth/test_handle_jwt.py
+++ b/tests/test_litellm/proxy/auth/test_handle_jwt.py
@@ -6792,10 +6792,11 @@ async def test_sync_user_role_and_teams_singular_claim_only_recognized_under_fla
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("identity_only", [False, True])
+@pytest.mark.parametrize("allow_provisioning", [False, True])
 @pytest.mark.parametrize("existing_user", [False, True])
 @pytest.mark.parametrize("model_allowed", [False, True])
 async def test_auth_builder_identity_lookup_does_not_provision_users(
-    monkeypatch: pytest.MonkeyPatch, identity_only: bool, existing_user: bool, model_allowed: bool
+    monkeypatch: pytest.MonkeyPatch, identity_only: bool, allow_provisioning: bool, existing_user: bool, model_allowed: bool
 ) -> None:
     from litellm.proxy._types import ScopeMapping
     from litellm.proxy.auth.auth_checks import UserNotFoundError
@@ -6841,6 +6842,7 @@ async def test_auth_builder_identity_lookup_does_not_provision_users(
         parent_otel_span=None,
         proxy_logging_obj=MagicMock(),
         identity_only=identity_only,
+        allow_provisioning=allow_provisioning,
     )
     if not identity_only and not model_allowed:
         with pytest.raises(HTTPException) as denial:
@@ -6848,7 +6850,7 @@ async def test_auth_builder_identity_lookup_does_not_provision_users(
         assert denial.value.status_code == 403
         users.create.assert_not_awaited()
         return
-    if identity_only and not existing_user:
+    if (identity_only or not allow_provisioning) and not existing_user:
         with pytest.raises(UserNotFoundError):
             await pending
     else:
@@ -6856,7 +6858,7 @@ async def test_auth_builder_identity_lookup_does_not_provision_users(
         assert result["user_id"] == user_id
         assert result["user_object"] is not None
         assert result["user_object"].user_id == user_id
-    assert users.create.await_count == (0 if identity_only or existing_user else 1)
+    assert users.create.await_count == (0 if identity_only or not allow_provisioning or existing_user else 1)
 
 
 def _entra_agent_registry() -> AgentRegistry:

From a6228fab66f289b9e8014c4fc75646eae821d1aa Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 02:03:21 +0000
Subject: [PATCH 44/67] fix(anthropic): write usage into copies of the
 read-only message_delta chunk

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../adapters/streaming_iterator.py                          | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/litellm/llms/anthropic/experimental_pass_through/adapters/streaming_iterator.py b/litellm/llms/anthropic/experimental_pass_through/adapters/streaming_iterator.py
index e7179aad25b..4486eb0985a 100644
--- a/litellm/llms/anthropic/experimental_pass_through/adapters/streaming_iterator.py
+++ b/litellm/llms/anthropic/experimental_pass_through/adapters/streaming_iterator.py
@@ -376,10 +376,9 @@ class AnthropicStreamWrapper(AdapterCompletionStreamWrapper):
         usage_dict: UsageDelta = LiteLLMAnthropicMessagesAdapter._translate_openai_usage_to_anthropic_usage_delta(
             chunk.usage
         )
-        merged_chunk["usage"] = usage_dict
         if self.applied_edits and "context_management" not in merged_chunk:
             merged_chunk["context_management"] = ContextManagementResponse(applied_edits=list(self.applied_edits))
-        return self._augment_message_delta_usage(merged_chunk)
+        return self._augment_message_delta_usage({**merged_chunk, "usage": usage_dict})
 
     def _handle_choiceless_chunk(self, chunk: "ModelResponseStream") -> bool:
         """Consume an OpenAI-compatible chunk that carries no ``choices``.
@@ -448,8 +447,7 @@ class AnthropicStreamWrapper(AdapterCompletionStreamWrapper):
             }
             iterations.append(message_iteration)
         augmented_usage["iterations"] = iterations
-        augmented["usage"] = augmented_usage
-        return augmented
+        return {**augmented, "usage": augmented_usage}
 
     def _next_compaction_event(self) -> dict[str, object] | None:
         """Return the next compaction content-block SSE event, or ``None``.

From 7680d3de863648b500fc605d0eaa0c894d0a6bf4 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 02:05:44 +0000
Subject: [PATCH 45/67] fix(responses): tolerate dict terminal responses when
 estimating usage

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 35 ++++++++--------
 .../responses/test_streaming_iterator.py      | 42 +++++++++++++++++++
 2 files changed, 60 insertions(+), 17 deletions(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index df3c26c1a4f..10ddf07ac7e 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -428,24 +428,25 @@ class BaseResponsesAPIStreamingIterator:
                     openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED,
                 ):
                     self.completed_response = openai_responses_api_chunk
-                    _response_obj: Final[ResponsesAPIResponse | None] = getattr(
-                        openai_responses_api_chunk, "response", None
-                    )
-                    if (
-                        _chunk_type
-                        in (
-                            openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
-                            openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
-                        )
-                        and _response_obj is not None
-                        and _response_obj.usage is None
+                    _response_obj: Final[object] = getattr(openai_responses_api_chunk, "response", None)
+                    if _chunk_type in (
+                        openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
+                        openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
                     ):
-                        _response_obj.usage = _estimate_usage_safely(
-                            self.model or "",
-                            self.request_data.get("input"),
-                            self.request_data,
-                            self._generated_content + self._generated_tool_arguments,
-                        )
+                        if isinstance(_response_obj, ResponsesAPIResponse) and _response_obj.usage is None:
+                            _response_obj.usage = _estimate_usage_safely(
+                                self.model or "",
+                                self.request_data.get("input"),
+                                self.request_data,
+                                self._generated_content + self._generated_tool_arguments,
+                            )
+                        elif isinstance(_response_obj, dict) and _response_obj.get("usage") is None:  # pyright: ignore[reportUnknownMemberType]  # the model_constructed terminal event leaves response as an untyped dict
+                            _response_obj["usage"] = _estimate_usage_safely(
+                                self.model or "",
+                                self.request_data.get("input"),
+                                self.request_data,
+                                self._generated_content + self._generated_tool_arguments,
+                            )
                     _stamp_responses_usage_cost(getattr(openai_responses_api_chunk, "response", None), self.logging_obj)
 
                     if _chunk_type == openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED:
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index 8a76b0bedff..8cf9556761e 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -849,3 +849,45 @@ async def test_completed_event_without_usage_counts_tool_input_deltas(tool_delta
     assert usage is not None
     assert usage.output_tokens > 0
     assert usage.total_tokens == usage.input_tokens + usage.output_tokens
+
+
+@pytest.mark.asyncio
+async def test_completed_event_with_a_dict_response_still_gets_the_usage_estimate():
+    """transform_streaming_response can model_construct a terminal event whose
+    response stays a plain dict; the estimate must fill it without raising."""
+    dict_response: Final = {
+        "id": "resp_dict",
+        "model": "gpt-4o-mini",
+        "object": "response",
+        "output": [],
+        "usage": None,
+    }
+
+    def _transform(model, parsed_chunk, logging_obj):
+        if parsed_chunk.get("type") == "response.completed":
+            return ResponseCompletedEvent.model_construct(type="response.completed", response=dict_response)
+        stub: Final = Mock()
+        stub.type = parsed_chunk.get("type")
+        if "delta" in parsed_chunk:
+            stub.delta = parsed_chunk.get("delta")
+        return stub
+
+    config: Final = Mock(spec=BaseResponsesAPIConfig)
+    config.transform_streaming_response.side_effect = _transform
+    iterator: Final = _make_iterator(
+        sse_events=[
+            _sse_event({"type": "response.output_text.delta", "delta": "hello world"}),
+            _sse_event({"type": "response.completed", "response": {}}),
+        ],
+        logging_obj=_logging_obj_stub(),
+        config=config,
+        request_data={"input": "count these input tokens please"},
+    )
+
+    async for _ in iterator:
+        pass
+
+    usage: Final = iterator.completed_response.response["usage"]
+    assert usage is not None
+    assert usage.input_tokens > 0
+    assert usage.output_tokens > 0

From 133f1e8ef56a2870e175128f68eb434c5061d8d4 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 02:06:42 +0000
Subject: [PATCH 46/67] test(fireworks-ai): drop the explanatory comment on the
 cache-read constant

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../llms/fireworks_ai/test_fireworks_ai_cost_calculator.py      | 2 --
 1 file changed, 2 deletions(-)

diff --git a/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py b/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
index f461f17b627..1bee310d9d3 100644
--- a/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
+++ b/tests/test_litellm/llms/fireworks_ai/test_fireworks_ai_cost_calculator.py
@@ -15,8 +15,6 @@ from litellm.types.utils import (
 
 MODEL = "accounts/fireworks/models/glm-5p2"
 INPUT_COST = 1.4e-06
-# Read the cached rate from the price map so this test tracks the shipped value
-# (glm-5p2 is $0.14/1M) instead of hardcoding a number that breaks when it changes.
 CACHE_READ_COST = litellm.get_model_info(model=MODEL, custom_llm_provider="fireworks_ai")["cache_read_input_token_cost"]
 OUTPUT_COST = 4.4e-06
 

From 8cce2b196a0388873d34b3bf42f3f772105df3c4 Mon Sep 17 00:00:00 2001
From: aniket-kardile <aniket.kardile@singulr.ai>
Date: Tue, 15 Sep 2026 19:14:49 -0700
Subject: [PATCH 47/67] feat(guardrails): singulr v2 API contract with
 logging_only, pre_mcp_call and post_mcp_call

Squash of BerriAI/litellm#37464 (head da298ca7) by @aniket-kardile, adopted onto main: v2 gateway payload contract with request, response, mcp_request and mcp_response scopes, typed payload models, proxy user, org and team metadata forwarded to Singulr, and the logging_only, pre_mcp_call and post_mcp_call modes.
---
 .../guardrail_hooks/singulr/singulr.py        |  472 ++++++-
 .../guardrails/guardrail_hooks/singulr.py     |   55 +-
 .../guardrail_hooks/test_singulr.py           | 1127 +++++++++++++++--
 3 files changed, 1447 insertions(+), 207 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py b/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py
index 5109f09d9c2..e0dcdf02069 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py
@@ -1,4 +1,9 @@
+import asyncio
+import json
 import os
+from collections.abc import Mapping, Sequence
+from datetime import datetime, timezone
+from types import MappingProxyType
 from typing import Any, Final
 from urllib.parse import urlparse
 
@@ -19,20 +24,30 @@ from litellm.llms.custom_httpx.http_handler import (
     get_async_httpx_client,
     httpxSpecialProvider,
 )
+from litellm.proxy._types import UserAPIKeyAuth
 from litellm.types.guardrails import GuardrailEventHooks
 from litellm.types.proxy.guardrails.guardrail_hooks.base import (
     GuardrailConfigModel,
 )
 from litellm.types.proxy.guardrails.guardrail_hooks.singulr import (
+    AssistantMessage,
     SingulrGuardrailPayload,
-    SingulrGuardrailRequest,
     SingulrGuardrailResponse,
+    SingulrMcpGuardrailPayload,
+    ToolCall,
+    ToolCallFunction,
+)
+from litellm.types.utils import (
+    GenericGuardrailAPIInputs,
+    GuardrailStatus,
+    StandardLoggingGuardrailInformation,
 )
-from litellm.types.utils import GenericGuardrailAPIInputs
 
 _DEFAULT_API_BASE: Final = "http://localhost:8003"
-_GUARD_ENDPOINT: Final = "/api/v1/ai-gateway/litellm"
+_GUARD_ENDPOINT: Final = "/api/v1/ai-gateway/litellm-v2"
 _DEFAULT_TIMEOUT: Final = 30.0
+_EMPTY_MAPPING: Final[Mapping[str, Any]] = MappingProxyType({})
+_MCP_MODEL_PREFIX: Final = "MCP:"
 
 
 class _CustomGuardrailOptions(TypedDict, total=False, extra_items=object):
@@ -51,8 +66,8 @@ class SingulrGuardrail(CustomGuardrail):
         **kwargs: Unpack[_CustomGuardrailOptions],
     ) -> None:
         self.singulr_api_key = singulr_api_key or os.environ.get("SINGULR_API_KEY")
-        self.singulr_api_base = (singulr_api_base or os.environ.get("SINGULR_API_BASE") or _DEFAULT_API_BASE).rstrip(
-            "/"
+        self.singulr_api_base = (
+            (singulr_api_base or os.environ.get("SINGULR_API_BASE") or _DEFAULT_API_BASE).strip().rstrip("/")
         )
         parsed: Final = urlparse(self.singulr_api_base)
         if parsed.scheme == "http" and parsed.hostname not in (
@@ -85,6 +100,9 @@ class SingulrGuardrail(CustomGuardrail):
             kwargs["supported_event_hooks"] = [
                 GuardrailEventHooks.pre_call,
                 GuardrailEventHooks.post_call,
+                GuardrailEventHooks.logging_only,
+                GuardrailEventHooks.pre_mcp_call,
+                GuardrailEventHooks.post_mcp_call,
             ]
 
         super().__init__(**kwargs)
@@ -97,52 +115,77 @@ class SingulrGuardrail(CustomGuardrail):
 
         return SingulrGuardrailConfigModel
 
-    def _build_payload(
-        self,
-        request_data: dict[str, Any],
-        inputs: GenericGuardrailAPIInputs,
-        input_type: str,
-    ) -> dict[str, object]:
-        if not request_data:
-            texts: Final = inputs.get("texts", [])
+    @staticmethod
+    def _metadata_containers(request_data: Mapping[str, Any]) -> tuple[Mapping[str, Any], ...]:
+        """Candidate metadata dicts to check, in priority order.
 
-            payload = SingulrGuardrailPayload(
-                input_type=input_type,
-                is_playground_request=True,
-                playground_text=texts[0] if texts else None,
+        Most call paths put metadata at the top level of ``request_data``
+        (``litellm_metadata`` or ``metadata``). ``post_mcp_call`` instead hands
+        us ``litellm_logging_obj.model_call_details``, which nests it under
+        ``litellm_params`` instead, so that's checked as a fallback.
+        """
+        litellm_params: Final = request_data.get("litellm_params") or _EMPTY_MAPPING
+        return tuple(
+            container
+            for container in (
+                request_data.get("litellm_metadata"),
+                request_data.get("metadata"),
+                litellm_params.get("litellm_metadata") if litellm_params else None,
+                litellm_params.get("metadata") if litellm_params else None,
             )
-        else:
-            response: Final = request_data.get("response")
-            singulr_req_object: Final = SingulrGuardrailRequest(
-                model=request_data.get("model"),
-                messages=request_data.get("messages"),
-                tools=request_data.get("tools"),
-                model_response=response.model_dump(mode="json") if input_type == "response" and response else None,
-                litellm_metadata=request_data.get("litellm_metadata"),
-            )
-            payload = SingulrGuardrailPayload(
-                litellm_call_id=request_data.get("litellm_call_id"),
-                request_data=singulr_req_object,
-                input_type=input_type,
-            )
-
-        return payload.model_dump(mode="json")
-
-    def _build_headers(self) -> dict[str, str]:
-        return dict(
-            (header, value)
-            for header, value in (
-                ("Content-Type", "application/json"),
-                ("X-Singulr-Gateway-Token", self.singulr_api_key),
-                (
-                    "X-Singulr-Enforcement-Entity-Id",
-                    self.singulr_application_id or "",
-                ),
-                ("X-Singulr-Guardrail-Id", self.singulr_guardrail_id or ""),
-            )
-            if value
+            if container
         )
 
+    @classmethod
+    def _resolve_metadata_value(cls, request_data: Mapping[str, Any], key: str) -> str | None:
+        for container in cls._metadata_containers(request_data=request_data):
+            value = container.get(key)
+            if value:
+                return value
+        return None
+
+    @classmethod
+    def _resolve_user_role_from_request_data(cls, request_data: Mapping[str, Any]) -> str | None:
+        for container in cls._metadata_containers(request_data=request_data):
+            auth = container.get("user_api_key_auth")
+            if isinstance(auth, UserAPIKeyAuth) and auth.user_role:
+                return auth.user_role.value
+        return None
+
+    @classmethod
+    def _build_metadata(cls, request_data: Mapping[str, Any]) -> Mapping[str, Any] | None:
+        fields: Final = (
+            "user_api_key_alias",
+            "user_api_key_user_id",
+            "user_api_key_user_email",
+            "user_api_key_org_id",
+            "user_api_key_org_alias",
+            "user_api_key_team_id",
+            "user_api_key_team_alias",
+        )
+        resolved: Final = (
+            *((field, cls._resolve_metadata_value(request_data=request_data, key=field)) for field in fields),
+            ("user_api_key_user_role", cls._resolve_user_role_from_request_data(request_data=request_data)),
+        )
+        if not any(value for _, value in resolved):
+            return None
+        return {key: value for key, value in resolved if value}  # mutable-ok: short-lived JSON payload dict
+
+    @staticmethod
+    def _build_user_message(text: str) -> Mapping[str, Any]:
+        return {"role": "user", "content": text}  # mutable-ok: short-lived JSON payload dict
+
+    def _build_headers(self) -> Mapping[str, str]:
+        all_headers: Final = MappingProxyType(
+            {
+                "Content-Type": "application/json",
+                "X-Singulr-Gateway-Token": self.singulr_api_key,
+                "X-Singulr-Enforcement-Entity-Id": self.singulr_application_id,
+                "X-Singulr-Guardrail-Id": self.singulr_guardrail_id,
+            }
+        )
+        return MappingProxyType({header: value for header, value in all_headers.items() if value})
+
     async def _call_api(self, payload: dict[str, object]) -> SingulrGuardrailResponse | None:
         endpoint: Final = f"{self.singulr_api_base}{_GUARD_ENDPOINT}"
         verbose_proxy_logger.debug("Singulr: %s", endpoint)
@@ -168,7 +211,7 @@ class SingulrGuardrail(CustomGuardrail):
             if self.block_on_error:
                 raise GuardrailRaisedException(
                     guardrail_name=self.guardrail_name,
-                    message=(f"Singulr API returned HTTP {exc.response.status_code}: {exc.response.text}"),
+                    message=f"Singulr API returned HTTP {exc.response.status_code}: {exc.response.text}",
                 ) from exc
             return None
 
@@ -190,33 +233,328 @@ class SingulrGuardrail(CustomGuardrail):
                 ) from exc
             return None
 
-    @log_guardrail_information
-    async def apply_guardrail(
+    async def _apply_guardrail_on_request(
         self,
         inputs: GenericGuardrailAPIInputs,
-        request_data: dict,
-        input_type: str,
-        logging_obj: "LiteLLMLoggingObj | None" = None,
+        texts: Sequence[str],
+        structured_messages: Sequence[Any],
+        request_data: Mapping[str, Any],
     ) -> GenericGuardrailAPIInputs:
-        payload: Final = self._build_payload(request_data, inputs, input_type)
-        if not payload:
-            return inputs
-
-        result: Final = await self._call_api(payload)
-        if result is None:
-            return inputs
-
-        verbose_proxy_logger.debug(
-            "Singulr: should_block=%s blocking_due_to=%s",
-            result.should_block,
-            result.blocking_due_to,
+        messages: Final = (
+            tuple(structured_messages)
+            if structured_messages
+            else tuple(self._build_user_message(text) for text in texts)
         )
 
-        if result.should_block:
+        images: Final = inputs.get("images")
+        tools: Final = inputs.get("tools")
+
+        if not messages and not images and not tools:
+            verbose_proxy_logger.debug("Singulr: No messages, images, or tools to check after filtering")
+            return inputs
+
+        metadata: Final = self._build_metadata(request_data=request_data)
+
+        singulr_req_obj = SingulrGuardrailPayload(
+            correlation_id=request_data.get("litellm_call_id"),
+            model_name=inputs.get("model"),
+            guardrail_scope="request",
+            messages=messages,
+            images=images,
+            tools=tools,
+            metadata=metadata,
+        )
+        payload = singulr_req_obj.model_dump(mode="json")
+        guardrail_resp = await self._call_api(payload)
+
+        if guardrail_resp is None:
+            return inputs
+
+        if guardrail_resp.should_block:
             raise GuardrailRaisedException(
                 guardrail_name=self.guardrail_name,
-                message=f"Blocked by Singulr: {result.blocking_due_to or 'unknown'}",
+                status_code=400,
+                message=f"Blocked by Singulr, Blocking due to {guardrail_resp.blocking_due_to or 'unknown'}",
+                blocked_content=True,
+            )
+        return inputs
+
+    async def _apply_guardrail_on_mcp_request(self, request_data: Mapping[str, Any]) -> None:
+        metadata: Final = self._build_metadata(request_data=request_data)
+
+        singulr_mcp_obj = SingulrMcpGuardrailPayload(
+            guardrail_scope="mcp_request",
+            tool_name=request_data.get("mcp_tool_name"),
+            tool_arguments=request_data.get("mcp_arguments"),
+            mcp_server_name=request_data.get("mcp_server_name"),
+            metadata=metadata,
+        )
+        payload = singulr_mcp_obj.model_dump(mode="json")
+        guardrail_resp = await self._call_api(payload)
+
+        if guardrail_resp is None:
+            return
+
+        if guardrail_resp.should_block:
+            raise GuardrailRaisedException(
+                guardrail_name=self.guardrail_name,
+                status_code=400,
+                message=f"Blocked by Singulr, Blocking due to {guardrail_resp.blocking_due_to or 'unknown'}",
+                blocked_content=True,
+            )
+
+    async def _apply_guardrail_on_mcp_response(
+        self, inputs: GenericGuardrailAPIInputs, texts: Sequence[str], request_data: Mapping[str, Any]
+    ) -> GenericGuardrailAPIInputs:
+        if not texts:
+            return inputs
+
+        metadata: Final = self._build_metadata(request_data=request_data)
+
+        singulr_mcp_obj = SingulrMcpGuardrailPayload(
+            model_name=request_data.get("model"),
+            guardrail_scope="mcp_response",
+            tool_result=texts,
+            metadata=metadata,
+        )
+        payload = singulr_mcp_obj.model_dump(mode="json")
+        guardrail_resp = await self._call_api(payload)
+
+        if guardrail_resp is None:
+            return inputs
+
+        if guardrail_resp.should_block:
+            raise GuardrailRaisedException(
+                guardrail_name=self.guardrail_name,
+                status_code=400,
+                message=f"Blocked by Singulr, Blocking due to {guardrail_resp.blocking_due_to or 'unknown'}",
                 blocked_content=True,
             )
 
         return inputs
+
+    @staticmethod
+    def _build_tool_call(tool_call: Mapping[str, Any]) -> "ToolCall | None":
+        tool_call_id: Final = tool_call.get("id")
+        fun: Final = tool_call.get("function")
+        if not tool_call_id or not fun:
+            return None
+        func_name: Final = fun.get("name")
+        args: Final = fun.get("arguments")
+        if not func_name or args is None:
+            return None
+        call_type: Final = tool_call.get("type")
+        return ToolCall(
+            id=tool_call_id,
+            type=call_type if isinstance(call_type, str) and call_type else "function",
+            function=ToolCallFunction(
+                name=func_name,
+                arguments=args if isinstance(args, str) else json.dumps(args, default=str),
+            ),
+        )
+
+    async def _apply_guardrail_on_response(
+        self, inputs: GenericGuardrailAPIInputs, texts: Sequence[str], request_data: Mapping[str, Any]
+    ) -> GenericGuardrailAPIInputs:
+        combined_texts: Final = "\n".join(texts) if texts else None
+
+        tool_calls: Final = inputs.get("tool_calls", ())
+        tool_calls_res: Final = tuple(
+            tool_call_res
+            for tool_call_res in (self._build_tool_call(tool_call) for tool_call in tool_calls)
+            if tool_call_res is not None
+        )
+
+        assistant_message: Final = AssistantMessage(
+            role="assistant",
+            content=combined_texts,
+            tool_calls=tool_calls_res,
+        )
+
+        metadata: Final = self._build_metadata(request_data=request_data)
+
+        singulr_resp_obj = SingulrGuardrailPayload(
+            correlation_id=request_data.get("litellm_call_id"),
+            guardrail_scope="response",
+            model_name=request_data.get("model"),
+            messages=request_data.get("messages"),
+            images=inputs.get("images"),
+            response=assistant_message,
+            metadata=metadata,
+        )
+
+        payload = singulr_resp_obj.model_dump(mode="json")
+        guardrail_resp = await self._call_api(payload)
+
+        if guardrail_resp is None:
+            return inputs
+
+        if guardrail_resp.should_block:
+            raise GuardrailRaisedException(
+                guardrail_name=self.guardrail_name,
+                status_code=400,
+                message=f"Blocked by Singulr, Blocking due to {guardrail_resp.blocking_due_to or 'unknown'}",
+                blocked_content=True,
+            )
+        return inputs
+
+    def _logging_only_response_payload(
+        self,
+        kwargs: Mapping[str, Any],
+        result: Any,  # noqa: ANN401  # result can be any callback shape
+    ) -> Mapping[str, Any]:
+        metadata: Final = self._build_metadata(request_data=kwargs)
+        try:
+            return SingulrGuardrailPayload(
+                correlation_id=kwargs.get("litellm_call_id"),
+                model_name=kwargs.get("model"),
+                guardrail_scope="response",
+                response=result,
+                metadata=metadata,
+            ).model_dump(mode="json")
+        except Exception as exc:  # noqa: BLE001  # result can be any callback shape; fall back to a stringified report
+            verbose_proxy_logger.debug("Singulr: could not JSON-serialize response, falling back: %s", exc)
+            return {  # mutable-ok: short-lived JSON payload dict
+                "correlation_id": kwargs.get("litellm_call_id"),
+                "guardrail_scope": "response",
+                "response": str(result),
+                "metadata": metadata,
+            }
+
+    async def _report_logging_only(
+        self,
+        kwargs: Mapping[str, Any],
+        result: Any,  # noqa: ANN401  # result can be any callback shape
+    ) -> tuple[SingulrGuardrailResponse | None, ...]:
+        messages: Final = kwargs.get("messages") or ()
+        request_verdict: Final = (
+            await self._call_api(
+                SingulrGuardrailPayload(
+                    correlation_id=kwargs.get("litellm_call_id"),
+                    model_name=kwargs.get("model"),
+                    guardrail_scope="request",
+                    messages=messages,
+                    metadata=self._build_metadata(request_data=kwargs),
+                ).model_dump(mode="json")
+            )
+            if messages
+            else None
+        )
+        response_verdict: Final = (
+            await self._call_api(self._logging_only_response_payload(kwargs=kwargs, result=result)) if result else None
+        )
+        return (request_verdict, response_verdict)
+
+    async def _logging_only_guardrail_status(
+        self,
+        kwargs: Mapping[str, Any],
+        result: Any,  # noqa: ANN401  # result can be any callback shape
+    ) -> GuardrailStatus | None:
+        """``None`` means no verdict was reached, so nothing should be logged."""
+        try:
+            verdicts: Final = await self._report_logging_only(kwargs=kwargs, result=result)
+        except GuardrailRaisedException:
+            return "guardrail_intervened"
+        except Exception as exc:  # noqa: BLE001  # logging_only must never break the request
+            verbose_proxy_logger.debug("Singulr: logging_only hook swallowed exception: %s", exc)
+            return None
+        if any(verdict is not None and verdict.should_block for verdict in verdicts):
+            return "guardrail_intervened"
+        return "success"
+
+    @staticmethod
+    def _is_mcp_call(kwargs: Mapping[str, Any]) -> bool:
+        model: Final = kwargs.get("model")
+        return isinstance(model, str) and model.startswith(_MCP_MODEL_PREFIX)
+
+    async def async_logging_hook(
+        self,
+        kwargs: dict,  # mutable-ok: matches CustomLogger override; mutated via setdefault
+        result: Any,  # noqa: ANN401  # required by CustomLogger.async_logging_hook override signature
+        call_type: str,
+    ) -> tuple[dict, Any]:
+        if self._is_mcp_call(kwargs):
+            verbose_proxy_logger.debug("Singulr: skipping logging_only report for MCP call %s", kwargs.get("model"))
+            return kwargs, result
+
+        start_time: Final = datetime.now(timezone.utc)
+        guardrail_status: Final = await self._logging_only_guardrail_status(kwargs=kwargs, result=result)
+        if guardrail_status is None:
+            return kwargs, result
+
+        end_time: Final = datetime.now(timezone.utc)
+        slg: Final = StandardLoggingGuardrailInformation(
+            guardrail_name=self.guardrail_name or "singulr",
+            guardrail_mode=GuardrailEventHooks.logging_only,
+            guardrail_status=guardrail_status,
+            start_time=start_time.timestamp(),
+            end_time=end_time.timestamp(),
+            duration=(end_time - start_time).total_seconds(),
+            masked_entity_count=None,
+        )
+        standard_logging_object: Final = kwargs.setdefault(
+            "standard_logging_object",
+            {},  # mutable-ok: shared, mutated accumulator
+        )
+        existing = standard_logging_object.get("guardrail_information")
+        if isinstance(existing, list):
+            existing.append(slg)
+        else:
+            standard_logging_object["guardrail_information"] = [slg]  # mutable-ok: shared accumulator
+
+        return kwargs, result
+
+    def logging_hook(
+        self,
+        kwargs: dict,  # mutable-ok: required by CustomLogger.logging_hook override signature
+        result: Any,  # noqa: ANN401  # required by CustomLogger.logging_hook override signature
+        call_type: str,
+    ) -> tuple[dict, Any]:
+        try:
+            try:
+                loop = asyncio.get_event_loop()
+            except RuntimeError:
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+            if loop.is_running():
+                verbose_proxy_logger.debug(
+                    "Singulr: sync logging_hook called from a running loop; skipping logging_only report"
+                )
+                return kwargs, result
+            loop.run_until_complete(self.async_logging_hook(kwargs=kwargs, result=result, call_type=call_type))
+        except Exception as exc:  # noqa: BLE001  # logging_only must never break the request
+            verbose_proxy_logger.debug("Singulr: sync logging_hook swallowed exception: %s", exc)
+        return kwargs, result
+
+    @log_guardrail_information
+    async def apply_guardrail(
+        self,
+        inputs: GenericGuardrailAPIInputs,
+        request_data: dict,  # mutable-ok: required by CustomGuardrail.apply_guardrail override signature
+        input_type: str,
+        logging_obj: "LiteLLMLoggingObj | None" = None,
+    ) -> GenericGuardrailAPIInputs:
+        texts: Final = inputs.get("texts", ())
+        structured_messages: Final = inputs.get("structured_messages", ())
+
+        verbose_proxy_logger.debug(
+            "Singulr Guardrail: apply_guardrail called with input_type=%s, texts=%d, structured_messages=%d",
+            input_type,
+            len(texts),
+            len(structured_messages),
+        )
+
+        if input_type == "request":
+            if request_data.get("mcp_tool_name"):
+                await self._apply_guardrail_on_mcp_request(request_data=request_data)
+                return inputs
+            return await self._apply_guardrail_on_request(
+                inputs=inputs, texts=texts, structured_messages=structured_messages, request_data=request_data
+            )
+        elif input_type == "response":
+            if request_data.get("call_type") == "call_mcp_tool":
+                return await self._apply_guardrail_on_mcp_response(
+                    inputs=inputs, texts=texts, request_data=request_data
+                )
+            return await self._apply_guardrail_on_response(inputs=inputs, texts=texts, request_data=request_data)
+        return inputs
diff --git a/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py b/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py
index d0d19d191c1..fd349b44e0c 100644
--- a/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py
+++ b/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py
@@ -1,30 +1,59 @@
-from typing import Any
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
 from .base import GuardrailConfigModel
 
 
-class SingulrGuardrailRequest(BaseModel):
-    model: str | None = None
-    messages: list[dict[str, Any]] | None = None
-    tools: list[dict[str, Any]] | None = None
-    model_response: dict[str, Any] | None = None
-    litellm_metadata: dict[str, Any] | None = None
+class ContentBlock(BaseModel):
+    type: str | None = None
+    text: str | None = None
+
+
+class ToolCallFunction(BaseModel):
+    name: str
+    arguments: str
+
+
+class ToolCall(BaseModel):
+    id: str
+    type: str = "function"
+    function: ToolCallFunction
+
+
+class AssistantMessage(BaseModel):
+    role: Literal["assistant"] = "assistant"
+    content: str | Sequence[ContentBlock] | None = None
+    tool_calls: Sequence[ToolCall] | None = None
 
 
 class SingulrGuardrailPayload(BaseModel):
-    litellm_call_id: str | None = None
-    request_data: SingulrGuardrailRequest | None = None
-    input_type: str
-    is_playground_request: bool | None = None
-    playground_text: str | None = None
+    correlation_id: str | None = None
+    model_name: str | None = None
+    model_provider_name: str | None = None
+    guardrail_scope: str | None = None
+    messages: Sequence[Any] | None = None
+    images: Sequence[str] | None = None
+    tools: Sequence[Any] | None = None  # pyright: ignore[reportExplicitAny]  # forwards caller-supplied OpenAI tool defs verbatim
+    response: Any = None  # pyright: ignore[reportExplicitAny]  # logging_only reports raw litellm callback results (ModelResponse, EmbeddingResponse, etc.)
+    metadata: Mapping[str, Any] | None = None
+
+
+class SingulrMcpGuardrailPayload(BaseModel):
+    model_name: str | None = None
+    guardrail_scope: str | None = None
+    tool_name: str | None = None
+    tool_arguments: Mapping[str, Any] | None = None
+    mcp_server_name: str | None = None
+    tool_result: Sequence[str] | None = None
+    metadata: Mapping[str, Any] | None = None
 
 
 class SingulrGuardrailResponse(BaseModel):
     """Response returned by the Singulr guardrail API."""
 
-    should_block: bool = False
+    should_block: bool | None = None
     blocking_due_to: str | None = None
 
 
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py
index 14d8e90e027..7a228a7c3fb 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py
@@ -1,14 +1,17 @@
+import json
 from unittest.mock import MagicMock, patch
 
 import httpx
 import pytest
 
 from litellm.exceptions import GuardrailRaisedException
+from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth
 from litellm.proxy.guardrails.guardrail_hooks.singulr.singulr import SingulrGuardrail
 from litellm.types.guardrails import GuardrailEventHooks
 from litellm.types.proxy.guardrails.guardrail_hooks.singulr import (
     SingulrGuardrailConfigModel,
 )
+from litellm.types.utils import ModelResponse
 
 
 # ---------------------------------------------------------------------------
@@ -55,6 +58,31 @@ class TestSingulrConfiguration:
         assert guardrail.singulr_guardrail_id == "id123"
         assert guardrail.singulr_application_id == "entity123"
 
+    def test_api_base_strips_surrounding_whitespace(self):
+        """Regression: a UI-saved api_base with a trailing space
+        (e.g. "https://custom.api.local ") broke urlparse's port parsing and
+        made every guardrail call fail with a connection error, even though
+        the configured host was reachable."""
+        guardrail = SingulrGuardrail(
+            singulr_api_key="test_key",
+            singulr_api_base=" https://custom.api.local ",
+        )
+        assert guardrail.singulr_api_base == "https://custom.api.local"
+
+    def test_api_base_strips_trailing_slash(self):
+        guardrail = SingulrGuardrail(singulr_api_key="test_key", singulr_api_base="https://custom.api.local/")
+        assert guardrail.singulr_api_base == "https://custom.api.local"
+
+    def test_non_local_http_api_base_raises(self):
+        """Guardrail payloads carry the API token and full conversation
+        content, so a non-local endpoint must use HTTPS."""
+        with pytest.raises(ValueError, match="HTTPS"):
+            SingulrGuardrail(singulr_api_key="test_key", singulr_api_base="http://guardrails.singulr.ai")
+
+    def test_localhost_http_api_base_is_allowed(self):
+        guardrail = SingulrGuardrail(singulr_api_key="test_key", singulr_api_base="http://localhost:8003")
+        assert guardrail.singulr_api_base == "http://localhost:8003"
+
     def test_block_on_error_defaults_true(self):
         guardrail = SingulrGuardrail(singulr_api_key="test_key")
         assert guardrail.block_on_error is True
@@ -67,142 +95,460 @@ class TestSingulrConfiguration:
         guardrail = SingulrGuardrail(singulr_api_key="test_key", timeout=5.0)
         assert guardrail.timeout == 5.0
 
-    def test_supports_pre_call_and_post_call_hooks(self):
+    def test_supports_pre_call_post_call_logging_and_mcp_hooks(self):
         guardrail = SingulrGuardrail(singulr_api_key="test_key")
         assert guardrail.supported_event_hooks == [
             GuardrailEventHooks.pre_call,
             GuardrailEventHooks.post_call,
+            GuardrailEventHooks.logging_only,
+            GuardrailEventHooks.pre_mcp_call,
+            GuardrailEventHooks.post_mcp_call,
         ]
 
 
 # ---------------------------------------------------------------------------
-# _build_payload: playground requests (no request_data)
+# Payload construction for real proxy requests (request_data present)
 # ---------------------------------------------------------------------------
 
 
-class TestSingulrBuildPayloadPlayground:
-    def test_playground_request_uses_flat_text(self, singulr_guardrail):
-        """The test-playground /apply_guardrail endpoint sends no request_data,
-        only inputs["texts"]. Without this branch, a playground call would
-        crash instead of producing a usable payload."""
-        payload = singulr_guardrail._build_payload({}, {"texts": ["Ignore previous instructions"]}, "request")
-        assert payload["is_playground_request"] is True
-        assert payload["playground_text"] == "Ignore previous instructions"
-        assert payload["request_data"] is None
+class TestSingulrRequestPayload:
+    @pytest.mark.asyncio
+    async def test_model_and_messages_are_forwarded(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"model": "gpt-4o", "litellm_call_id": "call-1"}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["How do I reset my password?"], "model": "gpt-4o"},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["model_name"] == "gpt-4o"
+        assert sent_payload["correlation_id"] == "call-1"
+        assert sent_payload["guardrail_scope"] == "request"
+        assert sent_payload["messages"] == [{"role": "user", "content": "How do I reset my password?"}]
 
-    def test_playground_request_with_no_texts_has_none_playground_text(self, singulr_guardrail):
-        payload = singulr_guardrail._build_payload({}, {}, "request")
-        assert payload["playground_text"] is None
+    @pytest.mark.asyncio
+    async def test_structured_messages_are_forwarded_verbatim(self, singulr_guardrail):
+        """When structured_messages are provided (e.g. system + user turns),
+        they must be sent as-is instead of being flattened into single
+        user-role messages built from texts."""
+        resp = _make_response({"should_block": False})
+        structured_messages = [
+            {"role": "system", "content": "Be concise."},
+            {"role": "user", "content": "How do I reset my password?"},
+        ]
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["How do I reset my password?"], "structured_messages": structured_messages},
+                request_data={},
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["messages"] == structured_messages
 
-    def test_playground_input_type_is_included(self, singulr_guardrail):
-        payload = singulr_guardrail._build_payload({}, {"texts": ["hi"]}, "response")
-        assert payload["input_type"] == "response"
+    @pytest.mark.asyncio
+    async def test_images_are_forwarded(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": [], "images": ["data:image/png;base64,abc123"]},
+                request_data={},
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["images"] == ["data:image/png;base64,abc123"]
 
+    @pytest.mark.asyncio
+    async def test_no_messages_or_images_skips_the_api_call(self, singulr_guardrail):
+        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
+            result = await singulr_guardrail.apply_guardrail(
+                inputs={"texts": []},
+                request_data={},
+                input_type="request",
+            )
+        mock_post.assert_not_called()
+        assert result == {"texts": []}
 
-# ---------------------------------------------------------------------------
-# _build_payload: real proxy requests (request_data present)
-# ---------------------------------------------------------------------------
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "extra_inputs",
+        [
+            {"tools": [{"type": "function", "function": {"name": "delete_file", "description": "", "parameters": {}}}]},
+            {"images": ["data:image/png;base64,abc123"]},
+        ],
+        ids=["tools_alone", "images_alone"],
+    )
+    async def test_tools_or_images_alone_still_trigger_the_api_call(self, singulr_guardrail, extra_inputs):
+        """Regression: a request with only tool definitions or only images and
+        no text must still be checked, not skipped for lack of a message."""
+        resp = _make_response({"should_block": False})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": [], **extra_inputs},
+                request_data={},
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        for key, value in extra_inputs.items():
+            assert sent_payload[key] == value
 
+    @pytest.mark.asyncio
+    async def test_tools_are_forwarded(self, singulr_guardrail):
+        """Regression: tool/function definitions are client-controlled and can
+        carry prompt-injection content, so they must reach Singulr for
+        inspection instead of only messages and images."""
+        resp = _make_response({"should_block": False})
+        tools = [
+            {
+                "type": "function",
+                "function": {"name": "search_docs", "description": "Search internal docs", "parameters": {}},
+            }
+        ]
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["How do I reset my password?"], "tools": tools},
+                request_data={},
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["tools"] == tools
 
-class TestSingulrBuildPayloadRequestData:
-    def test_model_messages_and_tools_are_forwarded(self, singulr_guardrail):
+    @pytest.mark.asyncio
+    async def test_responses_api_mcp_tools_are_forwarded(self, singulr_guardrail):
+        """Regression: Responses API tools (e.g. {"type": "mcp", "server_label": ...})
+        have no "function" key, unlike Chat Completions tools. SingulrGuardrailPayload
+        rejected them with a pydantic ValidationError, turning every Responses API
+        request carrying an MCP tool into a 500."""
+        resp = _make_response({"should_block": False})
+        tools = [
+            {
+                "type": "mcp",
+                "server_label": "docs-server",
+                "server_url": "https://mcp.example.com",
+                "allowed_tools": ["search_docs"],
+            }
+        ]
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["How do I reset my password?"], "tools": tools},
+                request_data={},
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["tools"] == tools
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_alias_is_forwarded_in_metadata(self, singulr_guardrail):
+        """Regression: the alias must be sent as {"user_api_key_alias": <alias>},
+        not as a dict whose key is the alias value itself."""
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_alias": "my-key-alias"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_alias": "my-key-alias"}
+
+    @pytest.mark.asyncio
+    async def test_falls_back_to_regular_metadata_for_key_alias(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"metadata": {"user_api_key_alias": "fallback-alias"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_alias": "fallback-alias"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_user_id_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_user_id": "my-user-id"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_user_id": "my-user-id"}
+
+    @pytest.mark.asyncio
+    async def test_falls_back_to_regular_metadata_for_user_id(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"metadata": {"user_api_key_user_id": "fallback-user-id"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_user_id": "fallback-user-id"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_user_email_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_user_email": "user@example.com"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_user_email": "user@example.com"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_organization_alias_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_org_alias": "Acme Org"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_org_alias": "Acme Org"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_team_alias_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_team_alias": "AI Content Security Team"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_team_alias": "AI Content Security Team"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_org_id_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_org_id": "org-123"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_org_id": "org-123"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_team_id_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_team_id": "team-456"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_team_id": "team-456"}
+
+    @pytest.mark.asyncio
+    async def test_user_api_key_user_role_is_forwarded_in_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        auth = UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY)
+        request_data = {"litellm_metadata": {"user_api_key_auth": auth}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_user_role": LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value}
+
+    @pytest.mark.asyncio
+    async def test_no_user_role_available_omits_role_from_metadata(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"litellm_metadata": {"user_api_key_alias": "my-key-alias"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert "user_api_key_user_role" not in sent_payload["metadata"]
+
+    @pytest.mark.asyncio
+    async def test_all_user_metadata_fields_forwarded_together(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        auth = UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY)
         request_data = {
-            "model": "gpt-4o",
-            "messages": [{"role": "user", "content": "How do I reset my password?"}],
-            "tools": [{"type": "function", "function": {"name": "get_weather"}}],
+            "litellm_metadata": {
+                "user_api_key_alias": "my-key-alias",
+                "user_api_key_user_id": "my-user-id",
+                "user_api_key_user_email": "user@example.com",
+                "user_api_key_org_id": "org-123",
+                "user_api_key_org_alias": "Acme Org",
+                "user_api_key_team_id": "team-456",
+                "user_api_key_team_alias": "AI Content Security Team",
+                "user_api_key_auth": auth,
+            }
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {
+            "user_api_key_alias": "my-key-alias",
+            "user_api_key_user_id": "my-user-id",
+            "user_api_key_user_email": "user@example.com",
+            "user_api_key_org_id": "org-123",
+            "user_api_key_org_alias": "Acme Org",
+            "user_api_key_team_id": "team-456",
+            "user_api_key_team_alias": "AI Content Security Team",
+            "user_api_key_user_role": LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value,
         }
-        payload = singulr_guardrail._build_payload(request_data, {"texts": []}, "request")
-        assert payload["request_data"]["model"] == "gpt-4o"
-        assert payload["request_data"]["messages"] == request_data["messages"]
-        assert payload["request_data"]["tools"] == request_data["tools"]
-        assert payload["is_playground_request"] is None
 
-    def test_model_response_absent_on_request_side(self, singulr_guardrail):
-        """The response hasn't happened yet at request time, so model_response
-        must not be forwarded even if request_data carries a stale response
-        object from a previous call."""
-        from litellm.types.utils import ModelResponse
+    @pytest.mark.asyncio
+    async def test_no_key_alias_available_sends_no_metadata(self, singulr_guardrail):
+        """Regression: with no alias found, metadata must be omitted (None),
+        not a {None: None} dict that fails payload validation."""
+        resp = _make_response({"should_block": False})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data={},
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] is None
 
-        request_data = {"model": "gpt-4o", "response": ModelResponse()}
-        payload = singulr_guardrail._build_payload(request_data, {"texts": []}, "request")
-        assert payload["request_data"]["model_response"] is None
 
-    def test_model_response_is_forwarded_and_json_serializable(self, singulr_guardrail):
-        """Regression: request_data["response"] is a ModelResponse (pydantic)
-        object containing nested non-JSON-safe values (e.g. a `created`
-        unix timestamp is fine, but nested pydantic submodels are not plain
-        dicts). Without mode="json" on both the inner and outer dumps, this
-        payload cannot be sent via httpx's json= kwarg."""
-        import json as _json
+# ---------------------------------------------------------------------------
+# Payload construction for responses
+# ---------------------------------------------------------------------------
 
-        from litellm.types.utils import Choices, Message, ModelResponse, Usage
 
-        response = ModelResponse(
-            choices=[Choices(message=Message(role="assistant", content="Go to settings."))],
-            usage=Usage(prompt_tokens=10, completion_tokens=5, total_tokens=15),
-        )
-        request_data = {"model": "gpt-4o", "response": response}
-        payload = singulr_guardrail._build_payload(request_data, {"texts": ["Go to settings."]}, "response")
-
-        # Must not raise - this is what httpx's json= kwarg effectively does.
-        serialized = _json.dumps(payload)
-        assert "Go to settings." in serialized
-        assert payload["request_data"]["model_response"]["choices"][0]["message"]["content"] == "Go to settings."
-
-    def test_model_requested_tool_calls_are_forwarded_in_model_response(self, singulr_guardrail):
-        """Tool calls the model requests arrive inside response.choices[].message.tool_calls.
-        They must survive the dump so Singulr can inspect what tools the
-        model is trying to invoke."""
-        from litellm.types.utils import Choices, Message, ModelResponse
-
-        response = ModelResponse(
-            choices=[
-                Choices(
-                    message=Message(
-                        role="assistant",
-                        content=None,
-                        tool_calls=[
-                            {
-                                "id": "call_1",
-                                "type": "function",
-                                "function": {"name": "get_current_time", "arguments": "{}"},
-                            }
-                        ],
-                    )
-                )
+class TestSingulrResponsePayload:
+    @pytest.mark.asyncio
+    async def test_assistant_text_and_tool_calls_are_forwarded(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        inputs = {
+            "texts": ["Go to settings."],
+            "tool_calls": [
+                {
+                    "id": "call_1",
+                    "type": "function",
+                    "function": {"name": "get_current_time", "arguments": "{}"},
+                }
             ],
-        )
-        request_data = {"model": "gpt-4o", "response": response}
-        payload = singulr_guardrail._build_payload(request_data, {"texts": []}, "response")
-
-        tool_calls = payload["request_data"]["model_response"]["choices"][0]["message"]["tool_calls"]
-        assert tool_calls[0]["function"]["name"] == "get_current_time"
-
-    def test_litellm_metadata_is_forwarded(self, singulr_guardrail):
-        request_data = {"model": "gpt-4o", "litellm_metadata": {"user_api_key_hash": "abc123"}}
-        payload = singulr_guardrail._build_payload(request_data, {"texts": []}, "request")
-        assert payload["request_data"]["litellm_metadata"] == {"user_api_key_hash": "abc123"}
-
-    def test_internal_logging_object_is_not_forwarded(self, singulr_guardrail):
-        """Regression: request_data can carry internal proxy objects (e.g. the
-        Logging instance) that aren't JSON-serializable at all. _build_payload
-        must only pull known request/response fields out of request_data,
-        not dump it wholesale, or this crashes on every real proxy call."""
-        import json as _json
-
-        class _NotSerializable:
-            pass
-
-        request_data = {
-            "model": "gpt-4o",
-            "messages": [{"role": "user", "content": "hi"}],
-            "litellm_logging_obj": _NotSerializable(),
         }
-        payload = singulr_guardrail._build_payload(request_data, {"texts": ["hi"]}, "request")
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data={},
+                input_type="response",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "response"
+        assert sent_payload["response"]["content"] == "Go to settings."
+        assert sent_payload["response"]["tool_calls"][0]["function"]["name"] == "get_current_time"
 
-        # Must not raise.
-        _json.dumps(payload)
-        assert "litellm_logging_obj" not in payload["request_data"]
+    @pytest.mark.asyncio
+    async def test_response_images_are_forwarded(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        inputs = {"texts": ["ok"], "images": ["data:image/png;base64,xyz"]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data={},
+                input_type="response",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["images"] == ["data:image/png;base64,xyz"]
+
+    @pytest.mark.asyncio
+    async def test_incomplete_tool_calls_are_dropped(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        inputs = {
+            "texts": [],
+            "tool_calls": [
+                {"id": None, "type": "function", "function": {"name": "f", "arguments": "{}"}},
+                {"id": "call_2", "type": "function", "function": None},
+                {"id": "call_3", "type": "function", "function": {"name": None, "arguments": "{}"}},
+                {"id": "call_4", "type": "function", "function": {"name": "f", "arguments": None}},
+            ],
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data={},
+                input_type="response",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["response"]["tool_calls"] == []
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "raw_type, expected_type",
+        [(None, "function"), ("custom", "custom")],
+        ids=["type_missing", "type_not_function"],
+    )
+    async def test_tool_call_type_other_than_function_is_still_scanned(
+        self, singulr_guardrail, raw_type, expected_type
+    ):
+        """Regression: a tool call whose type is absent or isn't "function" used
+        to raise a pydantic ValidationError while building the payload, which
+        escaped apply_guardrail as a 500 instead of reaching the scan at all."""
+        resp = _make_response({"should_block": False})
+        tool_call = {"id": "call_1", "function": {"name": "get_current_time", "arguments": "{}"}}
+        inputs = {
+            "texts": [],
+            "tool_calls": [tool_call if raw_type is None else {**tool_call, "type": raw_type}],
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(inputs=inputs, request_data={}, input_type="response")
+        sent_tool_calls = mock_post.call_args.kwargs["json"]["response"]["tool_calls"]
+        assert [call["type"] for call in sent_tool_calls] == [expected_type]
+        assert sent_tool_calls[0]["function"]["name"] == "get_current_time"
+
+    @pytest.mark.asyncio
+    async def test_non_string_tool_call_arguments_are_serialized(self, singulr_guardrail):
+        """Some providers hand back already-parsed arguments; they must be
+        scanned as JSON text rather than crashing the payload build."""
+        resp = _make_response({"should_block": False})
+        inputs = {
+            "texts": [],
+            "tool_calls": [
+                {"id": "call_1", "type": "function", "function": {"name": "rm", "arguments": {"path": "/etc/passwd"}}}
+            ],
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(inputs=inputs, request_data={}, input_type="response")
+        sent_tool_calls = mock_post.call_args.kwargs["json"]["response"]["tool_calls"]
+        assert json.loads(sent_tool_calls[0]["function"]["arguments"]) == {"path": "/etc/passwd"}
+
+    @pytest.mark.asyncio
+    async def test_block_verdict_still_raises_for_a_non_function_tool_call(self, singulr_guardrail):
+        """The point of scanning these calls: the verdict must still be enforced."""
+        resp = _make_response({"should_block": True, "blocking_due_to": "dangerous_tool"})
+        inputs = {
+            "texts": [],
+            "tool_calls": [{"id": "call_1", "function": {"name": "rm", "arguments": "{}"}}],
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            with pytest.raises(GuardrailRaisedException) as exc_info:
+                await singulr_guardrail.apply_guardrail(inputs=inputs, request_data={}, input_type="response")
+        assert "dangerous_tool" in str(exc_info.value)
 
 
 # ---------------------------------------------------------------------------
@@ -212,8 +558,15 @@ class TestSingulrBuildPayloadRequestData:
 
 class TestSingulrAllowAction:
     @pytest.mark.asyncio
-    async def test_allow_returns_inputs_unchanged(self, singulr_guardrail):
-        resp = _make_response({"should_block": False})
+    @pytest.mark.parametrize(
+        "guard_response",
+        [{"should_block": False}, {}],
+        ids=["should_block_false", "should_block_omitted"],
+    )
+    async def test_should_block_falsy_returns_inputs_unchanged_on_request(self, singulr_guardrail, guard_response):
+        """should_block is optional on the wire; a response that omits it
+        entirely must be treated as allow, not block."""
+        resp = _make_response(guard_response)
         inputs = {"texts": ["How do I reset my password?"]}
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
             result = await singulr_guardrail.apply_guardrail(
@@ -223,18 +576,40 @@ class TestSingulrAllowAction:
             )
             assert result is inputs
 
+    @pytest.mark.asyncio
+    async def test_should_block_false_returns_inputs_unchanged_on_response(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        inputs = {"texts": ["Here is your answer."]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            result = await singulr_guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data={},
+                input_type="response",
+            )
+            assert result is inputs
+
+    @pytest.mark.asyncio
+    async def test_response_returns_inputs_unchanged_when_api_unreachable_and_block_on_error_false(self):
+        guardrail = SingulrGuardrail(
+            singulr_api_base="https://api.test.singulr.ai",
+            singulr_api_key="test_token_1234",
+            guardrail_name="test-singulr",
+            block_on_error=False,
+        )
+        inputs = {"texts": ["Here is your answer."]}
+        with patch.object(guardrail.async_handler, "post", side_effect=httpx.TransportError("unreachable")):
+            result = await guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data={},
+                input_type="response",
+            )
+            assert result is inputs
+
 
 class TestSingulrBlockAction:
     @pytest.mark.asyncio
-    async def test_block_raises_guardrail_exception(self, singulr_guardrail):
-        """Regression: a should_block=True response must stop the request
-        instead of silently letting it through."""
-        resp = _make_response(
-            {
-                "should_block": True,
-                "blocking_due_to": "PII Information detected",
-            }
-        )
+    async def test_should_block_true_raises_on_request(self, singulr_guardrail):
+        resp = _make_response({"should_block": True, "blocking_due_to": "PII Information detected"})
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
             with pytest.raises(GuardrailRaisedException) as exc_info:
                 await singulr_guardrail.apply_guardrail(
@@ -243,6 +618,25 @@ class TestSingulrBlockAction:
                     input_type="request",
                 )
             assert "PII Information detected" in str(exc_info.value)
+            assert exc_info.value.blocked_content is True
+
+    @pytest.mark.asyncio
+    async def test_should_block_true_raises_on_response(self, singulr_guardrail):
+        """Regression: apply_guardrail's response path compared
+        should_block (a bool) against the string "block", which is always
+        False, so a should_block=True response never blocked the assistant's
+        reply. It must raise on any truthy should_block, matching the
+        request path."""
+        resp = _make_response({"should_block": True, "blocking_due_to": "Toxic content detected"})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            with pytest.raises(GuardrailRaisedException) as exc_info:
+                await singulr_guardrail.apply_guardrail(
+                    inputs={"texts": ["Here is something toxic."]},
+                    request_data={},
+                    input_type="response",
+                )
+            assert "Toxic content detected" in str(exc_info.value)
+            assert exc_info.value.blocked_content is True
 
     @pytest.mark.asyncio
     async def test_block_without_reason_uses_unknown_placeholder(self, singulr_guardrail):
@@ -256,6 +650,478 @@ class TestSingulrBlockAction:
                 )
 
 
+# ---------------------------------------------------------------------------
+# MCP tool call guardrail (pre_mcp_call / post_mcp_call)
+# ---------------------------------------------------------------------------
+
+
+class TestSingulrMcpRequest:
+    @pytest.mark.asyncio
+    async def test_mcp_tool_name_routes_to_mcp_request_payload(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {
+            "mcp_tool_name": "search_docs",
+            "mcp_arguments": {"query": "reset password"},
+            "mcp_server_name": "docs-server",
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            result = await singulr_guardrail.apply_guardrail(
+                inputs={"texts": []},
+                request_data=request_data,
+                input_type="request",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "mcp_request"
+        assert sent_payload["tool_name"] == "search_docs"
+        assert sent_payload["tool_arguments"] == {"query": "reset password"}
+        assert sent_payload["mcp_server_name"] == "docs-server"
+        assert result == {"texts": []}
+
+    @pytest.mark.asyncio
+    async def test_mcp_request_should_block_true_raises(self, singulr_guardrail):
+        resp = _make_response({"should_block": True, "blocking_due_to": "Disallowed tool"})
+        request_data = {"mcp_tool_name": "delete_file", "mcp_arguments": {"path": "/etc/passwd"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            with pytest.raises(GuardrailRaisedException, match="Disallowed tool") as exc_info:
+                await singulr_guardrail.apply_guardrail(
+                    inputs={"texts": []},
+                    request_data=request_data,
+                    input_type="request",
+                )
+            assert exc_info.value.blocked_content is True
+
+    @pytest.mark.asyncio
+    async def test_mcp_request_is_a_noop_when_api_unreachable_and_block_on_error_false(self):
+        guardrail = SingulrGuardrail(
+            singulr_api_base="https://api.test.singulr.ai",
+            singulr_api_key="test_token_1234",
+            guardrail_name="test-singulr",
+            block_on_error=False,
+        )
+        request_data = {"mcp_tool_name": "search_docs", "mcp_arguments": {"query": "reset password"}}
+        with patch.object(guardrail.async_handler, "post", side_effect=httpx.TransportError("unreachable")):
+            result = await guardrail.apply_guardrail(
+                inputs={"texts": []},
+                request_data=request_data,
+                input_type="request",
+            )
+        assert result == {"texts": []}
+
+
+class TestSingulrMcpResponse:
+    @pytest.mark.asyncio
+    async def test_call_mcp_tool_response_routes_to_mcp_response_payload(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {
+            "call_type": "call_mcp_tool",
+            "mcp_tool_name": "search_docs",
+            "mcp_server_name": "docs-server",
+            "model": "MCP: docs-server",
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["Result: password reset link sent."]},
+                request_data=request_data,
+                input_type="response",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "mcp_response"
+        assert sent_payload["model_name"] == "MCP: docs-server"
+        assert sent_payload["tool_result"] == ["Result: password reset link sent."]
+
+    @pytest.mark.asyncio
+    async def test_mcp_response_with_no_texts_skips_the_api_call(self, singulr_guardrail):
+        request_data = {"call_type": "call_mcp_tool", "mcp_tool_name": "search_docs"}
+        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
+            result = await singulr_guardrail.apply_guardrail(
+                inputs={"texts": []},
+                request_data=request_data,
+                input_type="response",
+            )
+        mock_post.assert_not_called()
+        assert result == {"texts": []}
+
+    @pytest.mark.asyncio
+    async def test_mcp_response_should_block_true_raises(self, singulr_guardrail):
+        resp = _make_response({"should_block": True, "blocking_due_to": "Sensitive tool output"})
+        request_data = {"call_type": "call_mcp_tool", "mcp_tool_name": "search_docs"}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            with pytest.raises(GuardrailRaisedException, match="Sensitive tool output") as exc_info:
+                await singulr_guardrail.apply_guardrail(
+                    inputs={"texts": ["leaked secret"]},
+                    request_data=request_data,
+                    input_type="response",
+                )
+            assert exc_info.value.blocked_content is True
+
+    @pytest.mark.asyncio
+    async def test_mcp_response_resolves_metadata_from_nested_litellm_params(self, singulr_guardrail):
+        """post_mcp_call hands apply_guardrail litellm_logging_obj.model_call_details,
+        which nests metadata under litellm_params instead of at the top level."""
+        resp = _make_response({"should_block": False})
+        auth = UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY)
+        request_data = {
+            "call_type": "call_mcp_tool",
+            "mcp_tool_name": "search_docs",
+            "litellm_params": {
+                "metadata": {
+                    "user_api_key_alias": "my-key-alias",
+                    "user_api_key_user_id": "my-user-id",
+                    "user_api_key_user_email": "user@example.com",
+                    "user_api_key_org_id": "org-123",
+                    "user_api_key_org_alias": "Acme Org",
+                    "user_api_key_team_id": "team-456",
+                    "user_api_key_team_alias": "AI Content Security Team",
+                    "user_api_key_auth": auth,
+                }
+            },
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["Result: password reset link sent."]},
+                request_data=request_data,
+                input_type="response",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {
+            "user_api_key_alias": "my-key-alias",
+            "user_api_key_user_id": "my-user-id",
+            "user_api_key_user_email": "user@example.com",
+            "user_api_key_org_id": "org-123",
+            "user_api_key_org_alias": "Acme Org",
+            "user_api_key_team_id": "team-456",
+            "user_api_key_team_alias": "AI Content Security Team",
+            "user_api_key_user_role": LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value,
+        }
+
+    @pytest.mark.asyncio
+    async def test_mcp_response_prefers_top_level_metadata_over_nested_litellm_params(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {
+            "call_type": "call_mcp_tool",
+            "mcp_tool_name": "search_docs",
+            "litellm_metadata": {"user_api_key_alias": "top-level-alias"},
+            "litellm_params": {"metadata": {"user_api_key_alias": "nested-alias"}},
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["hi"]},
+                request_data=request_data,
+                input_type="response",
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["metadata"] == {"user_api_key_alias": "top-level-alias"}
+
+    @pytest.mark.asyncio
+    async def test_mcp_response_returns_inputs_unchanged_when_api_unreachable_and_block_on_error_false(self):
+        guardrail = SingulrGuardrail(
+            singulr_api_base="https://api.test.singulr.ai",
+            singulr_api_key="test_token_1234",
+            guardrail_name="test-singulr",
+            block_on_error=False,
+        )
+        request_data = {"call_type": "call_mcp_tool", "mcp_tool_name": "search_docs"}
+        inputs = {"texts": ["leaked secret"]}
+        with patch.object(guardrail.async_handler, "post", side_effect=httpx.TransportError("unreachable")):
+            result = await guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data=request_data,
+                input_type="response",
+            )
+        assert result is inputs
+
+
+# ---------------------------------------------------------------------------
+# apply_guardrail dispatch (request vs response vs unknown input_type)
+# ---------------------------------------------------------------------------
+
+
+class TestSingulrApplyGuardrailDispatch:
+    @pytest.mark.asyncio
+    async def test_unknown_input_type_returns_inputs_unchanged(self, singulr_guardrail):
+        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
+            inputs = {"texts": ["hi"]}
+            result = await singulr_guardrail.apply_guardrail(
+                inputs=inputs,
+                request_data={},
+                input_type="unsupported",
+            )
+        mock_post.assert_not_called()
+        assert result is inputs
+
+
+# ---------------------------------------------------------------------------
+# logging_only hook
+# ---------------------------------------------------------------------------
+
+
+class TestSingulrLoggingHook:
+    @pytest.mark.asyncio
+    async def test_forwards_request_messages_and_response_text(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        kwargs = {"messages": [{"role": "user", "content": "hi"}], "model": "gpt-4o", "litellm_call_id": "call-1"}
+        result = {"choices": [{"finish_reason": "stop", "message": {"content": "hello there"}}]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=result, call_type="acompletion")
+
+        request_payload = mock_post.call_args_list[0].kwargs["json"]
+        response_payload = mock_post.call_args_list[1].kwargs["json"]
+        assert request_payload["guardrail_scope"] == "request"
+        assert request_payload["messages"] == kwargs["messages"]
+        assert response_payload["guardrail_scope"] == "response"
+        assert response_payload["response"] == result
+
+    @pytest.mark.asyncio
+    async def test_forwards_user_metadata_in_both_request_and_response_payloads(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        kwargs = {
+            "messages": [{"role": "user", "content": "hi"}],
+            "model": "gpt-4o",
+            "litellm_call_id": "call-1",
+            "litellm_metadata": {"user_api_key_alias": "my-key-alias", "user_api_key_org_id": "org-123"},
+        }
+        result = {"choices": [{"finish_reason": "stop", "message": {"content": "hello there"}}]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=result, call_type="acompletion")
+
+        request_payload = mock_post.call_args_list[0].kwargs["json"]
+        response_payload = mock_post.call_args_list[1].kwargs["json"]
+        expected_metadata = {"user_api_key_alias": "my-key-alias", "user_api_key_org_id": "org-123"}
+        assert request_payload["metadata"] == expected_metadata
+        assert response_payload["metadata"] == expected_metadata
+
+    @pytest.mark.asyncio
+    async def test_forwards_a_real_model_response_without_swallowing_it(self, singulr_guardrail):
+        """Regression: a normal completion callback passes a ModelResponse, not a
+        dict. The response payload must carry its actual serialized content instead
+        of silently dropping it because ModelResponse isn't a Mapping."""
+        resp = _make_response({"should_block": False})
+        result = ModelResponse(
+            choices=[{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": "hello there"}}]
+        )
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.async_logging_hook(kwargs={}, result=result, call_type="acompletion")
+
+        response_payload = mock_post.call_args.kwargs["json"]
+        assert response_payload["guardrail_scope"] == "response"
+        assert response_payload["response"]["choices"][0]["message"]["content"] == "hello there"
+
+    @pytest.mark.asyncio
+    async def test_non_serializable_result_falls_back_to_string_report(self, singulr_guardrail):
+        """A result that pydantic can't serialize to JSON must still get reported,
+        as a stringified fallback, instead of raising out of the logging_only hook."""
+        resp = _make_response({"should_block": False})
+
+        class Unserializable:
+            def __repr__(self) -> str:
+                return "<Unserializable>"
+
+        kwargs = {"litellm_metadata": {"user_api_key_alias": "my-key-alias"}}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=Unserializable(), call_type="acompletion")
+
+        response_payload = mock_post.call_args.kwargs["json"]
+        assert response_payload["response"] == "<Unserializable>"
+        assert response_payload["metadata"] == {"user_api_key_alias": "my-key-alias"}
+
+    @pytest.mark.asyncio
+    async def test_no_messages_and_no_result_skips_both_api_calls(self, singulr_guardrail):
+        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
+            returned_kwargs, returned_result = await singulr_guardrail.async_logging_hook(
+                kwargs={}, result=None, call_type="acompletion"
+            )
+        mock_post.assert_not_called()
+        assert returned_result is None
+        guardrail_information = returned_kwargs["standard_logging_object"]["guardrail_information"]
+        assert guardrail_information[0]["guardrail_status"] == "success"
+
+    @pytest.mark.asyncio
+    async def test_mcp_tool_call_is_not_reported(self, singulr_guardrail):
+        """MCP traffic is already covered by the pre/post_mcp_call hooks, which send
+        the richer mcp_request/mcp_response payloads. The logging_only hook sees the
+        same call again with model="MCP: <tool_name>" and must skip it so Singulr
+        doesn't get a duplicate, lower-fidelity report of every tool call."""
+        kwargs = {"model": "MCP: get_weather", "messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
+            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result={"choices": []}, call_type="acompletion"
+            )
+        mock_post.assert_not_called()
+        assert "standard_logging_object" not in updated_kwargs
+        assert result == {"choices": []}
+
+    @pytest.mark.asyncio
+    async def test_mcp_list_tools_call_is_not_reported(self, singulr_guardrail):
+        kwargs = {"model": "MCP: list_tools", "messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
+            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
+        mock_post.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_non_mcp_model_is_still_reported(self, singulr_guardrail):
+        """Guard against the skip being too broad: a normal LLM call whose model
+        merely mentions MCP later in the name must still be reported."""
+        resp = _make_response({"should_block": False})
+        kwargs = {"model": "gpt-4o-mcp", "messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=None, call_type="acompletion"
+            )
+        mock_post.assert_called_once()
+        assert updated_kwargs["standard_logging_object"]["guardrail_information"][0]["guardrail_status"] == "success"
+
+    @pytest.mark.asyncio
+    async def test_records_standard_logging_guardrail_information(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=None, call_type="acompletion"
+            )
+        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert len(guardrail_information) == 1
+        assert guardrail_information[0]["guardrail_name"] == "test-singulr"
+        assert guardrail_information[0]["guardrail_status"] == "success"
+
+    @pytest.mark.asyncio
+    async def test_request_block_verdict_marks_guardrail_status_intervened(self, singulr_guardrail):
+        """Regression: a successful HTTP call whose body says should_block is a
+        real intervention. logging_only can't fail the request, so the verdict
+        only ever surfaces through guardrail_status, and it used to be recorded
+        as a plain success."""
+        resp = _make_response({"should_block": True, "blocking_due_to": "pii"})
+        kwargs = {"messages": [{"role": "user", "content": "my ssn is 123-45-6789"}]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=None, call_type="acompletion"
+            )
+        assert result is None
+        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert guardrail_information[0]["guardrail_status"] == "guardrail_intervened"
+
+    @pytest.mark.asyncio
+    async def test_response_block_verdict_marks_guardrail_status_intervened(self, singulr_guardrail):
+        """Only the response leg blocks here, so a request verdict of False must
+        not mask it."""
+        responses = [_make_response({"should_block": False}), _make_response({"should_block": True})]
+        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(singulr_guardrail.async_handler, "post", side_effect=responses):
+            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result={"choices": []}, call_type="acompletion"
+            )
+        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert guardrail_information[0]["guardrail_status"] == "guardrail_intervened"
+
+    @pytest.mark.asyncio
+    async def test_block_verdict_still_reports_both_legs_and_returns_result(self, singulr_guardrail):
+        """A block verdict on the request leg is logging-only: it must not
+        short-circuit the response report or alter what the hook returns."""
+        resp = _make_response({"should_block": True})
+        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+        result = {"choices": [{"finish_reason": "stop", "message": {"content": "hello"}}]}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            returned_kwargs, returned_result = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=result, call_type="acompletion"
+            )
+        assert [call.kwargs["json"]["guardrail_scope"] for call in mock_post.call_args_list] == ["request", "response"]
+        assert returned_result is result
+        assert returned_kwargs is kwargs
+
+    @pytest.mark.asyncio
+    async def test_api_error_marks_guardrail_status_intervened(self, singulr_guardrail):
+        """With block_on_error=True (the default), a transport failure while
+        reporting to Singulr raises internally; async_logging_hook must catch
+        it, mark the status accordingly, and still return (kwargs, result)
+        instead of propagating -- logging_only must never block the call."""
+        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(
+            singulr_guardrail.async_handler,
+            "post",
+            side_effect=httpx.TransportError("connection refused"),
+        ):
+            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=None, call_type="acompletion"
+            )
+        assert result is None
+        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert guardrail_information[0]["guardrail_status"] == "guardrail_intervened"
+
+    @pytest.mark.asyncio
+    async def test_unexpected_exception_is_swallowed_without_recording_guardrail_information(self, singulr_guardrail):
+        """A non-guardrail exception (e.g. a bug in a downstream integration)
+        must not propagate out of the logging_only hook, and must not record
+        standard_logging_guardrail_information since no verdict was reached."""
+        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+        with patch.object(singulr_guardrail.async_handler, "post", side_effect=RuntimeError("boom")):
+            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=None, call_type="acompletion"
+            )
+        assert result is None
+        assert "standard_logging_object" not in updated_kwargs
+
+    @pytest.mark.asyncio
+    async def test_appends_to_existing_guardrail_information_list(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        existing_entry = {"guardrail_name": "other-guardrail"}
+        kwargs = {
+            "messages": [{"role": "user", "content": "hi"}],
+            "standard_logging_object": {"guardrail_information": [existing_entry]},
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
+                kwargs=kwargs, result=None, call_type="acompletion"
+            )
+        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert guardrail_information[0] is existing_entry
+        assert guardrail_information[1]["guardrail_name"] == "test-singulr"
+
+    def test_sync_logging_hook_returns_kwargs_and_result_unchanged_when_loop_running(self, singulr_guardrail):
+        """logging_hook is the sync entrypoint used outside an event loop;
+        inside a running loop it must no-op rather than deadlock or raise."""
+        import asyncio
+
+        async def _drive():
+            kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+            return singulr_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
+
+        returned_kwargs, returned_result = asyncio.run(_drive())
+        assert returned_result is None
+        assert returned_kwargs == {"messages": [{"role": "user", "content": "hi"}]}
+
+    def test_sync_logging_hook_creates_a_new_event_loop_when_none_is_set(self, singulr_guardrail):
+        """A thread with no current event loop must get a fresh one instead
+        of raising RuntimeError out of the sync entrypoint."""
+        from concurrent.futures import ThreadPoolExecutor
+
+        resp = _make_response({"should_block": False})
+
+        def _run():
+            kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+            with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+                return singulr_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
+
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            returned_kwargs, returned_result = pool.submit(_run).result()
+        assert returned_result is None
+        guardrail_information = returned_kwargs["standard_logging_object"]["guardrail_information"]
+        assert guardrail_information[0]["guardrail_status"] == "success"
+
+    def test_sync_logging_hook_swallows_unexpected_exception(self, singulr_guardrail):
+        """A bug surfacing from async_logging_hook itself, not just the
+        Singulr API call, must not propagate out of the sync entrypoint."""
+        from concurrent.futures import ThreadPoolExecutor
+
+        def _run():
+            kwargs = {"messages": [{"role": "user", "content": "hi"}]}
+            with patch.object(singulr_guardrail, "async_logging_hook", side_effect=RuntimeError("boom")):
+                return singulr_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
+
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            returned_kwargs, returned_result = pool.submit(_run).result()
+        assert returned_result is None
+        assert returned_kwargs == {"messages": [{"role": "user", "content": "hi"}]}
+
+
 # ---------------------------------------------------------------------------
 # HTTP call wiring (endpoint, timeout, headers)
 # ---------------------------------------------------------------------------
@@ -263,7 +1129,7 @@ class TestSingulrBlockAction:
 
 class TestSingulrRequestWiring:
     @pytest.mark.asyncio
-    async def test_sends_configured_timeout(self):
+    async def test_sends_configured_timeout_and_calls_the_guard_endpoint(self):
         """litellm_params.timeout must reach the httpx call so operators can
         tighten or loosen the latency budget instead of being stuck with a
         hardcoded 30s regardless of configuration."""
@@ -279,7 +1145,9 @@ class TestSingulrRequestWiring:
                 request_data={},
                 input_type="request",
             )
-            assert mock_post.call_args.kwargs["timeout"] == 5.0
+        call_kwargs = mock_post.call_args.kwargs
+        assert call_kwargs["timeout"] == 5.0
+        assert call_kwargs["url"] == "https://api.test.singulr.ai/api/v1/ai-gateway/litellm-v2"
 
 
 class TestSingulrBuildHeaders:
@@ -350,17 +1218,19 @@ class TestSingulrInvalidResponse:
     @pytest.mark.asyncio
     async def test_response_missing_expected_fields_block_on_error_true_raises(self):
         """Regression: a response body that fails SingulrGuardrailResponse
-        validation (e.g. should_block is a string, not a bool) must raise
-        GuardrailRaisedException instead of letting pydantic.ValidationError
-        propagate unhandled."""
+        validation must raise GuardrailRaisedException instead of letting
+        pydantic.ValidationError propagate unhandled."""
         guardrail = SingulrGuardrail(
             singulr_api_base="https://api.test.singulr.ai",
             singulr_api_key="test_token_1234",
             guardrail_name="test-singulr",
             block_on_error=True,
         )
-        resp = _make_response({"should_block": "not-a-bool"})
-        with patch.object(guardrail.async_handler, "post", return_value=resp):
+        mock_resp = MagicMock()
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.side_effect = ValueError("not valid json")
+
+        with patch.object(guardrail.async_handler, "post", return_value=mock_resp):
             with pytest.raises(GuardrailRaisedException):
                 await guardrail.apply_guardrail(
                     inputs={"texts": ["test"]},
@@ -481,6 +1351,9 @@ class TestSingulrConfigModel:
     def test_ui_friendly_name(self):
         assert SingulrGuardrailConfigModel.ui_friendly_name() == "Singulr"
 
+    def test_get_config_model_returns_singulr_config_model(self):
+        assert SingulrGuardrail.get_config_model() is SingulrGuardrailConfigModel
+
 
 # ---------------------------------------------------------------------------
 # Initializer and registry

From 146085669c1f3a70e413aeb4cffb1d522706e47b Mon Sep 17 00:00:00 2001
From: Yucheng He <yucheng@berri.ai>
Date: Tue, 15 Sep 2026 19:14:49 -0700
Subject: [PATCH 48/67] fix(guardrails): run Singulr logging_only through the
 base hook, key MCP scans off the proxy call type and type the payloads

Removes the Singulr async_logging_hook and logging_hook overrides so logging_only runs through CustomGuardrail.async_logging_hook: the response scope reaches Singulr as an assistant message instead of a raw ModelResponse dump, a vendor timeout is recorded as guardrail_failed_to_respond, a request-scope block ends the scan, and the sync success callback thread makes no Singulr call.

Decides MCP versus LLM by the proxy logging object's call_type (then the call_type or server-only markers in request_data), never by name, arguments or mcp_tool_name keys a client can put in a chat body. REST /mcp-rest/tools/call pre-scans reach Singulr as mcp_request and a non-mapping arguments value is forwarded as tool_arguments instead of raising.

should_block is a strict bool defaulting to false so a null verdict is an invalid response that block_on_error decides; payload fields drop Any for Sequence, Mapping and AssistantMessage types; metadata carries only the keys present; docstrings and section comments removed per the repo comment policy.
---
 .../guardrail_hooks/singulr/singulr.py        | 171 +-----
 .../guardrails/guardrail_hooks/singulr.py     |  16 +-
 .../guardrail_hooks/test_singulr.py           | 577 +++++++-----------
 3 files changed, 256 insertions(+), 508 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py b/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py
index e0dcdf02069..a91812bb474 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/singulr/singulr.py
@@ -1,8 +1,6 @@
-import asyncio
 import json
 import os
 from collections.abc import Mapping, Sequence
-from datetime import datetime, timezone
 from types import MappingProxyType
 from typing import Any, Final
 from urllib.parse import urlparse
@@ -37,11 +35,7 @@ from litellm.types.proxy.guardrails.guardrail_hooks.singulr import (
     ToolCall,
     ToolCallFunction,
 )
-from litellm.types.utils import (
-    GenericGuardrailAPIInputs,
-    GuardrailStatus,
-    StandardLoggingGuardrailInformation,
-)
+from litellm.types.utils import CallTypes, GenericGuardrailAPIInputs
 
 _DEFAULT_API_BASE: Final = "http://localhost:8003"
 _GUARD_ENDPOINT: Final = "/api/v1/ai-gateway/litellm-v2"
@@ -117,13 +111,6 @@ class SingulrGuardrail(CustomGuardrail):
 
     @staticmethod
     def _metadata_containers(request_data: Mapping[str, Any]) -> tuple[Mapping[str, Any], ...]:
-        """Candidate metadata dicts to check, in priority order.
-
-        Most call paths put metadata at the top level of ``request_data``
-        (``litellm_metadata`` or ``metadata``). ``post_mcp_call`` instead hands
-        us ``litellm_logging_obj.model_call_details``, which nests it under
-        ``litellm_params`` instead, so that's checked as a fallback.
-        """
         litellm_params: Final = request_data.get("litellm_params") or _EMPTY_MAPPING
         return tuple(
             container
@@ -153,7 +140,7 @@ class SingulrGuardrail(CustomGuardrail):
         return None
 
     @classmethod
-    def _build_metadata(cls, request_data: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    def _build_metadata(cls, request_data: Mapping[str, Any]) -> Mapping[str, str] | None:
         fields: Final = (
             "user_api_key_alias",
             "user_api_key_user_id",
@@ -279,13 +266,30 @@ class SingulrGuardrail(CustomGuardrail):
             )
         return inputs
 
+    @staticmethod
+    def _mcp_tool_name(request_data: Mapping[str, Any]) -> str | None:
+        return request_data.get("mcp_tool_name") or request_data.get("name")
+
+    @staticmethod
+    def _mcp_arguments(request_data: Mapping[str, Any]) -> object:
+        arguments: Final = request_data.get("mcp_arguments")
+        return arguments if arguments is not None else request_data.get("arguments")
+
+    @staticmethod
+    def _is_mcp_call(request_data: Mapping[str, Any], logging_obj: LiteLLMLoggingObj | None) -> bool:
+        call_type: Final = logging_obj.call_type if logging_obj is not None else request_data.get("call_type")
+        if call_type is not None:
+            return call_type == CallTypes.call_mcp_tool.value
+        model: Final = request_data.get("model")
+        return "mcp_tool_name" in request_data or (isinstance(model, str) and model.startswith(_MCP_MODEL_PREFIX))
+
     async def _apply_guardrail_on_mcp_request(self, request_data: Mapping[str, Any]) -> None:
         metadata: Final = self._build_metadata(request_data=request_data)
 
         singulr_mcp_obj = SingulrMcpGuardrailPayload(
             guardrail_scope="mcp_request",
-            tool_name=request_data.get("mcp_tool_name"),
-            tool_arguments=request_data.get("mcp_arguments"),
+            tool_name=self._mcp_tool_name(request_data),
+            tool_arguments=self._mcp_arguments(request_data),
             mcp_server_name=request_data.get("mcp_server_name"),
             metadata=metadata,
         )
@@ -398,134 +402,6 @@ class SingulrGuardrail(CustomGuardrail):
             )
         return inputs
 
-    def _logging_only_response_payload(
-        self,
-        kwargs: Mapping[str, Any],
-        result: Any,  # noqa: ANN401  # result can be any callback shape
-    ) -> Mapping[str, Any]:
-        metadata: Final = self._build_metadata(request_data=kwargs)
-        try:
-            return SingulrGuardrailPayload(
-                correlation_id=kwargs.get("litellm_call_id"),
-                model_name=kwargs.get("model"),
-                guardrail_scope="response",
-                response=result,
-                metadata=metadata,
-            ).model_dump(mode="json")
-        except Exception as exc:  # noqa: BLE001  # result can be any callback shape; fall back to a stringified report
-            verbose_proxy_logger.debug("Singulr: could not JSON-serialize response, falling back: %s", exc)
-            return {  # mutable-ok: short-lived JSON payload dict
-                "correlation_id": kwargs.get("litellm_call_id"),
-                "guardrail_scope": "response",
-                "response": str(result),
-                "metadata": metadata,
-            }
-
-    async def _report_logging_only(
-        self,
-        kwargs: Mapping[str, Any],
-        result: Any,  # noqa: ANN401  # result can be any callback shape
-    ) -> tuple[SingulrGuardrailResponse | None, ...]:
-        messages: Final = kwargs.get("messages") or ()
-        request_verdict: Final = (
-            await self._call_api(
-                SingulrGuardrailPayload(
-                    correlation_id=kwargs.get("litellm_call_id"),
-                    model_name=kwargs.get("model"),
-                    guardrail_scope="request",
-                    messages=messages,
-                    metadata=self._build_metadata(request_data=kwargs),
-                ).model_dump(mode="json")
-            )
-            if messages
-            else None
-        )
-        response_verdict: Final = (
-            await self._call_api(self._logging_only_response_payload(kwargs=kwargs, result=result)) if result else None
-        )
-        return (request_verdict, response_verdict)
-
-    async def _logging_only_guardrail_status(
-        self,
-        kwargs: Mapping[str, Any],
-        result: Any,  # noqa: ANN401  # result can be any callback shape
-    ) -> GuardrailStatus | None:
-        """``None`` means no verdict was reached, so nothing should be logged."""
-        try:
-            verdicts: Final = await self._report_logging_only(kwargs=kwargs, result=result)
-        except GuardrailRaisedException:
-            return "guardrail_intervened"
-        except Exception as exc:  # noqa: BLE001  # logging_only must never break the request
-            verbose_proxy_logger.debug("Singulr: logging_only hook swallowed exception: %s", exc)
-            return None
-        if any(verdict is not None and verdict.should_block for verdict in verdicts):
-            return "guardrail_intervened"
-        return "success"
-
-    @staticmethod
-    def _is_mcp_call(kwargs: Mapping[str, Any]) -> bool:
-        model: Final = kwargs.get("model")
-        return isinstance(model, str) and model.startswith(_MCP_MODEL_PREFIX)
-
-    async def async_logging_hook(
-        self,
-        kwargs: dict,  # mutable-ok: matches CustomLogger override; mutated via setdefault
-        result: Any,  # noqa: ANN401  # required by CustomLogger.async_logging_hook override signature
-        call_type: str,
-    ) -> tuple[dict, Any]:
-        if self._is_mcp_call(kwargs):
-            verbose_proxy_logger.debug("Singulr: skipping logging_only report for MCP call %s", kwargs.get("model"))
-            return kwargs, result
-
-        start_time: Final = datetime.now(timezone.utc)
-        guardrail_status: Final = await self._logging_only_guardrail_status(kwargs=kwargs, result=result)
-        if guardrail_status is None:
-            return kwargs, result
-
-        end_time: Final = datetime.now(timezone.utc)
-        slg: Final = StandardLoggingGuardrailInformation(
-            guardrail_name=self.guardrail_name or "singulr",
-            guardrail_mode=GuardrailEventHooks.logging_only,
-            guardrail_status=guardrail_status,
-            start_time=start_time.timestamp(),
-            end_time=end_time.timestamp(),
-            duration=(end_time - start_time).total_seconds(),
-            masked_entity_count=None,
-        )
-        standard_logging_object: Final = kwargs.setdefault(
-            "standard_logging_object",
-            {},  # mutable-ok: shared, mutated accumulator
-        )
-        existing = standard_logging_object.get("guardrail_information")
-        if isinstance(existing, list):
-            existing.append(slg)
-        else:
-            standard_logging_object["guardrail_information"] = [slg]  # mutable-ok: shared accumulator
-
-        return kwargs, result
-
-    def logging_hook(
-        self,
-        kwargs: dict,  # mutable-ok: required by CustomLogger.logging_hook override signature
-        result: Any,  # noqa: ANN401  # required by CustomLogger.logging_hook override signature
-        call_type: str,
-    ) -> tuple[dict, Any]:
-        try:
-            try:
-                loop = asyncio.get_event_loop()
-            except RuntimeError:
-                loop = asyncio.new_event_loop()
-                asyncio.set_event_loop(loop)
-            if loop.is_running():
-                verbose_proxy_logger.debug(
-                    "Singulr: sync logging_hook called from a running loop; skipping logging_only report"
-                )
-                return kwargs, result
-            loop.run_until_complete(self.async_logging_hook(kwargs=kwargs, result=result, call_type=call_type))
-        except Exception as exc:  # noqa: BLE001  # logging_only must never break the request
-            verbose_proxy_logger.debug("Singulr: sync logging_hook swallowed exception: %s", exc)
-        return kwargs, result
-
     @log_guardrail_information
     async def apply_guardrail(
         self,
@@ -544,15 +420,16 @@ class SingulrGuardrail(CustomGuardrail):
             len(structured_messages),
         )
 
+        is_mcp_call: Final = self._is_mcp_call(request_data, logging_obj)
         if input_type == "request":
-            if request_data.get("mcp_tool_name"):
+            if is_mcp_call:
                 await self._apply_guardrail_on_mcp_request(request_data=request_data)
                 return inputs
             return await self._apply_guardrail_on_request(
                 inputs=inputs, texts=texts, structured_messages=structured_messages, request_data=request_data
             )
         elif input_type == "response":
-            if request_data.get("call_type") == "call_mcp_tool":
+            if is_mcp_call:
                 return await self._apply_guardrail_on_mcp_response(
                     inputs=inputs, texts=texts, request_data=request_data
                 )
diff --git a/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py b/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py
index fd349b44e0c..ea1e6238181 100644
--- a/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py
+++ b/litellm/types/proxy/guardrails/guardrail_hooks/singulr.py
@@ -1,5 +1,5 @@
 from collections.abc import Mapping, Sequence
-from typing import Any, Literal
+from typing import Literal
 
 from pydantic import BaseModel, Field
 
@@ -33,27 +33,27 @@ class SingulrGuardrailPayload(BaseModel):
     model_name: str | None = None
     model_provider_name: str | None = None
     guardrail_scope: str | None = None
-    messages: Sequence[Any] | None = None
+    messages: Sequence[Mapping[str, object]] | None = None
     images: Sequence[str] | None = None
-    tools: Sequence[Any] | None = None  # pyright: ignore[reportExplicitAny]  # forwards caller-supplied OpenAI tool defs verbatim
-    response: Any = None  # pyright: ignore[reportExplicitAny]  # logging_only reports raw litellm callback results (ModelResponse, EmbeddingResponse, etc.)
-    metadata: Mapping[str, Any] | None = None
+    tools: Sequence[Mapping[str, object]] | None = None
+    response: AssistantMessage | None = None
+    metadata: Mapping[str, str] | None = None
 
 
 class SingulrMcpGuardrailPayload(BaseModel):
     model_name: str | None = None
     guardrail_scope: str | None = None
     tool_name: str | None = None
-    tool_arguments: Mapping[str, Any] | None = None
+    tool_arguments: object = None
     mcp_server_name: str | None = None
     tool_result: Sequence[str] | None = None
-    metadata: Mapping[str, Any] | None = None
+    metadata: Mapping[str, str] | None = None
 
 
 class SingulrGuardrailResponse(BaseModel):
     """Response returned by the Singulr guardrail API."""
 
-    should_block: bool | None = None
+    should_block: bool = False
     blocking_due_to: str | None = None
 
 
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py
index 7a228a7c3fb..b775d399b86 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_singulr.py
@@ -4,6 +4,7 @@ from unittest.mock import MagicMock, patch
 import httpx
 import pytest
 
+import litellm
 from litellm.exceptions import GuardrailRaisedException
 from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth
 from litellm.proxy.guardrails.guardrail_hooks.singulr.singulr import SingulrGuardrail
@@ -14,12 +15,8 @@ from litellm.types.proxy.guardrails.guardrail_hooks.singulr import (
 from litellm.types.utils import ModelResponse
 
 
-# ---------------------------------------------------------------------------
-# Fixtures
-# ---------------------------------------------------------------------------
 @pytest.fixture
 def singulr_guardrail():
-    """Create a SingulrGuardrail instance with test credentials."""
     return SingulrGuardrail(
         singulr_api_base="https://api.test.singulr.ai",
         singulr_api_key="test_token_1234",
@@ -31,8 +28,26 @@ def singulr_guardrail():
     )
 
 
+@pytest.fixture
+def logging_only_guardrail():
+    return SingulrGuardrail(
+        singulr_api_base="https://api.test.singulr.ai",
+        singulr_api_key="test_token_1234",
+        singulr_guardrail_id="test_guardrail_id",
+        singulr_application_id="test_enforcement_entity",
+        guardrail_name="test-singulr",
+        event_hook="logging_only",
+        default_on=True,
+    )
+
+
+def _logging_obj(call_type: str) -> MagicMock:
+    logging_obj = MagicMock()
+    logging_obj.call_type = call_type
+    return logging_obj
+
+
 def _make_response(body: dict) -> MagicMock:
-    """Build a mock httpx response with the given JSON body."""
     mock = MagicMock()
     mock.json.return_value = body
     mock.raise_for_status = MagicMock()
@@ -40,11 +55,6 @@ def _make_response(body: dict) -> MagicMock:
     return mock
 
 
-# ---------------------------------------------------------------------------
-# Configuration
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrConfiguration:
     def test_init_with_explicit_credentials(self):
         guardrail = SingulrGuardrail(
@@ -59,10 +69,6 @@ class TestSingulrConfiguration:
         assert guardrail.singulr_application_id == "entity123"
 
     def test_api_base_strips_surrounding_whitespace(self):
-        """Regression: a UI-saved api_base with a trailing space
-        (e.g. "https://custom.api.local ") broke urlparse's port parsing and
-        made every guardrail call fail with a connection error, even though
-        the configured host was reachable."""
         guardrail = SingulrGuardrail(
             singulr_api_key="test_key",
             singulr_api_base=" https://custom.api.local ",
@@ -74,8 +80,6 @@ class TestSingulrConfiguration:
         assert guardrail.singulr_api_base == "https://custom.api.local"
 
     def test_non_local_http_api_base_raises(self):
-        """Guardrail payloads carry the API token and full conversation
-        content, so a non-local endpoint must use HTTPS."""
         with pytest.raises(ValueError, match="HTTPS"):
             SingulrGuardrail(singulr_api_key="test_key", singulr_api_base="http://guardrails.singulr.ai")
 
@@ -106,11 +110,6 @@ class TestSingulrConfiguration:
         ]
 
 
-# ---------------------------------------------------------------------------
-# Payload construction for real proxy requests (request_data present)
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrRequestPayload:
     @pytest.mark.asyncio
     async def test_model_and_messages_are_forwarded(self, singulr_guardrail):
@@ -130,9 +129,6 @@ class TestSingulrRequestPayload:
 
     @pytest.mark.asyncio
     async def test_structured_messages_are_forwarded_verbatim(self, singulr_guardrail):
-        """When structured_messages are provided (e.g. system + user turns),
-        they must be sent as-is instead of being flattened into single
-        user-role messages built from texts."""
         resp = _make_response({"should_block": False})
         structured_messages = [
             {"role": "system", "content": "Be concise."},
@@ -180,8 +176,6 @@ class TestSingulrRequestPayload:
         ids=["tools_alone", "images_alone"],
     )
     async def test_tools_or_images_alone_still_trigger_the_api_call(self, singulr_guardrail, extra_inputs):
-        """Regression: a request with only tool definitions or only images and
-        no text must still be checked, not skipped for lack of a message."""
         resp = _make_response({"should_block": False})
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
             await singulr_guardrail.apply_guardrail(
@@ -195,9 +189,6 @@ class TestSingulrRequestPayload:
 
     @pytest.mark.asyncio
     async def test_tools_are_forwarded(self, singulr_guardrail):
-        """Regression: tool/function definitions are client-controlled and can
-        carry prompt-injection content, so they must reach Singulr for
-        inspection instead of only messages and images."""
         resp = _make_response({"should_block": False})
         tools = [
             {
@@ -216,10 +207,6 @@ class TestSingulrRequestPayload:
 
     @pytest.mark.asyncio
     async def test_responses_api_mcp_tools_are_forwarded(self, singulr_guardrail):
-        """Regression: Responses API tools (e.g. {"type": "mcp", "server_label": ...})
-        have no "function" key, unlike Chat Completions tools. SingulrGuardrailPayload
-        rejected them with a pydantic ValidationError, turning every Responses API
-        request carrying an MCP tool into a 500."""
         resp = _make_response({"should_block": False})
         tools = [
             {
@@ -240,8 +227,6 @@ class TestSingulrRequestPayload:
 
     @pytest.mark.asyncio
     async def test_user_api_key_alias_is_forwarded_in_metadata(self, singulr_guardrail):
-        """Regression: the alias must be sent as {"user_api_key_alias": <alias>},
-        not as a dict whose key is the alias value itself."""
         resp = _make_response({"should_block": False})
         request_data = {"litellm_metadata": {"user_api_key_alias": "my-key-alias"}}
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
@@ -420,8 +405,6 @@ class TestSingulrRequestPayload:
 
     @pytest.mark.asyncio
     async def test_no_key_alias_available_sends_no_metadata(self, singulr_guardrail):
-        """Regression: with no alias found, metadata must be omitted (None),
-        not a {None: None} dict that fails payload validation."""
         resp = _make_response({"should_block": False})
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
             await singulr_guardrail.apply_guardrail(
@@ -433,11 +416,6 @@ class TestSingulrRequestPayload:
         assert sent_payload["metadata"] is None
 
 
-# ---------------------------------------------------------------------------
-# Payload construction for responses
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrResponsePayload:
     @pytest.mark.asyncio
     async def test_assistant_text_and_tool_calls_are_forwarded(self, singulr_guardrail):
@@ -506,9 +484,6 @@ class TestSingulrResponsePayload:
     async def test_tool_call_type_other_than_function_is_still_scanned(
         self, singulr_guardrail, raw_type, expected_type
     ):
-        """Regression: a tool call whose type is absent or isn't "function" used
-        to raise a pydantic ValidationError while building the payload, which
-        escaped apply_guardrail as a 500 instead of reaching the scan at all."""
         resp = _make_response({"should_block": False})
         tool_call = {"id": "call_1", "function": {"name": "get_current_time", "arguments": "{}"}}
         inputs = {
@@ -523,8 +498,6 @@ class TestSingulrResponsePayload:
 
     @pytest.mark.asyncio
     async def test_non_string_tool_call_arguments_are_serialized(self, singulr_guardrail):
-        """Some providers hand back already-parsed arguments; they must be
-        scanned as JSON text rather than crashing the payload build."""
         resp = _make_response({"should_block": False})
         inputs = {
             "texts": [],
@@ -539,7 +512,6 @@ class TestSingulrResponsePayload:
 
     @pytest.mark.asyncio
     async def test_block_verdict_still_raises_for_a_non_function_tool_call(self, singulr_guardrail):
-        """The point of scanning these calls: the verdict must still be enforced."""
         resp = _make_response({"should_block": True, "blocking_due_to": "dangerous_tool"})
         inputs = {
             "texts": [],
@@ -551,11 +523,6 @@ class TestSingulrResponsePayload:
         assert "dangerous_tool" in str(exc_info.value)
 
 
-# ---------------------------------------------------------------------------
-# Allow / block decisions
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrAllowAction:
     @pytest.mark.asyncio
     @pytest.mark.parametrize(
@@ -564,8 +531,6 @@ class TestSingulrAllowAction:
         ids=["should_block_false", "should_block_omitted"],
     )
     async def test_should_block_falsy_returns_inputs_unchanged_on_request(self, singulr_guardrail, guard_response):
-        """should_block is optional on the wire; a response that omits it
-        entirely must be treated as allow, not block."""
         resp = _make_response(guard_response)
         inputs = {"texts": ["How do I reset my password?"]}
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
@@ -605,6 +570,34 @@ class TestSingulrAllowAction:
             )
             assert result is inputs
 
+    @pytest.mark.asyncio
+    async def test_explicit_null_verdict_fails_closed_by_default(self, singulr_guardrail):
+        resp = _make_response({"should_block": None})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
+            with pytest.raises(GuardrailRaisedException, match="invalid response"):
+                await singulr_guardrail.apply_guardrail(
+                    inputs={"texts": ["hi"]},
+                    request_data={"model": "gpt-4o"},
+                    input_type="request",
+                )
+
+    @pytest.mark.asyncio
+    async def test_explicit_null_verdict_fails_open_when_block_on_error_false(self):
+        guardrail = SingulrGuardrail(
+            singulr_api_base="https://api.test.singulr.ai",
+            singulr_api_key="test_token_1234",
+            guardrail_name="test-singulr",
+            block_on_error=False,
+        )
+        resp = _make_response({"should_block": None})
+        inputs = {"texts": ["hi"]}
+        with patch.object(guardrail.async_handler, "post", return_value=resp):
+            assert await guardrail._call_api({"guardrail_scope": "request"}) is None
+            result = await guardrail.apply_guardrail(
+                inputs=inputs, request_data={"model": "gpt-4o"}, input_type="request"
+            )
+        assert result is inputs
+
 
 class TestSingulrBlockAction:
     @pytest.mark.asyncio
@@ -622,11 +615,6 @@ class TestSingulrBlockAction:
 
     @pytest.mark.asyncio
     async def test_should_block_true_raises_on_response(self, singulr_guardrail):
-        """Regression: apply_guardrail's response path compared
-        should_block (a bool) against the string "block", which is always
-        False, so a should_block=True response never blocked the assistant's
-        reply. It must raise on any truthy should_block, matching the
-        request path."""
         resp = _make_response({"should_block": True, "blocking_due_to": "Toxic content detected"})
         with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
             with pytest.raises(GuardrailRaisedException) as exc_info:
@@ -650,11 +638,6 @@ class TestSingulrBlockAction:
                 )
 
 
-# ---------------------------------------------------------------------------
-# MCP tool call guardrail (pre_mcp_call / post_mcp_call)
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrMcpRequest:
     @pytest.mark.asyncio
     async def test_mcp_tool_name_routes_to_mcp_request_payload(self, singulr_guardrail):
@@ -707,6 +690,97 @@ class TestSingulrMcpRequest:
             )
         assert result == {"texts": []}
 
+    @pytest.mark.asyncio
+    async def test_mcp_rest_body_shape_routes_to_mcp_request_payload(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"name": "echo", "arguments": {"text": "my ssn is 123-45-6789"}, "server_id": "srv-1"}
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["my ssn is 123-45-6789"], "tools": [{"type": "function"}]},
+                request_data=request_data,
+                input_type="request",
+                logging_obj=_logging_obj("call_mcp_tool"),
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "mcp_request"
+        assert sent_payload["tool_name"] == "echo"
+        assert sent_payload["tool_arguments"] == {"text": "my ssn is 123-45-6789"}
+        assert "messages" not in sent_payload
+
+    @pytest.mark.asyncio
+    async def test_mcp_rest_body_without_arguments_still_routes_to_mcp_request(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": [], "tools": [{"type": "function"}]},
+                request_data={"name": "echo", "server_id": "srv-1"},
+                input_type="request",
+                logging_obj=_logging_obj("call_mcp_tool"),
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "mcp_request"
+        assert sent_payload["tool_name"] == "echo"
+        assert sent_payload["tool_arguments"] is None
+
+    @pytest.mark.asyncio
+    async def test_non_mapping_tool_arguments_are_forwarded_verbatim(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["raw text"], "tools": [{"type": "function"}]},
+                request_data={"name": "echo", "arguments": "raw text", "server_id": "srv-1"},
+                input_type="request",
+                logging_obj=_logging_obj("call_mcp_tool"),
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "mcp_request"
+        assert sent_payload["tool_arguments"] == "raw text"
+
+    @pytest.mark.asyncio
+    async def test_llm_request_body_keys_cannot_reroute_the_scan_to_mcp(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {
+            "model": "gpt-4o",
+            "messages": [{"role": "user", "content": "my ssn is 123-45-6789"}],
+            "name": "x",
+            "arguments": {},
+            "mcp_tool_name": "x",
+            "call_type": "call_mcp_tool",
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={
+                    "texts": ["my ssn is 123-45-6789"],
+                    "structured_messages": [{"role": "user", "content": "my ssn is 123-45-6789"}],
+                },
+                request_data=request_data,
+                input_type="request",
+                logging_obj=_logging_obj("acompletion"),
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "request"
+        assert [m["content"] for m in sent_payload["messages"]] == ["my ssn is 123-45-6789"]
+
+    @pytest.mark.asyncio
+    async def test_llm_response_with_spoofed_mcp_keys_still_scans_the_tool_calls(self, singulr_guardrail):
+        resp = _make_response({"should_block": False})
+        request_data = {"model": "gpt-4o", "messages": [], "name": "x", "arguments": {}, "mcp_tool_name": "x"}
+        tool_call = {
+            "id": "call_1",
+            "type": "function",
+            "function": {"name": "transfer_funds", "arguments": '{"amount": 5000}'},
+        }
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": [], "tool_calls": [tool_call]},
+                request_data=request_data,
+                input_type="response",
+                logging_obj=_logging_obj("acompletion"),
+            )
+        sent_payload = mock_post.call_args.kwargs["json"]
+        assert sent_payload["guardrail_scope"] == "response"
+        assert sent_payload["response"]["tool_calls"][0]["function"]["name"] == "transfer_funds"
+
 
 class TestSingulrMcpResponse:
     @pytest.mark.asyncio
@@ -756,8 +830,6 @@ class TestSingulrMcpResponse:
 
     @pytest.mark.asyncio
     async def test_mcp_response_resolves_metadata_from_nested_litellm_params(self, singulr_guardrail):
-        """post_mcp_call hands apply_guardrail litellm_logging_obj.model_call_details,
-        which nests metadata under litellm_params instead of at the top level."""
         resp = _make_response({"should_block": False})
         auth = UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER_VIEW_ONLY)
         request_data = {
@@ -830,10 +902,26 @@ class TestSingulrMcpResponse:
             )
         assert result is inputs
 
-
-# ---------------------------------------------------------------------------
-# apply_guardrail dispatch (request vs response vs unknown input_type)
-# ---------------------------------------------------------------------------
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        ("request_data", "logging_obj"),
+        [
+            ({"call_type": "call_mcp_tool", "model": "MCP: echo"}, None),
+            ({"model": "MCP: echo"}, None),
+            ({"name": "echo", "arguments": {"text": "hi"}}, _logging_obj("call_mcp_tool")),
+        ],
+        ids=["post_mcp_call_model_call_details", "logging_only_scratch_request", "rest_pre_call_logger"],
+    )
+    async def test_mcp_response_is_detected_from_each_producer(self, singulr_guardrail, request_data, logging_obj):
+        resp = _make_response({"should_block": False})
+        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await singulr_guardrail.apply_guardrail(
+                inputs={"texts": ["tool output"]},
+                request_data=request_data,
+                input_type="response",
+                logging_obj=logging_obj,
+            )
+        assert mock_post.call_args.kwargs["json"]["guardrail_scope"] == "mcp_response"
 
 
 class TestSingulrApplyGuardrailDispatch:
@@ -850,289 +938,109 @@ class TestSingulrApplyGuardrailDispatch:
         assert result is inputs
 
 
-# ---------------------------------------------------------------------------
-# logging_only hook
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrLoggingHook:
-    @pytest.mark.asyncio
-    async def test_forwards_request_messages_and_response_text(self, singulr_guardrail):
-        resp = _make_response({"should_block": False})
-        kwargs = {"messages": [{"role": "user", "content": "hi"}], "model": "gpt-4o", "litellm_call_id": "call-1"}
-        result = {"choices": [{"finish_reason": "stop", "message": {"content": "hello there"}}]}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
-            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=result, call_type="acompletion")
-
-        request_payload = mock_post.call_args_list[0].kwargs["json"]
-        response_payload = mock_post.call_args_list[1].kwargs["json"]
-        assert request_payload["guardrail_scope"] == "request"
-        assert request_payload["messages"] == kwargs["messages"]
-        assert response_payload["guardrail_scope"] == "response"
-        assert response_payload["response"] == result
-
-    @pytest.mark.asyncio
-    async def test_forwards_user_metadata_in_both_request_and_response_payloads(self, singulr_guardrail):
-        resp = _make_response({"should_block": False})
+    @staticmethod
+    def _logged_call(**overrides):
         kwargs = {
-            "messages": [{"role": "user", "content": "hi"}],
             "model": "gpt-4o",
+            "messages": [{"role": "user", "content": "hi"}],
             "litellm_call_id": "call-1",
-            "litellm_metadata": {"user_api_key_alias": "my-key-alias", "user_api_key_org_id": "org-123"},
+            "litellm_params": {"metadata": {"user_api_key_alias": "my-key-alias", "user_api_key_org_id": "org-123"}},
+            "standard_logging_object": {"guardrail_information": []},
         }
-        result = {"choices": [{"finish_reason": "stop", "message": {"content": "hello there"}}]}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
-            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=result, call_type="acompletion")
-
-        request_payload = mock_post.call_args_list[0].kwargs["json"]
-        response_payload = mock_post.call_args_list[1].kwargs["json"]
-        expected_metadata = {"user_api_key_alias": "my-key-alias", "user_api_key_org_id": "org-123"}
-        assert request_payload["metadata"] == expected_metadata
-        assert response_payload["metadata"] == expected_metadata
+        return {**kwargs, **overrides}
 
     @pytest.mark.asyncio
-    async def test_forwards_a_real_model_response_without_swallowing_it(self, singulr_guardrail):
-        """Regression: a normal completion callback passes a ModelResponse, not a
-        dict. The response payload must carry its actual serialized content instead
-        of silently dropping it because ModelResponse isn't a Mapping."""
+    async def test_scans_request_then_response_as_an_assistant_message(self, logging_only_guardrail):
         resp = _make_response({"should_block": False})
         result = ModelResponse(
             choices=[{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": "hello there"}}]
         )
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
-            await singulr_guardrail.async_logging_hook(kwargs={}, result=result, call_type="acompletion")
-
-        response_payload = mock_post.call_args.kwargs["json"]
-        assert response_payload["guardrail_scope"] == "response"
-        assert response_payload["response"]["choices"][0]["message"]["content"] == "hello there"
-
-    @pytest.mark.asyncio
-    async def test_non_serializable_result_falls_back_to_string_report(self, singulr_guardrail):
-        """A result that pydantic can't serialize to JSON must still get reported,
-        as a stringified fallback, instead of raising out of the logging_only hook."""
-        resp = _make_response({"should_block": False})
-
-        class Unserializable:
-            def __repr__(self) -> str:
-                return "<Unserializable>"
-
-        kwargs = {"litellm_metadata": {"user_api_key_alias": "my-key-alias"}}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
-            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=Unserializable(), call_type="acompletion")
-
-        response_payload = mock_post.call_args.kwargs["json"]
-        assert response_payload["response"] == "<Unserializable>"
-        assert response_payload["metadata"] == {"user_api_key_alias": "my-key-alias"}
-
-    @pytest.mark.asyncio
-    async def test_no_messages_and_no_result_skips_both_api_calls(self, singulr_guardrail):
-        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
-            returned_kwargs, returned_result = await singulr_guardrail.async_logging_hook(
-                kwargs={}, result=None, call_type="acompletion"
+        with patch.object(logging_only_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            updated_kwargs, returned = await logging_only_guardrail.async_logging_hook(
+                kwargs=self._logged_call(), result=result, call_type="acompletion"
             )
-        mock_post.assert_not_called()
-        assert returned_result is None
-        guardrail_information = returned_kwargs["standard_logging_object"]["guardrail_information"]
-        assert guardrail_information[0]["guardrail_status"] == "success"
+
+        assert returned is result
+        scopes = [call.kwargs["json"]["guardrail_scope"] for call in mock_post.call_args_list]
+        assert scopes == ["request", "response"]
+        request_payload = mock_post.call_args_list[0].kwargs["json"]
+        response_payload = mock_post.call_args_list[1].kwargs["json"]
+        assert request_payload["messages"] == [{"role": "user", "content": "hi"}]
+        assert request_payload["correlation_id"] == "call-1"
+        assert response_payload["response"] == {"role": "assistant", "content": "hello there", "tool_calls": []}
+        expected_metadata = {"user_api_key_alias": "my-key-alias", "user_api_key_org_id": "org-123"}
+        assert request_payload["metadata"] == expected_metadata
+        assert response_payload["metadata"] == expected_metadata
+        statuses = [
+            entry["guardrail_status"] for entry in updated_kwargs["standard_logging_object"]["guardrail_information"]
+        ]
+        assert statuses == ["success", "success"]
 
     @pytest.mark.asyncio
-    async def test_mcp_tool_call_is_not_reported(self, singulr_guardrail):
-        """MCP traffic is already covered by the pre/post_mcp_call hooks, which send
-        the richer mcp_request/mcp_response payloads. The logging_only hook sees the
-        same call again with model="MCP: <tool_name>" and must skip it so Singulr
-        doesn't get a duplicate, lower-fidelity report of every tool call."""
-        kwargs = {"model": "MCP: get_weather", "messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
-            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result={"choices": []}, call_type="acompletion"
-            )
-        mock_post.assert_not_called()
-        assert "standard_logging_object" not in updated_kwargs
-        assert result == {"choices": []}
-
-    @pytest.mark.asyncio
-    async def test_mcp_list_tools_call_is_not_reported(self, singulr_guardrail):
-        kwargs = {"model": "MCP: list_tools", "messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(singulr_guardrail.async_handler, "post") as mock_post:
-            await singulr_guardrail.async_logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
-        mock_post.assert_not_called()
-
-    @pytest.mark.asyncio
-    async def test_non_mcp_model_is_still_reported(self, singulr_guardrail):
-        """Guard against the skip being too broad: a normal LLM call whose model
-        merely mentions MCP later in the name must still be reported."""
-        resp = _make_response({"should_block": False})
-        kwargs = {"model": "gpt-4o-mcp", "messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
-            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=None, call_type="acompletion"
-            )
-        mock_post.assert_called_once()
-        assert updated_kwargs["standard_logging_object"]["guardrail_information"][0]["guardrail_status"] == "success"
-
-    @pytest.mark.asyncio
-    async def test_records_standard_logging_guardrail_information(self, singulr_guardrail):
-        resp = _make_response({"should_block": False})
-        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
-            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=None, call_type="acompletion"
-            )
-        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
-        assert len(guardrail_information) == 1
-        assert guardrail_information[0]["guardrail_name"] == "test-singulr"
-        assert guardrail_information[0]["guardrail_status"] == "success"
-
-    @pytest.mark.asyncio
-    async def test_request_block_verdict_marks_guardrail_status_intervened(self, singulr_guardrail):
-        """Regression: a successful HTTP call whose body says should_block is a
-        real intervention. logging_only can't fail the request, so the verdict
-        only ever surfaces through guardrail_status, and it used to be recorded
-        as a plain success."""
+    async def test_block_verdict_is_recorded_as_intervened_without_failing_the_call(self, logging_only_guardrail):
         resp = _make_response({"should_block": True, "blocking_due_to": "pii"})
-        kwargs = {"messages": [{"role": "user", "content": "my ssn is 123-45-6789"}]}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
-            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=None, call_type="acompletion"
+        with patch.object(logging_only_guardrail.async_handler, "post", return_value=resp):
+            updated_kwargs, returned = await logging_only_guardrail.async_logging_hook(
+                kwargs=self._logged_call(messages=[{"role": "user", "content": "my ssn is 123-45-6789"}]),
+                result=None,
+                call_type="acompletion",
             )
-        assert result is None
-        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
-        assert guardrail_information[0]["guardrail_status"] == "guardrail_intervened"
+        assert returned is None
+        entries = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert entries[0]["guardrail_status"] == "guardrail_intervened"
+        assert entries[0]["guardrail_mode"] == "logging_only"
+        assert "Blocking due to pii" in str(entries[0]["guardrail_response"])
 
     @pytest.mark.asyncio
-    async def test_response_block_verdict_marks_guardrail_status_intervened(self, singulr_guardrail):
-        """Only the response leg blocks here, so a request verdict of False must
-        not mask it."""
-        responses = [_make_response({"should_block": False}), _make_response({"should_block": True})]
-        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(singulr_guardrail.async_handler, "post", side_effect=responses):
-            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result={"choices": []}, call_type="acompletion"
+    async def test_vendor_timeout_is_recorded_as_failed_to_respond(self, logging_only_guardrail):
+        timeout = litellm.Timeout("Singulr timed out", model="gpt-4o", llm_provider="singulr")
+        with patch.object(logging_only_guardrail.async_handler, "post", side_effect=timeout):
+            updated_kwargs, returned = await logging_only_guardrail.async_logging_hook(
+                kwargs=self._logged_call(), result=None, call_type="acompletion"
             )
-        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
-        assert guardrail_information[0]["guardrail_status"] == "guardrail_intervened"
+        assert returned is None
+        entries = updated_kwargs["standard_logging_object"]["guardrail_information"]
+        assert [entry["guardrail_status"] for entry in entries] == ["guardrail_failed_to_respond"]
+        assert "timed out" in str(entries[0]["guardrail_response"])
 
     @pytest.mark.asyncio
-    async def test_block_verdict_still_reports_both_legs_and_returns_result(self, singulr_guardrail):
-        """A block verdict on the request leg is logging-only: it must not
-        short-circuit the response report or alter what the hook returns."""
-        resp = _make_response({"should_block": True})
-        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-        result = {"choices": [{"finish_reason": "stop", "message": {"content": "hello"}}]}
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp) as mock_post:
-            returned_kwargs, returned_result = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=result, call_type="acompletion"
-            )
-        assert [call.kwargs["json"]["guardrail_scope"] for call in mock_post.call_args_list] == ["request", "response"]
-        assert returned_result is result
-        assert returned_kwargs is kwargs
+    async def test_mcp_tool_result_is_scanned_as_mcp_response(self, logging_only_guardrail):
+        from mcp.types import CallToolResult, TextContent
 
-    @pytest.mark.asyncio
-    async def test_api_error_marks_guardrail_status_intervened(self, singulr_guardrail):
-        """With block_on_error=True (the default), a transport failure while
-        reporting to Singulr raises internally; async_logging_hook must catch
-        it, mark the status accordingly, and still return (kwargs, result)
-        instead of propagating -- logging_only must never block the call."""
-        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(
-            singulr_guardrail.async_handler,
-            "post",
-            side_effect=httpx.TransportError("connection refused"),
-        ):
-            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=None, call_type="acompletion"
-            )
-        assert result is None
-        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
-        assert guardrail_information[0]["guardrail_status"] == "guardrail_intervened"
-
-    @pytest.mark.asyncio
-    async def test_unexpected_exception_is_swallowed_without_recording_guardrail_information(self, singulr_guardrail):
-        """A non-guardrail exception (e.g. a bug in a downstream integration)
-        must not propagate out of the logging_only hook, and must not record
-        standard_logging_guardrail_information since no verdict was reached."""
-        kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-        with patch.object(singulr_guardrail.async_handler, "post", side_effect=RuntimeError("boom")):
-            updated_kwargs, result = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=None, call_type="acompletion"
-            )
-        assert result is None
-        assert "standard_logging_object" not in updated_kwargs
-
-    @pytest.mark.asyncio
-    async def test_appends_to_existing_guardrail_information_list(self, singulr_guardrail):
         resp = _make_response({"should_block": False})
-        existing_entry = {"guardrail_name": "other-guardrail"}
-        kwargs = {
-            "messages": [{"role": "user", "content": "hi"}],
-            "standard_logging_object": {"guardrail_information": [existing_entry]},
-        }
-        with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
-            updated_kwargs, _ = await singulr_guardrail.async_logging_hook(
-                kwargs=kwargs, result=None, call_type="acompletion"
+        result = CallToolResult(content=[TextContent(type="text", text="ssn 123-45-6789")])
+        with patch.object(logging_only_guardrail.async_handler, "post", return_value=resp) as mock_post:
+            await logging_only_guardrail.async_logging_hook(
+                kwargs=self._logged_call(model="MCP: get_customer_record", messages=None),
+                result=result,
+                call_type="call_mcp_tool",
             )
-        guardrail_information = updated_kwargs["standard_logging_object"]["guardrail_information"]
-        assert guardrail_information[0] is existing_entry
-        assert guardrail_information[1]["guardrail_name"] == "test-singulr"
+        payloads = [call.kwargs["json"] for call in mock_post.call_args_list]
+        assert [payload["guardrail_scope"] for payload in payloads] == ["mcp_response"]
+        assert payloads[0]["tool_result"] == ["ssn 123-45-6789"]
+        assert payloads[0]["model_name"] == "MCP: get_customer_record"
 
-    def test_sync_logging_hook_returns_kwargs_and_result_unchanged_when_loop_running(self, singulr_guardrail):
-        """logging_hook is the sync entrypoint used outside an event loop;
-        inside a running loop it must no-op rather than deadlock or raise."""
-        import asyncio
-
-        async def _drive():
-            kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-            return singulr_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
-
-        returned_kwargs, returned_result = asyncio.run(_drive())
-        assert returned_result is None
-        assert returned_kwargs == {"messages": [{"role": "user", "content": "hi"}]}
-
-    def test_sync_logging_hook_creates_a_new_event_loop_when_none_is_set(self, singulr_guardrail):
-        """A thread with no current event loop must get a fresh one instead
-        of raising RuntimeError out of the sync entrypoint."""
+    def test_sync_logging_hook_never_calls_singulr(self, logging_only_guardrail):
         from concurrent.futures import ThreadPoolExecutor
 
-        resp = _make_response({"should_block": False})
+        kwargs = {"messages": [{"role": "user", "content": "hi"}], "standard_logging_object": {}}
 
         def _run():
-            kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-            with patch.object(singulr_guardrail.async_handler, "post", return_value=resp):
-                return singulr_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
+            with patch.object(logging_only_guardrail.async_handler, "post") as mock_post:
+                returned = logging_only_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
+                mock_post.assert_not_called()
+                return returned
 
         with ThreadPoolExecutor(max_workers=1) as pool:
             returned_kwargs, returned_result = pool.submit(_run).result()
         assert returned_result is None
-        guardrail_information = returned_kwargs["standard_logging_object"]["guardrail_information"]
-        assert guardrail_information[0]["guardrail_status"] == "success"
-
-    def test_sync_logging_hook_swallows_unexpected_exception(self, singulr_guardrail):
-        """A bug surfacing from async_logging_hook itself, not just the
-        Singulr API call, must not propagate out of the sync entrypoint."""
-        from concurrent.futures import ThreadPoolExecutor
-
-        def _run():
-            kwargs = {"messages": [{"role": "user", "content": "hi"}]}
-            with patch.object(singulr_guardrail, "async_logging_hook", side_effect=RuntimeError("boom")):
-                return singulr_guardrail.logging_hook(kwargs=kwargs, result=None, call_type="acompletion")
-
-        with ThreadPoolExecutor(max_workers=1) as pool:
-            returned_kwargs, returned_result = pool.submit(_run).result()
-        assert returned_result is None
-        assert returned_kwargs == {"messages": [{"role": "user", "content": "hi"}]}
-
-
-# ---------------------------------------------------------------------------
-# HTTP call wiring (endpoint, timeout, headers)
-# ---------------------------------------------------------------------------
+        assert returned_kwargs == {"messages": [{"role": "user", "content": "hi"}], "standard_logging_object": {}}
 
 
 class TestSingulrRequestWiring:
     @pytest.mark.asyncio
     async def test_sends_configured_timeout_and_calls_the_guard_endpoint(self):
-        """litellm_params.timeout must reach the httpx call so operators can
-        tighten or loosen the latency budget instead of being stuck with a
-        hardcoded 30s regardless of configuration."""
         guardrail = SingulrGuardrail(
             singulr_api_key="test_key",
             singulr_api_base="https://api.test.singulr.ai",
@@ -1168,11 +1076,6 @@ class TestSingulrBuildHeaders:
         assert "X-Singulr-Guardrail-Id" not in headers
 
 
-# ---------------------------------------------------------------------------
-# Non-JSON / malformed response handling
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrInvalidResponse:
     @pytest.mark.asyncio
     async def test_non_json_response_block_on_error_false_returns_inputs(self):
@@ -1217,9 +1120,6 @@ class TestSingulrInvalidResponse:
 
     @pytest.mark.asyncio
     async def test_response_missing_expected_fields_block_on_error_true_raises(self):
-        """Regression: a response body that fails SingulrGuardrailResponse
-        validation must raise GuardrailRaisedException instead of letting
-        pydantic.ValidationError propagate unhandled."""
         guardrail = SingulrGuardrail(
             singulr_api_base="https://api.test.singulr.ai",
             singulr_api_key="test_token_1234",
@@ -1239,11 +1139,6 @@ class TestSingulrInvalidResponse:
                 )
 
 
-# ---------------------------------------------------------------------------
-# Transport error handling
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrTransportError:
     @pytest.mark.asyncio
     async def test_remote_protocol_error_block_on_error_false_returns_inputs(self):
@@ -1287,11 +1182,6 @@ class TestSingulrTransportError:
                 )
 
 
-# ---------------------------------------------------------------------------
-# HTTP status error handling
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrHttpStatusError:
     @pytest.mark.asyncio
     async def test_http_error_message_names_status_code_not_unreachable(self):
@@ -1342,11 +1232,6 @@ class TestSingulrHttpStatusError:
         assert result is inputs
 
 
-# ---------------------------------------------------------------------------
-# Config model
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrConfigModel:
     def test_ui_friendly_name(self):
         assert SingulrGuardrailConfigModel.ui_friendly_name() == "Singulr"
@@ -1355,11 +1240,6 @@ class TestSingulrConfigModel:
         assert SingulrGuardrail.get_config_model() is SingulrGuardrailConfigModel
 
 
-# ---------------------------------------------------------------------------
-# Initializer and registry
-# ---------------------------------------------------------------------------
-
-
 class TestSingulrInitializer:
     def test_guardrail_initializer_registry_has_entry(self):
         from litellm.proxy.guardrails.guardrail_hooks.singulr import (
@@ -1369,11 +1249,6 @@ class TestSingulrInitializer:
         assert callable(initialize_guardrail)
 
     def test_initialize_guardrail_reads_singulr_prefixed_fields(self):
-        """Regression: the UI config form (and YAML config) populate the
-        singulr_-prefixed fields declared on SingulrGuardrailConfigModel, not
-        the generic api_base/api_key fields. initialize_guardrail must read
-        those, or a UI-configured singulr_api_base is silently ignored and
-        the guardrail falls back to the localhost default."""
         from litellm.proxy.guardrails.guardrail_hooks.singulr import (
             initialize_guardrail,
         )
@@ -1398,10 +1273,6 @@ class TestSingulrInitializer:
         assert cb.singulr_guardrail_id == "configured_guardrail_id"
 
     def test_initialize_guardrail_wires_timeout(self):
-        """BaseLitellmParams.timeout exists so operators can override the
-        per-request latency budget. initialize_guardrail must forward it to
-        SingulrGuardrail instead of leaving every deployment stuck on the
-        hardcoded default regardless of configuration."""
         from litellm.proxy.guardrails.guardrail_hooks.singulr import (
             initialize_guardrail,
         )

From c7e4160ee6ce40493e5e3d896a30ac1668a55c70 Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 19:15:34 -0700
Subject: [PATCH 49/67] fix(mcp): enforce OAuth write policy across signed
 callbacks

---
 .../mcp_server/bridge_token_flow.py           |  54 ++++----
 .../mcp_server/discoverable_endpoints.py      |  58 +++++----
 .../test_user_api_key_auth.py                 |   1 +
 .../mcp_server/test_discoverable_endpoints.py | 118 +++++++++++++++++-
 4 files changed, 181 insertions(+), 50 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 962e39d7dd6..5fe0929773c 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -306,18 +306,8 @@ async def _revalidate_active_subject(identity: "EnvelopeIdentity") -> "_KeyResol
 
 async def _extract_user_id_from_request(request: Request, server_id: str | None = None) -> str | None:
     """Resolve identity for binding, or authorize the credential-write action for a target server."""
-    from litellm.proxy._experimental.mcp_server.mcp_server_manager import (  # noqa: PLC0415  # registry imports auth helpers
-        global_mcp_server_manager,
-    )
-    from litellm.proxy._experimental.mcp_server.ui_session_utils import (
-        can_access_mcp_server,  # noqa: PLC0415  # proxy import cycle
-    )
     from litellm.proxy._types import UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.handle_jwt import JWTHandler  # noqa: PLC0415  # proxy import cycle
-    from litellm.proxy.auth.route_checks import RouteChecks  # noqa: PLC0415  # proxy import cycle
-    from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
-        _run_centralized_common_checks,  # pyright: ignore[reportPrivateUsage]  # reuse admission policy for the credential-write action
-    )
 
     token: Final = _litellm_key_from_request(request)
     # The OAuth relay is public; the optional server-side write is the same protected action
@@ -331,23 +321,39 @@ async def _extract_user_id_from_request(request: Request, server_id: str | None
     auth: Final = resolved.key if isinstance(resolved, _ResolvedKey) else resolved
     if not isinstance(auth, UserAPIKeyAuth) or not _active_key_user_id(auth):
         return None
-    if write_route is not None and server_id is not None:
-        try:
-            RouteChecks.is_virtual_key_allowed_to_call_route(route=write_route, valid_token=auth, request=request)
-            await _run_centralized_common_checks(
-                user_api_key_auth_obj=auth,
-                request=request,
-                request_data={},
-                route=write_route,
-            )
-            if not await can_access_mcp_server(auth, server_id, global_mcp_server_manager.get_allowed_mcp_servers):
-                return None
-        except Exception as exc:  # noqa: BLE001  # authorization failure must never write credentials
-            verbose_logger.debug("OAuth credential write not authorized (%s)", type(exc).__name__)
-            return None
+    if server_id is not None and not await can_store_oauth_credential(request, auth, server_id):
+        return None
     return auth.user_id
 
 
+async def can_store_oauth_credential(request: Request, auth: "UserAPIKeyAuth", server_id: str) -> bool:
+    """Apply the same write policy to request credentials and verified signed-callback users."""
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import (  # noqa: PLC0415  # registry imports auth helpers
+        global_mcp_server_manager,
+    )
+    from litellm.proxy._experimental.mcp_server.ui_session_utils import (
+        can_access_mcp_server,  # noqa: PLC0415  # proxy import cycle
+    )
+    from litellm.proxy.auth.route_checks import RouteChecks  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
+        _run_centralized_common_checks,  # pyright: ignore[reportPrivateUsage]  # reuse admission policy for the credential-write action
+    )
+
+    write_route: Final = f"/v1/mcp/server/{server_id}/oauth-user-credential"
+    try:
+        RouteChecks.is_virtual_key_allowed_to_call_route(route=write_route, valid_token=auth, request=request)
+        await _run_centralized_common_checks(
+            user_api_key_auth_obj=auth,
+            request=request,
+            request_data={},
+            route=write_route,
+        )
+        return await can_access_mcp_server(auth, server_id, global_mcp_server_manager.get_allowed_mcp_servers)
+    except Exception as exc:  # noqa: BLE001  # authorization failure must never write credentials
+        verbose_logger.debug("OAuth credential write not authorized (%s)", type(exc).__name__)
+        return False
+
+
 async def _resolve_jwt_auth(
     request: Request,
     token: str,
diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index 56968745ea9..9ba67f966a2 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -29,9 +29,11 @@ from litellm.proxy._experimental.mcp_server.bridge_token_flow import (
     _BridgeRefreshReady,
     _extract_user_id_from_request,
     _finish_bridge_mint,
+    _litellm_key_from_request,  # pyright: ignore[reportPrivateUsage]  # shared credential precedence for authorization issuance
     _prepare_bridge_mint,
     _prepare_bridge_refresh,
     _reload_active_user_by_id,
+    can_store_oauth_credential,
 )
 from litellm.proxy._experimental.mcp_server.faults import (
     CallerRejected,
@@ -836,16 +838,29 @@ async def _user_can_reach_mcp_server(user_id: str, server_id: str) -> bool:
     return server_id in await global_mcp_server_manager.get_allowed_mcp_servers(admitted)
 
 
-async def _bridge_authorize_access_denial(
-    litellm_user_id: str,
+async def _resolve_oauth_authorization_user(
+    request: Request,
     mcp_server: MCPServer,
     redirect_uri: str,
     state: str,
-) -> RedirectResponse | None:
-    """The denial redirect for a signed-in user who cannot reach the target server, or None to proceed."""
-    if await _user_can_reach_mcp_server(litellm_user_id, mcp_server.server_id):
-        return None
-    return _bridge_access_denied_redirect(redirect_uri, state, mcp_server)
+    enforce_binding: bool,
+) -> str | RedirectResponse:
+    """Resolve the authorization subject without replacing denied credentials with cookie grants."""
+    from litellm.proxy._experimental.mcp_server.byok_oauth_endpoints import (  # noqa: PLC0415  # proxy import cycle
+        _user_id_from_session_cookie,
+    )
+
+    request_user_id: Final = (
+        await _extract_user_id_from_request(request, mcp_server.server_id) if enforce_binding else None
+    )
+    if enforce_binding and request_user_id is None and _litellm_key_from_request(request):
+        return _bridge_access_denied_redirect(redirect_uri, state, mcp_server)
+    user_id: Final = request_user_id or _user_id_from_session_cookie(request)
+    if user_id is None:
+        return _redirect_to_litellm_login(request)
+    if not await _user_can_reach_mcp_server(user_id, mcp_server.server_id):
+        return _bridge_access_denied_redirect(redirect_uri, state, mcp_server)
+    return user_id
 
 
 async def authorize_with_server(
@@ -911,23 +926,12 @@ async def authorize_with_server(
     # Seal the authenticated caller into state so the token exchange cannot select another credential owner.
     litellm_user_id: str | None = None
     if enforce_binding or (resolved_server.is_dcr_bridge and resolved_server.is_oauth_delegate):
-        from litellm.proxy._experimental.mcp_server.byok_oauth_endpoints import (  # noqa: PLC0415  # inline import avoids a module-load circular import
-            _user_id_from_session_cookie,
+        subject: Final = await _resolve_oauth_authorization_user(
+            request, resolved_server, redirect_uri, state, enforce_binding
         )
-
-        litellm_user_id = (
-            await _extract_user_id_from_request(request) if enforce_binding else None
-        ) or _user_id_from_session_cookie(request)
-        if litellm_user_id is None:
-            return _redirect_to_litellm_login(request)
-        denial: Final = await _bridge_authorize_access_denial(
-            litellm_user_id=litellm_user_id,
-            mcp_server=resolved_server,
-            redirect_uri=redirect_uri,
-            state=state,
-        )
-        if denial is not None:
-            return denial
+        if isinstance(subject, RedirectResponse):
+            return subject
+        litellm_user_id = subject
 
     oauth_nonce: Final = secrets.token_urlsafe(32) if enforce_binding else None
     encoded_state: Final = encode_state_with_base_url(
@@ -1220,8 +1224,14 @@ async def exchange_token_with_server(
             try:
                 # Identity binding above must retain the verified caller even when a write is
                 # denied. Authorize persistence separately, immediately before its side effect.
+                from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPRequestHandler
+
+                # A sealed code delegates a verified user for this authorized server. Raw
+                # request credentials retain their own JWT/key restrictions during resolution.
                 can_store: Final = (
-                    await _user_can_reach_mcp_server(user_id, resolved_server.server_id)
+                    await can_store_oauth_credential(
+                        request, await MCPRequestHandler.reload_admitted_user(user_id), resolved_server.server_id
+                    )
                     if bridge_identity is not None
                     else await _extract_user_id_from_request(request, resolved_server.server_id) == user_id
                 )
diff --git a/tests/proxy_unit_tests/test_user_api_key_auth.py b/tests/proxy_unit_tests/test_user_api_key_auth.py
index 0cdf3500d50..a8fce58c60b 100644
--- a/tests/proxy_unit_tests/test_user_api_key_auth.py
+++ b/tests/proxy_unit_tests/test_user_api_key_auth.py
@@ -1069,6 +1069,7 @@ async def test_jwt_non_admin_team_route_access(monkeypatch):
 
     mock_jwt_response = {
         "is_proxy_admin": False,
+        "jwt_claims": {},
         "team_id": None,
         "team_object": None,
         "user_id": None,
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index 8c179eea4cb..1739ac6d743 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -11171,8 +11171,8 @@ async def test_identity_bound_authorization_carries_nonce_and_caller_through_cal
               "litellm.proxy._experimental.mcp_server.discoverable_endpoints._extract_user_id_from_request",
               new=AsyncMock(return_value="alice")),
         patch(  # test-quality-ok: isolate user access lookup while testing nonce and caller preservation
-              "litellm.proxy._experimental.mcp_server.discoverable_endpoints._bridge_authorize_access_denial",
-              new=AsyncMock(return_value=None)),
+              "litellm.proxy._experimental.mcp_server.discoverable_endpoints._user_can_reach_mcp_server",
+              new=AsyncMock(return_value=True)),
     ):
         authorized = await authorize_with_server(
             request, server, "client", "http://127.0.0.1:6274/callback", state="client-state",
@@ -11972,3 +11972,117 @@ async def test_oauth_write_denial_does_not_erase_identity_binding(
     assert denied.value.status_code == 403
     assert denied.value.detail == {"error": "oauth_principal_mismatch"}
     manager.get_allowed_mcp_servers.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("admin_only", [False, True])
+async def test_signed_oauth_callback_honors_credential_write_policy(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    admin_only: bool,
+) -> None:
+    import httpx
+    import litellm
+
+    from litellm.caching.llm_caching_handler import LLMClientCache
+    from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server import discoverable_endpoints, mcp_server_manager
+    from litellm.proxy._types import MCPTransport
+    from litellm.types.llms.custom_http import httpxSpecialProvider
+    from litellm.types.mcp_server.mcp_server_manager import MCPServer
+
+    server: Final = MCPServer(
+        server_id="signed-server", name="signed-server", transport=MCPTransport.http,
+        auth_type=MCPAuth.oauth2, oauth2_flow="authorization_code", client_id="client",
+        token_url="https://upstream.example.test/token",
+    )
+    monkeypatch.setattr(proxy_server, "general_settings", {
+        "enable_jwt_auth": True,
+        "admin_only_routes": [f"/v1/mcp/server/{server.server_id}/oauth-user-credential"] if admin_only else [],
+    })
+    monkeypatch.setenv("LITELLM_SALT_KEY", "signed-oauth-test-salt")
+    manager: Final = MagicMock()
+    manager.get_allowed_mcp_servers = AsyncMock(return_value=[server.server_id])
+    manager.invalidate_user_oauth_token_cache = AsyncMock()
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
+    table: Final = proxy_server.prisma_client.db.litellm_mcpusercredentials
+    table.find_unique = AsyncMock(return_value=None)
+    table.upsert = AsyncMock()
+    clients: Final = LLMClientCache()
+    monkeypatch.setattr(litellm, "in_memory_llm_clients_cache", clients)
+
+    def upstream_response(outbound: httpx.Request) -> httpx.Response:
+        assert outbound.url == server.token_url
+        assert b"code=upstream-code" in outbound.content
+        return httpx.Response(200, json={"access_token": "upstream-token", "token_type": "Bearer"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(upstream_response)) as transport:
+        upstream: Final = AsyncHTTPHandler()
+        await upstream.client.aclose()
+        upstream.client = transport
+        clients.set_cache("async_httpx_client" + httpxSpecialProvider.Oauth2Check, upstream)
+        response: Final = await discoverable_endpoints.exchange_token_with_server(
+            request=_token_request({}, path="/signed-server/token"), mcp_server=server,
+            grant_type="authorization_code",
+            code=discoverable_endpoints.seal_bridge_authorization_code("upstream-code", "jwt-owner", server.server_id),
+            redirect_uri="http://localhost/callback", client_id="client", client_secret=None, code_verifier=None,
+        )
+    assert response.status_code == 200
+    assert json.loads(response.body)["access_token"] == "upstream-token"
+    if admin_only:
+        table.upsert.assert_not_awaited()
+    else:
+        table.upsert.assert_awaited_once()
+        assert table.upsert.call_args.kwargs["where"]["user_id_server_id"] == {
+            "user_id": "jwt-owner", "server_id": server.server_id,
+        }
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("allowed", [False, True])
+async def test_identity_bound_authorize_preserves_presented_jwt_permissions(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    allowed: bool,
+) -> None:
+    from urllib.parse import parse_qs, urlparse
+
+    from litellm.proxy._experimental.mcp_server import byok_oauth_endpoints, discoverable_endpoints, mcp_server_manager
+    from litellm.proxy._types import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPOAuthIdentityBinding, MCPServer
+
+    _, signing_key = jwt_oauth_identity
+    monkeypatch.setenv("LITELLM_SALT_KEY", "authorize-policy-test-salt")
+    server: Final = MCPServer(
+        server_id="bound-server", name="bound-server", transport=MCPTransport.http,
+        auth_type=MCPAuth.oauth2, oauth2_flow="authorization_code", client_id="client",
+        authorization_url="https://upstream.example.test/authorize", token_url="https://upstream.example.test/token",
+        oauth_identity_binding=MCPOAuthIdentityBinding(
+            mode="enforce", issuer="https://upstream.example.test", audiences=["client"],
+        ),
+    )
+    manager: Final = MagicMock()
+    # The full user roster permits the server; the presented JWT may have narrower access.
+    manager.get_allowed_mcp_servers = AsyncMock(
+        side_effect=lambda auth: [server.server_id] if allowed or auth.mcp_admitted_user_subject else [],
+    )
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
+    monkeypatch.setattr(  # test-quality-ok: session-cookie decoder is the separate authentication boundary; a valid cookie must not override a denied explicit credential
+        byok_oauth_endpoints, "_user_id_from_session_cookie", lambda request: "jwt-owner",
+    )
+    response: Final = await discoverable_endpoints.authorize_with_server(
+        request=_token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"}),
+        mcp_server=server, client_id="client", redirect_uri="http://127.0.0.1:6274/callback",
+        state="client-state", code_challenge="pkce-challenge", code_challenge_method="S256",
+    )
+    redirect: Final = urlparse(response.headers["location"])
+    query: Final = parse_qs(redirect.query)
+    if allowed:
+        assert redirect.hostname == "upstream.example.test"
+        assert query["nonce"] and response.headers.get("set-cookie")
+    else:
+        assert redirect.hostname == "127.0.0.1"
+        assert query["error"] == ["access_denied"]
+        assert query["state"] == ["client-state"]
+        assert "set-cookie" not in response.headers

From d94b9d117d70e42866948c2986a9ea0c3a4533e6 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 19:16:45 -0700
Subject: [PATCH 50/67] docs(e2e): clarify recorded IDs and quota header
 semantics

---
 tests/e2e/PROVIDER_CACHE.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 280132d0940..efd9eb66daa 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -22,6 +22,12 @@ Do not give cache credentials to candidate deployments. Counter artifacts contai
 
 Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
 
+## Recorded response semantics
+
+Replay preserves the original response ID, usage and end-to-end headers. The proxy can therefore deduplicate repeated provider IDs when storing spend-log rows, just as it does when a live upstream returns the same ID twice. One spend-log row per invocation is not guaranteed for identical recorded responses. Existing spend reconciliation requests use distinct prompt markers and retain their distinct-ID and row-count assertions; accounting tests are not automatically excluded from caching
+
+Provider remaining-quota headers describe the captured response. Metrics derived from them are historical on a cache hit, not a measurement of current provider capacity. Gateway-generated API-key quota headers are a separate contract. A test of fresh provider quota or timing must use the live-provider policy; replay can still exercise how the proxy processes the recorded headers
+
 ## Qualification
 
 `tests/code_coverage_tests/test_provider_cache.py` exercises local HTTP providers and disposable real Redis. CI runs these checks with the existing provider-edge and replay harness tests. These component checks do not establish Buildkite deployment, full-suite cross-build reuse or a genuine 24-hour expiry observation; those require separate runtime evidence

From 064d5d61dad263bad11a77668d1de75176767b69 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 18:51:55 -0700
Subject: [PATCH 51/67] ci(image-scan): ignore zlib CVE-2026-85091 until Wolfi
 ships the fix

Wolfi's security database names zlib 1.3.3-r0 as the fix for CVE-2026-85091,
but the newest zlib published to the Wolfi apk repo is 1.3.2-r7. Every
wolfi-base digest, including the current latest, still reports the CVE, so no
base image bump or apk upgrade can clear it and image-scan fails on every PR
touching a Dockerfile or the lockfile, and on the nightly schedule.

Ignore that CVE and its GHSA alias for the zlib apk package only, so a fixable
High in anything else still fails the job.
---
 .github/workflows/image-scan.yml |  2 ++
 .grype.yaml                      | 13 +++++++++++++
 2 files changed, 15 insertions(+)
 create mode 100644 .grype.yaml

diff --git a/.github/workflows/image-scan.yml b/.github/workflows/image-scan.yml
index 206bb809e0c..c27d49ed610 100644
--- a/.github/workflows/image-scan.yml
+++ b/.github/workflows/image-scan.yml
@@ -26,6 +26,7 @@ on:
       - ui/Dockerfile
       - ui/nginx.conf
       - .github/workflows/image-scan.yml
+      - .grype.yaml
   schedule:
     - cron: "41 6 * * *"
   workflow_dispatch:
@@ -93,6 +94,7 @@ jobs:
           GRYPE_MATCH_PYTHON_USING_CPES: "true"
         run: |
           "$RUNNER_TEMP/grype" litellm-image-scan:${{ github.sha }} \
+            --config .grype.yaml \
             --only-fixed \
             --fail-on high \
             --output table
diff --git a/.grype.yaml b/.grype.yaml
new file mode 100644
index 00000000000..c5e49851dc9
--- /dev/null
+++ b/.grype.yaml
@@ -0,0 +1,13 @@
+# Wolfi's security database names zlib 1.3.3-r0 as the fix for CVE-2026-85091,
+# but the newest zlib published to the Wolfi apk repo is 1.3.2-r7, so every
+# wolfi-base digest reports it and no `apk upgrade` can clear it.
+# Drop this once Wolfi ships zlib >= 1.3.3-r0; expected by 2026-10-15.
+ignore:
+  - vulnerability: CVE-2026-85091
+    package:
+      name: zlib
+      type: apk
+  - vulnerability: GHSA-g5fp-32jq-cfw2
+    package:
+      name: zlib
+      type: apk

From 3dda798c8a24f255219a2808eccbd2f66434f681 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 19:28:50 -0700
Subject: [PATCH 52/67] ci(e2e): consolidate cache contracts in filtered
 CircleCI job

---
 .circleci/config.yml                          | 17 ++++-
 .circleci/scripts/classify_changes.sh         | 11 +++-
 .circleci/scripts/path_filter.sh              |  4 +-
 .github/workflows/test-provider-cache.yml     | 63 -------------------
 .../test_litellm/test_circleci_path_filter.py | 14 +++++
 5 files changed, 40 insertions(+), 69 deletions(-)
 delete mode 100644 .github/workflows/test-provider-cache.yml

diff --git a/.circleci/config.yml b/.circleci/config.yml
index bb4ad0f4019..e2102a9ae91 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -9,7 +9,7 @@ commands:
     parameters:
       category:
         type: enum
-        enum: ["backend", "client"]
+        enum: ["backend", "client", "provider-harness"]
         default: "backend"
     steps:
       - run:
@@ -2918,19 +2918,30 @@ jobs:
   provider_replay_harness:
     docker:
       - *python312_image
+      - image: redis@sha256:e2debfb7956fa12c7ddc79d7e645c8cf26b30c99a6e9161ea9bf4171e1668a5f
     working_directory: ~/project
     resource_class: medium
+    environment:
+      E2E_CACHE_TEST_REDIS_URL: redis://127.0.0.1:6379/0
+      E2E_PROVIDER_CACHE: "0"
+      E2E_FIXTURE_MODE: live
     steps:
+      - checkout
+      - skip_if_unrelated_changes:
+          category: provider-harness
       - setup_litellm_test_deps
+      - wait_for_service:
+          url: tcp://localhost:6379
       - run:
-          name: Test provider replay harness
+          name: Test provider capture and replay harness
           command: |
             mkdir -p test-results/provider-replay-harness
             uv run --no-sync pytest -q --noconftest -o addopts= -o pythonpath=tests/e2e -p no:rerunfailures \
               --junitxml=test-results/provider-replay-harness/junit.xml \
               tests/e2e/test_provider_edge.py tests/e2e/test_fixture_bundle.py \
               tests/e2e/test_fixture_canonical.py tests/e2e/test_fixture_mode.py \
-              tests/code_coverage_tests/test_provider_replay_harness.py
+              tests/code_coverage_tests/test_provider_replay_harness.py \
+              tests/code_coverage_tests/test_provider_cache.py
       - store_test_results:
           path: test-results/provider-replay-harness
 
diff --git a/.circleci/scripts/classify_changes.sh b/.circleci/scripts/classify_changes.sh
index 7aa0c3544ee..9dc7b76b23f 100755
--- a/.circleci/scripts/classify_changes.sh
+++ b/.circleci/scripts/classify_changes.sh
@@ -1,13 +1,19 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
-category="${1:?usage: classify_changes.sh <backend|client|ui>}"
+category="${1:?usage: classify_changes.sh <backend|client|ui|provider-harness>}"
 
 has_client=false
 has_backend=false
 has_ci=false
+has_provider_harness=false
 while IFS= read -r file || [ -n "$file" ]; do
   [ -n "$file" ] || continue
+  case "$file" in
+    tests/e2e/*/*.py) : ;;
+    tests/e2e/*.py | tests/code_coverage_tests/test_provider_cache.py | tests/code_coverage_tests/test_provider_replay_harness.py | tests/test_litellm/test_circleci_path_filter.py | .circleci/* | pyproject.toml | uv.lock)
+      has_provider_harness=true ;;
+  esac
   case "$file" in
     ui/* | tests/e2e/ui/*) has_client=true ;;
     docs/* | *.md | *.mdx) : ;;
@@ -17,6 +23,9 @@ while IFS= read -r file || [ -n "$file" ]; do
 done
 
 case "$category" in
+  provider-harness)
+    [ "$has_provider_harness" = true ] && echo run || echo skip
+    ;;
   backend)
     [ "$has_backend" = true ] && echo run || echo skip
     ;;
diff --git a/.circleci/scripts/path_filter.sh b/.circleci/scripts/path_filter.sh
index dcf64a24399..cdadde732bd 100755
--- a/.circleci/scripts/path_filter.sh
+++ b/.circleci/scripts/path_filter.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
-category="${1:?usage: path_filter.sh <backend|client>}"
+category="${1:?usage: path_filter.sh <backend|client|provider-harness>}"
 here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 run_full() {
@@ -36,5 +36,5 @@ if [ "$decision" = run ]; then
   run_full "$category-relevant changes detected"
 fi
 
-echo "path-filter[$category]: only unrelated (docs/client) changes detected; halting job as successful"
+echo "path-filter[$category]: only unrelated changes detected; halting job as successful"
 circleci-agent step halt
diff --git a/.github/workflows/test-provider-cache.yml b/.github/workflows/test-provider-cache.yml
deleted file mode 100644
index 0507f90cf89..00000000000
--- a/.github/workflows/test-provider-cache.yml
+++ /dev/null
@@ -1,63 +0,0 @@
-name: Provider cache contracts
-
-on:
-  pull_request:
-    paths:
-      - 'tests/e2e/**'
-      - 'tests/code_coverage_tests/test_provider_cache.py'
-      - 'tests/code_coverage_tests/test_provider_replay_harness.py'
-      - '.github/workflows/test-provider-cache.yml'
-      - 'pyproject.toml'
-      - 'uv.lock'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  provider-cache:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    services:
-      redis:
-        image: redis@sha256:e2debfb7956fa12c7ddc79d7e645c8cf26b30c99a6e9161ea9bf4171e1668a5f
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 5s
-          --health-timeout 3s
-          --health-retries 10
-    env:
-      PYTHONDONTWRITEBYTECODE: '1'
-      PYTHONPATH: tests/e2e
-      E2E_CACHE_TEST_REDIS_URL: redis://127.0.0.1:6379/0
-      E2E_PROVIDER_CACHE: '0'
-      E2E_FIXTURE_MODE: live
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: '3.13'
-      - uses: ./.github/actions/setup-uv-with-retries
-        with:
-          version: '0.10.9'
-      - uses: ./.github/actions/cache-cargo-build
-      - name: Install locked dependencies
-        run: .github/scripts/uv_sync_with_retries.sh --frozen --group proxy-dev --group e2e-dev
-      - name: Verify cache and existing edge contracts
-        run: >-
-          uv run --no-sync pytest -c /dev/null -p no:cacheprovider
-          tests/code_coverage_tests/test_provider_cache.py
-          tests/code_coverage_tests/test_provider_replay_harness.py
-          tests/e2e/test_provider_edge.py
-          -q --junitxml=provider-cache-results.xml
-      - name: Save test results
-        if: always()
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        with:
-          name: provider-cache-results
-          path: provider-cache-results.xml
-          if-no-files-found: warn
diff --git a/tests/test_litellm/test_circleci_path_filter.py b/tests/test_litellm/test_circleci_path_filter.py
index b427a1a3bd8..af0e932400f 100644
--- a/tests/test_litellm/test_circleci_path_filter.py
+++ b/tests/test_litellm/test_circleci_path_filter.py
@@ -49,6 +49,20 @@ CI = [".github/workflows/test-litellm-ui-unit.yml"]
 @pytest.mark.parametrize(
     "category,changed,expected",
     [
+        ("provider-harness", ["tests/e2e/provider_cache.py"], "run"),
+        ("provider-harness", ["tests/e2e/conftest.py"], "run"),
+        ("provider-harness", ["tests/e2e/e2e_http.py"], "run"),
+        ("provider-harness", ["tests/code_coverage_tests/test_provider_cache.py"], "run"),
+        ("provider-harness", ["tests/code_coverage_tests/test_provider_replay_harness.py"], "run"),
+        ("provider-harness", [".circleci/config.yml"], "run"),
+        ("provider-harness", [".circleci/scripts/classify_changes.sh"], "run"),
+        ("provider-harness", ["pyproject.toml"], "run"),
+        ("provider-harness", ["uv.lock"], "run"),
+        ("provider-harness", ["tests/e2e/PROVIDER_CACHE.md"], "skip"),
+        ("provider-harness", ["tests/e2e/ui/test_example.py"], "skip"),
+        ("provider-harness", ["tests/e2e/quota_management/test_quota.py"], "skip"),
+        ("provider-harness", ["litellm/main.py"], "skip"),
+        ("provider-harness", ["ui/litellm-dashboard/src/App.tsx"], "skip"),
         # docs-only: skip everything
         ("backend", DOCS, "skip"),
         ("client", DOCS, "skip"),

From 39b78128103b1c0a2f703e275ddef60e1c1a98e1 Mon Sep 17 00:00:00 2001
From: Tin Chi Lo <tin@berri.ai>
Date: Tue, 15 Sep 2026 18:28:21 -0700
Subject: [PATCH 53/67] feat(ui): configure capability and Fuse v2 classifiers

---
 .../AutoRouters/AutoRoutersPanel.tsx          |   4 +-
 .../components/AutoRouters/autoRouterRows.ts  |   2 +
 ...oRouterClassifierTabs.integration.test.tsx |  75 +++
 .../add_model/AutoRouterClassifierTabs.tsx    |  58 ++
 .../add_model/ClassificationMethodConfig.tsx  |  55 +-
 .../add_model/ComplexityRouterConfig.tsx      | 636 +++++++++---------
 ...plexityRouterFastMode.integration.test.tsx | 186 ++++-
 .../add_model/DefaultModelField.tsx           |  56 ++
 ...ecastClassifierConfig.integration.test.tsx | 224 ++++++
 .../add_model/ForecastClassifierConfig.tsx    | 433 ++++++++++++
 .../add_model/PlanModeOverrideControls.tsx    |  44 ++
 .../components/add_model/RoutingOptions.tsx   |  23 +
 .../add_model/TierModelEffortRows.tsx         |  10 +-
 .../components/add_model/TierRestrictions.tsx |  12 +-
 .../add_model/add_auto_router_tab.test.tsx    | 108 +++
 .../add_model/add_auto_router_tab.tsx         | 451 +++++++------
 .../build_complexity_router_config.ts         | 132 +++-
 .../classifier_type_transition.test.ts        |  80 +++
 .../add_model/classifier_type_transition.ts   |  50 ++
 .../forecast_classifier_config.test.ts        | 284 ++++++++
 .../add_model/forecast_classifier_config.ts   | 188 ++++++
 .../src/components/add_model/tier_rows.ts     |  11 +-
 .../add_model/tier_set_actions.test.ts        |  29 +
 .../components/add_model/tier_set_actions.ts  |  30 +-
 ...d_updated_complexity_router_config.test.ts |  13 +-
 .../edit_auto_router_modal.tsx                | 141 ++--
 26 files changed, 2593 insertions(+), 742 deletions(-)
 create mode 100644 ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.integration.test.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/DefaultModelField.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/PlanModeOverrideControls.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/RoutingOptions.tsx
 create mode 100644 ui/litellm-dashboard/src/components/add_model/classifier_type_transition.test.ts
 create mode 100644 ui/litellm-dashboard/src/components/add_model/classifier_type_transition.ts
 create mode 100644 ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts
 create mode 100644 ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.ts

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/AutoRoutersPanel.tsx b/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/AutoRoutersPanel.tsx
index f11b74c939d..1625e0cbfb8 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/AutoRoutersPanel.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/AutoRoutersPanel.tsx
@@ -104,8 +104,8 @@ export function AutoRoutersPanel({
           <DialogHeader>
             <DialogTitle>Add Auto Router</DialogTitle>
             <DialogDescription>
-              Routes each request to a model by classifying its complexity. Called like any other model, so clients keep
-              using a single model name.
+              Choose a classifier to route each request to a model. Called like any other model, so clients keep using a
+              single model name.
             </DialogDescription>
           </DialogHeader>
           <AddAutoRouterTab
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/autoRouterRows.ts b/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/autoRouterRows.ts
index 7821437441d..dffb5811c0d 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/autoRouterRows.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/autoRouterRows.ts
@@ -57,6 +57,8 @@ const dedupe = (models: string[]): string[] => Array.from(new Set(models));
 
 const COMPLEXITY_TYPE_LABELS: Record<string, string> = {
   llm: "LLM Classifier",
+  capability: "Capability",
+  llm_v2: "Fuse v2",
   heuristic_first: "Heuristic first",
   hybrid: "Hybrid",
   custom: "Custom classifier",
diff --git a/ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.integration.test.tsx b/ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.integration.test.tsx
new file mode 100644
index 00000000000..ac6851349ea
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.integration.test.tsx
@@ -0,0 +1,75 @@
+import React, { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, renderWithProviders, screen } from "../../../tests/test-utils";
+import AutoRouterClassifierTabs from "./AutoRouterClassifierTabs";
+import type { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+
+const initial: ComplexityRouterConfigValue = {
+  classifier_type: "llm",
+  tiers: { SIMPLE: ["efficient"], MEDIUM: [], COMPLEX: [], REASONING: ["capable"] },
+};
+
+function Form({ initialValue = initial }: { initialValue?: ComplexityRouterConfigValue }) {
+  const [value, setValue] = useState(initialValue);
+  return (
+    <AutoRouterClassifierTabs value={value} onChange={setValue}>
+      <output aria-label="Classifier type">{value.classifier_type}</output>
+    </AutoRouterClassifierTabs>
+  );
+}
+
+describe("AutoRouterClassifierTabs", () => {
+  it.each(["heuristic", "heuristic_v2", "llm", "heuristic_first", "hybrid"] as const)(
+    "groups %s under Complexity without resetting its configuration",
+    (classifier_type) => {
+      const onChange = vi.fn();
+      renderWithProviders(
+        <AutoRouterClassifierTabs value={{ ...initial, classifier_type }} onChange={onChange}>
+          Existing classifier settings
+        </AutoRouterClassifierTabs>,
+      );
+      expect(screen.getByRole("tab", { name: "Complexity" })).toHaveAttribute("aria-selected", "true");
+      expect(screen.getByRole("tabpanel", { name: "Complexity" })).toHaveTextContent("Existing classifier settings");
+      fireEvent.click(screen.getByRole("tab", { name: "Complexity" }));
+      expect(onChange).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([
+    ["capability", "Capability"],
+    ["llm_v2", "Fuse v2"],
+  ] as const)("opens saved %s settings and switches back to local Complexity", (classifier_type, label) => {
+    renderWithProviders(<Form initialValue={{ ...initial, classifier_type }} />);
+    expect(screen.getByRole("tab", { name: label })).toHaveAttribute("aria-selected", "true");
+    fireEvent.click(screen.getByRole("tab", { name: "Complexity" }));
+    expect(screen.getByRole("tab", { name: "Complexity" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("status", { name: "Classifier type" })).toHaveTextContent("heuristic");
+  });
+
+  it("keeps custom tiers editable under Complexity and explains why forecast tabs are disabled", () => {
+    const onChange = vi.fn();
+    renderWithProviders(
+      <AutoRouterClassifierTabs
+        value={{
+          ...initial,
+          custom_tier_set: {
+            tiers: [{ id: "review", name: "REVIEW", definition: "Code reviews", models: ["capable"] }],
+            fallback_tier_id: "review",
+          },
+        }}
+        onChange={onChange}
+      >
+        Custom tiers
+      </AutoRouterClassifierTabs>,
+    );
+    expect(screen.getByRole("tabpanel", { name: "Complexity" })).toHaveTextContent("Custom tiers");
+    for (const name of ["Capability", "Fuse v2"]) {
+      const tab = screen.getByRole("tab", { name });
+      expect(tab).toHaveAttribute("aria-disabled", "true");
+      expect(tab).toHaveAccessibleDescription("Restore standard tiers to use Capability or Fuse v2.");
+      fireEvent.click(tab);
+    }
+    expect(onChange).not.toHaveBeenCalled();
+    expect(screen.getByText("Restore standard tiers to use Capability or Fuse v2.")).toBeVisible();
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.tsx b/ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.tsx
new file mode 100644
index 00000000000..98c0d4aab2f
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/AutoRouterClassifierTabs.tsx
@@ -0,0 +1,58 @@
+import React, { useId } from "react";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { effectiveClassifierType, type ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+import { transitionClassifierType } from "./classifier_type_transition";
+import { isForecastClassifier } from "./forecast_classifier_config";
+
+interface AutoRouterClassifierTabsProps {
+  value: ComplexityRouterConfigValue;
+  onChange: (value: ComplexityRouterConfigValue) => void;
+  children: React.ReactNode;
+}
+
+const AutoRouterClassifierTabs: React.FC<AutoRouterClassifierTabsProps> = ({ value, onChange, children }) => {
+  const restrictionId = useId();
+  const classifierType = effectiveClassifierType(value);
+  const selected = isForecastClassifier(classifierType) ? classifierType : "complexity";
+  const hasCustomTiers = Boolean(value.custom_tier_set);
+
+  const handleChange = (tab: unknown) => {
+    if (tab === selected) return;
+    if (tab === "complexity") {
+      onChange(transitionClassifierType(value, isForecastClassifier(classifierType) ? "heuristic" : classifierType));
+    } else if (!hasCustomTiers && (tab === "capability" || tab === "llm_v2")) {
+      onChange(transitionClassifierType(value, tab));
+    }
+  };
+
+  return (
+    <Tabs value={selected} onValueChange={handleChange}>
+      <p className="text-sm font-medium">Classifier type</p>
+      <TabsList aria-label="Classifier type" className="w-full">
+        <TabsTrigger value="complexity">Complexity</TabsTrigger>
+        <TabsTrigger
+          value="capability"
+          disabled={hasCustomTiers}
+          aria-describedby={hasCustomTiers ? restrictionId : undefined}
+        >
+          Capability
+        </TabsTrigger>
+        <TabsTrigger
+          value="llm_v2"
+          disabled={hasCustomTiers}
+          aria-describedby={hasCustomTiers ? restrictionId : undefined}
+        >
+          Fuse v2
+        </TabsTrigger>
+      </TabsList>
+      {hasCustomTiers && (
+        <p id={restrictionId} className="text-sm text-muted-foreground">
+          Restore standard tiers to use Capability or Fuse v2.
+        </p>
+      )}
+      <TabsContent value={selected}>{children}</TabsContent>
+    </Tabs>
+  );
+};
+
+export default AutoRouterClassifierTabs;
diff --git a/ui/litellm-dashboard/src/components/add_model/ClassificationMethodConfig.tsx b/ui/litellm-dashboard/src/components/add_model/ClassificationMethodConfig.tsx
index a6f2e65793a..64b08fc9ed1 100644
--- a/ui/litellm-dashboard/src/components/add_model/ClassificationMethodConfig.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ClassificationMethodConfig.tsx
@@ -1,3 +1,4 @@
+import { transitionClassifierType } from "./classifier_type_transition";
 import { Info } from "lucide-react";
 import { SimpleTooltip } from "@/components/ui/tooltip";
 import { MultiSelect } from "@/components/shared/MultiSelect";
@@ -17,7 +18,6 @@ import ClassifierReasoningEffortSelect from "./ClassifierReasoningEffortSelect";
 import ClassifierCircuitBreakerConfig from "./ClassifierCircuitBreakerConfig";
 import ClassifierVisionConfig from "./ClassifierVisionConfig";
 import type { ReasoningEffort } from "./complexity_router_tiers";
-import { nonReasoningTierFields } from "./nonReasoningTierFields";
 import { useComplexityScorerDefaults } from "@/app/(dashboard)/hooks/autoRouter/useComplexityScorerDefaults";
 import {
   ClassificationFrequency,
@@ -33,12 +33,10 @@ import {
   DEFAULT_CLASSIFIER_FALLBACK,
   DEFAULT_CLASSIFIER_TIMEOUT_MS,
   DEFAULT_CLASSIFICATION_RUBRIC,
-  NEW_CLASSIFIER_CLASSIFICATION_RUBRIC,
   ClassificationRubric,
   effectiveTierLabel,
   heuristicScoringRole,
   usesLlmClassifier,
-  DEFAULT_HEURISTIC_FIRST_MAX_TIER,
   DEFAULT_HYBRID_BOUNDARY_MARGIN,
   HEURISTIC_FIRST_MAX_TIER_KEYS,
   effectiveClassifierType,
@@ -263,35 +261,7 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
   const explicitlySupportedClassifierEfforts = effortOptionsByModel[classifierModel];
 
   const handleClassifierTypeChange = (classifierType: ClassifierType) => {
-    const nextValue: ComplexityRouterConfigValue = {
-      ...value,
-      classifier_type: classifierType,
-      classifier_llm_config: usesLlmClassifier(classifierType)
-        ? value.classifier_llm_config ?? {
-            model: "",
-            timeout_ms: DEFAULT_CLASSIFIER_TIMEOUT_MS,
-            classification_rubric: NEW_CLASSIFIER_CLASSIFICATION_RUBRIC,
-          }
-        : undefined,
-      classifier_context_window_size: usesLlmClassifier(classifierType)
-        ? value.classifier_context_window_size ?? DEFAULT_CLASSIFIER_CONTEXT_WINDOW_SIZE
-        : undefined,
-      classifier_context_budget_chars: usesLlmClassifier(classifierType)
-        ? value.classifier_context_budget_chars ?? DEFAULT_CLASSIFIER_CONTEXT_BUDGET_CHARS
-        : undefined,
-      classifier_context_include_assistant_turns: usesLlmClassifier(classifierType)
-        ? value.classifier_context_include_assistant_turns
-        : undefined,
-      classifier_fallback: usesLlmClassifier(classifierType) ? value.classifier_fallback : undefined,
-      heuristic_first_max_tier:
-        classifierType === "heuristic_first"
-          ? value.heuristic_first_max_tier ?? DEFAULT_HEURISTIC_FIRST_MAX_TIER
-          : undefined,
-      hybrid_boundary_margin:
-        classifierType === "hybrid" ? value.hybrid_boundary_margin ?? DEFAULT_HYBRID_BOUNDARY_MARGIN : undefined,
-      ...nonReasoningTierFields(classifierType, value),
-    };
-    onChange(nextValue);
+    onChange(transitionClassifierType(value, classifierType));
   };
 
   const handleHeuristicFirstMaxTierChange = (tier: string) => {
@@ -433,27 +403,6 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
     });
   };
 
-  if (classifierType === "capability") {
-    return (
-      <p className="text-sm text-muted-foreground">
-        This router uses capability forecasting. Configure its classifier, threshold, and calibration through YAML or
-        the API. Saving preserves those settings
-      </p>
-    );
-  }
-
-  if (classifierType === "llm_v2") {
-    return (
-      <div className="rounded-md border p-4 text-sm">
-        <strong>LLM V2 classifier (experimental)</strong>
-        <p className="mt-2 text-muted-foreground">
-          Combines task demands and model capability in one forecast. Its solver profiles and quality allowance are
-          configured through the API. Saving this router preserves those settings
-        </p>
-      </div>
-    );
-  }
-
   return (
     <>
       <ClassifierTypeRadios value={value} classifierType={classifierType} onTypeChange={handleClassifierTypeChange} />
diff --git a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx
index c6b9a69e76a..4ccabff18b9 100644
--- a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx
@@ -1,8 +1,11 @@
+import RoutingOptions from "./RoutingOptions";
+import PlanModeOverrideControls from "./PlanModeOverrideControls";
+import ForecastClassifierConfig, { ForecastSolverModels } from "./ForecastClassifierConfig";
+import { isForecastClassifier, type CapabilitySettings, type FuseSettings } from "./forecast_classifier_config";
 import { SimpleTooltip } from "@/components/ui/tooltip";
 import { MultiSelect } from "@/components/shared/MultiSelect";
-import { SearchSelect } from "@/components/shared/SearchSelect";
+import DefaultModelField from "./DefaultModelField";
 import { ChevronRight, Info, Plus, Trash2, X } from "lucide-react";
-import { Switch } from "@/components/ui/switch";
 
 import { AffinityControls } from "./AffinityControls";
 import NonReasoningTierToggle from "./NonReasoningTierToggle";
@@ -204,11 +207,6 @@ const rowOrigin = (row: TierRow, editing: boolean): string => {
   return isBuiltInTierName(row.name) ? "built-in" : "custom";
 };
 
-const defaultModelPlaceholderFor = (derivedDefaultModel: string | undefined, isCustomSet: boolean): string => {
-  if (derivedDefaultModel) return `Derived from tiers: ${derivedDefaultModel}`;
-  return isCustomSet ? "Add a model to your fallback tier" : "Add a model to the Simple or Medium tier";
-};
-
 const builtInTierInfo = (rowId: string): { label: string; description: string; examples: string } | undefined => {
   const builtIn = ALL_BUILT_IN_TIERS.find((tier) => tier === rowId);
   return builtIn ? TIER_DESCRIPTIONS[builtIn] : undefined;
@@ -376,6 +374,8 @@ export interface ComplexityRouterConfigValue {
   /** An explicit pin. Unset means the default tracks the tiers - see resolveComplexityDefaultModel. */
   default_model?: string;
   classifier_type: ClassifierType;
+  capability_classifier_config?: CapabilitySettings;
+  llm_v2_config?: FuseSettings;
   classifier_llm_config?: ClassifierLLMConfig;
   classifier_context_window_size?: number;
   classifier_context_budget_chars?: number;
@@ -535,44 +535,6 @@ export const DEFAULT_HYBRID_BOUNDARY_MARGIN = 0.03;
  */
 export const HEURISTIC_FIRST_MAX_TIER_KEYS = TIER_ORDER.slice(0, -1);
 
-const PlanModeOverrideControls: React.FC<{
-  value: ComplexityRouterConfigValue;
-  onChange: (value: ComplexityRouterConfigValue) => void;
-  planModeTierOptions: { value: string; label: string }[];
-}> = ({ value, onChange, planModeTierOptions }) => (
-  <>
-    <div className="flex items-center gap-2 mb-2">
-      <Switch
-        checked={value.plan_mode_min_tier !== undefined}
-        disabled={planModeTierOptions.length === 0}
-        onCheckedChange={(enabled) =>
-          onChange({
-            ...value,
-            plan_mode_min_tier: enabled ? planModeTierOptions.at(-1)?.value : undefined,
-          })
-        }
-        aria-label="Route plan-mode requests to a minimum tier"
-      />
-      <strong className="font-semibold">Route plan-mode requests to a minimum tier</strong>
-    </div>
-    <span className="block text-xs mb-3 text-muted-foreground">
-      Requests from coding agents in plan mode (Claude Code, GitHub Copilot) route to at least this tier. The classifier
-      still wins when it picks higher, and the override only lasts while plan mode is active.
-      {planModeTierOptions.length === 0 && " Add models to a tier to enable this."}
-    </span>
-    {value.plan_mode_min_tier !== undefined && (
-      <div style={{ maxWidth: 320 }}>
-        <TierRowSelect
-          label="Plan-mode minimum tier"
-          options={planModeTierOptions}
-          value={value.plan_mode_min_tier ?? null}
-          onValueChange={(tier) => onChange({ ...value, plan_mode_min_tier: tier })}
-        />
-      </div>
-    )}
-  </>
-);
-
 const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
   modelInfo,
   value,
@@ -596,6 +558,7 @@ const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
   onAutoRouterCompressionChange,
   showValidationErrors = false,
 }) => {
+  const forecast = isForecastClassifier(value.classifier_type);
   const customTierSet = value.custom_tier_set;
   const tierRows = activeTierRows(value);
   const tierRowsError = customTierSet ? getCustomTierRowsError(customTierSet) : null;
@@ -605,8 +568,6 @@ const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
     value: row.id,
     label: tierRowLabel(row, value.tier_labels),
   }));
-  const derivedDefaultModel = resolveComplexityDefaultModel(value);
-  const defaultModelPlaceholder = defaultModelPlaceholderFor(derivedDefaultModel, Boolean(customTierSet));
   const defaultModel = resolveComplexityDefaultModel(value, value.default_model);
 
   const dispatch = (action: TierSetAction) => {
@@ -641,298 +602,321 @@ const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
       tier_model_params: setTierModelParam(value.tier_model_params, tier, model, change),
     });
 
-  // Clearing the select drops the key entirely rather than storing "", so an emptied pin reads as
-  // "track the tiers" everywhere downstream instead of as a blank model name.
-  const handleDefaultModelChange = (model: string | null | undefined) => {
-    onChange({ ...value, default_model: model || undefined });
-  };
-
-  const handleTierLabelChange = (tier: keyof ComplexityTiers, label: string) => {
-    onChange({
-      ...value,
-      tier_labels: { ...value.tier_labels, [tier]: label },
-    });
-  };
+  const handleTierLabelChange = (tier: keyof ComplexityTiers, label: string) =>
+    onChange({ ...value, tier_labels: { ...value.tier_labels, [tier]: label } });
 
   return (
     <div className="w-full max-w-none">
       <div className="inline-flex items-center gap-2 mb-4">
-        <h4 className="m-0 text-xl font-semibold text-foreground">Complexity Tier Configuration</h4>
-        <SimpleTooltip content="Map each complexity tier to one or more models. Simple queries use cheaper/faster models, complex queries use more capable models.">
-          <Info className="size-4 text-muted-foreground" />
-        </SimpleTooltip>
+        <h4 className="m-0 text-xl font-semibold text-foreground">
+          {forecast ? "Solver models" : "Complexity Tier Configuration"}
+        </h4>
+        {!forecast && (
+          <SimpleTooltip content="Map each complexity tier to one or more models. Simple queries use cheaper/faster models, complex queries use more capable models.">
+            <Info className="size-4 text-muted-foreground" />
+          </SimpleTooltip>
+        )}
       </div>
 
-      <TierConfigIntro value={value} />
-
-      <Card>
-        <CardContent>
-          {!customTierSet && (
-            <NonReasoningTierToggle value={value} onChange={onChange} available={value.classifier_type === "llm"} />
-          )}
-
-          {tierRows.map((row, index) => {
-            const tierInfo = builtInTierInfo(row.id);
-            const label = tierRowLabel(row, value.tier_labels);
-            const tierMissing = showValidationErrors && row.models.length === 0;
-            const needsDefinition = Boolean(customTierSet) && !row.definition.trim() && !isBuiltInTierName(row.name);
-            const definitionMissing = showValidationErrors && needsDefinition;
-            const showsDisplayName = !customTierSet && !editingTiers;
-            return (
-              <div key={row.id}>
-                {index > 0 && <Separator className="my-4" />}
-                <div className="mb-4">
-                  <TierRowHeader
-                    row={row}
-                    index={index}
-                    rowCount={tierRows.length}
-                    label={label}
-                    description={tierInfo?.description}
-                    editing={editingTiers}
-                    isCustomSet={Boolean(customTierSet)}
-                    onRemove={() => removeTierRow(row.id)}
-                  />
-                  {tierInfo && !customTierSet && (
-                    <span className="block mb-2 text-xs text-muted-foreground">Examples: {tierInfo.examples}</span>
-                  )}
-                  {editingTiers && (
-                    <TierRowEditFields
-                      row={row}
-                      index={index}
-                      definitionMissing={definitionMissing}
-                      onPatch={(patch) => updateTierRow(row.id, patch)}
-                    />
-                  )}
-                  {showsDisplayName && tierInfo && (
-                    <InputGroup className="mb-2">
-                      <InputGroupInput
-                        value={value.tier_labels?.[row.id as keyof ComplexityTiers] ?? ""}
-                        onChange={(event) => handleTierLabelChange(row.id as keyof ComplexityTiers, event.target.value)}
-                        placeholder={`Display name (default: ${tierInfo.label})`}
-                        aria-label={`Display name for the ${tierInfo.label} tier`}
-                      />
-                      {value.tier_labels?.[row.id as keyof ComplexityTiers] && (
-                        <InputGroupAddon align="inline-end">
-                          <InputGroupButton
-                            size="icon-xs"
-                            aria-label={`Clear display name for the ${tierInfo.label} tier`}
-                            onClick={() => handleTierLabelChange(row.id as keyof ComplexityTiers, "")}
-                          >
-                            <X />
-                          </InputGroupButton>
-                        </InputGroupAddon>
-                      )}
-                    </InputGroup>
-                  )}
-                  <MultiSelect
-                    options={modelOptions}
-                    value={row.models}
-                    onValueChange={(models: string[]) => setRowModels(row, models)}
-                    placeholder={`Select model(s) for ${label.toLowerCase()} queries`}
-                    emptyText="No models found"
-                    className={tierMissing ? "w-full border-destructive" : "w-full"}
-                  />
-                  <TierModelEffortRows
-                    tierLabel={label}
-                    models={row.models}
-                    effortOptionsByModel={tierEffortOptionsByModel}
-                    paramsByModel={row.params}
-                    fastModeByModel={fastModeByModel}
-                    onEffortChange={(model, effort) =>
-                      handleTierModelParamChange(row.id, model, ["reasoning_effort", effort])
-                    }
-                    onFastModeChange={(model, enabled) =>
-                      handleTierModelParamChange(row.id, model, ["speed", enabled ? "fast" : undefined])
-                    }
-                  />
-                  {row.models.length > 1 && (
-                    <span className="text-xs text-muted-foreground">
-                      Multiple models selected: the router randomly picks among them per request (or Thompson-samples
-                      within the pool when adaptive routing is on).
-                    </span>
-                  )}
-                  {tierMissing && <span className="text-xs text-destructive">The {label} tier is required</span>}
-                </div>
-              </div>
-            );
-          })}
-
-          <TierSetToolbar
-            editing={editingTiers}
-            isCustomSet={Boolean(customTierSet)}
-            rowCount={tierRows.length}
-            rowsError={tierRowsError}
-            keywordRulesError={keywordRulesError}
-            onEditingChange={onEditingTiersChange}
-            onAdd={addCustomTier}
-            onRestore={exitToBuiltInTiers}
+      {forecast ? (
+        <>
+          <ForecastSolverModels
+            value={value}
+            onChange={onChange}
+            modelOptions={modelOptions}
+            effortOptionsByModel={tierEffortOptionsByModel}
+            fastModeByModel={fastModeByModel}
           />
+          <ForecastClassifierConfig
+            value={value}
+            onChange={onChange}
+            modelOptions={modelOptions}
+            effortOptionsByModel={classifierEffortOptionsByModel}
+          />
+        </>
+      ) : (
+        <>
+          <TierConfigIntro value={value} />
 
-          {customTierSet && (
-            <FallbackTierField
-              rows={tierRows}
-              fallbackTierId={customTierSet.fallback_tier_id}
-              onValueChange={(fallbackTierId) => onChange(setFallbackTier(value, fallbackTierId))}
-            />
-          )}
+          <Card>
+            <CardContent>
+              {!customTierSet && (
+                <NonReasoningTierToggle value={value} onChange={onChange} available={value.classifier_type === "llm"} />
+              )}
 
-          <Separator className="my-4" />
+              {tierRows.map((row, index) => {
+                const tierInfo = builtInTierInfo(row.id);
+                const label = tierRowLabel(row, value.tier_labels);
+                const tierMissing = showValidationErrors && row.models.length === 0;
+                const needsDefinition =
+                  Boolean(customTierSet) && !row.definition.trim() && !isBuiltInTierName(row.name);
+                const definitionMissing = showValidationErrors && needsDefinition;
+                const showsDisplayName = !customTierSet && !editingTiers;
+                return (
+                  <div key={row.id}>
+                    {index > 0 && <Separator className="my-4" />}
+                    <div className="mb-4">
+                      <TierRowHeader
+                        row={row}
+                        index={index}
+                        rowCount={tierRows.length}
+                        label={label}
+                        description={tierInfo?.description}
+                        editing={editingTiers}
+                        isCustomSet={Boolean(customTierSet)}
+                        onRemove={() => removeTierRow(row.id)}
+                      />
+                      {tierInfo && !customTierSet && (
+                        <span className="block mb-2 text-xs text-muted-foreground">Examples: {tierInfo.examples}</span>
+                      )}
+                      {editingTiers && (
+                        <TierRowEditFields
+                          row={row}
+                          index={index}
+                          definitionMissing={definitionMissing}
+                          onPatch={(patch) => updateTierRow(row.id, patch)}
+                        />
+                      )}
+                      {showsDisplayName && tierInfo && (
+                        <InputGroup className="mb-2">
+                          <InputGroupInput
+                            value={value.tier_labels?.[row.id as keyof ComplexityTiers] ?? ""}
+                            onChange={(event) =>
+                              handleTierLabelChange(row.id as keyof ComplexityTiers, event.target.value)
+                            }
+                            placeholder={`Display name (default: ${tierInfo.label})`}
+                            aria-label={`Display name for the ${tierInfo.label} tier`}
+                          />
+                          {value.tier_labels?.[row.id as keyof ComplexityTiers] && (
+                            <InputGroupAddon align="inline-end">
+                              <InputGroupButton
+                                size="icon-xs"
+                                aria-label={`Clear display name for the ${tierInfo.label} tier`}
+                                onClick={() => handleTierLabelChange(row.id as keyof ComplexityTiers, "")}
+                              >
+                                <X />
+                              </InputGroupButton>
+                            </InputGroupAddon>
+                          )}
+                        </InputGroup>
+                      )}
+                      <MultiSelect
+                        options={modelOptions}
+                        value={row.models}
+                        onValueChange={(models: string[]) => setRowModels(row, models)}
+                        placeholder={`Select model(s) for ${label.toLowerCase()} queries`}
+                        emptyText="No models found"
+                        className={tierMissing ? "w-full border-destructive" : "w-full"}
+                      />
+                      <TierModelEffortRows
+                        tierLabel={label}
+                        models={row.models}
+                        effortOptionsByModel={tierEffortOptionsByModel}
+                        paramsByModel={row.params}
+                        fastModeByModel={fastModeByModel}
+                        onEffortChange={(model, effort) =>
+                          handleTierModelParamChange(row.id, model, ["reasoning_effort", effort])
+                        }
+                        onFastModeChange={(model, enabled) =>
+                          handleTierModelParamChange(row.id, model, ["speed", enabled ? "fast" : undefined])
+                        }
+                      />
+                      {row.models.length > 1 && (
+                        <span className="text-xs text-muted-foreground">
+                          Multiple models selected: the router randomly picks among them per request (or
+                          Thompson-samples within the pool when adaptive routing is on).
+                        </span>
+                      )}
+                      {tierMissing && <span className="text-xs text-destructive">The {label} tier is required</span>}
+                    </div>
+                  </div>
+                );
+              })}
 
-          <div className="mb-2">
-            <div className="flex items-center gap-2 mb-2">
-              <strong className="text-base font-semibold">Default Model</strong>
-              <SimpleTooltip content="Leave empty to follow the tiers. A model chosen here is pinned: it stays the default however the tiers change.">
-                <Info className="size-4 text-muted-foreground" />
-              </SimpleTooltip>
-            </div>
-            <SearchSelect
-              options={modelOptions}
-              value={value.default_model ?? ""}
-              onValueChange={handleDefaultModelChange}
-              placeholder={defaultModelPlaceholder}
-              emptyText="No models found"
-              aria-label="Default model"
-            />
-            <span className="block mt-1 text-xs text-muted-foreground">
-              Used when the tier the request lands in has no model, and when the classifier fails with &quot;Route to
-              the default model&quot; selected.
-            </span>
-          </div>
-        </CardContent>
-      </Card>
+              <TierSetToolbar
+                editing={editingTiers}
+                isCustomSet={Boolean(customTierSet)}
+                rowCount={tierRows.length}
+                rowsError={tierRowsError}
+                keywordRulesError={keywordRulesError}
+                onEditingChange={onEditingTiersChange}
+                onAdd={addCustomTier}
+                onRestore={exitToBuiltInTiers}
+              />
 
+              {customTierSet && (
+                <FallbackTierField
+                  rows={tierRows}
+                  fallbackTierId={customTierSet.fallback_tier_id}
+                  onValueChange={(fallbackTierId) => onChange(setFallbackTier(value, fallbackTierId))}
+                />
+              )}
+            </CardContent>
+          </Card>
+        </>
+      )}
+      {!forecast && <DefaultModelField value={value} onChange={onChange} modelOptions={modelOptions} />}
       <Separator className="my-6" />
 
-      <div className="rounded-lg border border-border bg-muted">
-        {[
-          {
-            key: "classifier",
-            label: <strong className="text-foreground font-semibold">Advanced: Classification Method</strong>,
-            children: (
-              <ClassificationMethodConfig
-                value={value}
-                onChange={onChange}
-                modelOptions={modelOptions}
-                effortOptionsByModel={classifierEffortOptionsByModel}
-                customTechnicalKeywords={customTechnicalKeywords}
-                onCustomTechnicalKeywordsChange={onCustomTechnicalKeywordsChange}
-                showValidationErrors={showValidationErrors}
-                defaultModel={defaultModel}
-              />
-            ),
-          },
-          {
-            key: "adaptive",
-            label: <strong className="text-foreground font-semibold">Advanced: Adaptive Routing</strong>,
-            children: (
-              <Restricted by={restrictedBy(value, "adaptive")}>
-                <AdaptiveRoutingConfig value={value} onChange={onChange} />
-              </Restricted>
-            ),
-          },
-          {
-            key: "affinity",
-            label: <strong className="text-foreground font-semibold">Advanced: Affinity</strong>,
-            children: <AffinityControls value={value} onChange={onChange} />,
-          },
-          {
-            key: "modality",
-            label: <strong className="text-foreground font-semibold">Advanced: Modality Routing</strong>,
-            children: <ModalityRoutingControls value={value} onChange={onChange} />,
-          },
-          {
-            key: "plan-mode",
-            label: <strong className="text-foreground font-semibold">Advanced: Plan-Mode Override</strong>,
-            children: (
-              <PlanModeOverrideControls value={value} onChange={onChange} planModeTierOptions={planModeTierOptions} />
-            ),
-          },
-          {
-            key: "context-window",
-            label: <strong className="text-foreground font-semibold">Advanced: Context Window Escalation</strong>,
-            children: <ContextWindowEscalationConfig value={value} onChange={onChange} />,
-          },
-          {
-            key: "stall-escalation",
-            label: <strong className="text-foreground font-semibold">Advanced: Stalled Task Escalation</strong>,
-            children: (
-              <Restricted by={restrictedBy(value, "stallEscalation")}>
-                <StallEscalationConfig value={value} onChange={onChange} />
-              </Restricted>
-            ),
-          },
-          {
-            key: "response",
-            label: <strong className="text-foreground font-semibold">Advanced: Response Format</strong>,
-            children: <ResponseFormatControls value={value} onChange={onChange} />,
-          },
-          ...(onEscalationKeywordsChange
-            ? [
-                {
-                  key: "escalation",
-                  label: <strong className="text-foreground font-semibold">Advanced: Escalation Keywords</strong>,
-                  children: (
-                    <Restricted by={restrictedBy(value, "escalation")}>
-                      <EscalationKeywords keywords={escalationKeywords} onChange={onEscalationKeywordsChange} />
-                    </Restricted>
-                  ),
-                },
-              ]
-            : []),
-          ...(onAutoRouterCompressionChange
-            ? [
-                {
-                  key: "compression",
-                  label: <strong className="text-foreground font-semibold">Advanced: Compression</strong>,
-                  children: (
-                    <CompressionControls value={autoRouterCompression} onChange={onAutoRouterCompressionChange} />
-                  ),
-                },
-              ]
-            : []),
-          ...(onKeywordTierRulesChange || onSemanticMatchingEnabledChange
-            ? [
-                {
-                  key: "keyword-semantic",
-                  label: <strong className="text-foreground font-semibold">Advanced: Keyword/Semantic Matching</strong>,
-                  children: (
-                    <>
-                      {onKeywordTierRulesChange && (
-                        <KeywordTierRules
-                          rules={keywordTierRules}
-                          onChange={onKeywordTierRulesChange}
-                          tierLabels={value.tier_labels}
-                          tierNames={customTierSet && tierRows.map(activeTierName).filter(Boolean)}
-                        />
-                      )}
-                      {onKeywordTierRulesChange && onSemanticMatchingEnabledChange && <Separator className="my-4" />}
-                      {onSemanticMatchingEnabledChange && (
-                        <SemanticKeywordMatching
-                          enabled={semanticMatchingEnabled}
-                          onEnabledChange={onSemanticMatchingEnabledChange}
-                          embeddingModel={embeddingModel}
-                          onEmbeddingModelChange={onEmbeddingModelChange}
-                          matchThreshold={matchThreshold}
-                          onMatchThresholdChange={onMatchThresholdChange}
-                          modelInfo={modelInfo}
-                          showValidationErrors={showValidationErrors}
-                        />
-                      )}
-                    </>
-                  ),
-                },
-              ]
-            : []),
-        ].map(({ key, label, children }) => (
-          <Collapsible key={key} className="border-b border-border last:border-b-0">
-            <CollapsibleTrigger className="group flex w-full items-center gap-2 px-4 py-3 text-left">
-              <ChevronRight className="size-4 shrink-0 text-muted-foreground transition-transform group-data-panel-open:rotate-90" />
-              {label}
-            </CollapsibleTrigger>
-            <CollapsibleContent className="px-4 pb-4">{children}</CollapsibleContent>
-          </Collapsible>
-        ))}
-      </div>
+      <RoutingOptions forecast={forecast}>
+        {forecast && (
+          <>
+            <DefaultModelField value={value} onChange={onChange} modelOptions={modelOptions} />
+            <ForecastSolverModels
+              additionalPoolsOnly
+              value={value}
+              onChange={onChange}
+              modelOptions={modelOptions}
+              effortOptionsByModel={tierEffortOptionsByModel}
+              fastModeByModel={fastModeByModel}
+            />
+          </>
+        )}
+        <div className="rounded-lg border border-border bg-muted">
+          {[
+            ...(!forecast
+              ? [
+                  {
+                    key: "classifier",
+                    label: <strong className="text-foreground font-semibold">Advanced: Classification Method</strong>,
+                    children: (
+                      <ClassificationMethodConfig
+                        value={value}
+                        onChange={onChange}
+                        modelOptions={modelOptions}
+                        effortOptionsByModel={classifierEffortOptionsByModel}
+                        customTechnicalKeywords={customTechnicalKeywords}
+                        onCustomTechnicalKeywordsChange={onCustomTechnicalKeywordsChange}
+                        showValidationErrors={showValidationErrors}
+                        defaultModel={defaultModel}
+                      />
+                    ),
+                  },
+                ]
+              : []),
+            ...(value.classifier_type !== "llm_v2"
+              ? [
+                  {
+                    key: "adaptive",
+                    label: <strong className="text-foreground font-semibold">Advanced: Adaptive Routing</strong>,
+                    children: (
+                      <Restricted by={restrictedBy(value, "adaptive")}>
+                        <AdaptiveRoutingConfig value={value} onChange={onChange} />
+                      </Restricted>
+                    ),
+                  },
+                ]
+              : []),
+            {
+              key: "affinity",
+              label: <strong className="text-foreground font-semibold">Advanced: Affinity</strong>,
+              children: <AffinityControls value={value} onChange={onChange} />,
+            },
+            {
+              key: "modality",
+              label: <strong className="text-foreground font-semibold">Advanced: Modality Routing</strong>,
+              children: <ModalityRoutingControls value={value} onChange={onChange} />,
+            },
+            {
+              key: "plan-mode",
+              label: <strong className="text-foreground font-semibold">Advanced: Plan-Mode Override</strong>,
+              children: (
+                <PlanModeOverrideControls value={value} onChange={onChange} planModeTierOptions={planModeTierOptions} />
+              ),
+            },
+            {
+              key: "context-window",
+              label: <strong className="text-foreground font-semibold">Advanced: Context Window Escalation</strong>,
+              children: <ContextWindowEscalationConfig value={value} onChange={onChange} />,
+            },
+            {
+              key: "stall-escalation",
+              label: <strong className="text-foreground font-semibold">Advanced: Stalled Task Escalation</strong>,
+              children: (
+                <Restricted by={restrictedBy(value, "stallEscalation")}>
+                  <StallEscalationConfig value={value} onChange={onChange} />
+                </Restricted>
+              ),
+            },
+            {
+              key: "response",
+              label: <strong className="text-foreground font-semibold">Advanced: Response Format</strong>,
+              children: <ResponseFormatControls value={value} onChange={onChange} />,
+            },
+            ...(onEscalationKeywordsChange
+              ? [
+                  {
+                    key: "escalation",
+                    label: <strong className="text-foreground font-semibold">Advanced: Escalation Keywords</strong>,
+                    children: (
+                      <Restricted by={restrictedBy(value, "escalation")}>
+                        <EscalationKeywords keywords={escalationKeywords} onChange={onEscalationKeywordsChange} />
+                      </Restricted>
+                    ),
+                  },
+                ]
+              : []),
+            ...(onAutoRouterCompressionChange
+              ? [
+                  {
+                    key: "compression",
+                    label: <strong className="text-foreground font-semibold">Advanced: Compression</strong>,
+                    children: (
+                      <CompressionControls value={autoRouterCompression} onChange={onAutoRouterCompressionChange} />
+                    ),
+                  },
+                ]
+              : []),
+            ...(onKeywordTierRulesChange || onSemanticMatchingEnabledChange
+              ? [
+                  {
+                    key: "keyword-semantic",
+                    label: (
+                      <strong className="text-foreground font-semibold">Advanced: Keyword/Semantic Matching</strong>
+                    ),
+                    children: (
+                      <>
+                        {onKeywordTierRulesChange && (
+                          <KeywordTierRules
+                            rules={keywordTierRules}
+                            onChange={onKeywordTierRulesChange}
+                            tierLabels={value.tier_labels}
+                            tierNames={
+                              customTierSet || isForecastClassifier(value.classifier_type)
+                                ? tierRows.map(activeTierName).filter(Boolean)
+                                : undefined
+                            }
+                          />
+                        )}
+                        {onKeywordTierRulesChange && onSemanticMatchingEnabledChange && <Separator className="my-4" />}
+                        {onSemanticMatchingEnabledChange && (
+                          <SemanticKeywordMatching
+                            enabled={semanticMatchingEnabled}
+                            onEnabledChange={onSemanticMatchingEnabledChange}
+                            embeddingModel={embeddingModel}
+                            onEmbeddingModelChange={onEmbeddingModelChange}
+                            matchThreshold={matchThreshold}
+                            onMatchThresholdChange={onMatchThresholdChange}
+                            modelInfo={modelInfo}
+                            showValidationErrors={showValidationErrors}
+                          />
+                        )}
+                      </>
+                    ),
+                  },
+                ]
+              : []),
+          ].map(({ key, label, children }) => (
+            <Collapsible key={key} className="border-b border-border last:border-b-0">
+              <CollapsibleTrigger className="group flex w-full items-center gap-2 px-4 py-3 text-left">
+                <ChevronRight className="size-4 shrink-0 text-muted-foreground transition-transform group-data-panel-open:rotate-90" />
+                {label}
+              </CollapsibleTrigger>
+              <CollapsibleContent className="px-4 pb-4">{children}</CollapsibleContent>
+            </Collapsible>
+          ))}
+        </div>
+      </RoutingOptions>
     </div>
   );
 };
diff --git a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterFastMode.integration.test.tsx b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterFastMode.integration.test.tsx
index 34d14091bde..810289da79f 100644
--- a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterFastMode.integration.test.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterFastMode.integration.test.tsx
@@ -1,11 +1,12 @@
 import userEvent from "@testing-library/user-event";
 import React from "react";
 import { describe, expect, it, vi } from "vitest";
-import { renderWithProviders, screen } from "../../../tests/test-utils";
+import { renderWithProviders, screen, within } from "../../../tests/test-utils";
 import {
   buildUpdatedComplexityRouterConfig,
   hydrateComplexityRouterConfig,
 } from "../edit_auto_router/edit_auto_router_modal";
+import type { KeywordTierRule } from "./KeywordTierRules";
 import type { ModelGroup } from "../llm_calls/fetch_models";
 import ComplexityRouterConfig, { type ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
 
@@ -50,8 +51,8 @@ it.each([false, true])("edits and round-trips independent model settings with cu
   const view = renderWithProviders(editor(initial));
   const fast = () => screen.getByRole("switch", { name: `Fast mode for primary in the ${label} tier` });
 
-  expect(screen.getAllByRole("switch", { name: /^Fast mode for/ })).toHaveLength(3);
-  expect(screen.queryByRole("switch", { name: /^Fast mode for (blocked|missing)/ })).not.toBeInTheDocument();
+  expect(screen.getAllByRole("switch", { name: /^Fast mode for/ })).toHaveLength(4);
+  expect(screen.queryByRole("switch", { name: /^Fast mode for missing/ })).not.toBeInTheDocument();
   expect(screen.queryByRole("combobox", { name: /^Reasoning effort for secondary/ })).not.toBeInTheDocument();
   expect(screen.getByRole("switch", { name: `Fast mode for secondary in the ${label} tier` })).toBeChecked();
   expect(fast()).not.toBeChecked();
@@ -125,19 +126,170 @@ it.each([false, true])("edits and round-trips independent model settings with cu
   );
 });
 
-describe("Fast mode metadata", () => {
-  it("offers nothing before model capabilities load and leaves stored speed untouched", () => {
-    const value: ComplexityRouterConfigValue = {
-      tiers: { SIMPLE: ["primary"], MEDIUM: [], COMPLEX: [], REASONING: [] },
-      classifier_type: "heuristic",
-      tier_model_params: { SIMPLE: { primary: { speed: "fast" } } },
-    };
-    const onChange = vi.fn();
-    renderWithProviders(<ComplexityRouterConfig modelInfo={[]} value={value} onChange={onChange} />);
-    expect(screen.queryByRole("switch", { name: /^Fast mode for/ })).not.toBeInTheDocument();
-    expect(onChange).not.toHaveBeenCalled();
-    expect(buildUpdatedComplexityRouterConfig({}, value).tier_model_configs).toEqual({
-      SIMPLE: [{ model_name: "primary", litellm_params: { speed: "fast" } }],
-    });
+it.each(["capability", "llm_v2"] as const)("preserves Fast mode controls for %s solvers", async (classifierType) => {
+  const user = userEvent.setup();
+  const initial: ComplexityRouterConfigValue = {
+    classifier_type: classifierType,
+    classifier_llm_config: { model: "primary", timeout_ms: 3000 },
+    tiers: { SIMPLE: ["primary"], MEDIUM: [], COMPLEX: [], REASONING: ["blocked"] },
+    capability_classifier_config: { efficient_tier: "SIMPLE", capable_tier: "REASONING", base_threshold: 0.7 },
+    llm_v2_config: {
+      efficient_profile: "Small solver",
+      capable_profile: "Large solver",
+      harness: "One attempt",
+      max_quality_gap: 0.05,
+    },
+    tier_model_params: { SIMPLE: { primary: { reasoning_effort: "high", max_tokens: 1024 } } },
+  };
+  const onChange = vi.fn<(value: ComplexityRouterConfigValue) => void>();
+  const editor = (value: ComplexityRouterConfigValue) => (
+    <ComplexityRouterConfig modelInfo={modelInfo} value={value} onChange={onChange} />
+  );
+  const view = renderWithProviders(editor(initial));
+  const fast = () => screen.getByRole("switch", { name: "Fast mode for primary in the Efficient solver tier" });
+  expect(screen.getAllByRole("switch", { name: /^Fast mode for/ })).toHaveLength(1);
+  expect(fast()).not.toBeChecked();
+  await user.click(fast());
+  const enabled = onChange.mock.lastCall![0];
+  expect(enabled.tier_model_params?.SIMPLE.primary).toEqual({
+    reasoning_effort: "high",
+    max_tokens: 1024,
+    speed: "fast",
+  });
+  const saved = buildUpdatedComplexityRouterConfig({}, enabled);
+  expect(saved.tier_model_configs).toEqual({
+    SIMPLE: [{ model_name: "primary", litellm_params: { reasoning_effort: "high", max_tokens: 1024, speed: "fast" } }],
+  });
+  view.rerender(editor(hydrateComplexityRouterConfig(saved, undefined)));
+  expect(fast()).toBeChecked();
+  await user.click(fast());
+  expect(onChange.mock.lastCall![0].tier_model_params?.SIMPLE.primary).toEqual({
+    reasoning_effort: "high",
+    max_tokens: 1024,
   });
 });
+
+describe("Fast mode metadata", () => {
+  it.each(["heuristic", "capability", "llm_v2"] as const)(
+    "can clear stored Fast mode without current capability metadata for %s",
+    async (classifier_type) => {
+      const user = userEvent.setup();
+      const value: ComplexityRouterConfigValue = {
+        tiers: { SIMPLE: ["primary"], MEDIUM: [], COMPLEX: [], REASONING: ["secondary"] },
+        classifier_type,
+        tier_model_params: { SIMPLE: { primary: { speed: "fast", max_tokens: 512 } } },
+      };
+      const onChange = vi.fn<(value: ComplexityRouterConfigValue) => void>();
+      const editor = (current: ComplexityRouterConfigValue, info: ModelGroup[]) => (
+        <ComplexityRouterConfig modelInfo={info} value={current} onChange={onChange} />
+      );
+      const view = renderWithProviders(editor(value, []));
+      const fast = () => screen.getByRole("switch", { name: /^Fast mode for primary/ });
+      expect(fast()).toBeChecked();
+      expect(onChange).not.toHaveBeenCalled();
+      view.rerender(editor(value, [{ model_group: "primary", supports_fast_mode: false }]));
+      expect(fast()).toBeChecked();
+      await user.click(fast());
+      const cleared = onChange.mock.lastCall![0];
+      expect(cleared.tier_model_params?.SIMPLE.primary).toEqual({ max_tokens: 512 });
+      const saved = buildUpdatedComplexityRouterConfig({}, cleared);
+      expect(saved.tier_model_configs).toEqual({
+        SIMPLE: [{ model_name: "primary", litellm_params: { max_tokens: 512 } }],
+      });
+      view.rerender(editor(hydrateComplexityRouterConfig(saved, undefined), []));
+      expect(screen.queryByRole("switch", { name: /^Fast mode for primary/ })).not.toBeInTheDocument();
+      view.rerender(editor(cleared, modelInfo));
+      expect(fast()).not.toBeChecked();
+    },
+  );
+});
+
+it.each(["MEDIUM", "REASONING"])("clears a legacy Capability pool while reconciling plan floor %s", async (floor) => {
+  const user = userEvent.setup();
+  const stored = {
+    classifier_type: "capability" as const,
+    plan_mode_min_tier: floor,
+    tiers: { SIMPLE: ["primary"], MEDIUM: ["secondary"], COMPLEX: [], REASONING: ["blocked"] },
+    tier_model_configs: { MEDIUM: [{ model_name: "secondary", litellm_params: { speed: "fast" } }] },
+  };
+  const value = hydrateComplexityRouterConfig(stored, undefined);
+  const onChange = vi.fn<(value: ComplexityRouterConfigValue) => void>();
+  renderWithProviders(<ComplexityRouterConfig modelInfo={modelInfo} value={value} onChange={onChange} />);
+  await user.click(screen.getByRole("button", { name: "Advanced routing options" }));
+  expect(screen.getByRole("switch", { name: "Fast mode for secondary in the Medium routing pool tier" })).toBeChecked();
+  expect(onChange).not.toHaveBeenCalled();
+  await user.click(screen.getByRole("combobox", { name: "Select medium routing pool models" }));
+  await user.click(await screen.findByRole("option", { name: "secondary" }));
+  await user.keyboard("{Escape}");
+  const cleared = onChange.mock.lastCall![0];
+  expect(cleared.tiers.MEDIUM).toEqual([]);
+  expect(cleared.plan_mode_min_tier).toBe(floor === "MEDIUM" ? undefined : floor);
+  expect(cleared.tier_model_params).toBeUndefined();
+  expect(buildUpdatedComplexityRouterConfig(stored, cleared).tiers).toEqual({
+    SIMPLE: ["primary"],
+    REASONING: ["blocked"],
+  });
+});
+
+it.each(["capability", "llm_v2"] as const)(
+  "shows and clears a persisted default model in %s",
+  async (classifier_type) => {
+    const user = userEvent.setup();
+    const stored = {
+      classifier_type,
+      default_model: "legacy-default",
+      tiers: { SIMPLE: ["primary"], REASONING: ["secondary"] },
+    };
+    const onChange = vi.fn<(value: ComplexityRouterConfigValue) => void>();
+    const editor = (value: ComplexityRouterConfigValue) => (
+      <ComplexityRouterConfig modelInfo={modelInfo} value={value} onChange={onChange} />
+    );
+    const view = renderWithProviders(editor(hydrateComplexityRouterConfig(stored, undefined)));
+    await user.click(screen.getByRole("button", { name: "Advanced routing options" }));
+    const select = () => screen.getByRole("combobox", { name: "Default model" });
+    expect(select()).toHaveValue("legacy-default");
+    expect(onChange).not.toHaveBeenCalled();
+    await user.click(select());
+    await user.click(await screen.findByRole("option", { name: "blocked" }));
+    const changed = onChange.mock.lastCall![0];
+    expect(buildUpdatedComplexityRouterConfig(stored, changed).default_model).toBe("blocked");
+    view.rerender(editor(changed));
+    await user.click(
+      within(screen.getByRole("group", { name: "Default model configuration" })).getByRole("button", { name: "Clear" }),
+    );
+    const cleared = onChange.mock.lastCall![0];
+    expect(cleared.default_model).toBeUndefined();
+    const saved = buildUpdatedComplexityRouterConfig(stored, cleared);
+    expect(saved).not.toHaveProperty("default_model");
+    view.rerender(editor(hydrateComplexityRouterConfig(saved, undefined)));
+    expect(select()).toHaveValue("");
+    expect(select()).toHaveAttribute("placeholder", expect.stringContaining("primary"));
+  },
+);
+
+it.each(["capability", "llm_v2"] as const)("offers only populated keyword targets for %s", async (classifier_type) => {
+  const user = userEvent.setup();
+  const value: ComplexityRouterConfigValue = {
+    classifier_type,
+    tiers: { SIMPLE: ["primary"], MEDIUM: [], COMPLEX: [], REASONING: ["secondary"] },
+  };
+  const onRulesChange = vi.fn<(rules: KeywordTierRule[]) => void>();
+  const editor = (rules: KeywordTierRule[]) => (
+    <ComplexityRouterConfig
+      value={value}
+      onChange={vi.fn()}
+      modelInfo={modelInfo}
+      keywordTierRules={rules}
+      onKeywordTierRulesChange={onRulesChange}
+    />
+  );
+  const view = renderWithProviders(editor([]));
+  await user.click(screen.getByRole("button", { name: "Advanced routing options" }));
+  await user.click(screen.getByText("Advanced: Keyword/Semantic Matching"));
+  await user.click(screen.getByRole("button", { name: "Add keyword rule" }));
+  const rules = onRulesChange.mock.lastCall![0];
+  expect(rules[0].tier).toBe("SIMPLE");
+  view.rerender(editor(rules));
+  await user.click(screen.getByRole("combobox", { name: "Route keyword rule 1 to tier" }));
+  expect((await screen.findAllByRole("option")).map((option) => option.textContent)).toEqual(["Simple", "Reasoning"]);
+});
diff --git a/ui/litellm-dashboard/src/components/add_model/DefaultModelField.tsx b/ui/litellm-dashboard/src/components/add_model/DefaultModelField.tsx
new file mode 100644
index 00000000000..a3ab85f7c13
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/DefaultModelField.tsx
@@ -0,0 +1,56 @@
+import React from "react";
+import { Info } from "lucide-react";
+import { SearchSelect } from "@/components/shared/SearchSelect";
+import { SimpleTooltip } from "@/components/ui/tooltip";
+import type { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+import { isForecastClassifier } from "./forecast_classifier_config";
+import { resolveComplexityDefaultModel } from "./tier_rows";
+
+interface DefaultModelFieldProps {
+  value: ComplexityRouterConfigValue;
+  onChange: (value: ComplexityRouterConfigValue) => void;
+  modelOptions: { value: string; label: string }[];
+}
+
+const defaultModelPlaceholderFor = (derivedDefaultModel: string | undefined, isCustomSet: boolean): string => {
+  if (derivedDefaultModel) return `Derived from tiers: ${derivedDefaultModel}`;
+  return isCustomSet ? "Add a model to your fallback tier" : "Add a model to the Simple or Medium tier";
+};
+
+const DefaultModelField = ({ value, onChange, modelOptions }: DefaultModelFieldProps) => {
+  const defaultModelPlaceholder = defaultModelPlaceholderFor(
+    resolveComplexityDefaultModel(value),
+    Boolean(value.custom_tier_set),
+  );
+  // Clearing the select drops the key entirely rather than storing "", so an emptied pin reads as
+  // "track the tiers" everywhere downstream instead of as a blank model name.
+  const handleDefaultModelChange = (model: string | null | undefined) => {
+    onChange({ ...value, default_model: model || undefined });
+  };
+
+  return (
+    <div className="mt-4 mb-2" role="group" aria-label="Default model configuration">
+      <div className="flex items-center gap-2 mb-2">
+        <strong className="text-base font-semibold">Default Model</strong>
+        <SimpleTooltip content="Leave empty to follow the tiers. A model chosen here is pinned: it stays the default however the tiers change.">
+          <Info className="size-4 text-muted-foreground" />
+        </SimpleTooltip>
+      </div>
+      <SearchSelect
+        options={modelOptions}
+        value={value.default_model ?? ""}
+        onValueChange={handleDefaultModelChange}
+        placeholder={defaultModelPlaceholder}
+        emptyText="No models found"
+        aria-label="Default model"
+      />
+      <span className="block mt-1 text-xs text-muted-foreground">
+        {isForecastClassifier(value.classifier_type)
+          ? "Used when routing cannot find a suitable model. Classifier failures route to the capable solver."
+          : 'Used when the tier the request lands in has no model, and when the classifier fails with "Route to the default model" selected.'}
+      </span>
+    </div>
+  );
+};
+
+export default DefaultModelField;
diff --git a/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx b/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx
new file mode 100644
index 00000000000..c249a63899a
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx
@@ -0,0 +1,224 @@
+import React, { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { fireEvent, renderWithProviders, screen } from "../../../tests/test-utils";
+import ClassificationMethodConfig from "./ClassificationMethodConfig";
+import AutoRouterClassifierTabs from "./AutoRouterClassifierTabs";
+import ForecastClassifierConfig from "./ForecastClassifierConfig";
+import type { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+import { getForecastConfigError, isForecastClassifier } from "./forecast_classifier_config";
+import { buildUpdatedComplexityRouterConfig } from "../edit_auto_router/edit_auto_router_modal";
+
+vi.mock("@/components/networking", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@/components/networking")>()),
+  getComplexityScorerDefaults: vi.fn(async () => ({
+    tier_boundaries: {},
+    token_thresholds: {},
+    dimension_weights: {},
+  })),
+}));
+
+const initial: ComplexityRouterConfigValue = {
+  classifier_type: "capability",
+  classifier_llm_config: { model: "judge", timeout_ms: 20000 },
+  tiers: { SIMPLE: ["efficient"], MEDIUM: [], COMPLEX: [], REASONING: ["capable"] },
+  capability_classifier_config: { efficient_tier: "SIMPLE", capable_tier: "REASONING", base_threshold: 0.7 },
+};
+const fuseInitial: ComplexityRouterConfigValue = {
+  ...initial,
+  classifier_type: "llm_v2",
+  capability_classifier_config: undefined,
+  adaptive: false,
+  llm_v2_config: {
+    efficient_profile: "Small solver",
+    capable_profile: "Larger solver",
+    harness: "One attempt",
+    max_quality_gap: 0.05,
+  },
+};
+const options = ["judge", "efficient", "capable"].map((model) => ({ value: model, label: model }));
+
+function Form({ initialValue = initial }: { initialValue?: ComplexityRouterConfigValue }) {
+  const [value, setValue] = useState(initialValue);
+  const [saved, setSaved] = useState("");
+  return (
+    <>
+      <AutoRouterClassifierTabs value={value} onChange={setValue}>
+        {isForecastClassifier(value.classifier_type) ? (
+          <ForecastClassifierConfig
+            value={value}
+            onChange={setValue}
+            modelOptions={options}
+            effortOptionsByModel={{}}
+          />
+        ) : (
+          <ClassificationMethodConfig
+            value={value}
+            onChange={setValue}
+            modelOptions={options}
+            effortOptionsByModel={{}}
+          />
+        )}
+      </AutoRouterClassifierTabs>
+      <button
+        disabled={Boolean(getForecastConfigError(value))}
+        onClick={() => setSaved(JSON.stringify(buildUpdatedComplexityRouterConfig({}, value)))}
+      >
+        Save configuration
+      </button>
+      <output aria-label="Saved configuration">{saved}</output>
+    </>
+  );
+}
+
+describe("forecast classifier form", () => {
+  it("switches a populated standard router to Capability without saving hidden pools or their overrides", () => {
+    renderWithProviders(
+      <Form
+        initialValue={{
+          classifier_type: "llm",
+          classifier_llm_config: { model: "judge", timeout_ms: 20000, classification_rubric: "agentic" },
+          adaptive: true,
+          plan_mode_min_tier: "MEDIUM",
+          tiers: {
+            SIMPLE: ["efficient", "second-efficient"],
+            MEDIUM: ["leftover-medium"],
+            COMPLEX: ["leftover-complex"],
+            REASONING: ["capable"],
+          },
+          tier_model_params: {
+            SIMPLE: { efficient: { reasoning_effort: "low", speed: "fast", max_tokens: 1024 } },
+            MEDIUM: { "leftover-medium": { speed: "fast" } },
+            COMPLEX: { "leftover-complex": { max_tokens: 4096 } },
+            REASONING: { capable: { reasoning_effort: "high" } },
+          },
+        }}
+      />,
+    );
+    fireEvent.click(screen.getByRole("tab", { name: "Capability" }));
+    fireEvent.change(screen.getByLabelText("Solve probability threshold"), { target: { value: "0.7" } });
+    expect(screen.getByRole("button", { name: "Save configuration" })).toBeEnabled();
+    fireEvent.click(screen.getByRole("button", { name: "Save configuration" }));
+    const output = screen.getByRole("status", { name: "Saved configuration" });
+    expect(output).toHaveTextContent('"classifier_type":"capability"');
+    expect(output).toHaveTextContent('"SIMPLE":["efficient","second-efficient"]');
+    expect(output).toHaveTextContent('"REASONING":["capable"]');
+    expect(output).toHaveTextContent('"reasoning_effort":"low","speed":"fast","max_tokens":1024');
+    expect(output).toHaveTextContent('"reasoning_effort":"high"');
+    expect(output).toHaveTextContent('"adaptive":true');
+    expect(output).not.toHaveTextContent("leftover-medium");
+    expect(output).not.toHaveTextContent("leftover-complex");
+    expect(output).not.toHaveTextContent('"plan_mode_min_tier"');
+  });
+
+  it.each(["capability", "llm_v2"] as const)(
+    "carries non-default solver assignments when switching away from %s",
+    (source) => {
+      const pair = { efficient_tier: "MEDIUM", capable_tier: "COMPLEX" };
+      const previous: ComplexityRouterConfigValue = {
+        ...(source === "capability" ? initial : fuseInitial),
+        tiers: { SIMPLE: [], MEDIUM: ["efficient"], COMPLEX: ["capable"], REASONING: [] },
+        capability_classifier_config:
+          source === "capability" ? { ...initial.capability_classifier_config!, ...pair } : undefined,
+        llm_v2_config: source === "llm_v2" ? { ...fuseInitial.llm_v2_config!, ...pair } : undefined,
+        plan_mode_min_tier: "COMPLEX",
+        tier_model_params: { MEDIUM: { efficient: { max_tokens: 128 } }, COMPLEX: { capable: { speed: "fast" } } },
+      };
+      renderWithProviders(<Form initialValue={previous} />);
+      fireEvent.click(screen.getByRole("tab", { name: source === "capability" ? "Fuse v2" : "Capability" }));
+      if (source === "capability") {
+        fireEvent.change(screen.getByLabelText("Efficient solver profile"), { target: { value: "Small solver" } });
+        fireEvent.change(screen.getByLabelText("Capable solver profile"), { target: { value: "Large solver" } });
+        fireEvent.change(screen.getByLabelText("Harness and budget"), { target: { value: "One attempt" } });
+        fireEvent.change(screen.getByLabelText("Maximum quality gap"), { target: { value: "0.05" } });
+      } else {
+        fireEvent.change(screen.getByLabelText("Solve probability threshold"), { target: { value: "0.7" } });
+      }
+      expect(screen.getByRole("button", { name: "Save configuration" })).toBeEnabled();
+      fireEvent.click(screen.getByRole("button", { name: "Save configuration" }));
+      const output = screen.getByRole("status", { name: "Saved configuration" });
+      expect(output).toHaveTextContent('"efficient_tier":"MEDIUM","capable_tier":"COMPLEX"');
+      expect(output).toHaveTextContent('"tiers":{"MEDIUM":["efficient"],"COMPLEX":["capable"]}');
+      expect(output).toHaveTextContent('"plan_mode_min_tier":"COMPLEX"');
+      expect(output).toHaveTextContent('"max_tokens":128');
+      expect(output).toHaveTextContent('"speed":"fast"');
+    },
+  );
+
+  it("keeps decimal and negative numbers when entered one character at a time", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<Form />);
+    const threshold = screen.getByLabelText("Solve probability threshold");
+    await user.clear(threshold);
+    await user.type(threshold, "0.65");
+    expect(threshold).toHaveValue(0.65);
+    await user.click(screen.getByRole("button", { name: "Classifier options" }));
+    await user.click(screen.getByRole("switch", { name: "Use fitted calibration" }));
+    await user.type(screen.getByLabelText("Efficient intercept"), "-0.3");
+    expect(screen.getByLabelText("Efficient intercept")).toHaveValue(-0.3);
+  });
+
+  it.each([
+    ["capability", "LLM Classifier"],
+    ["capability", "Heuristic first"],
+    ["capability", "Hybrid"],
+    ["llm_v2", "LLM Classifier"],
+    ["llm_v2", "Heuristic first"],
+    ["llm_v2", "Hybrid"],
+  ] as const)("restores the current rubric when switching %s through Complexity to %s", async (source, target) => {
+    const user = userEvent.setup();
+    renderWithProviders(<Form initialValue={source === "capability" ? initial : fuseInitial} />);
+    fireEvent.click(screen.getByRole("tab", { name: "Complexity" }));
+    fireEvent.click(screen.getByRole("radio", { name: new RegExp(`^${target}`) }));
+    await user.click(screen.getByRole("combobox", { name: "Classifier Model" }));
+    await user.click(screen.getByRole("option", { name: "judge", exact: true }));
+    fireEvent.click(screen.getByRole("button", { name: "Save configuration" }));
+    const output = screen.getByRole("status", { name: "Saved configuration" });
+    expect(output).toHaveTextContent('"classification_rubric":"agentic"');
+    expect(output).toHaveTextContent('"model":"judge"');
+    expect(output).toHaveTextContent('"timeout_ms":3000');
+    expect(output).not.toHaveTextContent('"capability_classifier_config"');
+    expect(output).not.toHaveTextContent('"llm_v2_config"');
+  });
+
+  it("saves capability threshold edits together with fitted calibration", () => {
+    renderWithProviders(<Form />);
+    fireEvent.change(screen.getByLabelText("Solve probability threshold"), { target: { value: "0.6" } });
+    fireEvent.click(screen.getByRole("button", { name: "Classifier options" }));
+    fireEvent.click(screen.getByRole("switch", { name: "Use fitted calibration" }));
+    expect(screen.getByRole("button", { name: "Save configuration" })).toBeDisabled();
+    fireEvent.change(screen.getByLabelText("Calibration version"), { target: { value: "eval-a" } });
+    fireEvent.change(screen.getByLabelText("Efficient slope"), { target: { value: "1.2" } });
+    fireEvent.change(screen.getByLabelText("Efficient intercept"), { target: { value: "-0.3" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save configuration" }));
+    const output = screen.getByRole("status", { name: "Saved configuration" });
+    expect(output).toHaveTextContent('"base_threshold":0.6');
+    expect(output).toHaveTextContent('"calibration":{"version":"eval-a","slope":1.2,"intercept":-0.3}');
+    fireEvent.change(screen.getByLabelText("Solve probability threshold"), { target: { value: "" } });
+    expect(screen.getByRole("button", { name: "Save configuration" })).toBeDisabled();
+  });
+
+  it("switches to Fuse, requires solver context, and saves the filled fields", () => {
+    renderWithProviders(<Form />);
+    fireEvent.click(screen.getByRole("tab", { name: "Fuse v2" }));
+    expect(screen.queryByLabelText("Solve probability threshold")).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Save configuration" })).toBeDisabled();
+    fireEvent.change(screen.getByLabelText("Efficient solver profile"), {
+      target: { value: "Short reasoning budget" },
+    });
+    fireEvent.change(screen.getByLabelText("Capable solver profile"), { target: { value: "Larger reasoning budget" } });
+    fireEvent.change(screen.getByLabelText("Harness and budget"), {
+      target: { value: "Shell and test runner, one attempt" },
+    });
+    fireEvent.change(screen.getByLabelText("Maximum quality gap"), { target: { value: "0.05" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save configuration" }));
+    const output = screen.getByRole("status", { name: "Saved configuration" });
+    expect(output).toHaveTextContent('"classifier_type":"llm_v2"');
+    expect(output).toHaveTextContent('"efficient_profile":"Short reasoning budget"');
+    expect(output).toHaveTextContent('"capable_profile":"Larger reasoning budget"');
+    expect(output).toHaveTextContent('"harness":"Shell and test runner, one attempt"');
+    expect(output).toHaveTextContent('"max_quality_gap":0.05');
+    expect(output).toHaveTextContent('"adaptive":false');
+    expect(output).not.toHaveTextContent('"capability_classifier_config"');
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.tsx b/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.tsx
new file mode 100644
index 00000000000..b901a509435
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.tsx
@@ -0,0 +1,433 @@
+import React from "react";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+import { ChevronRight } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import { Switch } from "@/components/ui/switch";
+import { SearchSelect } from "@/components/shared/SearchSelect";
+import { MultiSelect } from "@/components/shared/MultiSelect";
+import {
+  type ComplexityRouterConfigValue,
+  type ClassificationFrequency,
+  classificationFrequency,
+  withClassificationFrequency,
+  DEFAULT_CLASSIFIER_TIMEOUT_MS,
+} from "./ComplexityRouterConfig";
+import {
+  forecastTierNames,
+  forecastModels,
+  getForecastConfigError,
+  newCapabilitySettings,
+  newFuseSettings,
+  type CapabilitySettings,
+  type FuseSettings,
+} from "./forecast_classifier_config";
+import ClassifierReasoningEffortSelect from "./ClassifierReasoningEffortSelect";
+import ClassifierCircuitBreakerConfig from "./ClassifierCircuitBreakerConfig";
+import ClassifierVisionConfig from "./ClassifierVisionConfig";
+import TierModelEffortRows from "./TierModelEffortRows";
+import { activeTierRows } from "./tier_rows";
+import { setTierModels } from "./tier_set_actions";
+import { tierRowLabel, setTierModelParam, setTierModelReasoningEffort } from "./complexity_router_tiers";
+
+interface Props {
+  value: ComplexityRouterConfigValue;
+  onChange: (value: ComplexityRouterConfigValue) => void;
+  modelOptions: { value: string; label: string }[];
+  effortOptionsByModel: Record<string, string[] | null | undefined>;
+}
+
+const NumberField = ({
+  label,
+  value,
+  onChange,
+  min,
+  max,
+  step = "any",
+  help,
+}: {
+  label: string;
+  value: number;
+  onChange: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number | "any";
+  help?: string;
+}) => {
+  const id = React.useId();
+  return (
+    <div className="space-y-1">
+      <Label htmlFor={id}>{label}</Label>
+      <Input
+        id={id}
+        type="number"
+        min={min}
+        max={max}
+        step={step}
+        value={Number.isFinite(value) ? value : ""}
+        onChange={(event) => onChange(event.target.value === "" ? Number.NaN : Number(event.target.value))}
+      />
+      {help && <p className="text-xs text-muted-foreground">{help}</p>}
+    </div>
+  );
+};
+
+export const ForecastSolverModels = ({
+  value,
+  onChange,
+  modelOptions,
+  effortOptionsByModel,
+  fastModeByModel,
+  additionalPoolsOnly = false,
+}: Props & { fastModeByModel: Record<string, boolean>; additionalPoolsOnly?: boolean }) => {
+  const id = React.useId();
+  const names = forecastTierNames(value);
+  const additionalRows =
+    value.classifier_type === "capability"
+      ? activeTierRows(value)
+          .filter((row) => !names.includes(row.id) && row.models.length > 0)
+          .map((row) => ({ tier: row.id, label: `${tierRowLabel(row, value.tier_labels)} routing pool` }))
+      : [];
+  const rows = additionalPoolsOnly
+    ? additionalRows
+    : names.map((tier, index) => ({ tier, label: index === 0 ? "Efficient solver" : "Capable solver" }));
+  if (rows.length === 0) return null;
+  return (
+    <div className="rounded-lg border p-4 space-y-4">
+      {rows.map(({ tier, label }) => {
+        const models = forecastModels(value.tiers, tier);
+        const setModels = (next: string[]) => onChange(setTierModels(value, tier, next));
+        return (
+          <div key={tier} className="space-y-2">
+            <Label htmlFor={`${id}-${tier}`} className="block text-sm font-semibold">
+              {label}
+            </Label>
+            {value.classifier_type === "llm_v2" ? (
+              <SearchSelect
+                options={modelOptions}
+                inputId={`${id}-${tier}`}
+                value={models[0] ?? ""}
+                aria-label={label}
+                placeholder={`Select ${label.toLowerCase()}`}
+                onValueChange={(model) => setModels(model ? [model] : [])}
+              />
+            ) : (
+              <MultiSelect
+                options={modelOptions}
+                id={`${id}-${tier}`}
+                value={models}
+                onValueChange={setModels}
+                placeholder={`Select ${label.toLowerCase()} models`}
+              />
+            )}
+            <TierModelEffortRows
+              tierLabel={label}
+              models={models}
+              effortOptionsByModel={Object.fromEntries(
+                Object.entries(effortOptionsByModel).map(([model, efforts]) => [model, efforts ?? []]),
+              )}
+              paramsByModel={value.tier_model_params?.[tier] ?? {}}
+              fastModeByModel={fastModeByModel}
+              onFastModeChange={(model, enabled) =>
+                onChange({
+                  ...value,
+                  tier_model_params: setTierModelParam(value.tier_model_params, tier, model, [
+                    "speed",
+                    enabled ? "fast" : undefined,
+                  ]),
+                })
+              }
+              onEffortChange={(model, effort) =>
+                onChange({
+                  ...value,
+                  tier_model_params: setTierModelReasoningEffort(value.tier_model_params, tier, model, effort),
+                })
+              }
+            />
+          </div>
+        );
+      })}
+      {!additionalPoolsOnly && (
+        <p className="text-sm text-muted-foreground">
+          Invalid forecasts and classifier failures route to the capable solver
+        </p>
+      )}
+    </div>
+  );
+};
+
+const CalibrationFields = ({
+  label,
+  value,
+  onChange,
+  bounded = false,
+}: {
+  label: string;
+  bounded?: boolean;
+  value: { slope: number; intercept: number };
+  onChange: (value: { slope: number; intercept: number }) => void;
+}) => (
+  <div className="grid gap-3 sm:grid-cols-2">
+    <NumberField
+      label={`${label} slope`}
+      value={value.slope}
+      min={0}
+      max={bounded ? 20 : undefined}
+      onChange={(slope) => onChange({ ...value, slope })}
+    />
+    <NumberField
+      label={`${label} intercept`}
+      value={value.intercept}
+      min={bounded ? -20 : undefined}
+      max={bounded ? 20 : undefined}
+      onChange={(intercept) => onChange({ ...value, intercept })}
+    />
+  </div>
+);
+
+const emptyCoefficients = () => ({ slope: Number.NaN, intercept: Number.NaN });
+
+const ForecastClassifierConfig = ({ value, onChange, modelOptions, effortOptionsByModel }: Props) => {
+  const id = React.useId();
+  const isCapability = value.classifier_type === "capability";
+  const capability = value.capability_classifier_config ?? newCapabilitySettings();
+  const fuse = value.llm_v2_config ?? newFuseSettings();
+  const config = isCapability ? capability : fuse;
+  const llm = value.classifier_llm_config ?? { model: "", timeout_ms: DEFAULT_CLASSIFIER_TIMEOUT_MS };
+  const updateCapability = (next: CapabilitySettings) => onChange({ ...value, capability_classifier_config: next });
+  const updateFuse = (next: FuseSettings) => onChange({ ...value, llm_v2_config: next });
+  const updateTransport = (patch: { max_output_tokens?: number; response_format?: "json_schema" | "json_object" }) =>
+    isCapability ? updateCapability({ ...capability, ...patch }) : updateFuse({ ...fuse, ...patch });
+  const setCalibrationVersion = (version: string) => {
+    if (isCapability && capability.calibration)
+      updateCapability({ ...capability, calibration: { ...capability.calibration, version } });
+    if (!isCapability && fuse.calibration) updateFuse({ ...fuse, calibration: { ...fuse.calibration, version } });
+  };
+  const error = getForecastConfigError(value);
+  return (
+    <div className="mt-4 space-y-4">
+      <p className="text-sm text-muted-foreground">
+        {isCapability
+          ? "Forecasts whether the efficient solver can complete the task using the bundled capability card"
+          : "Forecasts success for both solvers and selects efficient when the estimated quality gap is within your allowance"}
+      </p>
+      <div className="space-y-1">
+        <Label htmlFor={`${id}-judge`}>Judge model</Label>
+        <SearchSelect
+          inputId={`${id}-judge`}
+          aria-label="Judge model"
+          options={modelOptions}
+          value={llm.model}
+          placeholder="Select the judge model"
+          onValueChange={(model) => {
+            if (model === llm.model) return;
+            onChange({ ...value, classifier_llm_config: { ...llm, model: model ?? "", reasoning_effort: undefined } });
+          }}
+        />
+      </div>
+      {isCapability ? (
+        <>
+          <NumberField
+            label="Solve probability threshold"
+            value={capability.base_threshold}
+            min={0}
+            max={1}
+            help="Minimum estimated chance of whole-task success required to use the efficient solver"
+            onChange={(base_threshold) => updateCapability({ ...capability, base_threshold })}
+          />
+        </>
+      ) : (
+        <>
+          {(["efficient_profile", "capable_profile", "harness"] as const).map((field) => {
+            const label = {
+              efficient_profile: "Efficient solver profile",
+              capable_profile: "Capable solver profile",
+              harness: "Harness and budget",
+            }[field];
+            return (
+              <div key={field} className="space-y-1">
+                <Label htmlFor={`${id}-${field}`}>{label}</Label>
+                <Textarea
+                  id={`${id}-${field}`}
+                  value={fuse[field]}
+                  maxLength={4000}
+                  placeholder={
+                    field === "harness"
+                      ? "Tools, execution environment, verification, and budget available to each solver"
+                      : "Describe this solver's strengths, limitations, and settings"
+                  }
+                  onChange={(event) => updateFuse({ ...fuse, [field]: event.target.value })}
+                />
+              </div>
+            );
+          })}
+          <NumberField
+            label="Maximum quality gap"
+            value={fuse.max_quality_gap}
+            min={0}
+            max={1}
+            help="Allowed difference between capable and efficient success probabilities, from 0 to 1. This is an estimate, not a measured quality guarantee"
+            onChange={(max_quality_gap) => updateFuse({ ...fuse, max_quality_gap })}
+          />
+        </>
+      )}
+      <Collapsible className="rounded-lg border">
+        <CollapsibleTrigger className="group flex w-full items-center gap-2 px-4 py-3 text-left font-medium">
+          <ChevronRight className="size-4 transition-transform group-data-panel-open:rotate-90" />
+          Classifier options
+        </CollapsibleTrigger>
+        <CollapsibleContent className="space-y-4 px-4 pb-4">
+          <ClassifierReasoningEffortSelect
+            model={llm.model}
+            value={llm.reasoning_effort}
+            explicitlySupported={effortOptionsByModel[llm.model]}
+            onChange={(reasoning_effort) => onChange({ ...value, classifier_llm_config: { ...llm, reasoning_effort } })}
+          />
+          <NumberField
+            label="Timeout (ms)"
+            min={1}
+            step={1}
+            value={llm.timeout_ms}
+            help="Allow enough time for the judge to produce its forecast"
+            onChange={(timeout_ms) => onChange({ ...value, classifier_llm_config: { ...llm, timeout_ms } })}
+          />
+          <ClassifierCircuitBreakerConfig
+            value={llm}
+            onChange={(classifier_llm_config) => onChange({ ...value, classifier_llm_config })}
+          />
+          <ClassifierVisionConfig
+            value={llm}
+            onChange={(classifier_llm_config) => onChange({ ...value, classifier_llm_config })}
+          />
+          <div className="space-y-1">
+            <Label htmlFor={`${id}-frequency`}>How often to classify</Label>
+            <SearchSelect
+              inputId={`${id}-frequency`}
+              aria-label="How often to classify"
+              value={classificationFrequency(value)}
+              allowClear={false}
+              options={[
+                { value: "every_request", label: "Every request" },
+                { value: "user_turn", label: "Every new user message" },
+                { value: "session", label: "Once per session" },
+              ]}
+              onValueChange={(frequency) => {
+                if (frequency) onChange(withClassificationFrequency(value, frequency as ClassificationFrequency));
+              }}
+            />
+          </div>
+          {isCapability && (
+            <NumberField
+              label="Capability boundary step"
+              value={capability.threshold_step ?? 0}
+              min={0}
+              max={0.5}
+              help="Added once for uncertain or unmatched tasks and twice for unsupported tasks; the final threshold cannot exceed 1"
+              onChange={(threshold_step) => updateCapability({ ...capability, threshold_step })}
+            />
+          )}
+          <NumberField
+            label="Classifier output token limit"
+            min={1}
+            step={1}
+            value={config.max_output_tokens ?? (isCapability ? 4096 : 1024)}
+            onChange={(max_output_tokens) => updateTransport({ max_output_tokens })}
+          />
+          <div className="space-y-1">
+            <Label htmlFor={`${id}-format`}>Forecast response format</Label>
+            <SearchSelect
+              inputId={`${id}-format`}
+              aria-label="Forecast response format"
+              value={config.response_format ?? "json_schema"}
+              allowClear={false}
+              options={[
+                { value: "json_schema", label: "Strict JSON schema" },
+                { value: "json_object", label: "JSON object (for judges without strict schema support)" },
+              ]}
+              onValueChange={(response_format) => {
+                if (response_format === "json_schema" || response_format === "json_object")
+                  updateTransport({ response_format });
+              }}
+            />
+          </div>
+          <div className="space-y-3 rounded-md border p-3">
+            <Label>
+              <Switch
+                checked={Boolean(config.calibration)}
+                onCheckedChange={(enabled) =>
+                  isCapability
+                    ? updateCapability({
+                        ...capability,
+                        calibration: enabled ? { version: "", ...emptyCoefficients() } : undefined,
+                      })
+                    : updateFuse({
+                        ...fuse,
+                        calibration: enabled
+                          ? {
+                              version: "",
+                              prompt_version: "llm-v2-1",
+                              efficient: emptyCoefficients(),
+                              capable: emptyCoefficients(),
+                            }
+                          : undefined,
+                      })
+                }
+              />
+              Use fitted calibration
+            </Label>
+            <p className="text-xs text-muted-foreground">
+              Optional coefficients fitted for your judge, solvers, and harness. Leave off to use raw forecasts
+            </p>
+            {config.calibration && (
+              <div className="space-y-1">
+                <Label htmlFor={`${id}-version`}>Calibration version</Label>
+                <Input
+                  id={`${id}-version`}
+                  value={config.calibration.version}
+                  maxLength={isCapability ? 128 : 512}
+                  onChange={(event) => setCalibrationVersion(event.target.value)}
+                />
+              </div>
+            )}
+            {isCapability && capability.calibration && (
+              <CalibrationFields
+                label="Efficient"
+                bounded
+                value={capability.calibration}
+                onChange={(next) =>
+                  updateCapability({
+                    ...capability,
+                    calibration: { version: capability.calibration?.version ?? "", ...next },
+                  })
+                }
+              />
+            )}
+            {!isCapability &&
+              fuse.calibration &&
+              (["efficient", "capable"] as const).map((role) => (
+                <CalibrationFields
+                  key={role}
+                  label={role === "efficient" ? "Efficient" : "Capable"}
+                  value={fuse.calibration![role]}
+                  onChange={(next) => {
+                    if (fuse.calibration) updateFuse({ ...fuse, calibration: { ...fuse.calibration, [role]: next } });
+                  }}
+                />
+              ))}
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+      <p className="text-xs text-muted-foreground">
+        The classifier uses its bundled prompt and always falls back to the capable solver
+      </p>
+      {error && (
+        <p role="alert" className="text-sm text-destructive">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export default ForecastClassifierConfig;
diff --git a/ui/litellm-dashboard/src/components/add_model/PlanModeOverrideControls.tsx b/ui/litellm-dashboard/src/components/add_model/PlanModeOverrideControls.tsx
new file mode 100644
index 00000000000..83fd0c42d16
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/PlanModeOverrideControls.tsx
@@ -0,0 +1,44 @@
+import React from "react";
+import { Switch } from "@/components/ui/switch";
+import TierRowSelect from "./TierRowSelect";
+import type { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+
+const PlanModeOverrideControls: React.FC<{
+  value: ComplexityRouterConfigValue;
+  onChange: (value: ComplexityRouterConfigValue) => void;
+  planModeTierOptions: { value: string; label: string }[];
+}> = ({ value, onChange, planModeTierOptions }) => (
+  <>
+    <div className="flex items-center gap-2 mb-2">
+      <Switch
+        checked={value.plan_mode_min_tier !== undefined}
+        disabled={planModeTierOptions.length === 0}
+        onCheckedChange={(enabled) =>
+          onChange({
+            ...value,
+            plan_mode_min_tier: enabled ? planModeTierOptions.at(-1)?.value : undefined,
+          })
+        }
+        aria-label="Route plan-mode requests to a minimum tier"
+      />
+      <strong className="font-semibold">Route plan-mode requests to a minimum tier</strong>
+    </div>
+    <span className="block text-xs mb-3 text-muted-foreground">
+      Requests from coding agents in plan mode (Claude Code, GitHub Copilot) route to at least this tier. The classifier
+      still wins when it picks higher, and the override only lasts while plan mode is active.
+      {planModeTierOptions.length === 0 && " Add models to a tier to enable this."}
+    </span>
+    {value.plan_mode_min_tier !== undefined && (
+      <div style={{ maxWidth: 320 }}>
+        <TierRowSelect
+          label="Plan-mode minimum tier"
+          options={planModeTierOptions}
+          value={value.plan_mode_min_tier ?? null}
+          onValueChange={(tier) => onChange({ ...value, plan_mode_min_tier: tier })}
+        />
+      </div>
+    )}
+  </>
+);
+
+export default PlanModeOverrideControls;
diff --git a/ui/litellm-dashboard/src/components/add_model/RoutingOptions.tsx b/ui/litellm-dashboard/src/components/add_model/RoutingOptions.tsx
new file mode 100644
index 00000000000..be376a0dde5
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/RoutingOptions.tsx
@@ -0,0 +1,23 @@
+import React from "react";
+import { ChevronRight } from "lucide-react";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+
+interface RoutingOptionsProps {
+  forecast: boolean;
+  children: React.ReactNode;
+}
+
+const RoutingOptions = ({ forecast, children }: RoutingOptionsProps) =>
+  forecast ? (
+    <Collapsible className="rounded-lg border">
+      <CollapsibleTrigger className="group flex w-full items-center gap-2 px-4 py-3 text-left font-medium">
+        <ChevronRight className="size-4 transition-transform group-data-panel-open:rotate-90" />
+        Advanced routing options
+      </CollapsibleTrigger>
+      <CollapsibleContent className="space-y-4 px-4 pb-4">{children}</CollapsibleContent>
+    </Collapsible>
+  ) : (
+    <>{children}</>
+  );
+
+export default RoutingOptions;
diff --git a/ui/litellm-dashboard/src/components/add_model/TierModelEffortRows.tsx b/ui/litellm-dashboard/src/components/add_model/TierModelEffortRows.tsx
index 54afa28fb6e..11c5b23b6e8 100644
--- a/ui/litellm-dashboard/src/components/add_model/TierModelEffortRows.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/TierModelEffortRows.tsx
@@ -23,6 +23,12 @@ interface TierModelEffortRowsProps {
   onFastModeChange: (model: string, enabled: boolean) => void;
 }
 
+const canEditFastMode = (
+  model: string,
+  fastModeByModel: TierModelEffortRowsProps["fastModeByModel"],
+  paramsByModel: TierModelEffortRowsProps["paramsByModel"],
+): boolean => fastModeByModel?.[model] === true || paramsByModel?.[model]?.speed === "fast";
+
 export interface TierEffortRow {
   model: string;
   effort: ReasoningEffort | undefined;
@@ -49,7 +55,7 @@ export const tierEffortRows = ({
       const listed = effort !== undefined && !supported.includes(effort) ? [...supported, effort] : supported;
       return { model, effort, options: Array.from(new Set(listed)) };
     })
-    .filter(({ model, options }) => options.length > 0 || fastModeByModel?.[model] === true);
+    .filter(({ model, options }) => options.length > 0 || canEditFastMode(model, fastModeByModel, paramsByModel));
 
 const TierModelEffortRows: React.FC<TierModelEffortRowsProps> = (props) => {
   const { tierLabel, paramsByModel, onEffortChange, fastModeByModel, onFastModeChange } = props;
@@ -101,7 +107,7 @@ const TierModelEffortRows: React.FC<TierModelEffortRowsProps> = (props) => {
                 </SelectContent>
               </Select>
             )}
-            {fastModeByModel?.[model] === true && (
+            {canEditFastMode(model, fastModeByModel, paramsByModel) && (
               <SimpleTooltip content="Fast mode has higher pricing and requires an eligible provider account. Off removes this tier's speed override and inherits the request or provider default">
                 <label
                   className="flex items-center gap-2 text-xs"
diff --git a/ui/litellm-dashboard/src/components/add_model/TierRestrictions.tsx b/ui/litellm-dashboard/src/components/add_model/TierRestrictions.tsx
index bedf8b5a628..dfab6b108cf 100644
--- a/ui/litellm-dashboard/src/components/add_model/TierRestrictions.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/TierRestrictions.tsx
@@ -2,9 +2,17 @@ import React from "react";
 import { CUSTOM_TIER_RESTRICTIONS, CustomTierSet, TierRestriction } from "./tier_rows";
 
 export const restrictedBy = (
-  value: { custom_tier_set?: CustomTierSet },
+  value: { custom_tier_set?: CustomTierSet; classifier_type?: string },
   key: keyof typeof CUSTOM_TIER_RESTRICTIONS,
-): TierRestriction | undefined => (value.custom_tier_set ? CUSTOM_TIER_RESTRICTIONS[key] : undefined);
+): TierRestriction | undefined => {
+  if (value.custom_tier_set) return CUSTOM_TIER_RESTRICTIONS[key];
+  if (value.classifier_type === "llm_v2" && key === "adaptive")
+    return {
+      omit: ["adaptive", "adaptive_weights", "adaptive_eligible", "tier_distance_penalty"],
+      reason: "Fuse v2 uses its quality-gap decision directly; adaptive routing is unavailable",
+    };
+  return undefined;
+};
 
 export const Restricted: React.FC<{ by: TierRestriction | undefined; children: React.ReactNode }> = ({
   by,
diff --git a/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx b/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx
index 29c35da5e07..b98636c9c5c 100644
--- a/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx
@@ -167,6 +167,114 @@ describe("AddAutoRouterTab", () => {
     mockFetchAllModelDeployments.mockResolvedValue([]);
   });
 
+  it.each(["Capability", "Fuse v2"])(
+    "creates %s from its dedicated tab without complexity templates",
+    async (label) => {
+      const user = userEvent.setup();
+      mockFetchAvailableModels.mockResolvedValue([
+        { model_group: "efficient", mode: "chat" },
+        { model_group: "capable", mode: "chat" },
+        { model_group: "judge", mode: "chat" },
+      ]);
+      renderWithProviders(<Harness />);
+      await user.type(screen.getByLabelText("Auto Router Name"), "forecast-router");
+      await user.click(screen.getByRole("tab", { name: label, exact: true }));
+      expect(screen.getByLabelText("Auto Router Name")).toHaveValue("forecast-router");
+      expect(screen.queryByTestId("template-selector")).not.toBeInTheDocument();
+      expect(screen.queryByTestId("configure-automatically-button")).not.toBeInTheDocument();
+      expect(screen.queryByTestId("detailed-configuration-toggle")).not.toBeInTheDocument();
+      expect(screen.queryByText("Complexity Tier Configuration")).not.toBeInTheDocument();
+      expect(screen.queryByText("Advanced: Classification Method")).not.toBeInTheDocument();
+      expect(screen.queryByText("Advanced: Adaptive Routing")).not.toBeInTheDocument();
+      const capability = label === "Capability";
+      for (const [role, model] of [
+        ["Efficient", "efficient"],
+        ["Capable", "capable"],
+      ]) {
+        await user.click(
+          screen.getByRole("combobox", {
+            name: capability ? `Select ${role.toLowerCase()} solver models` : `${role} solver`,
+          }),
+        );
+        await user.click(await screen.findByRole("option", { name: model, exact: true }));
+        if (capability) await user.keyboard("{Escape}");
+      }
+      await user.click(screen.getByRole("combobox", { name: "Judge model" }));
+      await user.click(await screen.findByRole("option", { name: "judge", exact: true }));
+      expect(screen.getByRole("button", { name: "Add Auto Router" })).toBeDisabled();
+      if (capability) {
+        fireEvent.change(screen.getByLabelText("Solve probability threshold"), { target: { value: "0.7" } });
+      } else {
+        fireEvent.change(screen.getByLabelText("Efficient solver profile"), { target: { value: "Small solver" } });
+        fireEvent.change(screen.getByLabelText("Capable solver profile"), { target: { value: "Large solver" } });
+        fireEvent.change(screen.getByLabelText("Harness and budget"), { target: { value: "One attempt" } });
+        fireEvent.change(screen.getByLabelText("Maximum quality gap"), { target: { value: "0.05" } });
+      }
+      expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Add Auto Router" })).toBeEnabled();
+      await user.click(screen.getByRole("button", { name: "Advanced routing options" }));
+      if (capability) expect(screen.getByText("Advanced: Adaptive Routing")).toBeInTheDocument();
+      else expect(screen.queryByText("Advanced: Adaptive Routing")).not.toBeInTheDocument();
+      expect(screen.queryByText("Advanced: Classification Method")).not.toBeInTheDocument();
+      expect(screen.getByText("Advanced: Affinity")).toBeInTheDocument();
+      await user.click(screen.getByRole("button", { name: "Add Auto Router" }));
+      await waitFor(() => expect(handleAddAutoRouterSubmit).toHaveBeenCalledTimes(1));
+      expect(vi.mocked(handleAddAutoRouterSubmit).mock.calls[0][0].complexity_router_config).toMatchObject({
+        classifier_type: capability ? "capability" : "llm_v2",
+        tiers: { SIMPLE: ["efficient"], REASONING: ["capable"] },
+        classifier_llm_config: { model: "judge" },
+      });
+    },
+  );
+
+  it("restores the automatic/template/detail flow on the Complexity tab", async () => {
+    const user = userEvent.setup();
+    mockFetchAvailableModels.mockResolvedValue(ALL_FAMILY_MODELS);
+    renderWithProviders(<Harness />);
+    await screen.findByTestId("configure-automatically-button");
+    await user.click(screen.getByRole("tab", { name: "Capability", exact: true }));
+    expect(screen.queryByTestId("configure-automatically-button")).not.toBeInTheDocument();
+    await user.click(screen.getByRole("tab", { name: "Complexity", exact: true }));
+    expect(screen.getByTestId("configure-automatically-button")).toBeInTheDocument();
+    expect(screen.getByTestId("template-selector")).toBeInTheDocument();
+    expandDetailedConfiguration();
+    expect(screen.getByText("Complexity Tier Configuration")).toBeInTheDocument();
+    await user.click(screen.getByText("Advanced: Classification Method"));
+    expect(screen.queryByRole("radio", { name: /^Capability/ })).not.toBeInTheDocument();
+    expect(screen.queryByRole("radio", { name: /^Fuse v2/ })).not.toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: /^Heuristic \(default/ })).toBeChecked();
+  });
+
+  it.each(["Capability", "Fuse v2"])(
+    "retries failed model loading on %s without losing entered settings",
+    async (label) => {
+      const user = userEvent.setup();
+      mockFetchAvailableModels.mockRejectedValueOnce(new Error("Model list unavailable")).mockResolvedValue([
+        { model_group: "efficient", mode: "chat" },
+        { model_group: "capable", mode: "chat" },
+        { model_group: "judge", mode: "chat" },
+      ]);
+      renderWithProviders(<Harness />);
+      await user.click(screen.getByRole("tab", { name: label, exact: true }));
+      await user.type(screen.getByLabelText("Auto Router Name"), "forecast-retry");
+      const capability = label === "Capability";
+      const policyField = capability ? "Solve probability threshold" : "Efficient solver profile";
+      fireEvent.change(screen.getByLabelText(policyField), {
+        target: { value: capability ? "0.7" : "Small solver" },
+      });
+      expect(await screen.findByText("Could not load available models.")).toBeVisible();
+      expect(screen.queryByTestId("template-selector")).not.toBeInTheDocument();
+      await user.click(screen.getByRole("button", { name: "Retry", exact: true }));
+      await waitFor(() => expect(screen.queryByText("Could not load available models.")).not.toBeInTheDocument());
+      expect(screen.getByRole("tab", { name: label, exact: true })).toHaveAttribute("aria-selected", "true");
+      expect(screen.getByLabelText("Auto Router Name")).toHaveValue("forecast-retry");
+      expect(screen.getByLabelText(policyField)).toHaveValue(capability ? 0.7 : "Small solver");
+      await user.click(screen.getByRole("combobox", { name: "Judge model" }));
+      expect(await screen.findByRole("option", { name: "judge", exact: true })).toBeVisible();
+      expect(mockFetchAvailableModels).toHaveBeenCalledTimes(2);
+    },
+  );
+
   // Detailed Configuration starts collapsed so the modal opens onto just Name + Template; a caller
   // opts into the full tier/classifier form rather than always seeing it up front.
   it("keeps Detailed Configuration collapsed until a caller opens it", () => {
diff --git a/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.tsx b/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.tsx
index a1893b0a77d..126d9ba2311 100644
--- a/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.tsx
@@ -1,3 +1,5 @@
+import AutoRouterClassifierTabs from "./AutoRouterClassifierTabs";
+import { getForecastConfigError, isForecastClassifier } from "../add_model/forecast_classifier_config";
 import React, { useEffect, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { useWatch } from "react-hook-form";
@@ -138,7 +140,9 @@ export const getSubmitBlockedReason = (
     (config.custom_tier_set
       ? getCustomTierRowsError(config.custom_tier_set)
       : getTierLabelsError(config.tier_labels)) ??
-    getMissingTiersError(activeTierRows(config)) ??
+    (isForecastClassifier(config.classifier_type)
+      ? getForecastConfigError(config)
+      : getMissingTiersError(activeTierRows(config))) ??
     getPlanModeTierError(config.plan_mode_min_tier, activeTierRows(config)) ??
     getKeywordTierRulesError(keywordTierRules, activeTierRows(config)) ??
     getClassifierModelError(config) ??
@@ -401,6 +405,8 @@ const AddAutoRouterTab: React.FC<AddAutoRouterTabProps> = ({
     classificationMode: complexityRouterConfig.classification_mode,
     tierLabels: complexityRouterConfig.tier_labels,
     classifierType: complexityRouterConfig.classifier_type,
+    capabilityClassifierConfig: complexityRouterConfig.capability_classifier_config,
+    llmV2Config: complexityRouterConfig.llm_v2_config,
     classifierLlmConfig: complexityRouterConfig.classifier_llm_config,
     classifierContextWindowSize: complexityRouterConfig.classifier_context_window_size,
     classifierContextBudgetChars: complexityRouterConfig.classifier_context_budget_chars,
@@ -543,81 +549,138 @@ const AddAutoRouterTab: React.FC<AddAutoRouterTabProps> = ({
     setIsTestModalVisible(true);
   };
 
+  const configurationForm = (
+    <ComplexityRouterConfig
+      editingTiers={editingTiers}
+      onEditingTiersChange={setEditingTiers}
+      modelInfo={modelInfo}
+      value={complexityRouterConfig}
+      onChange={setComplexityRouterConfig}
+      customTechnicalKeywords={customTechnicalKeywords}
+      onCustomTechnicalKeywordsChange={setCustomTechnicalKeywords}
+      keywordTierRules={keywordTierRules}
+      onKeywordTierRulesChange={setKeywordTierRules}
+      keywordRulesError={getKeywordTierRulesError(keywordTierRules, activeTierRows(complexityRouterConfig))}
+      semanticMatchingEnabled={semanticMatchingEnabled}
+      onSemanticMatchingEnabledChange={setSemanticMatchingEnabled}
+      embeddingModel={embeddingModel}
+      onEmbeddingModelChange={setEmbeddingModel}
+      matchThreshold={matchThreshold}
+      onMatchThresholdChange={setMatchThreshold}
+      escalationKeywords={escalationKeywords}
+      onEscalationKeywordsChange={setEscalationKeywords}
+      autoRouterCompression={autoRouterCompression}
+      onAutoRouterCompressionChange={isMemberManaged ? undefined : setAutoRouterCompression}
+      showValidationErrors={showValidationErrors}
+    />
+  );
+  const forecast = isForecastClassifier(complexityRouterConfig.classifier_type);
+
   return (
     <TooltipProvider>
       <Card>
         <CardContent>
           <form onSubmit={form.handleSubmit(() => handleAutoRouterSubmit())} noValidate>
-            <FieldGroup>
-              <div>
-                <FormField
-                  control={form.control}
-                  name="auto_router_name"
-                  label={labelWithHint("Auto Router Name", "Unique name for this auto router configuration")}
-                >
-                  {({ ref, ...field }) => (
-                    <Input {...field} ref={ref} placeholder="e.g., smart_router, auto_router_1" />
-                  )}
-                </FormField>
-
-                {!automaticSetupLoading && automaticRouterConfig && (
-                  <div className="mt-5 flex flex-wrap items-center justify-between gap-3 rounded-lg border border-border bg-muted px-4 py-3">
-                    <div>
-                      <p className="text-sm font-medium text-foreground">Not sure where to start?</p>
-                      <p className="text-sm text-muted-foreground">Let us pick models for each complexity tier.</p>
-                    </div>
-                    <Button type="button" data-testid="configure-automatically-button" onClick={handleAutomaticSetup}>
-                      Configure automatically
-                    </Button>
-                  </div>
-                )}
-
-                <div className="mt-5">
-                  <label className="block text-sm font-medium text-foreground mb-2">Template</label>
-                  <Select
-                    items={templateItems}
-                    value={selectedPreset ?? null}
-                    onValueChange={(presetKey: string | null) => handlePresetChange(presetKey ?? undefined)}
-                  >
-                    <SelectTrigger data-testid="template-selector" className="w-full">
-                      <SelectValue placeholder="Choose a template or select Custom to define your own" />
-                    </SelectTrigger>
-                    <SelectContent>
-                      {sortedPresetOptions.map(({ preset, availability: presetState }) => {
-                        const disabledHint = presetDisabledHint(presetState);
-                        const hintClass = isPresetHintAlarming(presetState)
-                          ? "text-destructive"
-                          : "text-muted-foreground";
-                        const matchedHint =
-                          presetState.kind === "available" && presetState.viaDeployments
-                            ? "Matches your deployments"
-                            : null;
-
-                        return (
-                          <SelectItem
-                            key={preset.key}
-                            value={preset.key}
-                            label={preset.label}
-                            disabled={disabledHint !== null}
-                            title={disabledHint ?? preset.description}
+            <div className="mb-6">
+              <FormField
+                control={form.control}
+                name="auto_router_name"
+                label={labelWithHint("Auto Router Name", "Unique name for this auto router configuration")}
+              >
+                {({ ref, ...field }) => <Input {...field} ref={ref} placeholder="e.g., smart_router, auto_router_1" />}
+              </FormField>
+            </div>
+            <AutoRouterClassifierTabs
+              value={complexityRouterConfig}
+              onChange={(config) => {
+                setSelectedPreset(undefined);
+                setComplexityRouterConfig(config);
+              }}
+            >
+              <FieldGroup>
+                <div>
+                  {!forecast && (
+                    <>
+                      {!automaticSetupLoading && automaticRouterConfig && (
+                        <div className="mt-5 flex flex-wrap items-center justify-between gap-3 rounded-lg border border-border bg-muted px-4 py-3">
+                          <div>
+                            <p className="text-sm font-medium text-foreground">Not sure where to start?</p>
+                            <p className="text-sm text-muted-foreground">
+                              Let us pick models for each complexity tier.
+                            </p>
+                          </div>
+                          <Button
+                            type="button"
+                            data-testid="configure-automatically-button"
+                            onClick={handleAutomaticSetup}
                           >
-                            <div>
-                              <div className="font-medium">{preset.label}</div>
-                              <div className="text-xs text-muted-foreground">{preset.description}</div>
-                              {disabledHint && <div className={`text-xs mt-1 ${hintClass}`}>{disabledHint}</div>}
-                              {matchedHint && <div className="text-xs mt-1 text-success">{matchedHint}</div>}
-                            </div>
-                          </SelectItem>
-                        );
-                      })}
-                      <SelectItem value="custom" label="Custom Configuration">
-                        <div>
-                          <div className="font-medium">Custom Configuration</div>
-                          <div className="text-xs text-muted-foreground">Define your auto router from scratch</div>
+                            Configure automatically
+                          </Button>
                         </div>
-                      </SelectItem>
-                    </SelectContent>
-                  </Select>
+                      )}
+
+                      <div className="mt-5">
+                        <label className="block text-sm font-medium text-foreground mb-2">Template</label>
+                        <Select
+                          items={templateItems}
+                          value={selectedPreset ?? null}
+                          onValueChange={(presetKey: string | null) => handlePresetChange(presetKey ?? undefined)}
+                        >
+                          <SelectTrigger data-testid="template-selector" className="w-full">
+                            <SelectValue placeholder="Choose a template or select Custom to define your own" />
+                          </SelectTrigger>
+                          <SelectContent>
+                            {sortedPresetOptions.map(({ preset, availability: presetState }) => {
+                              const disabledHint = presetDisabledHint(presetState);
+                              const hintClass = isPresetHintAlarming(presetState)
+                                ? "text-destructive"
+                                : "text-muted-foreground";
+                              const matchedHint =
+                                presetState.kind === "available" && presetState.viaDeployments
+                                  ? "Matches your deployments"
+                                  : null;
+
+                              return (
+                                <SelectItem
+                                  key={preset.key}
+                                  value={preset.key}
+                                  label={preset.label}
+                                  disabled={disabledHint !== null}
+                                  title={disabledHint ?? preset.description}
+                                >
+                                  <div>
+                                    <div className="font-medium">{preset.label}</div>
+                                    <div className="text-xs text-muted-foreground">{preset.description}</div>
+                                    {disabledHint && <div className={`text-xs mt-1 ${hintClass}`}>{disabledHint}</div>}
+                                    {matchedHint && <div className="text-xs mt-1 text-success">{matchedHint}</div>}
+                                  </div>
+                                </SelectItem>
+                              );
+                            })}
+                            <SelectItem value="custom" label="Custom Configuration">
+                              <div>
+                                <div className="font-medium">Custom Configuration</div>
+                                <div className="text-xs text-muted-foreground">
+                                  Define your auto router from scratch
+                                </div>
+                              </div>
+                            </SelectItem>
+                          </SelectContent>
+                        </Select>
+                        {presetsPending && (
+                          <div className="text-xs mt-1 text-muted-foreground">Loading templates...</div>
+                        )}
+                        {presetsUnavailable && (
+                          <div className="text-xs mt-1 text-destructive">
+                            Could not load templates, so only Custom Configuration is shown.{" "}
+                            <button type="button" className="underline" onClick={() => void refetchPresets()}>
+                              Retry
+                            </button>
+                          </div>
+                        )}
+                      </div>
+                    </>
+                  )}
                   {modelsUnverifiable && (
                     <div className="text-xs mt-1 text-destructive">
                       Could not load available models.{" "}
@@ -626,163 +689,129 @@ const AddAutoRouterTab: React.FC<AddAutoRouterTabProps> = ({
                       </button>
                     </div>
                   )}
-                  {presetsPending && <div className="text-xs mt-1 text-muted-foreground">Loading templates...</div>}
-                  {presetsUnavailable && (
-                    <div className="text-xs mt-1 text-destructive">
-                      Could not load templates, so only Custom Configuration is shown.{" "}
-                      <button type="button" className="underline" onClick={() => void refetchPresets()}>
-                        Retry
-                      </button>
-                    </div>
-                  )}
                 </div>
-              </div>
 
-              {requiresTeamScope && (
-                <FormField
-                  control={form.control}
-                  name="team_id"
-                  label={labelWithHint(
-                    "Select Team",
-                    "Select the team this auto router belongs to. Only keys for this team will be able to call it.",
-                  )}
-                >
-                  {({ id, value, onChange }) => (
-                    <TeamDropdown
-                      id={id}
-                      value={value}
-                      onChange={onChange}
-                      filterTeam={(team) => canCreateAutoRouterForTeam(actor, team)}
-                    />
-                  )}
-                </FormField>
-              )}
-
-              <div className="border border-border rounded-lg">
-                <button
-                  type="button"
-                  onClick={() => setDetailsExpanded((expanded) => !expanded)}
-                  className="w-full flex flex-col gap-1 px-4 py-3 text-left hover:bg-muted"
-                  data-testid="detailed-configuration-toggle"
-                >
-                  <span className="flex items-center gap-2 font-medium text-foreground">
-                    {detailsExpanded ? (
-                      <ChevronDown className="size-3 text-muted-foreground" />
-                    ) : (
-                      <ChevronRight className="size-3 text-muted-foreground" />
+                {requiresTeamScope && (
+                  <FormField
+                    control={form.control}
+                    name="team_id"
+                    label={labelWithHint(
+                      "Select Team",
+                      "Select the team this auto router belongs to. Only keys for this team will be able to call it.",
                     )}
-                    Detailed Configuration
-                  </span>
-                  {!detailsExpanded && (
-                    <span className="text-xs text-muted-foreground line-clamp-2">
-                      {tierConfigSummary(complexityRouterConfig)}
-                    </span>
-                  )}
-                </button>
-                {detailsExpanded && (
-                  <div className="px-4 pb-4">
-                    <ComplexityRouterConfig
-                      editingTiers={editingTiers}
-                      onEditingTiersChange={setEditingTiers}
-                      modelInfo={modelInfo}
-                      value={complexityRouterConfig}
-                      onChange={setComplexityRouterConfig}
-                      customTechnicalKeywords={customTechnicalKeywords}
-                      onCustomTechnicalKeywordsChange={setCustomTechnicalKeywords}
-                      keywordTierRules={keywordTierRules}
-                      onKeywordTierRulesChange={setKeywordTierRules}
-                      keywordRulesError={getKeywordTierRulesError(
-                        keywordTierRules,
-                        activeTierRows(complexityRouterConfig),
+                  >
+                    {({ id, value, onChange }) => (
+                      <TeamDropdown
+                        id={id}
+                        value={value}
+                        onChange={onChange}
+                        filterTeam={(team) => canCreateAutoRouterForTeam(actor, team)}
+                      />
+                    )}
+                  </FormField>
+                )}
+
+                {forecast ? (
+                  configurationForm
+                ) : (
+                  <div className="border border-border rounded-lg">
+                    <button
+                      type="button"
+                      onClick={() => setDetailsExpanded((expanded) => !expanded)}
+                      className="w-full flex flex-col gap-1 px-4 py-3 text-left hover:bg-muted"
+                      data-testid="detailed-configuration-toggle"
+                    >
+                      <span className="flex items-center gap-2 font-medium text-foreground">
+                        {detailsExpanded ? (
+                          <ChevronDown className="size-3 text-muted-foreground" />
+                        ) : (
+                          <ChevronRight className="size-3 text-muted-foreground" />
+                        )}
+                        Detailed Configuration
+                      </span>
+                      {!detailsExpanded && (
+                        <span className="text-xs text-muted-foreground line-clamp-2">
+                          {tierConfigSummary(complexityRouterConfig)}
+                        </span>
                       )}
-                      semanticMatchingEnabled={semanticMatchingEnabled}
-                      onSemanticMatchingEnabledChange={setSemanticMatchingEnabled}
-                      embeddingModel={embeddingModel}
-                      onEmbeddingModelChange={setEmbeddingModel}
-                      matchThreshold={matchThreshold}
-                      onMatchThresholdChange={setMatchThreshold}
-                      escalationKeywords={escalationKeywords}
-                      onEscalationKeywordsChange={setEscalationKeywords}
-                      autoRouterCompression={autoRouterCompression}
-                      onAutoRouterCompressionChange={isMemberManaged ? undefined : setAutoRouterCompression}
-                      showValidationErrors={showValidationErrors}
-                    />
+                    </button>
+                    {detailsExpanded && <div className="px-4 pb-4">{configurationForm}</div>}
                   </div>
                 )}
-              </div>
 
-              {isAdmin && (
-                <FormField
-                  control={form.control}
-                  name="model_access_group"
-                  label={labelWithHint(
-                    "Model Access Group",
-                    "Use model access groups to control who can access this auto router",
-                  )}
-                >
-                  {({ id, value, onChange, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy }) => (
-                    <AccessGroupTagsCombobox
-                      id={id}
-                      value={value}
-                      onChange={onChange}
-                      options={modelAccessGroups}
-                      ariaInvalid={ariaInvalid}
-                      ariaDescribedBy={ariaDescribedBy}
+                {isAdmin && (
+                  <FormField
+                    control={form.control}
+                    name="model_access_group"
+                    label={labelWithHint(
+                      "Model Access Group",
+                      "Use model access groups to control who can access this auto router",
+                    )}
+                  >
+                    {({ id, value, onChange, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy }) => (
+                      <AccessGroupTagsCombobox
+                        id={id}
+                        value={value}
+                        onChange={onChange}
+                        options={modelAccessGroups}
+                        ariaInvalid={ariaInvalid}
+                        ariaDescribedBy={ariaDescribedBy}
+                      />
+                    )}
+                  </FormField>
+                )}
+
+                <div className="flex justify-between items-center">
+                  <Tooltip>
+                    <TooltipTrigger
+                      render={
+                        <a
+                          href="https://github.com/BerriAI/litellm/issues"
+                          className="text-sm text-primary underline-offset-4 hover:underline"
+                        >
+                          Need Help?
+                        </a>
+                      }
                     />
-                  )}
-                </FormField>
-              )}
-
-              <div className="flex justify-between items-center">
-                <Tooltip>
-                  <TooltipTrigger
-                    render={
-                      <a
-                        href="https://github.com/BerriAI/litellm/issues"
-                        className="text-sm text-primary underline-offset-4 hover:underline"
+                    <TooltipContent>Get help on our github</TooltipContent>
+                  </Tooltip>
+                  <div className="flex gap-2">
+                    <BlockedReasonTooltip reason={submitBlockedReason}>
+                      <Button
+                        type="button"
+                        variant="outline"
+                        data-testid="auto-router-test-routing-btn"
+                        disabled={submitBlockedReason !== null || isSubmitting}
+                        onClick={() => setIsRoutingTestVisible(true)}
                       >
-                        Need Help?
-                      </a>
-                    }
-                  />
-                  <TooltipContent>Get help on our github</TooltipContent>
-                </Tooltip>
-                <div className="flex gap-2">
-                  <BlockedReasonTooltip reason={submitBlockedReason}>
+                        Test Routing
+                      </Button>
+                    </BlockedReasonTooltip>
                     <Button
                       type="button"
                       variant="outline"
-                      data-testid="auto-router-test-routing-btn"
-                      disabled={submitBlockedReason !== null || isSubmitting}
-                      onClick={() => setIsRoutingTestVisible(true)}
+                      data-testid="auto-router-test-connect-btn"
+                      onClick={handleTestConnection}
+                      disabled={isTestingConnection}
                     >
-                      Test Routing
+                      {isTestingConnection && <UiLoadingSpinner className="size-4" />}
+                      Test Connection
                     </Button>
-                  </BlockedReasonTooltip>
-                  <Button
-                    type="button"
-                    variant="outline"
-                    data-testid="auto-router-test-connect-btn"
-                    onClick={handleTestConnection}
-                    disabled={isTestingConnection}
-                  >
-                    {isTestingConnection && <UiLoadingSpinner className="size-4" />}
-                    Test Connection
-                  </Button>
-                  <BlockedReasonTooltip reason={submitBlockedReason}>
-                    <Button
-                      type="button"
-                      disabled={submitBlockedReason !== null || isSubmitting}
-                      onClick={() => {
-                        void handleAutoRouterSubmit();
-                      }}
-                    >
-                      Add Auto Router
-                    </Button>
-                  </BlockedReasonTooltip>
+                    <BlockedReasonTooltip reason={submitBlockedReason}>
+                      <Button
+                        type="button"
+                        disabled={submitBlockedReason !== null || isSubmitting}
+                        onClick={() => {
+                          void handleAutoRouterSubmit();
+                        }}
+                      >
+                        Add Auto Router
+                      </Button>
+                    </BlockedReasonTooltip>
+                  </div>
                 </div>
-              </div>
-            </FieldGroup>
+              </FieldGroup>
+            </AutoRouterClassifierTabs>
           </form>
         </CardContent>
       </Card>
diff --git a/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts b/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts
index 822af77e0db..d16be537ce6 100644
--- a/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts
+++ b/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts
@@ -1,3 +1,9 @@
+import {
+  isForecastClassifier,
+  withoutForecastPromptOverrides,
+  type CapabilitySettings,
+  type FuseSettings,
+} from "./forecast_classifier_config";
 import type { ModelGroup } from "../llm_calls/fetch_models";
 import { KeywordTierRule } from "./KeywordTierRules";
 import {
@@ -126,6 +132,48 @@ const scorerKnobPayload = ({
       };
 };
 
+export interface StoredComplexityRouterConfig {
+  tiers?: Partial<Record<keyof ComplexityTiers, unknown>>;
+  enable_non_reasoning_tier?: boolean;
+  tier_model_configs?: unknown;
+  default_model?: string | null;
+  plan_mode_min_tier?: unknown;
+  classification_prompt?: unknown;
+  classification_examples?: unknown;
+  heuristic_first_max_tier?: unknown;
+  hybrid_boundary_margin?: unknown;
+  tier_labels?: unknown;
+  classifier_type?: ClassifierType;
+  capability_classifier_config?: unknown;
+  llm_v2_config?: unknown;
+  classifier_llm_config?: ClassifierLLMConfig;
+  classifier_context_window_size?: unknown;
+  classifier_context_budget_chars?: unknown;
+  classifier_context_include_assistant_turns?: unknown;
+  classifier_fallback?: unknown;
+  classification_mode?: unknown;
+  tier_boundaries?: unknown;
+  token_thresholds?: unknown;
+  dimension_weights?: unknown;
+  custom_dimensions?: unknown;
+  reasoning_override_min_score?: unknown;
+  session_affinity?: unknown;
+  session_affinity_ttl_seconds?: unknown;
+  modality_routing?: unknown;
+  modality_pin_override?: unknown;
+  deployment_affinity?: unknown;
+  adaptive?: boolean;
+  adaptive_weights?: AdaptiveRouterWeights;
+  tier_distance_penalty?: number;
+  adaptive_eligible?: AdaptiveEligible;
+  return_raw_model_name?: boolean;
+  enable_context_window_escalation?: unknown;
+  context_window_escalation_buffer?: unknown;
+  stall_escalation_enabled?: unknown;
+  stall_escalation_window?: unknown;
+  stall_escalation_repeat_threshold?: unknown;
+}
+
 export interface BuildComplexityRouterConfigParams {
   tiers: ComplexityTiers;
   enableNonReasoningTier?: boolean;
@@ -134,6 +182,8 @@ export interface BuildComplexityRouterConfigParams {
   planModeMinTier: string | undefined;
   tierLabels: ComplexityTierLabels | undefined;
   classifierType: ClassifierType;
+  capabilityClassifierConfig?: CapabilitySettings;
+  llmV2Config?: FuseSettings;
   classifierLlmConfig: ClassifierLLMConfigWire | undefined;
   classifierContextWindowSize: number | undefined;
   classifierContextBudgetChars: number | undefined;
@@ -198,6 +248,8 @@ export interface ComplexityRouterConfigPayload {
   plan_mode_min_tier?: string;
   tier_labels?: ComplexityTierLabels;
   classifier_type: ClassifierType;
+  capability_classifier_config?: CapabilitySettings;
+  llm_v2_config?: FuseSettings;
   classifier_llm_config?: ClassifierLLMConfig;
   classifier_context_window_size?: number;
   classifier_context_budget_chars?: number;
@@ -468,31 +520,34 @@ const classifierWireFields = (
     | "classifierContextBudgetChars"
     | "classifierContextIncludeAssistantTurns"
   >,
-): Partial<ComplexityRouterConfigPayload> => ({
-  ...(usesLlmClassifier(effectiveType) &&
-    classifierLlmConfig && {
-      classifier_llm_config:
-        effectiveType === "capability" ? classifierLlmConfig : normalizeClassifierLlmConfig(classifierLlmConfig),
-    }),
-  ...(usesLlmClassifier(effectiveType) &&
-    classifierFallback !== undefined && { classifier_fallback: classifierFallback }),
-  ...(effectiveType === "heuristic_first" &&
-    heuristicFirstMaxTier?.trim() && { heuristic_first_max_tier: heuristicFirstMaxTier }),
-  ...(effectiveType === "hybrid" &&
-    hybridBoundaryMargin !== undefined && { hybrid_boundary_margin: hybridBoundaryMargin }),
-  ...(usesLlmClassifier(effectiveType) &&
-    classifierContextWindowSize !== undefined && {
-      classifier_context_window_size: classifierContextWindowSize,
-    }),
-  ...(usesLlmClassifier(effectiveType) &&
-    classifierContextBudgetChars !== undefined && {
-      classifier_context_budget_chars: classifierContextBudgetChars,
-    }),
-  ...(usesLlmClassifier(effectiveType) &&
-    classifierContextIncludeAssistantTurns !== undefined && {
-      classifier_context_include_assistant_turns: classifierContextIncludeAssistantTurns,
-    }),
-});
+): Partial<ComplexityRouterConfigPayload> => {
+  const supportsFallback = usesLlmClassifier(effectiveType) && !isForecastClassifier(effectiveType);
+  return {
+    ...(usesLlmClassifier(effectiveType) &&
+      classifierLlmConfig && {
+        classifier_llm_config: isForecastClassifier(effectiveType)
+          ? withoutForecastPromptOverrides(classifierLlmConfig)
+          : normalizeClassifierLlmConfig(classifierLlmConfig),
+      }),
+    ...(supportsFallback && classifierFallback !== undefined && { classifier_fallback: classifierFallback }),
+    ...(effectiveType === "heuristic_first" &&
+      heuristicFirstMaxTier?.trim() && { heuristic_first_max_tier: heuristicFirstMaxTier }),
+    ...(effectiveType === "hybrid" &&
+      hybridBoundaryMargin !== undefined && { hybrid_boundary_margin: hybridBoundaryMargin }),
+    ...(usesLlmClassifier(effectiveType) &&
+      classifierContextWindowSize !== undefined && {
+        classifier_context_window_size: classifierContextWindowSize,
+      }),
+    ...(usesLlmClassifier(effectiveType) &&
+      classifierContextBudgetChars !== undefined && {
+        classifier_context_budget_chars: classifierContextBudgetChars,
+      }),
+    ...(usesLlmClassifier(effectiveType) &&
+      classifierContextIncludeAssistantTurns !== undefined && {
+        classifier_context_include_assistant_turns: classifierContextIncludeAssistantTurns,
+      }),
+  };
+};
 
 export const buildComplexityRouterConfig = ({
   tiers,
@@ -502,6 +557,8 @@ export const buildComplexityRouterConfig = ({
   planModeMinTier,
   tierLabels,
   classifierType,
+  capabilityClassifierConfig,
+  llmV2Config,
   classifierLlmConfig,
   classifierContextWindowSize,
   classifierContextBudgetChars,
@@ -572,8 +629,12 @@ export const buildComplexityRouterConfig = ({
   // the form never rewrote. The UI gates the same controls on this, not on the raw value.
   const effectiveType: ClassifierType = customTierSet ? "llm" : classifierType;
 
+  const supportsOpeningPrompt =
+    !customTierSet && !isForecastClassifier(effectiveType) && usesLlmClassifier(effectiveType);
   const payload: ComplexityRouterConfigPayload = {
-    tiers,
+    tiers: isForecastClassifier(effectiveType)
+      ? Object.fromEntries(Object.entries(tiers).filter(([, models]) => models.length > 0))
+      : tiers,
     // The backend rejects the flag beside a custom tier set.
     ...(!customTierSet && enableNonReasoningTier && { enable_non_reasoning_tier: true }),
     ...(serializedTierModelConfigs && { tier_model_configs: serializedTierModelConfigs }),
@@ -582,10 +643,12 @@ export const buildComplexityRouterConfig = ({
     ...(cleanedTierLabels && { tier_labels: cleanedTierLabels }),
     classifier_type: classifierType,
     ...classifierWireFields(effectiveType, classifierInputs),
+    ...(effectiveType === "capability" &&
+      capabilityClassifierConfig && { capability_classifier_config: capabilityClassifierConfig }),
+    ...(effectiveType === "llm_v2" && { llm_v2_config: llmV2Config, adaptive: false }),
     // A built-in router's opening instructions. Suppressed beside a legacy whole-prompt override,
     // which the backend rejects as a second override of the same prompt.
-    ...(!customTierSet &&
-      usesLlmClassifier(effectiveType) &&
+    ...(supportsOpeningPrompt &&
       !classifierLlmConfig?.system_prompt?.trim() && {
         ...(classificationPrompt?.trim() && { classification_prompt: classificationPrompt.trim() }),
         ...(classificationExamples?.trim() && { classification_examples: classificationExamples.trim() }),
@@ -612,12 +675,13 @@ export const buildComplexityRouterConfig = ({
       embedding_model: embeddingModel,
       match_threshold: matchThreshold,
     }),
-    ...(adaptive && {
-      adaptive: true,
-      adaptive_weights: adaptiveWeights,
-      ...(adaptiveEligible === "all" && { tier_distance_penalty: tierDistancePenalty }),
-      adaptive_eligible: adaptiveEligible,
-    }),
+    ...(adaptive &&
+      effectiveType !== "llm_v2" && {
+        adaptive: true,
+        adaptive_weights: adaptiveWeights,
+        ...(adaptiveEligible === "all" && { tier_distance_penalty: tierDistancePenalty }),
+        adaptive_eligible: adaptiveEligible,
+      }),
     ...(returnRawModelName && { return_raw_model_name: true }),
     ...(enableContextWindowEscalation !== undefined && {
       enable_context_window_escalation: enableContextWindowEscalation,
diff --git a/ui/litellm-dashboard/src/components/add_model/classifier_type_transition.test.ts b/ui/litellm-dashboard/src/components/add_model/classifier_type_transition.test.ts
new file mode 100644
index 00000000000..e3fe00d2bc8
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/classifier_type_transition.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import type { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+import { transitionClassifierType } from "./classifier_type_transition";
+
+const standard: ComplexityRouterConfigValue = {
+  classifier_type: "llm",
+  classifier_llm_config: { model: "judge", timeout_ms: 20000, classification_rubric: "business" },
+  classifier_context_window_size: 8,
+  classifier_context_budget_chars: 16000,
+  classifier_context_include_assistant_turns: true,
+  classifier_fallback: "default_model",
+  tiers: { SIMPLE: ["efficient"], MEDIUM: ["middle"], COMPLEX: [], REASONING: ["capable"] },
+};
+
+describe("transitionClassifierType", () => {
+  it.each(["heuristic_first", "hybrid"] as const)("keeps existing LLM settings when switching to %s", (target) => {
+    const result = transitionClassifierType(standard, target);
+    const expectedSettings = {
+      classifier_type: target,
+      classifier_llm_config: standard.classifier_llm_config,
+      classifier_context_window_size: 8,
+      classifier_context_budget_chars: 16000,
+      classifier_context_include_assistant_turns: true,
+      classifier_fallback: "default_model",
+    };
+    expect(result).toMatchObject(expectedSettings);
+  });
+
+  it.each(["capability", "llm_v2"] as const)("requires explicit policy input for a new %s classifier", (target) => {
+    const result = transitionClassifierType(standard, target);
+    expect(result.classifier_llm_config).toEqual({ model: "judge", timeout_ms: 20000 });
+    expect(result.classifier_fallback).toBeUndefined();
+    if (target === "capability") {
+      expect(result.capability_classifier_config?.base_threshold).toBeNaN();
+    } else {
+      expect(result.llm_v2_config).toMatchObject({ efficient_profile: "", capable_profile: "", harness: "" });
+      expect(result.llm_v2_config?.max_quality_gap).toBeNaN();
+    }
+    expect(standard.tiers.MEDIUM).toEqual(["middle"]);
+    expect(standard.classifier_llm_config?.classification_rubric).toBe("business");
+  });
+
+  it.each([
+    ["capability", "llm"],
+    ["capability", "heuristic_first"],
+    ["capability", "hybrid"],
+    ["llm_v2", "llm"],
+    ["llm_v2", "heuristic_first"],
+    ["llm_v2", "hybrid"],
+  ] as const)("restores the complexity rubric from %s to %s while preserving the judge", (source, target) => {
+    const forecast = transitionClassifierType(standard, source);
+    const result = transitionClassifierType(forecast, target);
+    expect(result.classifier_llm_config).toEqual({
+      model: "judge",
+      timeout_ms: 20000,
+      classification_rubric: "agentic",
+    });
+    expect(result.capability_classifier_config).toBeUndefined();
+    expect(result.llm_v2_config).toBeUndefined();
+  });
+
+  it("clears the inactive non-reasoning pool and plan floor when switching to local classification", () => {
+    const initial: ComplexityRouterConfigValue = {
+      ...standard,
+      tiers: { ...standard.tiers, NON_REASONING: ["chat"] },
+      enable_non_reasoning_tier: true,
+      plan_mode_min_tier: "NON_REASONING",
+    };
+    const result = transitionClassifierType(initial, "heuristic");
+    expect(result.classifier_llm_config).toBeUndefined();
+    expect(result.classifier_context_window_size).toBeUndefined();
+    expect(result.classifier_context_budget_chars).toBeUndefined();
+    expect(result.classifier_context_include_assistant_turns).toBeUndefined();
+    expect(result.classifier_fallback).toBeUndefined();
+    expect(result.tiers.NON_REASONING).toBeUndefined();
+    expect(result.enable_non_reasoning_tier).toBeUndefined();
+    expect(result.plan_mode_min_tier).toBeUndefined();
+    expect(result.tiers.SIMPLE).toEqual(["efficient"]);
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/add_model/classifier_type_transition.ts b/ui/litellm-dashboard/src/components/add_model/classifier_type_transition.ts
new file mode 100644
index 00000000000..df87e2854e3
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/classifier_type_transition.ts
@@ -0,0 +1,50 @@
+import {
+  type ClassifierType,
+  type ComplexityRouterConfigValue,
+  DEFAULT_CLASSIFIER_CONTEXT_BUDGET_CHARS,
+  DEFAULT_CLASSIFIER_CONTEXT_WINDOW_SIZE,
+  DEFAULT_CLASSIFIER_TIMEOUT_MS,
+  DEFAULT_HEURISTIC_FIRST_MAX_TIER,
+  DEFAULT_HYBRID_BOUNDARY_MARGIN,
+  NEW_CLASSIFIER_CLASSIFICATION_RUBRIC,
+  usesLlmClassifier,
+} from "./ComplexityRouterConfig";
+import { isForecastClassifier, prepareForecastClassifier } from "./forecast_classifier_config";
+import { nonReasoningTierFields } from "./nonReasoningTierFields";
+
+export const transitionClassifierType = (
+  value: ComplexityRouterConfigValue,
+  classifierType: ClassifierType,
+): ComplexityRouterConfigValue => {
+  const startsLlmRubric =
+    !value.classifier_llm_config ||
+    (isForecastClassifier(value.classifier_type) && !isForecastClassifier(classifierType));
+  const judgeConfig = value.classifier_llm_config ?? { model: "", timeout_ms: DEFAULT_CLASSIFIER_TIMEOUT_MS };
+  const nextValue: ComplexityRouterConfigValue = {
+    ...value,
+    classifier_llm_config: usesLlmClassifier(classifierType)
+      ? {
+          ...judgeConfig,
+          ...(startsLlmRubric && { classification_rubric: NEW_CLASSIFIER_CLASSIFICATION_RUBRIC }),
+        }
+      : undefined,
+    classifier_context_window_size: usesLlmClassifier(classifierType)
+      ? value.classifier_context_window_size ?? DEFAULT_CLASSIFIER_CONTEXT_WINDOW_SIZE
+      : undefined,
+    classifier_context_budget_chars: usesLlmClassifier(classifierType)
+      ? value.classifier_context_budget_chars ?? DEFAULT_CLASSIFIER_CONTEXT_BUDGET_CHARS
+      : undefined,
+    classifier_context_include_assistant_turns: usesLlmClassifier(classifierType)
+      ? value.classifier_context_include_assistant_turns
+      : undefined,
+    classifier_fallback: usesLlmClassifier(classifierType) ? value.classifier_fallback : undefined,
+    heuristic_first_max_tier:
+      classifierType === "heuristic_first"
+        ? value.heuristic_first_max_tier ?? DEFAULT_HEURISTIC_FIRST_MAX_TIER
+        : undefined,
+    hybrid_boundary_margin:
+      classifierType === "hybrid" ? value.hybrid_boundary_margin ?? DEFAULT_HYBRID_BOUNDARY_MARGIN : undefined,
+    ...nonReasoningTierFields(classifierType, value),
+  };
+  return prepareForecastClassifier(nextValue, classifierType);
+};
diff --git a/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts b/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts
new file mode 100644
index 00000000000..d07d4a24cf0
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts
@@ -0,0 +1,284 @@
+import { describe, expect, it } from "vitest";
+import type { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
+import { getForecastConfigError, prepareForecastClassifier } from "./forecast_classifier_config";
+import { getKeywordTierRulesError } from "./build_complexity_router_config";
+import { activeTierRows } from "./tier_rows";
+import {
+  buildUpdatedComplexityRouterConfig,
+  hydrateComplexityRouterConfig,
+} from "../edit_auto_router/edit_auto_router_modal";
+
+const capability: ComplexityRouterConfigValue = {
+  classifier_type: "capability",
+  classifier_llm_config: { model: "judge", timeout_ms: 20000 },
+  tiers: { SIMPLE: ["efficient"], MEDIUM: [], COMPLEX: [], REASONING: ["capable"] },
+  capability_classifier_config: {
+    efficient_tier: "SIMPLE",
+    capable_tier: "REASONING",
+    base_threshold: 0.7,
+    threshold_step: 0.1,
+  },
+};
+const fuse: ComplexityRouterConfigValue = {
+  ...capability,
+  classifier_type: "llm_v2",
+  capability_classifier_config: undefined,
+  adaptive: false,
+  llm_v2_config: {
+    efficient_profile: "A concise solver",
+    capable_profile: "A solver with more reasoning budget",
+    harness: "One attempt with shell and tests",
+    max_quality_gap: 0.05,
+  },
+};
+
+describe("forecast classifier configuration", () => {
+  it.each([
+    { version: "eval", slope: 21, intercept: 0 },
+    { version: "eval", slope: 1, intercept: -21 },
+    { version: " eval ", slope: 1, intercept: 0 },
+  ])("rejects capability calibration outside the server contract: %j", (calibration) => {
+    const value = {
+      ...capability,
+      capability_classifier_config: { ...capability.capability_classifier_config!, calibration },
+    };
+    expect(getForecastConfigError(value)).toContain("calibration");
+  });
+
+  it.each([capability, fuse])("accepts a complete $classifier_type configuration", (value) => {
+    expect(getForecastConfigError(value)).toBeNull();
+  });
+
+  it("requires both solvers without requiring unused middle tiers", () => {
+    expect(getForecastConfigError({ ...capability, tiers: { ...capability.tiers, REASONING: [] } })).toContain("both");
+    expect(getForecastConfigError(capability)).toBeNull();
+  });
+
+  it("rejects a stepped threshold that exceeds one", () => {
+    expect(
+      getForecastConfigError({
+        ...capability,
+        capability_classifier_config: { ...capability.capability_classifier_config!, threshold_step: 0.2 },
+      }),
+    ).toContain("twice");
+  });
+
+  it.each([Number.NaN, -0.1, 1.1])("rejects an invalid probability %s", (base_threshold) => {
+    expect(
+      getForecastConfigError({
+        ...capability,
+        capability_classifier_config: { ...capability.capability_classifier_config!, base_threshold },
+      }),
+    ).not.toBeNull();
+  });
+
+  it.each(["efficient_profile", "capable_profile", "harness"] as const)("requires %s for Fuse", (field) => {
+    expect(getForecastConfigError({ ...fuse, llm_v2_config: { ...fuse.llm_v2_config!, [field]: " " } })).not.toBeNull();
+  });
+
+  it("requires distinct single model groups and disables adaptive selection", () => {
+    expect(getForecastConfigError({ ...fuse, tiers: { ...fuse.tiers, SIMPLE: ["capable"] } })).toContain("distinct");
+    expect(getForecastConfigError({ ...fuse, tiers: { ...fuse.tiers, SIMPLE: ["efficient", "second"] } })).toContain(
+      "distinct",
+    );
+    expect(getForecastConfigError({ ...fuse, adaptive: true })).toContain("adaptive");
+  });
+
+  it("removes incompatible prompt and tier settings when switching to Fuse", () => {
+    const previous: ComplexityRouterConfigValue = {
+      ...fuse,
+      adaptive: true,
+      classifier_fallback: "default_model",
+      classifier_llm_config: {
+        model: "judge",
+        timeout_ms: 20000,
+        system_prompt: "old rubric",
+        classification_rubric: "business",
+      },
+      classification_prompt: "old prompt",
+      classification_examples: "old example",
+      tiers: { ...fuse.tiers, MEDIUM: ["extra"], SIMPLE: ["efficient", "second"] },
+    };
+    const next = prepareForecastClassifier(previous);
+    const saved = buildUpdatedComplexityRouterConfig({}, next);
+    expect(getForecastConfigError(next)).toBeNull();
+    expect(saved.adaptive).toBe(false);
+    expect(saved.tiers).toEqual({ SIMPLE: ["efficient"], REASONING: ["capable"] });
+    expect(saved.classifier_llm_config).toEqual({ model: "judge", timeout_ms: 20000 });
+    expect(saved).not.toHaveProperty("classification_prompt");
+    expect(saved).not.toHaveProperty("classification_examples");
+    expect(saved).not.toHaveProperty("classifier_fallback");
+  });
+
+  it.each([capability, fuse])(
+    "switching to $classifier_type removes hidden pools and their overrides while retaining the solver settings",
+    (value) => {
+      const efficientParams = { reasoning_effort: "low", speed: "fast", max_tokens: 1024 };
+      const secondEfficientParams = { reasoning_effort: "medium", max_tokens: 2048 };
+      const capableParams = { reasoning_effort: "high", max_tokens: 4096 };
+      const secondCapableParams = { speed: "fast" };
+      const previous: ComplexityRouterConfigValue = {
+        ...value,
+        adaptive: true,
+        plan_mode_min_tier: "MEDIUM",
+        enable_non_reasoning_tier: true,
+        tiers: {
+          NON_REASONING: ["relay"],
+          SIMPLE: ["efficient", "second-efficient"],
+          MEDIUM: ["leftover-medium"],
+          COMPLEX: ["leftover-complex"],
+          REASONING: ["capable", "second-capable"],
+        },
+        tier_model_params: {
+          NON_REASONING: { relay: { max_tokens: 128 } },
+          SIMPLE: { efficient: efficientParams, "second-efficient": secondEfficientParams },
+          MEDIUM: { "leftover-medium": { speed: "fast" } },
+          COMPLEX: { "leftover-complex": { reasoning_effort: "high" } },
+          REASONING: { capable: capableParams, "second-capable": secondCapableParams },
+          LEGACY_CUSTOM: { "leftover-custom": { max_tokens: 512 } },
+        },
+      };
+      const next = prepareForecastClassifier(previous);
+      const preservesPools = value.classifier_type === "capability";
+      const expectedTiers = {
+        SIMPLE: preservesPools ? ["efficient", "second-efficient"] : ["efficient"],
+        MEDIUM: [],
+        COMPLEX: [],
+        REASONING: preservesPools ? ["capable", "second-capable"] : ["capable"],
+      };
+      expect(next.tiers).toEqual(expectedTiers);
+      expect(next.tier_model_params).toEqual({
+        SIMPLE: {
+          efficient: efficientParams,
+          ...(preservesPools && { "second-efficient": secondEfficientParams }),
+        },
+        REASONING: {
+          capable: capableParams,
+          ...(preservesPools && { "second-capable": secondCapableParams }),
+        },
+      });
+      expect(next.adaptive).toBe(preservesPools);
+      expect(next.plan_mode_min_tier).toBeUndefined();
+      expect(getForecastConfigError(next)).toBeNull();
+      expect(activeTierRows(next).map((row) => row.name)).toEqual(["SIMPLE", "REASONING"]);
+      expect(
+        getKeywordTierRulesError([{ id: "old-middle", keywords: ["invoice"], tier: "MEDIUM" }], activeTierRows(next)),
+      ).toContain("no longer has");
+      expect(
+        getKeywordTierRulesError([{ id: "solver", keywords: ["audit"], tier: "REASONING" }], activeTierRows(next)),
+      ).toBeNull();
+      const saved = buildUpdatedComplexityRouterConfig(previous, next);
+      expect(saved.tiers).toEqual({ SIMPLE: expectedTiers.SIMPLE, REASONING: expectedTiers.REASONING });
+      expect(saved.tier_model_configs).toEqual({
+        SIMPLE: [
+          { model_name: "efficient", litellm_params: efficientParams },
+          ...(preservesPools ? [{ model_name: "second-efficient", litellm_params: secondEfficientParams }] : []),
+        ],
+        REASONING: [
+          { model_name: "capable", litellm_params: capableParams },
+          ...(preservesPools ? [{ model_name: "second-capable", litellm_params: secondCapableParams }] : []),
+        ],
+      });
+      expect(saved).not.toHaveProperty("plan_mode_min_tier");
+    },
+  );
+
+  it("preserves fitted calibration through edits and removes it when disabled", () => {
+    const stored = {
+      ...capability,
+      capability_classifier_config: {
+        ...capability.capability_classifier_config!,
+        calibration: { version: "eval-a", slope: 1.2, intercept: -0.3 },
+      },
+    };
+    const hydrated = hydrateComplexityRouterConfig(stored, undefined);
+    const edited = {
+      ...hydrated,
+      capability_classifier_config: { ...hydrated.capability_classifier_config!, base_threshold: 0.6 },
+    };
+    expect(buildUpdatedComplexityRouterConfig(stored, edited).capability_classifier_config).toEqual({
+      ...stored.capability_classifier_config,
+      base_threshold: 0.6,
+    });
+    const disabled = {
+      ...edited,
+      capability_classifier_config: { ...edited.capability_classifier_config, calibration: undefined },
+    };
+    expect(buildUpdatedComplexityRouterConfig(stored, disabled).capability_classifier_config).toHaveProperty(
+      "calibration",
+      undefined,
+    );
+  });
+
+  it("preserves non-default tier assignments", () => {
+    const value = {
+      ...capability,
+      capability_classifier_config: {
+        ...capability.capability_classifier_config!,
+        efficient_tier: "MEDIUM",
+        capable_tier: "COMPLEX",
+      },
+      tiers: { SIMPLE: [], MEDIUM: ["efficient"], COMPLEX: ["capable"], REASONING: [] },
+    };
+    expect(getForecastConfigError(value)).toBeNull();
+    expect(buildUpdatedComplexityRouterConfig({}, value).capability_classifier_config).toEqual(
+      value.capability_classifier_config,
+    );
+    const previous = {
+      ...value,
+      tiers: { ...value.tiers, SIMPLE: ["leftover-simple"], REASONING: ["leftover-reasoning"] },
+      plan_mode_min_tier: "COMPLEX",
+      tier_model_params: {
+        MEDIUM: { efficient: { max_tokens: 1024 } },
+        COMPLEX: { capable: { speed: "fast" } },
+        SIMPLE: { "leftover-simple": { speed: "fast" } },
+      },
+    };
+    const next = prepareForecastClassifier(previous);
+    expect(next.tiers).toEqual(value.tiers);
+    expect(next.plan_mode_min_tier).toBe("COMPLEX");
+    expect(next.tier_model_params).toEqual({
+      MEDIUM: { efficient: { max_tokens: 1024 } },
+      COMPLEX: { capable: { speed: "fast" } },
+    });
+  });
+
+  it("keeps configured extra Capability pools through hydration and an unrelated edit", () => {
+    const stored = {
+      ...capability,
+      adaptive: true,
+      plan_mode_min_tier: "MEDIUM",
+      tiers: { ...capability.tiers, MEDIUM: ["middle"] },
+      tier_model_configs: { MEDIUM: [{ model_name: "middle", litellm_params: { speed: "fast", max_tokens: 1024 } }] },
+    };
+    const hydrated = hydrateComplexityRouterConfig(stored, undefined);
+    expect(hydrated.tiers.MEDIUM).toEqual(["middle"]);
+    expect(hydrated.plan_mode_min_tier).toBe("MEDIUM");
+    expect(activeTierRows(hydrated).map((row) => row.name)).toEqual(["SIMPLE", "MEDIUM", "REASONING"]);
+    expect(
+      getKeywordTierRulesError([{ id: "kept", keywords: ["invoice"], tier: "MEDIUM" }], activeTierRows(hydrated)),
+    ).toBeNull();
+    const saved = buildUpdatedComplexityRouterConfig(stored, {
+      ...hydrated,
+      capability_classifier_config: { ...hydrated.capability_classifier_config!, base_threshold: 0.6 },
+    });
+    expect(saved.tiers).toEqual({ SIMPLE: ["efficient"], MEDIUM: ["middle"], REASONING: ["capable"] });
+    expect(saved.tier_model_configs).toEqual(stored.tier_model_configs);
+    expect(saved.adaptive).toBe(true);
+    expect(saved.plan_mode_min_tier).toBe("MEDIUM");
+  });
+
+  it("keeps empty built-in tiers available to standard classifiers", () => {
+    const standard: ComplexityRouterConfigValue = { ...capability, classifier_type: "llm" };
+    expect(activeTierRows(standard).map((row) => row.name)).toEqual(["SIMPLE", "MEDIUM", "COMPLEX", "REASONING"]);
+    expect(
+      getKeywordTierRulesError([{ id: "middle", keywords: ["invoice"], tier: "MEDIUM" }], activeTierRows(standard)),
+    ).toBeNull();
+  });
+
+  it.each([capability, fuse])("drops $classifier_type settings when switching to the heuristic", (value) => {
+    const saved = buildUpdatedComplexityRouterConfig(value, { ...value, classifier_type: "heuristic" });
+    expect(saved).not.toHaveProperty("capability_classifier_config");
+    expect(saved).not.toHaveProperty("llm_v2_config");
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.ts b/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.ts
new file mode 100644
index 00000000000..5e0c76a2717
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.ts
@@ -0,0 +1,188 @@
+import { z } from "zod";
+import type { ClassifierType, ComplexityRouterConfigValue, ComplexityTiers } from "./ComplexityRouterConfig";
+import { pruneTierModelParams } from "./complexity_router_tiers";
+import { tierOrderFor } from "./tier_rows";
+
+const probability = z.number().finite().min(0).max(1);
+const version = z.string().trim().min(1).max(512);
+const profile = z.string().trim().min(1).max(4000);
+const transport = {
+  max_output_tokens: z.number().int().positive().optional(),
+  response_format: z.enum(["json_schema", "json_object"]).optional(),
+};
+const coefficients = z.object({ slope: z.number().finite().positive(), intercept: z.number().finite() });
+
+const capabilityShape = {
+  efficient_tier: z.string().min(1),
+  capable_tier: z.string().min(1),
+  base_threshold: probability,
+  threshold_step: z.number().finite().nonnegative().optional(),
+  ...transport,
+  calibration: z
+    .object({
+      version: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^\S(?:.*\S)?$/),
+      slope: z.number().finite().min(0).max(20),
+      intercept: z.number().finite().min(-20).max(20),
+    })
+    .nullable()
+    .optional(),
+};
+export const capabilitySettingsSchema = z.object(capabilityShape);
+
+const fuseCalibrationShape = {
+  version,
+  prompt_version: z.literal("llm-v2-1"),
+  efficient: coefficients,
+  capable: coefficients,
+};
+const fuseShape = {
+  efficient_tier: z.string().min(1).optional(),
+  capable_tier: z.string().min(1).optional(),
+  efficient_profile: profile,
+  capable_profile: profile,
+  harness: profile,
+  max_quality_gap: probability,
+  ...transport,
+  calibration: z.object(fuseCalibrationShape).nullable().optional(),
+};
+export const fuseSettingsSchema = z.object(fuseShape);
+
+export type CapabilitySettings = z.infer<typeof capabilitySettingsSchema>;
+export type FuseSettings = z.infer<typeof fuseSettingsSchema>;
+
+export const isForecastClassifier = (type: ClassifierType): boolean => type === "capability" || type === "llm_v2";
+
+export const newCapabilitySettings = (): CapabilitySettings => ({
+  efficient_tier: "SIMPLE",
+  capable_tier: "REASONING",
+  base_threshold: Number.NaN,
+});
+
+export const newFuseSettings = (): FuseSettings => ({
+  efficient_profile: "",
+  capable_profile: "",
+  harness: "",
+  max_quality_gap: Number.NaN,
+});
+
+export const forecastTierNames = (
+  value: Pick<ComplexityRouterConfigValue, "classifier_type" | "capability_classifier_config" | "llm_v2_config">,
+): readonly [string, string] => {
+  const settings = value.classifier_type === "capability" ? value.capability_classifier_config : value.llm_v2_config;
+  return [settings?.efficient_tier ?? "SIMPLE", settings?.capable_tier ?? "REASONING"];
+};
+
+export const forecastModels = (tiers: ComplexityTiers, tier: string): string[] =>
+  Object.entries(tiers).find(([name]) => name === tier)?.[1] ?? [];
+
+export const withoutForecastPromptOverrides = <T extends { system_prompt?: string; classification_rubric?: string }>(
+  config: T,
+): Omit<T, "system_prompt" | "classification_rubric"> => {
+  const { system_prompt: _prompt, classification_rubric: _rubric, ...rest } = config;
+  return rest;
+};
+
+export const prepareForecastClassifier = (
+  previous: ComplexityRouterConfigValue,
+  classifierType: ClassifierType = previous.classifier_type,
+): ComplexityRouterConfigValue => {
+  const value = { ...previous, classifier_type: classifierType };
+  if (!isForecastClassifier(classifierType))
+    return {
+      ...value,
+      capability_classifier_config: undefined,
+      llm_v2_config: undefined,
+    };
+  // Capture routing identity before replacing the source classifier's settings.
+  const [sourceEfficient, sourceCapable] = forecastTierNames(previous);
+  const transferredPair =
+    isForecastClassifier(previous.classifier_type) && previous.classifier_type !== classifierType
+      ? { efficient_tier: sourceEfficient, capable_tier: sourceCapable }
+      : {};
+  const configured = {
+    ...value,
+    capability_classifier_config:
+      value.classifier_type === "capability"
+        ? { ...(value.capability_classifier_config ?? newCapabilitySettings()), ...transferredPair }
+        : undefined,
+    llm_v2_config:
+      value.classifier_type === "llm_v2"
+        ? { ...(value.llm_v2_config ?? newFuseSettings()), ...transferredPair }
+        : undefined,
+  };
+  const [efficient, capable] = forecastTierNames(configured);
+  const solverModels = (tier: string) => {
+    const models = forecastModels(value.tiers, tier);
+    return value.classifier_type === "llm_v2" ? models.slice(0, 1) : models;
+  };
+  const tiers: ComplexityTiers = {
+    SIMPLE: [],
+    MEDIUM: [],
+    COMPLEX: [],
+    REASONING: [],
+    [efficient]: solverModels(efficient),
+    [capable]: solverModels(capable),
+  };
+  return {
+    ...configured,
+    tiers,
+    tier_model_params: Object.keys(value.tier_model_params ?? {}).reduce(
+      (params, tier) => pruneTierModelParams(params, tier, forecastModels(tiers, tier)),
+      value.tier_model_params,
+    ),
+    plan_mode_min_tier:
+      value.plan_mode_min_tier && forecastModels(tiers, value.plan_mode_min_tier).length > 0
+        ? value.plan_mode_min_tier
+        : undefined,
+    custom_tier_set: undefined,
+    enable_non_reasoning_tier: false,
+    classification_prompt: undefined,
+    classification_examples: undefined,
+    classifier_fallback: undefined,
+    classifier_llm_config: value.classifier_llm_config && withoutForecastPromptOverrides(value.classifier_llm_config),
+    ...(value.classifier_type === "llm_v2" && { adaptive: false }),
+  };
+};
+
+export const getForecastConfigError = (value: ComplexityRouterConfigValue): string | null => {
+  if (!isForecastClassifier(value.classifier_type) || value.custom_tier_set) return null;
+  const timeout = value.classifier_llm_config?.timeout_ms;
+  if (timeout !== undefined && (!Number.isInteger(timeout) || timeout <= 0))
+    return "Enter a positive whole-number classifier timeout";
+  const [efficient, capable] = forecastTierNames(value);
+  const order: readonly string[] = tierOrderFor(value.enable_non_reasoning_tier);
+  if (!order.includes(efficient) || !order.includes(capable) || order.indexOf(capable) <= order.indexOf(efficient))
+    return "The capable tier must be higher than the efficient tier";
+  const efficientModels = forecastModels(value.tiers, efficient);
+  const capableModels = forecastModels(value.tiers, capable);
+  if (!efficientModels.length || !capableModels.length)
+    return "Select models for both the efficient and capable solvers";
+  if (value.classifier_type === "capability") {
+    const result = capabilitySettingsSchema.safeParse(value.capability_classifier_config);
+    if (!result.success)
+      return "Enter a solve threshold between 0 and 1 and valid capability settings, including any calibration coefficients";
+    if (result.data.base_threshold + 2 * (result.data.threshold_step ?? 0) > 1)
+      return "The solve threshold plus twice the boundary step must be at most 1";
+    return null;
+  }
+  return getFuseConfigError(value, efficient, capable);
+};
+
+const getFuseConfigError = (value: ComplexityRouterConfigValue, efficient: string, capable: string): string | null => {
+  const efficientModels = forecastModels(value.tiers, efficient);
+  const capableModels = forecastModels(value.tiers, capable);
+  if (value.adaptive) return "Turn off adaptive routing for Fuse v2";
+  if (value.enable_non_reasoning_tier) return "Fuse v2 does not support the non-reasoning tier";
+  if (efficientModels.length !== 1 || capableModels.length !== 1 || efficientModels[0] === capableModels[0])
+    return "Fuse v2 requires one distinct model group for each solver";
+  if (Object.entries(value.tiers).some(([tier, models]) => models.length > 0 && ![efficient, capable].includes(tier)))
+    return "Fuse v2 supports only its efficient and capable tiers";
+  const result = fuseSettingsSchema.safeParse(value.llm_v2_config);
+  if (!result.success)
+    return "Complete both solver profiles, the harness, and a quality gap between 0 and 1; any calibration needs valid coefficients and a version";
+  return null;
+};
diff --git a/ui/litellm-dashboard/src/components/add_model/tier_rows.ts b/ui/litellm-dashboard/src/components/add_model/tier_rows.ts
index 3111c7a2bb3..b4c6b2cb81e 100644
--- a/ui/litellm-dashboard/src/components/add_model/tier_rows.ts
+++ b/ui/litellm-dashboard/src/components/add_model/tier_rows.ts
@@ -1,4 +1,5 @@
-import type { ComplexityTiers } from "./ComplexityRouterConfig";
+import { isForecastClassifier } from "./forecast_classifier_config";
+import type { ClassifierType, ComplexityTiers } from "./ComplexityRouterConfig";
 import type { ComplexityTier } from "./KeywordTierRules";
 import type { TierModelParams, TierModelParamsByTier } from "./complexity_router_tiers";
 
@@ -32,6 +33,7 @@ export const MAX_TIER_NAME_CHARS = 64;
 export const MAX_TIER_DEFINITION_CHARS = 500;
 
 export interface ActiveTierSet {
+  classifier_type?: ClassifierType;
   tiers: ComplexityTiers;
   enable_non_reasoning_tier?: boolean;
   custom_tier_set?: CustomTierSet;
@@ -62,7 +64,12 @@ export const activeTierRows = (value: ActiveTierSet): ActiveTierRow[] => {
   const rows =
     value.custom_tier_set?.tiers ??
     tierOrderFor(value.enable_non_reasoning_tier).map((tier) => builtInRow(tier, value.tiers));
-  return rows.map((row) => ({ ...row, params: value.tier_model_params?.[row.id] ?? {} }));
+  return rows
+    .filter(
+      (row) =>
+        value.custom_tier_set || !isForecastClassifier(value.classifier_type ?? "heuristic") || row.models.length > 0,
+    )
+    .map((row) => ({ ...row, params: value.tier_model_params?.[row.id] ?? {} }));
 };
 
 // The wire shape of an edited tier set, shared by the payload builder and the prompt preview so the
diff --git a/ui/litellm-dashboard/src/components/add_model/tier_set_actions.test.ts b/ui/litellm-dashboard/src/components/add_model/tier_set_actions.test.ts
index f939eb95bca..9efdee3279a 100644
--- a/ui/litellm-dashboard/src/components/add_model/tier_set_actions.test.ts
+++ b/ui/litellm-dashboard/src/components/add_model/tier_set_actions.test.ts
@@ -23,6 +23,35 @@ const apply = (value: ComplexityRouterConfigValue, action: Parameters<typeof app
   applyTierSetAction(value, rules, action);
 
 describe("applyTierSetAction", () => {
+  it.each(["llm", "capability", "llm_v2"] as const)(
+    "clears an emptied plan floor and can repopulate its pool for %s",
+    (classifier_type) => {
+      const initial: ComplexityRouterConfigValue = {
+        ...builtIn,
+        classifier_type,
+        plan_mode_min_tier: "SIMPLE",
+        tier_model_params: { SIMPLE: { "gpt-3.5-turbo": { speed: "fast" } } },
+      };
+      const { value: cleared } = apply(initial, { kind: "models", id: "SIMPLE", models: [] });
+      expect(cleared.plan_mode_min_tier).toBeUndefined();
+      expect(cleared.tier_model_params).toBeUndefined();
+      expect(cleared.tiers.SIMPLE).toEqual([]);
+      const { value: restored } = apply(cleared, { kind: "models", id: "SIMPLE", models: ["gpt-4"] });
+      expect(restored.tiers.SIMPLE).toEqual(["gpt-4"]);
+      expect(restored.plan_mode_min_tier).toBeUndefined();
+      expect(restored.tier_model_params).toBeUndefined();
+    },
+  );
+
+  it("preserves a populated custom plan floor after removing only one model", () => {
+    const initial: ComplexityRouterConfigValue = { ...custom, plan_mode_min_tier: "sec" };
+    const { value: changed } = apply(initial, { kind: "models", id: "sec", models: ["new-model"] });
+    expect(changed.plan_mode_min_tier).toBe("sec");
+    const { value: cleared } = apply(changed, { kind: "models", id: "sec", models: [] });
+    expect(cleared.plan_mode_min_tier).toBeUndefined();
+    expect(cleared.custom_tier_set?.tiers.find((row) => row.id === "sec")?.models).toEqual([]);
+  });
+
   it("adds a row and moves the form into an edited set, which the built-in record never leaves", () => {
     const { value } = apply(builtIn, { kind: "add" });
     expect(value.custom_tier_set?.tiers).toHaveLength(5);
diff --git a/ui/litellm-dashboard/src/components/add_model/tier_set_actions.ts b/ui/litellm-dashboard/src/components/add_model/tier_set_actions.ts
index f737e0fdff6..40f239f1ae5 100644
--- a/ui/litellm-dashboard/src/components/add_model/tier_set_actions.ts
+++ b/ui/litellm-dashboard/src/components/add_model/tier_set_actions.ts
@@ -93,6 +93,30 @@ const exitToBuiltInTiers = (value: ComplexityRouterConfigValue, rows: readonly A
   return commitTierRows(activeTierRows(restored), "", restored);
 };
 
+/** Model changes reconcile params and the plan floor against the resulting populated pools. */
+export const setTierModels = (
+  value: ComplexityRouterConfigValue,
+  id: string,
+  models: string[],
+): ComplexityRouterConfigValue => {
+  const next: ComplexityRouterConfigValue = {
+    ...value,
+    ...(value.custom_tier_set
+      ? {
+          custom_tier_set: {
+            ...value.custom_tier_set,
+            tiers: value.custom_tier_set.tiers.map((row) => (row.id === id ? { ...row, models } : row)),
+          },
+        }
+      : { tiers: { ...value.tiers, [id]: models } }),
+    tier_model_params: pruneTierModelParams(value.tier_model_params, id, models),
+  };
+  const floor = next.plan_mode_min_tier;
+  return floor && !activeTierRows(next).some((row) => row.id === floor && row.models.length > 0)
+    ? { ...next, plan_mode_min_tier: undefined }
+    : next;
+};
+
 const nextTierSetValue = (
   value: ComplexityRouterConfigValue,
   rows: ActiveTierRow[],
@@ -102,11 +126,7 @@ const nextTierSetValue = (
 
   switch (action.kind) {
     case "models":
-      return commitTierRows(
-        rows.map((row) => (row.id === action.id ? { ...row, models: action.models } : row)),
-        fallbackId,
-        { ...value, tier_model_params: pruneTierModelParams(value.tier_model_params, action.id, action.models) },
-      );
+      return setTierModels(value, action.id, action.models);
     case "patch":
       return commitTierRows(
         rows.map((row) => (row.id === action.id ? { ...row, ...action.patch } : row)),
diff --git a/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts b/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts
index 09b39d4b071..1aa6f0e3d35 100644
--- a/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts
+++ b/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts
@@ -675,7 +675,11 @@ describe("managed keys survive an untouched open-and-save", () => {
 
   // The opt-in fifth tier requires the LLM classifier, which this heuristic_first fixture is not,
   // so it gets its own round trip below.
-  const KEYS_ANOTHER_TIER_LADDER_OWNS = new Set(["enable_non_reasoning_tier"]);
+  const KEYS_ANOTHER_TIER_LADDER_OWNS = new Set([
+    "capability_classifier_config",
+    "llm_v2_config",
+    "enable_non_reasoning_tier",
+  ]);
 
   it("carries every managed key a built-in router can hold through hydrate then save", () => {
     const hydrated = hydrateComplexityRouterConfig(STORED_ALL_MANAGED, undefined);
@@ -850,7 +854,12 @@ describe("LLM V2 configuration preservation", () => {
     harness: "Shell access, one attempt",
     max_quality_gap: 0.03,
     response_format: "json_object",
-    calibration: { version: "pair-v1", prompt_version: "llm-v2-1" },
+    calibration: {
+      version: "pair-v1",
+      prompt_version: "llm-v2-1",
+      efficient: { slope: 1.2, intercept: -0.3 },
+      capable: { slope: 0.9, intercept: 0.1 },
+    },
   };
   const stored = {
     tiers: { SIMPLE: ["efficient"], REASONING: ["capable"] },
diff --git a/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx b/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx
index 98e85a71b18..4a6c22689cc 100644
--- a/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx
+++ b/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx
@@ -1,3 +1,11 @@
+import AutoRouterClassifierTabs from "../add_model/AutoRouterClassifierTabs";
+import type { StoredComplexityRouterConfig } from "../add_model/build_complexity_router_config";
+export type { StoredComplexityRouterConfig } from "../add_model/build_complexity_router_config";
+import {
+  getForecastConfigError,
+  capabilitySettingsSchema,
+  fuseSettingsSchema,
+} from "../add_model/forecast_classifier_config";
 import React, { useEffect, useMemo, useState } from "react";
 import {
   complexityRouterSchema,
@@ -62,13 +70,7 @@ import {
   hydrateTokenThresholds,
 } from "../add_model/heuristic_scoring_knobs";
 import ComplexityRouterConfig, {
-  AdaptiveEligible,
-  AdaptiveRouterWeights,
-  ClassifierLLMConfig,
-  ClassifierType,
-  effectiveClassifierType,
   ComplexityRouterConfigValue,
-  ComplexityTiers,
   heuristicScoringRole,
   DEFAULT_ADAPTIVE_WEIGHTS,
   DEFAULT_SESSION_AFFINITY,
@@ -97,47 +99,6 @@ interface EditAutoRouterModalProps {
 // Keys this modal rewrites from its own form state on save. Anything absent from this set is
 // carried through untouched from the stored config, so a key only belongs here once the modal
 // actually renders a control that can set it.
-/** The complexity_router_config as it comes back from the proxy, before any hydration. Fields the
- * hydrators validate themselves stay `unknown`; the ones assigned straight through carry their type. */
-export interface StoredComplexityRouterConfig {
-  tiers?: Partial<Record<keyof ComplexityTiers, unknown>>;
-  enable_non_reasoning_tier?: boolean;
-  tier_model_configs?: unknown;
-  default_model?: string | null;
-  plan_mode_min_tier?: unknown;
-  classification_prompt?: unknown;
-  classification_examples?: unknown;
-  heuristic_first_max_tier?: unknown;
-  hybrid_boundary_margin?: unknown;
-  tier_labels?: unknown;
-  classifier_type?: ClassifierType;
-  classifier_llm_config?: ClassifierLLMConfig;
-  classifier_context_window_size?: unknown;
-  classifier_context_budget_chars?: unknown;
-  classifier_context_include_assistant_turns?: unknown;
-  classifier_fallback?: unknown;
-  classification_mode?: unknown;
-  tier_boundaries?: unknown;
-  token_thresholds?: unknown;
-  dimension_weights?: unknown;
-  custom_dimensions?: unknown;
-  reasoning_override_min_score?: unknown;
-  session_affinity?: unknown;
-  session_affinity_ttl_seconds?: unknown;
-  modality_routing?: unknown;
-  modality_pin_override?: unknown;
-  deployment_affinity?: unknown;
-  adaptive?: boolean;
-  adaptive_weights?: AdaptiveRouterWeights;
-  tier_distance_penalty?: number;
-  adaptive_eligible?: AdaptiveEligible;
-  return_raw_model_name?: boolean;
-  enable_context_window_escalation?: unknown;
-  context_window_escalation_buffer?: unknown;
-  stall_escalation_enabled?: unknown;
-  stall_escalation_window?: unknown;
-  stall_escalation_repeat_threshold?: unknown;
-}
 
 /**
  * The stored complexity_router_config as form state. Every key in MANAGED_COMPLEXITY_ROUTER_KEYS is
@@ -164,6 +125,8 @@ export const hydrateComplexityRouterConfig = (
     plan_mode_min_tier: hydratePlanModeMinTier(parsedConfig.plan_mode_min_tier, custom_tier_set),
     tier_labels: hydrateTierLabels(parsedConfig.tier_labels),
     classifier_type: parsedConfig.classifier_type || "heuristic",
+    capability_classifier_config: capabilitySettingsSchema.safeParse(parsedConfig.capability_classifier_config).data,
+    llm_v2_config: fuseSettingsSchema.safeParse(parsedConfig.llm_v2_config).data,
     classifier_llm_config: parsedConfig.classifier_llm_config,
     classifier_context_window_size:
       typeof parsedConfig.classifier_context_window_size === "number"
@@ -251,6 +214,8 @@ export const MANAGED_COMPLEXITY_ROUTER_KEYS = new Set([
   "plan_mode_min_tier",
   "tier_labels",
   "classifier_type",
+  "capability_classifier_config",
+  "llm_v2_config",
   "classifier_llm_config",
   "classifier_context_window_size",
   "classifier_context_budget_chars",
@@ -339,7 +304,6 @@ export const buildUpdatedComplexityRouterConfig = (
   keywordMatching?: KeywordMatchingState,
 ): Record<string, unknown> => {
   const isManaged = (key: string): boolean => {
-    if (key === "llm_v2_config" && effectiveClassifierType(value) !== "llm_v2") return true;
     if (MANAGED_COMPLEXITY_ROUTER_KEYS.has(key)) return true;
     if (keywordMatching !== undefined && KEYWORD_MATCHING_KEYS.has(key)) return true;
     return customTechnicalKeywords !== undefined && key === "custom_technical_keywords";
@@ -362,6 +326,8 @@ export const buildUpdatedComplexityRouterConfig = (
     classificationMode: value.classification_mode,
     tierLabels: value.tier_labels,
     classifierType: value.classifier_type,
+    capabilityClassifierConfig: value.capability_classifier_config,
+    llmV2Config: value.llm_v2_config,
     classifierLlmConfig: value.classifier_llm_config,
     classifierContextWindowSize: value.classifier_context_window_size,
     classifierContextBudgetChars: value.classifier_context_budget_chars,
@@ -458,6 +424,7 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
       getPlanModeTierError(complexityRouterConfig.plan_mode_min_tier, activeTierRows(complexityRouterConfig)) ??
       getKeywordTierRulesError(keywordTierRules, activeTierRows(complexityRouterConfig)) ??
       getClassifierModelError(complexityRouterConfig) ??
+      getForecastConfigError(complexityRouterConfig) ??
       (heuristicScoringRole(complexityRouterConfig) === "decides"
         ? customDimensionsError(complexityRouterConfig.custom_dimensions)
         : null);
@@ -589,6 +556,7 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
       }
       const classifierError =
         getClassifierModelError(complexityRouterConfig) ??
+        getForecastConfigError(complexityRouterConfig) ??
         (heuristicScoringRole(complexityRouterConfig) === "decides"
           ? customDimensionsError(complexityRouterConfig.custom_dimensions)
           : null);
@@ -742,6 +710,14 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
     { value: "custom", label: "Enter custom model name" },
   ];
 
+  const routerNameField = (
+    <FormField control={form.control} name="auto_router_name" label="Auto Router Name">
+      {({ ref, ...field }) => (
+        <Input {...field} ref={ref} readOnly={isMemberManaged} placeholder="e.g., auto_router_1, smart_routing" />
+      )}
+    </FormField>
+  );
+
   return (
     <Dialog open={isVisible} onOpenChange={(open) => !open && onCancel()}>
       <DialogContent className="max-h-[90vh] overflow-y-auto sm:max-w-4xl">
@@ -755,48 +731,41 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
 
           <form onSubmit={(event) => event.preventDefault()} noValidate>
             <FieldGroup>
-              <FormField control={form.control} name="auto_router_name" label="Auto Router Name">
-                {({ ref, ...field }) => (
-                  <Input
-                    {...field}
-                    ref={ref}
-                    readOnly={isMemberManaged}
-                    placeholder="e.g., auto_router_1, smart_routing"
-                  />
-                )}
-              </FormField>
+              {routerNameField}
 
               {isComplexityRouterModel ? (
                 /* Complexity Router Configuration */
                 <div className="w-full">
-                  <ComplexityRouterConfig
-                    editingTiers={editingTiers}
-                    onEditingTiersChange={setEditingTiers}
-                    showValidationErrors={showValidationErrors}
-                    modelInfo={modelInfo}
-                    value={complexityRouterConfig}
-                    onChange={(config) => {
-                      setComplexityRouterConfig(config);
-                    }}
-                    customTechnicalKeywords={customTechnicalKeywords}
-                    onCustomTechnicalKeywordsChange={setCustomTechnicalKeywords}
-                    keywordTierRules={keywordTierRules}
-                    onKeywordTierRulesChange={setKeywordTierRules}
-                    keywordRulesError={getKeywordTierRulesError(
-                      keywordTierRules,
-                      activeTierRows(complexityRouterConfig),
-                    )}
-                    semanticMatchingEnabled={semanticMatchingEnabled}
-                    onSemanticMatchingEnabledChange={setSemanticMatchingEnabled}
-                    embeddingModel={embeddingModel}
-                    onEmbeddingModelChange={setEmbeddingModel}
-                    matchThreshold={matchThreshold}
-                    onMatchThresholdChange={setMatchThreshold}
-                    escalationKeywords={escalationKeywords}
-                    onEscalationKeywordsChange={setEscalationKeywords}
-                    autoRouterCompression={autoRouterCompression}
-                    onAutoRouterCompressionChange={isMemberManaged ? undefined : setAutoRouterCompression}
-                  />
+                  <AutoRouterClassifierTabs value={complexityRouterConfig} onChange={setComplexityRouterConfig}>
+                    <ComplexityRouterConfig
+                      editingTiers={editingTiers}
+                      onEditingTiersChange={setEditingTiers}
+                      showValidationErrors={showValidationErrors}
+                      modelInfo={modelInfo}
+                      value={complexityRouterConfig}
+                      onChange={(config) => {
+                        setComplexityRouterConfig(config);
+                      }}
+                      customTechnicalKeywords={customTechnicalKeywords}
+                      onCustomTechnicalKeywordsChange={setCustomTechnicalKeywords}
+                      keywordTierRules={keywordTierRules}
+                      onKeywordTierRulesChange={setKeywordTierRules}
+                      keywordRulesError={getKeywordTierRulesError(
+                        keywordTierRules,
+                        activeTierRows(complexityRouterConfig),
+                      )}
+                      semanticMatchingEnabled={semanticMatchingEnabled}
+                      onSemanticMatchingEnabledChange={setSemanticMatchingEnabled}
+                      embeddingModel={embeddingModel}
+                      onEmbeddingModelChange={setEmbeddingModel}
+                      matchThreshold={matchThreshold}
+                      onMatchThresholdChange={setMatchThreshold}
+                      escalationKeywords={escalationKeywords}
+                      onEscalationKeywordsChange={setEscalationKeywords}
+                      autoRouterCompression={autoRouterCompression}
+                      onAutoRouterCompressionChange={isMemberManaged ? undefined : setAutoRouterCompression}
+                    />
+                  </AutoRouterClassifierTabs>
                 </div>
               ) : (
                 <>

From 917018308788e3abca5cbb10afdefaa05dcdb804 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 19:32:50 -0700
Subject: [PATCH 54/67] fix(e2e): exclude unknown routes from upstream counters

---
 tests/code_coverage_tests/test_provider_cache.py | 16 +++++++++++-----
 tests/e2e/provider_edge.py                       |  3 ++-
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 9a4cba7f322..9d89a5fe622 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -434,22 +434,28 @@ def test_enabled_environment_reuses_store_across_fresh_backends(
         configured_cache.cache_clear()
 
 
-def test_duplicate_headers_bypass_cache_and_count_live_calls(store: RedisResponseStore, provider: Provider) -> None:
+@pytest.mark.parametrize("known_mount", (True, False))
+def test_duplicate_headers_bypass_cache_and_count_live_calls(
+    store: RedisResponseStore, provider: Provider, known_mount: bool,
+) -> None:
     cache: Final = CacheEdge(store, SECRET)
     with edge(cache, provider) as url:
         parsed: Final = urlsplit(url)
         for _ in range(2):
             connection = HTTPConnection(str(parsed.hostname), parsed.port, timeout=5)
             try:
-                connection.putrequest("POST", parsed.path)
+                connection.putrequest("POST", parsed.path if known_mount else "/unknown/v1/chat/completions")
                 connection.putheader("content-length", str(len(BODY)))
                 connection.putheader("content-type", "application/json")
                 connection.putheader("x-duplicate", "first")
                 connection.putheader("x-duplicate", "second")
                 connection.endheaders(BODY)
-                assert connection.getresponse().read() == SUCCESS
+                response = connection.getresponse()
+                assert response.status == (200 if known_mount else 404)
+                payload = response.read()
+                assert payload == SUCCESS if known_mount else b"unknown provider mount" in payload
             finally:
                 connection.close()
-    assert len(provider.hits) == 2
+    assert len(provider.hits) == (2 if known_mount else 0)
     assert dict(cache.counters.counts)["duplicate_header_bypass"] == 2
-    assert dict(cache.counters.counts)["upstream_attempts"] == 2
+    assert dict(cache.counters.counts).get("upstream_attempts", 0) == (2 if known_mount else 0)
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index 053a2b5c0d3..dda9e6f8e4f 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -891,7 +891,8 @@ class _EdgeHandler(BaseHTTPRequestHandler):
         )
         if isinstance(edge_server.backend, CacheEdge) and duplicate_headers:
             edge_server.backend.counters.increment("duplicate_header_bypass")
-            edge_server.backend.counters.increment("upstream_attempts")
+            if urlsplit(self.path).path.lstrip("/").partition("/")[0] in edge_server.mounts:
+                edge_server.backend.counters.increment("upstream_attempts")
         outcome: Final = handle_edge_request(
             selected_backend,
             edge_server.mounts,

From 6fd988cc637ff96e1d879bb85bd65d0e1745f07f Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 19:45:33 -0700
Subject: [PATCH 55/67] test(router): ignore deployment-selection logs in the
 fallback log assertion

simple_shuffle logs the selected deployment at INFO whenever a weight set
applies, so the fallback group's selection line lands between the fallback
notice and the success notice and pushed the notice out of the tail-3 window.
Filter it the same way the neighbouring get_available_deployment noise is
already filtered.
---
 tests/local_testing/test_router_debug_logs.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/local_testing/test_router_debug_logs.py b/tests/local_testing/test_router_debug_logs.py
index 0fce5c824c7..b3c26a7689f 100644
--- a/tests/local_testing/test_router_debug_logs.py
+++ b/tests/local_testing/test_router_debug_logs.py
@@ -86,6 +86,7 @@ def test_async_fallbacks(caplog):
         if "Task exception was never retrieved" not in log
         and "Task was destroyed but it is pending" not in log
         and "get_available_deployment" not in log
+        and "Selected deployment for model" not in log
         and "in the Langfuse queue" not in log
         and "Unclosed client session" not in log
         and "Unclosed connector" not in log

From a8fba14e107ccaad5e972895606f2efeb53efab0 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 19:48:25 -0700
Subject: [PATCH 56/67] test(proxy): assert budget resets decrement the cleared
 spend

The reset job moved from zeroing spend to an atomic decrement of the amount
it cleared, so every batched write now carries {"decrement": <cleared>}
instead of 0. Four tests still pinned 0 and had been failing since, which
also meant they no longer checked the amount at all. Assert the decrement
equals each row's own pre-reset spend, so a wrong amount fails the test.
---
 .../test_proxy_budget_reset.py                | 24 +++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/tests/litellm_utils_tests/test_proxy_budget_reset.py b/tests/litellm_utils_tests/test_proxy_budget_reset.py
index 4103536950d..fe3c38a771f 100644
--- a/tests/litellm_utils_tests/test_proxy_budget_reset.py
+++ b/tests/litellm_utils_tests/test_proxy_budget_reset.py
@@ -163,6 +163,9 @@ async def test_reset_budget_keys_partial_failure():
     key1, key2, key3, key4, key5, key6 = (
         _attrify(k) for k in [key1, key2, key3, key4, key5, key6]
     )
+    pre_reset_spend = {
+        k["token"]: k["spend"] for k in [key2, key3, key4, key5, key6]
+    }
     prisma_client.get_data = AsyncMock(
         return_value=[key1, key2, key3, key4, key5, key6]
     )
@@ -201,7 +204,7 @@ async def test_reset_budget_keys_partial_failure():
     # And every write must carry only {spend, budget_reset_at} — never the full row.
     for c in key_writes:
         assert set(c["data"].keys()) == {"spend", "budget_reset_at"}
-        assert c["data"]["spend"] == 0
+        assert c["data"]["spend"] == {"decrement": pre_reset_spend[c["where"]["token"]]}
 
     # Verify that the failure logging hook was scheduled (due to the failure for key1)
     failure_hook_calls = (
@@ -252,6 +255,9 @@ async def test_reset_budget_users_partial_failure():
     user1, user2, user3, user4, user5, user6 = (
         _attrify(u) for u in [user1, user2, user3, user4, user5, user6]
     )
+    pre_reset_spend = {
+        u["user_id"]: u["spend"] for u in [user2, user3, user4, user5, user6]
+    }
     prisma_client.get_data = AsyncMock(
         return_value=[user1, user2, user3, user4, user5, user6]
     )
@@ -280,7 +286,9 @@ async def test_reset_budget_users_partial_failure():
     assert written_ids == ["user2", "user3", "user4", "user5", "user6"]
     for c in user_writes:
         assert set(c["data"].keys()) == {"spend", "budget_reset_at"}
-        assert c["data"]["spend"] == 0
+        assert c["data"]["spend"] == {
+            "decrement": pre_reset_spend[c["where"]["user_id"]]
+        }
 
     failure_hook_calls = (
         proxy_logging_obj.service_logging_obj.async_service_failure_hook.call_args_list
@@ -441,6 +449,7 @@ async def test_reset_budget_teams_partial_failure():
     for t in [team1, team2]:
         t.setdefault("team_id", t["id"])
     team1, team2 = _attrify(team1), _attrify(team2)
+    pre_reset_spend = team2["spend"]
     prisma_client.get_data = AsyncMock(return_value=[team1, team2])
 
     async def fake_reset_team(team, current_time, reset_settings=None):
@@ -465,7 +474,7 @@ async def test_reset_budget_teams_partial_failure():
     assert len(team_writes) == 1
     assert team_writes[0]["where"] == {"team_id": "team2"}
     assert set(team_writes[0]["data"].keys()) == {"spend", "budget_reset_at"}
-    assert team_writes[0]["data"]["spend"] == 0
+    assert team_writes[0]["data"]["spend"] == {"decrement": pre_reset_spend}
 
     failure_hook_calls = (
         proxy_logging_obj.service_logging_obj.async_service_failure_hook.call_args_list
@@ -542,6 +551,11 @@ async def test_reset_budget_continues_other_categories_on_failure():
     user1, user2 = _attrify(user1), _attrify(user2)
     team1, team2 = _attrify(team1), _attrify(team2)
     enduser1 = _attrify(enduser1)
+    pre_reset_spend = {
+        **{k["token"]: k["spend"] for k in [key1, key2]},
+        **{u["user_id"]: u["spend"] for u in [user2]},
+        **{t["team_id"]: t["spend"] for t in [team1, team2]},
+    }
     _wire_cascade_reads_for_test(prisma_client)
 
     proxy_logging_obj = MagicMock()
@@ -618,7 +632,9 @@ async def test_reset_budget_continues_other_categories_on_failure():
     # Every batched write must carry only the two reset fields, never the full row.
     for c in key_writes + user_writes + team_writes:
         assert set(c["data"].keys()) == {"spend", "budget_reset_at"}
-        assert c["data"]["spend"] == 0
+        assert c["data"]["spend"] == {
+            "decrement": pre_reset_spend[next(iter(c["where"].values()))]
+        }
 
 
 # ---------------------------------------------------------------------------

From 7121e64db4903dc7b832b25f79f1f5f048b73a36 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 03:13:53 +0000
Subject: [PATCH 57/67] fix(responses): type the dict terminal response so the
 estimated usage is billed

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 42 +++++++++++--------
 .../responses/test_streaming_iterator.py      | 15 +++++--
 2 files changed, 35 insertions(+), 22 deletions(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 10ddf07ac7e..3004337f9d1 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -429,25 +429,31 @@ class BaseResponsesAPIStreamingIterator:
                 ):
                     self.completed_response = openai_responses_api_chunk
                     _response_obj: Final[object] = getattr(openai_responses_api_chunk, "response", None)
-                    if _chunk_type in (
-                        openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
-                        openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
+                    _typed_response: Final[ResponsesAPIResponse | None] = (
+                        ResponsesAPIResponse.model_construct(**_response_obj)  # pyright: ignore[reportUnknownArgumentType]  # the model_constructed terminal event leaves response as an untyped dict
+                        if isinstance(_response_obj, dict)
+                        else _response_obj
+                        if isinstance(_response_obj, ResponsesAPIResponse)
+                        else None
+                    )
+                    if (
+                        _typed_response is not None
+                        and _chunk_type
+                        in (
+                            openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
+                            openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
+                        )
+                        and _typed_response.usage is None
                     ):
-                        if isinstance(_response_obj, ResponsesAPIResponse) and _response_obj.usage is None:
-                            _response_obj.usage = _estimate_usage_safely(
-                                self.model or "",
-                                self.request_data.get("input"),
-                                self.request_data,
-                                self._generated_content + self._generated_tool_arguments,
-                            )
-                        elif isinstance(_response_obj, dict) and _response_obj.get("usage") is None:  # pyright: ignore[reportUnknownMemberType]  # the model_constructed terminal event leaves response as an untyped dict
-                            _response_obj["usage"] = _estimate_usage_safely(
-                                self.model or "",
-                                self.request_data.get("input"),
-                                self.request_data,
-                                self._generated_content + self._generated_tool_arguments,
-                            )
-                    _stamp_responses_usage_cost(getattr(openai_responses_api_chunk, "response", None), self.logging_obj)
+                        _typed_response.usage = _estimate_usage_safely(
+                            self.model or "",
+                            self.request_data.get("input"),
+                            self.request_data,
+                            self._generated_content + self._generated_tool_arguments,
+                        )
+                    if _typed_response is not None and _typed_response is not _response_obj:
+                        openai_responses_api_chunk.response = _typed_response  # pyright: ignore[reportAttributeAccessIssue]  # reached only on the dict path, which only response-carrying terminal events produce
+                    _stamp_responses_usage_cost(_typed_response, self.logging_obj)
 
                     if _chunk_type == openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED:
                         self._handle_logging_failed_response()
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index 8cf9556761e..30a7c4faaed 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -852,9 +852,10 @@ async def test_completed_event_without_usage_counts_tool_input_deltas(tool_delta
 
 
 @pytest.mark.asyncio
-async def test_completed_event_with_a_dict_response_still_gets_the_usage_estimate():
+async def test_completed_event_with_a_dict_response_is_typed_and_billed():
     """transform_streaming_response can model_construct a terminal event whose
-    response stays a plain dict; the estimate must fill it without raising."""
+    response stays a plain dict; the iterator must type it so the estimated
+    usage reaches the cost stamping path."""
     dict_response: Final = {
         "id": "resp_dict",
         "model": "gpt-4o-mini",
@@ -874,12 +875,14 @@ async def test_completed_event_with_a_dict_response_still_gets_the_usage_estimat
 
     config: Final = Mock(spec=BaseResponsesAPIConfig)
     config.transform_streaming_response.side_effect = _transform
+    logging_obj: Final = _logging_obj_stub()
+    logging_obj._response_cost_calculator.return_value = 0.000704
     iterator: Final = _make_iterator(
         sse_events=[
             _sse_event({"type": "response.output_text.delta", "delta": "hello world"}),
             _sse_event({"type": "response.completed", "response": {}}),
         ],
-        logging_obj=_logging_obj_stub(),
+        logging_obj=logging_obj,
         config=config,
         request_data={"input": "count these input tokens please"},
     )
@@ -887,7 +890,11 @@ async def test_completed_event_with_a_dict_response_still_gets_the_usage_estimat
     async for _ in iterator:
         pass
 
-    usage: Final = iterator.completed_response.response["usage"]
+    completed_response: Final = iterator.completed_response.response
+    assert isinstance(completed_response, ResponsesAPIResponse)
+    usage: Final = completed_response.usage
     assert usage is not None
     assert usage.input_tokens > 0
     assert usage.output_tokens > 0
+    assert usage.cost == pytest.approx(0.000704)
+    logging_obj._response_cost_calculator.assert_any_call(result=completed_response)

From a6fb21c3f86cfb645b0e94c46c0ea6c8a1955d91 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 20:26:20 -0700
Subject: [PATCH 58/67] fix(e2e): record cookie-setting provider responses and
 keep prompt-caching tests live

The first cache-enabled litellm-e2e build (211) showed three gaps in the shared provider cache:

Every OpenAI response carries Cloudflare bot-management Set-Cookie headers, and the capture rejected any response with Set-Cookie, so no OpenAI response was ever recorded (179 of 372 misses rejected). The edge already withholds Set-Cookie from the proxy, so drop it before validating and storing instead of rejecting.

The provider prompt-caching tests need fresh provider state: a replayed priming response reports cache creation rather than a cache read, and the TPM test then trips the key limit. Mark both modules provider_live.

TestApiBaseSeam::test_live_mode_returns_none ran inside the cache-enabled runner and saw the shared edge; isolate it from E2E_PROVIDER_CACHE.
---
 tests/code_coverage_tests/test_provider_cache.py      | 11 +++++++++++
 tests/e2e/PROVIDER_CACHE.md                           |  4 ++--
 tests/e2e/llm_translation/test_cache_control.py       |  2 +-
 tests/e2e/provider_cache.py                           | 10 ++++++----
 .../ratelimit/test_tpm_excludes_cached_tokens_e2e.py  |  2 +-
 tests/e2e/test_provider_edge.py                       |  3 ++-
 6 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 9d89a5fe622..828227ed239 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -38,6 +38,7 @@ class Provider(ThreadingHTTPServer):
     delay: float = 0
     stream: bool = False
     truncated: bool = False
+    cookie: str = ""
 
 
 class Handler(BaseHTTPRequestHandler):
@@ -62,6 +63,8 @@ class Handler(BaseHTTPRequestHandler):
             return
         self.send_header("content-type", "application/json")
         self.send_header("content-length", str(len(server.response)))
+        if server.cookie:
+            self.send_header("set-cookie", server.cookie)
         self.end_headers()
         self.wfile.write(server.response)
 
@@ -172,6 +175,14 @@ def test_failed_provider_responses_never_enter_cache(store: RedisResponseStore,
     assert len(provider.hits) == 2
 
 
+def test_cookie_setting_success_is_reused_without_the_cookie(store: RedisResponseStore, provider: Provider) -> None:
+    provider.cookie = "__cf_bm=synthetic-bot-management; Path=/; HttpOnly; Secure"
+    with edge(CacheEdge(store, SECRET), provider) as url:
+        replies: Final = tuple(call(url) for _ in range(2))
+    assert len(provider.hits) == 1
+    assert all(reply.body == SUCCESS and "set-cookie" not in reply.headers for reply in replies)
+
+
 def test_expiry_does_not_slide(store: RedisResponseStore, provider: Provider) -> None:
     short: Final = replace(store, lifetime_ms=250)
     with edge(CacheEdge(short, SECRET), provider) as url:
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index efd9eb66daa..8635c9ed9ae 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -2,7 +2,7 @@
 
 `E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
 
-The edge caches complete successful POST responses for `/v1/chat/completions` and `/v1/messages`, including streams. Unsupported endpoints pass through. It matches the method, original URL, effective outbound headers (including authentication and HTTP-library defaults), body presence and exact body bytes using a full keyed digest. It sends the same prepared request used for matching. No prompts, random markers, JSON values or credentials are normalized away
+The edge caches complete successful POST responses for `/v1/chat/completions` and `/v1/messages`, including streams. Unsupported endpoints pass through. It matches the method, original URL, effective outbound headers (including authentication and HTTP-library defaults), body presence and exact body bytes using a full keyed digest. It sends the same prepared request used for matching. No prompts, random markers, JSON values or credentials are normalized away. Provider `Set-Cookie` headers are dropped before validation and never recorded: the edge already withholds them from the proxy, and OpenAI responses always carry Cloudflare bot-management cookies
 
 An eligible miss calls the provider. A complete successful response is stored immediately even if a later test assertion fails. Provider errors, malformed responses, truncated streams and cancelled captures are not stored. Cache reads, writes and lease failures fall through to normal provider behavior; they introduce no provider retry. An already-started response cannot be restarted after a delivery failure
 
@@ -20,7 +20,7 @@ The trusted runner receives:
 
 Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
 
-Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
+Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
 
 ## Recorded response semantics
 
diff --git a/tests/e2e/llm_translation/test_cache_control.py b/tests/e2e/llm_translation/test_cache_control.py
index a18e03c982b..102b3f00698 100644
--- a/tests/e2e/llm_translation/test_cache_control.py
+++ b/tests/e2e/llm_translation/test_cache_control.py
@@ -44,7 +44,7 @@ from models import ChatBody, ChatMessage, ChatResponse, LiteLLMParamsBody, Usage
 from passthrough_client import PassthroughClient
 import os
 
-pytestmark = pytest.mark.e2e
+pytestmark = [pytest.mark.e2e, pytest.mark.provider_live]
 
 BEDROCK_MODEL = "bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0"
 VERTEX_MODEL = "vertex_ai/gemini-2.5-flash"
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 50b336f5263..0c6eac75a43 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -28,6 +28,7 @@ from pydantic import BaseModel, ConfigDict, JsonValue, TypeAdapter, ValidationEr
 LIFETIME_SECONDS: Final = 86_400
 MAX_REQUEST_BYTES: Final = 256 * 1024
 MAX_RESPONSE_BYTES: Final = 8 * 1024 * 1024
+UNRECORDED_RESPONSE_HEADERS: Final = frozenset({"set-cookie"})
 JSON_VALUE: Final[TypeAdapter[JsonValue]] = TypeAdapter(JsonValue)
 
 
@@ -104,8 +105,6 @@ def cacheable_endpoint(method: str, url: str, body: bytes | None) -> bool:
 def successful_response(url: str, status: int, headers: Mapping[str, str], body: bytes) -> bool:
     if not 200 <= status < 300 or len(body) > MAX_RESPONSE_BYTES:
         return False
-    if any(name.lower() == "set-cookie" for name in headers):
-        return False
     streaming: Final = "text/event-stream" in headers.get("content-type", "").lower()
     if streaming:
         try:
@@ -283,11 +282,14 @@ class CacheEdge:
                     yield step
                     capture.observe(step)
             chunks: Final = capture.chunks() if capture.eligible else ()
-            if not capture.eligible or not successful_response(url, head.status_code, head.headers, b"".join(chunks)):
+            headers: Final = {
+                name: value for name, value in head.headers.items() if name.lower() not in UNRECORDED_RESPONSE_HEADERS
+            }
+            if not capture.eligible or not successful_response(url, head.status_code, headers, b"".join(chunks)):
                 self.counters.increment("rejected")
                 return
             response: Final = CachedResponse(
-                request_key=key, status_code=head.status_code, headers=head.headers,
+                request_key=key, status_code=head.status_code, headers=headers,
                 chunks=tuple(base64.b64encode(chunk).decode("ascii") for chunk in chunks),
             )
             published: Final = self.store.publish(key, lease, encode_response(self.secret, response))
diff --git a/tests/e2e/quota_management/ratelimit/test_tpm_excludes_cached_tokens_e2e.py b/tests/e2e/quota_management/ratelimit/test_tpm_excludes_cached_tokens_e2e.py
index b0bc6b3508c..33d869ee80e 100644
--- a/tests/e2e/quota_management/ratelimit/test_tpm_excludes_cached_tokens_e2e.py
+++ b/tests/e2e/quota_management/ratelimit/test_tpm_excludes_cached_tokens_e2e.py
@@ -26,7 +26,7 @@ from models import (
 )
 from quota_client import QuotaClient
 
-pytestmark = pytest.mark.e2e
+pytestmark = [pytest.mark.e2e, pytest.mark.provider_live]
 
 # Anthropic prompt caching (host has ANTHROPIC_API_KEY; Bedrock was "Operation not allowed").
 ANTHROPIC_MODEL = "anthropic/claude-haiku-4-5-20251001"
diff --git a/tests/e2e/test_provider_edge.py b/tests/e2e/test_provider_edge.py
index 81be81e7b59..5d0c79f26f6 100644
--- a/tests/e2e/test_provider_edge.py
+++ b/tests/e2e/test_provider_edge.py
@@ -1254,7 +1254,8 @@ class TestHandleEdgeRequestPure:
 
 
 class TestApiBaseSeam:
-    def test_live_mode_returns_none(self, tmp_path: Path) -> None:
+    def test_live_mode_returns_none(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("E2E_PROVIDER_CACHE", raising=False)
         for mode_raw in ("live", ""):
             assert (
                 provider_edge_api_base(

From 06fcc1f733040a2a83f0131c8b9cdaaf3ab63f1f Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 03:28:08 +0000
Subject: [PATCH 59/67] feat(router): stream shadow traffic and fan out
 silent_model to multiple targets

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/router.py                             |  58 ++++--
 .../test_router_silent_experiment.py          | 188 +++++++++++++++++-
 2 files changed, 224 insertions(+), 22 deletions(-)

diff --git a/litellm/router.py b/litellm/router.py
index d531072530b..a8c74b1a72c 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -425,12 +425,27 @@ def _stream_chunks_have_generated_content(chunks: Sequence[ModelResponseStream])
 
 _NO_SESSION_KWARGS: Final[Mapping[str, Mapping[str, object]]] = MappingProxyType({})
 _SESSION_ADAPTER: Final = TypeAdapter(Mapping[str, object])
+_SILENT_MODEL_ADAPTER: Final = TypeAdapter(str | list[str])
 
 
 def _as_retry_skipped_deployment_ids(value: object) -> tuple[str, ...]:
     return tuple(item for item in value if isinstance(item, str)) if isinstance(value, tuple) else ()
 
 
+def _silent_experiment_targets(silent_model: object) -> tuple[str, ...]:
+    if silent_model is None:
+        return ()
+    try:
+        targets: Final = _SILENT_MODEL_ADAPTER.validate_python(silent_model)
+    except ValidationError:
+        verbose_router_logger.warning(
+            "silent_model must be a model name or a list of model names, got %r; skipping shadow traffic",
+            silent_model,
+        )
+        return ()
+    return (targets,) if isinstance(targets, str) else tuple(targets)
+
+
 def _with_router_resolved_session_model(session: object, model_name: str) -> Mapping[str, Mapping[str, object]]:
     """
     Realtime client-secret requests carry the model inside ``session`` as well, and the caller's copy of it still
@@ -2455,18 +2470,17 @@ class Router:
             )
             silent_model: Final = litellm_params.pop("silent_model", None)
 
-            if silent_model is not None:
+            for silent_target in _silent_experiment_targets(silent_model):
                 # Mirroring traffic to a secondary model
                 # Use threading.Thread (not ThreadPoolExecutor) - executor.submit()
                 # requires pickling args, which fails when kwargs contain unpicklable
                 # objects (e.g. _thread.RLock from OTEL spans, loggers) in deployment.
-                thread: Final = threading.Thread(
+                threading.Thread(
                     target=self._silent_experiment_completion,
-                    args=(silent_model, messages),
+                    args=(silent_target, messages),
                     kwargs=kwargs,
                     daemon=True,
-                )
-                thread.start()
+                ).start()
 
             kwargs.setdefault("messages", messages)
             self._update_kwargs_with_deployment(deployment=deployment, kwargs=kwargs)
@@ -2567,9 +2581,6 @@ class Router:
 
         silent_kwargs["metadata"]["is_silent_experiment"] = True
 
-        # Force stream=False so the response is fully consumed and callbacks fire
-        silent_kwargs["stream"] = False
-
         # Pop logging objects and call IDs to ensure a fresh logging context
         # This prevents collisions in the Proxy's database (spend_logs)
         silent_kwargs.pop("litellm_call_id", None)
@@ -2579,6 +2590,21 @@ class Router:
 
         return silent_kwargs
 
+    async def _run_silent_experiment(
+        self, silent_model: str, messages: Sequence[Mapping[str, str]], silent_kwargs: Mapping[str, object]
+    ) -> None:
+        remaining_kwargs: Final = {key: value for key, value in silent_kwargs.items() if key != "stream"}
+        response: Final = await self.acompletion(
+            model=silent_model,
+            messages=cast(list[AllMessageValues], messages),
+            stream=bool(silent_kwargs.get("stream", False)),
+            **remaining_kwargs,
+        )
+        if not isinstance(response, CustomStreamWrapper):
+            return
+        async for _ in response:
+            pass
+
     def _silent_experiment_completion(self, silent_model: str, messages: Sequence[Mapping[str, str]], **kwargs):
         """
         Run a silent experiment in the background (thread).
@@ -2604,11 +2630,7 @@ class Router:
             try:
 
                 async def _run_silent_completion():
-                    await self.acompletion(
-                        model=silent_model,
-                        messages=cast(list[AllMessageValues], messages),
-                        **silent_kwargs,
-                    )
+                    await self._run_silent_experiment(silent_model, messages, silent_kwargs)
                     # Drain any fire-and-forget tasks (e.g. alerting hooks)
                     # scheduled via asyncio.create_task during acompletion.
                     pending: Final = asyncio.all_tasks()
@@ -3500,11 +3522,7 @@ class Router:
             silent_kwargs["metadata"]["model_group"] = silent_model
 
             # Trigger the silent request
-            await self.acompletion(
-                model=silent_model,
-                messages=cast(list[AllMessageValues], messages),
-                **silent_kwargs,
-            )
+            await self._run_silent_experiment(silent_model, messages, silent_kwargs)
         except Exception as e:
             verbose_router_logger.error("Silent experiment failed for model %s: %s", silent_model, e)
 
@@ -3563,12 +3581,12 @@ class Router:
             )
             silent_model: Final = litellm_params.pop("silent_model", None)
 
-            if silent_model is not None:
+            for silent_target in _silent_experiment_targets(silent_model):
                 # Mirroring traffic to a secondary model
                 # This is a silent experiment, so we don't want to block the primary request
                 asyncio.create_task(
                     self._silent_experiment_acompletion(
-                        silent_model=silent_model,
+                        silent_model=silent_target,
                         messages=messages,  # Use messages instead of *args
                         **kwargs,
                     )
diff --git a/tests/test_litellm/test_router_silent_experiment.py b/tests/test_litellm/test_router_silent_experiment.py
index bfdf39bad71..eed688a79dd 100644
--- a/tests/test_litellm/test_router_silent_experiment.py
+++ b/tests/test_litellm/test_router_silent_experiment.py
@@ -1,11 +1,70 @@
 import asyncio
 import time
+from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
 import litellm
+from litellm.integrations.custom_logger import CustomLogger
 from litellm.router import Router
+from litellm.router import _silent_experiment_targets
+
+
+class _RecordingLogger(CustomLogger):
+    def __init__(self) -> None:
+        super().__init__()
+        self.success_kwargs: list[dict[str, object]] = []
+
+    async def async_log_success_event(self, kwargs, response_obj, start_time, end_time):
+        self.success_kwargs.append(kwargs)
+
+    def shadow_successes(self) -> list[dict[str, object]]:
+        return [
+            call
+            for call in self.success_kwargs
+            if call.get("litellm_params", {}).get("metadata", {}).get("is_silent_experiment") is True
+        ]
+
+
+@pytest.fixture
+def recording_logger():
+    original_callbacks: Final = litellm.callbacks
+    logger: Final = _RecordingLogger()
+    litellm.callbacks = [logger]
+    try:
+        yield logger
+    finally:
+        litellm.callbacks = original_callbacks
+
+
+async def _wait_for_shadow_successes(logger: _RecordingLogger, expected: int, timeout: float = 5.0) -> None:
+    deadline: Final = time.monotonic() + timeout
+    while len(logger.shadow_successes()) < expected and time.monotonic() < deadline:
+        await asyncio.sleep(0.05)
+
+
+def _wait_for_shadow_successes_sync(logger: _RecordingLogger, expected: int, timeout: float = 5.0) -> None:
+    deadline: Final = time.monotonic() + timeout
+    while len(logger.shadow_successes()) < expected and time.monotonic() < deadline:
+        time.sleep(0.05)
+
+
+def _streaming_model_list(silent_model: object) -> list[dict[str, object]]:
+    return [
+        {
+            "model_name": "primary-model",
+            "litellm_params": {"model": "openai/gpt-5.4-mini", "api_key": "fake-key", "silent_model": silent_model},
+        },
+        {
+            "model_name": "shadow-a",
+            "litellm_params": {"model": "openai/gpt-5.4-nano", "api_key": "fake-key", "silent_model": "shadow-b"},
+        },
+        {
+            "model_name": "shadow-b",
+            "litellm_params": {"model": "anthropic/claude-haiku-4-5", "api_key": "fake-key"},
+        },
+    ]
 
 
 class _NonCopyableSpan:
@@ -65,8 +124,8 @@ def test_get_silent_experiment_kwargs():
     assert result["metadata"]["is_silent_experiment"] is True
     assert result["metadata"]["foo"] == "bar"
     assert "litellm_call_id" not in result
-    # stream must be forced to False so callbacks fire in background
-    assert result["stream"] is False
+    # the shadow must stream exactly like the primary so TTFT / ITL metrics are comparable
+    assert result["stream"] is True
     # proxy_server_request must be preserved for spend log metadata
     assert "proxy_server_request" in result
     # CRITICAL: metadata must be a DIFFERENT dict object than the original,
@@ -86,6 +145,131 @@ def test_get_silent_experiment_kwargs():
     assert result["metadata"]["user_api_key_auth"] is mock_auth
 
 
+def test_get_silent_experiment_kwargs_without_stream_stays_non_streaming():
+    router = Router(model_list=[{"model_name": "m", "litellm_params": {"model": "gpt-3.5-turbo", "api_key": "k"}}])
+    result = router._get_silent_experiment_kwargs(metadata={"foo": "bar"}, stream=False)
+    assert result["stream"] is False
+    assert "stream" not in router._get_silent_experiment_kwargs(metadata={"foo": "bar"})
+
+
+@pytest.mark.parametrize(
+    "silent_model, expected",
+    [
+        ("shadow-a", ("shadow-a",)),
+        (["shadow-a", "shadow-b"], ("shadow-a", "shadow-b")),
+        ([], ()),
+        (None, ()),
+        (42, ()),
+        (["shadow-a", 42], ()),
+    ],
+)
+def test_silent_experiment_targets(silent_model, expected):
+    assert _silent_experiment_targets(silent_model) == expected
+
+
+@pytest.mark.asyncio
+async def test_streaming_shadow_is_streamed_and_drained_async(recording_logger):
+    router = Router(model_list=_streaming_model_list("shadow-a"))
+    response = await router.acompletion(
+        model="primary-model",
+        messages=[{"role": "user", "content": "hi"}],
+        stream=True,
+        stream_options={"include_usage": True},
+        mock_response="pong",
+        metadata={"foo": "bar"},
+    )
+    chunks = [chunk async for chunk in response]
+    assert chunks
+    await _wait_for_shadow_successes(recording_logger, expected=1)
+
+    shadow_successes = recording_logger.shadow_successes()
+    assert len(shadow_successes) == 1
+    shadow = shadow_successes[0]
+    assert shadow["stream"] is True
+    assert shadow["stream_options"] == {"include_usage": True}
+    assert shadow["litellm_params"]["metadata"]["model_group"] == "shadow-a"
+    assert shadow["async_complete_streaming_response"] is not None
+
+
+def test_streaming_shadow_is_streamed_and_drained_sync(recording_logger):
+    router = Router(model_list=_streaming_model_list("shadow-a"))
+    response = router.completion(
+        model="primary-model",
+        messages=[{"role": "user", "content": "hi"}],
+        stream=True,
+        mock_response="pong",
+        metadata={"foo": "bar"},
+    )
+    chunks = list(response)
+    assert chunks
+    _wait_for_shadow_successes_sync(recording_logger, expected=1)
+
+    shadow_successes = recording_logger.shadow_successes()
+    assert len(shadow_successes) == 1
+    assert shadow_successes[0]["stream"] is True
+    assert shadow_successes[0]["litellm_params"]["metadata"]["model_group"] == "shadow-a"
+    assert shadow_successes[0]["async_complete_streaming_response"] is not None
+
+
+@pytest.mark.asyncio
+async def test_multiple_shadow_targets_fan_out_async(recording_logger):
+    router = Router(model_list=_streaming_model_list(["shadow-a", "shadow-b"]))
+    metadata = {"foo": "bar"}
+    response = await router.acompletion(
+        model="primary-model",
+        messages=[{"role": "user", "content": "hi"}],
+        stream=True,
+        mock_response="pong",
+        metadata=metadata,
+    )
+    assert [chunk async for chunk in response]
+    await _wait_for_shadow_successes(recording_logger, expected=2)
+
+    shadow_successes = recording_logger.shadow_successes()
+    model_groups = sorted(call["litellm_params"]["metadata"]["model_group"] for call in shadow_successes)
+    assert model_groups == ["shadow-a", "shadow-b"]
+    shadow_metadatas = [call["litellm_params"]["metadata"] for call in shadow_successes]
+    assert shadow_metadatas[0] is not shadow_metadatas[1]
+    assert all(call["stream"] is True for call in shadow_successes)
+    assert "is_silent_experiment" not in metadata
+    assert metadata.get("model_group") != "shadow-a"
+    primary_successes = [call for call in recording_logger.success_kwargs if call not in shadow_successes]
+    assert len(primary_successes) == 1
+    assert primary_successes[0]["litellm_params"]["metadata"]["model_group"] == "primary-model"
+
+
+def test_multiple_shadow_targets_fan_out_sync(recording_logger):
+    router = Router(model_list=_streaming_model_list(["shadow-a", "shadow-b"]))
+    response = router.completion(
+        model="primary-model",
+        messages=[{"role": "user", "content": "hi"}],
+        mock_response="pong",
+        metadata={"foo": "bar"},
+    )
+    assert response.choices[0].message.content == "pong"
+    _wait_for_shadow_successes_sync(recording_logger, expected=2)
+
+    shadow_successes = recording_logger.shadow_successes()
+    model_groups = sorted(call["litellm_params"]["metadata"]["model_group"] for call in shadow_successes)
+    assert model_groups == ["shadow-a", "shadow-b"]
+    assert all(call["stream"] is False for call in shadow_successes)
+
+
+@pytest.mark.asyncio
+async def test_shadow_of_a_shadow_is_not_launched(recording_logger):
+    router = Router(model_list=_streaming_model_list(["shadow-a"]))
+    response = await router.acompletion(
+        model="primary-model",
+        messages=[{"role": "user", "content": "hi"}],
+        mock_response="pong",
+    )
+    assert response.choices[0].message.content == "pong"
+    await _wait_for_shadow_successes(recording_logger, expected=2, timeout=1.0)
+
+    model_groups = [call["litellm_params"]["metadata"]["model_group"] for call in recording_logger.shadow_successes()]
+    assert model_groups == ["shadow-a"]
+
+
 def test_silent_experiment_completion_direct():
     """
     Test _silent_experiment_completion directly (for router code coverage).

From 7cc07d437a3d76b5f42204adf6f4561150957a3c Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 03:47:03 +0000
Subject: [PATCH 60/67] fix(responses): build the billed terminal response
 immutably and guard the cache dump

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py       | 90 +++++++++++++------
 .../responses/test_streaming_iterator.py      | 50 ++++++++++-
 2 files changed, 112 insertions(+), 28 deletions(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index 3004337f9d1..d6d3e2576f6 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -427,39 +427,45 @@ class BaseResponsesAPIStreamingIterator:
                     openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
                     openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED,
                 ):
-                    self.completed_response = openai_responses_api_chunk
                     _response_obj: Final[object] = getattr(openai_responses_api_chunk, "response", None)
-                    _typed_response: Final[ResponsesAPIResponse | None] = (
-                        ResponsesAPIResponse.model_construct(**_response_obj)  # pyright: ignore[reportUnknownArgumentType]  # the model_constructed terminal event leaves response as an untyped dict
-                        if isinstance(_response_obj, dict)
-                        else _response_obj
-                        if isinstance(_response_obj, ResponsesAPIResponse)
-                        else None
+                    _estimate_wanted: Final[bool] = _chunk_type in (
+                        openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
+                        openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
                     )
-                    if (
-                        _typed_response is not None
-                        and _chunk_type
-                        in (
-                            openai_types.ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
-                            openai_types.ResponsesAPIStreamEvents.RESPONSE_INCOMPLETE,
+                    _billed_response: Final[ResponsesAPIResponse | None] = _billed_terminal_response(
+                        _response_obj,
+                        (
+                            lambda: (
+                                _estimate_usage_safely(
+                                    self.model or "",
+                                    self.request_data.get("input"),
+                                    self.request_data,
+                                    self._generated_content + self._generated_tool_arguments,
+                                )
+                                if _estimate_wanted
+                                else None
+                            )
+                        ),
+                    )
+                    _terminal_chunk: Final = (
+                        openai_responses_api_chunk
+                        if _billed_response is None or _billed_response is _response_obj
+                        else (
+                            openai_responses_api_chunk.model_copy(update={"response": _billed_response})
+                            if issubclass(type(openai_responses_api_chunk), BaseModel)  # pyright: ignore[reportUnnecessaryIsInstance]  # test stubs use spec'd Mocks whose __class__ reports BaseModel but whose model_copy returns a Mock
+                            else _replace_response(openai_responses_api_chunk, _billed_response)
                         )
-                        and _typed_response.usage is None
-                    ):
-                        _typed_response.usage = _estimate_usage_safely(
-                            self.model or "",
-                            self.request_data.get("input"),
-                            self.request_data,
-                            self._generated_content + self._generated_tool_arguments,
-                        )
-                    if _typed_response is not None and _typed_response is not _response_obj:
-                        openai_responses_api_chunk.response = _typed_response  # pyright: ignore[reportAttributeAccessIssue]  # reached only on the dict path, which only response-carrying terminal events produce
-                    _stamp_responses_usage_cost(_typed_response, self.logging_obj)
+                    )
+                    self.completed_response = _terminal_chunk
+                    _stamp_responses_usage_cost(_billed_response, self.logging_obj)
 
                     if _chunk_type == openai_types.ResponsesAPIStreamEvents.RESPONSE_FAILED:
                         self._handle_logging_failed_response()
                     else:
                         self._handle_logging_completed_response()
 
+                    return _terminal_chunk
+
                 return openai_responses_api_chunk
 
             return None
@@ -688,7 +694,9 @@ class BaseResponsesAPIStreamingIterator:
         if cache is None:
             return
 
-        cached_response: Final = response_obj.model_dump_json()
+        cached_response: Final = _dump_json_safely(response_obj)
+        if cached_response is None:
+            return
         if is_async:
             from litellm.caching.caching_handler import create_cache_write_task
 
@@ -1334,6 +1342,38 @@ def _add_text_like_part_events(
         )
 
 
+def _billed_terminal_response(
+    response_obj: object, estimate: Callable[[], ResponseAPIUsage | None] | None
+) -> ResponsesAPIResponse | None:
+    if isinstance(response_obj, ResponsesAPIResponse):
+        return (
+            response_obj
+            if response_obj.usage is not None or estimate is None
+            else response_obj.model_copy(update={"usage": estimate()})
+        )
+    if not isinstance(response_obj, dict):
+        return None
+    usage: Final[object] = response_obj.get("usage")  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]  # a model_constructed terminal event leaves response as an untyped dict
+    return ResponsesAPIResponse.model_construct(
+        **{**response_obj, "usage": usage if usage is not None or estimate is None else estimate()}  # pyright: ignore[reportUnknownArgumentType, reportArgumentType]  # same untyped dict spread
+    )
+
+
+def _replace_response(
+    event: ResponsesAPIStreamingResponse, response: ResponsesAPIResponse
+) -> ResponsesAPIStreamingResponse:
+    setattr(event, "response", response)
+    return event
+
+
+def _dump_json_safely(response: BaseModel) -> str | None:
+    try:
+        return response.model_dump_json()
+    except Exception as exc:
+        verbose_logger.debug("could not serialize completed response for cache: %s", exc)
+        return None
+
+
 def _logging_copy(event: object) -> object:
     """Hand logging callbacks a copy, so their usage rewrite (Responses shape to chat shape) never
     reaches the event the caller is iterating. The round trip through ``model_dump`` sidesteps the
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index 30a7c4faaed..b33cc4e93c2 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -10,6 +10,7 @@ from unittest.mock import Mock, patch
 
 import httpx
 import pytest
+from pydantic_core import PydanticSerializationError
 
 import litellm
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
@@ -887,10 +888,11 @@ async def test_completed_event_with_a_dict_response_is_typed_and_billed():
         request_data={"input": "count these input tokens please"},
     )
 
-    async for _ in iterator:
-        pass
+    yielded: Final = [chunk async for chunk in iterator]
 
-    completed_response: Final = iterator.completed_response.response
+    terminal_event: Final = iterator.completed_response
+    assert yielded[-1] is terminal_event
+    completed_response: Final = terminal_event.response
     assert isinstance(completed_response, ResponsesAPIResponse)
     usage: Final = completed_response.usage
     assert usage is not None
@@ -898,3 +900,45 @@ async def test_completed_event_with_a_dict_response_is_typed_and_billed():
     assert usage.output_tokens > 0
     assert usage.cost == pytest.approx(0.000704)
     logging_obj._response_cost_calculator.assert_any_call(result=completed_response)
+
+
+def test_billed_terminal_response_keeps_a_response_that_already_has_usage():
+    from litellm.responses.streaming_iterator import _billed_terminal_response
+
+    response: Final = _responses_api_response_with_usage()
+
+    assert _billed_terminal_response(response, None) is response
+
+
+def test_billed_terminal_response_copies_when_estimating_and_leaves_the_original_untouched():
+    from litellm.responses.streaming_iterator import _billed_terminal_response
+
+    response: Final = _responses_api_response_without_usage()
+    estimated: Final = ResponseAPIUsage(input_tokens=3, output_tokens=4, total_tokens=7)
+
+    billed: Final = _billed_terminal_response(response, lambda: estimated)
+
+    assert billed is not response
+    assert billed.usage is estimated
+    assert response.usage is None
+
+
+def test_persist_completed_response_to_cache_survives_an_unserializable_response(monkeypatch):
+    bad_response: Final = ResponsesAPIResponse.model_construct(id="r", output=[object()], usage=None)
+    with pytest.raises(PydanticSerializationError):
+        bad_response.model_dump_json()
+
+    logging_obj: Final = _logging_obj_stub()
+    caching_handler: Final = Mock()
+    caching_handler.request_kwargs = {"stream": True}
+    logging_obj._llm_caching_handler = caching_handler
+    iterator: Final = _make_iterator(sse_events=[], logging_obj=logging_obj)
+    iterator.completed_response = ResponseCompletedEvent.model_construct(
+        type="response.completed", response=bad_response
+    )
+    cache: Final = Mock()
+    monkeypatch.setattr(litellm, "cache", cache)
+
+    iterator._persist_completed_response_to_cache(is_async=False)
+
+    cache.add_cache.assert_not_called()

From 9cabde90dd3e6d1101c6d89487d0a8e683b4df2f Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 03:48:32 +0000
Subject: [PATCH 61/67] test(router): cover _run_silent_experiment directly for
 router coverage gate

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../test_router_silent_experiment.py          | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/tests/test_litellm/test_router_silent_experiment.py b/tests/test_litellm/test_router_silent_experiment.py
index eed688a79dd..79ce18e40b8 100644
--- a/tests/test_litellm/test_router_silent_experiment.py
+++ b/tests/test_litellm/test_router_silent_experiment.py
@@ -311,6 +311,25 @@ async def test_silent_experiment_acompletion_direct():
         )
 
 
+@pytest.mark.asyncio
+async def test_run_silent_experiment_drains_stream_so_callbacks_fire(recording_logger):
+    router = Router(model_list=_streaming_model_list(None))
+    silent_kwargs: Final = {
+        "stream": True,
+        "stream_options": {"include_usage": True},
+        "mock_response": "pong",
+        "metadata": {"is_silent_experiment": True, "model_group": "shadow-b"},
+    }
+    await router._run_silent_experiment("shadow-b", [{"role": "user", "content": "hi"}], silent_kwargs)
+    await _wait_for_shadow_successes(recording_logger, expected=1)
+
+    shadow_successes = recording_logger.shadow_successes()
+    assert len(shadow_successes) == 1
+    assert shadow_successes[0]["stream"] is True
+    assert shadow_successes[0]["async_complete_streaming_response"] is not None
+    assert silent_kwargs["stream"] is True
+
+
 @pytest.mark.asyncio
 async def test_router_silent_experiment_acompletion():
     """

From ff878e7df06e85a0c6ee2a75f1541894929e0af2 Mon Sep 17 00:00:00 2001
From: kerry <kerry@berri.ai>
Date: Wed, 16 Sep 2026 03:54:04 +0000
Subject: [PATCH 62/67] refactor(responses): copy the terminal event instead of
 mutating stubbed chunks

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/responses/streaming_iterator.py          | 13 +------------
 .../responses/test_streaming_iterator.py         | 16 ++++++++--------
 2 files changed, 9 insertions(+), 20 deletions(-)

diff --git a/litellm/responses/streaming_iterator.py b/litellm/responses/streaming_iterator.py
index d6d3e2576f6..8d766cf1cd0 100644
--- a/litellm/responses/streaming_iterator.py
+++ b/litellm/responses/streaming_iterator.py
@@ -450,11 +450,7 @@ class BaseResponsesAPIStreamingIterator:
                     _terminal_chunk: Final = (
                         openai_responses_api_chunk
                         if _billed_response is None or _billed_response is _response_obj
-                        else (
-                            openai_responses_api_chunk.model_copy(update={"response": _billed_response})
-                            if issubclass(type(openai_responses_api_chunk), BaseModel)  # pyright: ignore[reportUnnecessaryIsInstance]  # test stubs use spec'd Mocks whose __class__ reports BaseModel but whose model_copy returns a Mock
-                            else _replace_response(openai_responses_api_chunk, _billed_response)
-                        )
+                        else openai_responses_api_chunk.model_copy(update={"response": _billed_response})
                     )
                     self.completed_response = _terminal_chunk
                     _stamp_responses_usage_cost(_billed_response, self.logging_obj)
@@ -1359,13 +1355,6 @@ def _billed_terminal_response(
     )
 
 
-def _replace_response(
-    event: ResponsesAPIStreamingResponse, response: ResponsesAPIResponse
-) -> ResponsesAPIStreamingResponse:
-    setattr(event, "response", response)
-    return event
-
-
 def _dump_json_safely(response: BaseModel) -> str | None:
     try:
         return response.model_dump_json()
diff --git a/tests/test_litellm/responses/test_streaming_iterator.py b/tests/test_litellm/responses/test_streaming_iterator.py
index b33cc4e93c2..dbf54ec3b9b 100644
--- a/tests/test_litellm/responses/test_streaming_iterator.py
+++ b/tests/test_litellm/responses/test_streaming_iterator.py
@@ -47,10 +47,10 @@ def _mock_config() -> Mock:
     def _transform(model, parsed_chunk, logging_obj):
         evt_type = parsed_chunk.get("type")
         if evt_type == "response.completed":
-            completed = Mock(spec=ResponseCompletedEvent)
-            completed.type = ResponsesAPIStreamEvents.RESPONSE_COMPLETED
-            completed.response = mock_responses_api_response
-            return completed
+            return ResponseCompletedEvent(
+                type=ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
+                response=mock_responses_api_response,
+            )
         stub = Mock()
         stub.type = evt_type
         return stub
@@ -348,10 +348,10 @@ def _mock_config_with_completed_response(response: ResponsesAPIResponse) -> Mock
     def _transform(model, parsed_chunk, logging_obj):
         evt_type = parsed_chunk.get("type")
         if evt_type == "response.completed":
-            completed = Mock(spec=ResponseCompletedEvent)
-            completed.type = ResponsesAPIStreamEvents.RESPONSE_COMPLETED
-            completed.response = response
-            return completed
+            return ResponseCompletedEvent(
+                type=ResponsesAPIStreamEvents.RESPONSE_COMPLETED,
+                response=response,
+            )
         stub = Mock()
         stub.type = evt_type
         if "delta" in parsed_chunk:

From 9d640b86ed1874562e6b3bbd68242e2923f38275 Mon Sep 17 00:00:00 2001
From: Tin Chi Lo <tin@berri.ai>
Date: Tue, 15 Sep 2026 20:58:38 -0700
Subject: [PATCH 63/67] fix(ui): simplify Capability and Fuse routing options

---
 .../add_model/ComplexityRouterConfig.tsx      | 42 +++++++++----------
 ...ecastClassifierConfig.integration.test.tsx |  2 +-
 .../add_model/add_auto_router_tab.test.tsx    | 18 ++++++--
 .../build_complexity_router_config.test.ts    | 31 ++++++++++++++
 .../build_complexity_router_config.ts         | 27 ++++++------
 .../forecast_classifier_config.test.ts        |  2 +-
 ...d_updated_complexity_router_config.test.ts | 37 ++++++++++++++++
 .../edit_auto_router_modal.tsx                |  5 ++-
 8 files changed, 122 insertions(+), 42 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx
index 4ccabff18b9..f6b50ce20bc 100644
--- a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx
@@ -794,19 +794,15 @@ const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
                   },
                 ]
               : []),
-            ...(value.classifier_type !== "llm_v2"
-              ? [
-                  {
-                    key: "adaptive",
-                    label: <strong className="text-foreground font-semibold">Advanced: Adaptive Routing</strong>,
-                    children: (
-                      <Restricted by={restrictedBy(value, "adaptive")}>
-                        <AdaptiveRoutingConfig value={value} onChange={onChange} />
-                      </Restricted>
-                    ),
-                  },
-                ]
-              : []),
+            {
+              key: "adaptive",
+              label: <strong className="text-foreground font-semibold">Advanced: Adaptive Routing</strong>,
+              children: (
+                <Restricted by={restrictedBy(value, "adaptive")}>
+                  <AdaptiveRoutingConfig value={value} onChange={onChange} />
+                </Restricted>
+              ),
+            },
             {
               key: "affinity",
               label: <strong className="text-foreground font-semibold">Advanced: Affinity</strong>,
@@ -906,15 +902,17 @@ const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
                   },
                 ]
               : []),
-          ].map(({ key, label, children }) => (
-            <Collapsible key={key} className="border-b border-border last:border-b-0">
-              <CollapsibleTrigger className="group flex w-full items-center gap-2 px-4 py-3 text-left">
-                <ChevronRight className="size-4 shrink-0 text-muted-foreground transition-transform group-data-panel-open:rotate-90" />
-                {label}
-              </CollapsibleTrigger>
-              <CollapsibleContent className="px-4 pb-4">{children}</CollapsibleContent>
-            </Collapsible>
-          ))}
+          ]
+            .filter(({ key }) => !forecast || !["adaptive", "context-window", "escalation"].includes(key))
+            .map(({ key, label, children }) => (
+              <Collapsible key={key} className="border-b border-border last:border-b-0">
+                <CollapsibleTrigger className="group flex w-full items-center gap-2 px-4 py-3 text-left">
+                  <ChevronRight className="size-4 shrink-0 text-muted-foreground transition-transform group-data-panel-open:rotate-90" />
+                  {label}
+                </CollapsibleTrigger>
+                <CollapsibleContent className="px-4 pb-4">{children}</CollapsibleContent>
+              </Collapsible>
+            ))}
         </div>
       </RoutingOptions>
     </div>
diff --git a/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx b/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx
index c249a63899a..4a574ac736d 100644
--- a/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ForecastClassifierConfig.integration.test.tsx
@@ -105,7 +105,7 @@ describe("forecast classifier form", () => {
     expect(output).toHaveTextContent('"REASONING":["capable"]');
     expect(output).toHaveTextContent('"reasoning_effort":"low","speed":"fast","max_tokens":1024');
     expect(output).toHaveTextContent('"reasoning_effort":"high"');
-    expect(output).toHaveTextContent('"adaptive":true');
+    expect(output).toHaveTextContent('"adaptive":false');
     expect(output).not.toHaveTextContent("leftover-medium");
     expect(output).not.toHaveTextContent("leftover-complex");
     expect(output).not.toHaveTextContent('"plan_mode_min_tier"');
diff --git a/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx b/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx
index b98636c9c5c..48903d585ff 100644
--- a/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx
@@ -213,17 +213,24 @@ describe("AddAutoRouterTab", () => {
       expect(screen.queryByRole("alert")).not.toBeInTheDocument();
       expect(screen.getByRole("button", { name: "Add Auto Router" })).toBeEnabled();
       await user.click(screen.getByRole("button", { name: "Advanced routing options" }));
-      if (capability) expect(screen.getByText("Advanced: Adaptive Routing")).toBeInTheDocument();
-      else expect(screen.queryByText("Advanced: Adaptive Routing")).not.toBeInTheDocument();
+      for (const label of ["Adaptive Routing", "Context Window Escalation", "Escalation Keywords"]) {
+        expect(screen.queryByText(`Advanced: ${label}`)).not.toBeInTheDocument();
+      }
+      expect(screen.getByText("Advanced: Stalled Task Escalation")).toBeInTheDocument();
+      expect(screen.getByText("Advanced: Response Format")).toBeInTheDocument();
       expect(screen.queryByText("Advanced: Classification Method")).not.toBeInTheDocument();
       expect(screen.getByText("Advanced: Affinity")).toBeInTheDocument();
       await user.click(screen.getByRole("button", { name: "Add Auto Router" }));
       await waitFor(() => expect(handleAddAutoRouterSubmit).toHaveBeenCalledTimes(1));
-      expect(vi.mocked(handleAddAutoRouterSubmit).mock.calls[0][0].complexity_router_config).toMatchObject({
+      const expected = {
         classifier_type: capability ? "capability" : "llm_v2",
+        adaptive: false,
+        enable_context_window_escalation: false,
+        escalation_keywords: [],
         tiers: { SIMPLE: ["efficient"], REASONING: ["capable"] },
         classifier_llm_config: { model: "judge" },
-      });
+      };
+      expect(vi.mocked(handleAddAutoRouterSubmit).mock.calls[0][0].complexity_router_config).toMatchObject(expected);
     },
   );
 
@@ -239,6 +246,9 @@ describe("AddAutoRouterTab", () => {
     expect(screen.getByTestId("template-selector")).toBeInTheDocument();
     expandDetailedConfiguration();
     expect(screen.getByText("Complexity Tier Configuration")).toBeInTheDocument();
+    for (const label of ["Adaptive Routing", "Context Window Escalation", "Escalation Keywords"]) {
+      expect(screen.getByText(`Advanced: ${label}`)).toBeInTheDocument();
+    }
     await user.click(screen.getByText("Advanced: Classification Method"));
     expect(screen.queryByRole("radio", { name: /^Capability/ })).not.toBeInTheDocument();
     expect(screen.queryByRole("radio", { name: /^Fuse v2/ })).not.toBeInTheDocument();
diff --git a/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.test.ts b/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.test.ts
index bc30b591ea9..6e6e7a3c6cd 100644
--- a/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.test.ts
+++ b/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.test.ts
@@ -48,6 +48,37 @@ const baseParams: BuildComplexityRouterConfigParams = {
 };
 
 describe("buildComplexityRouterConfig", () => {
+  it.each(["capability", "llm_v2", "heuristic"] as const)(
+    "disables the removed overrides only for forecast creates: %s",
+    (classifierType) => {
+      const forecast = classifierType !== "heuristic";
+      const params = {
+        ...baseParams,
+        classifierType,
+        adaptive: true,
+        enableContextWindowEscalation: true,
+        contextWindowEscalationBuffer: 0.9,
+      };
+      const config = buildComplexityRouterConfig(params);
+      expect(config.adaptive).toBe(!forecast);
+      expect(config.enable_context_window_escalation).toBe(!forecast);
+      expect(config.escalation_keywords).toEqual(forecast ? [] : ["LITELLM ESCALATE"]);
+      for (const key of [
+        "adaptive_weights",
+        "adaptive_eligible",
+        "tier_distance_penalty",
+        "context_window_escalation_buffer",
+      ]) {
+        expect(Object.hasOwn(config, key)).toBe(!forecast);
+      }
+      if (forecast) {
+        const untouched = buildComplexityRouterConfig({ ...baseParams, classifierType });
+        expect(untouched.enable_context_window_escalation).toBe(false);
+        expect(untouched.escalation_keywords).toEqual([]);
+      }
+    },
+  );
+
   it("carries Fast and reasoning overrides independently into a new router payload", () => {
     const params = { speed: "fast", reasoning_effort: "high", max_tokens: 1024 };
     const config = buildComplexityRouterConfig({
diff --git a/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts b/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts
index d16be537ce6..8a377c17ad7 100644
--- a/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts
+++ b/ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts
@@ -628,13 +628,11 @@ export const buildComplexityRouterConfig = ({
   // An edited tier set forces the LLM classifier, so llm-only inputs must survive a classifier_type
   // the form never rewrote. The UI gates the same controls on this, not on the raw value.
   const effectiveType: ClassifierType = customTierSet ? "llm" : classifierType;
+  const forecast = isForecastClassifier(effectiveType);
 
-  const supportsOpeningPrompt =
-    !customTierSet && !isForecastClassifier(effectiveType) && usesLlmClassifier(effectiveType);
+  const supportsOpeningPrompt = !customTierSet && !forecast && usesLlmClassifier(effectiveType);
   const payload: ComplexityRouterConfigPayload = {
-    tiers: isForecastClassifier(effectiveType)
-      ? Object.fromEntries(Object.entries(tiers).filter(([, models]) => models.length > 0))
-      : tiers,
+    tiers: forecast ? Object.fromEntries(Object.entries(tiers).filter(([, models]) => models.length > 0)) : tiers,
     // The backend rejects the flag beside a custom tier set.
     ...(!customTierSet && enableNonReasoningTier && { enable_non_reasoning_tier: true }),
     ...(serializedTierModelConfigs && { tier_model_configs: serializedTierModelConfigs }),
@@ -645,7 +643,8 @@ export const buildComplexityRouterConfig = ({
     ...classifierWireFields(effectiveType, classifierInputs),
     ...(effectiveType === "capability" &&
       capabilityClassifierConfig && { capability_classifier_config: capabilityClassifierConfig }),
-    ...(effectiveType === "llm_v2" && { llm_v2_config: llmV2Config, adaptive: false }),
+    ...(effectiveType === "llm_v2" && { llm_v2_config: llmV2Config }),
+    ...(forecast && { adaptive: false }),
     // A built-in router's opening instructions. Suppressed beside a legacy whole-prompt override,
     // which the backend rejects as a second override of the same prompt.
     ...(supportsOpeningPrompt &&
@@ -660,7 +659,7 @@ export const buildComplexityRouterConfig = ({
     modality_pin_override: modalityPinOverride ?? false,
     ...(customTechnicalKeywords.length > 0 && { custom_technical_keywords: customTechnicalKeywords }),
     ...(cleanedKeywordTierRules.length > 0 && { keyword_tier_rules: cleanedKeywordTierRules }),
-    escalation_keywords: cleanedEscalationKeywords,
+    escalation_keywords: forecast ? [] : cleanedEscalationKeywords,
     // Only written when on: the backend rejects it alongside session_affinity, user_turn mode and
     // a custom tier set, so an off router must not carry the key into any of those saves.
     ...(stallEscalationEnabled && {
@@ -676,19 +675,21 @@ export const buildComplexityRouterConfig = ({
       match_threshold: matchThreshold,
     }),
     ...(adaptive &&
-      effectiveType !== "llm_v2" && {
+      !forecast && {
         adaptive: true,
         adaptive_weights: adaptiveWeights,
         ...(adaptiveEligible === "all" && { tier_distance_penalty: tierDistancePenalty }),
         adaptive_eligible: adaptiveEligible,
       }),
     ...(returnRawModelName && { return_raw_model_name: true }),
-    ...(enableContextWindowEscalation !== undefined && {
-      enable_context_window_escalation: enableContextWindowEscalation,
-    }),
-    ...(contextWindowEscalationBuffer !== undefined && {
-      context_window_escalation_buffer: contextWindowEscalationBuffer,
+    // Omission enables the backend default, so hidden forecast controls need an explicit opt-out.
+    ...((forecast || enableContextWindowEscalation !== undefined) && {
+      enable_context_window_escalation: forecast ? false : enableContextWindowEscalation,
     }),
+    ...(!forecast &&
+      contextWindowEscalationBuffer !== undefined && {
+        context_window_escalation_buffer: contextWindowEscalationBuffer,
+      }),
     ...(sessionAffinityTtlSeconds !== undefined && {
       session_affinity_ttl_seconds: sessionAffinityTtlSeconds,
     }),
diff --git a/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts b/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts
index d07d4a24cf0..218eebe8430 100644
--- a/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts
+++ b/ui/litellm-dashboard/src/components/add_model/forecast_classifier_config.test.ts
@@ -264,7 +264,7 @@ describe("forecast classifier configuration", () => {
     });
     expect(saved.tiers).toEqual({ SIMPLE: ["efficient"], MEDIUM: ["middle"], REASONING: ["capable"] });
     expect(saved.tier_model_configs).toEqual(stored.tier_model_configs);
-    expect(saved.adaptive).toBe(true);
+    expect(saved.adaptive).toBe(false);
     expect(saved.plan_mode_min_tier).toBe("MEDIUM");
   });
 
diff --git a/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts b/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts
index 1aa6f0e3d35..4ae6efbb12d 100644
--- a/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts
+++ b/ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts
@@ -46,6 +46,43 @@ const hydratedState: KeywordMatchingState = {
 };
 
 describe("buildUpdatedComplexityRouterConfig keyword matching", () => {
+  it.each(["capability", "llm_v2", "heuristic"] as const)(
+    "handles enabled stored overrides when editing %s with or without keyword form state",
+    (classifier_type) => {
+      const stored = {
+        ...STORED,
+        classifier_type,
+        adaptive: classifier_type !== "llm_v2",
+        adaptive_weights: { quality: 0.6, cost: 0.4 },
+        adaptive_eligible: "all",
+        tier_distance_penalty: 0.8,
+        enable_context_window_escalation: true,
+        context_window_escalation_buffer: 0.9,
+      };
+      const value = hydrateComplexityRouterConfig(stored, undefined);
+      for (const keywordState of [undefined, hydratedState]) {
+        const saved = buildUpdatedComplexityRouterConfig(stored, value, undefined, keywordState);
+        const forecast = classifier_type !== "heuristic";
+        expect(saved.adaptive).toBe(!forecast);
+        expect(saved.enable_context_window_escalation).toBe(!forecast);
+        expect(saved.escalation_keywords).toEqual(forecast ? [] : stored.escalation_keywords);
+        for (const key of [
+          "adaptive_weights",
+          "adaptive_eligible",
+          "tier_distance_penalty",
+          "context_window_escalation_buffer",
+        ]) {
+          expect(Object.hasOwn(saved, key)).toBe(!forecast);
+        }
+        expect(saved.keyword_tier_rules).toEqual(STORED.keyword_tier_rules);
+        expect(saved.semantic_keyword_matching).toBe(true);
+        expect(saved.some_future_backend_key).toEqual(STORED.some_future_backend_key);
+      }
+      expect(value.enable_context_window_escalation).toBe(true);
+      expect(stored.escalation_keywords).toEqual(["urgent", "outage"]);
+    },
+  );
+
   it("round-trips an untouched edit without changing any keyword-matching value", () => {
     // Opening the modal hydrates state from STORED; saving with nothing changed must be a
     // no-op. These keys are now MANAGED, so a hydration bug silently wipes them.
diff --git a/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx b/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx
index 4a6c22689cc..e25c7f07dd7 100644
--- a/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx
+++ b/ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx
@@ -3,6 +3,7 @@ import type { StoredComplexityRouterConfig } from "../add_model/build_complexity
 export type { StoredComplexityRouterConfig } from "../add_model/build_complexity_router_config";
 import {
   getForecastConfigError,
+  isForecastClassifier,
   capabilitySettingsSchema,
   fuseSettingsSchema,
 } from "../add_model/forecast_classifier_config";
@@ -71,6 +72,7 @@ import {
 } from "../add_model/heuristic_scoring_knobs";
 import ComplexityRouterConfig, {
   ComplexityRouterConfigValue,
+  effectiveClassifierType,
   heuristicScoringRole,
   DEFAULT_ADAPTIVE_WEIGHTS,
   DEFAULT_SESSION_AFFINITY,
@@ -305,6 +307,7 @@ export const buildUpdatedComplexityRouterConfig = (
 ): Record<string, unknown> => {
   const isManaged = (key: string): boolean => {
     if (MANAGED_COMPLEXITY_ROUTER_KEYS.has(key)) return true;
+    if (key === "escalation_keywords" && isForecastClassifier(effectiveClassifierType(value))) return true;
     if (keywordMatching !== undefined && KEYWORD_MATCHING_KEYS.has(key)) return true;
     return customTechnicalKeywords !== undefined && key === "custom_technical_keywords";
   };
@@ -365,7 +368,7 @@ export const buildUpdatedComplexityRouterConfig = (
 
   // Keys this call does not own stay as the stored config left them.
   const unowned: readonly string[] = [
-    ...(keywordMatching === undefined ? KEYWORD_MATCHING_KEYS : []),
+    ...(keywordMatching === undefined ? [...KEYWORD_MATCHING_KEYS].filter((key) => !isManaged(key)) : []),
     ...(customTechnicalKeywords === undefined ? ["custom_technical_keywords"] : []),
   ];
   return {

From 0f7ed4433be21292a84ed0c0f9a48c23875740b3 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 04:04:01 +0000
Subject: [PATCH 64/67] fix(router): snapshot shadow kwargs before fan-out so
 shadows never see primary mutations

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/router.py                             | 17 +++-
 .../test_router_silent_experiment.py          | 85 ++++++++++++++++++-
 2 files changed, 98 insertions(+), 4 deletions(-)

diff --git a/litellm/router.py b/litellm/router.py
index a8c74b1a72c..e3c17bfb288 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -446,6 +446,13 @@ def _silent_experiment_targets(silent_model: object) -> tuple[str, ...]:
     return (targets,) if isinstance(targets, str) else tuple(targets)
 
 
+def _silent_experiment_kwargs_snapshot(kwargs: Mapping[str, object]) -> Mapping[str, object]:
+    metadata: Final = kwargs.get("metadata")
+    if not isinstance(metadata, Mapping):
+        return MappingProxyType({**kwargs})
+    return MappingProxyType({**kwargs, "metadata": dict(metadata)})
+
+
 def _with_router_resolved_session_model(session: object, model_name: str) -> Mapping[str, Mapping[str, object]]:
     """
     Realtime client-secret requests carry the model inside ``session`` as well, and the caller's copy of it still
@@ -2470,6 +2477,7 @@ class Router:
             )
             silent_model: Final = litellm_params.pop("silent_model", None)
 
+            shadow_kwargs: Final = _silent_experiment_kwargs_snapshot(kwargs)
             for silent_target in _silent_experiment_targets(silent_model):
                 # Mirroring traffic to a secondary model
                 # Use threading.Thread (not ThreadPoolExecutor) - executor.submit()
@@ -2478,7 +2486,7 @@ class Router:
                 threading.Thread(
                     target=self._silent_experiment_completion,
                     args=(silent_target, messages),
-                    kwargs=kwargs,
+                    kwargs=shadow_kwargs,
                     daemon=True,
                 ).start()
 
@@ -2593,7 +2601,9 @@ class Router:
     async def _run_silent_experiment(
         self, silent_model: str, messages: Sequence[Mapping[str, str]], silent_kwargs: Mapping[str, object]
     ) -> None:
-        remaining_kwargs: Final = {key: value for key, value in silent_kwargs.items() if key != "stream"}
+        remaining_kwargs: Final = MappingProxyType(
+            {key: value for key, value in silent_kwargs.items() if key != "stream"}
+        )
         response: Final = await self.acompletion(
             model=silent_model,
             messages=cast(list[AllMessageValues], messages),
@@ -3581,6 +3591,7 @@ class Router:
             )
             silent_model: Final = litellm_params.pop("silent_model", None)
 
+            shadow_kwargs: Final = _silent_experiment_kwargs_snapshot(kwargs)
             for silent_target in _silent_experiment_targets(silent_model):
                 # Mirroring traffic to a secondary model
                 # This is a silent experiment, so we don't want to block the primary request
@@ -3588,7 +3599,7 @@ class Router:
                     self._silent_experiment_acompletion(
                         silent_model=silent_target,
                         messages=messages,  # Use messages instead of *args
-                        **kwargs,
+                        **shadow_kwargs,
                     )
                 )
 
diff --git a/tests/test_litellm/test_router_silent_experiment.py b/tests/test_litellm/test_router_silent_experiment.py
index 79ce18e40b8..64d9400960d 100644
--- a/tests/test_litellm/test_router_silent_experiment.py
+++ b/tests/test_litellm/test_router_silent_experiment.py
@@ -1,5 +1,7 @@
 import asyncio
 import time
+from collections.abc import Callable
+from types import SimpleNamespace
 from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
 
@@ -8,6 +10,7 @@ import pytest
 import litellm
 from litellm.integrations.custom_logger import CustomLogger
 from litellm.router import Router
+from litellm.router import _silent_experiment_kwargs_snapshot
 from litellm.router import _silent_experiment_targets
 
 
@@ -124,7 +127,6 @@ def test_get_silent_experiment_kwargs():
     assert result["metadata"]["is_silent_experiment"] is True
     assert result["metadata"]["foo"] == "bar"
     assert "litellm_call_id" not in result
-    # the shadow must stream exactly like the primary so TTFT / ITL metrics are comparable
     assert result["stream"] is True
     # proxy_server_request must be preserved for spend log metadata
     assert "proxy_server_request" in result
@@ -255,6 +257,87 @@ def test_multiple_shadow_targets_fan_out_sync(recording_logger):
     assert all(call["stream"] is False for call in shadow_successes)
 
 
+def _tagged_primary_model_list() -> list[dict[str, object]]:
+    return [
+        {
+            "model_name": "primary-model",
+            "litellm_params": {
+                "model": "openai/gpt-5.4-mini",
+                "api_key": "fake-key",
+                "silent_model": "shadow-b",
+                "tags": ["primary-only"],
+            },
+        },
+        {
+            "model_name": "shadow-b",
+            "litellm_params": {"model": "anthropic/claude-haiku-4-5", "api_key": "fake-key"},
+        },
+    ]
+
+
+def test_silent_experiment_kwargs_snapshot_is_isolated_from_later_primary_mutations():
+    metadata = {"foo": "bar"}
+    kwargs: dict[str, object] = {"metadata": metadata, "stream": True}
+    snapshot = _silent_experiment_kwargs_snapshot(kwargs)
+    kwargs["messages"] = [{"role": "user", "content": "added by the primary"}]
+    metadata["tags"] = ["primary-only"]
+
+    assert dict(snapshot) == {"metadata": {"foo": "bar"}, "stream": True}
+    assert dict(_silent_experiment_kwargs_snapshot({"stream": False, "metadata": None})) == {
+        "stream": False,
+        "metadata": None,
+    }
+
+
+def test_sync_shadow_gets_kwargs_snapshot_taken_before_primary_mutates_them(recording_logger):
+    deferred: list[Callable[[], None]] = []
+
+    class _DeferredThread:
+        def __init__(self, target, args, kwargs, daemon) -> None:
+            deferred.append(lambda: target(*args, **kwargs))
+
+        def start(self) -> None:
+            return None
+
+    router = Router(model_list=_tagged_primary_model_list())
+    with patch(  # test-quality-ok: Router has no thread factory to inject; deferring start is the only deterministic way to expose the race
+        "litellm.router.threading", SimpleNamespace(Thread=_DeferredThread)
+    ):
+        response = router.completion(
+            model="primary-model",
+            messages=[{"role": "user", "content": "hi"}],
+            mock_response="pong",
+            metadata={"foo": "bar"},
+        )
+    assert response.choices[0].message.content == "pong"
+    assert len(deferred) == 1
+    deferred[0]()
+    _wait_for_shadow_successes_sync(recording_logger, expected=1)
+
+    shadow_successes = recording_logger.shadow_successes()
+    assert len(shadow_successes) == 1
+    shadow_metadata = shadow_successes[0]["litellm_params"]["metadata"]
+    assert shadow_metadata["model_group"] == "shadow-b"
+    assert "primary-only" not in shadow_metadata.get("tags", [])
+
+
+@pytest.mark.asyncio
+async def test_async_shadow_does_not_inherit_primary_deployment_tags(recording_logger):
+    router = Router(model_list=_tagged_primary_model_list())
+    response = await router.acompletion(
+        model="primary-model",
+        messages=[{"role": "user", "content": "hi"}],
+        mock_response="pong",
+        metadata={"foo": "bar"},
+    )
+    assert response.choices[0].message.content == "pong"
+    await _wait_for_shadow_successes(recording_logger, expected=1)
+
+    shadow_successes = recording_logger.shadow_successes()
+    assert len(shadow_successes) == 1
+    assert "primary-only" not in shadow_successes[0]["litellm_params"]["metadata"].get("tags", [])
+
+
 @pytest.mark.asyncio
 async def test_shadow_of_a_shadow_is_not_launched(recording_logger):
     router = Router(model_list=_streaming_model_list(["shadow-a"]))

From 252c69b532b5282f2a2ba94ec22503bdbbf76bf6 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 04:31:43 +0000
Subject: [PATCH 65/67] fix(router): snapshot shadow kwargs per target so
 concurrent shadows never share metadata

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/router.py                             |  6 +--
 .../test_router_silent_experiment.py          | 37 ++++++++++++++++++-
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/litellm/router.py b/litellm/router.py
index e3c17bfb288..789fc81d8d3 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -2477,7 +2477,6 @@ class Router:
             )
             silent_model: Final = litellm_params.pop("silent_model", None)
 
-            shadow_kwargs: Final = _silent_experiment_kwargs_snapshot(kwargs)
             for silent_target in _silent_experiment_targets(silent_model):
                 # Mirroring traffic to a secondary model
                 # Use threading.Thread (not ThreadPoolExecutor) - executor.submit()
@@ -2486,7 +2485,7 @@ class Router:
                 threading.Thread(
                     target=self._silent_experiment_completion,
                     args=(silent_target, messages),
-                    kwargs=shadow_kwargs,
+                    kwargs=_silent_experiment_kwargs_snapshot(kwargs),
                     daemon=True,
                 ).start()
 
@@ -3591,7 +3590,6 @@ class Router:
             )
             silent_model: Final = litellm_params.pop("silent_model", None)
 
-            shadow_kwargs: Final = _silent_experiment_kwargs_snapshot(kwargs)
             for silent_target in _silent_experiment_targets(silent_model):
                 # Mirroring traffic to a secondary model
                 # This is a silent experiment, so we don't want to block the primary request
@@ -3599,7 +3597,7 @@ class Router:
                     self._silent_experiment_acompletion(
                         silent_model=silent_target,
                         messages=messages,  # Use messages instead of *args
-                        **shadow_kwargs,
+                        **_silent_experiment_kwargs_snapshot(kwargs),
                     )
                 )
 
diff --git a/tests/test_litellm/test_router_silent_experiment.py b/tests/test_litellm/test_router_silent_experiment.py
index 64d9400960d..d62962da275 100644
--- a/tests/test_litellm/test_router_silent_experiment.py
+++ b/tests/test_litellm/test_router_silent_experiment.py
@@ -1,6 +1,6 @@
 import asyncio
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from types import SimpleNamespace
 from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
@@ -321,6 +321,41 @@ def test_sync_shadow_gets_kwargs_snapshot_taken_before_primary_mutates_them(reco
     assert "primary-only" not in shadow_metadata.get("tags", [])
 
 
+def test_sync_shadow_workers_do_not_share_metadata_with_each_other(recording_logger):
+    workers: list[tuple[Mapping[str, object], Callable[[], None]]] = []
+
+    class _DeferredThread:
+        def __init__(self, target, args, kwargs, daemon) -> None:
+            workers.append((kwargs, lambda: target(*args, **kwargs)))
+
+        def start(self) -> None:
+            return None
+
+    router = Router(model_list=_streaming_model_list(["shadow-a", "shadow-b"]))
+    with patch(  # test-quality-ok: Router has no thread factory to inject; deferring start is the only deterministic way to expose the race
+        "litellm.router.threading", SimpleNamespace(Thread=_DeferredThread)
+    ):
+        router.completion(
+            model="primary-model",
+            messages=[{"role": "user", "content": "hi"}],
+            mock_response="pong",
+            metadata={"foo": "bar"},
+        )
+    assert len(workers) == 2
+    (first_kwargs, run_first), (_, run_second) = workers
+    first_kwargs["metadata"].pop("foo")
+    run_second()
+    run_first()
+    _wait_for_shadow_successes_sync(recording_logger, expected=2)
+
+    metadata_by_group = {
+        call["litellm_params"]["metadata"]["model_group"]: call["litellm_params"]["metadata"]
+        for call in recording_logger.shadow_successes()
+    }
+    assert metadata_by_group["shadow-b"]["foo"] == "bar"
+    assert "foo" not in metadata_by_group["shadow-a"]
+
+
 @pytest.mark.asyncio
 async def test_async_shadow_does_not_inherit_primary_deployment_tags(recording_logger):
     router = Router(model_list=_tagged_primary_model_list())

From e035682ed17295b9c5f0a363e266e890de31061c Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 22:15:57 -0700
Subject: [PATCH 66/67] refactor(auth): separate JWT identity and OAuth
 authorization

---
 .../mcp_server/bridge_token_flow.py           |  68 +++--
 .../mcp_server/discoverable_endpoints.py      |   5 +-
 litellm/proxy/auth/handle_jwt.py              | 276 ++++++++++--------
 .../mcp_server/test_discoverable_endpoints.py |  34 ++-
 .../proxy/auth/test_handle_jwt.py             | 100 +++++--
 5 files changed, 300 insertions(+), 183 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index 5fe0929773c..f001ee87dbd 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -24,6 +24,7 @@ if TYPE_CHECKING:
         UpstreamTokenGrant,
     )
     from litellm.proxy._types import UserAPIKeyAuth
+    from litellm.proxy.auth.handle_jwt import JWTIdentity
 
 
 def _litellm_key_from_request(request: Request) -> str | None:
@@ -304,26 +305,37 @@ async def _revalidate_active_subject(identity: "EnvelopeIdentity") -> "_KeyResol
             assert_never(identity.subject_type)
 
 
-async def _extract_user_id_from_request(request: Request, server_id: str | None = None) -> str | None:
-    """Resolve identity for binding, or authorize the credential-write action for a target server."""
+async def _extract_user_id_from_request(request: Request) -> str | None:
+    """Resolve the caller for identity binding without granting credential-write permission."""
+    from litellm.proxy.auth.handle_jwt import JWTIdentity  # noqa: PLC0415  # proxy import cycle
+
+    resolved: Final = await _resolve_request_auth(request)
+    if isinstance(resolved, JWTIdentity):
+        return resolved.user_id
+    return _active_key_user_id(resolved) if resolved is not None else None
+
+
+async def authorize_oauth_credential_request(request: Request, server_id: str) -> str | None:
     from litellm.proxy._types import UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
+
+    resolved: Final = await _resolve_request_auth(request, f"/v1/mcp/server/{server_id}/oauth-user-credential")
+    if not isinstance(resolved, UserAPIKeyAuth) or not _active_key_user_id(resolved):
+        return None
+    if not await can_store_oauth_credential(request, resolved, server_id):
+        return None
+    return resolved.user_id
+
+
+async def _resolve_request_auth(
+    request: Request, write_route: str | None = None
+) -> "UserAPIKeyAuth | JWTIdentity | None":
     from litellm.proxy.auth.handle_jwt import JWTHandler  # noqa: PLC0415  # proxy import cycle
 
     token: Final = _litellm_key_from_request(request)
-    # The OAuth relay is public; the optional server-side write is the same protected action
-    # as the direct credential endpoint. Authorize that action without rewriting the Request.
-    write_route: Final = f"/v1/mcp/server/{server_id}/oauth-user-credential" if server_id is not None else None
-    resolved: Final = (
-        await _resolve_jwt_auth(request, token, write_route)
-        if token is not None and JWTHandler.is_jwt(token)
-        else await _resolve_active_litellm_key(request)
-    )
-    auth: Final = resolved.key if isinstance(resolved, _ResolvedKey) else resolved
-    if not isinstance(auth, UserAPIKeyAuth) or not _active_key_user_id(auth):
-        return None
-    if server_id is not None and not await can_store_oauth_credential(request, auth, server_id):
-        return None
-    return auth.user_id
+    if token is not None and JWTHandler.is_jwt(token):
+        return await _resolve_jwt_auth(request, token, write_route)
+    resolved: Final = await _resolve_active_litellm_key(request)
+    return resolved.key if isinstance(resolved, _ResolvedKey) else None
 
 
 async def can_store_oauth_credential(request: Request, auth: "UserAPIKeyAuth", server_id: str) -> bool:
@@ -358,7 +370,7 @@ async def _resolve_jwt_auth(
     request: Request,
     token: str,
     write_route: str | None,
-) -> "UserAPIKeyAuth | None":
+) -> "UserAPIKeyAuth | JWTIdentity | None":
     from litellm.proxy._types import UserAPIKeyAuth  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.handle_jwt import JWTAuthManager  # noqa: PLC0415  # proxy import cycle
     from litellm.proxy.auth.user_api_key_auth import (  # noqa: PLC0415  # proxy import cycle
@@ -393,25 +405,35 @@ async def _resolve_jwt_auth(
                 return None if await _key_owner_scim_deactivated(mapped) or not _active_key_user_id(mapped) else mapped
             if mapped is not None:
                 return None
-        identity: Final = await JWTAuthManager.auth_builder(
+        if write_route is None:
+            identity: Final = await JWTAuthManager.resolve_identity(
+                api_key=token,
+                jwt_handler=jwt_handler,
+                prisma_client=prisma_client,
+                user_api_key_cache=user_api_key_cache,
+                parent_otel_span=None,
+                proxy_logging_obj=proxy_logging_obj,
+            )
+            if identity.user_object is not None and isinstance(_active_user_record(identity.user_object), str):
+                return None
+            return identity
+        authorized: Final = await JWTAuthManager.authorize_jwt(
             api_key=token,
             jwt_handler=jwt_handler,
             request_data={},
             general_settings=general_settings,
-            route=write_route or request.url.path,
+            route=write_route,
             prisma_client=prisma_client,
             user_api_key_cache=user_api_key_cache,
             parent_otel_span=None,
             proxy_logging_obj=proxy_logging_obj,
             request_headers=dict(request.headers),
             request_method=request.method,
-            identity_only=write_route is None,
-            allow_provisioning=False,
         )
-        resolved_user: Final = identity["user_object"]
+        resolved_user: Final = authorized["user_object"]
         if resolved_user is not None and isinstance(_active_user_record(resolved_user), str):
             return None
-        return JWTAuthManager.user_api_key_auth_from_result(identity)
+        return JWTAuthManager.user_api_key_auth_from_result(authorized)
     except Exception as exc:  # noqa: BLE001  # public OAuth exchange stays available; unvalidated identities never write credentials
         verbose_logger.debug("OAuth JWT identity could not be validated (%s)", type(exc).__name__)
         return None
diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index 9ba67f966a2..7e7189c8a6b 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -33,6 +33,7 @@ from litellm.proxy._experimental.mcp_server.bridge_token_flow import (
     _prepare_bridge_mint,
     _prepare_bridge_refresh,
     _reload_active_user_by_id,
+    authorize_oauth_credential_request,
     can_store_oauth_credential,
 )
 from litellm.proxy._experimental.mcp_server.faults import (
@@ -851,7 +852,7 @@ async def _resolve_oauth_authorization_user(
     )
 
     request_user_id: Final = (
-        await _extract_user_id_from_request(request, mcp_server.server_id) if enforce_binding else None
+        await authorize_oauth_credential_request(request, mcp_server.server_id) if enforce_binding else None
     )
     if enforce_binding and request_user_id is None and _litellm_key_from_request(request):
         return _bridge_access_denied_redirect(redirect_uri, state, mcp_server)
@@ -1233,7 +1234,7 @@ async def exchange_token_with_server(
                         request, await MCPRequestHandler.reload_admitted_user(user_id), resolved_server.server_id
                     )
                     if bridge_identity is not None
-                    else await _extract_user_id_from_request(request, resolved_server.server_id) == user_id
+                    else await authorize_oauth_credential_request(request, resolved_server.server_id) == user_id
                 )
                 if can_store:
                     await _store_per_user_token_server_side(
diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py
index f2bdbdd9341..4fe44eb1dc8 100644
--- a/litellm/proxy/auth/handle_jwt.py
+++ b/litellm/proxy/auth/handle_jwt.py
@@ -9,13 +9,13 @@ JWT token must have 'litellm_proxy_admin' in scope.
 from __future__ import annotations
 
 import asyncio
-import copy
 import fnmatch
 import hashlib
 import os
 import re
 import time
 from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
 from typing import Any, Final, Literal, NoReturn, Protocol, TypeVar, cast
 
 import httpx
@@ -130,6 +130,19 @@ class _UserInfoResponse(Protocol):
     def json(self) -> dict[str, object]: ...
 
 
+@dataclass(frozen=True, slots=True)
+class JWTIdentity:
+    user_id: str | None
+    user_object: LiteLLM_UserTable | None
+    agent_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class _JWTProvisioning:
+    user_id_upsert: bool
+    team_id_upsert: bool
+
+
 class AgentLookup(Protocol):
     """The registered-agent lookups a JWT agent claim is matched against."""
 
@@ -1473,6 +1486,7 @@ class JWTAuthManager:
         user_api_key_cache: UserApiKeyCache,
         parent_otel_span: Span | None,
         proxy_logging_obj: ProxyLogging,
+        team_id_upsert: bool | None = None,
     ) -> tuple[str | None, LiteLLM_TeamTable | None]:
         """Find and validate specific team ID from team_id_jwt_field or team_alias_jwt_field"""
         individual_team_id = jwt_handler.get_team_id(token=jwt_valid_token, default_value=None)
@@ -1500,7 +1514,9 @@ class JWTAuthManager:
                     user_api_key_cache=user_api_key_cache,
                     parent_otel_span=parent_otel_span,
                     proxy_logging_obj=proxy_logging_obj,
-                    team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert,
+                    team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert
+                    if team_id_upsert is None
+                    else team_id_upsert,
                 )
                 return individual_team_id, team_object
             except HTTPException as e:
@@ -2017,6 +2033,7 @@ class JWTAuthManager:
         user_api_key_cache: UserApiKeyCache,
         parent_otel_span: Span | None,
         proxy_logging_obj: ProxyLogging,
+        team_id_upsert: bool | None = None,
     ) -> None:
         """Attach team context from x-litellm-team-id to an admin result.
 
@@ -2034,7 +2051,7 @@ class JWTAuthManager:
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
                 proxy_logging_obj=proxy_logging_obj,
-                team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert,
+                team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert if team_id_upsert is None else team_id_upsert,
             )
         except Exception as e:
             # Fall back to pre-PR admin behavior: honor the admin's
@@ -2268,64 +2285,119 @@ class JWTAuthManager:
         proxy_logging_obj: ProxyLogging,
         request_headers: dict | None = None,
         request_method: str | None = None,
-        identity_only: bool = False,
-        allow_provisioning: bool = True,
     ) -> JWTAuthBuilderResult:
-        """Build JWT authentication and authorization context.
+        return await JWTAuthManager.authorize_jwt(
+            api_key=api_key,
+            jwt_handler=jwt_handler,
+            request_data=request_data,
+            general_settings=general_settings,
+            route=route,
+            prisma_client=prisma_client,
+            user_api_key_cache=user_api_key_cache,
+            parent_otel_span=parent_otel_span,
+            proxy_logging_obj=proxy_logging_obj,
+            request_headers=request_headers,
+            request_method=request_method,
+            provisioning=_JWTProvisioning(
+                user_id_upsert=jwt_handler.litellm_jwtauth.user_id_upsert,
+                team_id_upsert=jwt_handler.litellm_jwtauth.team_id_upsert,
+            ),
+        )
 
-        identity_only resolves the caller for OAuth identity binding and grants no permission.
-        Credential writes use full authorization with allow_provisioning=False: resolve the
-        existing policy context without creating users/teams or synchronizing membership.
-        A private handler configuration keeps that restriction out of concurrent normal requests.
-        """
-        handler: Final = jwt_handler if allow_provisioning else copy.copy(jwt_handler)
-        if not allow_provisioning:
-            handler.update_environment(
-                prisma_client=jwt_handler.prisma_client,
-                user_api_key_cache=jwt_handler.user_api_key_cache,
-                litellm_jwtauth=jwt_handler.litellm_jwtauth.model_copy(
-                    update={"user_id_upsert": False, "team_id_upsert": False, "sync_user_role_and_teams": False}
-                ),
-                leeway=jwt_handler.leeway,
+    @staticmethod
+    async def authenticate_jwt(api_key: str, jwt_handler: JWTHandler) -> dict[str, object]:
+        claims: Final = (
+            await jwt_handler.get_oidc_userinfo(token=api_key)
+            if jwt_handler.litellm_jwtauth.oidc_userinfo_enabled and not jwt_handler.is_jwt(token=api_key)
+            else await jwt_handler.auth_jwt(token=api_key)
+        )
+        validate: Final = jwt_handler.litellm_jwtauth.custom_validate
+        if validate is not None and not validate(claims):
+            raise HTTPException(status_code=403, detail="Invalid JWT token")
+        return claims
+
+    @staticmethod
+    async def resolve_identity(
+        api_key: str,
+        jwt_handler: JWTHandler,
+        prisma_client: PrismaClient | None,
+        user_api_key_cache: UserApiKeyCache,
+        parent_otel_span: Span | None,
+        proxy_logging_obj: ProxyLogging,
+    ) -> JWTIdentity:
+        claims: Final = await JWTAuthManager.authenticate_jwt(api_key, jwt_handler)
+        return await JWTAuthManager._resolve_claim_identity(
+            claims, jwt_handler, prisma_client, user_api_key_cache, parent_otel_span, proxy_logging_obj
+        )
+
+    @staticmethod
+    async def _resolve_claim_identity(
+        claims: dict[str, object],
+        jwt_handler: JWTHandler,
+        prisma_client: PrismaClient | None,
+        user_api_key_cache: UserApiKeyCache,
+        parent_otel_span: Span | None,
+        proxy_logging_obj: ProxyLogging,
+    ) -> JWTIdentity:
+        claim_user_id, user_email, valid_user_email = await JWTAuthManager.get_user_info(jwt_handler, claims)
+        user_id: Final = (
+            jwt_handler.get_object_id(token=claims, default_value=None) or claim_user_id
+            if jwt_handler.get_rbac_role(token=claims) == LitellmUserRoles.INTERNAL_USER
+            else claim_user_id
+        )
+        agent_id: Final = JWTAuthManager.resolve_agent_id(jwt_handler, claims, jwt_handler.agent_lookup)
+        is_admin: Final = jwt_handler.is_admin(scopes=jwt_handler.get_scopes(token=claims))
+        try:
+            user, _, _, _, canonical_id = await JWTAuthManager.get_objects(
+                user_id=user_id,
+                user_email=user_email,
+                org_id=None,
+                end_user_id=None,
+                team_id=None,
+                valid_user_email=valid_user_email,
+                jwt_handler=jwt_handler,
+                prisma_client=prisma_client,
+                user_api_key_cache=user_api_key_cache,
+                parent_otel_span=parent_otel_span,
+                proxy_logging_obj=proxy_logging_obj,
+                route="",
+                user_id_upsert=False,
             )
+        except UserNotFoundError:
+            if not is_admin:
+                raise
+            return JWTIdentity(user_id=user_id, user_object=None, agent_id=agent_id)
+        return JWTIdentity(user_id=user_id if is_admin else canonical_id, user_object=user, agent_id=agent_id)
 
-        # Check if OIDC UserInfo endpoint is enabled, but fall back to standard
-        # JWT auth if the token itself is a well-formed JWT (3-part structure).
-        if handler.litellm_jwtauth.oidc_userinfo_enabled and not handler.is_jwt(token=api_key):
-            verbose_proxy_logger.debug("OIDC UserInfo is enabled. Fetching user info from UserInfo endpoint.")
-            # Use the access token to fetch user info from OIDC UserInfo endpoint
-            jwt_valid_token: dict = await handler.get_oidc_userinfo(token=api_key)
-        else:
-            # Default behavior: decode and validate the JWT token
-            jwt_valid_token = await handler.auth_jwt(token=api_key)
-
-        # Check custom validate
-        if handler.litellm_jwtauth.custom_validate:
-            if not handler.litellm_jwtauth.custom_validate(jwt_valid_token):
-                raise HTTPException(
-                    status_code=403,
-                    detail="Invalid JWT token",
-                )
+    @staticmethod
+    async def authorize_jwt(
+        api_key: str,
+        jwt_handler: JWTHandler,
+        request_data: dict[str, object],
+        general_settings: dict[str, object],
+        route: str,
+        prisma_client: PrismaClient | None,
+        user_api_key_cache: UserApiKeyCache,
+        parent_otel_span: Span | None,
+        proxy_logging_obj: ProxyLogging,
+        request_headers: dict[str, str] | None = None,
+        request_method: str | None = None,
+        provisioning: _JWTProvisioning | None = None,
+    ) -> JWTAuthBuilderResult:
+        """Resolve and authorize JWT context; only normal admission supplies provisioning."""
+        handler: Final = jwt_handler
+        jwt_valid_token: Final = await JWTAuthManager.authenticate_jwt(api_key, handler)
+        team_id_upsert: Final = provisioning.team_id_upsert if provisioning is not None else False
+        model: Final = request_data.get("model")
+        requested_model: Final = model if isinstance(model, str) else None
 
         # Check RBAC
         rbac_role: Final = handler.get_rbac_role(token=jwt_valid_token)
-        if not identity_only:
-            await JWTAuthManager.check_rbac_role(
-                handler,
-                jwt_valid_token,
-                general_settings,
-                request_data,
-                route,
-                rbac_role,
-            )
+        await JWTAuthManager.check_rbac_role(handler, jwt_valid_token, general_settings, request_data, route, rbac_role)
 
         # Check Scope Based Access
         scopes: Final = handler.get_scopes(token=jwt_valid_token)
-        if (
-            not identity_only
-            and handler.litellm_jwtauth.enforce_scope_based_access
-            and handler.litellm_jwtauth.scope_mappings
-        ):
+        if handler.litellm_jwtauth.enforce_scope_based_access and handler.litellm_jwtauth.scope_mappings:
             JWTAuthManager.check_scope_based_access(
                 scope_mappings=handler.litellm_jwtauth.scope_mappings,
                 scopes=scopes,
@@ -2357,69 +2429,6 @@ class JWTAuthManager:
             agent_registry=handler.agent_lookup,
         )
 
-        if identity_only or (not allow_provisioning and handler.is_admin(scopes=scopes)):
-            try:
-                identity_user, _, _, _, identity_user_id = await JWTAuthManager.get_objects(
-                    user_id=user_id,
-                    user_email=user_email,
-                    org_id=None,
-                    end_user_id=None,
-                    team_id=None,
-                    valid_user_email=valid_user_email,
-                    jwt_handler=handler,
-                    prisma_client=prisma_client,
-                    user_api_key_cache=user_api_key_cache,
-                    parent_otel_span=parent_otel_span,
-                    proxy_logging_obj=proxy_logging_obj,
-                    route=route,
-                    user_id_upsert=False,
-                )
-            except UserNotFoundError:
-                if not handler.is_admin(scopes=scopes):
-                    raise
-                identity_user, identity_user_id = None, user_id
-            if not identity_only:
-                admin: Final = await JWTAuthManager.check_admin_access(
-                    handler,
-                    scopes,
-                    route,
-                    user_id,
-                    org_id,
-                    api_key,
-                    jwt_valid_token,
-                    user_email=user_email,
-                    agent_id=agent_id,
-                )
-                if admin is not None:
-                    await JWTAuthManager._attach_team_from_header_for_admin(
-                        admin_result=admin,
-                        route=route,
-                        request_headers=request_headers,
-                        jwt_handler=handler,
-                        prisma_client=prisma_client,
-                        user_api_key_cache=user_api_key_cache,
-                        parent_otel_span=parent_otel_span,
-                        proxy_logging_obj=proxy_logging_obj,
-                    )
-                    return {**admin, "user_object": identity_user}
-            return JWTAuthBuilderResult(
-                is_proxy_admin=False,
-                # Admin admission uses the claim ID; other callers use the canonical DB ID.
-                user_id=user_id if handler.is_admin(scopes=scopes) else identity_user_id,
-                user_email=identity_user.user_email if identity_user is not None else user_email,
-                user_object=identity_user,
-                team_id=None,
-                team_object=None,
-                org_id=None,
-                org_object=None,
-                end_user_id=None,
-                end_user_object=None,
-                team_membership=None,
-                token=api_key,
-                jwt_claims=jwt_valid_token,
-                agent_id=agent_id,
-            )
-
         # Check admin access
         admin_result: Final = await JWTAuthManager.check_admin_access(
             handler,
@@ -2442,7 +2451,13 @@ class JWTAuthManager:
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
                 proxy_logging_obj=proxy_logging_obj,
+                team_id_upsert=team_id_upsert,
             )
+            if provisioning is None:
+                identity: Final = await JWTAuthManager._resolve_claim_identity(
+                    jwt_valid_token, handler, prisma_client, user_api_key_cache, parent_otel_span, proxy_logging_obj
+                )
+                return {**admin_result, "user_object": identity.user_object}
             return admin_result
 
         # Get team with model access
@@ -2485,7 +2500,7 @@ class JWTAuthManager:
                     user_api_key_cache=user_api_key_cache,
                     parent_otel_span=parent_otel_span,
                     proxy_logging_obj=proxy_logging_obj,
-                    team_id_upsert=(handler.litellm_jwtauth.team_id_upsert and not db_team_fallback),
+                    team_id_upsert=(team_id_upsert and not db_team_fallback),
                 )
             except HTTPException:
                 if not db_team_fallback:
@@ -2503,13 +2518,14 @@ class JWTAuthManager:
                 user_api_key_cache,
                 parent_otel_span,
                 proxy_logging_obj,
+                team_id_upsert=team_id_upsert,
             )
 
         if not team_object and not team_id:
             ## CHECK USER GROUP ACCESS
             team_id, team_object = await JWTAuthManager.find_team_with_model_access(
                 team_ids=all_team_ids,
-                requested_model=request_data.get("model"),
+                requested_model=requested_model,
                 route=route,
                 request_method=request_method,
                 jwt_handler=handler,
@@ -2536,7 +2552,7 @@ class JWTAuthManager:
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
                 proxy_logging_obj=proxy_logging_obj,
-                team_id_upsert=handler.litellm_jwtauth.team_id_upsert,
+                team_id_upsert=team_id_upsert,
             )
 
         if team_id and not JWTAuthManager._team_has_passthrough_route_access(
@@ -2570,18 +2586,20 @@ class JWTAuthManager:
             proxy_logging_obj=proxy_logging_obj,
             route=route,
             org_alias=org_alias,
+            user_id_upsert=provisioning.user_id_upsert if provisioning is not None else False,
         )
 
         # Derive org_id from org_object if resolved by alias
         resolved_org_id: Final = org_object.organization_id if org_object else org_id
 
-        await JWTAuthManager.sync_user_role_and_teams(
-            jwt_handler=handler,
-            jwt_valid_token=jwt_valid_token,
-            user_object=user_object,
-            prisma_client=prisma_client,
-            user_api_key_cache=user_api_key_cache,
-        )
+        if provisioning is not None:
+            await JWTAuthManager.sync_user_role_and_teams(
+                jwt_handler=handler,
+                jwt_valid_token=jwt_valid_token,
+                user_object=user_object,
+                prisma_client=prisma_client,
+                user_api_key_cache=user_api_key_cache,
+            )
 
         # If JWT did not resolve team_id, attempt a team fallback.
         if team_id is None and db_team_fallback:
@@ -2592,11 +2610,11 @@ class JWTAuthManager:
             ) = await JWTAuthManager._resolve_db_team_fallback(
                 user_object=user_object,
                 user_id=user_id,
-                requested_model=request_data.get("model"),
+                requested_model=requested_model,
                 route=route,
                 jwt_handler=handler,
                 enforce_team_based_model_access=handler.litellm_jwtauth.enforce_team_based_model_access,
-                team_id_upsert=handler.litellm_jwtauth.team_id_upsert,
+                team_id_upsert=team_id_upsert,
                 prisma_client=prisma_client,
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
@@ -2624,7 +2642,7 @@ class JWTAuthManager:
                 user_api_key_cache=user_api_key_cache,
                 parent_otel_span=parent_otel_span,
                 proxy_logging_obj=proxy_logging_obj,
-                team_id_upsert=handler.litellm_jwtauth.team_id_upsert,
+                team_id_upsert=team_id_upsert,
             )
         elif db_team_fallback and team_id == header_team_id:
             JWTAuthManager._validate_header_team_in_db_membership(
@@ -2644,7 +2662,7 @@ class JWTAuthManager:
                 )
 
         ## MAP USER TO TEAMS
-        if allow_provisioning:
+        if provisioning is not None:
             await JWTAuthManager.map_user_to_teams(
                 user_object=user_object,
                 team_object=team_object,
@@ -2654,7 +2672,7 @@ class JWTAuthManager:
         JWTAuthManager.validate_object_id(
             user_id=user_id,
             team_id=team_id,
-            enforce_rbac=general_settings.get("enforce_rbac", False),
+            enforce_rbac=bool(general_settings.get("enforce_rbac", False)),
             is_proxy_admin=False,
         )
 
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index 1739ac6d743..8d300c7c508 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -6980,6 +6980,11 @@ async def _exchange_persistence_attempted_for_auth_type(auth_type) -> bool:
             new_callable=AsyncMock,
             return_value="admin-user",
         ),
+        patch(  # test-quality-ok: this control tests persistence by auth mode; write-policy behavior is covered separately
+            "litellm.proxy._experimental.mcp_server.discoverable_endpoints.authorize_oauth_credential_request",
+            new_callable=AsyncMock,
+            return_value="admin-user",
+        ),
         patch(
             "litellm.proxy._experimental.mcp_server.discoverable_endpoints._store_per_user_token_server_side",
             new_callable=AsyncMock,
@@ -11168,7 +11173,7 @@ async def test_identity_bound_authorization_carries_nonce_and_caller_through_cal
                        "path": "/authorize", "query_string": b"", "headers": []})
     with (
         patch(  # test-quality-ok: isolate authenticated request resolution from the real encrypted OAuth round trip
-              "litellm.proxy._experimental.mcp_server.discoverable_endpoints._extract_user_id_from_request",
+              "litellm.proxy._experimental.mcp_server.discoverable_endpoints.authorize_oauth_credential_request",
               new=AsyncMock(return_value="alice")),
         patch(  # test-quality-ok: isolate user access lookup while testing nonce and caller preservation
               "litellm.proxy._experimental.mcp_server.discoverable_endpoints._user_can_reach_mcp_server",
@@ -11569,17 +11574,24 @@ async def test_oauth_exchange_stores_token_for_validated_jwt_user(
         "missing_database",
     ],
 )
+@pytest.mark.parametrize("credential_write", [False, True])
 async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     monkeypatch: pytest.MonkeyPatch,
     rejection: str,
+    credential_write: bool,
 ) -> None:
     from cryptography.hazmat.primitives.asymmetric import rsa
 
     from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy import proxy_server
-    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._experimental.mcp_server import mcp_server_manager
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import (
+        _extract_user_id_from_request, authorize_oauth_credential_request,
+    )
 
+    allowed_servers: Final = AsyncMock(return_value=["server-a"])
+    monkeypatch.setattr(mcp_server_manager.global_mcp_server_manager, "get_allowed_mcp_servers", allowed_servers)
     handler, signing_key = jwt_oauth_identity
     key: Final = (
         rsa.generate_private_key(public_exponent=65537, key_size=2048) if rejection == "signature" else signing_key
@@ -11603,7 +11615,13 @@ async def test_oauth_jwt_identity_rejects_untrusted_or_inactive_owner(
         )
     if rejection == "custom_validate":
         handler.litellm_jwtauth.custom_validate = lambda claims: False
-    assert await _extract_user_id_from_request(_token_request({"Authorization": f"Bearer {bearer}"})) is None
+    request: Final = _token_request({"Authorization": f"Bearer {bearer}"})
+    result: Final = (
+        await authorize_oauth_credential_request(request, "server-a")
+        if credential_write else await _extract_user_id_from_request(request)
+    )
+    assert result is None
+    allowed_servers.assert_not_awaited()
 
 
 @pytest.mark.asyncio
@@ -11850,7 +11868,7 @@ async def test_oauth_credential_write_keeps_virtual_key_permissions(
     import asyncio
 
     from litellm.proxy._experimental.mcp_server import mcp_server_manager
-    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import authorize_oauth_credential_request
     from litellm.proxy._types import UserAPIKeyAuth, hash_token
     from litellm.proxy.auth.auth_checks import jwt_key_mapping_cache_key
 
@@ -11881,10 +11899,10 @@ async def test_oauth_credential_write_keeps_virtual_key_permissions(
     request: Final = _token_request({"Authorization": f"Bearer {bearer}"}, path="/server-a/token")
     if state == "cancelled":
         with pytest.raises(asyncio.CancelledError):
-            await _extract_user_id_from_request(request, "server-a")
+            await authorize_oauth_credential_request(request, "server-a")
         manager.get_allowed_mcp_servers.assert_awaited_once()
         return
-    assert await _extract_user_id_from_request(request, "server-a") == ("jwt-owner" if state == "allowed" else None)
+    assert await authorize_oauth_credential_request(request, "server-a") == ("jwt-owner" if state == "allowed" else None)
     if state in ("allowed", "server_denied", "lookup_error"):
         manager.get_allowed_mcp_servers.assert_awaited_once()
         writer: Final = manager.get_allowed_mcp_servers.call_args.args[0]
@@ -11907,7 +11925,7 @@ async def test_oauth_writer_preserves_claimed_team_instead_of_expanding_user_ros
     from litellm.models.user import LiteLLM_UserTable
     from litellm.proxy import proxy_server
     from litellm.proxy._experimental.mcp_server import mcp_server_manager
-    from litellm.proxy._experimental.mcp_server.bridge_token_flow import _extract_user_id_from_request
+    from litellm.proxy._experimental.mcp_server.bridge_token_flow import authorize_oauth_credential_request
     from litellm.proxy._types import LiteLLM_TeamTable, Member
 
     handler, signing_key = jwt_oauth_identity
@@ -11925,7 +11943,7 @@ async def test_oauth_writer_preserves_claimed_team_instead_of_expanding_user_ros
     monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
     bearer: Final = _oauth_identity_jwt(signing_key, claims={"team": "a"})
     request: Final = _token_request({"Authorization": f"Bearer {bearer}"}, path=f"/{server_id}/token")
-    assert await _extract_user_id_from_request(request, server_id) == (
+    assert await authorize_oauth_credential_request(request, server_id) == (
         "jwt-owner" if server_id == "team-a-server" else None
     )
     manager.get_allowed_mcp_servers.assert_awaited_once()
diff --git a/tests/test_litellm/proxy/auth/test_handle_jwt.py b/tests/test_litellm/proxy/auth/test_handle_jwt.py
index babbf88dc29..6fbbb37fbc3 100644
--- a/tests/test_litellm/proxy/auth/test_handle_jwt.py
+++ b/tests/test_litellm/proxy/auth/test_handle_jwt.py
@@ -6791,12 +6791,11 @@ async def test_sync_user_role_and_teams_singular_claim_only_recognized_under_fla
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("identity_only", [False, True])
-@pytest.mark.parametrize("allow_provisioning", [False, True])
+@pytest.mark.parametrize("operation", ["identity", "authorize", "admit"])
 @pytest.mark.parametrize("existing_user", [False, True])
 @pytest.mark.parametrize("model_allowed", [False, True])
-async def test_auth_builder_identity_lookup_does_not_provision_users(
-    monkeypatch: pytest.MonkeyPatch, identity_only: bool, allow_provisioning: bool, existing_user: bool, model_allowed: bool
+async def test_jwt_identity_and_authorization_keep_provisioning_in_admission(
+    monkeypatch: pytest.MonkeyPatch, operation: str, existing_user: bool, model_allowed: bool
 ) -> None:
     from litellm.proxy._types import ScopeMapping
     from litellm.proxy.auth.auth_checks import UserNotFoundError
@@ -6805,7 +6804,7 @@ async def test_auth_builder_identity_lookup_does_not_provision_users(
     private_key, jwk = _get_rsa_key_and_jwk("identity-mode")
     cache: Final = UserApiKeyCache()
     cache.set_cache("litellm_jwt_auth_keys_https://identity.example/jwks", [jwk])
-    user_id: Final = f"identity-mode-{identity_only}-{existing_user}-{model_allowed}"
+    user_id: Final = f"identity-mode-{operation}-{existing_user}-{model_allowed}"
     user: Final = LiteLLM_UserTable(user_id=user_id, organization_memberships=[])
     if existing_user:
         cache.set_cache(user_id, user)
@@ -6831,26 +6830,38 @@ async def test_auth_builder_identity_lookup_does_not_provision_users(
     token: Final = _encode_rsa_jwt(
         private_key, "https://identity.example", "gateway", "identity-mode", {"sub": user_id, "scope": "allowed"}
     )
-    pending: Final = JWTAuthManager.auth_builder(
-        api_key=token,
-        jwt_handler=handler,
+    common: Final = {
+        "api_key": token,
+        "jwt_handler": handler,
+        "prisma_client": database,
+        "user_api_key_cache": cache,
+        "parent_otel_span": None,
+        "proxy_logging_obj": MagicMock(),
+    }
+    if operation == "identity":
+        if not existing_user:
+            with pytest.raises(UserNotFoundError):
+                await JWTAuthManager.resolve_identity(**common)
+        else:
+            identity: Final = await JWTAuthManager.resolve_identity(**common)
+            assert identity.user_id == user_id
+            assert identity.user_object is not None and identity.user_object.user_id == user_id
+        users.create.assert_not_awaited()
+        return
+    authorize: Final = JWTAuthManager.auth_builder if operation == "admit" else JWTAuthManager.authorize_jwt
+    pending: Final = authorize(
+        **common,
         request_data={"model": "allowed-model" if model_allowed else "forbidden-model"},
         general_settings={},
-        route="/example/token" if identity_only else "/mcp/example",
-        prisma_client=database,
-        user_api_key_cache=cache,
-        parent_otel_span=None,
-        proxy_logging_obj=MagicMock(),
-        identity_only=identity_only,
-        allow_provisioning=allow_provisioning,
+        route="/mcp/example",
     )
-    if not identity_only and not model_allowed:
+    if not model_allowed:
         with pytest.raises(HTTPException) as denial:
             await pending
         assert denial.value.status_code == 403
         users.create.assert_not_awaited()
         return
-    if (identity_only or not allow_provisioning) and not existing_user:
+    if operation == "authorize" and not existing_user:
         with pytest.raises(UserNotFoundError):
             await pending
     else:
@@ -6858,7 +6869,7 @@ async def test_auth_builder_identity_lookup_does_not_provision_users(
         assert result["user_id"] == user_id
         assert result["user_object"] is not None
         assert result["user_object"].user_id == user_id
-    assert users.create.await_count == (0 if identity_only or not allow_provisioning or existing_user else 1)
+    assert users.create.await_count == (0 if operation == "authorize" or existing_user else 1)
 
 
 def _entra_agent_registry() -> AgentRegistry:
@@ -6997,6 +7008,14 @@ async def test_auth_builder_propagates_agent_id_from_jwt_claim(monkeypatch, is_a
     )
     jwt_handler.bind_agent_lookup(_entra_agent_registry())
 
+    if identity_only:
+        identity = await JWTAuthManager.resolve_identity(
+            api_key=token, jwt_handler=jwt_handler, prisma_client=None,
+            user_api_key_cache=None, parent_otel_span=None, proxy_logging_obj=None,
+        )
+        assert identity.agent_id == "canonical-agent-id"
+        return
+
     result = await JWTAuthManager.auth_builder(
         api_key=token,
         jwt_handler=jwt_handler,
@@ -7007,10 +7026,9 @@ async def test_auth_builder_propagates_agent_id_from_jwt_claim(monkeypatch, is_a
         user_api_key_cache=None,
         parent_otel_span=None,
         proxy_logging_obj=None,
-        identity_only=identity_only,
     )
 
-    assert result["is_proxy_admin"] is (is_admin_token and not identity_only)
+    assert result["is_proxy_admin"] is is_admin_token
     assert result["agent_id"] == "canonical-agent-id"
 
 
@@ -7025,6 +7043,14 @@ async def test_auth_builder_denies_jwt_naming_unregistered_agent_before_admin_ch
     )
     jwt_handler.bind_agent_lookup(_entra_agent_registry())
 
+    if identity_only:
+        with pytest.raises(HTTPException) as denial:
+            await JWTAuthManager.resolve_identity(
+                api_key=token, jwt_handler=jwt_handler, prisma_client=None,
+                user_api_key_cache=None, parent_otel_span=None, proxy_logging_obj=None,
+            )
+        assert denial.value.status_code == 403
+        return
     with pytest.raises(HTTPException) as exc_info:
         await JWTAuthManager.auth_builder(
             api_key=token,
@@ -7036,7 +7062,39 @@ async def test_auth_builder_denies_jwt_naming_unregistered_agent_before_admin_ch
             user_api_key_cache=None,
             parent_otel_span=None,
             proxy_logging_obj=None,
-            identity_only=identity_only,
         )
 
     assert exc_info.value.status_code == 403
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("admission", [False, True])
+async def test_admin_jwt_team_header_only_provisions_during_admission(monkeypatch, admission: bool):
+    from litellm.proxy.management_endpoints import team_endpoints
+
+    handler, token = _entra_signed_app_token(
+        monkeypatch, azp="canonical-agent-id", scope=LiteLLM_JWTAuth().admin_jwt_scope,
+    )
+    handler.bind_agent_lookup(_entra_agent_registry())
+    handler.litellm_jwtauth.team_id_upsert = True
+    handler.litellm_jwtauth.admin_allowed_routes = ["openai_routes"]
+    database = MagicMock()
+    database.db.litellm_teamtable.find_unique = AsyncMock(return_value=None)
+    create_team = AsyncMock(return_value=LiteLLM_TeamTable(team_id="new-team").model_dump())
+    monkeypatch.setattr(team_endpoints, "new_team", create_team)
+    resolve = JWTAuthManager.auth_builder if admission else JWTAuthManager.authorize_jwt
+
+    result = await resolve(
+        api_key=token, jwt_handler=handler, request_data={}, general_settings={},
+        route="/chat/completions", prisma_client=database,
+        user_api_key_cache=handler.user_api_key_cache, parent_otel_span=None,
+        proxy_logging_obj=MagicMock(), request_headers={"x-litellm-team-id": "new-team"},
+    )
+
+    assert result["is_proxy_admin"] is True
+    if admission:
+        create_team.assert_awaited_once()
+        assert result["team_id"] == "new-team"
+    else:
+        create_team.assert_not_awaited()
+        assert result["team_id"] is None

From ee676d59f259dbb1283b741b7856aaf8559ee3cf Mon Sep 17 00:00:00 2001
From: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 23:08:14 -0700
Subject: [PATCH 67/67] fix(mcp): preserve browser OAuth for unrelated bearer
 tokens

---
 .../mcp_server/bridge_token_flow.py           |  63 ++++++++
 .../mcp_server/discoverable_endpoints.py      |   7 +-
 .../mcp_server/test_discoverable_endpoints.py | 147 +++++++++++++++++-
 3 files changed, 207 insertions(+), 10 deletions(-)

diff --git a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
index f001ee87dbd..2b13baa624b 100644
--- a/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
+++ b/litellm/proxy/_experimental/mcp_server/bridge_token_flow.py
@@ -1,6 +1,8 @@
 """Bridge token flow: litellm identity resolution and the DCR-bridge oauth_delegate mint/refresh pipeline."""
 
 import math
+import os
+import secrets
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Final, Literal
@@ -12,6 +14,9 @@ from typing_extensions import assert_never
 
 from litellm._logging import verbose_logger
 from litellm.proxy._experimental.mcp_server.oauth_utils import TOKEN_NO_CACHE_HEADERS
+from litellm.proxy.common_utils.encrypt_decrypt_utils import (
+    _V2_GCM_PREFIX,  # pyright: ignore[reportPrivateUsage]  # reuse the encrypted credential's format discriminator
+)
 from litellm.types.mcp_server.mcp_server_manager import MCPServer
 
 if TYPE_CHECKING:
@@ -49,6 +54,64 @@ def _litellm_key_from_request(request: Request) -> str | None:
     return None
 
 
+async def oauth_authorization_uses_gateway_credential(request: Request) -> bool:
+    """Classify credentials for browser authorize; candidates still require full authorization."""
+    from litellm.proxy.auth.handle_jwt import JWTHandler  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.proxy_server import (  # noqa: PLC0415  # startup owns the active auth configuration
+        jwt_handler,
+        master_key,
+        user_custom_auth,
+    )
+
+    if "x-litellm-api-key" in request.headers:
+        return True
+    token: Final = _litellm_key_from_request(request)
+    if token is None:
+        return "authorization" in request.headers
+    if token.startswith("sk-") or (master_key and secrets.compare_digest(token.encode(), master_key.encode())):
+        return True
+    if user_custom_auth is not None or jwt_handler.litellm_jwtauth.oidc_userinfo_enabled:
+        return True
+    if not JWTHandler.is_jwt(token):
+        return await _opaque_bearer_is_gateway_credential(token)
+    claims: Final = JWTHandler.get_unverified_claims(token)
+    issuer: Final = claims.get("iss") if claims is not None else None
+    global_issuer: Final = os.getenv("JWT_ISSUER")
+    # An unscoped global validator can accept issuers absent from the configured issuer list.
+    if not isinstance(issuer, str) or not issuer or not global_issuer:
+        return True
+    return issuer == global_issuer or any(
+        issuer == configured.issuer for configured in jwt_handler.litellm_jwtauth.issuers or ()
+    )
+
+
+async def _opaque_bearer_is_gateway_credential(token: str) -> bool:
+    from litellm.proxy._experimental.mcp_server.outbound_credentials.envelope import (
+        is_envelope,  # noqa: PLC0415  # envelope imports bridge types
+        is_refresh_envelope,
+    )
+    from litellm.proxy._types import hash_token  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.auth_checks import ExperimentalUIJWTToken  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.resolvers.exceptions import KeyNotFoundError  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.auth.resolvers.store import IdentityStore  # noqa: PLC0415  # proxy import cycle
+    from litellm.proxy.proxy_server import (  # noqa: PLC0415  # startup owns the identity store dependencies
+        prisma_client,
+        user_api_key_cache,
+    )
+
+    if is_envelope(token) or is_refresh_envelope(token) or token.startswith(_V2_GCM_PREFIX):
+        return True
+    try:
+        if ExperimentalUIJWTToken.get_key_object_from_ui_hash_key(token) is not None:
+            return True
+        await IdentityStore(prisma_client, user_api_key_cache).resolve(hashed_token=hash_token(token))
+    except KeyNotFoundError:
+        return False
+    except Exception as exc:  # noqa: BLE001  # an identity lookup fault must not permit cookie fallback
+        verbose_logger.debug("OAuth bearer ownership could not be checked (%s)", type(exc).__name__)
+    return True
+
+
 def _key_is_active(key_obj: "UserAPIKeyAuth") -> bool:
     """``True`` when the presented key is neither blocked nor past its expiry.
 
diff --git a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
index 7e7189c8a6b..ffb27d5f92e 100644
--- a/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
+++ b/litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py
@@ -29,12 +29,12 @@ from litellm.proxy._experimental.mcp_server.bridge_token_flow import (
     _BridgeRefreshReady,
     _extract_user_id_from_request,
     _finish_bridge_mint,
-    _litellm_key_from_request,  # pyright: ignore[reportPrivateUsage]  # shared credential precedence for authorization issuance
     _prepare_bridge_mint,
     _prepare_bridge_refresh,
     _reload_active_user_by_id,
     authorize_oauth_credential_request,
     can_store_oauth_credential,
+    oauth_authorization_uses_gateway_credential,
 )
 from litellm.proxy._experimental.mcp_server.faults import (
     CallerRejected,
@@ -851,10 +851,11 @@ async def _resolve_oauth_authorization_user(
         _user_id_from_session_cookie,
     )
 
+    use_gateway_credential: Final = enforce_binding and await oauth_authorization_uses_gateway_credential(request)
     request_user_id: Final = (
-        await authorize_oauth_credential_request(request, mcp_server.server_id) if enforce_binding else None
+        await authorize_oauth_credential_request(request, mcp_server.server_id) if use_gateway_credential else None
     )
-    if enforce_binding and request_user_id is None and _litellm_key_from_request(request):
+    if use_gateway_credential and request_user_id is None:
         return _bridge_access_denied_redirect(redirect_uri, state, mcp_server)
     user_id: Final = request_user_id or _user_id_from_session_cookie(request)
     if user_id is None:
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
index 8d300c7c508..aa45b2f6793 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py
@@ -11170,7 +11170,7 @@ async def test_identity_bound_authorization_carries_nonce_and_caller_through_cal
         ),
     )
     request = Request({"type": "http", "scheme": "https", "server": ("proxy.example.com", 443),
-                       "path": "/authorize", "query_string": b"", "headers": []})
+                       "path": "/authorize", "query_string": b"", "headers": [(b"authorization", b"Bearer sk-alice")]})
     with (
         patch(  # test-quality-ok: isolate authenticated request resolution from the real encrypted OAuth round trip
               "litellm.proxy._experimental.mcp_server.discoverable_endpoints.authorize_oauth_credential_request",
@@ -12059,18 +12059,52 @@ async def test_signed_oauth_callback_honors_credential_write_policy(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("allowed", [False, True])
+@pytest.mark.parametrize("credential", [
+    "jwt", "key", "expired_jwt", "wrong_audience", "bad_signature", "malformed_jwt", "missing_issuer",
+    "foreign_explicit", "blank_explicit", "unknown_key", "blocked_key", "expired_key", "opaque_record",
+    "opaque_outage", "opaque_oidc", "opaque_custom", "foreign_unscoped", "foreign_configured", "encrypted", "invalid_encrypted", "envelope", "master",
+])
 async def test_identity_bound_authorize_preserves_presented_jwt_permissions(
     jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
     monkeypatch: pytest.MonkeyPatch,
     allowed: bool,
+    credential: str,
 ) -> None:
+    import jwt
+    from datetime import datetime, timedelta, timezone
     from urllib.parse import parse_qs, urlparse
 
-    from litellm.proxy._experimental.mcp_server import byok_oauth_endpoints, discoverable_endpoints, mcp_server_manager
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._types import JWTIssuerConfig, UserAPIKeyAuth, hash_token
+    from litellm.proxy.auth.auth_checks import ExperimentalUIJWTToken
+
+    from litellm.proxy._experimental.mcp_server import discoverable_endpoints, mcp_server_manager
     from litellm.proxy._types import MCPTransport
     from litellm.types.mcp_server.mcp_server_manager import MCPOAuthIdentityBinding, MCPServer
 
-    _, signing_key = jwt_oauth_identity
+    handler, signing_key = jwt_oauth_identity
+    master: Final = "browser-session-test-signing-key-123456789"
+    monkeypatch.setattr(proxy_server, "master_key", master)
+    monkeypatch.setattr(proxy_server, "user_custom_auth", (lambda: None) if credential == "opaque_custom" else None)
+    handler.litellm_jwtauth.oidc_userinfo_enabled = credential == "opaque_oidc"
+    if credential == "foreign_unscoped":
+        monkeypatch.delenv("JWT_ISSUER")
+    if credential == "foreign_configured":
+        handler.litellm_jwtauth.issuers = [JWTIssuerConfig(
+            issuer="https://unrelated.example.test", jwks_url="https://idp.example.test/jwks",
+            audience="litellm-proxy", user_id_jwt_field="identity.user_id",
+        )]
+    proxy_server.prisma_client.get_data = AsyncMock(
+        return_value=None, side_effect=RuntimeError("database unavailable") if credential == "opaque_outage" else None,
+    )
+    handler.user_api_key_cache.set_cache("cookie-owner", LiteLLM_UserTable(user_id="cookie-owner"))
+    key: Final = "opaque-record" if credential == "opaque_record" else "sk-browser-gateway-key"
+    if credential in ("key", "blocked_key", "expired_key", "opaque_record"):
+        handler.user_api_key_cache.set_cache(hash_token(key), UserAPIKeyAuth(
+            token=hash_token(key), user_id="jwt-owner", blocked=credential in ("blocked_key", "opaque_record"),
+            expires=datetime.now(timezone.utc) - timedelta(seconds=60) if credential == "expired_key" else None,
+        ))
     monkeypatch.setenv("LITELLM_SALT_KEY", "authorize-policy-test-salt")
     server: Final = MCPServer(
         server_id="bound-server", name="bound-server", transport=MCPTransport.http,
@@ -12086,21 +12120,120 @@ async def test_identity_bound_authorize_preserves_presented_jwt_permissions(
         side_effect=lambda auth: [server.server_id] if allowed or auth.mcp_admitted_user_subject else [],
     )
     monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
-    monkeypatch.setattr(  # test-quality-ok: session-cookie decoder is the separate authentication boundary; a valid cookie must not override a denied explicit credential
-        byok_oauth_endpoints, "_user_id_from_session_cookie", lambda request: "jwt-owner",
+    bearer: Final = (
+        key if credential in ("key", "blocked_key", "expired_key", "opaque_record", "unknown_key")
+        else "opaque-bearer" if credential in ("opaque_outage", "opaque_oidc", "opaque_custom")
+        else "not.a.jwt" if credential == "malformed_jwt"
+        else "llm_env_invalid" if credential == "envelope"
+        else "v2:gcm:invalid" if credential == "invalid_encrypted"
+        else master if credential == "master"
+        else ExperimentalUIJWTToken.get_experimental_ui_login_jwt_auth_token(
+            LiteLLM_UserTable(user_id="jwt-owner", user_role="internal_user"),
+        ) if credential == "encrypted"
+        else jwt.encode({"iss": "https://idp.example.test"}, "wrong-signing-key-at-least-32-bytes", algorithm="HS256")
+        if credential == "bad_signature"
+        else jwt.encode({"sub": "jwt-owner"}, signing_key, algorithm="RS256") if credential == "missing_issuer"
+        else _oauth_identity_jwt(
+            signing_key,
+            expires_in=-60 if credential == "expired_jwt" else 300,
+            audience="another-service" if credential == "wrong_audience" else "litellm-proxy",
+            issuer="https://unrelated.example.test" if credential.startswith("foreign_") or credential == "blank_explicit" else "https://idp.example.test",
+        )
+    )
+    cookie: Final = jwt.encode(
+        {"user_id": "cookie-owner", "login_method": "sso", "exp": int(time.time()) + 300}, master, algorithm="HS256",
     )
     response: Final = await discoverable_endpoints.authorize_with_server(
-        request=_token_request({"Authorization": f"Bearer {_oauth_identity_jwt(signing_key)}"}),
+        request=_token_request({
+            "Authorization": f"Bearer {bearer}", "Cookie": f"token={cookie}",
+            **({"x-litellm-api-key": bearer} if credential == "foreign_explicit" else {}),
+            **({"x-litellm-api-key": ""} if credential == "blank_explicit" else {}),
+        }),
         mcp_server=server, client_id="client", redirect_uri="http://127.0.0.1:6274/callback",
         state="client-state", code_challenge="pkce-challenge", code_challenge_method="S256",
     )
     redirect: Final = urlparse(response.headers["location"])
     query: Final = parse_qs(redirect.query)
-    if allowed:
+    if allowed and credential in ("jwt", "key", "foreign_unscoped", "foreign_configured"):
         assert redirect.hostname == "upstream.example.test"
         assert query["nonce"] and response.headers.get("set-cookie")
+        assert all(call.args[0].user_id == "jwt-owner" for call in manager.get_allowed_mcp_servers.await_args_list)
     else:
         assert redirect.hostname == "127.0.0.1"
         assert query["error"] == ["access_denied"]
         assert query["state"] == ["client-state"]
         assert "set-cookie" not in response.headers
+
+    proxy_server.prisma_client.db.litellm_mcpusercredentials.upsert.assert_not_called()
+    proxy_server.prisma_client.db.litellm_usertable.create.assert_not_called()
+    proxy_server.prisma_client.db.litellm_teamtable.create.assert_not_called()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("credential", ["none", "opaque", "foreign_jwt"])
+@pytest.mark.parametrize("cookie_state", ["allowed", "server_denied", "expired", "missing"])
+async def test_identity_bound_authorize_unrelated_bearer_uses_browser_session(
+    jwt_oauth_identity: tuple["JWTHandler", "RSAPrivateKey"],
+    monkeypatch: pytest.MonkeyPatch,
+    credential: str,
+    cookie_state: str,
+) -> None:
+    import jwt
+    from urllib.parse import parse_qs, urlparse
+
+    from litellm.models.user import LiteLLM_UserTable
+    from litellm.proxy import proxy_server
+    from litellm.proxy._experimental.mcp_server import discoverable_endpoints, mcp_server_manager
+    from litellm.proxy._types import MCPTransport
+    from litellm.types.mcp_server.mcp_server_manager import MCPOAuthIdentityBinding, MCPServer
+
+    handler, signing_key = jwt_oauth_identity
+    master: Final = "browser-session-test-signing-key-123456789"
+    monkeypatch.setattr(proxy_server, "master_key", master)
+    monkeypatch.setattr(proxy_server, "user_custom_auth", None)
+    monkeypatch.setenv("LITELLM_SALT_KEY", "authorize-policy-test-salt")
+    handler.user_api_key_cache.set_cache("cookie-owner", LiteLLM_UserTable(user_id="cookie-owner"))
+    proxy_server.prisma_client.get_data = AsyncMock(return_value=None)
+    server: Final = MCPServer(
+        server_id="bound-server", name="bound-server", transport=MCPTransport.http,
+        auth_type=MCPAuth.oauth2, oauth2_flow="authorization_code", client_id="client",
+        authorization_url="https://upstream.example.test/authorize", token_url="https://upstream.example.test/token",
+        oauth_identity_binding=MCPOAuthIdentityBinding(
+            mode="enforce", issuer="https://upstream.example.test", audiences=["client"],
+        ),
+    )
+    manager: Final = MagicMock()
+    manager.get_allowed_mcp_servers = AsyncMock(return_value=[] if cookie_state == "server_denied" else [server.server_id])
+    monkeypatch.setattr(mcp_server_manager, "global_mcp_server_manager", manager)
+    bearer: Final = (
+        _oauth_identity_jwt(signing_key, issuer="https://unrelated.example.test")
+        if credential == "foreign_jwt" else "unrelated-upstream-bearer"
+    )
+    cookie: Final = jwt.encode(
+        {"user_id": "cookie-owner", "login_method": "sso", "exp": int(time.time()) + (-60 if cookie_state == "expired" else 300)},
+        master, algorithm="HS256",
+    )
+    response: Final = await discoverable_endpoints.authorize_with_server(
+        request=_token_request({
+            **({"Authorization": f"Bearer {bearer}"} if credential != "none" else {}),
+            **({"Cookie": f"token={cookie}"} if cookie_state != "missing" else {}),
+        }),
+        mcp_server=server, client_id="client", redirect_uri="http://127.0.0.1:6274/callback",
+        state="client-state", code_challenge="pkce-challenge", code_challenge_method="S256",
+    )
+    redirect: Final = urlparse(response.headers["location"])
+    query: Final = parse_qs(redirect.query)
+    if cookie_state == "allowed":
+        assert redirect.hostname == "upstream.example.test"
+        assert query["nonce"] and response.headers.get("set-cookie")
+        manager.get_allowed_mcp_servers.assert_awaited_once()
+        assert manager.get_allowed_mcp_servers.call_args.args[0].user_id == "cookie-owner"
+    elif cookie_state == "server_denied":
+        assert query["error"] == ["access_denied"]
+        assert query["state"] == ["client-state"]
+    else:
+        assert redirect.path == "/sso/key/generate"
+        manager.get_allowed_mcp_servers.assert_not_awaited()
+    proxy_server.prisma_client.db.litellm_mcpusercredentials.upsert.assert_not_called()
+    proxy_server.prisma_client.db.litellm_usertable.create.assert_not_called()
+    proxy_server.prisma_client.db.litellm_teamtable.create.assert_not_called()