From bede8b5ea46c24b20d138c79025dd67beee97763 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 3 Sep 2026 02:49:49 -0700
Subject: [PATCH 01/31] fix(proxy): stop shipping the literal string "None" as
 error type and param

The proxy's exception tails defaulted `type` and `param` to the four-character
string "None", which is neither a known OpenAI error type nor the JSON null the
nullable `param` field is typed as, so a client's error handler matched nothing
and fell into its generic branch.

Lifts the helpers PR #39521 added for the unified LLM endpoints into
litellm/proxy/common_utils/openai_error_payload.py and calls them from the file,
rerank, image, realtime, anthropic, and pass-through route families, plus the
shared handle_exception_on_proxy handler that the management, batches,
fine-tuning, credential, SCIM, guardrail, and customer routes funnel through.

The remaining families (proxy_server, auth, health, spend tracking, and
management endpoints) follow in separate PRs so each slice stays QA'able on a
live proxy.
---
 .../proxy/anthropic_endpoints/endpoints.py    |  11 +-
 litellm/proxy/common_request_processing.py    |  78 ++++--------
 .../common_utils/openai_error_payload.py      |  48 +++++++
 litellm/proxy/image_endpoints/endpoints.py    |  17 ++-
 .../openai_files_endpoints/files_endpoints.py | 109 ++++++++--------
 .../pass_through_endpoints.py                 |  23 ++--
 litellm/proxy/realtime_endpoints/endpoints.py |  41 +++---
 litellm/proxy/rerank_endpoints/endpoints.py   |  17 ++-
 litellm/proxy/utils.py                        |   5 +-
 .../common_utils/test_openai_error_payload.py | 117 ++++++++++++++++++
 .../test_files_endpoint.py                    |  10 +-
 .../proxy/utils/helpers/test_error_helpers.py |   2 +-
 12 files changed, 320 insertions(+), 158 deletions(-)
 create mode 100644 litellm/proxy/common_utils/openai_error_payload.py
 create mode 100644 tests/test_litellm/proxy/common_utils/test_openai_error_payload.py

diff --git a/litellm/proxy/anthropic_endpoints/endpoints.py b/litellm/proxy/anthropic_endpoints/endpoints.py
index 7f0045c1d93..f26cb4d41f7 100644
--- a/litellm/proxy/anthropic_endpoints/endpoints.py
+++ b/litellm/proxy/anthropic_endpoints/endpoints.py
@@ -25,6 +25,11 @@ from litellm.proxy.common_request_processing import (
     proxy_exception_from_http_exception,
 )
 from litellm.proxy.common_utils.http_parsing_utils import _read_request_body
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 from litellm.types.utils import TokenCountResponse
 
 router: Final = APIRouter()
@@ -221,9 +226,9 @@ async def anthropic_response(
         error_msg: Final = f"{e}"
         raise ProxyException(
             message=getattr(e, "message", error_msg),
-            type=getattr(e, "type", "None"),
-            param=getattr(e, "param", "None"),
-            code=getattr(e, "status_code", 500),
+            type=openai_error_type(e, error_status_code(e, 500)),
+            param=openai_error_param(e),
+            code=error_status_code(e, 500),
             headers=headers,
         )
 
diff --git a/litellm/proxy/common_request_processing.py b/litellm/proxy/common_request_processing.py
index 6542842f5e4..99028c3645a 100644
--- a/litellm/proxy/common_request_processing.py
+++ b/litellm/proxy/common_request_processing.py
@@ -54,6 +54,12 @@ from litellm.proxy.common_utils.callback_utils import (
     get_logging_caching_headers,
     get_remaining_tokens_and_requests_from_request_data,
 )
+from litellm.proxy.common_utils.openai_error_payload import (
+    attribute_of,
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 from litellm.proxy.common_utils.sse_keepalive import (
     SSE_COMMENT_PING_BYTES,
     coerce_keepalive_interval,
@@ -463,46 +469,6 @@ def _stream_usage_tracking_updates(
     }
 
 
-def _getattr_object(value: object, name: str, default: object = None) -> object:
-    return getattr(value, name, default)
-
-
-_OPENAI_ERROR_TYPE_BY_STATUS: Final[Mapping[int, str]] = MappingProxyType(
-    {
-        status.HTTP_401_UNAUTHORIZED: "authentication_error",
-        status.HTTP_403_FORBIDDEN: "permission_error",
-        status.HTTP_429_TOO_MANY_REQUESTS: "rate_limit_error",
-    }
-)
-
-
-def _error_status_code(exc: object, default: int) -> int:
-    """The HTTP status an exception carries, or ``default`` when it carries none."""
-    carried: Final = _getattr_object(exc, "status_code")
-    return carried if isinstance(carried, int) and not isinstance(carried, bool) else default
-
-
-def _openai_error_type(exc: object, status_code: int) -> str:
-    """OpenAI types ``error.type`` as a required string, so an exception carrying none
-    falls back to the type its status code stands for."""
-    carried: Final = _getattr_object(exc, "type")
-    if isinstance(carried, str):
-        return carried
-    mapped: Final = _OPENAI_ERROR_TYPE_BY_STATUS.get(status_code)
-    if mapped is not None:
-        return mapped
-    if status_code < status.HTTP_500_INTERNAL_SERVER_ERROR:
-        return "invalid_request_error"
-    return "internal_server_error"
-
-
-def _openai_error_param(exc: object) -> str | None:
-    """OpenAI types ``error.param`` as nullable, so an exception carrying none
-    serializes as JSON ``null``."""
-    carried: Final = _getattr_object(exc, "param")
-    return carried if isinstance(carried, str) else None
-
-
 class _UpstreamHttpResponse(Protocol):
     @property
     def status_code(self) -> int: ...
@@ -572,15 +538,15 @@ def serialize_http_exception_detail(
 
 
 def proxy_exception_from_http_exception(exc: HTTPException, headers: dict[str, str]) -> ProxyException:
-    raw_detail: Final = _getattr_object(exc, "detail", str(exc))
+    raw_detail: Final = attribute_of(exc, "detail", str(exc))
     message, structured_fields = serialize_http_exception_detail(raw_detail)
     existing_fields: Final = getattr(exc, "provider_specific_fields", None) or {}
     merged_fields: Final = {**existing_fields, **structured_fields} if structured_fields else (existing_fields or None)
-    error_status: Final = _error_status_code(exc, status.HTTP_400_BAD_REQUEST)
+    error_status: Final = error_status_code(exc, status.HTTP_400_BAD_REQUEST)
     return ProxyException(
         message=message,
-        type=_openai_error_type(exc, error_status),
-        param=_openai_error_param(exc),
+        type=openai_error_type(exc, error_status),
+        param=openai_error_param(exc),
         code=error_status,
         provider_specific_fields=merged_fields,
         headers=headers,
@@ -864,8 +830,8 @@ def sse_error_payload(exc: BaseException) -> tuple[int, Mapping[str, object]]:
     are byte-identical.
     """
     # Preserve status code from HTTPException (e.g. guardrail blocks)
-    error_status: Final = _error_status_code(exc, status.HTTP_500_INTERNAL_SERVER_ERROR)
-    raw_detail: Final = _getattr_object(exc, "detail", "Error processing stream start")
+    error_status: Final = error_status_code(exc, status.HTTP_500_INTERNAL_SERVER_ERROR)
+    raw_detail: Final = attribute_of(exc, "detail", "Error processing stream start")
     message, structured_fields = serialize_http_exception_detail(raw_detail)
 
     existing_fields: Final = getattr(exc, "provider_specific_fields", None) or {}
@@ -873,8 +839,8 @@ def sse_error_payload(exc: BaseException) -> tuple[int, Mapping[str, object]]:
 
     error_obj: Final = {
         "message": message,
-        "type": _openai_error_type(exc, error_status),
-        "param": _openai_error_param(exc),
+        "type": openai_error_type(exc, error_status),
+        "param": openai_error_param(exc),
         "code": str(error_status),
     }
     if not merged_fields:
@@ -2755,10 +2721,10 @@ class ProxyBaseLLMRequestProcessing:
         ``ResponsesAPIResponse`` directly. Handle both shapes so the
         container-ownership recording path can walk ``.output`` either way.
         """
-        completed: Final = _getattr_object(stream_response, "completed_response")
+        completed: Final = attribute_of(stream_response, "completed_response")
         if completed is None:
             return None
-        response_obj: Final = _getattr_object(completed, "response")
+        response_obj: Final = attribute_of(completed, "response")
         if response_obj is not None:
             return response_obj
         return completed
@@ -3380,7 +3346,7 @@ class ProxyBaseLLMRequestProcessing:
         headers = getattr(e, "headers", None) or {}
         if not headers:
             # Try to get headers from e.response.headers (httpx.Response)
-            _response: Final = _getattr_object(e, "response")
+            _response: Final = attribute_of(e, "response")
             if _response is not None:
                 _response_headers: Final = getattr(_response, "headers", None)
                 if _response_headers:
@@ -3451,8 +3417,8 @@ class ProxyBaseLLMRequestProcessing:
             _code = status.HTTP_500_INTERNAL_SERVER_ERROR
         raise ProxyException(
             message=redact_internal_details_from_client_message(getattr(e, "message", error_msg)),
-            type=_openai_error_type(e, _code),
-            param=_openai_error_param(e),
+            type=openai_error_type(e, _code),
+            param=openai_error_param(e),
             openai_code=getattr(e, "code", None),
             code=_code,
             provider_specific_fields=getattr(e, "provider_specific_fields", None),
@@ -3662,11 +3628,11 @@ class ProxyBaseLLMRequestProcessing:
 
             if isinstance(e, HTTPException):
                 raise e
-            stream_error_status: Final = _error_status_code(e, status.HTTP_500_INTERNAL_SERVER_ERROR)
+            stream_error_status: Final = error_status_code(e, status.HTTP_500_INTERNAL_SERVER_ERROR)
             proxy_exception: Final = ProxyException(
                 message=redact_internal_details_from_client_message(getattr(e, "message", str(e))),
-                type=_openai_error_type(e, stream_error_status),
-                param=_openai_error_param(e),
+                type=openai_error_type(e, stream_error_status),
+                param=openai_error_param(e),
                 code=stream_error_status,
             )
             stream_completed = True
diff --git a/litellm/proxy/common_utils/openai_error_payload.py b/litellm/proxy/common_utils/openai_error_payload.py
new file mode 100644
index 00000000000..180ec152094
--- /dev/null
+++ b/litellm/proxy/common_utils/openai_error_payload.py
@@ -0,0 +1,48 @@
+"""Shapes the ``error`` object the proxy answers with so it matches OpenAI's contract:
+``type`` is a required string and ``param`` is nullable, neither of which the literal
+string ``"None"`` satisfies."""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Final
+
+from fastapi import status
+
+_OPENAI_ERROR_TYPE_BY_STATUS: Final[Mapping[int, str]] = MappingProxyType(
+    {
+        status.HTTP_401_UNAUTHORIZED: "authentication_error",
+        status.HTTP_403_FORBIDDEN: "permission_error",
+        status.HTTP_429_TOO_MANY_REQUESTS: "rate_limit_error",
+    }
+)
+
+
+def attribute_of(value: object, name: str, default: object = None) -> object:
+    return getattr(value, name, default)
+
+
+def error_status_code(exc: object, default: int) -> int:
+    """The HTTP status an exception carries, or ``default`` when it carries none."""
+    carried: Final = attribute_of(exc, "status_code")
+    return carried if isinstance(carried, int) and not isinstance(carried, bool) else default
+
+
+def openai_error_type(exc: object, status_code: int) -> str:
+    """OpenAI types ``error.type`` as a required string, so an exception carrying none
+    falls back to the type its status code stands for."""
+    carried: Final = attribute_of(exc, "type")
+    if isinstance(carried, str):
+        return carried
+    mapped: Final = _OPENAI_ERROR_TYPE_BY_STATUS.get(status_code)
+    if mapped is not None:
+        return mapped
+    if status_code < status.HTTP_500_INTERNAL_SERVER_ERROR:
+        return "invalid_request_error"
+    return "internal_server_error"
+
+
+def openai_error_param(exc: object) -> str | None:
+    """OpenAI types ``error.param`` as nullable, so an exception carrying none
+    serializes as JSON ``null``."""
+    carried: Final = attribute_of(exc, "param")
+    return carried if isinstance(carried, str) else None
diff --git a/litellm/proxy/image_endpoints/endpoints.py b/litellm/proxy/image_endpoints/endpoints.py
index 83caa92ede5..b83f7e5cd60 100644
--- a/litellm/proxy/image_endpoints/endpoints.py
+++ b/litellm/proxy/image_endpoints/endpoints.py
@@ -16,6 +16,11 @@ from litellm.litellm_core_utils.prompt_templates.common_utils import (
 from litellm.proxy._types import *
 from litellm.proxy.auth.user_api_key_auth import UserAPIKeyAuth, user_api_key_auth
 from litellm.proxy.common_request_processing import ProxyBaseLLMRequestProcessing
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 from litellm.proxy.route_llm_request import route_request
 from litellm.types.llms.openai import ChatCompletionUserMessage
 
@@ -193,18 +198,18 @@ async def image_generation(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
                 openai_code=getattr(e, "code", None),
-                code=getattr(e, "status_code", 500),
+                code=error_status_code(e, 500),
             )
 
 
diff --git a/litellm/proxy/openai_files_endpoints/files_endpoints.py b/litellm/proxy/openai_files_endpoints/files_endpoints.py
index bf07f4748ef..c315d30b8f3 100644
--- a/litellm/proxy/openai_files_endpoints/files_endpoints.py
+++ b/litellm/proxy/openai_files_endpoints/files_endpoints.py
@@ -45,6 +45,11 @@ from litellm.proxy.common_utils.openai_endpoint_utils import (
     get_custom_llm_provider_from_request_headers,
     get_custom_llm_provider_from_request_query,
 )
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 from litellm.proxy.openai_files_endpoints.batch_file_validation import (
     check_batch_file_upload,
     raise_batch_file_validation_failure,
@@ -296,22 +301,22 @@ async def route_create_file(
         if managed_files_obj is None:
             raise ProxyException(
                 message="Managed files hook not found",
-                type="None",
-                param="None",
+                type=ProxyErrorTypes.internal_server_error.value,
+                param=None,
                 code=500,
             )
         if llm_router is None:
             raise ProxyException(
                 message="LLM Router not found",
-                type="None",
-                param="None",
+                type=ProxyErrorTypes.internal_server_error.value,
+                param=None,
                 code=500,
             )
         if not isinstance(managed_files_obj, BaseFileEndpoints):
             raise ProxyException(
                 message="Managed files hook is not a BaseFileEndpoints",
-                type="None",
-                param="None",
+                type=ProxyErrorTypes.internal_server_error.value,
+                param=None,
                 code=500,
             )
         # Managed files internally calls llm_router.acreate_file() which includes loadbalancing
@@ -713,17 +718,17 @@ async def create_file(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e.detail)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
             )
     finally:
         for spool in spools:
@@ -812,22 +817,22 @@ async def get_file_content(
             if managed_files_obj is None:
                 raise ProxyException(
                     message="Managed files hook not found",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
             if llm_router is None:
                 raise ProxyException(
                     message="LLM Router not found",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
             if not isinstance(managed_files_obj, BaseFileEndpoints):
                 raise ProxyException(
                     message="Managed files hook is not a BaseFileEndpoints",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
 
@@ -1021,17 +1026,17 @@ async def get_file_content(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e.detail)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
             )
 
 
@@ -1151,15 +1156,15 @@ async def get_file(
             if managed_files_obj is None:
                 raise ProxyException(
                     message="Managed files hook not found",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
             if not isinstance(managed_files_obj, BaseFileEndpoints):
                 raise ProxyException(
                     message="Managed files hook is not a BaseFileEndpoints",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
             response = await managed_files_obj.afile_retrieve(
@@ -1215,17 +1220,17 @@ async def get_file(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e.detail)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
             )
 
 
@@ -1355,22 +1360,22 @@ async def delete_file(
             if managed_files_obj is None:
                 raise ProxyException(
                     message="Managed files hook not found",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
             if llm_router is None:
                 raise ProxyException(
                     message="LLM Router not found",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
             if not isinstance(managed_files_obj, BaseFileEndpoints):
                 raise ProxyException(
                     message="Managed files hook is not a BaseFileEndpoints",
-                    type="None",
-                    param="None",
+                    type=ProxyErrorTypes.internal_server_error.value,
+                    param=None,
                     code=500,
                 )
 
@@ -1427,17 +1432,17 @@ async def delete_file(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e.detail)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
             )
 
 
@@ -1629,15 +1634,15 @@ async def list_files(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e.detail)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
             )
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 79d5d0a016f..64ce461990a 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -77,6 +77,11 @@ from litellm.proxy.common_utils.http_parsing_utils import (
     _read_request_body,
     _safe_get_request_headers,
 )
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 from litellm.proxy.common_utils.sse_keepalive import (
     wrap_passthrough_sse_bytes_with_keepalive_pings,
 )
@@ -310,9 +315,9 @@ async def chat_completion_pass_through_endpoint(
         error_msg: Final = f"{e}"
         raise ProxyException(
             message=getattr(e, "message", error_msg),
-            type=getattr(e, "type", "None"),
-            param=getattr(e, "param", "None"),
-            code=getattr(e, "status_code", 500),
+            type=openai_error_type(e, error_status_code(e, 500)),
+            param=openai_error_param(e),
+            code=error_status_code(e, 500),
         )
 
 
@@ -1677,18 +1682,18 @@ async def pass_through_request(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(getattr(e, "detail", str(e)))),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
                 headers=custom_headers,
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
                 headers=custom_headers,
             )
 
diff --git a/litellm/proxy/realtime_endpoints/endpoints.py b/litellm/proxy/realtime_endpoints/endpoints.py
index 7f9cd251a8a..9996f60098d 100644
--- a/litellm/proxy/realtime_endpoints/endpoints.py
+++ b/litellm/proxy/realtime_endpoints/endpoints.py
@@ -17,6 +17,11 @@ from litellm.proxy.common_utils.encrypt_decrypt_utils import (
     encrypt_value_helper,
 )
 from litellm.proxy.common_utils.http_parsing_utils import _read_request_body
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 from litellm.types.realtime import (
     RealtimeClientSecretRequest,
     RealtimeClientSecretResponse,
@@ -301,15 +306,15 @@ async def create_realtime_client_secret(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", http_status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, http_status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, http_status.HTTP_400_BAD_REQUEST),
             )
         raise ProxyException(
             message=getattr(e, "message", str(e)),
-            type=getattr(e, "type", "None"),
-            param=getattr(e, "param", "None"),
-            code=getattr(e, "status_code", 500),
+            type=openai_error_type(e, error_status_code(e, 500)),
+            param=openai_error_param(e),
+            code=error_status_code(e, 500),
         )
 
     if upstream_resp.status_code != 200:
@@ -492,15 +497,15 @@ async def proxy_realtime_calls(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", http_status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, http_status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, http_status.HTTP_400_BAD_REQUEST),
             )
         raise ProxyException(
             message=getattr(e, "message", str(e)),
-            type=getattr(e, "type", "None"),
-            param=getattr(e, "param", "None"),
-            code=getattr(e, "status_code", 500),
+            type=openai_error_type(e, error_status_code(e, 500)),
+            param=openai_error_param(e),
+            code=error_status_code(e, 500),
         )
 
     return Response(
@@ -605,15 +610,15 @@ async def create_realtime_transcription_session(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "detail", getattr(e, "message", str(e))),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", http_status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, http_status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, http_status.HTTP_400_BAD_REQUEST),
             )
         raise ProxyException(
             message=getattr(e, "message", str(e)),
-            type=getattr(e, "type", "None"),
-            param=getattr(e, "param", "None"),
-            code=getattr(e, "status_code", 500),
+            type=openai_error_type(e, error_status_code(e, 500)),
+            param=openai_error_param(e),
+            code=error_status_code(e, 500),
         )
 
     if upstream_resp.status_code != 200:
diff --git a/litellm/proxy/rerank_endpoints/endpoints.py b/litellm/proxy/rerank_endpoints/endpoints.py
index dd5803796b7..16cd7368e4a 100644
--- a/litellm/proxy/rerank_endpoints/endpoints.py
+++ b/litellm/proxy/rerank_endpoints/endpoints.py
@@ -11,6 +11,11 @@ from litellm._logging import verbose_proxy_logger
 from litellm.proxy._types import *
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.proxy.common_request_processing import ProxyBaseLLMRequestProcessing
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
 
 router: Final = APIRouter()
 
@@ -112,15 +117,15 @@ async def rerank(
         if isinstance(e, HTTPException):
             raise ProxyException(
                 message=getattr(e, "message", str(e)),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", status.HTTP_400_BAD_REQUEST),
+                type=openai_error_type(e, error_status_code(e, status.HTTP_400_BAD_REQUEST)),
+                param=openai_error_param(e),
+                code=error_status_code(e, status.HTTP_400_BAD_REQUEST),
             )
         else:
             error_msg: Final = f"{e}"
             raise ProxyException(
                 message=getattr(e, "message", error_msg),
-                type=getattr(e, "type", "None"),
-                param=getattr(e, "param", "None"),
-                code=getattr(e, "status_code", 500),
+                type=openai_error_type(e, error_status_code(e, 500)),
+                param=openai_error_param(e),
+                code=error_status_code(e, 500),
             )
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index cab2bd6d9db..5c0fbd64744 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -37,6 +37,7 @@ from litellm.proxy._types import (
     SpendLogsMetadata,
     SpendLogsPayload,
 )
+from litellm.proxy.common_utils.openai_error_payload import openai_error_param
 from litellm.proxy.spend_tracking.spend_log_error_logger import spend_log_error
 from litellm.types.guardrails import GuardrailEventHooks
 from litellm.types.proxy.model_listing import ModelInfoResponse
@@ -7098,7 +7099,7 @@ def handle_exception_on_proxy(e: Exception) -> ProxyException:
         return ProxyException(
             message=getattr(e, "detail", f"error({e})"),
             type=ProxyErrorTypes.internal_server_error,
-            param=getattr(e, "param", "None"),
+            param=openai_error_param(e),
             code=getattr(e, "status_code", status.HTTP_500_INTERNAL_SERVER_ERROR),
         )
     elif isinstance(e, ProxyException):
@@ -7107,7 +7108,7 @@ def handle_exception_on_proxy(e: Exception) -> ProxyException:
     return ProxyException(
         message=str(e),
         type=ProxyErrorTypes.internal_server_error,
-        param=getattr(e, "param", "None"),
+        param=openai_error_param(e),
         code=_status_code,
     )
 
diff --git a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
new file mode 100644
index 00000000000..c165d7ffdb1
--- /dev/null
+++ b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
@@ -0,0 +1,117 @@
+import json
+
+import pytest
+from fastapi import HTTPException
+
+from litellm.proxy._types import ProxyErrorTypes, ProxyException
+from litellm.proxy.common_utils.openai_error_payload import (
+    error_status_code,
+    openai_error_param,
+    openai_error_type,
+)
+
+
+@pytest.mark.parametrize(
+    "status_code, expected_type",
+    [
+        (400, "invalid_request_error"),
+        (401, "authentication_error"),
+        (403, "permission_error"),
+        (404, "invalid_request_error"),
+        (422, "invalid_request_error"),
+        (429, "rate_limit_error"),
+        (499, "invalid_request_error"),
+        (500, "internal_server_error"),
+        (502, "internal_server_error"),
+        (503, "internal_server_error"),
+    ],
+)
+def test_status_code_decides_the_type_when_the_exception_carries_none(status_code, expected_type):
+    """A route that raises a bare HTTPException carries no error type, so the status it
+    answered with is the only thing left to name the OpenAI type from."""
+    assert openai_error_type(HTTPException(status_code=status_code, detail="boom"), status_code) == expected_type
+
+
+def test_a_carried_type_wins_over_the_one_the_status_would_imply():
+    """A ProxyException raised mid-request already names its own type, and relabelling a
+    402 budget_exceeded as the status map's guess would lose what the client branches on."""
+    carried = ProxyException(
+        message="Budget has been exceeded",
+        type=ProxyErrorTypes.budget_exceeded.value,
+        param=None,
+        code=400,
+    )
+
+    assert openai_error_type(carried, 400) == ProxyErrorTypes.budget_exceeded.value
+
+
+@pytest.mark.parametrize("carried_type", [None, 400, {"type": "invalid_request_error"}, ["invalid_request_error"]])
+def test_a_non_string_carried_type_falls_back_to_the_status(carried_type):
+    """OpenAI types error.type as a string, so anything else on the exception is not one and
+    must not reach the wire the way the literal "None" used to."""
+
+    class _Carrier(Exception):
+        type = carried_type
+
+    assert openai_error_type(_Carrier("boom"), 401) == "authentication_error"
+
+
+def test_the_type_is_never_the_string_none_after_a_json_round_trip():
+    """The bug this module exists for: json.dumps of a "None" default is indistinguishable
+    from a real type to a client's error handler."""
+    payload = json.loads(
+        json.dumps(
+            {
+                "type": openai_error_type(HTTPException(status_code=400, detail="boom"), 400),
+                "param": openai_error_param(HTTPException(status_code=400, detail="boom")),
+            }
+        )
+    )
+
+    assert payload == {"type": "invalid_request_error", "param": None}
+
+
+def test_a_carried_param_names_the_offending_field():
+    carried = ProxyException(message="Invalid purpose", type="invalid_request_error", param="purpose", code=400)
+
+    assert openai_error_param(carried) == "purpose"
+
+
+@pytest.mark.parametrize("exc", [HTTPException(status_code=400, detail="boom"), ValueError("boom"), None])
+def test_param_is_json_null_when_the_exception_names_no_field(exc):
+    assert openai_error_param(exc) is None
+
+
+def test_a_non_string_carried_param_is_json_null():
+    class _Carrier(Exception):
+        param = 42
+
+    assert openai_error_param(_Carrier("boom")) is None
+
+
+def test_a_carried_status_code_wins_over_the_default():
+    assert error_status_code(HTTPException(status_code=429, detail="slow down"), 400) == 429
+
+
+@pytest.mark.parametrize("default", [400, 500])
+def test_the_default_status_stands_when_the_exception_carries_none(default):
+    assert error_status_code(ValueError("boom"), default) == default
+
+
+@pytest.mark.parametrize("carried_status", [True, False, "429", None, 429.0])
+def test_a_non_int_carried_status_falls_back_to_the_default(carried_status):
+    """True is an int in Python but not an HTTP status, and a stringified one would break
+    every caller that compares the code numerically."""
+
+    class _Carrier(Exception):
+        status_code = carried_status
+
+    assert error_status_code(_Carrier("boom"), 500) == 500
+
+
+def test_a_status_carried_by_an_exception_drives_the_type_it_reports():
+    """The two helpers compose at every call site: the status the exception carries is what
+    names its type, not the default the route would have used."""
+    exc = HTTPException(status_code=403, detail="blocked by policy")
+
+    assert openai_error_type(exc, error_status_code(exc, 400)) == "permission_error"
diff --git a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
index bca97915347..123d54789bf 100644
--- a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
+++ b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
@@ -2920,9 +2920,9 @@ def test_unscoped_list_files_accepts_every_documented_purpose(
 def test_list_files_reports_a_bad_target_model_names_as_a_400(
     mocker: MockerFixture, monkeypatch, llm_router: Router
 ):
-    """The exception tail reports an HTTPException with its own status and error
-    type rather than relabelling it, so a client that branches on either keeps
-    reading the same thing off a bad request."""
+    """The exception tail answers with the OpenAI error object a client can branch on:
+    the type its 400 status stands for, and a JSON null param rather than the literal
+    string "None" no OpenAI SDK has a case for."""
     _setup_unscoped_list_files_route(mocker, monkeypatch, llm_router, _permissive_afile_list)
 
     response = _get_list_files("/v1/files?target_model_names=gpt-3.5-turbo,gpt-4o")
@@ -2931,8 +2931,8 @@ def test_list_files_reports_a_bad_target_model_names_as_a_400(
     assert response.json() == {
         "error": {
             "message": "target_model_names on list files must be a list of one model name. Example: ['gpt-4o']",
-            "type": "None",
-            "param": "None",
+            "type": "invalid_request_error",
+            "param": None,
             "code": "400",
         }
     }
diff --git a/tests/test_litellm/proxy/utils/helpers/test_error_helpers.py b/tests/test_litellm/proxy/utils/helpers/test_error_helpers.py
index e73e3c151e0..dc30798df55 100644
--- a/tests/test_litellm/proxy/utils/helpers/test_error_helpers.py
+++ b/tests/test_litellm/proxy/utils/helpers/test_error_helpers.py
@@ -135,7 +135,7 @@ def test_handle_exception_on_proxy_happy_path_generic_exception_defaults_to_500(
         "message": "kaboom",
         "type": ProxyErrorTypes.internal_server_error.value,
         "code": "500",
-        "param": "None",
+        "param": None,
     }
 
 

From 7a5b8bce7e42157cbfcbed306e2ea33672c7e5ea Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 3 Sep 2026 03:40:58 -0700
Subject: [PATCH 02/31] test(proxy): type the parametrized inputs of the error
 payload helper tests

---
 .../proxy/common_utils/test_openai_error_payload.py    | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
index c165d7ffdb1..3b39ea706fe 100644
--- a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
+++ b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
@@ -26,7 +26,7 @@ from litellm.proxy.common_utils.openai_error_payload import (
         (503, "internal_server_error"),
     ],
 )
-def test_status_code_decides_the_type_when_the_exception_carries_none(status_code, expected_type):
+def test_status_code_decides_the_type_when_the_exception_carries_none(status_code: int, expected_type: str):
     """A route that raises a bare HTTPException carries no error type, so the status it
     answered with is the only thing left to name the OpenAI type from."""
     assert openai_error_type(HTTPException(status_code=status_code, detail="boom"), status_code) == expected_type
@@ -46,7 +46,7 @@ def test_a_carried_type_wins_over_the_one_the_status_would_imply():
 
 
 @pytest.mark.parametrize("carried_type", [None, 400, {"type": "invalid_request_error"}, ["invalid_request_error"]])
-def test_a_non_string_carried_type_falls_back_to_the_status(carried_type):
+def test_a_non_string_carried_type_falls_back_to_the_status(carried_type: object):
     """OpenAI types error.type as a string, so anything else on the exception is not one and
     must not reach the wire the way the literal "None" used to."""
 
@@ -78,7 +78,7 @@ def test_a_carried_param_names_the_offending_field():
 
 
 @pytest.mark.parametrize("exc", [HTTPException(status_code=400, detail="boom"), ValueError("boom"), None])
-def test_param_is_json_null_when_the_exception_names_no_field(exc):
+def test_param_is_json_null_when_the_exception_names_no_field(exc: Exception | None):
     assert openai_error_param(exc) is None
 
 
@@ -94,12 +94,12 @@ def test_a_carried_status_code_wins_over_the_default():
 
 
 @pytest.mark.parametrize("default", [400, 500])
-def test_the_default_status_stands_when_the_exception_carries_none(default):
+def test_the_default_status_stands_when_the_exception_carries_none(default: int):
     assert error_status_code(ValueError("boom"), default) == default
 
 
 @pytest.mark.parametrize("carried_status", [True, False, "429", None, 429.0])
-def test_a_non_int_carried_status_falls_back_to_the_default(carried_status):
+def test_a_non_int_carried_status_falls_back_to_the_default(carried_status: object):
     """True is an int in Python but not an HTTP status, and a stringified one would break
     every caller that compares the code numerically."""
 

From cedf35992bdec398e7623d28e45b5218e4eff9bf Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 3 Sep 2026 04:02:55 -0700
Subject: [PATCH 03/31] fix(proxy): give each spend-log queue monitor its own
 flush event

`PrismaClient.spend_log_flush_requested` was an `asyncio.Event` built at
import time, so it bound to whichever event loop first awaited it and every
later loop got `RuntimeError: ... is bound to a different event loop` out of
`_wait_for_spend_log_flush_request`. The queue monitor's blanket `except
Exception` swallowed that into its error logger, so the flush silently never
happened and the row sat in the worker's queue until the next poll.

The monitor now creates its own Event inside the loop that awaits it and
hands it to the client, and `request_spend_log_flush` signals through the
client instead of the class. A request that arrives before the monitor is
running is dropped and loses nothing, because the monitor reads the queue on
its first pass before it ever waits.

In CI this showed up as the proxy-endpoints shard flaking on
test_monitor_spend_logs_queue_flushes_as_soon_as_one_is_requested whenever
--dist=loadscope put the health-endpoint tests, which boot a proxy TestClient
and start a monitor, on the same worker ahead of the spend-log tests.
---
 litellm/proxy/db/db_spend_update_writer.py    |  2 +-
 litellm/proxy/utils.py                        | 22 ++++---
 .../proxy/db/test_db_spend_update_writer.py   |  7 +-
 .../prisma_and_spend/test_spend_functions.py  | 66 +++++++++++++++++--
 4 files changed, 79 insertions(+), 18 deletions(-)

diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index e6880d521f1..18058f31385 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -940,7 +940,7 @@ class DBSpendUpdateWriter:
 
             await enqueue_spend_logs(prisma_client, (payload,))
             if payload.get("call_type") in RESPONSES_SESSION_CALL_TYPES:
-                request_spend_log_flush()
+                request_spend_log_flush(prisma_client)
         else:
             verbose_proxy_logger.debug("prisma_client is None. Skipping writing spend logs to db.")
 
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index cab2bd6d9db..aa3076dbd19 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -3519,7 +3519,7 @@ class _StaleReadEngine:
 class PrismaClient:
     spend_log_transactions: list = []
     _spend_log_transactions_lock = asyncio.Lock()
-    spend_log_flush_requested: ClassVar[asyncio.Event] = asyncio.Event()
+    spend_log_flush_requested: "asyncio.Event | None" = None
     spend_log_queue_bytes: ClassVar[int] = 0
     spend_logs_queue_monitor_task: "asyncio.Task[None] | None" = None
     tool_usage_transactions: list["ToolUsageTransaction"] = []
@@ -6245,23 +6245,27 @@ async def enqueue_spend_logs(
         )
 
 
-def request_spend_log_flush() -> None:
-    """Wake the queue monitor now rather than leaving the rows for its next poll.
+def request_spend_log_flush(prisma_client: PrismaClient) -> None:
+    """Wake this client's queue monitor now rather than leaving the rows for its next poll.
 
     The Responses API hands the client an id it can chain from straight away, and that
     lookup reads the DB, so the row cannot sit in this worker's queue for a poll interval.
     Repeated requests coalesce into the monitor's next pass, so the batching holds.
+    A request made before the monitor is running is dropped, and loses nothing: the
+    monitor reads the queue on its first pass, before it ever waits on a request.
     """
-    PrismaClient.spend_log_flush_requested.set()
+    flush_requested: Final = prisma_client.spend_log_flush_requested
+    if flush_requested is not None:
+        flush_requested.set()
 
 
-async def _wait_for_spend_log_flush_request(interval: float) -> bool:
+async def _wait_for_spend_log_flush_request(flush_requested: asyncio.Event, interval: float) -> bool:
     """Wait out ``interval``, returning early and True when a flush was requested."""
     try:
-        await asyncio.wait_for(PrismaClient.spend_log_flush_requested.wait(), timeout=interval)
+        await asyncio.wait_for(flush_requested.wait(), timeout=interval)
     except asyncio.TimeoutError:
         return False
-    PrismaClient.spend_log_flush_requested.clear()
+    flush_requested.clear()
     return True
 
 
@@ -6681,6 +6685,8 @@ async def _monitor_spend_logs_queue(
     max_backoff: Final = 30.0  # Maximum backoff interval in seconds
     backoff_multiplier: Final = 1.5  # Exponential backoff multiplier
     current_interval = base_interval
+    flush_requested: Final = asyncio.Event()
+    prisma_client.spend_log_flush_requested = flush_requested  # rebind-ok: the client owns its monitor's flush signal
 
     verbose_proxy_logger.info(
         "Starting spend logs queue monitor (threshold: %s, poll_interval: %ss)", threshold, base_interval
@@ -6719,7 +6725,7 @@ async def _monitor_spend_logs_queue(
                 # Exponential backoff when no logs to process
                 current_interval = min(current_interval * backoff_multiplier, max_backoff)
 
-            if await _wait_for_spend_log_flush_request(current_interval):
+            if await _wait_for_spend_log_flush_request(flush_requested, current_interval):
                 current_interval = base_interval
         except Exception as e:
             spend_log_error("Error in spend logs queue monitor: %s", str(e), exc=e)
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 11ef911de3e..104dcf55e66 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
@@ -2941,11 +2941,9 @@ async def test_insert_spend_log_asks_for_an_immediate_flush_on_responses_calls(c
     A `previous_response_id` chained straight off the previous turn reads the DB, so a
     Responses row cannot sit in this worker's queue until the monitor's next poll.
     """
-    from litellm.proxy.utils import PrismaClient
-
     db_writer = DBSpendUpdateWriter()
     prisma = _tool_usage_prisma()
-    PrismaClient.spend_log_flush_requested.clear()
+    prisma.spend_log_flush_requested = asyncio.Event()
 
     await db_writer._insert_spend_log_to_db(
         payload={"request_id": "req-1", "call_type": call_type},
@@ -2953,8 +2951,7 @@ async def test_insert_spend_log_asks_for_an_immediate_flush_on_responses_calls(c
     )
 
     assert prisma.spend_log_transactions == [{"request_id": "req-1", "call_type": call_type}]
-    assert PrismaClient.spend_log_flush_requested.is_set() is expects_flush
-    PrismaClient.spend_log_flush_requested.clear()
+    assert prisma.spend_log_flush_requested.is_set() is expects_flush
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py b/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py
index a1eb88a7834..ed854d2c95c 100644
--- a/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py
+++ b/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py
@@ -538,10 +538,9 @@ async def test_monitor_spend_logs_queue_flushes_as_soon_as_one_is_requested(
     """
     import litellm.constants as constants_mod
     import litellm.proxy.utils as utils_mod
-    from litellm.proxy.utils import PrismaClient, request_spend_log_flush
+    from litellm.proxy.utils import request_spend_log_flush
 
     monkeypatch.setattr(constants_mod, "SPEND_LOG_QUEUE_POLL_INTERVAL", 30.0, raising=False)
-    PrismaClient.spend_log_flush_requested.clear()
     mock_prisma_client.spend_log_transactions = []
     mock_prisma_client.tool_usage_transactions = []
 
@@ -562,16 +561,75 @@ async def test_monitor_spend_logs_queue_flushes_as_soon_as_one_is_requested(
     try:
         await asyncio.sleep(0.05)
         assert not flushed.is_set()
+        assert isinstance(mock_prisma_client.spend_log_flush_requested, asyncio.Event)
 
         mock_prisma_client.spend_log_transactions.append(make_spend_log_row(request_id="r1"))
-        request_spend_log_flush()
+        request_spend_log_flush(mock_prisma_client)
 
         await asyncio.wait_for(flushed.wait(), timeout=5.0)
     finally:
         monitor.cancel()
         with suppress(asyncio.CancelledError):
             await monitor
-        PrismaClient.spend_log_flush_requested.clear()
+
+
+def test_monitor_spend_logs_queue_flush_survives_an_earlier_event_loop(
+    mock_prisma_client: Any,
+    make_spend_log_row: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A second monitor, started in a fresh event loop, is still woken by a flush request,
+    so a worker whose first loop is gone keeps flushing Responses rows instead of stalling.
+    """
+    import litellm.constants as constants_mod
+    import litellm.proxy.utils as utils_mod
+    from litellm.proxy.utils import request_spend_log_flush
+
+    monkeypatch.setattr(constants_mod, "SPEND_LOG_QUEUE_POLL_INTERVAL", 30.0, raising=False)
+    mock_prisma_client.tool_usage_transactions = []
+
+    async def _flush_once_under_a_monitor() -> None:
+        flushed: Final = asyncio.Event()
+
+        async def _fake_job(*args: Any, **kwargs: Any) -> None:
+            flushed.set()
+
+        monkeypatch.setattr(utils_mod, "update_spend_logs_job", _fake_job)
+        mock_prisma_client.spend_log_transactions = []
+
+        monitor: Final = asyncio.create_task(
+            _monitor_spend_logs_queue(
+                prisma_client=mock_prisma_client,
+                db_writer_client=None,
+                proxy_logging_obj=MagicMock(),
+            )
+        )
+        try:
+            await asyncio.sleep(0.05)
+            assert not flushed.is_set()
+
+            mock_prisma_client.spend_log_transactions.append(make_spend_log_row(request_id="r1"))
+            request_spend_log_flush(mock_prisma_client)
+
+            await asyncio.wait_for(flushed.wait(), timeout=5.0)
+        finally:
+            monitor.cancel()
+            with suppress(asyncio.CancelledError):
+                await monitor
+
+    asyncio.run(_flush_once_under_a_monitor())
+    asyncio.run(_flush_once_under_a_monitor())
+
+
+def test_request_spend_log_flush_is_a_no_op_before_the_monitor_starts(mock_prisma_client: Any) -> None:
+    """A Responses row enqueued before the monitor's first pass must not fail the request."""
+    from litellm.proxy.utils import request_spend_log_flush
+
+    mock_prisma_client.spend_log_flush_requested = None
+
+    request_spend_log_flush(mock_prisma_client)
+
+    assert mock_prisma_client.spend_log_flush_requested is None
 
 
 def test_raise_failed_update_spend_exception_emits_failure_handler() -> None:

From 29bcb0eeb9b085492764cdd970bc4b28340f554b Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Thu, 3 Sep 2026 04:55:57 -0700
Subject: [PATCH 04/31] test(proxy): pin that a flush requested before the
 monitor starts costs the row nothing

The monitor reads the queue on its first pass, before it ever waits on a
request, so dropping a request made while spend_log_flush_requested is still
None delays nothing. Reordering the loop to wait first would turn that drop
into a real delay for the Responses chaining flow, and now fails this test.
---
 .../prisma_and_spend/test_spend_functions.py  | 38 +++++++++++++++++--
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py b/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py
index ed854d2c95c..c8b87bd671e 100644
--- a/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py
+++ b/tests/test_litellm/proxy/utils/prisma_and_spend/test_spend_functions.py
@@ -621,16 +621,48 @@ def test_monitor_spend_logs_queue_flush_survives_an_earlier_event_loop(
     asyncio.run(_flush_once_under_a_monitor())
 
 
-def test_request_spend_log_flush_is_a_no_op_before_the_monitor_starts(mock_prisma_client: Any) -> None:
-    """A Responses row enqueued before the monitor's first pass must not fail the request."""
+@pytest.mark.asyncio
+async def test_flush_requested_before_the_monitor_starts_costs_the_row_nothing(
+    mock_prisma_client: Any,
+    make_spend_log_row: Any,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A Responses row enqueued before the monitor exists still reaches the DB on its first
+    pass, so dropping that early request delays nothing.
+    """
+    import litellm.constants as constants_mod
+    import litellm.proxy.utils as utils_mod
     from litellm.proxy.utils import request_spend_log_flush
 
+    monkeypatch.setattr(constants_mod, "SPEND_LOG_QUEUE_POLL_INTERVAL", 30.0, raising=False)
     mock_prisma_client.spend_log_flush_requested = None
+    mock_prisma_client.tool_usage_transactions = []
+    mock_prisma_client.spend_log_transactions = [make_spend_log_row(request_id="r1")]
+
+    flushed: Final = asyncio.Event()
+
+    async def _fake_job(*args: Any, **kwargs: Any) -> None:
+        flushed.set()
+
+    monkeypatch.setattr(utils_mod, "update_spend_logs_job", _fake_job)
 
     request_spend_log_flush(mock_prisma_client)
-
     assert mock_prisma_client.spend_log_flush_requested is None
 
+    monitor: Final = asyncio.create_task(
+        _monitor_spend_logs_queue(
+            prisma_client=mock_prisma_client,
+            db_writer_client=None,
+            proxy_logging_obj=MagicMock(),
+        )
+    )
+    try:
+        await asyncio.wait_for(flushed.wait(), timeout=5.0)
+    finally:
+        monitor.cancel()
+        with suppress(asyncio.CancelledError):
+            await monitor
+
 
 def test_raise_failed_update_spend_exception_emits_failure_handler() -> None:
     proxy_logging = MagicMock()

From 16fd14f53705dab68ee8c4b0fd2c9093c8e3cdac Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Sat, 5 Sep 2026 18:03:24 -0700
Subject: [PATCH 05/31] fix(docker): ship pymongo in the proxy images for the
 MongoDB vector store

The MongoDB Atlas vector store provider imports pymongo lazily from the
opt-in `mongodb` extra, but none of the shipped images installed that
extra. Any image-based deployment that configured a MongoDB vector store
failed at search time with "requires the 'pymongo' package", which the
user cannot fix without extending the image

Adds `--extra mongodb` to every uv sync in the root Dockerfile,
Dockerfile.database, Dockerfile.non_root, and the gateway component
image. The backend component does not serve /vector_stores so it is left
as is. The extra resolves from the existing uv.lock to pymongo 4.17.0
plus dnspython 2.8.0, no lock change needed
---
 Dockerfile                 | 2 ++
 docker/Dockerfile.database | 2 ++
 docker/Dockerfile.non_root | 3 +++
 gateway/Dockerfile         | 2 ++
 4 files changed, 9 insertions(+)

diff --git a/Dockerfile b/Dockerfile
index 0a92aa9a68c..1648ec69d13 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -67,6 +67,7 @@ RUN uv sync --frozen --no-install-project --no-install-workspace --no-default-gr
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
+    --extra mongodb \
     --python python3.13
 
 # Copy full source tree
@@ -89,6 +90,7 @@ RUN uv sync --frozen --no-default-groups --no-editable \
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
+    --extra mongodb \
     --python python3.13
 
 RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/opt/prisma/binaries \
diff --git a/docker/Dockerfile.database b/docker/Dockerfile.database
index e9ad2849bb2..cc81ad6b3d3 100644
--- a/docker/Dockerfile.database
+++ b/docker/Dockerfile.database
@@ -65,6 +65,7 @@ RUN uv sync --frozen --no-install-project --no-install-workspace --no-default-gr
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
+    --extra mongodb \
     --python python3.13
 
 # Copy full source tree
@@ -87,6 +88,7 @@ RUN uv sync --frozen --no-default-groups --no-editable \
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
+    --extra mongodb \
     --python python3.13
 
 RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/opt/prisma/binaries \
diff --git a/docker/Dockerfile.non_root b/docker/Dockerfile.non_root
index edf20e8bbff..358425af901 100644
--- a/docker/Dockerfile.non_root
+++ b/docker/Dockerfile.non_root
@@ -71,6 +71,7 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
+    --extra mongodb \
     --python python3.13
 
 # Copy full source tree
@@ -99,6 +100,7 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
         --extra semantic-router \
         --extra saml \
         --extra bedrock-realtime \
+        --extra mongodb \
         --python python3.13 \
         --no-sources-package litellm-proxy-extras; \
     else \
@@ -109,6 +111,7 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
         --extra semantic-router \
         --extra saml \
         --extra bedrock-realtime \
+        --extra mongodb \
         --python python3.13; \
     fi
 
diff --git a/gateway/Dockerfile b/gateway/Dockerfile
index 308d70a6b26..e42e488d57f 100644
--- a/gateway/Dockerfile
+++ b/gateway/Dockerfile
@@ -47,6 +47,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
         --extra extra_proxy \
         --extra semantic-router \
         --extra bedrock-realtime \
+        --extra mongodb \
         --python python3.13
 
 # Stage 2 — copy source and install the project + workspace members.
@@ -59,6 +60,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
         --extra extra_proxy \
         --extra semantic-router \
         --extra bedrock-realtime \
+        --extra mongodb \
         --python python3.13
 
 RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/opt/prisma/binaries \

From dc09d9e7cfbd62f590f73fdb1844bc2aac5578bf Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 7 Sep 2026 17:24:17 -0700
Subject: [PATCH 06/31] feat(bedrock): add TwelveLabs Marengo Embed 3.0
 embeddings

---
 litellm/constants.py                          |   1 +
 litellm/llms/bedrock/embed/embedding.py       |   2 +-
 .../twelvelabs_marengo_3_transformation.py    | 204 +++++++++++++
 .../twelvelabs_marengo_transformation.py      |  51 +++-
 ...odel_prices_and_context_window_backup.json |  39 +++
 litellm/types/llms/bedrock.py                 | 113 +++++++-
 litellm/utils.py                              |   2 +-
 model_prices_and_context_window.json          |  39 +++
 .../test_bedrock_async_invoke_embedding.py    |  38 +++
 .../bedrock/embed/test_bedrock_embedding.py   | 129 +++++++++
 ...est_twelvelabs_marengo_3_transformation.py | 268 ++++++++++++++++++
 ..._bedrock_marengo_embed_3_model_metadata.py |  88 ++++++
 12 files changed, 961 insertions(+), 13 deletions(-)
 create mode 100644 litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
 create mode 100644 tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
 create mode 100644 tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py

diff --git a/litellm/constants.py b/litellm/constants.py
index d53686e5e5b..78cca3c6212 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -1370,6 +1370,7 @@ bedrock_embedding_models: Final[set] = set(
         "cohere.embed-multilingual-v3",
         "cohere.embed-v4:0",
         "twelvelabs.marengo-embed-2-7-v1:0",
+        "twelvelabs.marengo-embed-3-0-v1:0",
     ]
 )
 
diff --git a/litellm/llms/bedrock/embed/embedding.py b/litellm/llms/bedrock/embed/embedding.py
index 5fb86d476f4..ab27afcf817 100644
--- a/litellm/llms/bedrock/embed/embedding.py
+++ b/litellm/llms/bedrock/embed/embedding.py
@@ -474,7 +474,7 @@ class BedrockEmbedding(BaseAWSLLM):
         elif provider == "twelvelabs":
             batch_data = []
             for i in input:
-                twelvelabs_request = TwelveLabsMarengoEmbeddingConfig()._transform_request(
+                twelvelabs_request = TwelveLabsMarengoEmbeddingConfig(model=model)._transform_request(
                     input=i,
                     inference_params=inference_params,
                     async_invoke_route=has_async_invoke,
diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
new file mode 100644
index 00000000000..2ea99db47f0
--- /dev/null
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
@@ -0,0 +1,204 @@
+"""
+Request builder for Bedrock TwelveLabs Marengo Embed 3.0, whose payload nests the input under a key named after
+``inputType`` instead of the flat 2.7 layout.
+
+Docs - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-marengo-3.html
+"""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Final, assert_never
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
+
+from litellm.llms.bedrock.common_utils import BedrockError
+from litellm.types.llms.bedrock import (
+    TWELVELABS_MARENGO_3_EMBEDDING_OPTIONS,
+    TWELVELABS_MARENGO_3_EMBEDDING_SCOPES,
+    TWELVELABS_MARENGO_3_EMBEDDING_TYPES,
+    TWELVELABS_MARENGO_3_INPUT_TYPES,
+    TwelveLabsMarengo3AudioRequest,
+    TwelveLabsMarengo3EmbeddingRequest,
+    TwelveLabsMarengo3ImageRequest,
+    TwelveLabsMarengo3MultiInputRequest,
+    TwelveLabsMarengo3NamedMediaSource,
+    TwelveLabsMarengo3RequestBase,
+    TwelveLabsMarengo3Segmentation,
+    TwelveLabsMarengo3TextImageRequest,
+    TwelveLabsMarengo3TextRequest,
+    TwelveLabsMarengo3TimedMediaInput,
+    TwelveLabsMarengo3TimedMediaOptions,
+    TwelveLabsMarengo3VideoRequest,
+    TwelveLabsMediaSource,
+    TwelveLabsS3Location,
+)
+from litellm.utils import get_base64_str
+
+MARENGO_3_MODEL_MARKER: Final = "marengo-embed-3"
+S3_URI_PREFIX: Final = "s3://"
+TIMED_MEDIA_OPTION_FIELDS: Final = MappingProxyType(
+    {
+        "startSec": True,
+        "endSec": True,
+        "segmentation": True,
+        "embeddingOption": True,
+        "embeddingType": True,
+        "embeddingScope": True,
+    }
+)
+TIMED_MEDIA_OPTIONS: Final = TypeAdapter(TwelveLabsMarengo3TimedMediaOptions)
+
+
+def is_marengo_3_model(model: str | None) -> bool:
+    return MARENGO_3_MODEL_MARKER in (model or "")
+
+
+class Marengo3Params(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    inputType: TWELVELABS_MARENGO_3_INPUT_TYPES | None = None
+    input_type: TWELVELABS_MARENGO_3_INPUT_TYPES | None = None
+    media_source: str | None = None
+    media_sources: Mapping[str, str] | None = None
+    bucketOwner: str | None = None
+    startSec: float | None = None
+    endSec: float | None = None
+    segmentation: TwelveLabsMarengo3Segmentation | None = None
+    embeddingOption: tuple[TWELVELABS_MARENGO_3_EMBEDDING_OPTIONS, ...] | None = None
+    embeddingType: tuple[TWELVELABS_MARENGO_3_EMBEDDING_TYPES, ...] | None = None
+    embeddingScope: tuple[TWELVELABS_MARENGO_3_EMBEDDING_SCOPES, ...] | None = None
+    inferenceId: str | None = None
+
+    @property
+    def resolved_input_type(self) -> TWELVELABS_MARENGO_3_INPUT_TYPES:
+        return self.inputType or self.input_type or "text"
+
+    def timed_media_options(self) -> TwelveLabsMarengo3TimedMediaOptions:
+        return TIMED_MEDIA_OPTIONS.validate_python(
+            self.model_dump(include=TIMED_MEDIA_OPTION_FIELDS, exclude_none=True)
+        )
+
+
+def _s3_location(uri: str, bucket_owner: str | None) -> TwelveLabsS3Location:
+    if bucket_owner is None:
+        unowned: Final[TwelveLabsS3Location] = {"uri": uri}
+        return unowned
+    owned: Final[TwelveLabsS3Location] = {"uri": uri, "bucketOwner": bucket_owner}
+    return owned
+
+
+def _media_source(media: str, bucket_owner: str | None) -> TwelveLabsMediaSource:
+    if not media.startswith(S3_URI_PREFIX):
+        inline: Final[TwelveLabsMediaSource] = {"base64String": get_base64_str(media)}
+        return inline
+    remote: Final[TwelveLabsMediaSource] = {"s3Location": _s3_location(media, bucket_owner)}
+    return remote
+
+
+def _named_media_source(name: str, media: str, bucket_owner: str | None) -> TwelveLabsMarengo3NamedMediaSource:
+    named: Final[TwelveLabsMarengo3NamedMediaSource] = {
+        "name": name,
+        "mediaType": "image",
+        **_media_source(media, bucket_owner),
+    }
+    return named
+
+
+def _timed_media_input(media: str, params: Marengo3Params) -> TwelveLabsMarengo3TimedMediaInput:
+    timed: Final[TwelveLabsMarengo3TimedMediaInput] = {
+        "mediaSource": _media_source(media, params.bucketOwner),
+        **params.timed_media_options(),
+    }
+    return timed
+
+
+def _validated_params(inference_params: Mapping[str, object]) -> Marengo3Params:
+    try:
+        return Marengo3Params.model_validate(inference_params)
+    except ValidationError as error:
+        raise BedrockError(status_code=400, message=f"Invalid Marengo 3.0 parameters: {error}") from error
+
+
+def _require(value: str | None, input_type: str, param_name: str) -> str:
+    if value is None:
+        raise BedrockError(status_code=400, message=f"Input type '{input_type}' requires the '{param_name}' parameter")
+    return value
+
+
+def _require_media_sources(value: Mapping[str, str] | None) -> Mapping[str, str]:
+    if not value:
+        raise BedrockError(
+            status_code=400,
+            message="Input type 'multi_input' requires a non-empty 'media_sources' mapping of name to media",
+        )
+    return value
+
+
+def _request_base(inference_id: str | None) -> TwelveLabsMarengo3RequestBase:
+    if inference_id is None:
+        anonymous: Final[TwelveLabsMarengo3RequestBase] = {}
+        return anonymous
+    identified: Final[TwelveLabsMarengo3RequestBase] = {"inferenceId": inference_id}
+    return identified
+
+
+def build_marengo_3_request(input: str, inference_params: Mapping[str, object]) -> TwelveLabsMarengo3EmbeddingRequest:
+    params: Final = _validated_params(inference_params)
+    base: Final = _request_base(params.inferenceId)
+    input_type: Final = params.resolved_input_type
+    match input_type:
+        case "text":
+            text_request: Final[TwelveLabsMarengo3TextRequest] = {
+                **base,
+                "inputType": "text",
+                "text": {"inputText": input},
+            }
+            return text_request
+        case "image":
+            image_request: Final[TwelveLabsMarengo3ImageRequest] = {
+                **base,
+                "inputType": "image",
+                "image": {"mediaSource": _media_source(input, params.bucketOwner)},
+            }
+            return image_request
+        case "video":
+            video_request: Final[TwelveLabsMarengo3VideoRequest] = {
+                **base,
+                "inputType": "video",
+                "video": _timed_media_input(input, params),
+            }
+            return video_request
+        case "audio":
+            audio_request: Final[TwelveLabsMarengo3AudioRequest] = {
+                **base,
+                "inputType": "audio",
+                "audio": _timed_media_input(input, params),
+            }
+            return audio_request
+        case "text_image":
+            text_image_request: Final[TwelveLabsMarengo3TextImageRequest] = {
+                **base,
+                "inputType": "text_image",
+                "text_image": {
+                    "inputText": input,
+                    "mediaSource": _media_source(
+                        _require(params.media_source, input_type, "media_source"), params.bucketOwner
+                    ),
+                },
+            }
+            return text_image_request
+        case "multi_input":
+            media_sources: Final = tuple(
+                _named_media_source(name, media, params.bucketOwner)
+                for name, media in _require_media_sources(params.media_sources).items()
+            )
+            multi_input_request: Final[TwelveLabsMarengo3MultiInputRequest] = {
+                **base,
+                "inputType": "multi_input",
+                "multi_input": {"inputText": input, "mediaSources": media_sources}
+                if input
+                else {"mediaSources": media_sources},
+            }
+            return multi_input_request
+        case _:
+            assert_never(input_type)
diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
index a39c59b0efd..79b5825d2eb 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
@@ -4,13 +4,19 @@ Transformation logic from OpenAI /v1/embeddings format to Bedrock TwelveLabs Mar
 Why separate file? Make it easy to see how transformation works
 
 Docs - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-marengo.html
+Marengo 3.0 docs - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-marengo-3.html
 """
 
 from typing import Final, cast
 
+from litellm.llms.bedrock.embed.twelvelabs_marengo_3_transformation import (
+    build_marengo_3_request,
+    is_marengo_3_model,
+)
 from litellm.types.llms.bedrock import (
     TWELVELABS_EMBEDDING_INPUT_TYPES,
     TwelveLabsAsyncInvokeRequest,
+    TwelveLabsMarengo3EmbeddingRequest,
     TwelveLabsMarengoEmbeddingRequest,
     TwelveLabsOutputDataConfig,
     TwelveLabsS3Location,
@@ -26,10 +32,13 @@ class TwelveLabsMarengoEmbeddingConfig:
     Supports text, image, video, and audio inputs.
     - InvokeModel: text and image inputs
     - StartAsyncInvoke: video, audio, image, and text inputs
+
+    Marengo 3.0 (model ids containing "marengo-embed-3") nests the input under a key named after inputType and
+    adds the text_image and multi_input input types; that payload is built by build_marengo_3_request.
     """
 
-    def __init__(self) -> None:
-        pass
+    def __init__(self, model: str | None = None) -> None:
+        self.is_marengo_3: Final = is_marengo_3_model(model)
 
     def get_supported_openai_params(self) -> list[str]:
         return [
@@ -41,13 +50,20 @@ class TwelveLabsMarengoEmbeddingConfig:
             "useFixedLengthSec",
             "minClipSec",
             "input_type",
+            "endSec",
+            "segmentation",
+            "embeddingType",
+            "embeddingScope",
+            "inferenceId",
+            "media_source",
+            "media_sources",
         ]
 
     def map_openai_params(self, non_default_params: dict, optional_params: dict) -> dict:
         for k, v in non_default_params.items():
             if k == "encoding_format":
                 # TwelveLabs doesn't have encoding_format, but we can map it to embeddingOption
-                if v == "float":
+                if v == "float" and not self.is_marengo_3:
                     optional_params["embeddingOption"] = ["visual-text", "visual-image"]
             elif k == "textTruncate":
                 optional_params["textTruncate"] = v
@@ -56,7 +72,19 @@ class TwelveLabsMarengoEmbeddingConfig:
             elif k == "input_type":
                 # Map input_type to inputType for Bedrock
                 optional_params["inputType"] = v
-            elif k in ["startSec", "lengthSec", "useFixedLengthSec", "minClipSec"]:
+            elif k in (
+                "startSec",
+                "lengthSec",
+                "useFixedLengthSec",
+                "minClipSec",
+                "endSec",
+                "segmentation",
+                "embeddingType",
+                "embeddingScope",
+                "inferenceId",
+                "media_source",
+                "media_sources",
+            ):
                 optional_params[k] = v
         return optional_params
 
@@ -77,7 +105,7 @@ class TwelveLabsMarengoEmbeddingConfig:
         async_invoke_route: bool = False,
         model_id: str | None = None,
         output_s3_uri: str | None = None,
-    ) -> TwelveLabsMarengoEmbeddingRequest | TwelveLabsAsyncInvokeRequest:
+    ) -> TwelveLabsMarengoEmbeddingRequest | TwelveLabsMarengo3EmbeddingRequest | TwelveLabsAsyncInvokeRequest:
         """
         Transform OpenAI-style input to TwelveLabs Marengo format/async-invoke format.
 
@@ -87,20 +115,27 @@ class TwelveLabsMarengoEmbeddingConfig:
         - Video inputs (async-invoke only)
         - Audio inputs (async-invoke only)
         - S3 URLs for all media types (async-invoke only)
+        - Marengo 3.0 only: text_image and multi_input inputs (nested payload)
         """
-        # Get input_type or default to "text"
         input_type: Final = cast(
             TWELVELABS_EMBEDDING_INPUT_TYPES,
             inference_params.get("inputType") or inference_params.get("input_type") or "text",
         )
 
-        # Validate that async-invoke is used for video/audio
         if input_type in ["video", "audio"] and not async_invoke_route:
             raise ValueError(
                 f"Input type '{input_type}' requires async_invoke route. "
                 f"Use model format: 'bedrock/async_invoke/model_id'"
             )
 
+        if self.is_marengo_3:
+            marengo_3_request: Final = build_marengo_3_request(input=input, inference_params=inference_params)
+            if async_invoke_route and model_id:
+                return self._wrap_async_invoke_request(
+                    model_input=marengo_3_request, model_id=model_id, output_s3_uri=output_s3_uri
+                )
+            return marengo_3_request
+
         transformed_request: Final[TwelveLabsMarengoEmbeddingRequest] = {"inputType": input_type}
 
         if input_type == "text":
@@ -154,7 +189,7 @@ class TwelveLabsMarengoEmbeddingConfig:
 
     def _wrap_async_invoke_request(
         self,
-        model_input: TwelveLabsMarengoEmbeddingRequest,
+        model_input: TwelveLabsMarengoEmbeddingRequest | TwelveLabsMarengo3EmbeddingRequest,
         model_id: str,
         output_s3_uri: str | None = None,
     ) -> TwelveLabsAsyncInvokeRequest:
diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index b1ffc1583e4..cc75354a495 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -690,6 +690,45 @@
         "supports_embedding_image_input": true,
         "supports_image_input": true
     },
+    "twelvelabs.marengo-embed-3-0-v1:0": {
+        "input_cost_per_token": 7e-05,
+        "litellm_provider": "bedrock",
+        "max_input_tokens": 500,
+        "max_tokens": 500,
+        "mode": "embedding",
+        "output_cost_per_token": 0.0,
+        "output_vector_size": 512,
+        "supports_embedding_image_input": true,
+        "supports_image_input": true
+    },
+    "us.twelvelabs.marengo-embed-3-0-v1:0": {
+        "input_cost_per_token": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
+        "litellm_provider": "bedrock",
+        "max_input_tokens": 500,
+        "max_tokens": 500,
+        "mode": "embedding",
+        "output_cost_per_token": 0.0,
+        "output_vector_size": 512,
+        "supports_embedding_image_input": true,
+        "supports_image_input": true
+    },
+    "eu.twelvelabs.marengo-embed-3-0-v1:0": {
+        "input_cost_per_token": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
+        "litellm_provider": "bedrock",
+        "max_input_tokens": 500,
+        "max_tokens": 500,
+        "mode": "embedding",
+        "output_cost_per_token": 0.0,
+        "output_vector_size": 512,
+        "supports_embedding_image_input": true,
+        "supports_image_input": true
+    },
     "twelvelabs.pegasus-1-2-v1:0": {
         "input_cost_per_video_per_second": 0.00049,
         "output_cost_per_token": 7.5e-06,
diff --git a/litellm/types/llms/bedrock.py b/litellm/types/llms/bedrock.py
index bed0ba3dc08..9f93886a9c6 100644
--- a/litellm/types/llms/bedrock.py
+++ b/litellm/types/llms/bedrock.py
@@ -1,7 +1,7 @@
 import json
 from collections.abc import Sequence
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Final, Literal
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeAlias
 
 from typing_extensions import ReadOnly, Required, TypedDict, override
 
@@ -557,7 +557,7 @@ class AmazonTitanMultimodalEmbeddingResponse(TypedDict):
     message: str  # Specifies any errors that occur during generation.
 
 
-# TwelveLabs Marengo Embed 2.7 types
+# TwelveLabs Marengo Embed types
 TWELVELABS_EMBEDDING_INPUT_TYPES = Literal["text", "image", "video", "audio"]
 TWELVELABS_EMBEDDING_OPTIONS = Literal["visual-text", "visual-image", "audio"]
 
@@ -591,6 +591,113 @@ class TwelveLabsMarengoEmbeddingResponse(TypedDict):
     endSec: float
 
 
+TWELVELABS_MARENGO_3_INPUT_TYPES: TypeAlias = Literal["text", "image", "video", "audio", "text_image", "multi_input"]
+TWELVELABS_MARENGO_3_EMBEDDING_OPTIONS: TypeAlias = Literal["visual", "audio", "transcription"]
+TWELVELABS_MARENGO_3_EMBEDDING_TYPES: TypeAlias = Literal["separate_embedding", "fused_embedding"]
+TWELVELABS_MARENGO_3_EMBEDDING_SCOPES: TypeAlias = Literal["clip", "asset"]
+
+
+class TwelveLabsMarengo3FixedSegmentationConfig(TypedDict):
+    durationSec: ReadOnly[int]
+
+
+class TwelveLabsMarengo3FixedSegmentation(TypedDict):
+    method: ReadOnly[Literal["fixed"]]
+    fixed: ReadOnly[TwelveLabsMarengo3FixedSegmentationConfig]
+
+
+class TwelveLabsMarengo3DynamicSegmentationConfig(TypedDict):
+    minDurationSec: ReadOnly[int]
+
+
+class TwelveLabsMarengo3DynamicSegmentation(TypedDict):
+    method: ReadOnly[Literal["dynamic"]]
+    dynamic: ReadOnly[TwelveLabsMarengo3DynamicSegmentationConfig]
+
+
+TwelveLabsMarengo3Segmentation: TypeAlias = TwelveLabsMarengo3FixedSegmentation | TwelveLabsMarengo3DynamicSegmentation
+
+
+class TwelveLabsMarengo3TextInput(TypedDict):
+    inputText: ReadOnly[str]
+
+
+class TwelveLabsMarengo3ImageInput(TypedDict):
+    mediaSource: ReadOnly[TwelveLabsMediaSource]
+
+
+class TwelveLabsMarengo3TimedMediaOptions(TypedDict, total=False):
+    startSec: ReadOnly[float]
+    endSec: ReadOnly[float]
+    segmentation: ReadOnly[TwelveLabsMarengo3Segmentation]
+    embeddingOption: ReadOnly[Sequence[TWELVELABS_MARENGO_3_EMBEDDING_OPTIONS]]
+    embeddingType: ReadOnly[Sequence[TWELVELABS_MARENGO_3_EMBEDDING_TYPES]]
+    embeddingScope: ReadOnly[Sequence[TWELVELABS_MARENGO_3_EMBEDDING_SCOPES]]
+
+
+class TwelveLabsMarengo3TimedMediaInput(TwelveLabsMarengo3TimedMediaOptions):
+    mediaSource: Required[ReadOnly[TwelveLabsMediaSource]]
+
+
+class TwelveLabsMarengo3TextImageInput(TypedDict):
+    inputText: ReadOnly[str]
+    mediaSource: ReadOnly[TwelveLabsMediaSource]
+
+
+class TwelveLabsMarengo3NamedMediaSource(TwelveLabsMediaSource):
+    name: Required[ReadOnly[str]]
+    mediaType: Required[ReadOnly[Literal["image"]]]
+
+
+class TwelveLabsMarengo3MultiInput(TypedDict, total=False):
+    inputText: ReadOnly[str]
+    mediaSources: Required[ReadOnly[Sequence[TwelveLabsMarengo3NamedMediaSource]]]
+
+
+class TwelveLabsMarengo3RequestBase(TypedDict, total=False):
+    inferenceId: ReadOnly[str]
+
+
+class TwelveLabsMarengo3TextRequest(TwelveLabsMarengo3RequestBase):
+    inputType: ReadOnly[Literal["text"]]
+    text: ReadOnly[TwelveLabsMarengo3TextInput]
+
+
+class TwelveLabsMarengo3ImageRequest(TwelveLabsMarengo3RequestBase):
+    inputType: ReadOnly[Literal["image"]]
+    image: ReadOnly[TwelveLabsMarengo3ImageInput]
+
+
+class TwelveLabsMarengo3VideoRequest(TwelveLabsMarengo3RequestBase):
+    inputType: ReadOnly[Literal["video"]]
+    video: ReadOnly[TwelveLabsMarengo3TimedMediaInput]
+
+
+class TwelveLabsMarengo3AudioRequest(TwelveLabsMarengo3RequestBase):
+    inputType: ReadOnly[Literal["audio"]]
+    audio: ReadOnly[TwelveLabsMarengo3TimedMediaInput]
+
+
+class TwelveLabsMarengo3TextImageRequest(TwelveLabsMarengo3RequestBase):
+    inputType: ReadOnly[Literal["text_image"]]
+    text_image: ReadOnly[TwelveLabsMarengo3TextImageInput]
+
+
+class TwelveLabsMarengo3MultiInputRequest(TwelveLabsMarengo3RequestBase):
+    inputType: ReadOnly[Literal["multi_input"]]
+    multi_input: ReadOnly[TwelveLabsMarengo3MultiInput]
+
+
+TwelveLabsMarengo3EmbeddingRequest: TypeAlias = (
+    TwelveLabsMarengo3TextRequest
+    | TwelveLabsMarengo3ImageRequest
+    | TwelveLabsMarengo3VideoRequest
+    | TwelveLabsMarengo3AudioRequest
+    | TwelveLabsMarengo3TextImageRequest
+    | TwelveLabsMarengo3MultiInputRequest
+)
+
+
 class TwelveLabsS3OutputDataConfig(TypedDict):
     s3Uri: str
 
@@ -601,7 +708,7 @@ class TwelveLabsOutputDataConfig(TypedDict):
 
 class TwelveLabsAsyncInvokeRequest(TypedDict):
     modelId: str
-    modelInput: TwelveLabsMarengoEmbeddingRequest
+    modelInput: ReadOnly[TwelveLabsMarengoEmbeddingRequest | TwelveLabsMarengo3EmbeddingRequest]
     outputDataConfig: TwelveLabsOutputDataConfig
 
 
diff --git a/litellm/utils.py b/litellm/utils.py
index d0e11bc9551..b98aa821ff3 100644
--- a/litellm/utils.py
+++ b/litellm/utils.py
@@ -3623,7 +3623,7 @@ def get_optional_params_embeddings(
         elif "cohere.embed" in model:
             object = litellm.BedrockCohereEmbeddingConfig()
         elif "twelvelabs" in model or "marengo" in model:
-            object = litellm.TwelveLabsMarengoEmbeddingConfig()
+            object = litellm.TwelveLabsMarengoEmbeddingConfig(model=model)
         elif "nova" in model.lower():
             object = litellm.AmazonNovaEmbeddingConfig()
         else:  # unmapped model
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index b1ffc1583e4..cc75354a495 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -690,6 +690,45 @@
         "supports_embedding_image_input": true,
         "supports_image_input": true
     },
+    "twelvelabs.marengo-embed-3-0-v1:0": {
+        "input_cost_per_token": 7e-05,
+        "litellm_provider": "bedrock",
+        "max_input_tokens": 500,
+        "max_tokens": 500,
+        "mode": "embedding",
+        "output_cost_per_token": 0.0,
+        "output_vector_size": 512,
+        "supports_embedding_image_input": true,
+        "supports_image_input": true
+    },
+    "us.twelvelabs.marengo-embed-3-0-v1:0": {
+        "input_cost_per_token": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
+        "litellm_provider": "bedrock",
+        "max_input_tokens": 500,
+        "max_tokens": 500,
+        "mode": "embedding",
+        "output_cost_per_token": 0.0,
+        "output_vector_size": 512,
+        "supports_embedding_image_input": true,
+        "supports_image_input": true
+    },
+    "eu.twelvelabs.marengo-embed-3-0-v1:0": {
+        "input_cost_per_token": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
+        "litellm_provider": "bedrock",
+        "max_input_tokens": 500,
+        "max_tokens": 500,
+        "mode": "embedding",
+        "output_cost_per_token": 0.0,
+        "output_vector_size": 512,
+        "supports_embedding_image_input": true,
+        "supports_image_input": true
+    },
     "twelvelabs.pegasus-1-2-v1:0": {
         "input_cost_per_video_per_second": 0.00049,
         "output_cost_per_token": 7.5e-06,
diff --git a/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py b/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py
index 74a55cc1ef2..00f5145269a 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py
@@ -184,6 +184,44 @@ class TestBedrockAsyncInvokeEmbedding:
             request_url = mock_post.call_args.kwargs.get("url", "")
             assert "/async-invoke" in request_url
 
+    def test_async_invoke_marengo_3_wraps_the_nested_payload_with_the_base_model_id(self):
+        client = HTTPHandler()
+
+        with patch.object(client, "post") as mock_post:
+            mock_response = Mock()
+            mock_response.status_code = 200
+            mock_response.text = json.dumps(async_invoke_response)
+            mock_response.json = lambda: json.loads(mock_response.text)
+            mock_post.return_value = mock_response
+
+            response = litellm.embedding(
+                model="bedrock/async_invoke/twelvelabs.marengo-embed-3-0-v1:0",
+                input="s3://test-bucket/clip.mp4",
+                client=client,
+                aws_region_name="us-east-1",
+                aws_bedrock_runtime_endpoint="https://bedrock-runtime.us-east-1.amazonaws.com",
+                api_key="test-bearer-token-12345",
+                input_type="video",
+                embeddingOption=["visual", "audio"],
+                segmentation={"method": "fixed", "fixed": {"durationSec": 6}},
+                output_s3_uri="s3://test-bucket/async-invoke-output/",
+            )
+
+        assert response._hidden_params._invocation_arn == async_invoke_response["invocationArn"]
+        assert mock_post.call_args.kwargs["url"].endswith("/async-invoke")
+        assert json.loads(mock_post.call_args.kwargs["data"]) == {
+            "modelId": "twelvelabs.marengo-embed-3-0-v1:0",
+            "modelInput": {
+                "inputType": "video",
+                "video": {
+                    "mediaSource": {"s3Location": {"uri": "s3://test-bucket/clip.mp4"}},
+                    "segmentation": {"method": "fixed", "fixed": {"durationSec": 6}},
+                    "embeddingOption": ["visual", "audio"],
+                },
+            },
+            "outputDataConfig": {"s3OutputDataConfig": {"s3Uri": "s3://test-bucket/async-invoke-output/"}},
+        }
+
     @pytest.mark.asyncio
     async def test_async_invoke_twelvelabs_embedding_async_with_mock(self):
         """Test async invoke embedding with async calls."""
diff --git a/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py b/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
index 50f8bbcf584..b37e991b0b2 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
@@ -1059,3 +1059,132 @@ def test_bedrock_embedding_bearer_token_never_runs_the_sigv4_credential_chain(mo
 
     assert response.data[0]["embedding"] == titan_embedding_response["embedding"]
     assert mock_post.call_args.kwargs["headers"]["Authorization"] == "Bearer env-bearer-token-12345"
+
+
+marengo_3_embedding_response = {"data": [{"embedding": [0.01 * i for i in range(512)]}]}
+MARENGO_3_DUCK = "data:image/png;base64,ZHVjaw=="
+
+
+@pytest.mark.parametrize(
+    "model,kwargs,expected_body",
+    [
+        (
+            "bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
+            {"input_type": "text"},
+            {"inputType": "text", "text": {"inputText": "a duck on water"}},
+        ),
+        (
+            "bedrock/twelvelabs.marengo-embed-3-0-v1:0",
+            {"input_type": "text"},
+            {"inputType": "text", "text": {"inputText": "a duck on water"}},
+        ),
+        (
+            "bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
+            {"input_type": "text_image", "media_source": MARENGO_3_DUCK},
+            {
+                "inputType": "text_image",
+                "text_image": {"inputText": "a duck on water", "mediaSource": {"base64String": "ZHVjaw=="}},
+            },
+        ),
+        (
+            "bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
+            {"input_type": "multi_input", "media_sources": {"bird": MARENGO_3_DUCK}},
+            {
+                "inputType": "multi_input",
+                "multi_input": {
+                    "inputText": "a duck on water",
+                    "mediaSources": [{"name": "bird", "mediaType": "image", "base64String": "ZHVjaw=="}],
+                },
+            },
+        ),
+    ],
+)
+def test_marengo_3_embedding_sends_the_nested_payload_and_parses_512_dims(model, kwargs, expected_body):
+    client = HTTPHandler()
+
+    with patch.object(client, "post") as mock_post:
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.text = json.dumps(marengo_3_embedding_response)
+        mock_response.json = lambda: json.loads(mock_response.text)
+        mock_post.return_value = mock_response
+
+        response = litellm.embedding(
+            model=model,
+            input="a duck on water",
+            client=client,
+            aws_region_name="us-east-1",
+            api_key="test-bearer-token-12345",
+            **kwargs,
+        )
+
+    assert json.loads(mock_post.call_args.kwargs["data"]) == expected_body
+    assert mock_post.call_args.kwargs["url"].endswith(f"/model/{model.removeprefix('bedrock/').replace(':', '%3A')}/invoke")
+    assert len(response.data[0]["embedding"]) == 512
+    assert response.data[0]["embedding"][:2] == [0.0, 0.01]
+    assert response.usage.prompt_tokens == 128
+
+
+def test_marengo_3_image_embedding_sends_the_media_under_the_image_key():
+    client = HTTPHandler()
+
+    with patch.object(client, "post") as mock_post:
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.text = json.dumps(marengo_3_embedding_response)
+        mock_response.json = lambda: json.loads(mock_response.text)
+        mock_post.return_value = mock_response
+
+        response = litellm.embedding(
+            model="bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
+            input=MARENGO_3_DUCK,
+            client=client,
+            aws_region_name="us-east-1",
+            api_key="test-bearer-token-12345",
+            input_type="image",
+        )
+
+    assert json.loads(mock_post.call_args.kwargs["data"]) == {
+        "inputType": "image",
+        "image": {"mediaSource": {"base64String": "ZHVjaw=="}},
+    }
+    assert len(response.data[0]["embedding"]) == 512
+    assert response.data[0]["embedding"][:2] == [0.0, 0.01]
+
+
+def test_marengo_2_7_embedding_keeps_the_flat_payload():
+    client = HTTPHandler()
+
+    with patch.object(client, "post") as mock_post:
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.text = json.dumps(twelvelabs_embedding_response)
+        mock_response.json = lambda: json.loads(mock_response.text)
+        mock_post.return_value = mock_response
+
+        response = litellm.embedding(
+            model="bedrock/us.twelvelabs.marengo-embed-2-7-v1:0",
+            input="a duck on water",
+            client=client,
+            aws_region_name="us-east-1",
+            api_key="test-bearer-token-12345",
+            input_type="text",
+        )
+
+    assert json.loads(mock_post.call_args.kwargs["data"]) == {
+        "inputType": "text",
+        "inputText": "a duck on water",
+        "textTruncate": "end",
+    }
+    assert response.data[0]["embedding"] == [0.1, 0.2, 0.3]
+
+
+def test_marengo_3_text_image_without_media_source_is_a_bad_request():
+    with pytest.raises(litellm.BadRequestError, match=r"text_image.*media_source"):
+        litellm.embedding(
+            model="bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
+            input="a duck on water",
+            aws_region_name="us-east-1",
+            api_key="test-bearer-token-12345",
+            input_type="text_image",
+        )
diff --git a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
new file mode 100644
index 00000000000..0bf86352a5e
--- /dev/null
+++ b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
@@ -0,0 +1,268 @@
+import json
+
+import pytest
+
+from litellm.llms.bedrock.common_utils import BedrockError
+from litellm.llms.bedrock.embed.twelvelabs_marengo_3_transformation import (
+    build_marengo_3_request,
+    is_marengo_3_model,
+)
+from litellm.llms.bedrock.embed.twelvelabs_marengo_transformation import (
+    TwelveLabsMarengoEmbeddingConfig,
+)
+
+MARENGO_3_BASE = "twelvelabs.marengo-embed-3-0-v1:0"
+MARENGO_3_US = "us.twelvelabs.marengo-embed-3-0-v1:0"
+MARENGO_27_US = "us.twelvelabs.marengo-embed-2-7-v1:0"
+DUCK_DATA_URL = "data:image/png;base64,ZHVjaw=="
+OUTPUT_S3_URI = "s3://out-bucket/marengo/"
+
+
+@pytest.mark.parametrize(
+    "model,expected",
+    [
+        (MARENGO_3_BASE, True),
+        (MARENGO_3_US, True),
+        ("eu.twelvelabs.marengo-embed-3-0-v1:0", True),
+        ("async_invoke/twelvelabs.marengo-embed-3-0-v1:0", True),
+        (MARENGO_27_US, False),
+        ("twelvelabs.marengo-embed-2-7-v1:0", False),
+        (None, False),
+    ],
+)
+def test_is_marengo_3_model(model, expected):
+    assert is_marengo_3_model(model) is expected
+
+
+def wire(request: object) -> object:
+    return json.loads(json.dumps(request))
+
+
+def test_text_request_nests_input_text_under_text():
+    assert build_marengo_3_request("a dog on the beach", {"input_type": "text"}) == {
+        "inputType": "text",
+        "text": {"inputText": "a dog on the beach"},
+    }
+
+
+def test_missing_input_type_defaults_to_text():
+    assert build_marengo_3_request("hello", {})["inputType"] == "text"
+
+
+def test_camel_case_input_type_wins_over_snake_case():
+    request = build_marengo_3_request(DUCK_DATA_URL, {"inputType": "image", "input_type": "text"})
+    assert request["inputType"] == "image"
+
+
+def test_image_request_strips_data_url_prefix():
+    assert build_marengo_3_request(DUCK_DATA_URL, {"input_type": "image"}) == {
+        "inputType": "image",
+        "image": {"mediaSource": {"base64String": "ZHVjaw=="}},
+    }
+
+
+def test_image_request_from_s3_carries_bucket_owner():
+    request = build_marengo_3_request("s3://media/duck.png", {"input_type": "image", "bucketOwner": "123456789012"})
+    assert request == {
+        "inputType": "image",
+        "image": {"mediaSource": {"s3Location": {"uri": "s3://media/duck.png", "bucketOwner": "123456789012"}}},
+    }
+
+
+def test_s3_media_without_bucket_owner_omits_the_key():
+    request = build_marengo_3_request("s3://media/duck.png", {"input_type": "image"})
+    assert request["image"]["mediaSource"] == {"s3Location": {"uri": "s3://media/duck.png"}}
+
+
+def test_text_image_request_pairs_text_with_media_source():
+    request = build_marengo_3_request(
+        "a duck", {"input_type": "text_image", "media_source": DUCK_DATA_URL, "output_s3_uri": OUTPUT_S3_URI}
+    )
+    assert request == {
+        "inputType": "text_image",
+        "text_image": {"inputText": "a duck", "mediaSource": {"base64String": "ZHVjaw=="}},
+    }
+
+
+def test_text_image_request_requires_media_source():
+    with pytest.raises(BedrockError, match=r"text_image.*media_source") as excinfo:
+        build_marengo_3_request("a duck", {"input_type": "text_image"})
+    assert excinfo.value.status_code == 400
+
+
+def test_multi_input_request_names_each_media_source():
+    request = build_marengo_3_request(
+        "a photo of <@bird> next to <@dog>",
+        {
+            "input_type": "multi_input",
+            "media_sources": {"bird": DUCK_DATA_URL, "dog": "s3://media/dog.png"},
+            "bucketOwner": "123456789012",
+        },
+    )
+    assert wire(request) == {
+        "inputType": "multi_input",
+        "multi_input": {
+            "inputText": "a photo of <@bird> next to <@dog>",
+            "mediaSources": [
+                {"name": "bird", "mediaType": "image", "base64String": "ZHVjaw=="},
+                {
+                    "name": "dog",
+                    "mediaType": "image",
+                    "s3Location": {"uri": "s3://media/dog.png", "bucketOwner": "123456789012"},
+                },
+            ],
+        },
+    }
+
+
+def test_multi_input_without_text_omits_input_text():
+    request = build_marengo_3_request("", {"input_type": "multi_input", "media_sources": {"bird": DUCK_DATA_URL}})
+    assert "inputText" not in request["multi_input"]
+    assert request["multi_input"]["mediaSources"][0]["name"] == "bird"
+
+
+@pytest.mark.parametrize("params", [{"input_type": "multi_input"}, {"input_type": "multi_input", "media_sources": {}}])
+def test_multi_input_request_requires_media_sources(params):
+    with pytest.raises(BedrockError, match=r"multi_input.*media_sources") as excinfo:
+        build_marengo_3_request("<@bird>", params)
+    assert excinfo.value.status_code == 400
+
+
+@pytest.mark.parametrize("input_type", ["video", "audio"])
+def test_timed_media_request_nests_every_option_under_the_media_key(input_type):
+    request = build_marengo_3_request(
+        "s3://media/clip.mp4",
+        {
+            "input_type": input_type,
+            "startSec": 2,
+            "endSec": 12.5,
+            "segmentation": {"method": "dynamic", "dynamic": {"minDurationSec": 4}},
+            "embeddingOption": ["visual", "audio"],
+            "embeddingType": ["fused_embedding"],
+            "embeddingScope": ["clip", "asset"],
+            "inferenceId": "req-42",
+        },
+    )
+    assert wire(request) == {
+        "inputType": input_type,
+        input_type: {
+            "mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4"}},
+            "startSec": 2.0,
+            "endSec": 12.5,
+            "segmentation": {"method": "dynamic", "dynamic": {"minDurationSec": 4}},
+            "embeddingOption": ["visual", "audio"],
+            "embeddingType": ["fused_embedding"],
+            "embeddingScope": ["clip", "asset"],
+        },
+        "inferenceId": "req-42",
+    }
+
+
+def test_timed_media_request_without_options_carries_only_the_media_source():
+    request = build_marengo_3_request("s3://media/clip.mp4", {"input_type": "video"})
+    assert request["video"] == {"mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4"}}}
+
+
+@pytest.mark.parametrize(
+    "params",
+    [
+        {"input_type": "clip"},
+        {"input_type": "video", "embeddingOption": ["visual-text"]},
+        {"input_type": "video", "segmentation": {"method": "fixed", "dynamic": {"minDurationSec": 4}}},
+        {"input_type": "multi_input", "media_sources": ["not", "a", "mapping"]},
+    ],
+)
+def test_invalid_marengo_3_params_are_rejected_before_the_request_is_sent(params):
+    with pytest.raises(BedrockError, match=r"Invalid Marengo 3\.0 parameters") as excinfo:
+        build_marengo_3_request("s3://media/clip.mp4", params)
+    assert excinfo.value.status_code == 400
+
+
+def test_config_sends_the_nested_payload_for_marengo_3_and_the_flat_one_for_2_7():
+    nested = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_US)._transform_request(
+        input="hello", inference_params={"input_type": "text"}
+    )
+    flat = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_27_US)._transform_request(
+        input="hello", inference_params={"input_type": "text"}
+    )
+    assert nested == {"inputType": "text", "text": {"inputText": "hello"}}
+    assert flat == {"inputType": "text", "inputText": "hello", "textTruncate": "end"}
+
+
+def test_config_without_a_model_keeps_the_2_7_payload():
+    request = TwelveLabsMarengoEmbeddingConfig()._transform_request(input="hello", inference_params={})
+    assert request == {"inputType": "text", "inputText": "hello", "textTruncate": "end"}
+
+
+@pytest.mark.parametrize("input_type", ["video", "audio"])
+def test_marengo_3_video_and_audio_still_require_the_async_route(input_type):
+    with pytest.raises(ValueError, match=f"Input type '{input_type}' requires async_invoke route"):
+        TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_BASE)._transform_request(
+            input="s3://media/clip.mp4", inference_params={"input_type": input_type}
+        )
+
+
+def test_marengo_3_async_invoke_wraps_the_nested_payload_with_the_base_model_id():
+    request = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_BASE)._transform_request(
+        input="s3://media/clip.mp4",
+        inference_params={"input_type": "video", "embeddingOption": ["visual"], "output_s3_uri": OUTPUT_S3_URI},
+        async_invoke_route=True,
+        model_id="async_invoke%2Ftwelvelabs.marengo-embed-3-0-v1%3A0",
+        output_s3_uri=OUTPUT_S3_URI,
+    )
+    assert wire(request) == {
+        "modelId": MARENGO_3_BASE,
+        "modelInput": {
+            "inputType": "video",
+            "video": {"mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4"}}, "embeddingOption": ["visual"]},
+        },
+        "outputDataConfig": {"s3OutputDataConfig": {"s3Uri": OUTPUT_S3_URI}},
+    }
+
+
+def test_marengo_3_async_invoke_requires_an_output_s3_uri():
+    with pytest.raises(ValueError, match="output_s3_uri cannot be empty"):
+        TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_BASE)._transform_request(
+            input="hello",
+            inference_params={"input_type": "text"},
+            async_invoke_route=True,
+            model_id=MARENGO_3_BASE,
+            output_s3_uri="",
+        )
+
+
+def test_encoding_format_float_no_longer_injects_2_7_embedding_options_for_marengo_3():
+    marengo_3 = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_US).map_openai_params(
+        non_default_params={"encoding_format": "float"}, optional_params={}
+    )
+    marengo_27 = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_27_US).map_openai_params(
+        non_default_params={"encoding_format": "float"}, optional_params={}
+    )
+    assert marengo_3 == {}
+    assert marengo_27 == {"embeddingOption": ["visual-text", "visual-image"]}
+
+
+def test_marengo_3_only_params_are_forwarded_by_map_openai_params():
+    mapped = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_US).map_openai_params(
+        non_default_params={
+            "input_type": "text_image",
+            "media_source": DUCK_DATA_URL,
+            "media_sources": {"bird": DUCK_DATA_URL},
+            "endSec": 5,
+            "segmentation": {"method": "fixed", "fixed": {"durationSec": 6}},
+            "embeddingType": ["separate_embedding"],
+            "embeddingScope": ["clip"],
+            "inferenceId": "req-1",
+        },
+        optional_params={},
+    )
+    assert mapped == {
+        "inputType": "text_image",
+        "media_source": DUCK_DATA_URL,
+        "media_sources": {"bird": DUCK_DATA_URL},
+        "endSec": 5,
+        "segmentation": {"method": "fixed", "fixed": {"durationSec": 6}},
+        "embeddingType": ["separate_embedding"],
+        "embeddingScope": ["clip"],
+        "inferenceId": "req-1",
+    }
diff --git a/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py b/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py
new file mode 100644
index 00000000000..300dfeb5238
--- /dev/null
+++ b/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py
@@ -0,0 +1,88 @@
+import json
+from pathlib import Path
+
+import pytest
+
+import litellm
+from litellm.constants import bedrock_embedding_models
+from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
+from litellm.types.utils import Usage
+
+REPO_ROOT = Path(__file__).parents[2]
+MAIN_PATH = REPO_ROOT / "model_prices_and_context_window.json"
+BACKUP_PATH = REPO_ROOT / "litellm" / "model_prices_and_context_window_backup.json"
+
+BASE_MODEL = "twelvelabs.marengo-embed-3-0-v1:0"
+PROFILE_MODELS = ("us.twelvelabs.marengo-embed-3-0-v1:0", "eu.twelvelabs.marengo-embed-3-0-v1:0")
+ALL_MODELS = (BASE_MODEL, *PROFILE_MODELS)
+
+TEXT_REQUEST_COST = 7e-05
+IMAGE_REQUEST_COST = 0.0001
+VIDEO_COST_PER_SECOND = 0.0007
+AUDIO_COST_PER_SECOND = 0.00014
+
+
+def _load(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+@pytest.mark.parametrize("model", ALL_MODELS)
+def test_marengo_embed_3_specs(model):
+    info = _load(MAIN_PATH).get(model)
+    assert info is not None, f"{model} missing from model_prices_and_context_window.json"
+
+    assert info["litellm_provider"] == "bedrock"
+    assert info["mode"] == "embedding"
+    assert info["input_cost_per_token"] == TEXT_REQUEST_COST
+    assert info["output_cost_per_token"] == 0.0
+    assert info["max_input_tokens"] == 500
+    assert info["max_tokens"] == 500
+    assert info["output_vector_size"] == 512
+    assert info["supports_embedding_image_input"] is True
+    assert info["supports_image_input"] is True
+    assert "deprecation_date" not in info
+
+    routed_model, provider, _, _ = get_llm_provider(model=f"bedrock/{model}")
+    assert routed_model == model
+    assert provider == "bedrock"
+
+
+@pytest.mark.parametrize("model", PROFILE_MODELS)
+def test_marengo_embed_3_inference_profiles_price_image_video_and_audio(model):
+    info = _load(MAIN_PATH)[model]
+    assert info["input_cost_per_image"] == IMAGE_REQUEST_COST
+    assert info["input_cost_per_video_per_second"] == VIDEO_COST_PER_SECOND
+    assert info["input_cost_per_audio_per_second"] == AUDIO_COST_PER_SECOND
+
+
+@pytest.mark.parametrize("model", ALL_MODELS)
+def test_marengo_embed_3_is_visible_to_callers(model, local_model_cost_map):
+    info = litellm.get_model_info(model=model, custom_llm_provider="bedrock")
+    assert info["mode"] == "embedding"
+    assert info["output_vector_size"] == 512
+    assert info["max_input_tokens"] == 500
+
+
+@pytest.mark.parametrize("model", ALL_MODELS)
+def test_marengo_embed_3_text_request_is_billed(model, local_model_cost_map):
+    usage = Usage(prompt_tokens=128, completion_tokens=0, total_tokens=128)
+    prompt_cost, completion_cost = litellm.cost_per_token(
+        model=model, usage_object=usage, custom_llm_provider="bedrock"
+    )
+    assert prompt_cost == pytest.approx(128 * TEXT_REQUEST_COST)
+    assert completion_cost == 0.0
+
+
+def test_marengo_embed_3_is_a_known_bedrock_embedding_model():
+    assert BASE_MODEL in bedrock_embedding_models
+
+
+@pytest.mark.parametrize("model", ALL_MODELS)
+def test_backup_matches_main(model):
+    main_cost = _load(MAIN_PATH)
+    backup_cost = _load(BACKUP_PATH)
+
+    assert model in main_cost, f"{model} missing from model_prices_and_context_window.json"
+    assert model in backup_cost, f"{model} missing from model_prices_and_context_window_backup.json"
+    assert backup_cost[model] == main_cost[model], f"{model} differs between main and backup model cost maps"

From e2560390770bd4387c82889eff2d606ba88c42c5 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 7 Sep 2026 17:49:03 -0700
Subject: [PATCH 07/31] fix(bedrock): import assert_never from
 typing_extensions for Python 3.10

---
 .../llms/bedrock/embed/twelvelabs_marengo_3_transformation.py  | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
index 2ea99db47f0..0f61d37258f 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
@@ -7,9 +7,10 @@ Docs - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-mar
 
 from collections.abc import Mapping
 from types import MappingProxyType
-from typing import Final, assert_never
+from typing import Final
 
 from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
+from typing_extensions import assert_never
 
 from litellm.llms.bedrock.common_utils import BedrockError
 from litellm.types.llms.bedrock import (

From 86790a7723892c338ea3fcc680296a721c7fc47f Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:20:28 -0700
Subject: [PATCH 08/31] fix(bedrock): bill Marengo embeddings per request
 instead of per estimated token

AWS prices Marengo 2.7 and 3.0 text and image embeddings per request, never per
token, and their responses carry no token count. The old transform estimated
prompt tokens from the vector length, which billed a text request at 128 tokens
times the per-token rate (0.00896 instead of 0.00007). Marengo responses now
report zero tokens with query_count and image_count derived from the request
batch, and all six Marengo cost-map entries price per request (with the video
and audio per-second and per-image rates on the base entries). query_count is a
new prompt_tokens_details field wired to input_cost_per_query in the cost
calculator.
---
 .../litellm_core_utils/llm_cost_calc/utils.py |  10 ++
 litellm/llms/bedrock/embed/embedding.py       |   2 +-
 .../twelvelabs_marengo_transformation.py      | 142 +++++++++++-------
 ...odel_prices_and_context_window_backup.json |  18 ++-
 litellm/types/utils.py                        |   7 +-
 litellm/utils.py                              |   2 +-
 model_prices_and_context_window.json          |  18 ++-
 .../llm_cost_calc/test_llm_cost_calc_utils.py |  32 ++++
 .../bedrock/embed/test_bedrock_embedding.py   |  47 +++++-
 ..._bedrock_marengo_embed_3_model_metadata.py |  45 +++++-
 10 files changed, 240 insertions(+), 83 deletions(-)

diff --git a/litellm/litellm_core_utils/llm_cost_calc/utils.py b/litellm/litellm_core_utils/llm_cost_calc/utils.py
index 68dc27ec25e..46574ebae3f 100644
--- a/litellm/litellm_core_utils/llm_cost_calc/utils.py
+++ b/litellm/litellm_core_utils/llm_cost_calc/utils.py
@@ -780,6 +780,7 @@ class PromptTokensDetailsResult(TypedDict):
     image_count: int
     video_length_seconds: float
     audio_length_seconds: float
+    query_count: int
 
 
 def parse_prompt_tokens_details(usage: Usage) -> PromptTokensDetailsResult:
@@ -828,6 +829,7 @@ def parse_prompt_tokens_details(usage: Usage) -> PromptTokensDetailsResult:
         )
         or 0.0
     )
+    query_count: Final = _coerce_token_count(getattr(usage.prompt_tokens_details, "query_count", 0))
 
     return PromptTokensDetailsResult(
         cache_hit_tokens=cache_hit_tokens,
@@ -841,6 +843,7 @@ def parse_prompt_tokens_details(usage: Usage) -> PromptTokensDetailsResult:
         image_count=image_count,
         video_length_seconds=float(video_length_seconds),
         audio_length_seconds=float(audio_length_seconds),
+        query_count=query_count,
     )
 
 
@@ -978,6 +981,12 @@ def _calculate_input_cost(
             prompt_tokens_details["audio_length_seconds"],
         )
 
+    ### QUERY COUNT COST
+    if prompt_tokens_details["query_count"]:
+        prompt_cost += calculate_cost_component(
+            model_info, "input_cost_per_query", prompt_tokens_details["query_count"]
+        )
+
     return prompt_cost
 
 
@@ -1149,6 +1158,7 @@ def generic_cost_per_token(
         image_count=0,
         video_length_seconds=0.0,
         audio_length_seconds=0.0,
+        query_count=0,
     )
     if usage.prompt_tokens_details:
         prompt_tokens_details = parse_prompt_tokens_details(usage)
diff --git a/litellm/llms/bedrock/embed/embedding.py b/litellm/llms/bedrock/embed/embedding.py
index ab27afcf817..69eb9b693b1 100644
--- a/litellm/llms/bedrock/embed/embedding.py
+++ b/litellm/llms/bedrock/embed/embedding.py
@@ -229,7 +229,7 @@ class BedrockEmbedding(BaseAWSLLM):
                 returned_response = AmazonTitanG1Config()._transform_response(response_list=response_list, model=model)
             elif provider == "twelvelabs":
                 returned_response = TwelveLabsMarengoEmbeddingConfig()._transform_response(
-                    response_list=response_list, model=model
+                    response_list=response_list, model=model, batch_data=batch_data
                 )
             elif provider == "nova":
                 returned_response = AmazonNovaEmbeddingConfig()._transform_response(
diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
index 79b5825d2eb..ddf6dfbcc4d 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
@@ -7,14 +7,19 @@ Docs - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-mar
 Marengo 3.0 docs - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-marengo-3.html
 """
 
+from collections.abc import Mapping
 from typing import Final, cast
 
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+from typing_extensions import assert_never
+
 from litellm.llms.bedrock.embed.twelvelabs_marengo_3_transformation import (
     build_marengo_3_request,
     is_marengo_3_model,
 )
 from litellm.types.llms.bedrock import (
     TWELVELABS_EMBEDDING_INPUT_TYPES,
+    TWELVELABS_MARENGO_3_INPUT_TYPES,
     TwelveLabsAsyncInvokeRequest,
     TwelveLabsMarengo3EmbeddingRequest,
     TwelveLabsMarengoEmbeddingRequest,
@@ -22,7 +27,76 @@ from litellm.types.llms.bedrock import (
     TwelveLabsS3Location,
     TwelveLabsS3OutputDataConfig,
 )
-from litellm.types.utils import Embedding, EmbeddingResponse, Usage
+from litellm.types.utils import Embedding, EmbeddingResponse, PromptTokensDetailsWrapper, Usage
+
+
+class MarengoEmbeddingItem(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    embedding: tuple[float, ...]
+
+
+class MarengoInvokeResponse(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    data: tuple[MarengoEmbeddingItem, ...] = ()
+    embedding: tuple[float, ...] | None = None
+    embeddings: tuple[MarengoEmbeddingItem, ...] = ()
+
+    def vectors(self) -> tuple[tuple[float, ...], ...]:
+        if self.data:
+            return tuple(item.embedding for item in self.data)
+        if self.embedding is not None:
+            return (self.embedding,)
+        return tuple(item.embedding for item in self.embeddings)
+
+
+class MarengoBilledMultiInput(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    inputText: str | None = None
+    mediaSources: tuple[Mapping[str, object], ...] = ()
+
+
+class MarengoBilledRequest(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    inputType: TWELVELABS_MARENGO_3_INPUT_TYPES | None = None
+    multi_input: MarengoBilledMultiInput | None = None
+
+
+INVOKE_RESPONSES: Final = TypeAdapter(tuple[MarengoInvokeResponse, ...])
+BILLED_REQUESTS: Final = TypeAdapter(tuple[MarengoBilledRequest, ...])
+
+
+def _billed_units(request: MarengoBilledRequest) -> tuple[int, int]:
+    input_type: Final = request.inputType
+    match input_type:
+        case "text":
+            return (1, 0)
+        case "image":
+            return (0, 1)
+        case "text_image":
+            return (1, 1)
+        case "multi_input":
+            multi_input: Final = request.multi_input or MarengoBilledMultiInput()
+            return (1 if multi_input.inputText else 0, len(multi_input.mediaSources))
+        case "video" | "audio" | None:
+            return (0, 0)
+        case _:
+            assert_never(input_type)
+
+
+def _billed_usage(batch_data: list[dict] | None) -> Usage:
+    units: Final = tuple(_billed_units(request) for request in BILLED_REQUESTS.validate_python(batch_data or ()))
+    query_count: Final = sum(text_requests for text_requests, _ in units)
+    image_count: Final = sum(images for _, images in units)
+    details: Final = (
+        PromptTokensDetailsWrapper(query_count=query_count or None, image_count=image_count or None)
+        if query_count or image_count
+        else None
+    )
+    return Usage(prompt_tokens=0, completion_tokens=0, total_tokens=0, prompt_tokens_details=details)
 
 
 class TwelveLabsMarengoEmbeddingConfig:
@@ -223,62 +297,16 @@ class TwelveLabsMarengoEmbeddingConfig:
             ),
         )
 
-    def _transform_response(self, response_list: list[dict], model: str) -> EmbeddingResponse:
-        """
-        Transform TwelveLabs response to OpenAI format.
-        Handles the actual TwelveLabs response format: {"data": [{"embedding": [...]}]}
-        """
-        embeddings: Final[list[Embedding]] = []
-        total_tokens = 0
-
-        for response in response_list:
-            # TwelveLabs response format has a "data" field containing the embeddings
-            if "data" in response and isinstance(response["data"], list):
-                for item in response["data"]:
-                    if "embedding" in item:
-                        # Single embedding response
-                        embedding = Embedding(
-                            embedding=item["embedding"],
-                            index=len(embeddings),
-                            object="embedding",
-                        )
-                        embeddings.append(embedding)
-
-                        # Estimate token count (rough approximation)
-                        if "inputTextTokenCount" in item:
-                            total_tokens += item["inputTextTokenCount"]
-                        else:
-                            # Rough estimate: 1 token per 4 characters for text, or use embedding size
-                            total_tokens += len(item["embedding"]) // 4
-            elif "embedding" in response:
-                # Direct embedding response (fallback for other formats)
-                embedding = Embedding(
-                    embedding=response["embedding"],
-                    index=len(embeddings),
-                    object="embedding",
-                )
-                embeddings.append(embedding)
-
-                # Estimate token count (rough approximation)
-                if "inputTextTokenCount" in response:
-                    total_tokens += response["inputTextTokenCount"]
-                else:
-                    # Rough estimate: 1 token per 4 characters for text
-                    total_tokens += len(response.get("inputText", "")) // 4
-            elif "embeddings" in response:
-                # Multiple embeddings response (from video/audio)
-                for i, emb in enumerate(response["embeddings"]):
-                    embedding = Embedding(
-                        embedding=emb["embedding"],
-                        index=len(embeddings),
-                        object="embedding",
-                    )
-                    embeddings.append(embedding)
-                    total_tokens += len(emb["embedding"]) // 4  # Rough estimate
-
-        usage: Final = Usage(prompt_tokens=total_tokens, total_tokens=total_tokens)
-
-        return EmbeddingResponse(data=embeddings, model=model, usage=usage)
+    def _transform_response(
+        self, response_list: list[dict], model: str, batch_data: list[dict] | None = None
+    ) -> EmbeddingResponse:
+        vectors: Final = tuple(
+            vector for response in INVOKE_RESPONSES.validate_python(response_list) for vector in response.vectors()
+        )
+        embeddings: Final = [
+            Embedding(embedding=list(vector), index=index, object="embedding") for index, vector in enumerate(vectors)
+        ]
+        return EmbeddingResponse(data=embeddings, model=model, usage=_billed_usage(batch_data))
 
     def _transform_async_invoke_response(self, response: dict, model: str) -> EmbeddingResponse:
         """
diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index cc75354a495..7784ed2a6ac 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -650,7 +650,10 @@
     },
     "twelvelabs.marengo-embed-2-7-v1:0": {
         "deprecation_date": "2026-11-30",
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
         "litellm_provider": "bedrock",
         "max_input_tokens": 77,
         "max_tokens": 77,
@@ -662,7 +665,7 @@
     },
     "us.twelvelabs.marengo-embed-2-7-v1:0": {
         "deprecation_date": "2026-11-30",
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
@@ -677,7 +680,7 @@
     },
     "eu.twelvelabs.marengo-embed-2-7-v1:0": {
         "deprecation_date": "2026-11-30",
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
@@ -691,7 +694,10 @@
         "supports_image_input": true
     },
     "twelvelabs.marengo-embed-3-0-v1:0": {
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
         "litellm_provider": "bedrock",
         "max_input_tokens": 500,
         "max_tokens": 500,
@@ -702,7 +708,7 @@
         "supports_image_input": true
     },
     "us.twelvelabs.marengo-embed-3-0-v1:0": {
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
@@ -716,7 +722,7 @@
         "supports_image_input": true
     },
     "eu.twelvelabs.marengo-embed-3-0-v1:0": {
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
diff --git a/litellm/types/utils.py b/litellm/types/utils.py
index 9b5fb08a45f..c55eb6831c7 100644
--- a/litellm/types/utils.py
+++ b/litellm/types/utils.py
@@ -272,7 +272,7 @@ class ModelInfoBase(ProviderSpecificModelInfo, total=False):
     input_cost_per_token_above_272k_tokens_flex: float | None
     input_cost_per_token_above_512k_tokens: float | None  # MiniMax-M3: prompts >512K priced at 2x input
     input_cost_per_character_above_128k_tokens: float | None  # only for vertex ai models
-    input_cost_per_query: float | None  # only for rerank models
+    input_cost_per_query: float | None  # per-request pricing: rerank, search, and Bedrock Marengo embeddings
     input_cost_per_image: float | None  # only for vertex ai models
     input_cost_per_image_token: float | None  # for gpt-image-1 and similar models
     input_cost_per_video_token: float | None  # for gemini omni models with video input
@@ -1693,6 +1693,9 @@ class PromptTokensDetailsWrapper(
     audio_length_seconds: float | None = None
     """Length of audio sent to the model. Used for multimodal embeddings priced per audio-second."""
 
+    query_count: int | None = None
+    """Number of billable requests sent to the model. Used for embeddings priced per request, such as Bedrock Marengo."""
+
     cache_write_tokens: int | None = None
     """Number of cache write (creation) tokens sent to the model. OpenAI naming (prompt_tokens_details.cache_write_tokens); this is the canonical field."""
 
@@ -1734,6 +1737,8 @@ class PromptTokensDetailsWrapper(
             del self.video_length_seconds
         if self.audio_length_seconds is None:
             del self.audio_length_seconds
+        if self.query_count is None:
+            del self.query_count
         if self.web_search_requests is None:
             del self.web_search_requests
         if self.google_maps_grounding_requests is None:
diff --git a/litellm/utils.py b/litellm/utils.py
index b98aa821ff3..2ed1ad84e9c 100644
--- a/litellm/utils.py
+++ b/litellm/utils.py
@@ -6033,7 +6033,7 @@ def get_model_info(
             input_cost_per_character_above_128k_tokens: Optional[
                 float
             ]  # only for vertex ai models
-            input_cost_per_query: Optional[float] # only for rerank models
+            input_cost_per_query: Optional[float] # per-request pricing: rerank, search, and Bedrock Marengo embeddings
             input_cost_per_image: Optional[float]  # only for vertex ai models
             input_cost_per_audio_token: Optional[float]
             input_cost_per_audio_per_second: Optional[float]  # only for vertex ai models
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index cc75354a495..7784ed2a6ac 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -650,7 +650,10 @@
     },
     "twelvelabs.marengo-embed-2-7-v1:0": {
         "deprecation_date": "2026-11-30",
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
         "litellm_provider": "bedrock",
         "max_input_tokens": 77,
         "max_tokens": 77,
@@ -662,7 +665,7 @@
     },
     "us.twelvelabs.marengo-embed-2-7-v1:0": {
         "deprecation_date": "2026-11-30",
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
@@ -677,7 +680,7 @@
     },
     "eu.twelvelabs.marengo-embed-2-7-v1:0": {
         "deprecation_date": "2026-11-30",
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
@@ -691,7 +694,10 @@
         "supports_image_input": true
     },
     "twelvelabs.marengo-embed-3-0-v1:0": {
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
+        "input_cost_per_video_per_second": 0.0007,
+        "input_cost_per_audio_per_second": 0.00014,
+        "input_cost_per_image": 0.0001,
         "litellm_provider": "bedrock",
         "max_input_tokens": 500,
         "max_tokens": 500,
@@ -702,7 +708,7 @@
         "supports_image_input": true
     },
     "us.twelvelabs.marengo-embed-3-0-v1:0": {
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
@@ -716,7 +722,7 @@
         "supports_image_input": true
     },
     "eu.twelvelabs.marengo-embed-3-0-v1:0": {
-        "input_cost_per_token": 7e-05,
+        "input_cost_per_query": 7e-05,
         "input_cost_per_video_per_second": 0.0007,
         "input_cost_per_audio_per_second": 0.00014,
         "input_cost_per_image": 0.0001,
diff --git a/tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py b/tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py
index 59f0938e338..65a6dd2a4ca 100644
--- a/tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py
+++ b/tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py
@@ -2658,6 +2658,7 @@ def test_cache_writing_cost_with_zero_creation_tokens_and_ephemeral_details():
         "image_count": 0,
         "video_length_seconds": 0.0,
         "audio_length_seconds": 0.0,
+        "query_count": 0,
     }
 
     model_info: ModelInfo = {}
@@ -3239,6 +3240,37 @@ def test_image_count_prevents_text_tokens_fallback(_local_model_cost_map):
     assert completion_cost == 0.0
 
 
+def test_query_count_bills_input_cost_per_query(_local_model_cost_map):
+    usage = Usage(
+        prompt_tokens=0,
+        completion_tokens=0,
+        total_tokens=0,
+        prompt_tokens_details=PromptTokensDetailsWrapper(query_count=3, image_count=1),
+    )
+
+    prompt_cost, completion_cost = generic_cost_per_token(
+        model="us.twelvelabs.marengo-embed-3-0-v1:0",
+        usage=usage,
+        custom_llm_provider="bedrock",
+    )
+
+    assert prompt_cost == pytest.approx(3 * 7e-05 + 1e-04)
+    assert completion_cost == 0.0
+
+
+def test_query_count_is_free_without_a_per_query_price(_local_model_cost_map):
+    usage = Usage(
+        prompt_tokens=0,
+        completion_tokens=0,
+        total_tokens=0,
+        prompt_tokens_details=PromptTokensDetailsWrapper(query_count=1),
+    )
+
+    prompt_cost, _ = generic_cost_per_token(model="text-embedding-3-small", usage=usage, custom_llm_provider="openai")
+
+    assert prompt_cost == 0.0
+
+
 # ---------------------------------------------------------------------------
 # Data-residency (OpenAI regional processing) tests
 # ---------------------------------------------------------------------------
diff --git a/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py b/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
index b37e991b0b2..c29a87cd0cf 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
@@ -5,6 +5,7 @@ from unittest.mock import Mock, patch
 import pytest
 
 import litellm
+from litellm.llms.bedrock.embed.twelvelabs_marengo_transformation import TwelveLabsMarengoEmbeddingConfig
 from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler, HTTPHandler
 
 # Mock responses for different embedding models
@@ -1066,17 +1067,19 @@ MARENGO_3_DUCK = "data:image/png;base64,ZHVjaw=="
 
 
 @pytest.mark.parametrize(
-    "model,kwargs,expected_body",
+    "model,kwargs,expected_body,expected_usage_details",
     [
         (
             "bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
             {"input_type": "text"},
             {"inputType": "text", "text": {"inputText": "a duck on water"}},
+            {"query_count": 1},
         ),
         (
             "bedrock/twelvelabs.marengo-embed-3-0-v1:0",
             {"input_type": "text"},
             {"inputType": "text", "text": {"inputText": "a duck on water"}},
+            {"query_count": 1},
         ),
         (
             "bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
@@ -1085,6 +1088,7 @@ MARENGO_3_DUCK = "data:image/png;base64,ZHVjaw=="
                 "inputType": "text_image",
                 "text_image": {"inputText": "a duck on water", "mediaSource": {"base64String": "ZHVjaw=="}},
             },
+            {"query_count": 1, "image_count": 1},
         ),
         (
             "bedrock/us.twelvelabs.marengo-embed-3-0-v1:0",
@@ -1096,10 +1100,13 @@ MARENGO_3_DUCK = "data:image/png;base64,ZHVjaw=="
                     "mediaSources": [{"name": "bird", "mediaType": "image", "base64String": "ZHVjaw=="}],
                 },
             },
+            {"query_count": 1, "image_count": 1},
         ),
     ],
 )
-def test_marengo_3_embedding_sends_the_nested_payload_and_parses_512_dims(model, kwargs, expected_body):
+def test_marengo_3_embedding_sends_the_nested_payload_and_parses_512_dims(
+    model, kwargs, expected_body, expected_usage_details
+):
     client = HTTPHandler()
 
     with patch.object(client, "post") as mock_post:
@@ -1122,7 +1129,9 @@ def test_marengo_3_embedding_sends_the_nested_payload_and_parses_512_dims(model,
     assert mock_post.call_args.kwargs["url"].endswith(f"/model/{model.removeprefix('bedrock/').replace(':', '%3A')}/invoke")
     assert len(response.data[0]["embedding"]) == 512
     assert response.data[0]["embedding"][:2] == [0.0, 0.01]
-    assert response.usage.prompt_tokens == 128
+    assert response.usage.prompt_tokens == 0
+    assert response.usage.total_tokens == 0
+    assert response.usage.prompt_tokens_details.model_dump(exclude_none=True) == expected_usage_details
 
 
 def test_marengo_3_image_embedding_sends_the_media_under_the_image_key():
@@ -1150,6 +1159,8 @@ def test_marengo_3_image_embedding_sends_the_media_under_the_image_key():
     }
     assert len(response.data[0]["embedding"]) == 512
     assert response.data[0]["embedding"][:2] == [0.0, 0.01]
+    assert response.usage.prompt_tokens == 0
+    assert response.usage.prompt_tokens_details.model_dump(exclude_none=True) == {"image_count": 1}
 
 
 def test_marengo_2_7_embedding_keeps_the_flat_payload():
@@ -1177,6 +1188,36 @@ def test_marengo_2_7_embedding_keeps_the_flat_payload():
         "textTruncate": "end",
     }
     assert response.data[0]["embedding"] == [0.1, 0.2, 0.3]
+    assert response.usage.prompt_tokens == 0
+    assert response.usage.prompt_tokens_details.model_dump(exclude_none=True) == {"query_count": 1}
+
+
+def test_marengo_usage_counts_text_requests_and_images_across_a_batch():
+    duck = {"mediaType": "image", "base64String": "ZHVjaw=="}
+    response = TwelveLabsMarengoEmbeddingConfig()._transform_response(
+        response_list=[marengo_3_embedding_response, marengo_3_embedding_response, marengo_3_embedding_response],
+        model="us.twelvelabs.marengo-embed-3-0-v1:0",
+        batch_data=[
+            {"inputType": "text", "text": {"inputText": "a duck"}},
+            {"inputType": "image", "image": {"mediaSource": {"base64String": "ZHVjaw=="}}},
+            {"inputType": "multi_input", "multi_input": {"mediaSources": [{"name": "a", **duck}, {"name": "b", **duck}]}},
+        ],
+    )
+
+    assert [item["index"] for item in response.data] == [0, 1, 2]
+    assert response.usage.prompt_tokens == 0
+    assert response.usage.total_tokens == 0
+    assert response.usage.prompt_tokens_details.model_dump(exclude_none=True) == {"query_count": 1, "image_count": 3}
+
+
+def test_marengo_usage_without_request_data_bills_nothing():
+    response = TwelveLabsMarengoEmbeddingConfig()._transform_response(
+        response_list=[marengo_3_embedding_response], model="us.twelvelabs.marengo-embed-3-0-v1:0"
+    )
+
+    assert len(response.data[0]["embedding"]) == 512
+    assert response.usage.prompt_tokens == 0
+    assert response.usage.prompt_tokens_details is None
 
 
 def test_marengo_3_text_image_without_media_source_is_a_bad_request():
diff --git a/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py b/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py
index 300dfeb5238..0bb99339435 100644
--- a/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py
+++ b/tests/test_litellm/test_bedrock_marengo_embed_3_model_metadata.py
@@ -6,7 +6,7 @@ import pytest
 import litellm
 from litellm.constants import bedrock_embedding_models
 from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
-from litellm.types.utils import Usage
+from litellm.types.utils import PromptTokensDetailsWrapper, Usage
 
 REPO_ROOT = Path(__file__).parents[2]
 MAIN_PATH = REPO_ROOT / "model_prices_and_context_window.json"
@@ -15,6 +15,12 @@ BACKUP_PATH = REPO_ROOT / "litellm" / "model_prices_and_context_window_backup.js
 BASE_MODEL = "twelvelabs.marengo-embed-3-0-v1:0"
 PROFILE_MODELS = ("us.twelvelabs.marengo-embed-3-0-v1:0", "eu.twelvelabs.marengo-embed-3-0-v1:0")
 ALL_MODELS = (BASE_MODEL, *PROFILE_MODELS)
+MARENGO_2_7_MODELS = (
+    "twelvelabs.marengo-embed-2-7-v1:0",
+    "us.twelvelabs.marengo-embed-2-7-v1:0",
+    "eu.twelvelabs.marengo-embed-2-7-v1:0",
+)
+PER_REQUEST_MODELS = (*ALL_MODELS, *MARENGO_2_7_MODELS)
 
 TEXT_REQUEST_COST = 7e-05
 IMAGE_REQUEST_COST = 0.0001
@@ -34,7 +40,7 @@ def test_marengo_embed_3_specs(model):
 
     assert info["litellm_provider"] == "bedrock"
     assert info["mode"] == "embedding"
-    assert info["input_cost_per_token"] == TEXT_REQUEST_COST
+    assert info["input_cost_per_query"] == TEXT_REQUEST_COST
     assert info["output_cost_per_token"] == 0.0
     assert info["max_input_tokens"] == 500
     assert info["max_tokens"] == 500
@@ -48,9 +54,11 @@ def test_marengo_embed_3_specs(model):
     assert provider == "bedrock"
 
 
-@pytest.mark.parametrize("model", PROFILE_MODELS)
-def test_marengo_embed_3_inference_profiles_price_image_video_and_audio(model):
+@pytest.mark.parametrize("model", PER_REQUEST_MODELS)
+def test_marengo_prices_are_per_request_not_per_token(model):
     info = _load(MAIN_PATH)[model]
+    assert "input_cost_per_token" not in info
+    assert info["input_cost_per_query"] == TEXT_REQUEST_COST
     assert info["input_cost_per_image"] == IMAGE_REQUEST_COST
     assert info["input_cost_per_video_per_second"] == VIDEO_COST_PER_SECOND
     assert info["input_cost_per_audio_per_second"] == AUDIO_COST_PER_SECOND
@@ -64,13 +72,34 @@ def test_marengo_embed_3_is_visible_to_callers(model, local_model_cost_map):
     assert info["max_input_tokens"] == 500
 
 
-@pytest.mark.parametrize("model", ALL_MODELS)
-def test_marengo_embed_3_text_request_is_billed(model, local_model_cost_map):
+@pytest.mark.parametrize("model", PER_REQUEST_MODELS)
+@pytest.mark.parametrize(
+    "details,expected_cost",
+    [
+        (PromptTokensDetailsWrapper(query_count=1), TEXT_REQUEST_COST),
+        (PromptTokensDetailsWrapper(image_count=1), IMAGE_REQUEST_COST),
+        (PromptTokensDetailsWrapper(query_count=1, image_count=1), TEXT_REQUEST_COST + IMAGE_REQUEST_COST),
+        (PromptTokensDetailsWrapper(query_count=1, image_count=2), TEXT_REQUEST_COST + 2 * IMAGE_REQUEST_COST),
+        (PromptTokensDetailsWrapper(video_length_seconds=10), 10 * VIDEO_COST_PER_SECOND),
+        (PromptTokensDetailsWrapper(audio_length_seconds=10), 10 * AUDIO_COST_PER_SECOND),
+    ],
+)
+def test_marengo_requests_are_billed_per_request(model, details, expected_cost, local_model_cost_map):
+    usage = Usage(prompt_tokens=0, completion_tokens=0, total_tokens=0, prompt_tokens_details=details)
+    prompt_cost, completion_cost = litellm.cost_per_token(
+        model=model, usage_object=usage, custom_llm_provider="bedrock"
+    )
+    assert prompt_cost == pytest.approx(expected_cost)
+    assert completion_cost == 0.0
+
+
+@pytest.mark.parametrize("model", PER_REQUEST_MODELS)
+def test_marengo_token_counts_bill_nothing(model, local_model_cost_map):
     usage = Usage(prompt_tokens=128, completion_tokens=0, total_tokens=128)
     prompt_cost, completion_cost = litellm.cost_per_token(
         model=model, usage_object=usage, custom_llm_provider="bedrock"
     )
-    assert prompt_cost == pytest.approx(128 * TEXT_REQUEST_COST)
+    assert prompt_cost == 0.0
     assert completion_cost == 0.0
 
 
@@ -78,7 +107,7 @@ def test_marengo_embed_3_is_a_known_bedrock_embedding_model():
     assert BASE_MODEL in bedrock_embedding_models
 
 
-@pytest.mark.parametrize("model", ALL_MODELS)
+@pytest.mark.parametrize("model", PER_REQUEST_MODELS)
 def test_backup_matches_main(model):
     main_cost = _load(MAIN_PATH)
     backup_cost = _load(BACKUP_PATH)

From 80fea089b63e6b89e989f3a109b96a26bac90224 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:40:31 -0700
Subject: [PATCH 09/31] fix(bedrock): reject Marengo 2.7-only and misplaced
 media params on 3.0 unless drop_params

Marengo 3.0 requests now get a 400 naming any textTruncate, lengthSec,
useFixedLengthSec, or minClipSec parameter, and any video or audio option
sent with a text, image, text_image, or multi_input request, instead of
silently dropping them. drop_params (global, per deployment, or per
request) drops them instead. Pydantic validation errors name the field
and the reason, and the 3.0 marker is the exact "marengo-embed-3-" model
id segment.
---
 litellm/llms/bedrock/embed/embedding.py       |  3 +-
 .../twelvelabs_marengo_3_transformation.py    | 44 +++++++--
 .../twelvelabs_marengo_transformation.py      | 46 ++++++----
 ...est_twelvelabs_marengo_3_transformation.py | 90 +++++++++++++++++++
 4 files changed, 158 insertions(+), 25 deletions(-)

diff --git a/litellm/llms/bedrock/embed/embedding.py b/litellm/llms/bedrock/embed/embedding.py
index 69eb9b693b1..987c7cbf981 100644
--- a/litellm/llms/bedrock/embed/embedding.py
+++ b/litellm/llms/bedrock/embed/embedding.py
@@ -35,7 +35,7 @@ from .amazon_titan_multimodal_transformation import (
 )
 from .amazon_titan_v2_transformation import AmazonTitanV2Config
 from .cohere_transformation import BedrockCohereEmbeddingConfig
-from .twelvelabs_marengo_transformation import TwelveLabsMarengoEmbeddingConfig
+from .twelvelabs_marengo_transformation import TwelveLabsMarengoEmbeddingConfig, drop_params_enabled
 
 if TYPE_CHECKING:
     from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
@@ -480,6 +480,7 @@ class BedrockEmbedding(BaseAWSLLM):
                     async_invoke_route=has_async_invoke,
                     model_id=modelId,
                     output_s3_uri=inference_params.get("output_s3_uri"),
+                    drop_params=drop_params_enabled(litellm_params),
                 )
                 batch_data.append(twelvelabs_request)
         elif provider == "nova":
diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
index 0f61d37258f..f4f9cb03dab 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
@@ -35,7 +35,7 @@ from litellm.types.llms.bedrock import (
 )
 from litellm.utils import get_base64_str
 
-MARENGO_3_MODEL_MARKER: Final = "marengo-embed-3"
+MARENGO_3_MODEL_MARKER: Final = "marengo-embed-3-"
 S3_URI_PREFIX: Final = "s3://"
 TIMED_MEDIA_OPTION_FIELDS: Final = MappingProxyType(
     {
@@ -48,6 +48,9 @@ TIMED_MEDIA_OPTION_FIELDS: Final = MappingProxyType(
     }
 )
 TIMED_MEDIA_OPTIONS: Final = TypeAdapter(TwelveLabsMarengo3TimedMediaOptions)
+TIMED_INPUT_TYPES: Final = frozenset({"video", "audio"})
+MARENGO_2_7_ONLY_PARAMS: Final = ("textTruncate", "lengthSec", "useFixedLengthSec", "minClipSec")
+MARENGO_2_7_ONLY_FIELDS: Final = MappingProxyType({name: True for name in MARENGO_2_7_ONLY_PARAMS})
 
 
 def is_marengo_3_model(model: str | None) -> bool:
@@ -69,15 +72,23 @@ class Marengo3Params(BaseModel):
     embeddingType: tuple[TWELVELABS_MARENGO_3_EMBEDDING_TYPES, ...] | None = None
     embeddingScope: tuple[TWELVELABS_MARENGO_3_EMBEDDING_SCOPES, ...] | None = None
     inferenceId: str | None = None
+    textTruncate: object = None
+    lengthSec: object = None
+    useFixedLengthSec: object = None
+    minClipSec: object = None
 
     @property
     def resolved_input_type(self) -> TWELVELABS_MARENGO_3_INPUT_TYPES:
         return self.inputType or self.input_type or "text"
 
     def timed_media_options(self) -> TwelveLabsMarengo3TimedMediaOptions:
-        return TIMED_MEDIA_OPTIONS.validate_python(
-            self.model_dump(include=TIMED_MEDIA_OPTION_FIELDS, exclude_none=True)
-        )
+        return TIMED_MEDIA_OPTIONS.validate_python(self.given_timed_media_options())
+
+    def given_timed_media_options(self) -> dict[str, object]:
+        return self.model_dump(include=TIMED_MEDIA_OPTION_FIELDS, exclude_none=True)
+
+    def given_2_7_only_params(self) -> dict[str, object]:
+        return self.model_dump(include=MARENGO_2_7_ONLY_FIELDS, exclude_none=True)
 
 
 def _s3_location(uri: str, bucket_owner: str | None) -> TwelveLabsS3Location:
@@ -113,11 +124,23 @@ def _timed_media_input(media: str, params: Marengo3Params) -> TwelveLabsMarengo3
     return timed
 
 
+def _describe(error: ValidationError) -> str:
+    return "; ".join(
+        f"{'.'.join(str(part) for part in problem['loc'])}: {problem['msg']}" for problem in error.errors()
+    )
+
+
 def _validated_params(inference_params: Mapping[str, object]) -> Marengo3Params:
     try:
         return Marengo3Params.model_validate(inference_params)
     except ValidationError as error:
-        raise BedrockError(status_code=400, message=f"Invalid Marengo 3.0 parameters: {error}") from error
+        raise BedrockError(status_code=400, message=f"Invalid Marengo 3.0 parameters: {_describe(error)}") from error
+
+
+def _reject_unless_dropped(given: Mapping[str, object], drop_params: bool, reason: str) -> None:
+    if not given or drop_params:
+        return
+    raise BedrockError(status_code=400, message=f"{reason} {', '.join(given)}; set drop_params to drop them")
 
 
 def _require(value: str | None, input_type: str, param_name: str) -> str:
@@ -143,10 +166,19 @@ def _request_base(inference_id: str | None) -> TwelveLabsMarengo3RequestBase:
     return identified
 
 
-def build_marengo_3_request(input: str, inference_params: Mapping[str, object]) -> TwelveLabsMarengo3EmbeddingRequest:
+def build_marengo_3_request(
+    input: str, inference_params: Mapping[str, object], drop_params: bool = False
+) -> TwelveLabsMarengo3EmbeddingRequest:
     params: Final = _validated_params(inference_params)
     base: Final = _request_base(params.inferenceId)
     input_type: Final = params.resolved_input_type
+    _reject_unless_dropped(
+        params.given_2_7_only_params(), drop_params, "Marengo 3.0 does not accept the Marengo 2.7 parameters"
+    )
+    if input_type not in TIMED_INPUT_TYPES:
+        _reject_unless_dropped(
+            params.given_timed_media_options(), drop_params, f"Input type '{input_type}' does not accept"
+        )
     match input_type:
         case "text":
             text_request: Final[TwelveLabsMarengo3TextRequest] = {
diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
index ddf6dfbcc4d..35163ecf848 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
@@ -13,7 +13,9 @@ from typing import Final, cast
 from pydantic import BaseModel, ConfigDict, TypeAdapter
 from typing_extensions import assert_never
 
+import litellm
 from litellm.llms.bedrock.embed.twelvelabs_marengo_3_transformation import (
+    MARENGO_2_7_ONLY_PARAMS,
     build_marengo_3_request,
     is_marengo_3_model,
 )
@@ -99,6 +101,25 @@ def _billed_usage(batch_data: list[dict] | None) -> Usage:
     return Usage(prompt_tokens=0, completion_tokens=0, total_tokens=0, prompt_tokens_details=details)
 
 
+MARENGO_SHARED_PARAMS: Final = (
+    "encoding_format",
+    "embeddingOption",
+    "startSec",
+    "input_type",
+    "endSec",
+    "segmentation",
+    "embeddingType",
+    "embeddingScope",
+    "inferenceId",
+    "media_source",
+    "media_sources",
+)
+
+
+def drop_params_enabled(litellm_params: Mapping[str, object]) -> bool:
+    return litellm.drop_params is True or litellm_params.get("drop_params") is True
+
+
 class TwelveLabsMarengoEmbeddingConfig:
     """
     Reference - https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-marengo.html
@@ -115,23 +136,9 @@ class TwelveLabsMarengoEmbeddingConfig:
         self.is_marengo_3: Final = is_marengo_3_model(model)
 
     def get_supported_openai_params(self) -> list[str]:
-        return [
-            "encoding_format",
-            "textTruncate",
-            "embeddingOption",
-            "startSec",
-            "lengthSec",
-            "useFixedLengthSec",
-            "minClipSec",
-            "input_type",
-            "endSec",
-            "segmentation",
-            "embeddingType",
-            "embeddingScope",
-            "inferenceId",
-            "media_source",
-            "media_sources",
-        ]
+        if self.is_marengo_3:
+            return list(MARENGO_SHARED_PARAMS)
+        return [*MARENGO_SHARED_PARAMS, *MARENGO_2_7_ONLY_PARAMS]
 
     def map_openai_params(self, non_default_params: dict, optional_params: dict) -> dict:
         for k, v in non_default_params.items():
@@ -179,6 +186,7 @@ class TwelveLabsMarengoEmbeddingConfig:
         async_invoke_route: bool = False,
         model_id: str | None = None,
         output_s3_uri: str | None = None,
+        drop_params: bool = False,
     ) -> TwelveLabsMarengoEmbeddingRequest | TwelveLabsMarengo3EmbeddingRequest | TwelveLabsAsyncInvokeRequest:
         """
         Transform OpenAI-style input to TwelveLabs Marengo format/async-invoke format.
@@ -203,7 +211,9 @@ class TwelveLabsMarengoEmbeddingConfig:
             )
 
         if self.is_marengo_3:
-            marengo_3_request: Final = build_marengo_3_request(input=input, inference_params=inference_params)
+            marengo_3_request: Final = build_marengo_3_request(
+                input=input, inference_params=inference_params, drop_params=drop_params
+            )
             if async_invoke_route and model_id:
                 return self._wrap_async_invoke_request(
                     model_input=marengo_3_request, model_id=model_id, output_s3_uri=output_s3_uri
diff --git a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
index 0bf86352a5e..5033256d089 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
@@ -2,13 +2,16 @@ import json
 
 import pytest
 
+import litellm
 from litellm.llms.bedrock.common_utils import BedrockError
 from litellm.llms.bedrock.embed.twelvelabs_marengo_3_transformation import (
+    MARENGO_2_7_ONLY_PARAMS,
     build_marengo_3_request,
     is_marengo_3_model,
 )
 from litellm.llms.bedrock.embed.twelvelabs_marengo_transformation import (
     TwelveLabsMarengoEmbeddingConfig,
+    drop_params_enabled,
 )
 
 MARENGO_3_BASE = "twelvelabs.marengo-embed-3-0-v1:0"
@@ -27,6 +30,7 @@ OUTPUT_S3_URI = "s3://out-bucket/marengo/"
         ("async_invoke/twelvelabs.marengo-embed-3-0-v1:0", True),
         (MARENGO_27_US, False),
         ("twelvelabs.marengo-embed-2-7-v1:0", False),
+        ("twelvelabs.marengo-embed-30-v1:0", False),
         (None, False),
     ],
 )
@@ -266,3 +270,89 @@ def test_marengo_3_only_params_are_forwarded_by_map_openai_params():
         "embeddingScope": ["clip"],
         "inferenceId": "req-1",
     }
+
+
+@pytest.mark.parametrize(
+    "params,problem",
+    [
+        (
+            {"input_type": "clip"},
+            "input_type: Input should be 'text', 'image', 'video', 'audio', 'text_image' or 'multi_input'",
+        ),
+        ({"input_type": "video", "embeddingOption": "visual"}, "embeddingOption: Input should be a valid tuple"),
+        (
+            {"input_type": "multi_input", "media_sources": ["not", "a", "mapping"]},
+            "media_sources: Input should be a valid dictionary",
+        ),
+    ],
+)
+def test_invalid_marengo_3_params_name_the_field_and_the_reason(params, problem):
+    with pytest.raises(BedrockError) as excinfo:
+        build_marengo_3_request("s3://media/clip.mp4", params)
+    assert excinfo.value.message == f"Invalid Marengo 3.0 parameters: {problem}"
+
+
+MARENGO_2_7_ONLY_VALUES = {"textTruncate": "end", "lengthSec": 5, "useFixedLengthSec": True, "minClipSec": 2}
+
+
+@pytest.mark.parametrize("name", MARENGO_2_7_ONLY_PARAMS)
+def test_marengo_2_7_only_params_are_rejected_on_3_0_unless_dropped(name):
+    params = {"input_type": "text", name: MARENGO_2_7_ONLY_VALUES[name]}
+    with pytest.raises(BedrockError) as excinfo:
+        build_marengo_3_request("hello", params)
+    assert excinfo.value.status_code == 400
+    assert excinfo.value.message == (
+        f"Marengo 3.0 does not accept the Marengo 2.7 parameters {name}; set drop_params to drop them"
+    )
+    assert build_marengo_3_request("hello", params, drop_params=True) == {
+        "inputType": "text",
+        "text": {"inputText": "hello"},
+    }
+
+
+def test_marengo_2_7_only_params_are_advertised_only_for_2_7():
+    marengo_3 = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_US).get_supported_openai_params()
+    marengo_27 = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_27_US).get_supported_openai_params()
+    assert set(MARENGO_2_7_ONLY_PARAMS).isdisjoint(marengo_3)
+    assert set(MARENGO_2_7_ONLY_PARAMS) <= set(marengo_27)
+    assert set(marengo_3) <= set(marengo_27)
+
+
+def test_drop_params_comes_from_the_call_or_the_global(monkeypatch):
+    monkeypatch.setattr(litellm, "drop_params", False)
+    assert drop_params_enabled({}) is False
+    assert drop_params_enabled({"drop_params": True}) is True
+    monkeypatch.setattr(litellm, "drop_params", True)
+    assert drop_params_enabled({}) is True
+
+
+def test_config_drops_marengo_2_7_only_params_only_when_asked():
+    config = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_US)
+    with pytest.raises(BedrockError, match=r"Marengo 2\.7 parameters textTruncate"):
+        config._transform_request("hello", {"textTruncate": "end"})
+    assert config._transform_request("hello", {"textTruncate": "end"}, drop_params=True) == {
+        "inputType": "text",
+        "text": {"inputText": "hello"},
+    }
+
+
+@pytest.mark.parametrize(
+    "params",
+    [
+        {"input_type": "text"},
+        {"input_type": "image"},
+        {"input_type": "text_image", "media_source": DUCK_DATA_URL},
+        {"input_type": "multi_input", "media_sources": {"bird": DUCK_DATA_URL}},
+    ],
+)
+def test_timed_media_options_are_rejected_on_untimed_input_types_unless_dropped(params):
+    timed = {**params, "startSec": 0, "embeddingOption": ["visual"]}
+    with pytest.raises(BedrockError) as excinfo:
+        build_marengo_3_request(DUCK_DATA_URL, timed)
+    assert excinfo.value.status_code == 400
+    assert excinfo.value.message == (
+        f"Input type '{params['input_type']}' does not accept startSec, embeddingOption; set drop_params to drop them"
+    )
+    assert build_marengo_3_request(DUCK_DATA_URL, timed, drop_params=True) == build_marengo_3_request(
+        DUCK_DATA_URL, params
+    )

From a601c00afdc5ddda50cb7552aef0dc5f3d9dcf0c Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:47:25 -0700
Subject: [PATCH 10/31] fix(bedrock): pass litellm_params into the Bedrock
 embedding call so drop_params reaches Marengo 3.0

---
 litellm/main.py                               |  2 +-
 ...est_twelvelabs_marengo_3_transformation.py | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/litellm/main.py b/litellm/main.py
index 75b7f7f10a5..56f9cb2c0d0 100644
--- a/litellm/main.py
+++ b/litellm/main.py
@@ -6545,7 +6545,7 @@ def embedding(
                 client=client,
                 timeout=timeout,
                 aembedding=aembedding,
-                litellm_params={},
+                litellm_params=litellm_params_dict,
                 api_base=api_base,
                 print_verbose=print_verbose,
                 extra_headers=headers,
diff --git a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
index 5033256d089..d8d29cac35e 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
@@ -1,9 +1,11 @@
 import json
+from unittest.mock import Mock, patch
 
 import pytest
 
 import litellm
 from litellm.llms.bedrock.common_utils import BedrockError
+from litellm.llms.custom_httpx.http_handler import HTTPHandler
 from litellm.llms.bedrock.embed.twelvelabs_marengo_3_transformation import (
     MARENGO_2_7_ONLY_PARAMS,
     build_marengo_3_request,
@@ -356,3 +358,35 @@ def test_timed_media_options_are_rejected_on_untimed_input_types_unless_dropped(
     assert build_marengo_3_request(DUCK_DATA_URL, timed, drop_params=True) == build_marengo_3_request(
         DUCK_DATA_URL, params
     )
+
+
+def _embed_marengo_3_us(client: HTTPHandler, **params: object):
+    return litellm.embedding(
+        model=f"bedrock/{MARENGO_3_US}",
+        input="hello",
+        client=client,
+        aws_region_name="us-east-1",
+        aws_bedrock_runtime_endpoint="https://bedrock-runtime.us-east-1.amazonaws.com",
+        api_key="test-bearer-token",
+        **params,
+    )
+
+
+def test_per_request_drop_params_reaches_the_marengo_3_builder(monkeypatch):
+    monkeypatch.setattr(litellm, "drop_params", False)
+    client = HTTPHandler()
+    with patch.object(client, "post") as mock_post:
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.text = json.dumps({"data": [{"embedding": [0.1, 0.2]}]})
+        mock_response.json = lambda: json.loads(mock_response.text)
+        mock_post.return_value = mock_response
+
+        with pytest.raises(litellm.BadRequestError, match=r"Marengo 2\.7 parameters textTruncate"):
+            _embed_marengo_3_us(client, textTruncate="end")
+        assert mock_post.call_count == 0
+
+        response = _embed_marengo_3_us(client, textTruncate="end", drop_params=True)
+
+    assert response.data[0]["embedding"] == [0.1, 0.2]
+    assert json.loads(mock_post.call_args.kwargs["data"]) == {"inputType": "text", "text": {"inputText": "hello"}}

From 6076e9f61103f9f8054b8dfaa00539e47fc9163f Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 7 Sep 2026 18:54:31 -0700
Subject: [PATCH 11/31] chore(cost_calc): drop the query count section label
 comment

---
 litellm/litellm_core_utils/llm_cost_calc/utils.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/litellm/litellm_core_utils/llm_cost_calc/utils.py b/litellm/litellm_core_utils/llm_cost_calc/utils.py
index 46574ebae3f..c05d4c29a5e 100644
--- a/litellm/litellm_core_utils/llm_cost_calc/utils.py
+++ b/litellm/litellm_core_utils/llm_cost_calc/utils.py
@@ -981,7 +981,6 @@ def _calculate_input_cost(
             prompt_tokens_details["audio_length_seconds"],
         )
 
-    ### QUERY COUNT COST
     if prompt_tokens_details["query_count"]:
         prompt_cost += calculate_cost_component(
             model_info, "input_cost_per_query", prompt_tokens_details["query_count"]

From 5c037299f413c38609cbb7f5a582662e44b197d4 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Mon, 7 Sep 2026 23:02:27 -0700
Subject: [PATCH 12/31] feat: move MongoDB vector search to an optional sidecar

---
 .github/workflows/_test-unit-base.yml         |    2 +-
 Dockerfile                                    |    2 -
 docker/Dockerfile.database                    |    2 -
 docker/Dockerfile.non_root                    |    3 -
 gateway/Dockerfile                            |    2 -
 .../base_llm/vector_store/transformation.py   |    3 +
 litellm/llms/custom_httpx/llm_http_handler.py |   17 +-
 litellm/llms/mongodb/common_utils.py          |  303 ---
 .../mongodb/vector_stores/transformation.py   |  449 ++---
 pyproject.toml                                |    1 -
 .../test_mongodb_transformation.py            | 1691 ++---------------
 .../_components/VectorStoreForm.test.tsx      |   12 +-
 .../_components/VectorStoreForm.tsx           |    4 +-
 .../vector_store_providers.test.tsx           |   11 +-
 .../src/components/vector_store_providers.tsx |   27 +-
 uv.lock                                       |   79 +-
 16 files changed, 412 insertions(+), 2196 deletions(-)
 delete mode 100644 litellm/llms/mongodb/common_utils.py

diff --git a/.github/workflows/_test-unit-base.yml b/.github/workflows/_test-unit-base.yml
index 75b0f93fd77..62790e23143 100644
--- a/.github/workflows/_test-unit-base.yml
+++ b/.github/workflows/_test-unit-base.yml
@@ -113,7 +113,7 @@ jobs:
         if: steps.changes.outputs.decision != 'skip'
         timeout-minutes: 8
         run: |
-          .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router --extra saml --extra mongodb
+          .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router --extra saml
           uv run --no-sync python -c 'import os, sys; print(sys.version); assert f"{sys.version_info.major}.{sys.version_info.minor}" == os.environ["UV_PYTHON"]'
 
       - name: Cache Prisma binaries
diff --git a/Dockerfile b/Dockerfile
index 1648ec69d13..0a92aa9a68c 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -67,7 +67,6 @@ RUN uv sync --frozen --no-install-project --no-install-workspace --no-default-gr
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
-    --extra mongodb \
     --python python3.13
 
 # Copy full source tree
@@ -90,7 +89,6 @@ RUN uv sync --frozen --no-default-groups --no-editable \
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
-    --extra mongodb \
     --python python3.13
 
 RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/opt/prisma/binaries \
diff --git a/docker/Dockerfile.database b/docker/Dockerfile.database
index cc81ad6b3d3..e9ad2849bb2 100644
--- a/docker/Dockerfile.database
+++ b/docker/Dockerfile.database
@@ -65,7 +65,6 @@ RUN uv sync --frozen --no-install-project --no-install-workspace --no-default-gr
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
-    --extra mongodb \
     --python python3.13
 
 # Copy full source tree
@@ -88,7 +87,6 @@ RUN uv sync --frozen --no-default-groups --no-editable \
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
-    --extra mongodb \
     --python python3.13
 
 RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/opt/prisma/binaries \
diff --git a/docker/Dockerfile.non_root b/docker/Dockerfile.non_root
index 358425af901..edf20e8bbff 100644
--- a/docker/Dockerfile.non_root
+++ b/docker/Dockerfile.non_root
@@ -71,7 +71,6 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
     --extra semantic-router \
     --extra saml \
     --extra bedrock-realtime \
-    --extra mongodb \
     --python python3.13
 
 # Copy full source tree
@@ -100,7 +99,6 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
         --extra semantic-router \
         --extra saml \
         --extra bedrock-realtime \
-        --extra mongodb \
         --python python3.13 \
         --no-sources-package litellm-proxy-extras; \
     else \
@@ -111,7 +109,6 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
         --extra semantic-router \
         --extra saml \
         --extra bedrock-realtime \
-        --extra mongodb \
         --python python3.13; \
     fi
 
diff --git a/gateway/Dockerfile b/gateway/Dockerfile
index e42e488d57f..308d70a6b26 100644
--- a/gateway/Dockerfile
+++ b/gateway/Dockerfile
@@ -47,7 +47,6 @@ RUN --mount=type=cache,target=/root/.cache/uv \
         --extra extra_proxy \
         --extra semantic-router \
         --extra bedrock-realtime \
-        --extra mongodb \
         --python python3.13
 
 # Stage 2 — copy source and install the project + workspace members.
@@ -60,7 +59,6 @@ RUN --mount=type=cache,target=/root/.cache/uv \
         --extra extra_proxy \
         --extra semantic-router \
         --extra bedrock-realtime \
-        --extra mongodb \
         --python python3.13
 
 RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/opt/prisma/binaries \
diff --git a/litellm/llms/base_llm/vector_store/transformation.py b/litellm/llms/base_llm/vector_store/transformation.py
index c8d2b7fe522..07b60cb4b72 100644
--- a/litellm/llms/base_llm/vector_store/transformation.py
+++ b/litellm/llms/base_llm/vector_store/transformation.py
@@ -121,6 +121,9 @@ class RouterVectorStoreEmbeddingExecutor:
 
 
 class BaseVectorStoreConfig:
+    def validate_create_vector_store(self) -> None:
+        return None
+
     def get_supported_openai_params(self, model: str) -> list[VECTOR_STORE_OPENAI_PARAMS]:
         return []
 
diff --git a/litellm/llms/custom_httpx/llm_http_handler.py b/litellm/llms/custom_httpx/llm_http_handler.py
index 2f561809940..1dc4b198890 100644
--- a/litellm/llms/custom_httpx/llm_http_handler.py
+++ b/litellm/llms/custom_httpx/llm_http_handler.py
@@ -9814,7 +9814,7 @@ class BaseLLMHTTPHandler:
                 vector_store_search_optional_params=vector_store_search_optional_params,
                 api_base=api_base,
                 litellm_logging_obj=logging_obj,
-                litellm_params=dict(litellm_params),
+                litellm_params={**dict(litellm_params), "timeout": timeout},
                 extra_body=extra_body,
                 embedding_executor=embedding_executor,
             )
@@ -9859,6 +9859,10 @@ class BaseLLMHTTPHandler:
                 data=request_data,
                 timeout=timeout,
             )
+        except httpx.TimeoutException:
+            raise vector_store_provider_config.get_error_class(
+                error_message="Vector store search exceeded the caller timeout.", status_code=408, headers={}
+            ) from None
         except Exception as e:
             raise self._handle_error(e=e, provider_config=vector_store_provider_config)
 
@@ -9943,7 +9947,7 @@ class BaseLLMHTTPHandler:
                 vector_store_search_optional_params=vector_store_search_optional_params,
                 api_base=api_base,
                 litellm_logging_obj=logging_obj,
-                litellm_params=dict(litellm_params),
+                litellm_params={**dict(litellm_params), "timeout": timeout},
                 extra_body=extra_body,
                 embedding_executor=embedding_executor,
             )
@@ -9988,7 +9992,12 @@ class BaseLLMHTTPHandler:
                 url=url,
                 headers=headers,
                 data=request_data,
+                timeout=timeout,
             )
+        except httpx.TimeoutException:
+            raise vector_store_provider_config.get_error_class(
+                error_message="Vector store search exceeded the caller timeout.", status_code=408, headers={}
+            ) from None
         except Exception as e:
             raise self._handle_error(e=e, provider_config=vector_store_provider_config)
 
@@ -10018,6 +10027,8 @@ class BaseLLMHTTPHandler:
         else:
             async_httpx_client = client
 
+        vector_store_provider_config.validate_create_vector_store()
+
         headers: Final = vector_store_provider_config.validate_environment(
             headers=extra_headers or {}, litellm_params=litellm_params
         )
@@ -10088,6 +10099,8 @@ class BaseLLMHTTPHandler:
         else:
             sync_httpx_client = client
 
+        vector_store_provider_config.validate_create_vector_store()
+
         headers: Final = vector_store_provider_config.validate_environment(
             headers=extra_headers or {}, litellm_params=litellm_params
         )
diff --git a/litellm/llms/mongodb/common_utils.py b/litellm/llms/mongodb/common_utils.py
deleted file mode 100644
index 02c0b359407..00000000000
--- a/litellm/llms/mongodb/common_utils.py
+++ /dev/null
@@ -1,303 +0,0 @@
-"""Shared helpers for the MongoDB integrations. pymongo lives in the optional ``mongodb`` extra,
-so every import of it is deferred to call time."""
-
-import asyncio
-import threading
-import weakref
-from asyncio import AbstractEventLoop
-from collections import OrderedDict
-from collections.abc import Callable, Mapping
-from dataclasses import dataclass
-from types import MappingProxyType
-from typing import TYPE_CHECKING, Final, TypeAlias, TypeVar
-
-from litellm.exceptions import BadRequestError, ServiceUnavailableError, Timeout
-
-if TYPE_CHECKING:
-    from pymongo import AsyncMongoClient, MongoClient
-
-PYMONGO_INSTALL_HINT: Final = (
-    "The MongoDB vector store requires the 'pymongo' package. "
-    "Run 'pip install litellm[mongodb]' (or 'pip install pymongo') to install it."
-)
-
-MONGODB_PROVIDER: Final = "mongodb"
-
-
-def config_error(message: str) -> BadRequestError:
-    """400 rather than the 500 a bare ValueError becomes once litellm.exception_type wraps it."""
-    return BadRequestError(message=message, model=None, llm_provider=MONGODB_PROVIDER)
-
-
-def timeout_error(message: str) -> Timeout:
-    return Timeout(message=message, model=None, llm_provider=MONGODB_PROVIDER)
-
-
-def unavailable_error(message: str) -> ServiceUnavailableError:
-    """litellm only retries 408, 409, 429 and 5xx, so a 400 here would make a failover permanent."""
-    return ServiceUnavailableError(message=message, model=None, llm_provider=MONGODB_PROVIDER)
-
-
-DEFAULT_CONNECT_TIMEOUT_MS: Final = 10_000
-DEFAULT_SOCKET_TIMEOUT_MS: Final = 30_000
-DEFAULT_SERVER_SELECTION_TIMEOUT_MS: Final = 10_000
-
-_MAX_CACHED_CLIENTS: Final = 32
-
-_APP_NAME: Final = "litellm"
-
-
-@dataclass(frozen=True, slots=True)
-class MongoClientKey:
-    connection_string: str
-    connect_timeout_ms: int
-    socket_timeout_ms: int
-    server_selection_timeout_ms: int
-
-
-SyncClientFactory: TypeAlias = Callable[..., "MongoClient"]
-AsyncClientFactory: TypeAlias = Callable[..., "AsyncMongoClient"]
-
-_K = TypeVar("_K")
-_V = TypeVar("_V")
-
-_AsyncClientCacheKey: TypeAlias = tuple[MongoClientKey, int]
-# CPython recycles id() aggressively, so the id alone would hand a new loop a closed loop's client
-_AsyncClientEntry: TypeAlias = tuple["weakref.ref[AbstractEventLoop]", "AsyncMongoClient"]
-
-_SyncClientCache: TypeAlias = "OrderedDict[MongoClientKey, MongoClient]"
-_AsyncClientCache: TypeAlias = "OrderedDict[_AsyncClientCacheKey, _AsyncClientEntry]"
-
-_sync_clients: Final[_SyncClientCache] = OrderedDict()  # mutable-ok: process-level client cache
-_async_clients: Final[_AsyncClientCache] = OrderedDict()  # mutable-ok: same cache, per loop
-# async searches reach the sync client through executor threads, so both caches are shared state
-_cache_lock: Final = threading.Lock()
-
-
-def _store_bounded(cache: "OrderedDict[_K, _V]", cache_key: "_K", value: "_V") -> None:
-    """Eviction only drops this cache's reference; an in-flight search keeps its client alive."""
-    with _cache_lock:
-        cache[cache_key] = value  # mutable-ok: an LRU cache is mutable state by definition
-        cache.move_to_end(cache_key)
-        while len(cache) > _MAX_CACHED_CLIENTS:
-            cache.popitem(last=False)
-
-
-def _mark_used(cache: "OrderedDict[_K, _V]", cache_key: "_K") -> None:
-    with _cache_lock:
-        if cache_key in cache:
-            cache.move_to_end(cache_key)
-
-
-def import_sync_mongo_client() -> "type[MongoClient]":
-    try:
-        from pymongo import MongoClient as SyncMongoClient
-    except ImportError as e:
-        raise config_error(PYMONGO_INSTALL_HINT) from e
-    return SyncMongoClient
-
-
-def import_async_mongo_client() -> "type[AsyncMongoClient]":
-    try:
-        from pymongo import AsyncMongoClient as AsyncMongoClientClass
-    except ImportError as e:
-        raise config_error(PYMONGO_INSTALL_HINT) from e
-    return AsyncMongoClientClass
-
-
-def _client_kwargs(key: MongoClientKey) -> Mapping[str, object]:
-    return MappingProxyType(
-        {
-            "connectTimeoutMS": key.connect_timeout_ms,
-            "socketTimeoutMS": key.socket_timeout_ms,
-            "serverSelectionTimeoutMS": key.server_selection_timeout_ms,
-            "appname": _APP_NAME,
-        }
-    )
-
-
-def get_sync_client(key: MongoClientKey, client_class: SyncClientFactory | None = None) -> "MongoClient":
-    cached: Final = _sync_clients.get(key)
-    if cached is not None:
-        _mark_used(_sync_clients, key)
-        return cached
-    build: Final = client_class if client_class is not None else import_sync_mongo_client()
-    client: Final = build(key.connection_string, **_client_kwargs(key))
-    _store_bounded(_sync_clients, key, client)
-    return client
-
-
-def _purge_dead_loops() -> None:
-    """A cached client holds its loop alive, so a closed loop's entry would pin that client and its
-    sockets for the life of the process."""
-    with _cache_lock:
-        for stale in tuple(
-            cache_key
-            for cache_key, (loop_ref, _) in _async_clients.items()
-            if (cached_loop := loop_ref()) is None or cached_loop.is_closed()
-        ):
-            del _async_clients[stale]
-
-
-def get_async_client(key: MongoClientKey, client_class: AsyncClientFactory | None = None) -> "AsyncMongoClient":
-    """Async clients bind to the loop that created them, so the cache is keyed per loop."""
-    loop: Final = asyncio.get_running_loop()
-    loop_key: Final = (key, id(loop))
-    cached: Final = _async_clients.get(loop_key)
-    if cached is not None and cached[0]() is loop:
-        _mark_used(_async_clients, loop_key)
-        return cached[1]
-    _purge_dead_loops()
-    build: Final = client_class if client_class is not None else import_async_mongo_client()
-    client: Final = build(key.connection_string, **_client_kwargs(key))
-    _store_bounded(_async_clients, loop_key, (weakref.ref(loop), client))
-    return client
-
-
-def reset_client_cache() -> None:
-    with _cache_lock:
-        _sync_clients.clear()
-        _async_clients.clear()
-
-
-_AUTHENTICATION_FAILED_CODE: Final = 18
-_UNAUTHORIZED_CODE: Final = 13
-# Atlas reports a rejected user as code 8000 "AtlasError" where a self-managed mongod reports 18
-_AUTHENTICATION_MESSAGE_MARKERS: Final = ("bad auth", "authentication failed", "not authorized")
-_RESOLUTION_TIMEOUT_MARKERS: Final = ("resolution lifetime expired", "dns operation timed out")
-_UNKNOWN_HOSTNAME_MARKERS: Final = ("dns query name does not exist", "name or service not known")
-_CREDENTIAL_ESCAPING_MARKERS: Final = ("must be escaped according to rfc 3986", "bad database name")
-
-
-def _index_hint(index_name: str, database: str, collection: str) -> str:
-    return (
-        f"No queryable MongoDB Vector Search index named '{index_name}' was found on "
-        f"'{database}.{collection}'. Confirm the index exists on that exact collection, that its "
-        "status is READY rather than still building, and that the vector store id matches the index name."
-    )
-
-
-def missing_index_error(index_name: str, database: str, collection: str) -> BadRequestError:
-    """$vectorSearch against a missing index, database or collection returns zero documents rather
-    than failing, so an empty result set is checked against the catalogue and reported as this."""
-    return config_error(
-        f"{_index_hint(index_name, database, collection)} A vector search against a database, "
-        "collection or index that does not exist returns no results rather than an error, so this "
-        "was reported as an empty result set by MongoDB."
-    )
-
-
-def index_not_ready_error(index_name: str, database: str, collection: str, status: str) -> BadRequestError:
-    return config_error(
-        f"The MongoDB Vector Search index '{index_name}' on '{database}.{collection}' is not queryable "
-        f"yet; its status is {status}. Searches against it return no results until the build finishes."
-    )
-
-
-def translate_mongo_error(error: Exception, index_name: str, database: str, collection: str) -> Exception:
-    """Returns the exception to raise, so callers keep the driver error as ``__cause__``."""
-    try:
-        from pymongo.errors import (
-            ConfigurationError,
-            ConnectionFailure,
-            ExecutionTimeout,
-            InvalidOperation,
-            NetworkTimeout,
-            OperationFailure,
-            ServerSelectionTimeoutError,
-        )
-    except ImportError:
-        return error
-
-    if isinstance(error, ServerSelectionTimeoutError):
-        return timeout_error(
-            "Could not reach the MongoDB deployment before the timeout. On Atlas this is usually the "
-            "project's IP access list not containing this host, or a paused cluster. On a self-managed "
-            "deployment it is usually the host or port in the URI, or a firewall between this process "
-            f"and mongod. Either way it can also be an unresolvable hostname. Driver detail: {error}"
-        )
-    # ExecutionTimeout subclasses OperationFailure, so it has to be matched before it
-    if isinstance(error, (NetworkTimeout, ExecutionTimeout)):
-        return timeout_error(
-            f"The MongoDB vector search against '{database}.{collection}' timed out before returning. "
-            f"Driver detail: {error}"
-        )
-    # ServerSelectionTimeoutError and NetworkTimeout also subclass ConnectionFailure, so this only
-    # sees what those branches left
-    if isinstance(error, ConnectionFailure):
-        return unavailable_error(
-            f"The connection to '{database}.{collection}' was dropped or refused. That is usually a "
-            "replica set failover or a restarted node, so the search is worth retrying. If it keeps "
-            "happening: on Atlas the usual cause is a connection string with no username and password, "
-            "or a TLS failure, so confirm the URI is the one Atlas shows under Connect, Drivers; on a "
-            "self-managed deployment, check that mongod is listening on the host and port in the URI. "
-            f"Driver detail: {error}"
-        )
-    if isinstance(error, OperationFailure):
-        code: Final = error.code
-        detail: Final = str(error).lower()
-        if code in (_AUTHENTICATION_FAILED_CODE, _UNAUTHORIZED_CODE) or any(
-            marker in detail for marker in _AUTHENTICATION_MESSAGE_MARKERS
-        ):
-            return config_error(
-                "MongoDB rejected the credentials in mongodb_connection_string, or the database user "
-                f"lacks read access to '{database}.{collection}'. Driver detail: {error.details}"
-            )
-        if "dimension" in detail:
-            return config_error(
-                "The query embedding does not match the vector dimensions the index was built for. "
-                "litellm_embedding_model must be the same model that produced the stored vectors. "
-                f"Driver detail: {error}"
-            )
-        if "is not indexed as vector" in detail:
-            return config_error(
-                "mongodb_embedding_field names a field the MongoDB Vector Search index does not cover. "
-                f"It must match the 'path' the index '{index_name}' was created on. Driver detail: {error}"
-            )
-        if "index" in detail and ("not found" in detail or "does not exist" in detail or "unknown" in detail):
-            return config_error(f"{_index_hint(index_name, database, collection)} Driver detail: {error}")
-        return config_error(
-            f"MongoDB rejected the vector search against '{database}.{collection}' using index "
-            f"'{index_name}'. Driver detail: {error}"
-        )
-    if isinstance(error, ConfigurationError):
-        configuration_detail: Final = str(error).lower()
-        if any(marker in configuration_detail for marker in _RESOLUTION_TIMEOUT_MARKERS):
-            return timeout_error(
-                "The DNS lookup for the cluster in mongodb_connection_string did not finish in time. "
-                "A mongodb+srv:// URI needs an SRV lookup before any connection is attempted, so this "
-                f"is DNS or the configured timeout, not MongoDB. Driver detail: {error}"
-            )
-        if any(marker in configuration_detail for marker in _UNKNOWN_HOSTNAME_MARKERS):
-            return config_error(
-                "The hostname in mongodb_connection_string does not exist in DNS. On Atlas, check the "
-                "cluster name against the URI shown under Connect, Drivers. On a self-managed deployment, "
-                f"check that the hostname resolves from this process. Driver detail: {error}"
-            )
-        if any(marker in configuration_detail for marker in _CREDENTIAL_ESCAPING_MARKERS):
-            return config_error(
-                "mongodb_connection_string could not be parsed. A username or password containing "
-                "'@', '/', ':' or '%' has to be percent-encoded per RFC 3986, so 'p@ss/word' becomes "
-                "'p%40ss%2Fword'. If the credentials are already encoded, check the database name in "
-                f"the URI path instead. Driver detail: {error}"
-            )
-        return config_error(
-            f"mongodb_connection_string is not a usable MongoDB connection string. Driver detail: {error}"
-        )
-    if isinstance(error, InvalidOperation):
-        return config_error(f"The MongoDB client was already closed or is unusable. Driver detail: {error}")
-    # An unreadable tlsCAFile or tlsCertificateKeyFile raises OSError, not a PyMongoError
-    if isinstance(error, OSError) and error.filename:
-        return config_error(
-            f"'{error.filename}', named by a TLS option in mongodb_connection_string, could not be read. "
-            "Check that tlsCAFile and tlsCertificateKeyFile point at files this process can open; inside "
-            f"a container that is the path in the container, not on the host. Driver detail: {error}"
-        )
-    # pymongo raises a plain ValueError, not a PyMongoError, for an unusable port
-    if isinstance(error, ValueError):
-        return config_error(
-            "The host and port in mongodb_connection_string could not be parsed. If the port is a "
-            "number between 0 and 65535, the cause is usually an unescaped ':' in the password, which "
-            f"has to be percent-encoded per RFC 3986 as '%3A'. Driver detail: {error}"
-        )
-    return error
diff --git a/litellm/llms/mongodb/vector_stores/transformation.py b/litellm/llms/mongodb/vector_stores/transformation.py
index 3382c931c96..92965ab745b 100644
--- a/litellm/llms/mongodb/vector_stores/transformation.py
+++ b/litellm/llms/mongodb/vector_stores/transformation.py
@@ -1,37 +1,28 @@
-"""MongoDB Vector Search has no HTTP query API, so this is a direct provider that runs the
-``$vectorSearch`` aggregation through pymongo. ``vector_store_id`` is the search index name."""
-
-from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Mapping, Sequence
+from math import isfinite
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Final, NoReturn
+from typing import TYPE_CHECKING, Final, Literal, NoReturn
+from urllib.parse import quote, urlsplit
 
 import httpx
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
 
+from litellm.exceptions import AuthenticationError, BadRequestError, ServiceUnavailableError, Timeout
+from litellm.llms.base_llm.chat.transformation import BaseLLMException
 from litellm.llms.base_llm.vector_store.transformation import (
-    BaseDirectVectorStoreConfig,
+    BaseQueryEmbeddingVectorStoreConfig,
     LiteLLMVectorStoreEmbeddingExecutor,
     VectorStoreEmbeddingExecutor,
 )
-from litellm.llms.mongodb.common_utils import (
-    DEFAULT_CONNECT_TIMEOUT_MS,
-    DEFAULT_SERVER_SELECTION_TIMEOUT_MS,
-    DEFAULT_SOCKET_TIMEOUT_MS,
-    MongoClientKey,
-    config_error,
-    get_async_client,
-    get_sync_client,
-    index_not_ready_error,
-    missing_index_error,
-    translate_mongo_error,
-)
+from litellm.secret_managers.main import get_secret_str
+from litellm.types.router import GenericLiteLLMParams
 from litellm.types.utils import EmbeddingResponse
 from litellm.types.vector_stores import (
+    BaseVectorStoreAuthCredentials,
     VectorStoreCreateOptionalRequestParams,
-    VectorStoreResultContent,
+    VectorStoreIndexEndpoints,
     VectorStoreSearchOptionalRequestParams,
     VectorStoreSearchResponse,
-    VectorStoreSearchResult,
 )
 
 if TYPE_CHECKING:
@@ -39,26 +30,45 @@ if TYPE_CHECKING:
 
 DEFAULT_EMBEDDING_FIELD_NAME: Final = "embedding"
 DEFAULT_TEXT_FIELD_NAME: Final = "text"
-SCORE_FIELD_NAME: Final = "score"
-
 DEFAULT_MAX_NUM_RESULTS: Final = 10
 MIN_MAX_NUM_RESULTS: Final = 1
 MAX_MAX_NUM_RESULTS: Final = 50
-
 NUM_CANDIDATES_MULTIPLIER: Final = 10
 MIN_NUM_CANDIDATES: Final = 100
 MAX_NUM_CANDIDATES: Final = 10_000
-
 MAX_QUERY_CHARACTERS: Final = 32_000
-
 _EMPTY_EMBEDDING_CONFIG: Final = MappingProxyType({})
-
 _SEARCH_ONLY_MESSAGE: Final = (
     "MongoDB vector store is search-only. Create the collection and its MongoDB Vector Search "
     "index in MongoDB directly, then register it here by index name."
 )
 
 
+def config_error(message: str) -> BadRequestError:
+    return BadRequestError(message=message, model=None, llm_provider="mongodb")
+
+
+class _Content(BaseModel):
+    model_config = ConfigDict(frozen=True, strict=True)
+    type: Literal["text"]
+    text: str
+
+
+class _Result(BaseModel):
+    model_config = ConfigDict(frozen=True, strict=True, allow_inf_nan=False)
+    score: float | None
+    content: list[_Content]
+    file_id: str | None
+    filename: str | None
+
+
+class _SearchResponse(BaseModel):
+    model_config = ConfigDict(frozen=True, strict=True)
+    object: Literal["vector_store.search_results.page"]
+    search_query: str
+    data: list[_Result]
+
+
 class _MongoDBSearchParams(BaseModel):
     """Typed view over the vector store's litellm_params; unrelated keys are ignored."""
 
@@ -66,7 +76,6 @@ class _MongoDBSearchParams(BaseModel):
 
     litellm_embedding_model: str | None = None
     litellm_embedding_config: Mapping[str, object] | None = None
-    mongodb_connection_string: str | None = None
     mongodb_database: str | None = None
     mongodb_collection: str | None = None
     mongodb_text_field: str | None = None
@@ -91,21 +100,6 @@ class _MongoDBSearchParams(BaseModel):
             )
         return self.litellm_embedding_model
 
-    def require_connection_string(self) -> str:
-        if not self.mongodb_connection_string:
-            raise config_error(
-                "mongodb_connection_string is required in litellm_params for the MongoDB vector store. "
-                "Example: mongodb+srv://<user>:<password>@<cluster>.mongodb.net for Atlas, or "
-                "mongodb://<user>:<password>@<host>:27017 for a self-managed deployment"
-            )
-        scheme: Final = self.mongodb_connection_string.split("://", 1)[0].lower()
-        if scheme not in ("mongodb", "mongodb+srv"):
-            raise config_error(
-                "mongodb_connection_string must start with 'mongodb://' or 'mongodb+srv://', "
-                f"got '{self.mongodb_connection_string.split('://', 1)[0]}://'"
-            )
-        return self.mongodb_connection_string
-
     def require_database(self) -> str:
         if not self.mongodb_database:
             raise config_error(
@@ -127,30 +121,28 @@ _MONGODB_PARAM_PREFIX: Final = "mongodb_"
 _KNOWN_MONGODB_PARAMS: Final = frozenset(
     name for name in _MongoDBSearchParams.model_fields if name.startswith(_MONGODB_PARAM_PREFIX)
 )
+_RESPONSE_ADAPTER: Final = TypeAdapter(VectorStoreSearchResponse)
 
 
-class MongoDBVectorStoreConfig(BaseDirectVectorStoreConfig):
-    def __init__(
-        self,
-        embedding_executor: VectorStoreEmbeddingExecutor | None = None,
-        sync_client_factory: Callable[[MongoClientKey], object] | None = None,
-        async_client_factory: Callable[[MongoClientKey], object] | None = None,
-    ) -> None:
-        super().__init__()
-        self.embedding_executor: Final[VectorStoreEmbeddingExecutor] = (
-            embedding_executor if embedding_executor is not None else LiteLLMVectorStoreEmbeddingExecutor()
-        )
-        self.sync_client_factory: Final[Callable[[MongoClientKey], object]] = (
-            sync_client_factory if sync_client_factory is not None else get_sync_client
-        )
-        self.async_client_factory: Final[Callable[[MongoClientKey], object]] = (
-            async_client_factory if async_client_factory is not None else get_async_client
-        )
+class MongoDBVectorStoreConfig(BaseQueryEmbeddingVectorStoreConfig):
+    def __init__(self, embedding_executor: VectorStoreEmbeddingExecutor | None = None) -> None:
+        self.embedding_executor: Final = embedding_executor or LiteLLMVectorStoreEmbeddingExecutor()
+
+    def get_auth_credentials(self, litellm_params: Mapping[str, object]) -> BaseVectorStoreAuthCredentials:
+        return BaseVectorStoreAuthCredentials()
+
+    def get_vector_store_endpoints_by_type(self) -> VectorStoreIndexEndpoints:
+        return VectorStoreIndexEndpoints(read=[], write=[])  # mutable-ok: the TypedDict declares list fields
 
     @staticmethod
     def _reject_unknown_params(litellm_params: Mapping[str, object]) -> None:
         """Without this a mistyped mongodb_collection reads as 'mongodb_collection is required',
         naming a key the reader can see they have set."""
+        if litellm_params.get("mongodb_connection_string") is not None:
+            raise config_error(
+                "MongoDB vector stores now use the BETA sidecar. Move mongodb_connection_string to "
+                "MONGODB_CONNECTION_STRING in the sidecar, remove it from LiteLLM, and configure api_base and api_key."
+            )
         unknown: Final = sorted(
             key for key in litellm_params if key.startswith(_MONGODB_PARAM_PREFIX) and key not in _KNOWN_MONGODB_PARAMS
         )
@@ -191,239 +183,182 @@ class MongoDBVectorStoreConfig(BaseDirectVectorStoreConfig):
             return configured
         return min(max(limit * NUM_CANDIDATES_MULTIPLIER, MIN_NUM_CANDIDATES), MAX_NUM_CANDIDATES)
 
-    @staticmethod
-    def _timeout_ms(timeout: float | httpx.Timeout | None) -> tuple[int, int]:
-        """The connect and socket budgets pymongo is built with, in that order."""
-        if isinstance(timeout, httpx.Timeout):
-            return (
-                int((timeout.connect or DEFAULT_CONNECT_TIMEOUT_MS / 1000) * 1000),
-                int((timeout.read or DEFAULT_SOCKET_TIMEOUT_MS / 1000) * 1000),
+    def validate_environment(
+        self, headers: dict[str, object], litellm_params: GenericLiteLLMParams | None
+    ) -> dict[str, object]:
+        if litellm_params is None:
+            raise config_error("Configure api_base and api_key for the MongoDB BETA sidecar.")
+        self._reject_unknown_params(dict(litellm_params))
+        api_key: Final = litellm_params.api_key or get_secret_str("MONGODB_SIDECAR_API_KEY")
+        if not api_key:
+            raise config_error("MongoDB sidecar api_key is required. Set api_key or MONGODB_SIDECAR_API_KEY.")
+        return {**headers, "Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+
+    def get_complete_url(self, api_base: str | None, litellm_params: dict[str, object]) -> str:
+        if not api_base:
+            raise config_error("MongoDB sidecar api_base is required, for example http://mongodb-sidecar:8080.")
+        try:
+            parsed: Final = urlsplit(api_base)
+            valid: Final = parsed.scheme in ("http", "https") and bool(parsed.hostname) and parsed.port != 0
+        except ValueError:
+            raise config_error("MongoDB sidecar api_base must be a valid HTTP or HTTPS URL.") from None
+        if not valid or parsed.username or parsed.password or parsed.query or parsed.fragment:
+            raise config_error(
+                "MongoDB sidecar api_base must be an HTTP or HTTPS URL without credentials, query, or fragment."
             )
-        if timeout is None:
-            return DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_SOCKET_TIMEOUT_MS
-        return min(int(float(timeout) * 1000), DEFAULT_CONNECT_TIMEOUT_MS), int(float(timeout) * 1000)
+        return api_base.rstrip("/")
+
+    @staticmethod
+    def _timeout_ms(value: object) -> int:
+        seconds: Final = value.read if isinstance(value, httpx.Timeout) else value
+        if seconds is None:
+            return 30_000
+        if not isinstance(seconds, (int, float)) or not isfinite(seconds) or seconds <= 0:
+            raise config_error("MongoDB search timeout must be a positive finite number.")
+        return max(1, min(int(seconds * 1000), 30_000))
 
     @classmethod
-    def _client_key(cls, params: _MongoDBSearchParams, timeout: float | httpx.Timeout | None) -> MongoClientKey:
-        connect_ms, socket_ms = cls._timeout_ms(timeout)
-        return MongoClientKey(
-            connection_string=params.require_connection_string(),
-            connect_timeout_ms=connect_ms,
-            socket_timeout_ms=socket_ms,
-            server_selection_timeout_ms=min(connect_ms, DEFAULT_SERVER_SELECTION_TIMEOUT_MS),
-        )
+    def _params(
+        cls,
+        litellm_params: Mapping[str, object],
+        optional_params: VectorStoreSearchOptionalRequestParams,
+        extra_body: Mapping[str, object] | None,
+    ) -> _MongoDBSearchParams:
+        cls._reject_unknown_params(litellm_params)
+        if extra_body:
+            raise config_error("MongoDB vector store does not support extra_body overrides.")
+        for unsupported in ("filters", "ranking_options", "rewrite_query"):
+            if optional_params.get(unsupported) is not None:
+                raise config_error(f"MongoDB vector store does not support the {unsupported} parameter.")
+        try:
+            params: Final = _MongoDBSearchParams.model_validate(litellm_params)
+        except ValidationError:
+            raise config_error(
+                "Invalid MongoDB vector-store configuration. Check the database, collection, fields, and candidate count."
+            ) from None
+        params.require_database()
+        params.require_collection()
+        params.require_embedding_model()
+        cls._num_candidates(cls._limit(optional_params), params.mongodb_num_candidates)
+        cls._timeout_ms(litellm_params.get("timeout"))
+        return params
 
     @classmethod
-    def _pipeline(
+    def _request(
         cls,
         vector_store_id: str,
-        query_vector: Sequence[float],
+        query_text: str,
         params: _MongoDBSearchParams,
-        vector_store_search_optional_params: VectorStoreSearchOptionalRequestParams,
-    ) -> Sequence[Mapping[str, object]]:
-        if vector_store_search_optional_params.get("filters") is not None:
+        optional_params: VectorStoreSearchOptionalRequestParams,
+        api_base: str,
+        embedding_response: EmbeddingResponse,
+        timeout: object,
+    ) -> tuple[str, dict[str, object]]:
+        if not embedding_response.data:
             raise config_error(
-                "MongoDB vector store does not support the filters parameter yet. "
-                "Restrict the collection or the MongoDB Vector Search index definition instead."
+                "The embedding model returned no embedding for the search query. Check litellm_embedding_model."
             )
-        if vector_store_search_optional_params.get("ranking_options") is not None:
-            raise config_error(
-                "MongoDB vector store does not support the ranking_options parameter yet. "
-                "Every result already carries the vectorSearchScore, so filter or re-rank "
-                "on that rather than having the threshold silently ignored."
-            )
-        if vector_store_search_optional_params.get("rewrite_query") is not None:
-            raise config_error(
-                "MongoDB vector store does not support the rewrite_query parameter. The query is "
-                "embedded exactly as sent; rewrite it before calling if you need that."
-            )
-        limit: Final = cls._limit(vector_store_search_optional_params)
-        search: Final = MappingProxyType(
-            {
-                "index": vector_store_id,
-                "path": params.embedding_field,
-                "queryVector": tuple(query_vector),
-                "numCandidates": cls._num_candidates(limit, params.mongodb_num_candidates),
-                "limit": limit,
-            }
-        )
-        projection: Final = MappingProxyType(
-            {params.text_field: 1, SCORE_FIELD_NAME: MappingProxyType({"$meta": "vectorSearchScore"})}
-        )
-        return [  # mutable-ok: pymongo rejects any non-list pipeline in common.validate_list
-            MappingProxyType({"$vectorSearch": search}),
-            MappingProxyType({"$project": projection}),
-        ]
+        vector: Final = embedding_response.data[0]["embedding"]
+        if not vector or any(not isinstance(value, (float, int)) or not isfinite(value) for value in vector):
+            raise config_error("The embedding model must return a non-empty, finite query vector.")
+        limit: Final = cls._limit(optional_params)
+        return f"{api_base}/v1/vector_stores/{quote(vector_store_id, safe='')}/search", {
+            "query": query_text,
+            "query_vector": tuple(vector),
+            "mongodb_database": params.require_database(),
+            "mongodb_collection": params.require_collection(),
+            "mongodb_embedding_field": params.embedding_field,
+            "mongodb_text_field": params.text_field,
+            "mongodb_num_candidates": cls._num_candidates(limit, params.mongodb_num_candidates),
+            "max_num_results": limit,
+            "timeout_ms": cls._timeout_ms(timeout),
+        }
 
-    @classmethod
-    def _field_value(cls, document: Mapping[str, object], dotted_path: str) -> str | None:
-        """None means absent, which is what separates a mistyped field from genuinely empty text."""
-        head, _, rest = dotted_path.partition(".")
-        if head not in document:
-            return None
-        value: Final = document[head]
-        if not rest:
-            return None if value is None else str(value)
-        return cls._field_value(value, rest) if isinstance(value, Mapping) else None
-
-    @classmethod
-    def _to_result(cls, document: Mapping[str, object], text_field: str) -> VectorStoreSearchResult:
-        document_id: Final = document.get("_id")
-        identifier: Final = None if document_id is None else str(document_id)
-        content: Final = [  # mutable-ok: VectorStoreSearchResult declares a list of content parts
-            VectorStoreResultContent(text=cls._field_value(document, text_field) or "", type="text")
-        ]
-        raw_score: Final = document.get(SCORE_FIELD_NAME)
-        return VectorStoreSearchResult(
-            score=float(raw_score) if isinstance(raw_score, (int, float)) else None,
-            content=content,
-            file_id=identifier,
-            filename=identifier,
-        )
-
-    @classmethod
-    def _raise_for_missing_text_field(
-        cls, documents: Sequence[Mapping[str, object]], text_field: str, database: str, collection: str
-    ) -> None:
-        """$vectorSearch matches documents carrying no text, so a mistyped mongodb_text_field
-        returns well-scored results with empty content instead of failing."""
-        if documents and all(cls._field_value(document, text_field) is None for document in documents):
-            raise config_error(
-                f"None of the {len(documents)} matched documents in '{database}.{collection}' has a "
-                f"'{text_field}' field, so every result would carry empty text. Set mongodb_text_field "
-                "to the field holding the readable text; it accepts a dotted path such as metadata.body."
-            )
-
-    @classmethod
-    def _to_response(
-        cls, documents: Sequence[Mapping[str, object]], query_text: str, text_field: str
-    ) -> VectorStoreSearchResponse:
-        return VectorStoreSearchResponse(
-            object="vector_store.search_results.page",
-            search_query=query_text,
-            data=[  # mutable-ok: VectorStoreSearchResponse declares data as a list
-                cls._to_result(document, text_field) for document in documents
-            ],
-        )
-
-    @staticmethod
-    def _raise_for_unusable_index(
-        catalogue: Sequence[Mapping[str, object]], index_name: str, database: str, collection: str
-    ) -> None:
-        """mongod returns zero documents both for a query that matched nothing and for a missing
-        database, collection or index, so the catalogue decides which one happened."""
-        if not catalogue:
-            raise missing_index_error(index_name, database, collection)
-        entry: Final = catalogue[0]
-        if not entry.get("queryable"):
-            raise index_not_ready_error(index_name, database, collection, str(entry.get("status") or "unknown"))
-
-    @staticmethod
-    def _embedding_vector(embedding_response: EmbeddingResponse) -> Sequence[float]:
-        data: Final = embedding_response.data
-        if not data:
-            raise config_error(
-                "The embedding model returned no embedding for the search query, so there is nothing "
-                "to search MongoDB with. Check the embedding deployment named by litellm_embedding_model."
-            )
-        return data[0]["embedding"]
-
-    def execute_search_vector_store_request(
+    def transform_search_vector_store_request(
         self,
         vector_store_id: str,
         query: str | Sequence[str],
         vector_store_search_optional_params: VectorStoreSearchOptionalRequestParams,
+        api_base: str,
         litellm_logging_obj: "LiteLLMLoggingObj",
         litellm_params: Mapping[str, object],
+        extra_body: Mapping[str, object] | None = None,
         embedding_executor: VectorStoreEmbeddingExecutor | None = None,
-        timeout: float | httpx.Timeout | None = None,
-    ) -> VectorStoreSearchResponse:
-        self._reject_unknown_params(litellm_params)
-        params: Final = _MongoDBSearchParams.model_validate(litellm_params)
+    ) -> tuple[str, dict[str, object]]:
+        params: Final = self._params(litellm_params, vector_store_search_optional_params, extra_body)
         query_text: Final = self._query_text(query)
-        key: Final = self._client_key(params, timeout)
-        database: Final = params.require_database()
-        collection: Final = params.require_collection()
-
-        embedding_response: Final = (embedding_executor or self.embedding_executor).embed(
-            params.require_embedding_model(),
+        response: Final = (embedding_executor or self.embedding_executor).embed(
+            params.require_embedding_model(), query_text, params.litellm_embedding_config or _EMPTY_EMBEDDING_CONFIG
+        )
+        return self._request(
+            vector_store_id,
             query_text,
-            params.litellm_embedding_config or _EMPTY_EMBEDDING_CONFIG,
-        )
-        pipeline: Final = self._pipeline(
-            vector_store_id, self._embedding_vector(embedding_response), params, vector_store_search_optional_params
+            params,
+            vector_store_search_optional_params,
+            api_base,
+            response,
+            litellm_params.get("timeout"),
         )
 
-        try:
-            client: Final = self.sync_client_factory(key)
-            target: Final = client[database][collection]  # pyright: ignore[reportIndexIssue]  # factory is typed as returning object so injected doubles are accepted
-            documents: Final = tuple(target.aggregate(pipeline))
-        except Exception as e:
-            raise translate_mongo_error(e, index_name=vector_store_id, database=database, collection=collection) from e
-        if not documents:
-            try:
-                catalogue: Final = tuple(target.list_search_indexes(vector_store_id))
-            except Exception as e:
-                raise translate_mongo_error(
-                    e, index_name=vector_store_id, database=database, collection=collection
-                ) from e
-            self._raise_for_unusable_index(catalogue, vector_store_id, database, collection)
-        self._raise_for_missing_text_field(documents, params.text_field, database, collection)
-        return self._to_response(documents, query_text, params.text_field)
-
-    async def aexecute_search_vector_store_request(
+    async def atransform_search_vector_store_request(
         self,
         vector_store_id: str,
         query: str | Sequence[str],
         vector_store_search_optional_params: VectorStoreSearchOptionalRequestParams,
+        api_base: str,
         litellm_logging_obj: "LiteLLMLoggingObj",
         litellm_params: Mapping[str, object],
+        extra_body: Mapping[str, object] | None = None,
         embedding_executor: VectorStoreEmbeddingExecutor | None = None,
-        timeout: float | httpx.Timeout | None = None,
-    ) -> VectorStoreSearchResponse:
-        self._reject_unknown_params(litellm_params)
-        params: Final = _MongoDBSearchParams.model_validate(litellm_params)
+    ) -> tuple[str, dict[str, object]]:
+        params: Final = self._params(litellm_params, vector_store_search_optional_params, extra_body)
         query_text: Final = self._query_text(query)
-        key: Final = self._client_key(params, timeout)
-        database: Final = params.require_database()
-        collection: Final = params.require_collection()
-
-        embedding_response: Final = await (embedding_executor or self.embedding_executor).aembed(
-            params.require_embedding_model(),
+        response: Final = await (embedding_executor or self.embedding_executor).aembed(
+            params.require_embedding_model(), query_text, params.litellm_embedding_config or _EMPTY_EMBEDDING_CONFIG
+        )
+        return self._request(
+            vector_store_id,
             query_text,
-            params.litellm_embedding_config or _EMPTY_EMBEDDING_CONFIG,
-        )
-        pipeline: Final = self._pipeline(
-            vector_store_id, self._embedding_vector(embedding_response), params, vector_store_search_optional_params
+            params,
+            vector_store_search_optional_params,
+            api_base,
+            response,
+            litellm_params.get("timeout"),
         )
 
+    def transform_search_vector_store_response(
+        self, response: httpx.Response, litellm_logging_obj: "LiteLLMLoggingObj"
+    ) -> VectorStoreSearchResponse:
         try:
-            client: Final = self.async_client_factory(key)
-            target: Final = client[database][collection]  # pyright: ignore[reportIndexIssue]  # factory is typed as returning object so injected doubles are accepted
-            cursor: Final = await target.aggregate(pipeline)
-            documents: Final = [  # mutable-ok: an async comprehension cannot build a tuple directly
-                document async for document in cursor
-            ]
-        except Exception as e:
-            raise translate_mongo_error(e, index_name=vector_store_id, database=database, collection=collection) from e
-        if not documents:
-            try:
-                index_cursor: Final = await target.list_search_indexes(vector_store_id)
-                catalogue: Final = [  # mutable-ok: an async comprehension cannot build a tuple directly
-                    entry async for entry in index_cursor
-                ]
-            except Exception as e:
-                raise translate_mongo_error(
-                    e, index_name=vector_store_id, database=database, collection=collection
-                ) from e
-            self._raise_for_unusable_index(catalogue, vector_store_id, database, collection)
-        self._raise_for_missing_text_field(documents, params.text_field, database, collection)
-        return self._to_response(documents, query_text, params.text_field)
+            validated: Final = _SearchResponse.model_validate_json(response.content)
+            return _RESPONSE_ADAPTER.validate_python(validated.model_dump())
+        except ValidationError:
+            raise ServiceUnavailableError(
+                message="MongoDB sidecar returned an invalid search response. Check the sidecar version and deployment.",
+                model=None,
+                llm_provider="mongodb",
+            ) from None
+
+    def get_error_class(
+        self, error_message: str, status_code: int, headers: dict[str, object] | httpx.Headers
+    ) -> BaseLLMException:
+        if status_code == 400:
+            raise config_error(error_message)
+        if status_code == 401:
+            raise AuthenticationError(message="MongoDB sidecar rejected api_key.", model=None, llm_provider="mongodb")
+        if status_code == 408:
+            raise Timeout(message=error_message, model=None, llm_provider="mongodb")
+        raise ServiceUnavailableError(
+            message="MongoDB sidecar is unavailable. Check its address, health, and logs.",
+            model=None,
+            llm_provider="mongodb",
+        )
+
+    def validate_create_vector_store(self) -> NoReturn:
+        raise config_error(_SEARCH_ONLY_MESSAGE)
 
     def transform_create_vector_store_request(
-        self,
-        vector_store_create_optional_params: VectorStoreCreateOptionalRequestParams,
-        api_base: str,
+        self, vector_store_create_optional_params: VectorStoreCreateOptionalRequestParams, api_base: str
     ) -> NoReturn:
         raise config_error(_SEARCH_ONLY_MESSAGE)
 
diff --git a/pyproject.toml b/pyproject.toml
index af35c77d259..b7eecfb2109 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -114,7 +114,6 @@ caching = ["diskcache>=5.6.3,<6.0"]
 mcp = ["mcp>=1.28.1,<2.0"]
 # Driver for the MongoDB Atlas vector store; Atlas Vector Search has no HTTP query API.
 # The floor is 4.9 because that is the release AsyncMongoClient landed in.
-mongodb = ["pymongo>=4.9,<5.0"]
 # SAML SSO for the admin UI. python3-saml pulls in xmlsec/lxml, whose wheels
 # bundle the native libxmlsec1/libxml2 libraries, so no system packages are
 # required. Kept out of the base `proxy` extra so it stays optional.
diff --git a/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py b/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py
index f5d31c0da54..bca2b544673 100644
--- a/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py
+++ b/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py
@@ -1,1537 +1,182 @@
-import asyncio
-import gc
-import sys
-import threading
-import weakref
-from types import SimpleNamespace
-from unittest.mock import MagicMock, patch
+import json
+from collections.abc import Mapping
+from typing import Final
+from unittest.mock import MagicMock
 
 import httpx
 import pytest
 
 import litellm
-from litellm.exceptions import BadRequestError, ServiceUnavailableError, Timeout
-from litellm.llms.mongodb.common_utils import (
-    _MAX_CACHED_CLIENTS,
-    _async_clients,
-    _sync_clients,
-    MongoClientKey,
-    index_not_ready_error,
-    missing_index_error,
-    get_async_client,
-    get_sync_client,
-    reset_client_cache,
-    translate_mongo_error,
-)
-from litellm.llms.mongodb.vector_stores.transformation import (
-    MongoDBVectorStoreConfig,
-    _MongoDBSearchParams,
-)
-from litellm.types.utils import LlmProviders
-from litellm.utils import ProviderConfigManager
+from litellm.llms.custom_httpx.http_handler import HTTPHandler
+from litellm.llms.mongodb.vector_stores.transformation import MongoDBVectorStoreConfig
+from litellm.types.utils import EmbeddingResponse
+from litellm.types.vector_stores import VectorStoreSearchOptionalRequestParams
 
-CONNECTION_STRING = "mongodb+srv://user:pw@cluster.example.mongodb.net"
-INDEX = "movies_vector_index"
-
-BASE_PARAMS = {
-    "litellm_embedding_model": "openai/text-embedding-ada-002",
-    "mongodb_connection_string": CONNECTION_STRING,
-    "mongodb_database": "sample_mflix",
-    "mongodb_collection": "embedded_movies",
+BASE_PARAMS: Final = {
+    "api_base": "https://sidecar.example/prefix",
+    "api_key": "test-sidecar-key",
+    "litellm_embedding_model": "embedding-alias",
+    "mongodb_database": "policies",
+    "mongodb_collection": "documents",
+}
+RESULT: Final = {
+    "object": "vector_store.search_results.page",
+    "search_query": "travel policy",
+    "data": [
+        {"score": 0.9, "file_id": "123", "filename": "123", "content": [{"type": "text", "text": "Use code BLUE-42"}]}
+    ],
 }
 
 
-READY_INDEX = [{"name": INDEX, "status": "READY", "queryable": True}]
+class RecordingEmbeddingExecutor:
+    def __init__(self) -> None:
+        self.call: Final = MagicMock(return_value=EmbeddingResponse(data=[{"embedding": [0.1, 0.2, 0.3]}]))
+
+    def embed(self, model: str, query: str, configuration: Mapping[str, object]) -> EmbeddingResponse:
+        return self.call(model, query, configuration)
+
+    async def aembed(self, model: str, query: str, configuration: Mapping[str, object]) -> EmbeddingResponse:
+        return self.call(model, query, configuration)
 
 
-class RecordingClient:
-    """Stands in for pymongo's client class so the cache tests inject a fake rather than
-    patching the importer, and so they can assert what the client was actually built with."""
-
-    def __init__(self, connection_string, **kwargs):
-        self.connection_string = connection_string
-        self.kwargs = kwargs
-
-
-class FakeCollection:
-    def __init__(self, documents, error=None, search_indexes=None):
-        self.documents = documents
-        self.error = error
-        self.search_indexes = READY_INDEX if search_indexes is None else search_indexes
-        self.pipeline = None
-        self.listed_indexes = []
-
-    def aggregate(self, pipeline):
-        self.pipeline = pipeline
-        if self.error is not None:
-            raise self.error
-        return iter(self.documents)
-
-    def list_search_indexes(self, name):
-        self.listed_indexes.append(name)
-        return iter(self.search_indexes)
-
-
-class FakeAsyncCollection(FakeCollection):
-    async def aggregate(self, pipeline):
-        self.pipeline = pipeline
-        if self.error is not None:
-            raise self.error
-
-        async def cursor():
-            for document in self.documents:
-                yield document
-
-        return cursor()
-
-    async def list_search_indexes(self, name):
-        self.listed_indexes.append(name)
-
-        async def cursor():
-            for entry in self.search_indexes:
-                yield entry
-
-        return cursor()
-
-
-class FakeDatabase:
-    def __init__(self, collection):
-        self.collection = collection
-        self.requested_collection = None
-
-    def __getitem__(self, name):
-        self.requested_collection = name
-        return self.collection
-
-
-class FakeClient:
-    def __init__(self, collection):
-        self.database = FakeDatabase(collection)
-        self.requested_database = None
-
-    def __getitem__(self, name):
-        self.requested_database = name
-        return self.database
-
-
-class FakeEmbeddingExecutor:
-    def __init__(self, embedding):
-        self.embedding = embedding
-        self.captured = None
-
-    def _respond(self, model, query, configuration):
-        self.captured = SimpleNamespace(model=model, query=query, configuration=configuration)
-        return SimpleNamespace(data=[{"embedding": self.embedding}] if self.embedding is not None else [])
-
-    def embed(self, model, query, configuration):
-        return self._respond(model, query, configuration)
-
-    async def aembed(self, model, query, configuration):
-        return self._respond(model, query, configuration)
-
-
-def _config(documents=(), embedding=(0.1, 0.2, 0.3), error=None, search_indexes=None):
-    collection = FakeCollection(list(documents), error, search_indexes)
-    client = FakeClient(collection)
-    config = MongoDBVectorStoreConfig(
-        embedding_executor=FakeEmbeddingExecutor(list(embedding) if embedding is not None else None),
-        sync_client_factory=lambda key: client,
-    )
-    return config, client, collection
-
-
-def _async_config(documents=(), embedding=(0.1, 0.2, 0.3), error=None, search_indexes=None):
-    collection = FakeAsyncCollection(list(documents), error, search_indexes)
-    client = FakeClient(collection)
-    config = MongoDBVectorStoreConfig(
-        embedding_executor=FakeEmbeddingExecutor(list(embedding) if embedding is not None else None),
-        async_client_factory=lambda key: client,
-    )
-    return config, client, collection
-
-
-def _search(config, query="a lone astronaut", optional_params=None, litellm_params=None, timeout=None):
-    return config.execute_search_vector_store_request(
-        vector_store_id=INDEX,
-        query=query,
-        vector_store_search_optional_params=optional_params or {},
-        litellm_logging_obj=MagicMock(),
-        litellm_params={**BASE_PARAMS, **(litellm_params or {})},
-        timeout=timeout,
-    )
-
-
-async def _asearch(config, query="a lone astronaut", optional_params=None, litellm_params=None):
-    return await config.aexecute_search_vector_store_request(
-        vector_store_id=INDEX,
-        query=query,
-        vector_store_search_optional_params=optional_params or {},
-        litellm_logging_obj=MagicMock(),
-        litellm_params={**BASE_PARAMS, **(litellm_params or {})},
-    )
-
-
-def _stage(collection, name):
-    return next(stage[name] for stage in collection.pipeline if name in stage)
-
-
-def test_search_builds_vector_search_stage_against_the_named_index():
-    config, client, collection = _config()
-
-    _search(config, optional_params={"max_num_results": 5})
-
-    assert client.requested_database == "sample_mflix"
-    assert client.database.requested_collection == "embedded_movies"
-    assert _stage(collection, "$vectorSearch") == {
-        "index": INDEX,
-        "path": "embedding",
-        "queryVector": (0.1, 0.2, 0.3),
-        "numCandidates": 100,
-        "limit": 5,
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.parametrize("limit,candidates", [(None, 100), (1, 100), (50, 500)])
+@pytest.mark.asyncio
+async def test_search_preserves_embedding_and_http_contract(
+    asynchronous: bool, limit: int | None, candidates: int
+) -> None:
+    executor: Final = RecordingEmbeddingExecutor()
+    config: Final = MongoDBVectorStoreConfig(executor)
+    params: Final = {
+        **BASE_PARAMS,
+        "mongodb_text_field": "metadata.body",
+        "mongodb_embedding_field": "stored_vector",
+        "litellm_embedding_config": {"dimensions": 3},
+        "timeout": 0.75,
     }
-
-
-def test_the_pipeline_reaches_pymongo_as_a_list():
-    """pymongo's common.validate_list rejects any other sequence with
-    'pipeline must be a list, not <class ...>', so the outer container is part of the contract."""
-    config, _, collection = _config()
-
-    _search(config)
-
-    assert isinstance(collection.pipeline, list)
-
-
-def test_search_projects_the_text_field_and_the_similarity_score():
-    config, _, collection = _config()
-
-    _search(config)
-
-    assert _stage(collection, "$project") == {"text": 1, "score": {"$meta": "vectorSearchScore"}}
-
-
-def test_search_defaults_to_ten_results():
-    config, _, collection = _config()
-
-    _search(config)
-
-    assert _stage(collection, "$vectorSearch")["limit"] == 10
-
-
-def test_search_honors_custom_field_names():
-    config, _, collection = _config()
-
-    _search(
-        config,
-        litellm_params={"mongodb_embedding_field": "plot_embedding", "mongodb_text_field": "plot"},
-    )
-
-    assert _stage(collection, "$vectorSearch")["path"] == "plot_embedding"
-    assert _stage(collection, "$project") == {"plot": 1, "score": {"$meta": "vectorSearchScore"}}
-
-
-def test_num_candidates_scales_with_the_requested_limit():
-    config, _, collection = _config()
-
-    _search(config, optional_params={"max_num_results": 40})
-
-    assert _stage(collection, "$vectorSearch")["numCandidates"] == 400
-
-
-def test_num_candidates_can_be_overridden():
-    config, _, collection = _config()
-
-    _search(config, optional_params={"max_num_results": 5}, litellm_params={"mongodb_num_candidates": 250})
-
-    assert _stage(collection, "$vectorSearch")["numCandidates"] == 250
-
-
-@pytest.mark.parametrize("configured", [4, 10_001])
-def test_num_candidates_below_the_limit_or_above_the_ceiling_is_rejected(configured):
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="mongodb_num_candidates"):
-        _search(config, optional_params={"max_num_results": 5}, litellm_params={"mongodb_num_candidates": configured})
-
-
-def test_list_query_is_joined_into_one_embedding_input():
-    config, _, _ = _config()
-
-    _search(config, query=["deep", "space", "rescue"])
-
-    assert config.embedding_executor.captured.query == "deep space rescue"
-
-
-def test_embedding_config_is_expanded_into_the_embedding_call():
-    config, _, _ = _config()
-
-    _search(config, litellm_params={"litellm_embedding_config": {"api_base": "https://example.test", "timeout": 7}})
-
-    captured = config.embedding_executor.captured
-    assert captured.configuration == {"api_base": "https://example.test", "timeout": 7}
-    assert captured.model == "openai/text-embedding-ada-002"
-
-
-def test_response_maps_documents_to_openai_shaped_results():
-    documents = [
-        {"_id": "abc123", "text": "an astronaut adrift", "score": 0.94},
-        {"_id": "def456", "text": "a robot dog", "score": 0.81},
-    ]
-    config, _, _ = _config(documents=documents)
-
-    response = _search(config)
-
-    assert response["object"] == "vector_store.search_results.page"
-    assert response["search_query"] == "a lone astronaut"
-    assert [result["score"] for result in response["data"]] == [0.94, 0.81]
-    assert [result["content"][0]["text"] for result in response["data"]] == ["an astronaut adrift", "a robot dog"]
-    assert [result["file_id"] for result in response["data"]] == ["abc123", "def456"]
-    assert [result["filename"] for result in response["data"]] == ["abc123", "def456"]
-    assert response["data"][0]["content"][0]["type"] == "text"
-
-
-def test_response_reads_a_dotted_text_field_path():
-    config, _, _ = _config(documents=[{"_id": 1, "metadata": {"body": "nested text"}, "score": 0.5}])
-
-    response = _search(config, litellm_params={"mongodb_text_field": "metadata.body"})
-
-    assert response["data"][0]["content"][0]["text"] == "nested text"
-
-
-def test_a_dotted_path_resolves_three_levels_deep():
-    config, _, _ = _config(documents=[{"_id": 1, "a": {"b": {"c": "deep text"}}, "score": 0.5}])
-
-    response = _search(config, litellm_params={"mongodb_text_field": "a.b.c"})
-
-    assert response["data"][0]["content"][0]["text"] == "deep text"
-
-
-def test_a_dotted_path_that_runs_through_a_scalar_counts_as_absent():
-    """Walking 'plot.nope' when plot is a string must report the misconfiguration, not
-    stringify the scalar and hand the model text from the wrong field."""
-    config, _, _ = _config(documents=[{"_id": 1, "plot": "a plain string", "score": 0.5}])
-
-    with pytest.raises(BadRequestError, match=r"has a 'plot\.nope' field"):
-        _search(config, litellm_params={"mongodb_text_field": "plot.nope"})
-
-
-def test_a_non_string_text_field_is_stringified():
-    config, _, _ = _config(documents=[{"_id": 1, "year": 1979, "score": 0.5}])
-
-    response = _search(config, litellm_params={"mongodb_text_field": "year"})
-
-    assert response["data"][0]["content"][0]["text"] == "1979"
-
-
-def test_a_null_text_field_counts_as_absent():
-    config, _, _ = _config(documents=[{"_id": 1, "text": None, "score": 0.5}])
-
-    with pytest.raises(BadRequestError, match="has a 'text' field"):
-        _search(config)
-
-
-def test_response_tolerates_a_sparse_document_missing_the_text_field():
-    config, _, _ = _config(documents=[{"_id": 1, "score": 0.5}, {"_id": 2, "text": "has text", "score": 0.4}])
-
-    response = _search(config)
-
-    assert response["data"][0]["content"][0]["text"] == ""
-    assert response["data"][1]["content"][0]["text"] == "has text"
-
-
-def test_a_present_but_empty_text_field_is_not_treated_as_a_misconfiguration():
-    config, _, _ = _config(documents=[{"_id": 1, "text": "", "score": 0.5}])
-
-    response = _search(config)
-
-    assert response["data"][0]["content"][0]["text"] == ""
-
-
-def test_matches_that_all_lack_the_text_field_name_the_setting_to_fix():
-    """Atlas matches on the vector, so a mistyped mongodb_text_field returns confidently
-    scored results whose content is empty and hands the model an empty context."""
-    config, _, _ = _config(documents=[{"_id": 1, "score": 0.9}, {"_id": 2, "score": 0.8}])
-
-    with pytest.raises(BadRequestError, match="mongodb_text_field"):
-        _search(config)
-
-
-def test_response_tolerates_a_document_missing_a_score():
-    config, _, _ = _config(documents=[{"_id": 1, "text": "no score"}])
-
-    response = _search(config)
-
-    assert response["data"][0]["score"] is None
-
-
-def test_response_stringifies_a_non_string_document_id():
-    config, _, _ = _config(documents=[{"_id": 12345, "text": "numeric id", "score": 0.5}])
-
-    response = _search(config)
-
-    assert response["data"][0]["file_id"] == "12345"
-
-
-def test_search_requires_an_embedding_model():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="litellm_embedding_model is required"):
-        config.execute_search_vector_store_request(
-            vector_store_id=INDEX,
-            query="q",
-            vector_store_search_optional_params={},
+    kwargs: Final = {
+        "vector_store_id": "exact index",
+        "query": ["travel", "policy"],
+        "vector_store_search_optional_params": {"max_num_results": limit},
+        "api_base": BASE_PARAMS["api_base"],
+        "litellm_logging_obj": MagicMock(),
+        "litellm_params": params,
+    }
+    if asynchronous:
+        url, body = await config.atransform_search_vector_store_request(**kwargs)
+    else:
+        url, body = config.transform_search_vector_store_request(**kwargs)
+    assert url == "https://sidecar.example/prefix/v1/vector_stores/exact%20index/search"
+    assert body == {
+        "query": "travel policy",
+        "query_vector": (0.1, 0.2, 0.3),
+        "mongodb_database": "policies",
+        "mongodb_collection": "documents",
+        "mongodb_text_field": "metadata.body",
+        "mongodb_embedding_field": "stored_vector",
+        "mongodb_num_candidates": candidates,
+        "max_num_results": limit or 10,
+        "timeout_ms": 750,
+    }
+    executor.call.assert_called_once_with("embedding-alias", "travel policy", {"dimensions": 3})
+    assert config.transform_search_vector_store_response(httpx.Response(200, json=RESULT), MagicMock()) == RESULT
+
+
+@pytest.mark.parametrize(
+    "query,overrides,options",
+    [
+        ("", {}, {}),
+        ("  ", {}, {}),
+        ("x" * 32_001, {}, {}),
+        ("travel", {"litellm_embedding_model": None}, {}),
+        ("travel", {"mongodb_database": None}, {}),
+        ("travel", {"mongodb_collection": None}, {}),
+        ("travel", {"mongodb_connection_string": "mongodb://obsolete-secret"}, {}),
+        ("travel", {"mongodb_filter": {"private": True}}, {}),
+        ("travel", {"mongodb_num_candidates": 9}, {}),
+        ("travel", {"mongodb_num_candidates": 10_001}, {}),
+        ("travel", {}, {"max_num_results": 0}),
+        ("travel", {}, {"max_num_results": 51}),
+        ("travel", {}, {"filters": {}}),
+        ("travel", {}, {"ranking_options": {}}),
+        ("travel", {}, {"rewrite_query": False}),
+    ],
+)
+def test_invalid_search_is_rejected_before_embedding(
+    query: str, overrides: Mapping[str, object], options: VectorStoreSearchOptionalRequestParams
+) -> None:
+    executor: Final = RecordingEmbeddingExecutor()
+    config: Final = MongoDBVectorStoreConfig(executor)
+    with pytest.raises(litellm.BadRequestError) as error:
+        config.transform_search_vector_store_request(
+            vector_store_id="policy_index",
+            query=query,
+            vector_store_search_optional_params=options,
+            api_base=BASE_PARAMS["api_base"],
             litellm_logging_obj=MagicMock(),
-            litellm_params={k: v for k, v in BASE_PARAMS.items() if k != "litellm_embedding_model"},
+            litellm_params={**BASE_PARAMS, **overrides},
         )
-
-
-def test_missing_embedding_model_message_names_the_field_being_searched():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match=r"embedded_movies\.embedding"):
-        config.execute_search_vector_store_request(
-            vector_store_id=INDEX,
-            query="q",
-            vector_store_search_optional_params={},
-            litellm_logging_obj=MagicMock(),
-            litellm_params={k: v for k, v in BASE_PARAMS.items() if k != "litellm_embedding_model"},
-        )
-
-
-def test_search_requires_a_connection_string():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="mongodb_connection_string is required"):
-        _search(config, litellm_params={"mongodb_connection_string": None})
-
-
-@pytest.mark.parametrize("connection_string", ["postgres://host/db", "https://cluster.mongodb.net", "redis://host"])
-def test_search_rejects_a_non_mongodb_connection_scheme(connection_string):
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="must start with 'mongodb://' or 'mongodb\\+srv://'"):
-        _search(config, litellm_params={"mongodb_connection_string": connection_string})
-
-
-def test_search_accepts_the_plain_mongodb_scheme():
-    config, _, collection = _config()
-
-    _search(config, litellm_params={"mongodb_connection_string": "mongodb://localhost:27017"})
-
-    assert collection.pipeline is not None
-
-
-def test_search_requires_a_database():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="mongodb_database is required"):
-        _search(config, litellm_params={"mongodb_database": None})
-
-
-def test_search_requires_a_collection():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="mongodb_collection is required"):
-        _search(config, litellm_params={"mongodb_collection": None})
-
-
-def test_search_rejects_filters_rather_than_silently_ignoring_them():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="does not support the filters parameter"):
-        _search(config, optional_params={"filters": {"genre": "sci-fi"}})
-
-
-@pytest.mark.asyncio
-async def test_async_search_rejects_filters_rather_than_silently_ignoring_them():
-    config, _, _ = _async_config()
-
-    with pytest.raises(BadRequestError, match="does not support the filters parameter"):
-        await _asearch(config, optional_params={"filters": {"genre": "sci-fi"}})
-
-
-def test_search_rejects_ranking_options_rather_than_silently_ignoring_them():
-    """A score_threshold that is quietly dropped is worse than an error: the caller asked for
-    results above 0.9, gets results scoring 0.5, and nothing says the threshold never ran."""
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="does not support the ranking_options parameter"):
-        _search(config, optional_params={"ranking_options": {"score_threshold": 0.9}})
-
-
-def test_search_rejects_rewrite_query_rather_than_silently_ignoring_it():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="does not support the rewrite_query parameter"):
-        _search(config, optional_params={"rewrite_query": True})
-
-
-@pytest.mark.asyncio
-async def test_async_search_rejects_ranking_options_rather_than_silently_ignoring_them():
-    config, _, _ = _async_config()
-
-    with pytest.raises(BadRequestError, match="does not support the ranking_options parameter"):
-        await _asearch(config, optional_params={"ranking_options": {"score_threshold": 0.9}})
-
-
-@pytest.mark.parametrize("query", ["", "   ", "\n\t", []])
-def test_search_rejects_an_empty_query(query):
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="query must not be empty"):
-        _search(config, query=query)
-
-
-def test_search_rejects_an_oversized_query():
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="at most 32000 characters"):
-        _search(config, query="x" * 32_001)
-
-
-def test_search_accepts_a_query_at_the_size_ceiling():
-    config, _, collection = _config()
-
-    _search(config, query="x" * 32_000)
-
-    assert collection.pipeline is not None
-
-
-@pytest.mark.parametrize("max_num_results", [0, -1, 51, 1000])
-def test_search_rejects_out_of_range_max_num_results(max_num_results):
-    config, _, _ = _config()
-
-    with pytest.raises(BadRequestError, match="max_num_results must be between 1 and 50"):
-        _search(config, optional_params={"max_num_results": max_num_results})
-
-
-@pytest.mark.parametrize("max_num_results", [1, 50])
-def test_search_allows_max_num_results_at_the_bounds(max_num_results):
-    config, _, collection = _config()
-
-    _search(config, optional_params={"max_num_results": max_num_results})
-
-    assert _stage(collection, "$vectorSearch")["limit"] == max_num_results
-
-
-def test_search_treats_an_explicit_null_max_num_results_as_the_default():
-    config, _, collection = _config()
-
-    _search(config, optional_params={"max_num_results": None})
-
-    assert _stage(collection, "$vectorSearch")["limit"] == 10
-
-
-def test_search_fails_when_the_embedding_model_returns_nothing():
-    config, _, _ = _config(embedding=None)
-
-    with pytest.raises(BadRequestError, match="returned no embedding"):
-        _search(config)
-
-
-def test_validation_runs_before_any_connection_is_opened():
-    opened = []
-    config = MongoDBVectorStoreConfig(
-        embedding_executor=FakeEmbeddingExecutor([0.1]),
-        sync_client_factory=lambda key: opened.append(key) or FakeClient(FakeCollection([])),
-    )
-
-    with pytest.raises(BadRequestError, match="query must not be empty"):
-        _search(config, query="")
-
-    assert opened == []
-
-
-def test_create_vector_store_is_not_supported_and_says_why():
-    """litellm.exception_type only passes its own exception types through untouched, so a
-    NotImplementedError here reaches the caller as APIConnectionError, which the proxy serves
-    as a 500 with a traceback. Refusing an unsupported operation is a client error."""
-    config = MongoDBVectorStoreConfig()
-
-    with pytest.raises(BadRequestError, match="search-only"):
-        config.transform_create_vector_store_request({}, "https://example.test")
-
-    with pytest.raises(BadRequestError, match="search-only"):
-        config.transform_create_vector_store_response(httpx.Response(200))
-
-
-def test_the_create_refusal_survives_the_public_sdk_error_wrapper():
-    import litellm
-
-    with pytest.raises(BadRequestError) as raised:
-        litellm.vector_stores.create(custom_llm_provider="mongodb", name="anything")
-
-    assert "search-only" in str(raised.value)
-
-
-def test_provider_config_manager_returns_the_mongodb_config():
-    config = ProviderConfigManager.get_provider_vector_stores_config(LlmProviders.MONGODB)
-
-    assert isinstance(config, MongoDBVectorStoreConfig)
-
-
-@pytest.mark.asyncio
-async def test_async_search_builds_the_same_pipeline_and_maps_the_response():
-    documents = [{"_id": "abc123", "text": "an astronaut adrift", "score": 0.94}]
-    config, client, collection = _async_config(documents=documents)
-
-    response = await _asearch(config, optional_params={"max_num_results": 3})
-
-    assert client.requested_database == "sample_mflix"
-    assert client.database.requested_collection == "embedded_movies"
-    assert _stage(collection, "$vectorSearch")["limit"] == 3
-    assert _stage(collection, "$vectorSearch")["queryVector"] == (0.1, 0.2, 0.3)
-    assert response["data"][0]["content"][0]["text"] == "an astronaut adrift"
-    assert response["data"][0]["score"] == 0.94
-
-
-@pytest.mark.asyncio
-async def test_async_search_requires_an_embedding_model():
-    config, _, _ = _async_config()
-
-    with pytest.raises(BadRequestError, match="litellm_embedding_model is required"):
-        await config.aexecute_search_vector_store_request(
-            vector_store_id=INDEX,
-            query="q",
-            vector_store_search_optional_params={},
-            litellm_logging_obj=MagicMock(),
-            litellm_params={k: v for k, v in BASE_PARAMS.items() if k != "litellm_embedding_model"},
-        )
-
-
-class TestClientCache:
-    def setup_method(self):
-        reset_client_cache()
-
-    def teardown_method(self):
-        reset_client_cache()
-
-    def _key(self, connection_string=CONNECTION_STRING, socket_timeout_ms=30_000):
-        return MongoClientKey(
-            connection_string=connection_string,
-            connect_timeout_ms=10_000,
-            socket_timeout_ms=socket_timeout_ms,
-            server_selection_timeout_ms=10_000,
-        )
-
-    def test_the_same_connection_reuses_one_client(self):
-        first = get_sync_client(self._key(), RecordingClient)
-        second = get_sync_client(self._key(), RecordingClient)
-
-        assert first is second
-        assert first.connection_string == CONNECTION_STRING
-        assert first.kwargs["socketTimeoutMS"] == 30_000
-        assert first.kwargs["connectTimeoutMS"] == 10_000
-        assert first.kwargs["appname"] == "litellm"
-
-    def test_a_different_connection_gets_its_own_client(self):
-        first = get_sync_client(self._key(), RecordingClient)
-        second = get_sync_client(self._key(connection_string="mongodb://other.example.test"), RecordingClient)
-
-        assert first is not second
-        assert second.connection_string == "mongodb://other.example.test"
-
-    def test_a_different_timeout_gets_its_own_client(self):
-        first = get_sync_client(self._key(), RecordingClient)
-        second = get_sync_client(self._key(socket_timeout_ms=5_000), RecordingClient)
-
-        assert first is not second
-        assert second.kwargs["socketTimeoutMS"] == 5_000
-
-    @pytest.mark.asyncio
-    async def test_async_clients_are_cached_per_event_loop(self):
-        first = get_async_client(self._key(), RecordingClient)
-        second = get_async_client(self._key(), RecordingClient)
-
-        assert first is second
-        assert first.connection_string == CONNECTION_STRING
-
-
-    def _fill_cache(self):
-        for slot in range(_MAX_CACHED_CLIENTS):
-            get_sync_client(self._key(f"mongodb://cold-{slot}:27017"), RecordingClient)
-
-    def test_a_store_added_after_the_cache_filled_is_still_cached(self):
-        """Rebuilding a client costs an SRV lookup, a TLS handshake and topology discovery, so a
-        store that misses the cache on every single search pays that on every search."""
-        self._fill_cache()
-        latecomer = self._key("mongodb://latecomer:27017")
-
-        first = get_sync_client(latecomer, RecordingClient)
-
-        assert get_sync_client(latecomer, RecordingClient) is first
-
-    def test_the_cache_evicts_the_least_recently_used_client(self):
-        self._fill_cache()
-        oldest = self._key("mongodb://cold-0:27017")
-        newest = self._key(f"mongodb://cold-{_MAX_CACHED_CLIENTS - 1}:27017")
-        kept = get_sync_client(newest, RecordingClient)
-
-        get_sync_client(self._key("mongodb://latecomer:27017"), RecordingClient)
-
-        assert get_sync_client(newest, RecordingClient) is kept
-        assert oldest not in _sync_clients
-
-    def test_concurrent_searches_never_trip_over_an_eviction(self):
-        """Async searches run the sync client through executor threads, so a key can be evicted
-        between the lookup and the reordering that follows it."""
-        errors = []
-        churn = _MAX_CACHED_CLIENTS + 2
-
-        def hammer(offset):
-            try:
-                for step in range(3_000):
-                    get_sync_client(self._key(f"mongodb://h-{(step + offset) % churn}:27017"), RecordingClient)
-            except Exception as e:
-                errors.append(repr(e))
-
-        previous = sys.getswitchinterval()
-        sys.setswitchinterval(1e-9)
-        try:
-            threads = [threading.Thread(target=hammer, args=(offset,)) for offset in range(16)]
-            for thread in threads:
-                thread.start()
-            for thread in threads:
-                thread.join()
-        finally:
-            sys.setswitchinterval(previous)
-
-        assert errors == []
-
-    def test_the_cache_never_grows_past_its_cap(self):
-        for slot in range(_MAX_CACHED_CLIENTS * 3):
-            get_sync_client(self._key(f"mongodb://host-{slot}:27017"), RecordingClient)
-
-        assert len(_sync_clients) == _MAX_CACHED_CLIENTS
-
-    def test_a_new_loop_never_inherits_a_closed_loop_client(self):
-        """CPython recycles id() so aggressively that a fresh event loop almost always lands on
-        the id of one already collected: measured at 37 of 40 rounds. Keying the cache on the id
-        alone therefore hands the new loop an AsyncMongoClient bound to a closed loop, and every
-        operation on it raises "Event loop is closed"."""
-
-        class LoopAgnosticClient:
-            """Holds no reference to the loop, unlike pymongo's, whose own reference happens to
-            keep ids from being recycled and hides the bug until the cache fills."""
-
-            def __init__(self, *args, **kwargs):
-                self.built_on = None
-
-        key = self._key()
-        clients_handed_out = []
-
-        async def fetch():
-            return get_async_client(key, LoopAgnosticClient)
-
-        for _ in range(20):
-            loop = asyncio.new_event_loop()
-            client = loop.run_until_complete(fetch())
-            clients_handed_out.append((client, client.built_on, loop.is_closed()))
-            client.built_on = weakref.ref(loop)
-            loop.close()
-            del loop
-            gc.collect()
-
-        stale = [
-            handed_out
-            for client, built_on, _ in clients_handed_out
-            if built_on is not None and (built_on() is None or built_on().is_closed())
-            for handed_out in (client,)
-        ]
-        assert stale == [], f"{len(stale)} of 20 loops were handed a client built on a closed loop"
-
-    def test_the_cache_releases_clients_built_on_closed_loops(self):
-        """pymongo's AsyncMongoClient keeps a reference to the loop it was built on, so an entry
-        for a closed loop holds that client, and its sockets, for the life of the process. A
-        script calling asyncio.run per search fills the cache to its cap that way: measured live
-        against Atlas at 32 pinned clients and 212 open descriptors after 40 loops."""
-
-        class LoopHoldingClient:
-            def __init__(self, *args, **kwargs):
-                self.loop = asyncio.get_running_loop()
-
-        key = self._key()
-
-        async def fetch():
-            return get_async_client(key, LoopHoldingClient)
-
-        for _ in range(_MAX_CACHED_CLIENTS + 8):
-            loop = asyncio.new_event_loop()
-            loop.run_until_complete(fetch())
-            loop.close()
-
-        assert len(_async_clients) == 1, f"{len(_async_clients)} closed-loop clients are still cached"
-
-
-class TestClientKeyDerivation:
-    def test_no_timeout_uses_the_bounded_defaults(self):
-        key = MongoDBVectorStoreConfig._client_key(_MongoDBSearchParams.model_validate(BASE_PARAMS), None)
-
-        assert key.connect_timeout_ms == 10_000
-        assert key.socket_timeout_ms == 30_000
-        assert key.server_selection_timeout_ms == 10_000
-
-    def test_a_numeric_timeout_bounds_the_connect_phase(self):
-        key = MongoDBVectorStoreConfig._client_key(_MongoDBSearchParams.model_validate(BASE_PARAMS), 3.0)
-
-        assert key.socket_timeout_ms == 3_000
-        assert key.connect_timeout_ms == 3_000
-
-    def test_a_short_timeout_also_shortens_server_selection(self):
-        """Server selection runs before the connect attempt, so leaving it at the 10s default
-        would let a caller asking for a 3s budget block for 10s before anything is tried."""
-        key = MongoDBVectorStoreConfig._client_key(_MongoDBSearchParams.model_validate(BASE_PARAMS), 3.0)
-
-        assert key.server_selection_timeout_ms == 3_000
-
-    def test_a_generous_timeout_does_not_raise_server_selection_above_the_default(self):
-        key = MongoDBVectorStoreConfig._client_key(_MongoDBSearchParams.model_validate(BASE_PARAMS), 120.0)
-
-        assert key.socket_timeout_ms == 120_000
-        assert key.server_selection_timeout_ms == 10_000
-
-    def test_an_httpx_timeout_maps_connect_and_read_separately(self):
-        key = MongoDBVectorStoreConfig._client_key(
-            _MongoDBSearchParams.model_validate(BASE_PARAMS), httpx.Timeout(connect=2.0, read=45.0, write=5.0, pool=5.0)
-        )
-
-        assert key.connect_timeout_ms == 2_000
-        assert key.socket_timeout_ms == 45_000
-
-
-class TestErrorTranslation:
-    def _translate(self, error):
-        return translate_mongo_error(error, index_name=INDEX, database="sample_mflix", collection="embedded_movies")
-
-    def test_server_selection_timeout_points_at_the_atlas_access_list(self):
-        from pymongo.errors import ServerSelectionTimeoutError
-
-        translated = self._translate(ServerSelectionTimeoutError("no servers"))
-
-        assert "IP access list" in str(translated)
-        assert "paused cluster" in str(translated)
-
-    def test_authentication_failure_points_at_the_connection_string_credentials(self):
-        from pymongo.errors import OperationFailure
-
-        translated = self._translate(OperationFailure("auth failed", code=18))
-
-        assert "rejected the credentials" in str(translated)
-
-    def test_a_dropped_connection_stays_retryable(self):
-        """A replica set failover reaches the driver as AutoReconnect. litellm only retries 408,
-        409, 429 and 5xx, so classifying it as a client error would turn one failover into a
-        permanently failed search."""
-        from pymongo.errors import AutoReconnect
-
-        translated = self._translate(AutoReconnect("connection closed"))
-
-        assert litellm._should_retry(translated.status_code)
-        assert "dropped or refused" in str(translated)
-
-    def test_a_dropped_connection_still_names_the_misconfigurations_behind_it(self):
-        """Atlas answers a URI with no credentials by closing the connection rather than failing
-        auth, so the retryable message still has to name that."""
-        from pymongo.errors import AutoReconnect
-
-        translated = self._translate(AutoReconnect("connection closed"))
-
-        assert "no username and password" in str(translated)
-        assert "mongod is listening" in str(translated)
-
-    def test_the_retryable_classification_survives_the_public_sdk_error_wrapper(self):
-        """litellm.exception_type only passes its own exception types through; anything else becomes
-        an APIConnectionError and a 500, which would drop the retryable classification."""
-        from pymongo.errors import AutoReconnect
-
-        translated = self._translate(AutoReconnect("connection closed"))
-
-        wrapped = litellm.exception_type(
-            model=None,
-            original_exception=translated,
-            custom_llm_provider="mongodb",
-            completion_kwargs={},
-            extra_kwargs={},
-        )
-
-        assert isinstance(wrapped, ServiceUnavailableError)
-        assert litellm._should_retry(wrapped.status_code)
-
-    def test_a_pool_wait_queue_timeout_stays_retryable(self):
-        from pymongo.errors import WaitQueueTimeoutError
-
-        translated = self._translate(WaitQueueTimeoutError("timed out waiting for a connection"))
-
-        assert litellm._should_retry(translated.status_code)
-
-    def test_server_selection_timeout_still_wins_over_the_connection_branch(self):
-        from pymongo.errors import ServerSelectionTimeoutError
-
-        translated = self._translate(ServerSelectionTimeoutError("no servers"))
-
-        assert isinstance(translated, Timeout)
-        assert "dropped or refused" not in str(translated)
-
-    def test_network_timeout_still_wins_over_the_connection_branch(self):
-        from pymongo.errors import NetworkTimeout
-
-        translated = self._translate(NetworkTimeout("socket timed out"))
-
-        assert isinstance(translated, Timeout)
-        assert "dropped or refused" not in str(translated)
-
-    def test_an_unescaped_password_character_is_a_400_not_a_500(self):
-        """pymongo's URI parser raises a plain ValueError, not a PyMongoError, for an unusable port,
-        which is also what an unescaped ':' in a password produces. It must not be a 500."""
-        translated = self._translate(ValueError("Port contains non-digit characters"))
-
-        assert isinstance(translated, BadRequestError)
-        assert "percent-encoded" in str(translated)
-
-    def test_unauthorized_points_at_the_database_user_permissions(self):
-        from pymongo.errors import OperationFailure
-
-        translated = self._translate(OperationFailure("not authorized", code=13))
-
-        assert "sample_mflix.embedded_movies" in str(translated)
-
-    def test_code_13_alone_is_enough_without_a_recognisable_message(self):
-        """The other unauthorized case carries "not authorized", which the message markers also
-        match, so it cannot tell whether the code is still being checked at all."""
-        from pymongo.errors import OperationFailure
-
-        translated = self._translate(OperationFailure("user lacks privileges on this namespace", code=13))
-
-        assert "rejected the credentials" in str(translated)
-        assert "sample_mflix.embedded_movies" in str(translated)
-
-    def test_a_missing_index_names_the_index_and_the_collection(self):
-        from pymongo.errors import OperationFailure
-
-        translated = self._translate(OperationFailure("Index not found for name movies_vector_index", code=27))
-
-        assert INDEX in str(translated)
-        assert "READY" in str(translated)
-
-    def test_a_dimension_mismatch_points_at_the_embedding_model(self):
-        from pymongo.errors import OperationFailure
-
-        translated = self._translate(OperationFailure("queryVector has 1536 dimensions, index expects 2048"))
-
-        assert "litellm_embedding_model must be the same model" in str(translated)
-
-    def test_an_unrecognised_operation_failure_still_names_the_target(self):
-        from pymongo.errors import OperationFailure
-
-        translated = self._translate(OperationFailure("something else entirely"))
-
-        assert "sample_mflix.embedded_movies" in str(translated)
-        assert INDEX in str(translated)
-
-    def test_a_configuration_error_points_at_the_connection_string(self):
-        from pymongo.errors import ConfigurationError
-
-        translated = self._translate(ConfigurationError("bad uri"))
-
-        assert "not a usable MongoDB connection string" in str(translated)
-
-    def test_a_non_driver_error_is_returned_unchanged(self):
-        original = RuntimeError("unrelated")
-
-        assert self._translate(original) is original
-
-    def test_search_surfaces_a_translated_driver_error(self):
-        from pymongo.errors import ServerSelectionTimeoutError
-
-        config, _, _ = _config(error=ServerSelectionTimeoutError("no servers"))
-
-        with pytest.raises(Timeout, match="IP access list"):
-            _search(config)
-
-    @pytest.mark.asyncio
-    async def test_async_search_surfaces_a_translated_driver_error(self):
-        from pymongo.errors import OperationFailure
-
-        config, _, _ = _async_config(error=OperationFailure("auth failed", code=18))
-
-        with pytest.raises(BadRequestError, match="rejected the credentials"):
-            await _asearch(config)
-
-
-class TestMissingDriver:
-    def test_the_sync_import_names_the_extra_to_install(self):
-        from litellm.llms.mongodb.common_utils import import_sync_mongo_client
-
-        with patch.dict(sys.modules, {"pymongo": None}):
-            with pytest.raises(BadRequestError, match=r"pip install litellm\[mongodb\]"):
-                import_sync_mongo_client()
-
-    def test_the_async_import_names_the_extra_to_install(self):
-        from litellm.llms.mongodb.common_utils import import_async_mongo_client
-
-        with patch.dict(sys.modules, {"pymongo": None}):
-            with pytest.raises(BadRequestError, match=r"pip install litellm\[mongodb\]"):
-                import_async_mongo_client()
-
-    def test_error_translation_degrades_gracefully_without_the_driver(self):
-        original = RuntimeError("boom")
-
-        with patch.dict(sys.modules, {"pymongo.errors": None}):
-            assert translate_mongo_error(original, INDEX, "db", "col") is original
-
-
-class TestEmptyResultsAreDisambiguated:
-    """$vectorSearch returns zero documents for a missing database, collection or index just as it
-    does for a query that matched nothing, so an empty result set is checked against the index
-    catalogue before it is reported as 'no matches'."""
-
-    def test_a_missing_index_becomes_an_error_rather_than_an_empty_page(self):
-        config, _, collection = _config(documents=[], search_indexes=[])
-
-        with pytest.raises(BadRequestError, match="No queryable MongoDB Vector Search index"):
-            _search(config)
-
-        assert collection.listed_indexes == [INDEX]
-
-    def test_the_missing_index_error_explains_why_mongodb_reported_no_results(self):
-        config, _, _ = _config(documents=[], search_indexes=[])
-
-        with pytest.raises(BadRequestError, match="returns no results rather than an error"):
-            _search(config)
-
-    def test_an_index_still_building_becomes_an_error_naming_its_status(self):
-        config, _, _ = _config(
-            documents=[], search_indexes=[{"name": INDEX, "status": "PENDING", "queryable": False}]
-        )
-
-        with pytest.raises(BadRequestError, match="not queryable yet; its status is PENDING"):
-            _search(config)
-
-    def test_a_genuine_no_match_against_a_ready_index_returns_an_empty_page(self):
-        config, _, collection = _config(documents=[])
-
-        response = _search(config)
-
-        assert response["data"] == []
-        assert response["object"] == "vector_store.search_results.page"
-        assert collection.listed_indexes == [INDEX]
-
-    def test_the_catalogue_is_not_consulted_when_the_search_returned_hits(self):
-        config, _, collection = _config(documents=[{"_id": 1, "text": "hit", "score": 0.9}])
-
-        _search(config)
-
-        assert collection.listed_indexes == []
-
-    @pytest.mark.asyncio
-    async def test_async_missing_index_becomes_an_error_rather_than_an_empty_page(self):
-        config, _, collection = _async_config(documents=[], search_indexes=[])
-
-        with pytest.raises(BadRequestError, match="No queryable MongoDB Vector Search index"):
-            await _asearch(config)
-
-        assert collection.listed_indexes == [INDEX]
-
-    @pytest.mark.asyncio
-    async def test_async_index_still_building_becomes_an_error_naming_its_status(self):
-        config, _, _ = _async_config(
-            documents=[], search_indexes=[{"name": INDEX, "status": "PENDING", "queryable": False}]
-        )
-
-        with pytest.raises(BadRequestError, match="not queryable yet; its status is PENDING"):
-            await _asearch(config)
-
-    @pytest.mark.asyncio
-    async def test_async_genuine_no_match_returns_an_empty_page(self):
-        config, _, _ = _async_config(documents=[])
-
-        response = await _asearch(config)
-
-        assert response["data"] == []
-
-    @pytest.mark.asyncio
-    async def test_async_catalogue_is_not_consulted_when_the_search_returned_hits(self):
-        config, _, collection = _async_config(documents=[{"_id": 1, "text": "hit", "score": 0.9}])
-
-        await _asearch(config)
-
-        assert collection.listed_indexes == []
-
-    def test_a_failure_while_checking_the_catalogue_is_translated_too(self):
-        from pymongo.errors import OperationFailure
-
-        class ExplodingCollection(FakeCollection):
-            def list_search_indexes(self, name):
-                raise OperationFailure("not authorized", code=13)
-
-        collection = ExplodingCollection([], None, [])
-        config = MongoDBVectorStoreConfig(
-            embedding_executor=FakeEmbeddingExecutor([0.1]),
-            sync_client_factory=lambda key: FakeClient(collection),
-        )
-
-        with pytest.raises(BadRequestError, match="lacks read access"):
-            _search(config)
-
-
-class TestAtlasPlanExecutorErrors:
-    """Atlas reports a wrong vector path and a dimension mismatch through the same error code, so
-    each one has to be told apart by its message or both come back as a generic index failure."""
-
-    def _translate(self, message):
-        from pymongo.errors import OperationFailure
-
-        return translate_mongo_error(
-            OperationFailure(message, code=8),
-            index_name=INDEX,
-            database="sample_mflix",
-            collection="embedded_movies",
-        )
-
-    def test_a_wrong_vector_path_points_at_the_embedding_field_setting(self):
-        translated = self._translate(
-            "PlanExecutor error during aggregation :: caused by :: nope is not indexed as vector"
-        )
-
-        assert "mongodb_embedding_field names a field" in str(translated)
-
-    def test_a_dimension_mismatch_is_not_reported_as_a_wrong_path(self):
-        translated = self._translate(
-            "PlanExecutor error during aggregation :: caused by :: vector field is indexed with "
-            "1536 dimensions but queried with 3072"
-        )
-
-        assert "does not match the vector dimensions" in str(translated)
-        assert "mongodb_embedding_field" not in str(translated)
-
-
-class TestErrorsCarryTheRightHttpStatus:
-    """litellm.exception_type passes a litellm exception through untouched but wraps anything
-    else into APIConnectionError, which the proxy serves as a 500 with a Python traceback in the
-    body. A misconfigured connection string is the caller's to fix, so it has to arrive as a 400.
-    """
-
-    @pytest.mark.parametrize(
-        "invoke",
-        [
-            pytest.param(lambda: _search(_config()[0], query="  "), id="empty-query"),
-            pytest.param(
-                lambda: _search(_config()[0], optional_params={"max_num_results": 999}),
-                id="max-num-results-out-of-range",
-            ),
-            pytest.param(
-                lambda: _search(_config()[0], optional_params={"filters": {"genre": "Action"}}),
-                id="unsupported-filters",
-            ),
-            pytest.param(
-                lambda: _search(_config()[0], litellm_params={"mongodb_connection_string": "postgres://host/db"}),
-                id="wrong-uri-scheme",
-            ),
-            pytest.param(
-                lambda: _search(_config()[0], litellm_params={"mongodb_database": None}), id="missing-database"
-            ),
-            pytest.param(
-                lambda: _search(_config()[0], litellm_params={"litellm_embedding_model": None}),
-                id="missing-embedding-model",
-            ),
-        ],
-    )
-    def test_configuration_failures_are_400(self, invoke):
-        with pytest.raises(BadRequestError) as excinfo:
-            invoke()
-        assert excinfo.value.status_code == 400
-        assert excinfo.value.llm_provider == "mongodb"
-
-    def test_missing_index_is_400(self):
-        error = missing_index_error("idx", "db", "coll")
-        assert error.status_code == 400
-        assert error.llm_provider == "mongodb"
-
-    def test_index_still_building_is_400(self):
-        error = index_not_ready_error("idx", "db", "coll", "PENDING")
-        assert error.status_code == 400
-
-    def test_unreachable_deployment_is_a_timeout_not_a_bad_request(self):
-        from pymongo.errors import ServerSelectionTimeoutError
-
-        translated = translate_mongo_error(
-            ServerSelectionTimeoutError("no servers"), index_name="idx", database="db", collection="coll"
-        )
-        assert isinstance(translated, Timeout)
-        assert translated.status_code == 408
-
-    def test_query_execution_timeout_is_a_timeout(self):
-        from pymongo.errors import ExecutionTimeout
-
-        translated = translate_mongo_error(
-            ExecutionTimeout("too slow"), index_name="idx", database="db", collection="coll"
-        )
-        assert isinstance(translated, Timeout)
-        assert translated.status_code == 408
-
-    def test_unrecognised_errors_are_not_relabelled_as_bad_requests(self):
-        original = RuntimeError("something else entirely")
-        assert (
-            translate_mongo_error(original, index_name="idx", database="db", collection="coll")
-            is original
-        )
-
-
-def test_atlas_rejected_credentials_are_named_even_though_the_code_is_8000():
-    """Atlas answers a wrong password with code 8000 "AtlasError", not the 18 that a
-    self-hosted deployment returns, so a code-only check reports it as a generic
-    rejected search and never tells the caller to look at their connection string."""
-    from pymongo.errors import OperationFailure
-
-    error = OperationFailure(
-        "bad auth : authentication failed",
-        code=8000,
-        details={"ok": 0, "errmsg": "bad auth : authentication failed", "code": 8000, "codeName": "AtlasError"},
-    )
-    translated = translate_mongo_error(error, index_name="idx", database="sample_mflix", collection="embedded_movies")
-
-    assert isinstance(translated, BadRequestError)
-    assert "mongodb_connection_string" in str(translated)
-    assert "sample_mflix.embedded_movies" in str(translated)
-
-
-def test_a_rejected_search_that_is_not_an_auth_failure_keeps_the_generic_message():
-    from pymongo.errors import OperationFailure
-
-    error = OperationFailure("PlanExecutor error", code=8, details={"errmsg": "PlanExecutor error"})
-    translated = translate_mongo_error(error, index_name="idx", database="db", collection="coll")
-
-    assert "mongodb_connection_string" not in str(translated)
-
-
-class TestUnrecognisedParameters:
-    """litellm_params carries plenty of keys this provider does not own, so the params model has
-    to ignore extras. That turns a mistyped mongodb_collection into 'mongodb_collection is
-    required', pointing the reader at a key they can see they have set."""
-
-    def test_a_mistyped_parameter_is_named(self):
-        config, _, _ = _config()
-
-        with pytest.raises(BadRequestError, match="mongodb_collectoin"):
-            _search(config, litellm_params={"mongodb_collectoin": "embedded_movies"})
-
-    def test_the_supported_names_are_listed(self):
-        config, _, _ = _config()
-
-        with pytest.raises(BadRequestError, match="mongodb_connection_string"):
-            _search(config, litellm_params={"mongodb_databse": "sample_mflix"})
-
-    def test_unrelated_litellm_params_are_still_ignored(self):
-        config, _, _ = _config(documents=[{"_id": 1, "text": "hit", "score": 0.9}])
-
-        response = _search(
-            config,
-            litellm_params={"use_litellm_proxy": False, "use_in_pass_through": False, "vector_store_id": "x"},
-        )
-
-        assert len(response["data"]) == 1
-
-    @pytest.mark.asyncio
-    async def test_the_async_path_rejects_them_too(self):
-        config, _, _ = _async_config()
-
-        with pytest.raises(BadRequestError, match="mongodb_collectoin"):
-            await _asearch(config, litellm_params={"mongodb_collectoin": "embedded_movies"})
-
-
-class TestClientConstructionFailures:
-    """Building the client parses the URI and, for mongodb+srv://, performs a DNS SRV lookup, so it
-    fails on exactly the inputs a user is most likely to get wrong. Constructing it outside the
-    translation boundary let those escape as raw pymongo errors, which litellm.exception_type then
-    wrapped into a 500 with a traceback in the body."""
-
-    def _config_that_fails_to_connect(self, error):
-        def factory(_key):
-            raise error
-
-        return MongoDBVectorStoreConfig(
-            embedding_executor=FakeEmbeddingExecutor([0.1, 0.2, 0.3]), sync_client_factory=factory
-        )
-
-    def _async_config_that_fails_to_connect(self, error):
-        def factory(_key):
-            raise error
-
-        return MongoDBVectorStoreConfig(
-            embedding_executor=FakeEmbeddingExecutor([0.1, 0.2, 0.3]), async_client_factory=factory
-        )
-
-    def test_a_malformed_uri_is_a_bad_request_not_a_500(self):
-        from pymongo.errors import InvalidURI
-
-        config = self._config_that_fails_to_connect(InvalidURI("Invalid URI scheme"))
-
-        with pytest.raises(BadRequestError, match="not a usable MongoDB connection string"):
-            _search(config)
-
-    def test_an_unresolvable_cluster_name_says_so(self):
-        from pymongo.errors import ConfigurationError
-
-        config = self._config_that_fails_to_connect(ConfigurationError("The DNS query name does not exist"))
-
-        with pytest.raises(BadRequestError, match="does not exist in DNS"):
-            _search(config)
-
-    def test_a_dns_lookup_that_ran_out_of_time_is_a_timeout(self):
-        from pymongo.errors import ConfigurationError
-
-        config = self._config_that_fails_to_connect(
-            ConfigurationError("The resolution lifetime expired after 0.291 seconds")
-        )
-
-        with pytest.raises(Timeout, match="did not finish in time"):
-            _search(config)
-
-    @pytest.mark.asyncio
-    async def test_the_async_path_translates_them_too(self):
-        from pymongo.errors import InvalidURI
-
-        config = self._async_config_that_fails_to_connect(InvalidURI("Invalid URI scheme"))
-
-        with pytest.raises(BadRequestError, match="not a usable MongoDB connection string"):
-            await _asearch(config)
-
-
-class TestSelfManagedDeploymentsAreFirstClass:
-    """mongod serves $vectorSearch identically whether mongot runs under Atlas or beside a
-    self-managed deployment, so an operator without an Atlas account has to be able to act on
-    every message. Guidance that only names Atlas remedies sends them looking for an IP access
-    list and a paused cluster that do not exist in their deployment."""
-
-    def _config_that_fails_to_connect(self, error):
-        def factory(_key):
-            raise error
-
-        return MongoDBVectorStoreConfig(
-            embedding_executor=FakeEmbeddingExecutor([0.1, 0.2, 0.3]), sync_client_factory=factory
-        )
-
-    def test_a_plain_mongodb_uri_without_srv_or_credentials_is_accepted(self):
-        params = _MongoDBSearchParams.model_validate(
-            {**BASE_PARAMS, "mongodb_connection_string": "mongodb://mongod.internal:27017"}
-        )
-
-        assert params.require_connection_string() == "mongodb://mongod.internal:27017"
-
-    def test_an_unreachable_deployment_names_a_self_managed_remedy(self):
-        from pymongo.errors import ServerSelectionTimeoutError
-
-        config = self._config_that_fails_to_connect(ServerSelectionTimeoutError("connection refused"))
-
-        with pytest.raises(Timeout) as excinfo:
-            _search(config)
-
-        assert "self-managed" in str(excinfo.value)
-        assert "host or port" in str(excinfo.value)
-
-    def test_a_refused_connection_names_a_self_managed_remedy(self):
-        from pymongo.errors import ConnectionFailure
-
-        config = self._config_that_fails_to_connect(ConnectionFailure("connection closed"))
-
-        with pytest.raises(ServiceUnavailableError) as excinfo:
-            _search(config)
-
-        assert "self-managed" in str(excinfo.value)
-        assert "mongod is listening" in str(excinfo.value)
-
-    def test_an_unresolvable_hostname_names_a_self_managed_remedy(self):
-        from pymongo.errors import ConfigurationError
-
-        config = self._config_that_fails_to_connect(ConfigurationError("The DNS query name does not exist"))
-
-        with pytest.raises(BadRequestError) as excinfo:
-            _search(config)
-
-        assert "self-managed" in str(excinfo.value)
-
-    def test_the_missing_index_message_does_not_claim_atlas(self):
-        message = str(missing_index_error(INDEX, "sample_mflix", "embedded_movies"))
-
-        assert "MongoDB Vector Search index" in message
-        assert "Atlas" not in message
-
-    def test_the_not_ready_message_does_not_claim_atlas(self):
-        message = str(index_not_ready_error(INDEX, "sample_mflix", "embedded_movies", "PENDING"))
-
-        assert "MongoDB Vector Search index" in message
-        assert "Atlas" not in message
-
-    def test_the_search_only_refusal_does_not_claim_atlas(self):
-        config = MongoDBVectorStoreConfig()
-
-        with pytest.raises(BadRequestError) as excinfo:
-            config.transform_create_vector_store_request({}, api_base="")
-
-        assert "Atlas" not in str(excinfo.value)
-
-    def test_a_dimension_mismatch_does_not_claim_atlas(self):
-        from pymongo.errors import OperationFailure
-
-        error = OperationFailure("vector field is indexed with 128 dimensions but queried with 256")
-        translated = translate_mongo_error(error, index_name=INDEX, database="db", collection="c")
-
-        assert "Atlas" not in str(translated)
-        assert "dimensions the index was built for" in str(translated)
-
-    def test_an_uncovered_embedding_field_does_not_claim_atlas(self):
-        from pymongo.errors import OperationFailure
-
-        error = OperationFailure("embedding is not indexed as vector")
-        translated = translate_mongo_error(error, index_name=INDEX, database="db", collection="c")
-
-        assert "MongoDB Vector Search index does not cover" in str(translated)
-        assert "Atlas" not in str(translated)
-
-    def test_a_self_managed_auth_failure_is_still_recognised_by_code_18(self):
-        from pymongo.errors import OperationFailure
-
-        error = OperationFailure("Authentication failed.", code=18, details={"code": 18})
-        translated = translate_mongo_error(error, index_name=INDEX, database="db", collection="c")
-
-        assert isinstance(translated, BadRequestError)
-        assert "rejected the credentials" in str(translated)
-
-
-class TestUnescapedCredentialsAreDiagnosed:
-    """Self-managed deployments usually carry a generated password, so '@', '/', ':' and '%' in one
-    are routine. pymongo reports those as a port, a database name or an RFC 3986 complaint, none of
-    which points the operator at their password, so each has to be named for what it is. The errors
-    here come from pymongo's real parser rather than a synthetic stand-in."""
-
-    @staticmethod
-    def _real_parse_error(uri):
-        from pymongo import MongoClient
-
-        try:
-            MongoClient(uri, serverSelectionTimeoutMS=1)
-        except Exception as e:
-            return e
-        raise AssertionError(f"expected {uri!r} to fail parsing")
-
-    def _translated(self, uri):
-        return translate_mongo_error(
-            self._real_parse_error(uri), index_name=INDEX, database="db", collection="c"
-        )
-
-    @pytest.mark.parametrize(
-        "uri",
-        [
-            "mongodb://user:pa@ss@host:27017/",
-            "mongodb://user:pa:ss@host:27017/",
-            "mongodb://user:pa%ss@host:27017/",
-            "mongodb://user@x:pw@host:27017/",
-        ],
-    )
-    def test_rfc_3986_complaints_tell_the_operator_to_encode_the_password(self, uri):
-        translated = self._translated(uri)
-
-        assert isinstance(translated, BadRequestError)
-        assert "percent-encoded per RFC 3986" in str(translated)
-
-    @pytest.mark.parametrize(
-        "uri",
-        ["mongodb://user:pa/ss@host:27017/", "mongodb://user/x:pw@host:27017/"],
-    )
-    def test_a_slash_in_the_credentials_is_not_reported_as_a_database_name(self, uri):
-        translated = self._translated(uri)
-
-        assert isinstance(translated, BadRequestError)
-        assert "percent-encoded per RFC 3986" in str(translated)
-
-    def test_an_unusable_port_names_the_host_and_port_not_the_database(self):
-        translated = self._translated("mongodb://host:99999/")
-
-        assert isinstance(translated, BadRequestError)
-        assert "host and port" in str(translated)
-
-    def test_a_genuinely_bad_database_name_still_mentions_the_uri_path(self):
-        translated = self._translated("mongodb://host:27017/has space")
-
-        assert isinstance(translated, BadRequestError)
-        assert "database name in the URI path" in str(translated)
-
-
-class TestUnreadableTlsFilesAreDiagnosed:
-    """A private CA is how self-managed deployments present TLS, so tlsCAFile and
-    tlsCertificateKeyFile are on-prem options in practice. pymongo opens those files itself and
-    lets OSError out, which is not a PyMongoError, so before this they reached the caller as a 500
-    with a traceback. The errors here come from pymongo's real TLS setup."""
-
-    @staticmethod
-    def _real_tls_error(uri):
-        from pymongo import MongoClient
-
-        try:
-            MongoClient(uri, serverSelectionTimeoutMS=1500).admin.command("ping")
-        except Exception as e:
-            return e
-        raise AssertionError(f"expected {uri!r} to fail")
-
-    def _translated(self, uri):
-        return translate_mongo_error(self._real_tls_error(uri), index_name=INDEX, database="db", collection="c")
-
-    @pytest.mark.parametrize(
-        "path",
-        ["/nonexistent-directory-for-tests/ca.pem", "/tmp"],
-    )
-    def test_an_unreadable_ca_file_is_a_400_naming_the_path(self, path):
-        translated = self._translated(f"mongodb://localhost:27717/?tls=true&tlsCAFile={path}")
-
-        assert isinstance(translated, BadRequestError)
-        assert path in str(translated)
-        assert "tlsCAFile" in str(translated)
-
-    def test_an_unreadable_client_certificate_is_a_400_naming_the_path(self):
-        path = "/nonexistent-directory-for-tests/client.pem"
-        translated = self._translated(f"mongodb://localhost:27717/?tls=true&tlsCertificateKeyFile={path}")
-
-        assert isinstance(translated, BadRequestError)
-        assert path in str(translated)
-
-    def test_an_oserror_carrying_no_filename_is_left_for_the_other_branches(self):
-        translated = translate_mongo_error(OSError("socket hung up"), index_name=INDEX, database="db", collection="c")
-
-        assert not isinstance(translated, BadRequestError)
-
-
-class TestTheCallerSuppliedEmbeddingExecutorIsUsed:
-    """litellm.vector_stores.search always hands a direct provider an embedding_executor, so the
-    provider has to accept it and route the query through it rather than its own default."""
-
-    def test_the_supplied_executor_produces_the_query_vector(self):
-        config, _, collection = _config(embedding=(0.9, 0.9, 0.9), search_indexes=READY_INDEX)
-        caller = FakeEmbeddingExecutor([0.4, 0.5, 0.6])
-
-        config.execute_search_vector_store_request(
-            vector_store_id=INDEX,
-            query="a lone astronaut",
-            vector_store_search_optional_params={},
-            litellm_logging_obj=MagicMock(),
-            litellm_params=BASE_PARAMS,
-            embedding_executor=caller,
-        )
-
-        assert caller.captured.query == "a lone astronaut"
-        assert _stage(collection, "$vectorSearch")["queryVector"] == (0.4, 0.5, 0.6)
-
-    @pytest.mark.asyncio
-    async def test_the_supplied_executor_produces_the_query_vector_on_the_async_path(self):
-        config, _, collection = _async_config(embedding=(0.9, 0.9, 0.9), search_indexes=READY_INDEX)
-        caller = FakeEmbeddingExecutor([0.4, 0.5, 0.6])
-
-        await config.aexecute_search_vector_store_request(
-            vector_store_id=INDEX,
-            query="a lone astronaut",
-            vector_store_search_optional_params={},
-            litellm_logging_obj=MagicMock(),
-            litellm_params=BASE_PARAMS,
-            embedding_executor=caller,
-        )
-
-        assert caller.captured.query == "a lone astronaut"
-        assert _stage(collection, "$vectorSearch")["queryVector"] == (0.4, 0.5, 0.6)
+    assert "obsolete-secret" not in str(error.value)
+    executor.call.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "status,body,error_type",
+    [
+        (400, {"error": {"message": "Index is not queryable"}}, litellm.BadRequestError),
+        (401, {}, litellm.AuthenticationError),
+        (408, {}, litellm.Timeout),
+        (503, {}, litellm.ServiceUnavailableError),
+        (200, {}, litellm.ServiceUnavailableError),
+        (200, {**RESULT, "data": [{"score": "wrong"}]}, litellm.ServiceUnavailableError),
+        (0, {}, litellm.Timeout),
+        (-1, {}, litellm.BadRequestError),
+        (200, RESULT, None),
+    ],
+)
+def test_public_sdk_preserves_http_errors_response_and_timeout(
+    status: int, body: Mapping[str, object], error_type: type[Exception] | None
+) -> None:
+    executor: Final = RecordingEmbeddingExecutor()
+    if status == -1:
+        with pytest.raises(litellm.BadRequestError, match="search-only"):
+            litellm.vector_stores.create(custom_llm_provider="mongodb")
+        executor.call.assert_not_called()
+        return
+
+    def respond(request: httpx.Request) -> httpx.Response:
+        assert request.url == "https://sidecar.example/prefix/v1/vector_stores/policy_index/search"
+        assert request.headers["authorization"] == "Bearer test-sidecar-key"
+        assert request.extensions["timeout"]["read"] == 0.75
+        payload: Final = json.loads(request.content)
+        assert payload["timeout_ms"] == 750
+        assert payload["query_vector"] == [0.1, 0.2, 0.3]
+        if status == 0:
+            raise httpx.ReadTimeout("timed out", request=request)
+        return httpx.Response(status, json=body)
+
+    with httpx.Client(transport=httpx.MockTransport(respond)) as transport:
+        client: Final = HTTPHandler(client=transport)
+        if error_type is not None:
+            with pytest.raises(error_type):
+                litellm.vector_stores.search(
+                    vector_store_id="policy_index",
+                    query="travel policy",
+                    custom_llm_provider="mongodb",
+                    _direct_vector_store_embedding_executor=executor,
+                    client=client,
+                    timeout=0.75,
+                    **BASE_PARAMS,
+                )
+        else:
+            result: Final = litellm.vector_stores.search(
+                vector_store_id="policy_index",
+                query="travel policy",
+                custom_llm_provider="mongodb",
+                _direct_vector_store_embedding_executor=executor,
+                client=client,
+                timeout=0.75,
+                **BASE_PARAMS,
+            )
+            assert result == RESULT
+    executor.call.assert_called_once_with("embedding-alias", "travel policy", {})
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx
index 84a9314ecce..8da7098b695 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx
@@ -69,10 +69,11 @@ describe("VectorStoreForm", () => {
   });
 });
 
-const MONGODB_URI = "mongodb+srv://user:pass@cluster0.mongodb.net";
+const MONGODB_SIDECAR_URL = "http://mongodb-sidecar:8080";
 
 const MONGODB_REQUIRED_FORM_VALUES = {
-  mongodb_connection_string: MONGODB_URI,
+  api_base: MONGODB_SIDECAR_URL,
+  api_key: "sidecar-test-key",
   mongodb_database: "sample_mflix",
   mongodb_collection: "embedded_movies",
   embedding_model: "text-embedding-ada-002",
@@ -127,7 +128,8 @@ describe("buildVectorStoreLitellmParams", () => {
       mongodb_num_candidates: "200",
     };
     const expected = {
-      mongodb_connection_string: MONGODB_URI,
+      api_base: MONGODB_SIDECAR_URL,
+      api_key: "sidecar-test-key",
       mongodb_database: "sample_mflix",
       mongodb_collection: "embedded_movies",
       mongodb_embedding_field: "plot_embedding",
@@ -142,6 +144,7 @@ describe("buildVectorStoreLitellmParams", () => {
   it("sends only mongodb fields when an earlier provider left values in the form", () => {
     const formValues = {
       ...MONGODB_REQUIRED_FORM_VALUES,
+      mongodb_connection_string: "mongodb://obsolete-credentials",
       valkey_host: "left-over-from-valkey.example.com",
       valkey_port: "6379",
       aws_region_name: "us-west-2",
@@ -152,7 +155,8 @@ describe("buildVectorStoreLitellmParams", () => {
     expect(params).not.toHaveProperty("valkey_host");
     expect(params).not.toHaveProperty("valkey_port");
     expect(params).not.toHaveProperty("aws_region_name");
-    expect(params.mongodb_connection_string).toBe(MONGODB_URI);
+    expect(params.api_base).toBe(MONGODB_SIDECAR_URL);
+    expect(params).not.toHaveProperty("mongodb_connection_string");
   });
 
   it("omits a blank mongodb_num_candidates so litellm picks its own candidate count", () => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.tsx b/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.tsx
index 61da25874a5..67ef1b795ba 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.tsx
@@ -70,7 +70,6 @@ const PROVIDER_FIELD_NAMES = [
   "vector_bucket_name",
   "index_name",
   "aws_region_name",
-  "mongodb_connection_string",
   "mongodb_database",
   "mongodb_collection",
   "mongodb_embedding_field",
@@ -107,7 +106,6 @@ const vectorStoreShape = {
   vector_bucket_name: optionalText,
   index_name: optionalText,
   aws_region_name: optionalText,
-  mongodb_connection_string: optionalText,
   mongodb_database: optionalText,
   mongodb_collection: optionalText,
   mongodb_embedding_field: optionalText,
@@ -142,7 +140,7 @@ const VECTOR_STORE_ID_PLACEHOLDERS: Record<string, string> = {
   vertex_rag_engine: '6917529027641081856 (corpus ID from Vertex AI / "RAG Engine" console)',
   "vertex_ai/search_api": 'my-datastore_1234567890 (data store ID from Vertex AI / "Agent Search" console)',
   valkey: "my-search-index (FT index name in Valkey)",
-  mongodb: "my-vector-index (Atlas Vector Search index name)",
+  mongodb: "my-vector-index (MongoDB Vector Search index name)",
 };
 
 const VERTEX_SEARCH_API_WITH_ENGINE_PLACEHOLDER = "Any identifier you'll use to reference this in LiteLLM";
diff --git a/ui/litellm-dashboard/src/components/vector_store_providers.test.tsx b/ui/litellm-dashboard/src/components/vector_store_providers.test.tsx
index 8e3a3aa3402..32d0f5dccc0 100644
--- a/ui/litellm-dashboard/src/components/vector_store_providers.test.tsx
+++ b/ui/litellm-dashboard/src/components/vector_store_providers.test.tsx
@@ -35,7 +35,8 @@ describe("getVectorStoreProviderLogoAndName", () => {
     });
     expect(vectorStoreProviderMap.MongoDB).toBe("mongodb");
     expect(getProviderSpecificFields("mongodb").map((field) => field.name)).toEqual([
-      "mongodb_connection_string",
+      "api_base",
+      "api_key",
       "mongodb_database",
       "mongodb_collection",
       "embedding_model",
@@ -45,12 +46,10 @@ describe("getVectorStoreProviderLogoAndName", () => {
     ]);
   });
 
-  it("hides the mongodb connection string, which carries the database password", () => {
-    const connectionString = getProviderSpecificFields("mongodb").find(
-      (field) => field.name === "mongodb_connection_string",
-    );
+  it("hides the mongodb sidecar API key", () => {
+    const apiKey = getProviderSpecificFields("mongodb").find((field) => field.name === "api_key");
 
-    expect(connectionString).toMatchObject({ type: "password", required: true });
+    expect(apiKey).toMatchObject({ type: "password", required: true });
   });
 
   it("picks the mongodb embedding model from the proxy's models rather than a fixed list", () => {
diff --git a/ui/litellm-dashboard/src/components/vector_store_providers.tsx b/ui/litellm-dashboard/src/components/vector_store_providers.tsx
index a75f10771a8..6a8b2f405d2 100644
--- a/ui/litellm-dashboard/src/components/vector_store_providers.tsx
+++ b/ui/litellm-dashboard/src/components/vector_store_providers.tsx
@@ -14,7 +14,7 @@ export enum VectorStoreProviders {
   OpenAI = "OpenAI",
   Azure = "Azure OpenAI",
   Milvus = "Milvus",
-  MongoDB = "MongoDB Atlas",
+  MongoDB = "MongoDB (BETA)",
   Valkey = "Valkey",
 }
 
@@ -175,18 +175,25 @@ export const vectorStoreProviderFields: Record<string, VectorStoreFieldConfig[]>
   ],
   mongodb: [
     {
-      name: "mongodb_connection_string",
-      label: "Connection String",
-      tooltip:
-        "The full MongoDB connection string for your Atlas cluster, including the database user and password. Copy it from Atlas under Connect, Drivers (e.g. mongodb+srv://user:password@cluster.mongodb.net)",
-      placeholder: "mongodb+srv://user:password@cluster.mongodb.net",
+      name: "api_base",
+      label: "Sidecar URL",
+      tooltip: "The URL of your separately deployed MongoDB sidecar. Configure MongoDB credentials in the sidecar",
+      placeholder: "http://mongodb-sidecar:8080",
+      required: true,
+      type: "text",
+    },
+    {
+      name: "api_key",
+      label: "Sidecar API Key",
+      tooltip: "The MONGODB_SIDECAR_API_KEY configured in your MongoDB sidecar",
+      placeholder: "Enter sidecar API key",
       required: true,
       type: "password",
     },
     {
       name: "mongodb_database",
       label: "Database",
-      tooltip: "The Atlas database holding the collection you want to search",
+      tooltip: "The MongoDB database holding the collection you want to search",
       placeholder: "sample_mflix",
       required: true,
       type: "text",
@@ -194,7 +201,7 @@ export const vectorStoreProviderFields: Record<string, VectorStoreFieldConfig[]>
     {
       name: "mongodb_collection",
       label: "Collection",
-      tooltip: "The collection your Atlas Vector Search index was built on",
+      tooltip: "The collection your MongoDB Vector Search index was built on",
       placeholder: "embedded_movies",
       required: true,
       type: "text",
@@ -212,7 +219,7 @@ export const vectorStoreProviderFields: Record<string, VectorStoreFieldConfig[]>
       name: "mongodb_embedding_field",
       label: "Vector Field Name",
       tooltip:
-        "The field in each document that holds its embedding. It must match the path your Atlas Vector Search index was created on (default: embedding)",
+        "The field in each document that holds its embedding. It must match the path your MongoDB Vector Search index was created on (default: embedding)",
       placeholder: "embedding",
       required: false,
       type: "text",
@@ -232,7 +239,7 @@ export const vectorStoreProviderFields: Record<string, VectorStoreFieldConfig[]>
       name: "mongodb_num_candidates",
       label: "Candidates Considered",
       tooltip:
-        "How many nearest neighbours Atlas examines before returning the top results. Higher is more accurate and slower. Leave blank to let LiteLLM scale it with the requested result count",
+        "How many nearest neighbours MongoDB examines before returning the top results. Higher is more accurate and slower. Leave blank to let LiteLLM scale it with the requested result count",
       placeholder: "100",
       required: false,
       type: "text",
diff --git a/uv.lock b/uv.lock
index 89205cd9527..ce5d96f4d9c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -10,7 +10,7 @@ resolution-markers = [
 ]
 
 [options]
-exclude-newer = "2026-09-02T16:58:34.594994Z"
+exclude-newer = "2026-09-05T05:15:35.833796Z"
 exclude-newer-span = "P3D"
 
 [manifest]
@@ -4415,9 +4415,6 @@ mcp = [
 mlflow = [
     { name = "mlflow" },
 ]
-mongodb = [
-    { name = "pymongo" },
-]
 proxy = [
     { name = "apscheduler" },
     { name = "azure-identity" },
@@ -4649,7 +4646,6 @@ requires-dist = [
     { name = "pydantic", specifier = ">=2.10.0,<3.0.0" },
     { name = "pydantic-settings", specifier = ">=2.14.1,<3.0" },
     { name = "pyjwt", marker = "extra == 'proxy'", specifier = ">=2.13.0,<3.0" },
-    { name = "pymongo", marker = "extra == 'mongodb'", specifier = ">=4.9,<5.0" },
     { name = "pynacl", marker = "extra == 'proxy'", specifier = ">=1.6.2,<2.0" },
     { name = "pypdf", marker = "extra == 'proxy-runtime'", specifier = ">=6.16.1,<7.0" },
     { name = "pyroscope-io", marker = "sys_platform != 'win32' and extra == 'proxy'", specifier = ">=0.8.16,<1.0" },
@@ -4676,7 +4672,7 @@ requires-dist = [
     { name = "uvloop", marker = "sys_platform != 'win32' and extra == 'proxy'", specifier = ">=0.22.1,<1.0" },
     { name = "websockets", marker = "extra == 'proxy'", specifier = ">=15.0.1,<16.0" },
 ]
-provides-extras = ["proxy", "cli", "extra-proxy", "utils", "caching", "mcp", "mongodb", "saml", "semantic-router", "mlflow", "grpc", "stt-nvidia-riva", "google", "bedrock-realtime", "proxy-runtime"]
+provides-extras = ["proxy", "cli", "extra-proxy", "utils", "caching", "mcp", "saml", "semantic-router", "mlflow", "grpc", "stt-nvidia-riva", "google", "bedrock-realtime", "proxy-runtime"]
 
 [package.metadata.requires-dev]
 ci = [
@@ -7620,77 +7616,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d5/6f/9ac2548e290764781f9e7e2aaf0685b086379dabfb29ca38536985471eaf/pylint-4.0.5-py3-none-any.whl", hash = "sha256:00f51c9b14a3b3ae08cff6b2cdd43f28165c78b165b628692e428fb1f8dc2cf2", size = 536694, upload-time = "2026-02-20T09:07:31.028Z" },
 ]
 
-[[package]]
-name = "pymongo"
-version = "4.17.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "dnspython" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/ca/64/50be6fbac9c79fe2e4c17401a467da2d8764d82833d83cec325afe5cab32/pymongo-4.17.0.tar.gz", hash = "sha256:70ffa08ba641468cc068cf46c06b34f01a8ce3489f6411309fcb5ceabe6b2fc0", size = 2523370, upload-time = "2026-04-20T16:39:53.524Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/c9/77/28ebbf69772a4341d530831c7a006cdb06877ac23075cb53b0a227df4fe1/pymongo-4.17.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:47b021363cd923ace5edc7a1d63c0ff8a6d9d43859b8a1ba23645f5afae63221", size = 819234, upload-time = "2026-04-20T16:37:20.888Z" },
-    { url = "https://files.pythonhosted.org/packages/88/cf/5a70cee503ff9a2fea20607607f14d189f4d975960ac0945ec306ee7b695/pymongo-4.17.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:422fa50d7d7f5c22ea0953554396c9ef95684a2d775f860bd75a7b510538dfca", size = 819969, upload-time = "2026-04-20T16:37:24.187Z" },
-    { url = "https://files.pythonhosted.org/packages/23/d5/07b7e27e662c58d872efd104a0e8055eb6569aa1b6d4da436f3fdee7f897/pymongo-4.17.0-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:addd0498ebbdc6354227f6ed457ed9fce442d48a3bb30d5b5bad33e104996561", size = 1244510, upload-time = "2026-04-20T16:37:26.069Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/be/7cac5b1e89bd5a8e395067648241390321593a7c29243e36f91343c02a90/pymongo-4.17.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c5c8e180cb2cabe37300e1e36c60aa4f2ff956cc579f0142135a5d2cba252243", size = 1263245, upload-time = "2026-04-20T16:37:28.003Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/20/40e8e99824c1fda18261411e65ce3b0cd3d9a6ed3c056cdd0a569adc870b/pymongo-4.17.0-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:bd835cdb37a1adec359dd072c24f8bb14809e2644fde86fab4ee2fc9719b9483", size = 1304113, upload-time = "2026-04-20T16:37:30.048Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/94/fb7e25441dd66f2069a9b172380849b0eaa5881c18b3db217bf64a6d393c/pymongo-4.17.0-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c4979e7e8887862bbb44d203f00cc8263a3f27237876fa691b6beba23e40e6d8", size = 1297046, upload-time = "2026-04-20T16:37:32.054Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/c9/7352e0c20fe772541556e4d283c05e07ec48f8b0d2737ad930ac4a1b6655/pymongo-4.17.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:77aa4bc164b4de60d5db193b322f0f5b6ead716e831031bfdef8e8bd92205556", size = 1265708, upload-time = "2026-04-20T16:37:33.934Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/e4/3df15494c2015ed297958517f0e4f6493e21b00990748068a973e66d45e0/pymongo-4.17.0-cp310-cp310-win32.whl", hash = "sha256:48bbc576677b50af043df870d84ded67cc3a9b4aa7553201beef4da5dc050a0a", size = 805533, upload-time = "2026-04-20T16:37:35.744Z" },
-    { url = "https://files.pythonhosted.org/packages/22/fa/b4e71bb8cb82ad7d21bb4e8c476f2d573ba68b20368aac36ef06e4a196b4/pymongo-4.17.0-cp310-cp310-win_amd64.whl", hash = "sha256:e46767f28dea610e02edf6c5d956ce615c3c7790ea396660b9b1efd5c5ead2e0", size = 815677, upload-time = "2026-04-20T16:37:37.808Z" },
-    { url = "https://files.pythonhosted.org/packages/22/e2/0a4bba644f1cda3970ea1012149eeae3594ebfeed3f81fdaf32b61d90c95/pymongo-4.17.0-cp310-cp310-win_arm64.whl", hash = "sha256:757f2a4c0c2c46cab87df0333681ce69e86c9d5b45bc5203ceba5410b3489e59", size = 807293, upload-time = "2026-04-20T16:37:39.707Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/e2/336d86f221cf1b56b2ed9330d4a3b98f9f38f0b37829ae9a9184617d5419/pymongo-4.17.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4141e6c6a339789b2974efa00ecd9409101672d77a0e3ee2cc3839eedf8ec4df", size = 874668, upload-time = "2026-04-20T16:37:41.39Z" },
-    { url = "https://files.pythonhosted.org/packages/34/8e/75d3c6c935d187ab59c61e9c15d9aab3f274b563eaf1706e8cae5f508dec/pymongo-4.17.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:e68c76b84e0c132d9dbf9307f12ff8185702328187a87b9aca8c941303873433", size = 875294, upload-time = "2026-04-20T16:37:43.432Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/ec/62e855744489dbcd54fd778aae4d80fa4c4819e8fb228ca0cf6f21a03997/pymongo-4.17.0-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:ba2195d4f386f839a52a23ea1cfd60ffaaba78a3d7841db51b7e433001139918", size = 1496233, upload-time = "2026-04-20T16:37:45.518Z" },
-    { url = "https://files.pythonhosted.org/packages/82/e8/93e4e5e5ce8fdf8929dabeefe24aafa5ce046028eed0dfa8eeb936e72c49/pymongo-4.17.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8446ff4bfcb6ec2a2e50998c860986a1e992136f998b7f53e7a717fb8aa5a0b9", size = 1522927, upload-time = "2026-04-20T16:37:47.492Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/ca/425dc1d21e0f17bdea0072fc463f662f7fa06d2852af52975c9eced3c07c/pymongo-4.17.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2a0d5ac205728c86e0a02192f1aa5f865b0d7d51f8df6101c01a69a7fc620d72", size = 1583468, upload-time = "2026-04-20T16:37:49.221Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/9d/f08b07eeffda1a43c1759f0fa625e88ae12360996eb56d42aad832fa7dff/pymongo-4.17.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:485c8a8eaa4c739f00a331fc73757898ee7c092c214a79e63866ff76aaf282ff", size = 1572787, upload-time = "2026-04-20T16:37:51.061Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/c2/6855a07aafa7b894929af23675b6fb9634800ce43122b76a62f6eeb8da2a/pymongo-4.17.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b2dfcc795f5b9fedbe179a11fdf6051581479d196582a3fe819a92a00e9b9969", size = 1526184, upload-time = "2026-04-20T16:37:53.358Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/05/c952bac7db71c1942ea3559fcd308b49754cc5004b455935fb4000d1f37b/pymongo-4.17.0-cp311-cp311-win32.whl", hash = "sha256:c2292144505fb12156b981bd440f3dc994a883da06ac726c0c8692ccdbc1c510", size = 852621, upload-time = "2026-04-20T16:37:55.28Z" },
-    { url = "https://files.pythonhosted.org/packages/11/c0/c04da9f4c0c6252404598f4e394b862a58a9e866822a70ae261c8a018fdf/pymongo-4.17.0-cp311-cp311-win_amd64.whl", hash = "sha256:2e190827834fce70ecdf9d46796c6dbc0ce08ea87dc2ff5bc6f3f5579b605cb9", size = 867852, upload-time = "2026-04-20T16:37:57.233Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/b2/c7b4870fbeef471e947d3e014676f5910d02e0197074d692ebcf24ec049a/pymongo-4.17.0-cp311-cp311-win_arm64.whl", hash = "sha256:a8f9c40a09bb7d4b9fc8b1da65ecf6efa79bda5cb2756f39d9b6940fac1d19ae", size = 855019, upload-time = "2026-04-20T16:37:58.983Z" },
-    { url = "https://files.pythonhosted.org/packages/98/90/60bcb508840135d5ee46b51b1a950f548338aa8145a8366dbe6639ae51ac/pymongo-4.17.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d53ffa94b2340dbf6b055e09a0090618c60482c158ecfc9565642fc996bf0944", size = 930529, upload-time = "2026-04-20T16:38:00.936Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/e9/313840f1e52c6dfac47f704428cbfbce59956ebe7633bffc92b03f74f0ad/pymongo-4.17.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6fe0de9d0f6791abce3471230b32b4817bf89d27b1182b6a550e1ec0fa72aa9a", size = 930665, upload-time = "2026-04-20T16:38:02.915Z" },
-    { url = "https://files.pythonhosted.org/packages/78/35/9d3565ea45b1606f635c1e2cd2563c28d66caafdc50f7ad7d979fcd1b363/pymongo-4.17.0-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:e537e95514dae1aaa718f481ec03151a0f0394bcd05f1322896d8fc1330cb729", size = 1762369, upload-time = "2026-04-20T16:38:05.375Z" },
-    { url = "https://files.pythonhosted.org/packages/95/ee/149b0d4b1a11c38bff6f14c23d5814c9b0843fd6dc38ad40596bdb1a62d2/pymongo-4.17.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:37a8385c29881b43eab31f584100fa0eaddedd5607adf010147ba1810118be90", size = 1798044, upload-time = "2026-04-20T16:38:07.195Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/d4/4cee4a7b8d8f6f0550ef6cd2fea42455c5ed619a220cb6ba4fb40d6a5bc8/pymongo-4.17.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f3ee3d241ed77a4fc99ce3cff3b289c3ebce37f61fdd7349d3592c23b82c8784", size = 1878567, upload-time = "2026-04-20T16:38:09.121Z" },
-    { url = "https://files.pythonhosted.org/packages/45/ef/7fe366c84952619ee2f69973566c214775e083dd4df465751912153e4b72/pymongo-4.17.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:9eb5d63a3c518cb0804ed678f5e2b875af032d89a7cf57a57360322cf6a4d222", size = 1864881, upload-time = "2026-04-20T16:38:10.896Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/35/b577d82c6d1be7aee7ac7e249bc86f7847998345042e5f8360de238e177b/pymongo-4.17.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8e97e03fa13327c87e3fdc5656acd01e71817f0c1dc3221cd8f30de136bf4ec3", size = 1800349, upload-time = "2026-04-20T16:38:13.589Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/69/dafcf04f66e130ddd91aeb92e7a692480eda46dcd04ec1dbe82c06619e10/pymongo-4.17.0-cp312-cp312-win32.whl", hash = "sha256:6877214bff5f06f6884a9fc8d9016a4a7a5f51f537f5c51ac3a576f93e7dfb32", size = 900518, upload-time = "2026-04-20T16:38:15.541Z" },
-    { url = "https://files.pythonhosted.org/packages/11/35/5c9262a459f988b4eb2605f70815240b77a0d4131136c4326d18f1822b89/pymongo-4.17.0-cp312-cp312-win_amd64.whl", hash = "sha256:9828485f72f63c7d802e0ec41f71906f633c2692621ab3af55ca990186b091b1", size = 920335, upload-time = "2026-04-20T16:38:17.665Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/da/e9c7265ee176faccf4e52c4797837e794d93569a1046f6b19a4acc36e5ad/pymongo-4.17.0-cp312-cp312-win_arm64.whl", hash = "sha256:1195370a77baf003b59b10e91ecc4706297197f0dd9d29c840cc556dc08f7cee", size = 903289, upload-time = "2026-04-20T16:38:19.33Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/6b/c1206879708b94e82fcd8b9653440ec271f79a3674d122192df383047f5a/pymongo-4.17.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:809ec74de3b9148ae43fa8df9faf53470f511c8d384f13b99d6f671f2a379f15", size = 985829, upload-time = "2026-04-20T16:38:21.031Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/cf/bb044ed85160e5c40f568c7c4f4e8ea16f40764ff5d302e5befbe8f6f814/pymongo-4.17.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a431b737816bf4cddd4fa0fcef04e424ad36b7692734a64150f872fb8f3208be", size = 985899, upload-time = "2026-04-20T16:38:23.409Z" },
-    { url = "https://files.pythonhosted.org/packages/74/0a/f6dfd5ea3901e5d6888da8de8ba728971a1d447debab681cfc56f90d1208/pymongo-4.17.0-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:e4fab10f8403169ce92f3cea921609d9ee81107306caae06c08f592d4b8ad2b5", size = 2028569, upload-time = "2026-04-20T16:38:25.343Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/c5/081f59a1c02ae8c0dc73ae58e563838c44eec81aeafa7d0b93a637841c9b/pymongo-4.17.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:20323b0b1c1d33770ad1fc68d429c757734ce9ad3594421c3d6618f10572b1b9", size = 2072916, upload-time = "2026-04-20T16:38:27.291Z" },
-    { url = "https://files.pythonhosted.org/packages/31/42/6e41d434297ffe8b30d9c3717916591a4a7be9075a0dcc2fafdfaaaa62ed/pymongo-4.17.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:5a5de048e6da5c18e27cc2437e8c15b3b0cdc8385c15b41178b0caa3322a09c2", size = 2173234, upload-time = "2026-04-20T16:38:29.474Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/cf/1e4a7db352ef9485831c7268dfe8402f0117b32a9ad54b16e810699e3617/pymongo-4.17.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:dff3de1294fbbc1db0ba6b511f77b8e540601d092538a31312e99c8a91a78b1e", size = 2156784, upload-time = "2026-04-20T16:38:32.134Z" },
-    { url = "https://files.pythonhosted.org/packages/12/10/6195be29962a61ebb5f4bd9e4c7519890b172f7968a0a0d880398c6ddb02/pymongo-4.17.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:faf03e4c2aafd6de626dbd30ba246d369ae33f47f10629d1bbe40f72115027a6", size = 2074446, upload-time = "2026-04-20T16:38:34.004Z" },
-    { url = "https://files.pythonhosted.org/packages/37/48/33410b8819837ed370c738587306bdf060b59cef11823be212f4a07703c5/pymongo-4.17.0-cp313-cp313-win32.whl", hash = "sha256:c9786665926a09630c5d420c79762cfadbff35a9438bcbc4c81a9fb5ab9228b7", size = 948435, upload-time = "2026-04-20T16:38:35.922Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/77/c0ed522f798a286b99acaa7914ed8d9c80ab091f97f57c59ffed72906e5e/pymongo-4.17.0-cp313-cp313-win_amd64.whl", hash = "sha256:5960519b4d7168f1ecdd3ea10c81b2aedeb9423651aca953cfbc8e76705d3b38", size = 972847, upload-time = "2026-04-20T16:38:37.888Z" },
-    { url = "https://files.pythonhosted.org/packages/97/f0/c39480a2db385fde23861d0c8acda41cdaf1d43e46579db72c5c013a2e81/pymongo-4.17.0-cp313-cp313-win_arm64.whl", hash = "sha256:0ff6bd2f735ab5356541e3e57d5b7dbfbc3f2ee1ccb10b6b0f82d58af69d1d8e", size = 951575, upload-time = "2026-04-20T16:38:40.544Z" },
-    { url = "https://files.pythonhosted.org/packages/da/49/2b0250762a89737ed6f9cea238331baca061b89a8ddd10dd17fee52c3970/pymongo-4.17.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:ff5aa3f1c7e3f08eb0e7a016c91ba468b1850ccfd63d9b1f12f56350f4974cef", size = 1040945, upload-time = "2026-04-20T16:38:42.783Z" },
-    { url = "https://files.pythonhosted.org/packages/89/1c/7a9b5447a08be20e84b6e5b17330917e8d6d9507daa3cd099a9309f11ad7/pymongo-4.17.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:e816db649ba5d7de0568cf3a9f287a9dc9aad21cf0ca667ab156a7ef47fca0b0", size = 1041187, upload-time = "2026-04-20T16:38:45.358Z" },
-    { url = "https://files.pythonhosted.org/packages/78/a1/71704f61632dfc90407a5834fe5f6132854937c4a3648f6c05c351d85a45/pymongo-4.17.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:12c4fded3a9f1d6a687e36ebd384ac6d00b9b00de1969aa74048e7051ec2a713", size = 2294806, upload-time = "2026-04-20T16:38:47.734Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/b9/aff42be75108b96c2469b1d9329b912c15108f3e7ef32fdc86da8423c330/pymongo-4.17.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2db66aa8dd253a0fc1fad3b0d23d5b3993f7ebde02fbbd7727128debf2853675", size = 2348231, upload-time = "2026-04-20T16:38:50.371Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/30/44c115b8ba1479942c15fd9480eb29a7da0ba68acd56983423ba0deb4a94/pymongo-4.17.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3987e96e7c7be4083d42e8ac2cc6c0d5b78db9973c90fce42ae800b616ca6b20", size = 2467614, upload-time = "2026-04-20T16:38:52.665Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/84/21ee95c8bf0ca7acae7ec7eb365d740bf8fc0156c194baf2c3bdfcb85ec0/pymongo-4.17.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:cee36b3c0d0354f880fa7a7fdcdaf2bb5e542c2281e25c1bfadf8cfe21eba7d2", size = 2445970, upload-time = "2026-04-20T16:38:55.175Z" },
-    { url = "https://files.pythonhosted.org/packages/06/89/081d7f1809d5ca09d1e47e49f2111b245f5694de3a7af32cd3a353a6f43f/pymongo-4.17.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:320b34457b20bbcc79997801f95d25ce00472915ca5241167242b42c4359e027", size = 2348605, upload-time = "2026-04-20T16:38:57.557Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/c3/0d949f9d3f2a341c1f635c398c16615e96f89f51ff424ed81e914cf1a4de/pymongo-4.17.0-cp314-cp314-win32.whl", hash = "sha256:df4a644af9ae132d4bfdb2e9516ea51a615fd881caddfbfbd071cf1354844479", size = 1004119, upload-time = "2026-04-20T16:39:00.309Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/55/5c3a3db1048054c695c75c5964cc8bedc2247fdb5a75ef6fab4ec8bb013e/pymongo-4.17.0-cp314-cp314-win_amd64.whl", hash = "sha256:c797f8a80957134f6dd9690367a0f8f5906d672119af2c6aa55f0c527b656bed", size = 1032314, upload-time = "2026-04-20T16:39:02.665Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/19/e235f39906134cb0ffd5574c5a59c355ef5380f0499644ab94994afbb109/pymongo-4.17.0-cp314-cp314-win_arm64.whl", hash = "sha256:68fca71e05ee5da23a8d73cee8379dfb3d26e609a377cae731d742771ed96946", size = 1007627, upload-time = "2026-04-20T16:39:04.678Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/e0/c4c1a86791415b14c684fa0908f9da96de91594a3fd1fa1b8dc689fbb800/pymongo-4.17.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:b4384700cffc3f1dd98e088bc0072dedf6d7d68a230bb4b972665cf69c071c1e", size = 1099151, upload-time = "2026-04-20T16:39:06.969Z" },
-    { url = "https://files.pythonhosted.org/packages/81/4b/69c67f3e23fd9b23b9bedc7ebd23754881cc9d5c5d5b2a9811e96b07f475/pymongo-4.17.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:93641192644fa1ee0f34030e774fd31022a27ad11ba22cb1716142231524f8bd", size = 1099346, upload-time = "2026-04-20T16:39:08.996Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/19/a5208f62f9508a26d73acc69bd3821b8c8adae253679a3c26d2f9652f0d5/pymongo-4.17.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:75bc3aa5b94fdb7138d357ec6ca61cd97e0c79f4f7f0bd3efe9639b15cc50942", size = 2619034, upload-time = "2026-04-20T16:39:11.049Z" },
-    { url = "https://files.pythonhosted.org/packages/77/27/426cba1ec5973082a56d4150798529bfdf4151c31391ed1fbbecb23ef2ac/pymongo-4.17.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:50e8f8e23c6df7c6d6929f5e734980b227706e73ee847517c9ba5af90f7fc466", size = 2689939, upload-time = "2026-04-20T16:39:13.617Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/2e/f70993d1255e33f6ee59a4ec4371cc65bff7a7e3fda7d55c3386f25287e8/pymongo-4.17.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:15d3f3d732aecac1f8d481bde4029755615639bd3076f258a2147210aec8515a", size = 2824994, upload-time = "2026-04-20T16:39:16.057Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/eb/87b0e988ba889e1fcc3430c2cfc166b251872c813e92b43174298bee17ff/pymongo-4.17.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:6c5f62862d0f87be481fa1fe8cb811994486773c94a2b61e509285e3f2890763", size = 2801745, upload-time = "2026-04-20T16:39:18.476Z" },
-    { url = "https://files.pythonhosted.org/packages/67/4c/3f83412d086f682d4d468761d66ddc49cf161e786ea74073045eb4491c60/pymongo-4.17.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:64837adbbd72073301af51bb0fc80e3d7707fe5527cea1033ba0320f0b2f881b", size = 2684636, upload-time = "2026-04-20T16:39:20.878Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/d8/b75f6f4ab6c8beb50b0270a4f1e2530b5774f5e116563440e1677ca1820f/pymongo-4.17.0-cp314-cp314t-win32.whl", hash = "sha256:b93b22eedc62598cf5ee9d8c8007a8e9121c50fd88137012d8985500e9dc3151", size = 1056356, upload-time = "2026-04-20T16:39:22.996Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/5e/648c8a238eef18a25ed8a169ea6542d4a860bbec3e95b3d9badac2935c71/pymongo-4.17.0-cp314-cp314t-win_amd64.whl", hash = "sha256:3689ea34f6b647c7d1e7bdc60fcfb214b2789ed1359a7fb96569c69f50e5f18f", size = 1090964, upload-time = "2026-04-20T16:39:24.989Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/cb/d9780b66939c4fc1f024bcc7be23a2abcfe06a9745ca8fa76dc73395482e/pymongo-4.17.0-cp314-cp314t-win_arm64.whl", hash = "sha256:9543d8f84c2e5608565c08ac679774811e6730770d8a645439b073422a4276fb", size = 1058526, upload-time = "2026-04-20T16:39:27.924Z" },
-]
-
 [[package]]
 name = "pynacl"
 version = "1.6.2"

From 0c519b162f2ca44effc7ff5bd14d80e9cb8935ae Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Mon, 7 Sep 2026 23:43:21 -0700
Subject: [PATCH 13/31] fix: preserve MongoDB deadlines and secure remote
 sidecar transport

---
 .../mongodb/vector_stores/transformation.py   |  19 ++-
 .../test_mongodb_transformation.py            | 114 ++++++++++++------
 .../_components/VectorStoreForm.test.tsx      |   2 +-
 .../src/components/vector_store_providers.tsx |   4 +-
 4 files changed, 97 insertions(+), 42 deletions(-)

diff --git a/litellm/llms/mongodb/vector_stores/transformation.py b/litellm/llms/mongodb/vector_stores/transformation.py
index 92965ab745b..606da9cffb4 100644
--- a/litellm/llms/mongodb/vector_stores/transformation.py
+++ b/litellm/llms/mongodb/vector_stores/transformation.py
@@ -1,4 +1,5 @@
 from collections.abc import Mapping, Sequence
+from ipaddress import ip_address
 from math import isfinite
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Final, Literal, NoReturn
@@ -196,7 +197,7 @@ class MongoDBVectorStoreConfig(BaseQueryEmbeddingVectorStoreConfig):
 
     def get_complete_url(self, api_base: str | None, litellm_params: dict[str, object]) -> str:
         if not api_base:
-            raise config_error("MongoDB sidecar api_base is required, for example http://mongodb-sidecar:8080.")
+            raise config_error("MongoDB sidecar api_base is required, for example http://127.0.0.1:8080.")
         try:
             parsed: Final = urlsplit(api_base)
             valid: Final = parsed.scheme in ("http", "https") and bool(parsed.hostname) and parsed.port != 0
@@ -206,6 +207,17 @@ class MongoDBVectorStoreConfig(BaseQueryEmbeddingVectorStoreConfig):
             raise config_error(
                 "MongoDB sidecar api_base must be an HTTP or HTTPS URL without credentials, query, or fragment."
             )
+        if parsed.scheme == "http":
+            try:
+                loopback: Final = ip_address(parsed.hostname or "").is_loopback
+            except ValueError:
+                raise config_error(
+                    "MongoDB sidecar requires HTTPS. HTTP is supported only for a loopback IP such as 127.0.0.1."
+                ) from None
+            if not loopback:
+                raise config_error(
+                    "MongoDB sidecar requires HTTPS. HTTP is supported only for a loopback IP such as 127.0.0.1."
+                )
         return api_base.rstrip("/")
 
     @staticmethod
@@ -215,7 +227,10 @@ class MongoDBVectorStoreConfig(BaseQueryEmbeddingVectorStoreConfig):
             return 30_000
         if not isinstance(seconds, (int, float)) or not isfinite(seconds) or seconds <= 0:
             raise config_error("MongoDB search timeout must be a positive finite number.")
-        return max(1, min(int(seconds * 1000), 30_000))
+        try:
+            return max(1, int(seconds * 1000))
+        except (ValueError, OverflowError):
+            raise config_error("MongoDB search timeout must be a positive finite number.") from None
 
     @classmethod
     def _params(
diff --git a/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py b/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py
index bca2b544673..9de473fb1f0 100644
--- a/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py
+++ b/tests/test_litellm/llms/mongodb/vector_stores/test_mongodb_transformation.py
@@ -7,10 +7,10 @@ import httpx
 import pytest
 
 import litellm
-from litellm.llms.custom_httpx.http_handler import HTTPHandler
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler, HTTPHandler
 from litellm.llms.mongodb.vector_stores.transformation import MongoDBVectorStoreConfig
 from litellm.types.utils import EmbeddingResponse
-from litellm.types.vector_stores import VectorStoreSearchOptionalRequestParams
+from litellm.types.vector_stores import VectorStoreSearchOptionalRequestParams, VectorStoreSearchResponse
 
 BASE_PARAMS: Final = {
     "api_base": "https://sidecar.example/prefix",
@@ -131,52 +131,92 @@ def test_invalid_search_is_rejected_before_embedding(
         (200, {**RESULT, "data": [{"score": "wrong"}]}, litellm.ServiceUnavailableError),
         (0, {}, litellm.Timeout),
         (-1, {}, litellm.BadRequestError),
+        (-2, {"api_base": "http://sidecar.example"}, litellm.BadRequestError),
+        (-2, {"api_base": "http://10.0.0.10:8080"}, litellm.BadRequestError),
+        (-2, {"api_base": "http://localhost:8080"}, litellm.BadRequestError),
         (200, RESULT, None),
     ],
 )
-def test_public_sdk_preserves_http_errors_response_and_timeout(
-    status: int, body: Mapping[str, object], error_type: type[Exception] | None
+@pytest.mark.parametrize("asynchronous", [False, True])
+@pytest.mark.parametrize("timeout", [0.75, 120.0])
+@pytest.mark.parametrize("api_base", ["https://sidecar.example/prefix", "http://127.0.0.1:8080", "http://[::1]:8080"])
+@pytest.mark.asyncio
+async def test_public_sdk_preserves_http_errors_response_and_timeout(
+    status: int,
+    body: Mapping[str, object],
+    error_type: type[Exception] | None,
+    asynchronous: bool,
+    timeout: float,
+    api_base: str,
 ) -> None:
     executor: Final = RecordingEmbeddingExecutor()
     if status == -1:
-        with pytest.raises(litellm.BadRequestError, match="search-only"):
-            litellm.vector_stores.create(custom_llm_provider="mongodb")
-        executor.call.assert_not_called()
+        if asynchronous:
+            with pytest.raises(litellm.BadRequestError, match="search-only"):
+                await litellm.vector_stores.acreate(custom_llm_provider="mongodb")
+        else:
+            with pytest.raises(litellm.BadRequestError, match="search-only"):
+                litellm.vector_stores.create(custom_llm_provider="mongodb")
         return
-
-    def respond(request: httpx.Request) -> httpx.Response:
-        assert request.url == "https://sidecar.example/prefix/v1/vector_stores/policy_index/search"
-        assert request.headers["authorization"] == "Bearer test-sidecar-key"
-        assert request.extensions["timeout"]["read"] == 0.75
-        payload: Final = json.loads(request.content)
-        assert payload["timeout_ms"] == 750
-        assert payload["query_vector"] == [0.1, 0.2, 0.3]
-        if status == 0:
-            raise httpx.ReadTimeout("timed out", request=request)
-        return httpx.Response(status, json=body)
-
-    with httpx.Client(transport=httpx.MockTransport(respond)) as transport:
-        client: Final = HTTPHandler(client=transport)
-        if error_type is not None:
-            with pytest.raises(error_type):
+    if status == -2:
+        rejected_params: Final = {**BASE_PARAMS, "api_base": str(body["api_base"])}
+        if asynchronous:
+            with pytest.raises(litellm.BadRequestError, match="requires HTTPS"):
+                await litellm.vector_stores.asearch(
+                    vector_store_id="policy_index",
+                    query="travel policy",
+                    custom_llm_provider="mongodb",
+                    _direct_vector_store_embedding_executor=executor,
+                    **rejected_params,
+                )
+        else:
+            with pytest.raises(litellm.BadRequestError, match="requires HTTPS"):
                 litellm.vector_stores.search(
                     vector_store_id="policy_index",
                     query="travel policy",
                     custom_llm_provider="mongodb",
                     _direct_vector_store_embedding_executor=executor,
-                    client=client,
-                    timeout=0.75,
-                    **BASE_PARAMS,
+                    **rejected_params,
                 )
-        else:
-            result: Final = litellm.vector_stores.search(
-                vector_store_id="policy_index",
-                query="travel policy",
-                custom_llm_provider="mongodb",
-                _direct_vector_store_embedding_executor=executor,
-                client=client,
-                timeout=0.75,
-                **BASE_PARAMS,
-            )
-            assert result == RESULT
+        executor.call.assert_not_called()
+        return
+
+    def respond(request: httpx.Request) -> httpx.Response:
+        assert request.url == f"{api_base}/v1/vector_stores/policy_index/search"
+        assert request.headers["authorization"] == "Bearer test-sidecar-key"
+        assert request.extensions["timeout"]["read"] == timeout
+        payload: Final = json.loads(request.content)
+        assert payload["timeout_ms"] == int(timeout * 1000)
+        assert payload["query_vector"] == [0.1, 0.2, 0.3]
+        if status == 0:
+            raise httpx.ReadTimeout("timed out", request=request)
+        return httpx.Response(status, json=body)
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as async_transport:
+        with httpx.Client(transport=httpx.MockTransport(respond)) as transport:
+            client: Final = AsyncHTTPHandler() if asynchronous else HTTPHandler(client=transport)
+            if isinstance(client, AsyncHTTPHandler):
+                await client.client.aclose()
+                client.client = async_transport
+
+            async def search() -> VectorStoreSearchResponse:
+                kwargs: Final = {
+                    **BASE_PARAMS,
+                    "api_base": api_base,
+                    "vector_store_id": "policy_index",
+                    "query": "travel policy",
+                    "custom_llm_provider": "mongodb",
+                    "_direct_vector_store_embedding_executor": executor,
+                    "client": client,
+                    "timeout": timeout,
+                }
+                if asynchronous:
+                    return await litellm.vector_stores.asearch(**kwargs)
+                return litellm.vector_stores.search(**kwargs)
+
+            if error_type is not None:
+                with pytest.raises(error_type):
+                    await search()
+            else:
+                assert await search() == RESULT
     executor.call.assert_called_once_with("embedding-alias", "travel policy", {})
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx
index 8da7098b695..03020bbc4a5 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/vector-stores/_components/VectorStoreForm.test.tsx
@@ -69,7 +69,7 @@ describe("VectorStoreForm", () => {
   });
 });
 
-const MONGODB_SIDECAR_URL = "http://mongodb-sidecar:8080";
+const MONGODB_SIDECAR_URL = "http://127.0.0.1:8080";
 
 const MONGODB_REQUIRED_FORM_VALUES = {
   api_base: MONGODB_SIDECAR_URL,
diff --git a/ui/litellm-dashboard/src/components/vector_store_providers.tsx b/ui/litellm-dashboard/src/components/vector_store_providers.tsx
index 6a8b2f405d2..79e711f6f98 100644
--- a/ui/litellm-dashboard/src/components/vector_store_providers.tsx
+++ b/ui/litellm-dashboard/src/components/vector_store_providers.tsx
@@ -177,8 +177,8 @@ export const vectorStoreProviderFields: Record<string, VectorStoreFieldConfig[]>
     {
       name: "api_base",
       label: "Sidecar URL",
-      tooltip: "The URL of your separately deployed MongoDB sidecar. Configure MongoDB credentials in the sidecar",
-      placeholder: "http://mongodb-sidecar:8080",
+      tooltip: "Use HTTPS for a remote sidecar, or HTTP with a loopback IP for a sidecar on the same host or Pod",
+      placeholder: "http://127.0.0.1:8080",
       required: true,
       type: "text",
     },

From edde95197a5c37c7af3d9967a70b65ab47b6913c Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 11:11:48 -0700
Subject: [PATCH 14/31] test(proxy): cover every /v1/files route error type and
 param

---
 .../test_files_endpoint.py                    | 99 +++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
index 123d54789bf..2257ae1ab29 100644
--- a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
+++ b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
@@ -4666,3 +4666,102 @@ def test_create_file_path_traversal_filename_rejected_before_forwarding(monkeypa
     assert error["param"] == "file"
     assert "traversal" in error["message"].lower()
     assert forwarded_calls == []
+
+
+def _setup_managed_file_route_answering_404(mocker: MockerFixture, monkeypatch, llm_router: Router):
+    """Wire the single-file routes to a managed file store that knows no file, the way the
+    managed files hook answers once a file has been deleted or was never the caller's."""
+    import litellm.proxy.proxy_server as ps
+    from fastapi import HTTPException
+    from litellm.llms.base_llm.files.transformation import BaseFileEndpoints
+    from litellm.proxy._types import LitellmUserRoles
+
+    async def _file_not_found(file_id: str, **kwargs):
+        raise HTTPException(status_code=404, detail=f"File not found: {file_id}")
+
+    proxy_logging_obj = setup_proxy_logging_object(monkeypatch, llm_router)
+    managed_files = mocker.MagicMock(spec=BaseFileEndpoints)
+    managed_files.afile_retrieve = mocker.AsyncMock(side_effect=_file_not_found)
+    managed_files.afile_delete = mocker.AsyncMock(side_effect=_file_not_found)
+    managed_files.afile_content = mocker.AsyncMock(side_effect=_file_not_found)
+    proxy_logging_obj.proxy_hook_mapping["managed_files"] = managed_files
+    monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", llm_router)
+
+    app.dependency_overrides[ps.user_api_key_auth] = lambda: UserAPIKeyAuth(
+        api_key="test-key",
+        user_role=LitellmUserRoles.INTERNAL_USER,
+        user_id="test-user",
+    )
+
+
+def _call_managed_file_route(method: str, path: str):
+    try:
+        return client.request(method, path, headers={"Authorization": "Bearer test-key"})
+    finally:
+        import litellm.proxy.proxy_server as ps
+
+        app.dependency_overrides.pop(ps.user_api_key_auth, None)
+
+
+def _missing_managed_file_error(file_id: str) -> dict:
+    return {
+        "error": {
+            "message": f"File not found: {file_id}",
+            "type": "invalid_request_error",
+            "param": None,
+            "code": "404",
+        }
+    }
+
+
+def test_create_file_reports_a_half_specified_expires_after_as_a_400(monkeypatch, llm_router: Router):
+    """A 400 raised inside the route answers with the type a 400 stands for and a JSON null
+    param, not the literal string "None" in both fields, so a client can classify it."""
+    setup_proxy_logging_object(monkeypatch, llm_router)
+    monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", llm_router)
+
+    response = client.post(
+        "/v1/files",
+        files={"file": ("mydata.jsonl", VALID_BATCH_LINE, "application/jsonl")},
+        data={"purpose": "batch", "target_model_names": "gpt-3.5-turbo", "expires_after[anchor]": "created_at"},
+        headers={"Authorization": "Bearer test-key"},
+    )
+
+    assert response.status_code == 400, response.text
+    error = response.json()["error"]
+    assert "expires_after[seconds]" in error["message"]
+    assert error["type"] == "invalid_request_error"
+    assert error["param"] is None
+    assert error["code"] == "400"
+
+
+def test_get_file_reports_a_missing_managed_file_as_a_404(mocker: MockerFixture, monkeypatch, llm_router: Router):
+    _setup_managed_file_route_answering_404(mocker, monkeypatch, llm_router)
+    file_id = _unified_managed_file_id()
+
+    response = _call_managed_file_route("GET", f"/v1/files/{file_id}")
+
+    assert response.status_code == 404, response.text
+    assert response.json() == _missing_managed_file_error(file_id)
+
+
+def test_delete_file_reports_a_missing_managed_file_as_a_404(mocker: MockerFixture, monkeypatch, llm_router: Router):
+    _setup_managed_file_route_answering_404(mocker, monkeypatch, llm_router)
+    file_id = _unified_managed_file_id()
+
+    response = _call_managed_file_route("DELETE", f"/v1/files/{file_id}")
+
+    assert response.status_code == 404, response.text
+    assert response.json() == _missing_managed_file_error(file_id)
+
+
+def test_get_file_content_reports_a_missing_managed_file_as_a_404(
+    mocker: MockerFixture, monkeypatch, llm_router: Router
+):
+    _setup_managed_file_route_answering_404(mocker, monkeypatch, llm_router)
+    file_id = _unified_managed_file_id()
+
+    response = _call_managed_file_route("GET", f"/v1/files/{file_id}/content")
+
+    assert response.status_code == 404, response.text
+    assert response.json() == _missing_managed_file_error(file_id)

From 8b89c909a9448a66a0f60cc3c9de7e236271b838 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 12:16:08 -0700
Subject: [PATCH 15/31] fix(proxy): keep a ProxyException's status and label
 408s in the OpenAI error payload

error_status_code only read status_code, so a ProxyException raised
before routing (which stores its status as the string code) answered
500 with its 4xx type through the rerank, images, realtime, files, and
pass-through tails. It now falls back to a decimal code. A 408 maps to
timeout_error instead of invalid_request_error.

Tail regressions for rerank, images, realtime calls, and the chat
pass-through fail at the merge base with ('None', 'None'); the new
files-test helpers are fully typed.
---
 .../common_utils/openai_error_payload.py      |  9 ++-
 .../common_utils/test_openai_error_payload.py | 28 ++++++++++
 .../proxy/image_endpoints/test_endpoints.py   | 48 +++++++++++++++-
 .../test_files_endpoint.py                    | 24 +++++---
 .../test_pass_through_endpoints.py            | 38 ++++++++++++-
 .../test_realtime_webrtc_endpoints.py         | 42 ++++++++++++++
 .../proxy/rerank_endpoints/test_endpoints.py  | 56 ++++++++++++++++++-
 7 files changed, 230 insertions(+), 15 deletions(-)

diff --git a/litellm/proxy/common_utils/openai_error_payload.py b/litellm/proxy/common_utils/openai_error_payload.py
index 180ec152094..2d589871fea 100644
--- a/litellm/proxy/common_utils/openai_error_payload.py
+++ b/litellm/proxy/common_utils/openai_error_payload.py
@@ -12,6 +12,7 @@ _OPENAI_ERROR_TYPE_BY_STATUS: Final[Mapping[int, str]] = MappingProxyType(
     {
         status.HTTP_401_UNAUTHORIZED: "authentication_error",
         status.HTTP_403_FORBIDDEN: "permission_error",
+        status.HTTP_408_REQUEST_TIMEOUT: "timeout_error",
         status.HTTP_429_TOO_MANY_REQUESTS: "rate_limit_error",
     }
 )
@@ -22,9 +23,13 @@ def attribute_of(value: object, name: str, default: object = None) -> object:
 
 
 def error_status_code(exc: object, default: int) -> int:
-    """The HTTP status an exception carries, or ``default`` when it carries none."""
+    """The HTTP status an exception carries as ``status_code`` or, the way ``ProxyException``
+    stores it, as a stringified ``code``; ``default`` when it carries neither."""
     carried: Final = attribute_of(exc, "status_code")
-    return carried if isinstance(carried, int) and not isinstance(carried, bool) else default
+    if isinstance(carried, int) and not isinstance(carried, bool):
+        return carried
+    stringified: Final = attribute_of(exc, "code")
+    return int(stringified) if isinstance(stringified, str) and stringified.isdecimal() else default
 
 
 def openai_error_type(exc: object, status_code: int) -> str:
diff --git a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
index 3b39ea706fe..3145be2d522 100644
--- a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
+++ b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
@@ -18,6 +18,7 @@ from litellm.proxy.common_utils.openai_error_payload import (
         (401, "authentication_error"),
         (403, "permission_error"),
         (404, "invalid_request_error"),
+        (408, "timeout_error"),
         (422, "invalid_request_error"),
         (429, "rate_limit_error"),
         (499, "invalid_request_error"),
@@ -109,6 +110,33 @@ def test_a_non_int_carried_status_falls_back_to_the_default(carried_status: obje
     assert error_status_code(_Carrier("boom"), 500) == 500
 
 
+def test_a_proxy_exception_keeps_the_status_it_was_raised_with():
+    """ProxyException stores its status as the string ``code`` rather than ``status_code``,
+    so a route tail that rewraps one used to answer a 4xx rejection as a 500."""
+    rejection = ProxyException(message="session_id is required", type="bad_request_error", param="session_id", code=400)
+
+    assert error_status_code(rejection, 500) == 400
+
+
+@pytest.mark.parametrize("carried_code", [None, "None", "", "rate_limited", "4xx", 404])
+def test_a_code_that_is_not_a_decimal_string_falls_back_to_the_default(carried_code: object):
+    """Only ProxyException's stringified status is a status; ``code`` on anything else
+    (OpenAI's ``invalid_api_key``, a stray int) says nothing about the HTTP answer."""
+
+    class _Carrier(Exception):
+        code = carried_code
+
+    assert error_status_code(_Carrier("boom"), 500) == 500
+
+
+def test_a_status_code_wins_over_a_stringified_code():
+    class _Carrier(Exception):
+        status_code = 429
+        code = "400"
+
+    assert error_status_code(_Carrier("boom"), 500) == 429
+
+
 def test_a_status_carried_by_an_exception_drives_the_type_it_reports():
     """The two helpers compose at every call site: the status the exception carries is what
     names its type, not the default the route would have used."""
diff --git a/tests/test_litellm/proxy/image_endpoints/test_endpoints.py b/tests/test_litellm/proxy/image_endpoints/test_endpoints.py
index 203391aadad..d8b3eef98bd 100644
--- a/tests/test_litellm/proxy/image_endpoints/test_endpoints.py
+++ b/tests/test_litellm/proxy/image_endpoints/test_endpoints.py
@@ -5,12 +5,12 @@ from typing import Any, Dict
 
 import orjson
 import pytest
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException
 from fastapi.testclient import TestClient
 from starlette.requests import Request
 from starlette.responses import Response
 
-from litellm.proxy._types import UserAPIKeyAuth
+from litellm.proxy._types import ProxyException, UserAPIKeyAuth
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.proxy.image_endpoints import endpoints
 
@@ -167,3 +167,47 @@ def test_image_edit_multipart_n_that_is_not_a_number_is_left_alone(monkeypatch):
 
     assert response.status_code == 200
     assert captured["n"] == "two"
+
+
+@pytest.mark.asyncio
+async def test_a_model_the_router_cannot_serve_answers_an_openai_typed_error(monkeypatch: pytest.MonkeyPatch):
+    """A bare HTTPException carries no type or param, so the tail used to ship the
+    literal string "None" in both fields."""
+
+    async def fake_add_litellm_data_to_request(**kwargs: object) -> object:
+        return kwargs["data"]
+
+    async def fake_pre_call_hook(*, user_api_key_dict: UserAPIKeyAuth, data: dict[str, object], call_type: str) -> dict[str, object]:
+        return data
+
+    async def fake_post_call_failure_hook(**_: object) -> None:
+        return None
+
+    async def failing_route_request(**_: object) -> None:
+        raise HTTPException(
+            status_code=404, detail={"error": "image_generation: Invalid model name passed in model=dall-e-3"}
+        )
+
+    monkeypatch.setattr("litellm.proxy.proxy_server.add_litellm_data_to_request", fake_add_litellm_data_to_request)
+    monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", {})
+    monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", None)
+    monkeypatch.setattr("litellm.proxy.proxy_server.proxy_config", {})
+    monkeypatch.setattr(
+        "litellm.proxy.proxy_server.proxy_logging_obj",
+        SimpleNamespace(pre_call_hook=fake_pre_call_hook, post_call_failure_hook=fake_post_call_failure_hook),
+    )
+    monkeypatch.setattr("litellm.proxy.proxy_server.user_model", None)
+    monkeypatch.setattr("litellm.proxy.proxy_server.version", "test-version")
+    monkeypatch.setattr("litellm.proxy.image_endpoints.endpoints.route_request", failing_route_request)
+
+    body = orjson.dumps({"model": "dall-e-3", "prompt": "a lighthouse at dusk"})
+
+    async def receive() -> dict[str, object]:
+        return {"type": "http.request", "body": body, "more_body": False}
+
+    request = Request({"type": "http", "method": "POST", "path": "/v1/images/generations", "headers": []}, receive)
+
+    with pytest.raises(ProxyException) as raised:
+        await endpoints.image_generation(request=request, fastapi_response=Response(), user_api_key_dict=UserAPIKeyAuth())
+
+    assert (raised.value.type, raised.value.param, raised.value.code) == ("invalid_request_error", None, "404")
diff --git a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
index 2257ae1ab29..132b53792b0 100644
--- a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
+++ b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
@@ -4668,7 +4668,9 @@ def test_create_file_path_traversal_filename_rejected_before_forwarding(monkeypa
     assert forwarded_calls == []
 
 
-def _setup_managed_file_route_answering_404(mocker: MockerFixture, monkeypatch, llm_router: Router):
+def _setup_managed_file_route_answering_404(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, llm_router: Router
+) -> None:
     """Wire the single-file routes to a managed file store that knows no file, the way the
     managed files hook answers once a file has been deleted or was never the caller's."""
     import litellm.proxy.proxy_server as ps
@@ -4676,7 +4678,7 @@ def _setup_managed_file_route_answering_404(mocker: MockerFixture, monkeypatch,
     from litellm.llms.base_llm.files.transformation import BaseFileEndpoints
     from litellm.proxy._types import LitellmUserRoles
 
-    async def _file_not_found(file_id: str, **kwargs):
+    async def _file_not_found(file_id: str, **kwargs: object) -> None:
         raise HTTPException(status_code=404, detail=f"File not found: {file_id}")
 
     proxy_logging_obj = setup_proxy_logging_object(monkeypatch, llm_router)
@@ -4694,7 +4696,7 @@ def _setup_managed_file_route_answering_404(mocker: MockerFixture, monkeypatch,
     )
 
 
-def _call_managed_file_route(method: str, path: str):
+def _call_managed_file_route(method: str, path: str) -> httpx.Response:
     try:
         return client.request(method, path, headers={"Authorization": "Bearer test-key"})
     finally:
@@ -4703,7 +4705,7 @@ def _call_managed_file_route(method: str, path: str):
         app.dependency_overrides.pop(ps.user_api_key_auth, None)
 
 
-def _missing_managed_file_error(file_id: str) -> dict:
+def _missing_managed_file_error(file_id: str) -> dict[str, dict[str, str | None]]:
     return {
         "error": {
             "message": f"File not found: {file_id}",
@@ -4714,7 +4716,9 @@ def _missing_managed_file_error(file_id: str) -> dict:
     }
 
 
-def test_create_file_reports_a_half_specified_expires_after_as_a_400(monkeypatch, llm_router: Router):
+def test_create_file_reports_a_half_specified_expires_after_as_a_400(
+    monkeypatch: pytest.MonkeyPatch, llm_router: Router
+):
     """A 400 raised inside the route answers with the type a 400 stands for and a JSON null
     param, not the literal string "None" in both fields, so a client can classify it."""
     setup_proxy_logging_object(monkeypatch, llm_router)
@@ -4735,7 +4739,9 @@ def test_create_file_reports_a_half_specified_expires_after_as_a_400(monkeypatch
     assert error["code"] == "400"
 
 
-def test_get_file_reports_a_missing_managed_file_as_a_404(mocker: MockerFixture, monkeypatch, llm_router: Router):
+def test_get_file_reports_a_missing_managed_file_as_a_404(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, llm_router: Router
+):
     _setup_managed_file_route_answering_404(mocker, monkeypatch, llm_router)
     file_id = _unified_managed_file_id()
 
@@ -4745,7 +4751,9 @@ def test_get_file_reports_a_missing_managed_file_as_a_404(mocker: MockerFixture,
     assert response.json() == _missing_managed_file_error(file_id)
 
 
-def test_delete_file_reports_a_missing_managed_file_as_a_404(mocker: MockerFixture, monkeypatch, llm_router: Router):
+def test_delete_file_reports_a_missing_managed_file_as_a_404(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, llm_router: Router
+):
     _setup_managed_file_route_answering_404(mocker, monkeypatch, llm_router)
     file_id = _unified_managed_file_id()
 
@@ -4756,7 +4764,7 @@ def test_delete_file_reports_a_missing_managed_file_as_a_404(mocker: MockerFixtu
 
 
 def test_get_file_content_reports_a_missing_managed_file_as_a_404(
-    mocker: MockerFixture, monkeypatch, llm_router: Router
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, llm_router: Router
 ):
     _setup_managed_file_route_answering_404(mocker, monkeypatch, llm_router)
     file_id = _unified_managed_file_id()
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index fb4ed3db4d2..d57bed430c1 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -11,7 +11,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx
 import pytest
-from fastapi import Request, UploadFile
+from fastapi import Request, Response, UploadFile
 from starlette.datastructures import FormData, Headers, QueryParams
 from starlette.datastructures import UploadFile as StarletteUploadFile
 
@@ -22,6 +22,7 @@ from litellm.proxy.pass_through_endpoints.pass_through_endpoints import (
     InitPassThroughEndpointHelpers,
     LITELLM_PASS_THROUGH_CUSTOM_BODY_STATE_KEY,
     _registered_pass_through_routes,
+    chat_completion_pass_through_endpoint,
     create_pass_through_route,
     initialize_pass_through_endpoints,
     pass_through_request,
@@ -5837,3 +5838,38 @@ def test_passthrough_client_cannot_forge_session_id_omission(client_metadata_key
         )
         == "per-call-random-trace-id"
     )
+
+
+@pytest.mark.asyncio
+async def test_chat_completion_pass_through_endpoint_answers_an_openai_typed_error_for_an_unknown_model(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """A bare HTTPException carries no type or param, so the tail used to ship the
+    literal string "None" in both fields."""
+    proxy_logging = MagicMock()
+    proxy_logging.pre_call_hook = AsyncMock(side_effect=lambda **kwargs: kwargs["data"])
+    proxy_logging.post_call_failure_hook = AsyncMock()
+
+    async def fake_add_litellm_data_to_request(**kwargs: object) -> object:
+        return kwargs["data"]
+
+    monkeypatch.setattr("litellm.proxy.proxy_server.proxy_logging_obj", proxy_logging)
+    monkeypatch.setattr("litellm.proxy.proxy_server.add_litellm_data_to_request", fake_add_litellm_data_to_request)
+    monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", None)
+    monkeypatch.setattr("litellm.proxy.proxy_server.user_model", None)
+    monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", {})
+
+    request = MagicMock(spec=Request)
+    request.body = AsyncMock(
+        return_value=json.dumps({"model": "unknown-model", "messages": [{"role": "user", "content": "hi"}]}).encode()
+    )
+
+    with pytest.raises(ProxyException) as raised:
+        await chat_completion_pass_through_endpoint(
+            fastapi_response=Response(),
+            request=request,
+            adapter_id="anthropic",
+            user_api_key_dict=UserAPIKeyAuth(api_key="sk-test"),
+        )
+
+    assert (raised.value.type, raised.value.param, raised.value.code) == ("invalid_request_error", None, "400")
diff --git a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
index 66eeb3cef34..8cc5994dc81 100644
--- a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
+++ b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
@@ -6,10 +6,12 @@ Tests for LiteLLM proxy realtime WebRTC HTTP endpoints:
 
 import json
 import time
+from collections.abc import Awaitable, Callable
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx
 import pytest
+from fastapi import FastAPI, HTTPException
 from fastapi.testclient import TestClient
 
 
@@ -1199,3 +1201,43 @@ async def test_transcription_sessions_wraps_route_exception(
         assert "Model not allowed" in response.text
     finally:
         proxy_app.dependency_overrides.pop(user_api_key_auth, None)
+
+
+def test_realtime_calls_upstream_rejection_answers_an_openai_typed_error(
+    proxy_app: FastAPI,
+    mock_add_litellm_data: Callable[..., Awaitable[object]],
+    mock_pre_call_hook: Callable[..., Awaitable[object]],
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """A bare HTTPException carries no type or param, so the tail used to ship the
+    literal string "None" in both fields of the error the browser client reads."""
+    token_payload = _encode_realtime_token_payload(
+        ephemeral_key="fake_upstream_epk",
+        model_id="gpt-4o-realtime-preview",
+        user_id=None,
+        team_id=None,
+        expires_at=int(time.time()) + 3600,
+    )
+    encrypted_token = encrypt_value_helper(token_payload)
+
+    async def failing_route_request(*args: object, **kwargs: object) -> None:
+        raise HTTPException(
+            status_code=404,
+            detail={"error": "realtime: Invalid model name passed in model=gpt-4o-realtime-preview"},
+        )
+
+    proxy_logging = MagicMock()
+    proxy_logging.pre_call_hook = AsyncMock(side_effect=mock_pre_call_hook)
+    proxy_logging.post_call_failure_hook = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.route_request", failing_route_request)
+    monkeypatch.setattr("litellm.proxy.proxy_server.add_litellm_data_to_request", mock_add_litellm_data)
+    monkeypatch.setattr("litellm.proxy.proxy_server.proxy_logging_obj", proxy_logging)
+
+    response = TestClient(proxy_app).post(
+        "/v1/realtime/calls",
+        headers={"Authorization": f"Bearer {encrypted_token}"},
+        content=b"v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\ns=-\r\n",
+    )
+
+    assert response.status_code == 404
+    assert (response.json()["error"]["type"], response.json()["error"]["param"]) == ("invalid_request_error", None)
diff --git a/tests/test_litellm/proxy/rerank_endpoints/test_endpoints.py b/tests/test_litellm/proxy/rerank_endpoints/test_endpoints.py
index 9f11ff6f20d..ea858e04e0f 100644
--- a/tests/test_litellm/proxy/rerank_endpoints/test_endpoints.py
+++ b/tests/test_litellm/proxy/rerank_endpoints/test_endpoints.py
@@ -6,11 +6,11 @@ import json
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from fastapi import Request, Response
+from fastapi import HTTPException, Request, Response
 
 import litellm.proxy.common_request_processing as common_request_processing_mod
 import litellm.proxy.proxy_server as proxy_server_mod
-from litellm.proxy._types import UserAPIKeyAuth
+from litellm.proxy._types import ProxyException, UserAPIKeyAuth
 from litellm.proxy.rerank_endpoints.endpoints import rerank
 from litellm.types.utils import RerankResponse
 
@@ -118,3 +118,55 @@ async def test_rerank_omits_detailed_timing_headers_when_disabled():
         fastapi_response = await _call_rerank()
 
     assert "x-litellm-timing-llm-api-ms" not in fastapi_response.headers
+
+
+async def _rerank_failure(
+    failure: Exception, *, raised_before_routing: bool, monkeypatch: pytest.MonkeyPatch
+) -> ProxyException:
+    proxy_logging_obj = MagicMock()
+    proxy_logging_obj.pre_call_hook = AsyncMock(
+        side_effect=failure if raised_before_routing else lambda **kwargs: kwargs["data"]
+    )
+    proxy_logging_obj.post_call_failure_hook = AsyncMock()
+
+    async def fake_add_litellm_data_to_request(**kwargs: object) -> object:
+        return kwargs["data"]
+
+    async def failing_route_request(**kwargs: object) -> None:
+        raise failure
+
+    monkeypatch.setattr(proxy_server_mod, "add_litellm_data_to_request", fake_add_litellm_data_to_request)
+    monkeypatch.setattr(proxy_server_mod, "route_request", failing_route_request)
+    monkeypatch.setattr(proxy_server_mod, "proxy_logging_obj", proxy_logging_obj)
+    monkeypatch.setattr(proxy_server_mod, "llm_router", MagicMock())
+    monkeypatch.setattr(proxy_server_mod, "version", "1.2.3")
+
+    with pytest.raises(ProxyException) as raised:
+        await rerank(
+            request=_build_request(),
+            fastapi_response=Response(),
+            user_api_key_dict=UserAPIKeyAuth(api_key="sk-test"),
+        )
+    return raised.value
+
+
+@pytest.mark.asyncio
+async def test_a_model_the_router_cannot_serve_answers_an_openai_typed_error(monkeypatch: pytest.MonkeyPatch):
+    """A bare HTTPException carries no type or param, so the tail used to ship the
+    literal string "None" in both fields."""
+    failure = HTTPException(status_code=404, detail={"error": "rerank: Invalid model name passed in model=rerank-model"})
+
+    error = await _rerank_failure(failure, raised_before_routing=False, monkeypatch=monkeypatch)
+
+    assert (error.type, error.param, error.code) == ("invalid_request_error", None, "404")
+
+
+@pytest.mark.asyncio
+async def test_a_rejection_raised_before_routing_keeps_its_own_status(monkeypatch: pytest.MonkeyPatch):
+    """A ProxyException stores its status as the string ``code``, which the tail used to
+    miss and rewrap as a 500 while keeping the 4xx type and param."""
+    rejection = ProxyException(message="session_id is required", type="bad_request_error", param="session_id", code=400)
+
+    error = await _rerank_failure(rejection, raised_before_routing=True, monkeypatch=monkeypatch)
+
+    assert (error.type, error.param, error.code) == ("bad_request_error", "session_id", "400")

From 384eee26a5c144290d922879c619f18126deec01 Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 12:53:01 -0700
Subject: [PATCH 16/31] fix(bedrock): reject s3 Marengo media without
 bucketOwner and skip items without an embedding

---
 .../twelvelabs_marengo_3_transformation.py    | 14 ++++---
 .../twelvelabs_marengo_transformation.py      |  6 +--
 .../test_bedrock_async_invoke_embedding.py    |  3 +-
 .../bedrock/embed/test_bedrock_embedding.py   | 10 +++++
 ...est_twelvelabs_marengo_3_transformation.py | 40 +++++++++++++++----
 5 files changed, 55 insertions(+), 18 deletions(-)

diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
index f4f9cb03dab..4aac6f22bae 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_3_transformation.py
@@ -91,19 +91,21 @@ class Marengo3Params(BaseModel):
         return self.model_dump(include=MARENGO_2_7_ONLY_FIELDS, exclude_none=True)
 
 
-def _s3_location(uri: str, bucket_owner: str | None) -> TwelveLabsS3Location:
+def _require_bucket_owner(bucket_owner: str | None) -> str:
     if bucket_owner is None:
-        unowned: Final[TwelveLabsS3Location] = {"uri": uri}
-        return unowned
-    owned: Final[TwelveLabsS3Location] = {"uri": uri, "bucketOwner": bucket_owner}
-    return owned
+        raise BedrockError(
+            status_code=400,
+            message="s3:// media requires the 'bucketOwner' parameter, the account id that owns the bucket",
+        )
+    return bucket_owner
 
 
 def _media_source(media: str, bucket_owner: str | None) -> TwelveLabsMediaSource:
     if not media.startswith(S3_URI_PREFIX):
         inline: Final[TwelveLabsMediaSource] = {"base64String": get_base64_str(media)}
         return inline
-    remote: Final[TwelveLabsMediaSource] = {"s3Location": _s3_location(media, bucket_owner)}
+    s3_location: Final[TwelveLabsS3Location] = {"uri": media, "bucketOwner": _require_bucket_owner(bucket_owner)}
+    remote: Final[TwelveLabsMediaSource] = {"s3Location": s3_location}
     return remote
 
 
diff --git a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
index 35163ecf848..65ca2be191f 100644
--- a/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
+++ b/litellm/llms/bedrock/embed/twelvelabs_marengo_transformation.py
@@ -35,7 +35,7 @@ from litellm.types.utils import Embedding, EmbeddingResponse, PromptTokensDetail
 class MarengoEmbeddingItem(BaseModel):
     model_config = ConfigDict(extra="ignore", frozen=True)
 
-    embedding: tuple[float, ...]
+    embedding: tuple[float, ...] | None = None
 
 
 class MarengoInvokeResponse(BaseModel):
@@ -47,10 +47,10 @@ class MarengoInvokeResponse(BaseModel):
 
     def vectors(self) -> tuple[tuple[float, ...], ...]:
         if self.data:
-            return tuple(item.embedding for item in self.data)
+            return tuple(item.embedding for item in self.data if item.embedding is not None)
         if self.embedding is not None:
             return (self.embedding,)
-        return tuple(item.embedding for item in self.embeddings)
+        return tuple(item.embedding for item in self.embeddings if item.embedding is not None)
 
 
 class MarengoBilledMultiInput(BaseModel):
diff --git a/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py b/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py
index 00f5145269a..ddbd3a2e9ba 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_bedrock_async_invoke_embedding.py
@@ -204,6 +204,7 @@ class TestBedrockAsyncInvokeEmbedding:
                 input_type="video",
                 embeddingOption=["visual", "audio"],
                 segmentation={"method": "fixed", "fixed": {"durationSec": 6}},
+                bucketOwner="123456789012",
                 output_s3_uri="s3://test-bucket/async-invoke-output/",
             )
 
@@ -214,7 +215,7 @@ class TestBedrockAsyncInvokeEmbedding:
             "modelInput": {
                 "inputType": "video",
                 "video": {
-                    "mediaSource": {"s3Location": {"uri": "s3://test-bucket/clip.mp4"}},
+                    "mediaSource": {"s3Location": {"uri": "s3://test-bucket/clip.mp4", "bucketOwner": "123456789012"}},
                     "segmentation": {"method": "fixed", "fixed": {"durationSec": 6}},
                     "embeddingOption": ["visual", "audio"],
                 },
diff --git a/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py b/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
index c29a87cd0cf..bcd1a29d0e8 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_bedrock_embedding.py
@@ -1220,6 +1220,16 @@ def test_marengo_usage_without_request_data_bills_nothing():
     assert response.usage.prompt_tokens_details is None
 
 
+def test_marengo_response_items_without_an_embedding_are_skipped():
+    response = TwelveLabsMarengoEmbeddingConfig()._transform_response(
+        response_list=[{"data": [{"embeddingOption": "visual-text", "startSec": 0.0}, {"embedding": [0.1, 0.2, 0.3]}]}],
+        model="us.twelvelabs.marengo-embed-3-0-v1:0",
+    )
+
+    assert [item["embedding"] for item in response.data] == [[0.1, 0.2, 0.3]]
+    assert response.data[0]["index"] == 0
+
+
 def test_marengo_3_text_image_without_media_source_is_a_bad_request():
     with pytest.raises(litellm.BadRequestError, match=r"text_image.*media_source"):
         litellm.embedding(
diff --git a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
index d8d29cac35e..f149953b6f1 100644
--- a/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
+++ b/tests/test_litellm/llms/bedrock/embed/test_twelvelabs_marengo_3_transformation.py
@@ -75,9 +75,22 @@ def test_image_request_from_s3_carries_bucket_owner():
     }
 
 
-def test_s3_media_without_bucket_owner_omits_the_key():
-    request = build_marengo_3_request("s3://media/duck.png", {"input_type": "image"})
-    assert request["image"]["mediaSource"] == {"s3Location": {"uri": "s3://media/duck.png"}}
+@pytest.mark.parametrize(
+    "input_media,params",
+    [
+        ("s3://media/duck.png", {"input_type": "image"}),
+        ("s3://media/clip.mp4", {"input_type": "video"}),
+        ("a duck", {"input_type": "text_image", "media_source": "s3://media/duck.png"}),
+        ("a duck", {"input_type": "multi_input", "media_sources": {"img1": "s3://media/duck.png"}}),
+    ],
+)
+def test_s3_media_without_bucket_owner_is_rejected_naming_it(input_media, params):
+    with pytest.raises(BedrockError) as excinfo:
+        build_marengo_3_request(input_media, params)
+    assert excinfo.value.status_code == 400
+    assert excinfo.value.message == (
+        "s3:// media requires the 'bucketOwner' parameter, the account id that owns the bucket"
+    )
 
 
 def test_text_image_request_pairs_text_with_media_source():
@@ -147,12 +160,13 @@ def test_timed_media_request_nests_every_option_under_the_media_key(input_type):
             "embeddingType": ["fused_embedding"],
             "embeddingScope": ["clip", "asset"],
             "inferenceId": "req-42",
+            "bucketOwner": "123456789012",
         },
     )
     assert wire(request) == {
         "inputType": input_type,
         input_type: {
-            "mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4"}},
+            "mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4", "bucketOwner": "123456789012"}},
             "startSec": 2.0,
             "endSec": 12.5,
             "segmentation": {"method": "dynamic", "dynamic": {"minDurationSec": 4}},
@@ -165,8 +179,10 @@ def test_timed_media_request_nests_every_option_under_the_media_key(input_type):
 
 
 def test_timed_media_request_without_options_carries_only_the_media_source():
-    request = build_marengo_3_request("s3://media/clip.mp4", {"input_type": "video"})
-    assert request["video"] == {"mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4"}}}
+    request = build_marengo_3_request("s3://media/clip.mp4", {"input_type": "video", "bucketOwner": "123456789012"})
+    assert request["video"] == {
+        "mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4", "bucketOwner": "123456789012"}}
+    }
 
 
 @pytest.mark.parametrize(
@@ -211,7 +227,12 @@ def test_marengo_3_video_and_audio_still_require_the_async_route(input_type):
 def test_marengo_3_async_invoke_wraps_the_nested_payload_with_the_base_model_id():
     request = TwelveLabsMarengoEmbeddingConfig(model=MARENGO_3_BASE)._transform_request(
         input="s3://media/clip.mp4",
-        inference_params={"input_type": "video", "embeddingOption": ["visual"], "output_s3_uri": OUTPUT_S3_URI},
+        inference_params={
+            "input_type": "video",
+            "embeddingOption": ["visual"],
+            "bucketOwner": "123456789012",
+            "output_s3_uri": OUTPUT_S3_URI,
+        },
         async_invoke_route=True,
         model_id="async_invoke%2Ftwelvelabs.marengo-embed-3-0-v1%3A0",
         output_s3_uri=OUTPUT_S3_URI,
@@ -220,7 +241,10 @@ def test_marengo_3_async_invoke_wraps_the_nested_payload_with_the_base_model_id(
         "modelId": MARENGO_3_BASE,
         "modelInput": {
             "inputType": "video",
-            "video": {"mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4"}}, "embeddingOption": ["visual"]},
+            "video": {
+                "mediaSource": {"s3Location": {"uri": "s3://media/clip.mp4", "bucketOwner": "123456789012"}},
+                "embeddingOption": ["visual"],
+            },
         },
         "outputDataConfig": {"s3OutputDataConfig": {"s3Uri": OUTPUT_S3_URI}},
     }

From 720f2ca7751b36111fb3aed8c212869a3363de3e Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 13:11:24 -0700
Subject: [PATCH 17/31] fix(proxy): label a 408 invalid_request_error again and
 pin the in-route status on the files and realtime tails

---
 .../common_utils/openai_error_payload.py      |  1 -
 .../common_utils/test_openai_error_payload.py |  2 +-
 .../test_files_endpoint.py                    | 46 +++++++++++++++++++
 .../test_realtime_webrtc_endpoints.py         | 35 ++++++++++++++
 .../proxy/test_common_request_processing.py   | 13 ++++++
 5 files changed, 95 insertions(+), 2 deletions(-)

diff --git a/litellm/proxy/common_utils/openai_error_payload.py b/litellm/proxy/common_utils/openai_error_payload.py
index 2d589871fea..89f735ee8b6 100644
--- a/litellm/proxy/common_utils/openai_error_payload.py
+++ b/litellm/proxy/common_utils/openai_error_payload.py
@@ -12,7 +12,6 @@ _OPENAI_ERROR_TYPE_BY_STATUS: Final[Mapping[int, str]] = MappingProxyType(
     {
         status.HTTP_401_UNAUTHORIZED: "authentication_error",
         status.HTTP_403_FORBIDDEN: "permission_error",
-        status.HTTP_408_REQUEST_TIMEOUT: "timeout_error",
         status.HTTP_429_TOO_MANY_REQUESTS: "rate_limit_error",
     }
 )
diff --git a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
index 3145be2d522..8b653ddfb71 100644
--- a/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
+++ b/tests/test_litellm/proxy/common_utils/test_openai_error_payload.py
@@ -18,7 +18,7 @@ from litellm.proxy.common_utils.openai_error_payload import (
         (401, "authentication_error"),
         (403, "permission_error"),
         (404, "invalid_request_error"),
-        (408, "timeout_error"),
+        (408, "invalid_request_error"),
         (422, "invalid_request_error"),
         (429, "rate_limit_error"),
         (499, "invalid_request_error"),
diff --git a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
index 132b53792b0..5f1e7e1fe0c 100644
--- a/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
+++ b/tests/test_litellm/proxy/openai_files_endpoint/test_files_endpoint.py
@@ -4773,3 +4773,49 @@ def test_get_file_content_reports_a_missing_managed_file_as_a_404(
 
     assert response.status_code == 404, response.text
     assert response.json() == _missing_managed_file_error(file_id)
+
+
+def _setup_managed_file_stored_in_an_unknown_storage_backend(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, llm_router: Router
+) -> None:
+    """Wire the content route to a managed file whose row names a storage backend the
+    factory does not know, which is the one in-route ProxyException on these routes."""
+    from types import SimpleNamespace
+
+    import litellm.proxy.proxy_server as ps
+    from litellm.llms.base_llm.files.transformation import BaseFileEndpoints
+    from litellm.proxy._types import LitellmUserRoles
+
+    proxy_logging_obj = setup_proxy_logging_object(monkeypatch, llm_router)
+    managed_files = mocker.MagicMock(spec=BaseFileEndpoints)
+    managed_files.prisma_client = mocker.MagicMock()
+    proxy_logging_obj.proxy_hook_mapping["managed_files"] = managed_files
+    repository = mocker.MagicMock()
+    repository.table.find_first = mocker.AsyncMock(
+        return_value=SimpleNamespace(storage_backend="ftp", storage_url="ftp://bucket/file")
+    )
+    monkeypatch.setattr(
+        "litellm.proxy.openai_files_endpoints.files_endpoints.ManagedFileRepository", lambda _prisma: repository
+    )
+    monkeypatch.setattr("litellm.proxy.proxy_server.llm_router", llm_router)
+
+    app.dependency_overrides[ps.user_api_key_auth] = lambda: UserAPIKeyAuth(
+        api_key="test-key",
+        user_role=LitellmUserRoles.INTERNAL_USER,
+        user_id="test-user",
+    )
+
+
+def test_get_file_content_keeps_the_status_of_a_rejection_raised_inside_the_route(
+    mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, llm_router: Router
+):
+    """A ProxyException raised inside the route carries its status as the string ``code``,
+    and the tail used to rebuild it as a 500 because it only read ``status_code``."""
+    _setup_managed_file_stored_in_an_unknown_storage_backend(mocker, monkeypatch, llm_router)
+
+    response = _call_managed_file_route("GET", f"/v1/files/{_unified_managed_file_id()}/content")
+
+    assert response.status_code == 400, response.text
+    error = response.json()["error"]
+    assert error["message"].startswith("Storage backend error")
+    assert (error["type"], error["param"], error["code"]) == ("invalid_request_error", "file_id", "400")
diff --git a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
index 8cc5994dc81..7436cf84fec 100644
--- a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
+++ b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
@@ -1241,3 +1241,38 @@ def test_realtime_calls_upstream_rejection_answers_an_openai_typed_error(
 
     assert response.status_code == 404
     assert (response.json()["error"]["type"], response.json()["error"]["param"]) == ("invalid_request_error", None)
+
+
+def test_transcription_sessions_rejection_answers_an_openai_typed_error(
+    proxy_app: FastAPI,
+    mock_add_litellm_data: Callable[..., Awaitable[object]],
+    mock_pre_call_hook: Callable[..., Awaitable[object]],
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """A model the router cannot serve surfaces as a bare HTTPException, which this tail
+    used to relabel with the literal string "None" for both type and param."""
+
+    async def failing_route_request(*args: object, **kwargs: object) -> None:
+        raise HTTPException(
+            status_code=400,
+            detail={"error": "realtime: Invalid model name passed in model=no-such-transcribe"},
+        )
+
+    proxy_logging = MagicMock()
+    proxy_logging.pre_call_hook = AsyncMock(side_effect=mock_pre_call_hook)
+    proxy_logging.post_call_failure_hook = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.route_request", failing_route_request)
+    monkeypatch.setattr("litellm.proxy.proxy_server.add_litellm_data_to_request", mock_add_litellm_data)
+    monkeypatch.setattr("litellm.proxy.proxy_server.proxy_logging_obj", proxy_logging)
+    proxy_app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth(user_id="test-user")
+    try:
+        response = TestClient(proxy_app, raise_server_exceptions=False).post(
+            "/v1/realtime/transcription_sessions",
+            headers={"Authorization": "Bearer sk-test-master-key"},
+            json={"input_audio_transcription": {"model": "no-such-transcribe"}},
+        )
+    finally:
+        proxy_app.dependency_overrides.pop(user_api_key_auth, None)
+
+    assert response.status_code == 400
+    assert (response.json()["error"]["type"], response.json()["error"]["param"]) == ("invalid_request_error", None)
diff --git a/tests/test_litellm/proxy/test_common_request_processing.py b/tests/test_litellm/proxy/test_common_request_processing.py
index bfae42f64f1..be666607823 100644
--- a/tests/test_litellm/proxy/test_common_request_processing.py
+++ b/tests/test_litellm/proxy/test_common_request_processing.py
@@ -2202,6 +2202,19 @@ class TestGuardrailBlockErrorPayloadNeverStringifiesNone:
         assert frame["error"]["param"] is None
         assert frame["error"]["code"] == "400"
 
+    def test_a_streaming_frame_keeps_the_status_a_proxy_exception_was_raised_with(self):
+        """ProxyException stores its status as the string ``code``, so a 429 raised before the
+        first chunk used to reach the SSE frame as a 500."""
+        from litellm.proxy._types import ProxyException
+        from litellm.proxy.common_request_processing import sse_error_payload
+
+        error_status, error_obj = sse_error_payload(
+            ProxyException(message="Rate limit reached", type="rate_limit_error", param=None, code=429)
+        )
+
+        assert error_status == 429
+        assert (error_obj["type"], error_obj["code"]) == ("rate_limit_error", "429")
+
     @pytest.mark.parametrize(
         "status_code, expected_type",
         [

From b3bcd715e074aa11507ee81fe06f7716ecfa0bae Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 8 Sep 2026 15:01:17 -0700
Subject: [PATCH 18/31] test(proxy): type the realtime WebRTC fixtures with
 Protocols instead of a bare Callable

---
 .../test_realtime_webrtc_endpoints.py         | 29 +++++++++++++------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
index 7436cf84fec..82f2ef097aa 100644
--- a/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
+++ b/tests/test_litellm/proxy/realtime_endpoints/test_realtime_webrtc_endpoints.py
@@ -6,7 +6,8 @@ Tests for LiteLLM proxy realtime WebRTC HTTP endpoints:
 
 import json
 import time
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable
+from typing import Protocol
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx
@@ -161,17 +162,27 @@ def mock_route_request_realtime_calls():
     return _mock_route
 
 
+class AddLitellmDataToRequest(Protocol):
+    def __call__(self, data: dict[str, object], **kwargs: object) -> Awaitable[dict[str, object]]: ...
+
+
+class PreCallHook(Protocol):
+    def __call__(
+        self, user_api_key_dict: UserAPIKeyAuth, data: dict[str, object], call_type: str
+    ) -> Awaitable[dict[str, object]]: ...
+
+
 @pytest.fixture
-def mock_add_litellm_data():
-    async def _mock(data, **kwargs):
+def mock_add_litellm_data() -> AddLitellmDataToRequest:
+    async def _mock(data: dict[str, object], **kwargs: object) -> dict[str, object]:
         return data
 
     return _mock
 
 
 @pytest.fixture
-def mock_pre_call_hook():
-    async def _mock(user_api_key_dict, data, call_type):
+def mock_pre_call_hook() -> PreCallHook:
+    async def _mock(user_api_key_dict: UserAPIKeyAuth, data: dict[str, object], call_type: str) -> dict[str, object]:
         return data
 
     return _mock
@@ -1205,8 +1216,8 @@ async def test_transcription_sessions_wraps_route_exception(
 
 def test_realtime_calls_upstream_rejection_answers_an_openai_typed_error(
     proxy_app: FastAPI,
-    mock_add_litellm_data: Callable[..., Awaitable[object]],
-    mock_pre_call_hook: Callable[..., Awaitable[object]],
+    mock_add_litellm_data: AddLitellmDataToRequest,
+    mock_pre_call_hook: PreCallHook,
     monkeypatch: pytest.MonkeyPatch,
 ):
     """A bare HTTPException carries no type or param, so the tail used to ship the
@@ -1245,8 +1256,8 @@ def test_realtime_calls_upstream_rejection_answers_an_openai_typed_error(
 
 def test_transcription_sessions_rejection_answers_an_openai_typed_error(
     proxy_app: FastAPI,
-    mock_add_litellm_data: Callable[..., Awaitable[object]],
-    mock_pre_call_hook: Callable[..., Awaitable[object]],
+    mock_add_litellm_data: AddLitellmDataToRequest,
+    mock_pre_call_hook: PreCallHook,
     monkeypatch: pytest.MonkeyPatch,
 ):
     """A model the router cannot serve surfaces as a bare HTTPException, which this tail

From 568ea11ea1b405e7a7b0c50e8750cca640aa907b Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 8 Sep 2026 15:26:49 -0700
Subject: [PATCH 19/31] chore(ui): bump Next.js and Vitest dependencies

---
 ui/litellm-dashboard/package-lock.json        | 619 +++++++-----------
 ui/litellm-dashboard/package.json             |  11 +-
 .../AccessGroupCreateDialog.test.tsx          |   4 +-
 .../cloudzero/useCloudZeroCreate.test.ts      |   4 +-
 .../cloudzero/useCloudZeroDryRun.test.ts      |   4 +-
 .../cloudzero/useCloudZeroExport.test.ts      |   4 +-
 .../cloudzero/useCloudZeroSettings.test.ts    |  11 +-
 .../hooks/proxyConfig/useProxyConfig.test.ts  |  10 +-
 .../storeModelInDB/useStoreModelInDB.test.ts  |   4 +-
 .../_components/ToolTestPanel.test.tsx        |   4 +-
 .../DefaultUserSettingsForm.test.tsx          |   7 +-
 .../view_users/UsersTable.test.tsx            |   4 +-
 ...lassifierPromptEditor.integration.test.tsx |   4 +-
 .../add_model/ComplexityRouterConfig.test.tsx |   4 +-
 .../org-create/OrgCreateDialog.test.tsx       |   4 +-
 .../org-settings/OrgSettingsForm.test.tsx     |   8 +-
 16 files changed, 265 insertions(+), 441 deletions(-)

diff --git a/ui/litellm-dashboard/package-lock.json b/ui/litellm-dashboard/package-lock.json
index 4e5b0c1dda6..d920205d203 100644
--- a/ui/litellm-dashboard/package-lock.json
+++ b/ui/litellm-dashboard/package-lock.json
@@ -24,7 +24,7 @@
         "jwt-decode": "4.0.0",
         "lucide-react": "0.513.0",
         "moment": "2.30.1",
-        "next": "16.2.11",
+        "next": "16.3.3",
         "next-themes": "^0.4.6",
         "nuqs": "^2.9.4",
         "openai": "4.104.0",
@@ -58,10 +58,10 @@
         "@types/react-copy-to-clipboard": "5.0.7",
         "@types/react-dom": "19.2.4",
         "@types/react-syntax-highlighter": "15.5.13",
-        "@vitest/coverage-v8": "3.2.6",
-        "@vitest/ui": "3.2.6",
+        "@vitest/coverage-v8": "4.1.11",
+        "@vitest/ui": "4.1.11",
         "eslint": "9.39.2",
-        "eslint-config-next": "16.2.11",
+        "eslint-config-next": "16.3.3",
         "eslint-config-prettier": "10.1.8",
         "eslint-plugin-jest-dom": "5.10.1",
         "eslint-plugin-testing-library": "7.16.2",
@@ -75,7 +75,8 @@
         "tw-animate-css": "1.4.0",
         "typescript": "5.9.3",
         "typescript-eslint": "8.60.1",
-        "vitest": "3.2.6"
+        "vite": "7.3.5",
+        "vitest": "4.1.11"
       },
       "engines": {
         "node": ">=24.14.1",
@@ -109,20 +110,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/@ampproject/remapping": {
-      "version": "2.3.0",
-      "resolved": "https://registry.npmjs.org/@ampproject/remapping/-/remapping-2.3.0.tgz",
-      "integrity": "sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==",
-      "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@jridgewell/gen-mapping": "^0.3.5",
-        "@jridgewell/trace-mapping": "^0.3.24"
-      },
-      "engines": {
-        "node": ">=6.0.0"
-      }
-    },
     "node_modules/@anthropic-ai/sdk": {
       "version": "0.92.0",
       "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.92.0.tgz",
@@ -1955,16 +1942,6 @@
         "url": "https://opencollective.com/libvips"
       }
     },
-    "node_modules/@istanbuljs/schema": {
-      "version": "0.1.6",
-      "resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.6.tgz",
-      "integrity": "sha512-+Sg6GCR/wy1oSmQDFq4LQDAhm3ETKnorxN+y5nbLULOR3P0c14f2Wurzj3/xqPXtasLFfHd5iRFQ7AJt4KH2cw==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=8"
-      }
-    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -2035,25 +2012,26 @@
       }
     },
     "node_modules/@next/env": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/env/-/env-16.2.11.tgz",
-      "integrity": "sha512-0do5A3BJ2gxWr0ZCMcD6BhW+e595jyxdTl3rXTS6lOtD8ektMiW6CO+EPwt1Eca1DBnm90r/7GdiKWBKxH++DA==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/env/-/env-16.3.3.tgz",
+      "integrity": "sha512-U2eYQRwXj+dsqxV79zFqExDdatnNY/ZWc2nsJU1p/OgT7fd3dXwlF6OjYaFQCfMoeTA19PWq+wVmYgimVA+V+g==",
       "license": "MIT"
     },
     "node_modules/@next/eslint-plugin-next": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/eslint-plugin-next/-/eslint-plugin-next-16.2.11.tgz",
-      "integrity": "sha512-vMEf/aXOpzFFdtIvFYOnIDPKb0xBbrXONsz83CcKdRrekfxNdL8PNkq5qHqAHSXVlIifnX68LOMaxr3z5PkeLQ==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/eslint-plugin-next/-/eslint-plugin-next-16.3.3.tgz",
+      "integrity": "sha512-pbEh30vvjKpDoTAmo1v3q2uM4JUi8QaEBpbmjWvGfoec2jLghy/WNtvzAT0bk+Ik9oz6etjt4YjXEk4BQnicCw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
+        "@eslint-community/eslint-utils": "4.9.1",
         "fast-glob": "3.3.1"
       }
     },
     "node_modules/@next/swc-darwin-arm64": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.2.11.tgz",
-      "integrity": "sha512-wryL4pjKmDwGv2ox6+GZDFxvmtSRLqApBR8kL1j4+vhB7Z5vJC/zAnXpiR9Xkfzl0AS8WLMnsuGV/UKI67/rrw==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.3.3.tgz",
+      "integrity": "sha512-8Hiv32QJPwdV6KYJ8meR9SBA061tQqnIKTJDocvOXlEQqib0xMFpzArosuffFUUc0sslbh7QQ8a3Yey1QV8EIw==",
       "cpu": [
         "arm64"
       ],
@@ -2067,9 +2045,9 @@
       }
     },
     "node_modules/@next/swc-darwin-x64": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.2.11.tgz",
-      "integrity": "sha512-aZl2j4f/fLyjQvOhv0Oe9UaMAQHolYpKhctsoYzplSumKJKPUmgjcf6545aBtysLTcu994TREd0+pSgNE4ohmg==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.3.3.tgz",
+      "integrity": "sha512-A1lgKgwVchRYmSe467zdwhxT9040dd8lH+o65sL5Jet8fjB4kegw/rDyPIpYVRb6jAqwXFOJpjIXJLxQKLiE3A==",
       "cpu": [
         "x64"
       ],
@@ -2083,12 +2061,15 @@
       }
     },
     "node_modules/@next/swc-linux-arm64-gnu": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.2.11.tgz",
-      "integrity": "sha512-5jEriyEnH/LWFy27L2ZG0XaLlyEJIjhsImEsiS9P563PKEVp2BVups/xfOucIrsvVntp11oNcZwjHvaDPYVB5g==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.3.3.tgz",
+      "integrity": "sha512-bf0FIssMFueU2dm7vQEWWxk0c8UjKTdW0yzuh0sQsD8pf1+KCLDdaqhYZNMYGmXwEOiHAUzgBKudovIlcvvBjg==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2099,12 +2080,15 @@
       }
     },
     "node_modules/@next/swc-linux-arm64-musl": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.2.11.tgz",
-      "integrity": "sha512-eIjcpx2fnnFSSkZDbTxy74KnokUXDjfoLClpWelfgHLf621aTqswhwXQ7GkD5K5rplrS6LZ/Bj+mVuvzluBOEg==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.3.3.tgz",
+      "integrity": "sha512-W7viwCk9JY/cAkdz/A273rd5bb3RgT/IHwR7Upv90tunjBWNtAAhGhoecHh+teRNRSinuAFmE+l7fwZ4YKkrXg==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2115,12 +2099,15 @@
       }
     },
     "node_modules/@next/swc-linux-x64-gnu": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.2.11.tgz",
-      "integrity": "sha512-8WgzpaWMs46qJT9kiV47cje86L0x/Mu9t8/Gwj+pnbgW3rETVfCnaScPjlYUwNScpOozdcIMHWmAvuZJUonR2w==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.3.3.tgz",
+      "integrity": "sha512-0W46zw1N3ODpI6n0GeivHvvob1pooozgZVqy65k0mh4/7vr+FbY9+WpHzNVXjHipJf/A3FDheBG19H1s5A25rA==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2131,12 +2118,15 @@
       }
     },
     "node_modules/@next/swc-linux-x64-musl": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.2.11.tgz",
-      "integrity": "sha512-I3UgPds7G4ZYnTb/H+5GBGuUT2DhAk6j0mL6A4s63RjFs74wB2hOWP0vaxsK+3NJraExt3eYEPQ/UtT0x/64Nw==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.3.3.tgz",
+      "integrity": "sha512-H4mBso8ZTMBPtdT0PN0pBx2ayTvQuTuvS6qT13d77yVFJXAPCxkyIhLTmdMaGTJs0krQYI/qpzdHijCeihXhbg==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -2147,9 +2137,9 @@
       }
     },
     "node_modules/@next/swc-win32-arm64-msvc": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.2.11.tgz",
-      "integrity": "sha512-n89CjtcThnjrwgJMAiI5xbqwLY51zvwC9tSlArmVndAJLYVl9T9UAdlkXTmZvE++idoXe8KdglQlhNRdUp1c6g==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.3.3.tgz",
+      "integrity": "sha512-cTMUJpcEGmeywofCUfhR+rSsoE33+rVPnPEYNTNdLNlsOeEg/vktOsKUSTb28vUGqD2jkm4Zaskcwn7OCI6FQg==",
       "cpu": [
         "arm64"
       ],
@@ -2163,9 +2153,9 @@
       }
     },
     "node_modules/@next/swc-win32-x64-msvc": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.2.11.tgz",
-      "integrity": "sha512-md8CLNggS1Dx9pUgApzps5uAf+N8GN9xywzmNx9vHAWo94HtBwCCqkSnhIrdfQe83Dhz8Lfo/20Nb1Zxal092w==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.3.3.tgz",
+      "integrity": "sha512-2VR4cTBzHXaBjnGsuH6GyJjENzQOmHeAh11uY1iUhjm3j5dEUrVJuUj+VL78jaGi/Dik8xS76zEj18BsFhlVZQ==",
       "cpu": [
         "x64"
       ],
@@ -2965,9 +2955,9 @@
       "license": "MIT"
     },
     "node_modules/@swc/helpers": {
-      "version": "0.5.15",
-      "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.15.tgz",
-      "integrity": "sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==",
+      "version": "0.5.23",
+      "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.23.tgz",
+      "integrity": "sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==",
       "license": "Apache-2.0",
       "dependencies": {
         "tslib": "^2.8.0"
@@ -4325,32 +4315,29 @@
       ]
     },
     "node_modules/@vitest/coverage-v8": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-3.2.6.tgz",
-      "integrity": "sha512-LsAdmUapA0qSN306d8+zOyawM0hFm2m2Hg9IwVNIKBm+qJV8cijiq2c+gxKZcB1HCfIWAy+0qEZDCUQA58A1cw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.11.tgz",
+      "integrity": "sha512-8MVGEFnJIcdGjcbfKmeq8z0pZHH0JlVtoVZH9Q/qwUp6wyFnEJUBMrw9DCaj+ra3vShGmhavjalMIhPNxZAUcw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@ampproject/remapping": "^2.3.0",
         "@bcoe/v8-coverage": "^1.0.2",
-        "ast-v8-to-istanbul": "^0.3.3",
-        "debug": "^4.4.1",
+        "@vitest/utils": "4.1.11",
+        "ast-v8-to-istanbul": "^1.0.0",
         "istanbul-lib-coverage": "^3.2.2",
         "istanbul-lib-report": "^3.0.1",
-        "istanbul-lib-source-maps": "^5.0.6",
-        "istanbul-reports": "^3.1.7",
-        "magic-string": "^0.30.17",
-        "magicast": "^0.3.5",
-        "std-env": "^3.9.0",
-        "test-exclude": "^7.0.1",
-        "tinyrainbow": "^2.0.0"
+        "istanbul-reports": "^3.2.0",
+        "magicast": "^0.5.2",
+        "obug": "^2.1.1",
+        "std-env": "^4.0.0-rc.1",
+        "tinyrainbow": "^3.1.0"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
-        "@vitest/browser": "3.2.6",
-        "vitest": "3.2.6"
+        "@vitest/browser": "4.1.11",
+        "vitest": "4.1.11"
       },
       "peerDependenciesMeta": {
         "@vitest/browser": {
@@ -4359,39 +4346,40 @@
       }
     },
     "node_modules/@vitest/expect": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.6.tgz",
-      "integrity": "sha512-1+7q9BtaKzEmO+fmNT3kYvoNn5Y71XWAx2Q5HRim4tTVRQVRv4uJFAQ5FbK0OPUeNP/WmVCpxYxoJdvuHVjzBQ==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz",
+      "integrity": "sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
         "@types/chai": "^5.2.2",
-        "@vitest/spy": "3.2.6",
-        "@vitest/utils": "3.2.6",
-        "chai": "^5.2.0",
-        "tinyrainbow": "^2.0.0"
+        "@vitest/spy": "4.1.11",
+        "@vitest/utils": "4.1.11",
+        "chai": "^6.2.2",
+        "tinyrainbow": "^3.1.0"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       }
     },
     "node_modules/@vitest/mocker": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.6.tgz",
-      "integrity": "sha512-EZOrpDbkKotFAP7wPAQV1UIyoGOk4oX7ynWhBhLB7v+meMHbQhU16oPpIYGTTe4oFlhpryGpgpcZP/sin3hYuw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.11.tgz",
+      "integrity": "sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/spy": "3.2.6",
+        "@vitest/spy": "4.1.11",
         "estree-walker": "^3.0.3",
-        "magic-string": "^0.30.17"
+        "magic-string": "^0.30.21"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
         "msw": "^2.4.9",
-        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
       },
       "peerDependenciesMeta": {
         "msw": {
@@ -4403,42 +4391,42 @@
       }
     },
     "node_modules/@vitest/pretty-format": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.6.tgz",
-      "integrity": "sha512-lb7XXXzmm2h2ASzFnRvQpDo6onT1NmMJA3tkGTWiBFtRJ9lxGY3d3mm/Apt36gej2bkkOVLL/yTOtufDaFa/jA==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz",
+      "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "tinyrainbow": "^2.0.0"
+        "tinyrainbow": "^3.1.0"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       }
     },
     "node_modules/@vitest/runner": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.6.tgz",
-      "integrity": "sha512-HYcoSj1w5tcgUnzoF0HcyaAQjpA1gj9ftUJ7iSJSuipc02jW9gKkigwZbjFldAfYHA1fa8UZVRftdMY5msWM9Q==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz",
+      "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "3.2.6",
-        "pathe": "^2.0.3",
-        "strip-literal": "^3.0.0"
+        "@vitest/utils": "4.1.11",
+        "pathe": "^2.0.3"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       }
     },
     "node_modules/@vitest/snapshot": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.6.tgz",
-      "integrity": "sha512-H+ZjNTWGpObenh0YnlBctAPnJSI20P81PL8BPzWpx54YXLLTm8hEsWawtcYLMrwvpK48hGxLLbCS+1KRXhsKhw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz",
+      "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "3.2.6",
-        "magic-string": "^0.30.17",
+        "@vitest/pretty-format": "4.1.11",
+        "@vitest/utils": "4.1.11",
+        "magic-string": "^0.30.21",
         "pathe": "^2.0.3"
       },
       "funding": {
@@ -4446,50 +4434,47 @@
       }
     },
     "node_modules/@vitest/spy": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.6.tgz",
-      "integrity": "sha512-oq6BbH68WzcWmwtBrU9nqLeaXTR4XwJF7FSLkKEZo4i6eoXcrxjcwSuTvWBIRUTC6VC72nXYunzqgZA+IKdtxg==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.11.tgz",
+      "integrity": "sha512-apNa/prQy2qCeywhnixOHPRCgGNhvg7T4Dapfl1GahLp/R+uhBm5cPyFoNVyqsNd2h1nJxL6BqqdIjiABL60YA==",
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "tinyspy": "^4.0.3"
-      },
       "funding": {
         "url": "https://opencollective.com/vitest"
       }
     },
     "node_modules/@vitest/ui": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-3.2.6.tgz",
-      "integrity": "sha512-mATfG3zVdhobE9U1rIpvtYD3DGuSSxqZ3Aj/8ityGqKXy8YDJ9BoAjZmAz6dZ1IZ1xI5V+MerkCczvVa+3QK9Q==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.1.11.tgz",
+      "integrity": "sha512-r/rwyKoev21mWdRGSEkZOqkQ2BYy68mwjihg9M90nNRbf4NGrgzZ4cj6JNCEwlOGJkbKeMgsjlykvwKUbRr7gw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "3.2.6",
+        "@vitest/utils": "4.1.11",
         "fflate": "^0.8.2",
-        "flatted": "^3.3.3",
+        "flatted": "^3.4.2",
         "pathe": "^2.0.3",
-        "sirv": "^3.0.1",
-        "tinyglobby": "^0.2.14",
-        "tinyrainbow": "^2.0.0"
+        "sirv": "^3.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
-        "vitest": "3.2.6"
+        "vitest": "4.1.11"
       }
     },
     "node_modules/@vitest/utils": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.6.tgz",
-      "integrity": "sha512-lI23nIs4bnT3T8NIoh+vFaz5s2/DdP0Jgt2jxwgWljvwn82cLJtyi/If+fjFyoLMGIOz0U/fKvWE0d4jsNQEfg==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz",
+      "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "3.2.6",
-        "loupe": "^3.1.4",
-        "tinyrainbow": "^2.0.0"
+        "@vitest/pretty-format": "4.1.11",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
@@ -4800,9 +4785,9 @@
       "license": "MIT"
     },
     "node_modules/ast-v8-to-istanbul": {
-      "version": "0.3.12",
-      "resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-0.3.12.tgz",
-      "integrity": "sha512-BRRC8VRZY2R4Z4lFIL35MwNXmwVqBityvOIwETtsCSwvjl0IdgFsy9NhdaA6j74nUdtJJlIypeRhpDam19Wq3g==",
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-1.0.5.tgz",
+      "integrity": "sha512-UPAgKJFSEGMWSDr3LX4tqnAb4f7KGT8O40Tyx8wbYmmZ/yn58lNCm8h3svs3eXgiGd5AXxz8NDOvXWvicq+rJA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4972,16 +4957,6 @@
         "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
       }
     },
-    "node_modules/cac": {
-      "version": "6.7.14",
-      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
-      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=8"
-      }
-    },
     "node_modules/call-bind": {
       "version": "1.0.9",
       "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.9.tgz",
@@ -5072,18 +5047,11 @@
       }
     },
     "node_modules/chai": {
-      "version": "5.3.3",
-      "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
-      "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "assertion-error": "^2.0.1",
-        "check-error": "^2.1.1",
-        "deep-eql": "^5.0.1",
-        "loupe": "^3.1.0",
-        "pathval": "^2.0.0"
-      },
       "engines": {
         "node": ">=18"
       }
@@ -5152,16 +5120,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/check-error": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",
-      "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 16"
-      }
-    },
     "node_modules/class-variance-authority": {
       "version": "0.7.1",
       "resolved": "https://registry.npmjs.org/class-variance-authority/-/class-variance-authority-0.7.1.tgz",
@@ -5577,16 +5535,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/deep-eql": {
-      "version": "5.0.2",
-      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
-      "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/deep-is": {
       "version": "0.1.4",
       "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
@@ -5862,9 +5810,9 @@
       }
     },
     "node_modules/es-module-lexer": {
-      "version": "1.7.0",
-      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
-      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
+      "integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==",
       "dev": true,
       "license": "MIT"
     },
@@ -6062,13 +6010,13 @@
       }
     },
     "node_modules/eslint-config-next": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/eslint-config-next/-/eslint-config-next-16.2.11.tgz",
-      "integrity": "sha512-FIpbK/dUyxUExchDB7eBg3k+VU8R2iR/Cx9/kqTBUTFv2bOIR9aRrpno4rvAQ9VhiPQAyFKNA2NlZwouGWtclA==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/eslint-config-next/-/eslint-config-next-16.3.3.tgz",
+      "integrity": "sha512-teqtsR26tnlfXFHfVLTM/4tzEzU8DMu6GS1sddZzhfGzgd2f2ofbgDUcsk6cssSCzX6Tk6fmWifJcdANSdPJrw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@next/eslint-plugin-next": "16.2.11",
+        "@next/eslint-plugin-next": "16.3.3",
         "eslint-import-resolver-node": "^0.3.6",
         "eslint-import-resolver-typescript": "^3.5.2",
         "eslint-plugin-import": "^2.32.0",
@@ -6546,9 +6494,9 @@
       "license": "MIT"
     },
     "node_modules/expect-type": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
-      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+      "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
       "dev": true,
       "license": "Apache-2.0",
       "engines": {
@@ -6952,24 +6900,6 @@
         "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
       }
     },
-    "node_modules/glob": {
-      "version": "13.0.0",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.0.tgz",
-      "integrity": "sha512-tvZgpqk6fz4BaNZ66ZsRaZnbHvP/jG3uKJvAZOwEVUL4RTA5nJeeLYfyN9/VA8NX/V3IBG+hkeuGpKjvELkVhA==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "minimatch": "^10.1.1",
-        "minipass": "^7.1.2",
-        "path-scurry": "^2.0.0"
-      },
-      "engines": {
-        "node": "20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/glob-parent": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz",
@@ -7941,21 +7871,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/istanbul-lib-source-maps": {
-      "version": "5.0.6",
-      "resolved": "https://registry.npmjs.org/istanbul-lib-source-maps/-/istanbul-lib-source-maps-5.0.6.tgz",
-      "integrity": "sha512-yg2d+Em4KizZC5niWhQaIomgf5WlL4vOOjZ5xGCmF8SnPE/mDWWXgvRExdcpCgh9lLRRa1/fSYp2ymmbJ1pI+A==",
-      "dev": true,
-      "license": "BSD-3-Clause",
-      "dependencies": {
-        "@jridgewell/trace-mapping": "^0.3.23",
-        "debug": "^4.1.1",
-        "istanbul-lib-coverage": "^3.0.0"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/istanbul-reports": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
@@ -8607,13 +8522,6 @@
         "loose-envify": "cli.js"
       }
     },
-    "node_modules/loupe": {
-      "version": "3.2.1",
-      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
-      "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/lowlight": {
       "version": "1.20.0",
       "resolved": "https://registry.npmjs.org/lowlight/-/lowlight-1.20.0.tgz",
@@ -8668,15 +8576,15 @@
       }
     },
     "node_modules/magicast": {
-      "version": "0.3.5",
-      "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.3.5.tgz",
-      "integrity": "sha512-L0WhttDl+2BOsybvEOLK7fW3UA0OQ0IQ2d6Zl2x/a6vVRs3bAY0ECOSHHeL5jD+SbOpOCUEi0y1DgHEn9Qn1AQ==",
+      "version": "0.5.4",
+      "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.4.tgz",
+      "integrity": "sha512-llBEhWm1SacoRwgHUoQJYtwp4PBLF4faQi5TCpIGyGs9n4y5+juI0tDgyKIfpqxckRHaHzouUEph3THklWh03w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@babel/parser": "^7.25.4",
-        "@babel/types": "^7.25.4",
-        "source-map-js": "^1.2.0"
+        "@babel/parser": "^7.29.7",
+        "@babel/types": "^7.29.7",
+        "source-map-js": "^1.2.1"
       }
     },
     "node_modules/make-dir": {
@@ -9670,16 +9578,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/minipass": {
-      "version": "7.1.3",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
-      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": ">=16 || 14 >=14.17"
-      }
-    },
     "node_modules/moment": {
       "version": "2.30.1",
       "resolved": "https://registry.npmjs.org/moment/-/moment-2.30.1.tgz",
@@ -9747,16 +9645,16 @@
       "license": "MIT"
     },
     "node_modules/next": {
-      "version": "16.2.11",
-      "resolved": "https://registry.npmjs.org/next/-/next-16.2.11.tgz",
-      "integrity": "sha512-B339zaqbyK8cmxhoAvLrcwoabwCP1wz21zSzfqxqXAemTu2BXnH7tQnfcglKv1vnMUIDBc+Hth7XODQriTZiRQ==",
+      "version": "16.3.3",
+      "resolved": "https://registry.npmjs.org/next/-/next-16.3.3.tgz",
+      "integrity": "sha512-tuRTx1nQ/yVw83cwJBo9F+njGUgMn3UHQycreWHB8XsStvvAh1AthbI8/4IpKnFaF58F+iSiHejYOlMQ/eq83g==",
       "license": "MIT",
       "dependencies": {
-        "@next/env": "16.2.11",
-        "@swc/helpers": "0.5.15",
+        "@next/env": "16.3.3",
+        "@swc/helpers": "0.5.23",
         "baseline-browser-mapping": "^2.9.19",
         "caniuse-lite": "^1.0.30001579",
-        "postcss": "8.4.31",
+        "postcss": "8.5.23",
         "styled-jsx": "5.1.6"
       },
       "bin": {
@@ -9766,15 +9664,15 @@
         "node": ">=20.9.0"
       },
       "optionalDependencies": {
-        "@next/swc-darwin-arm64": "16.2.11",
-        "@next/swc-darwin-x64": "16.2.11",
-        "@next/swc-linux-arm64-gnu": "16.2.11",
-        "@next/swc-linux-arm64-musl": "16.2.11",
-        "@next/swc-linux-x64-gnu": "16.2.11",
-        "@next/swc-linux-x64-musl": "16.2.11",
-        "@next/swc-win32-arm64-msvc": "16.2.11",
-        "@next/swc-win32-x64-msvc": "16.2.11",
-        "sharp": "^0.34.5"
+        "@next/swc-darwin-arm64": "16.3.3",
+        "@next/swc-darwin-x64": "16.3.3",
+        "@next/swc-linux-arm64-gnu": "16.3.3",
+        "@next/swc-linux-arm64-musl": "16.3.3",
+        "@next/swc-linux-x64-gnu": "16.3.3",
+        "@next/swc-linux-x64-musl": "16.3.3",
+        "@next/swc-win32-arm64-msvc": "16.3.3",
+        "@next/swc-win32-x64-msvc": "16.3.3",
+        "sharp": "^0.35.3"
       },
       "peerDependencies": {
         "@opentelemetry/api": "^1.1.0",
@@ -10069,6 +9967,20 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/obug": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.4.tgz",
+      "integrity": "sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20.0"
+      }
+    },
     "node_modules/openai": {
       "version": "4.104.0",
       "resolved": "https://registry.npmjs.org/openai/-/openai-4.104.0.tgz",
@@ -10378,23 +10290,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/path-scurry": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
-      "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "lru-cache": "^11.0.0",
-        "minipass": "^7.1.2"
-      },
-      "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/pathe": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
@@ -10402,16 +10297,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/pathval": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",
-      "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 14.16"
-      }
-    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -11531,9 +11416,9 @@
       "license": "MIT"
     },
     "node_modules/std-env": {
-      "version": "3.10.0",
-      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
-      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.2.0.tgz",
+      "integrity": "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==",
       "dev": true,
       "license": "MIT"
     },
@@ -11714,26 +11599,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/strip-literal": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/strip-literal/-/strip-literal-3.1.0.tgz",
-      "integrity": "sha512-8r3mkIM/2+PpjHoOtiAW8Rg3jJLHaV7xPwG+YRGrv6FP0wwk/toTpATxWYOW0BKdWwl82VT2tFYi5DlROa0Mxg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "js-tokens": "^9.0.1"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/antfu"
-      }
-    },
-    "node_modules/strip-literal/node_modules/js-tokens": {
-      "version": "9.0.1",
-      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
-      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
-      "dev": true,
-      "license": "MIT"
-    },
     "node_modules/style-to-js": {
       "version": "1.1.21",
       "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz",
@@ -11838,21 +11703,6 @@
         "url": "https://opencollective.com/webpack"
       }
     },
-    "node_modules/test-exclude": {
-      "version": "7.0.2",
-      "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-7.0.2.tgz",
-      "integrity": "sha512-u9E6A+ZDYdp7a4WnarkXPZOx8Ilz46+kby6p1yZ8zsGTz9gYa6FIS7lj2oezzNKmtdyyJNNmmXDppga5GB7kSw==",
-      "dev": true,
-      "license": "ISC",
-      "dependencies": {
-        "@istanbuljs/schema": "^0.1.2",
-        "glob": "^10.4.1",
-        "minimatch": "^10.2.2"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/tiny-invariant": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz",
@@ -11867,11 +11717,14 @@
       "license": "MIT"
     },
     "node_modules/tinyexec": {
-      "version": "0.3.2",
-      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
-      "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz",
+      "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
     },
     "node_modules/tinyglobby": {
       "version": "0.2.16",
@@ -11890,30 +11743,10 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
-    "node_modules/tinypool": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",
-      "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "^18.0.0 || >=20.0.0"
-      }
-    },
     "node_modules/tinyrainbow": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-2.0.0.tgz",
-      "integrity": "sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=14.0.0"
-      }
-    },
-    "node_modules/tinyspy": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",
-      "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
+      "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -12547,29 +12380,6 @@
         }
       }
     },
-    "node_modules/vite-node": {
-      "version": "3.2.4",
-      "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-3.2.4.tgz",
-      "integrity": "sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "cac": "^6.7.14",
-        "debug": "^4.4.1",
-        "es-module-lexer": "^1.7.0",
-        "pathe": "^2.0.3",
-        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
-      },
-      "bin": {
-        "vite-node": "vite-node.mjs"
-      },
-      "engines": {
-        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/vitest"
-      }
-    },
     "node_modules/vite/node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -12586,65 +12396,79 @@
       }
     },
     "node_modules/vitest": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.6.tgz",
-      "integrity": "sha512-xejya+bT/j/+R/AGa1XOfRxLmNUlLtlwjRsFUILF+xHfzElmGcmFydy2gqqIrd62ptIEfwVMofd19uNWD9L7Nw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz",
+      "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@types/chai": "^5.2.2",
-        "@vitest/expect": "3.2.6",
-        "@vitest/mocker": "3.2.6",
-        "@vitest/pretty-format": "^3.2.6",
-        "@vitest/runner": "3.2.6",
-        "@vitest/snapshot": "3.2.6",
-        "@vitest/spy": "3.2.6",
-        "@vitest/utils": "3.2.6",
-        "chai": "^5.2.0",
-        "debug": "^4.4.1",
-        "expect-type": "^1.2.1",
-        "magic-string": "^0.30.17",
+        "@vitest/expect": "4.1.11",
+        "@vitest/mocker": "4.1.11",
+        "@vitest/pretty-format": "4.1.11",
+        "@vitest/runner": "4.1.11",
+        "@vitest/snapshot": "4.1.11",
+        "@vitest/spy": "4.1.11",
+        "@vitest/utils": "4.1.11",
+        "es-module-lexer": "^2.0.0",
+        "expect-type": "^1.3.0",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
         "pathe": "^2.0.3",
-        "picomatch": "^4.0.2",
-        "std-env": "^3.9.0",
+        "picomatch": "^4.0.3",
+        "std-env": "^4.0.0-rc.1",
         "tinybench": "^2.9.0",
-        "tinyexec": "^0.3.2",
-        "tinyglobby": "^0.2.14",
-        "tinypool": "^1.1.1",
-        "tinyrainbow": "^2.0.0",
-        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0",
-        "vite-node": "3.2.4",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
         "why-is-node-running": "^2.3.0"
       },
       "bin": {
         "vitest": "vitest.mjs"
       },
       "engines": {
-        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
       },
       "funding": {
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
         "@edge-runtime/vm": "*",
-        "@types/debug": "^4.1.12",
-        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
-        "@vitest/browser": "3.2.6",
-        "@vitest/ui": "3.2.6",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.1.11",
+        "@vitest/browser-preview": "4.1.11",
+        "@vitest/browser-webdriverio": "4.1.11",
+        "@vitest/coverage-istanbul": "4.1.11",
+        "@vitest/coverage-v8": "4.1.11",
+        "@vitest/ui": "4.1.11",
         "happy-dom": "*",
-        "jsdom": "*"
+        "jsdom": "*",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
       },
       "peerDependenciesMeta": {
         "@edge-runtime/vm": {
           "optional": true
         },
-        "@types/debug": {
+        "@opentelemetry/api": {
           "optional": true
         },
         "@types/node": {
           "optional": true
         },
-        "@vitest/browser": {
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
           "optional": true
         },
         "@vitest/ui": {
@@ -12655,6 +12479,9 @@
         },
         "jsdom": {
           "optional": true
+        },
+        "vite": {
+          "optional": false
         }
       }
     },
diff --git a/ui/litellm-dashboard/package.json b/ui/litellm-dashboard/package.json
index ededdfb4606..5dd70dff4fe 100644
--- a/ui/litellm-dashboard/package.json
+++ b/ui/litellm-dashboard/package.json
@@ -40,7 +40,7 @@
     "jwt-decode": "4.0.0",
     "lucide-react": "0.513.0",
     "moment": "2.30.1",
-    "next": "16.2.11",
+    "next": "16.3.3",
     "next-themes": "^0.4.6",
     "nuqs": "^2.9.4",
     "openai": "4.104.0",
@@ -74,10 +74,10 @@
     "@types/react-copy-to-clipboard": "5.0.7",
     "@types/react-dom": "19.2.4",
     "@types/react-syntax-highlighter": "15.5.13",
-    "@vitest/coverage-v8": "3.2.6",
-    "@vitest/ui": "3.2.6",
+    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/ui": "4.1.11",
     "eslint": "9.39.2",
-    "eslint-config-next": "16.2.11",
+    "eslint-config-next": "16.3.3",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-jest-dom": "5.10.1",
     "eslint-plugin-testing-library": "7.16.2",
@@ -91,7 +91,8 @@
     "tw-animate-css": "1.4.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.60.1",
-    "vitest": "3.2.6"
+    "vite": "7.3.5",
+    "vitest": "4.1.11"
   },
   "overrides": {
     "prismjs": "1.30.0",
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/access-groups/_components/access-group-create/AccessGroupCreateDialog.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/access-groups/_components/access-group-create/AccessGroupCreateDialog.test.tsx
index 7a006efce1e..1ea7286c686 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/access-groups/_components/access-group-create/AccessGroupCreateDialog.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/access-groups/_components/access-group-create/AccessGroupCreateDialog.test.tsx
@@ -2,7 +2,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import React from "react";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, type Mock } from "vitest";
 
 vi.mock("@/components/ModelSelect/ModelSelect", () => ({
   ModelSelect: ({ onChange }: { onChange: (values: string[]) => void }) => (
@@ -32,7 +32,7 @@ const Harness = ({ createAccessGroup }: { createAccessGroup: (body: unknown) =>
   );
 };
 
-const renderDialog = (overrides?: { createAccessGroup?: ReturnType<typeof vi.fn> }) => {
+const renderDialog = (overrides?: { createAccessGroup?: Mock }) => {
   const createAccessGroup = overrides?.createAccessGroup ?? vi.fn().mockResolvedValue({});
   const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
   render(
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroCreate.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroCreate.test.ts
index f370e4d6d6e..f0cfd2a4e30 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroCreate.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroCreate.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { ReactNode } from "react";
@@ -28,7 +28,7 @@ vi.mock("@/components/networking", () => ({
 
 describe("useCloudZeroCreate", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroDryRun.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroDryRun.test.ts
index b5b903ea620..5e9446be1d2 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroDryRun.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroDryRun.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { ReactNode } from "react";
@@ -28,7 +28,7 @@ vi.mock("@/components/networking", () => ({
 
 describe("useCloudZeroDryRun", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroExport.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroExport.test.ts
index 3c44d75dd06..20f33dfeeef 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroExport.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroExport.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { ReactNode } from "react";
@@ -28,7 +28,7 @@ vi.mock("@/components/networking", () => ({
 
 describe("useCloudZeroExport", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroSettings.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroSettings.test.ts
index b0c96987519..53d5b874b9e 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroSettings.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/cloudzero/useCloudZeroSettings.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { ReactNode } from "react";
@@ -54,7 +54,7 @@ const mockCloudZeroSettings: CloudZeroSettings = {
 
 describe("useCloudZeroSettings", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
@@ -69,6 +69,7 @@ describe("useCloudZeroSettings", () => {
     });
 
     vi.clearAllMocks();
+    mockGetProxyBaseUrl.mockReset();
 
     fetchSpy = vi.fn();
     global.fetch = fetchSpy;
@@ -240,7 +241,7 @@ describe("useCloudZeroSettings", () => {
 
 describe("useCloudZeroUpdateSettings", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
@@ -255,6 +256,7 @@ describe("useCloudZeroUpdateSettings", () => {
     });
 
     vi.clearAllMocks();
+    mockGetProxyBaseUrl.mockReset();
 
     fetchSpy = vi.fn();
     global.fetch = fetchSpy;
@@ -481,7 +483,7 @@ describe("useCloudZeroUpdateSettings", () => {
 
 describe("useCloudZeroDeleteSettings", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
@@ -496,6 +498,7 @@ describe("useCloudZeroDeleteSettings", () => {
     });
 
     vi.clearAllMocks();
+    mockGetProxyBaseUrl.mockReset();
 
     fetchSpy = vi.fn();
     global.fetch = fetchSpy;
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/proxyConfig/useProxyConfig.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/proxyConfig/useProxyConfig.test.ts
index 4ba80df5c6c..822f04e6dc2 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/proxyConfig/useProxyConfig.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/proxyConfig/useProxyConfig.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { ReactNode } from "react";
@@ -109,7 +109,7 @@ vi.mock("../common/queryKeysFactory", () => ({
 
 describe("useProxyConfig", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
@@ -277,7 +277,7 @@ describe("useProxyConfig", () => {
 
 describe("useDeleteProxyConfigField", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
@@ -452,7 +452,7 @@ describe("useDeleteProxyConfigField", () => {
 });
 
 describe("getProxyConfigCall", () => {
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
   let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
@@ -508,7 +508,7 @@ describe("getProxyConfigCall", () => {
 });
 
 describe("deleteProxyConfigFieldCall", () => {
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
   let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/storeModelInDB/useStoreModelInDB.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/storeModelInDB/useStoreModelInDB.test.ts
index dd69e8c8791..696383b04c8 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/storeModelInDB/useStoreModelInDB.test.ts
+++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/storeModelInDB/useStoreModelInDB.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from "vitest";
 import { renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import React, { ReactNode } from "react";
@@ -11,7 +11,7 @@ vi.mock("@/components/networking", () => ({
 
 describe("useStoreModelInDB", () => {
   let queryClient: QueryClient;
-  let fetchSpy: ReturnType<typeof vi.fn>;
+  let fetchSpy: Mock;
 
   beforeEach(() => {
     queryClient = new QueryClient({
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/ToolTestPanel.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/ToolTestPanel.test.tsx
index 81c55e7982a..43e0b1ddd1f 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/ToolTestPanel.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/mcp-servers/_components/ToolTestPanel.test.tsx
@@ -2,7 +2,7 @@ import React from "react";
 import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import type { UserEvent } from "@testing-library/user-event";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, type Mock } from "vitest";
 
 import { ToolTestPanel } from "./ToolTestPanel";
 import { InputSchema, MCPTool } from "@/components/mcp_tools/types";
@@ -341,7 +341,7 @@ describe("ToolTestPanel argument payload", () => {
 });
 
 describe("ToolTestPanel schema changes under a stable tool name", () => {
-  const renderWith = (schema: InputSchema, onSubmit: ReturnType<typeof vi.fn>) => (
+  const renderWith = (schema: InputSchema, onSubmit: Mock) => (
     <ToolTestPanel
       tool={buildTool(schema)}
       onSubmit={onSubmit}
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/users/_components/default-user-settings/DefaultUserSettingsForm.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/users/_components/default-user-settings/DefaultUserSettingsForm.test.tsx
index 15ab243b868..a10e70dcb87 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/users/_components/default-user-settings/DefaultUserSettingsForm.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/users/_components/default-user-settings/DefaultUserSettingsForm.test.tsx
@@ -2,7 +2,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import React from "react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 
 vi.mock("@/app/(dashboard)/hooks/teams/useTeams", () => ({
   useInfiniteTeams: () => ({
@@ -65,10 +65,7 @@ const SAVED_BODY = {
   teams: [{ team_id: "team-alpha", max_budget_in_team: 25, user_role: "user" }],
 };
 
-const renderForm = (overrides?: {
-  fetchSettings?: ReturnType<typeof vi.fn>;
-  updateSettings?: ReturnType<typeof vi.fn>;
-}) => {
+const renderForm = (overrides?: { fetchSettings?: Mock; updateSettings?: Mock }) => {
   const fetchSettings = overrides?.fetchSettings ?? vi.fn().mockResolvedValue(SETTINGS);
   const updateSettings = overrides?.updateSettings ?? vi.fn().mockResolvedValue(undefined);
   const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/users/_components/view_users/UsersTable.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/users/_components/view_users/UsersTable.test.tsx
index 860b1c35cfd..16911946d34 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/users/_components/view_users/UsersTable.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/users/_components/view_users/UsersTable.test.tsx
@@ -3,7 +3,7 @@ import type { PaginationState, RowSelectionState, SortingState } from "@tanstack
 import { render, screen, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { useState } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, type Mock } from "vitest";
 
 import { UserInfo } from "@/components/networking";
 
@@ -39,7 +39,7 @@ interface HarnessOverrides {
   onUserClick?: (userId: string, openInEditMode?: boolean) => void;
   onDeleteUser?: (user: UserInfo) => void;
   onResetPassword?: (userId: string) => void;
-  onSortingChange?: ReturnType<typeof vi.fn>;
+  onSortingChange?: Mock;
 }
 
 /**
diff --git a/ui/litellm-dashboard/src/components/add_model/ClassifierPromptEditor.integration.test.tsx b/ui/litellm-dashboard/src/components/add_model/ClassifierPromptEditor.integration.test.tsx
index 22720a01a6c..667ee8d6d43 100644
--- a/ui/litellm-dashboard/src/components/add_model/ClassifierPromptEditor.integration.test.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ClassifierPromptEditor.integration.test.tsx
@@ -1,6 +1,6 @@
 import { fireEvent, renderWithProviders, screen } from "../../../tests/test-utils";
 import userEvent from "@testing-library/user-event";
-import { vi } from "vitest";
+import { vi, type Mock } from "vitest";
 import ClassifierPromptEditor from "./ClassifierPromptEditor";
 import { ClassificationRubric } from "./ComplexityRouterConfig";
 vi.mock(
@@ -26,7 +26,7 @@ beforeEach(() => {
 
 interface OpenEditorOptions {
   systemPrompt?: string;
-  onChange?: ReturnType<typeof vi.fn>;
+  onChange?: Mock;
   contextWindowSize?: number;
   tierLabels?: Record<string, string>;
   classificationRubric?: ClassificationRubric;
diff --git a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.test.tsx b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.test.tsx
index 0c12cc0ba1a..f9a6321dac9 100644
--- a/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.test.tsx
+++ b/ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.test.tsx
@@ -1,7 +1,7 @@
 import { fireEvent, renderWithProviders, screen, within } from "../../../tests/test-utils";
 import userEvent from "@testing-library/user-event";
 import React from "react";
-import { vi } from "vitest";
+import { vi, type Mock } from "vitest";
 import ComplexityRouterConfig, { ComplexityRouterConfigValue } from "./ComplexityRouterConfig";
 vi.mock(
   "@/app/(dashboard)/hooks/autoRouter/useComplexityScorerDefaults",
@@ -1701,7 +1701,7 @@ describe("classifier vision settings", () => {
     classifier_llm_config: { model: "gpt-3.5-turbo", timeout_ms: 3000 },
   };
 
-  const VisionFixture = ({ onChange = vi.fn() }: { onChange?: ReturnType<typeof vi.fn> }) => {
+  const VisionFixture = ({ onChange = vi.fn() }: { onChange?: Mock }) => {
     const [value, setValue] = React.useState(llmValue);
     return (
       <ComplexityRouterConfig
diff --git a/ui/litellm-dashboard/src/components/organization/org-create/OrgCreateDialog.test.tsx b/ui/litellm-dashboard/src/components/organization/org-create/OrgCreateDialog.test.tsx
index 3ffb11fb90d..22b9dd26732 100644
--- a/ui/litellm-dashboard/src/components/organization/org-create/OrgCreateDialog.test.tsx
+++ b/ui/litellm-dashboard/src/components/organization/org-create/OrgCreateDialog.test.tsx
@@ -2,7 +2,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import React from "react";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, type Mock } from "vitest";
 
 vi.mock("@/components/ModelSelect/ModelSelect", () => ({
   ModelSelect: ({ onChange }: { onChange: (values: string[]) => void }) => (
@@ -46,7 +46,7 @@ const Harness = ({ createOrganization }: { createOrganization: (body: unknown) =
   );
 };
 
-const renderDialog = (overrides?: { createOrganization?: ReturnType<typeof vi.fn> }) => {
+const renderDialog = (overrides?: { createOrganization?: Mock }) => {
   const createOrganization = overrides?.createOrganization ?? vi.fn().mockResolvedValue({});
   const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
   render(
diff --git a/ui/litellm-dashboard/src/components/organization/org-settings/OrgSettingsForm.test.tsx b/ui/litellm-dashboard/src/components/organization/org-settings/OrgSettingsForm.test.tsx
index 5633424902d..5eaeed7b531 100644
--- a/ui/litellm-dashboard/src/components/organization/org-settings/OrgSettingsForm.test.tsx
+++ b/ui/litellm-dashboard/src/components/organization/org-settings/OrgSettingsForm.test.tsx
@@ -2,7 +2,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import React from "react";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, type Mock } from "vitest";
 
 vi.mock("@/components/ModelSelect/ModelSelect", () => ({
   ModelSelect: ({ onChange }: { onChange: (values: string[]) => void }) => (
@@ -67,11 +67,7 @@ const org: Organization = {
   },
 };
 
-const renderForm = (overrides?: {
-  patchOrganization?: ReturnType<typeof vi.fn>;
-  onSaved?: () => void;
-  org?: Organization;
-}) => {
+const renderForm = (overrides?: { patchOrganization?: Mock; onSaved?: () => void; org?: Organization }) => {
   const patchOrganization = overrides?.patchOrganization ?? vi.fn().mockResolvedValue({});
   const onSaved = overrides?.onSaved ?? vi.fn();
   const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });

From 183d05ae052799c5d19ad597f2747ee333827182 Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 15:45:32 -0700
Subject: [PATCH 20/31] feat(otel): add http/json export protocol for OTel v2
 traces (#40290)

* feat(otel): add http/json export protocol for OTel v2 traces

OTEL_EXPORTER_OTLP_PROTOCOL=http/json was accepted but routed to the protobuf
OTLP/HTTP exporter, so collectors that only decode JSON rejected every batch.
Route it to an OTLP/JSON span exporter that reuses the SDK HTTP transport and
expose the protocol as a select field on the OpenTelemetry callback in the
admin UI.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* refactor(otel): walk the fixed OTLP shape instead of recursing when hex-encoding ids

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix(ui): map stored callback variables onto their form fields when editing a callback

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: yassin <yassin@berri.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/integrations/callback_configs.json    |   7 ++
 litellm/integrations/otel/model/config.py     |   2 +-
 .../integrations/otel/plumbing/otlp_json.py   |  70 ++++++++++++
 .../integrations/otel/plumbing/providers.py   |  10 +-
 litellm/proxy/_types.py                       |   1 +
 .../otel/test_otel_v2_components.py           | 104 +++++++++++++++++-
 .../src/components/callback_info_helpers.tsx  |   1 +
 .../src/components/settings.test.tsx          |  83 ++++++++++++++
 .../src/components/settings.tsx               |  84 +++++++++-----
 9 files changed, 334 insertions(+), 28 deletions(-)
 create mode 100644 litellm/integrations/otel/plumbing/otlp_json.py

diff --git a/litellm/integrations/callback_configs.json b/litellm/integrations/callback_configs.json
index b98eef8329b..c40b90cee25 100644
--- a/litellm/integrations/callback_configs.json
+++ b/litellm/integrations/callback_configs.json
@@ -367,6 +367,13 @@
         "ui_name": "Headers",
         "description": "Headers for OTEL exporter (e.g., x-honeycomb-team=YOUR_API_KEY)",
         "required": false
+      },
+      "otel_exporter_otlp_protocol": {
+        "type": "select",
+        "ui_name": "Export Protocol",
+        "description": "OTLP wire format for trace exports. Use http/json for collectors that cannot decode protobuf",
+        "options": ["http/protobuf", "http/json"],
+        "required": false
       }
     },
     "description": "OpenTelemetry Logging Integration"
diff --git a/litellm/integrations/otel/model/config.py b/litellm/integrations/otel/model/config.py
index e3501d0ee94..422c8409411 100644
--- a/litellm/integrations/otel/model/config.py
+++ b/litellm/integrations/otel/model/config.py
@@ -69,7 +69,7 @@ class ExporterSpec(BaseModel):
 
     kind: str = Field(
         default="console",
-        description="console | in_memory | otlp_http | otlp_grpc | <factory kind>",
+        description="console | in_memory | otlp_http | http/json | otlp_grpc | <factory kind>",
     )
     endpoint: str | None = None
     traces_endpoint: str | None = Field(
diff --git a/litellm/integrations/otel/plumbing/otlp_json.py b/litellm/integrations/otel/plumbing/otlp_json.py
new file mode 100644
index 00000000000..b4b659f1e01
--- /dev/null
+++ b/litellm/integrations/otel/plumbing/otlp_json.py
@@ -0,0 +1,70 @@
+"""OTLP/HTTP span exporter that sends the OTLP/JSON encoding instead of protobuf.
+
+The SDK only ships a protobuf OTLP/HTTP exporter; this reuses its transport and
+retry loop and swaps the payload for OTLP/JSON (enums as integers, ids as hex).
+"""
+
+import base64
+import json
+from collections.abc import Mapping, Sequence
+from types import MappingProxyType
+from typing import Final, TypeAlias
+
+from google.protobuf.json_format import MessageToDict
+from opentelemetry.exporter.otlp.proto.common.trace_encoder import encode_spans
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import ReadableSpan
+
+JSON_CONTENT_TYPE: Final = "application/json"
+_HEX_ID_KEYS: Final = frozenset({"traceId", "spanId", "parentSpanId"})
+
+_JsonValue: TypeAlias = "Mapping[str, _JsonValue] | Sequence[_JsonValue] | str | int | float | bool | None"
+_JsonObject: TypeAlias = Mapping[str, "_JsonValue"]
+
+
+def _objects(node: _JsonObject, key: str) -> tuple[_JsonObject, ...]:
+    items: Final = node.get(key)
+    if isinstance(items, str) or not isinstance(items, Sequence):
+        return ()
+    return tuple(item for item in items if isinstance(item, Mapping))
+
+
+def _hex_ids(node: _JsonObject) -> _JsonObject:
+    return MappingProxyType(
+        {
+            key: base64.b64decode(item).hex() if key in _HEX_ID_KEYS and isinstance(item, str) else item
+            for key, item in node.items()
+        }
+    )
+
+
+def _hex_span(span: _JsonObject) -> _JsonObject:
+    links: Final = _objects(span, "links")
+    if not links:
+        return _hex_ids(span)
+    return MappingProxyType({**_hex_ids(span), "links": tuple(_hex_ids(link) for link in links)})
+
+
+def _hex_scope_spans(scope: _JsonObject) -> _JsonObject:
+    return MappingProxyType({**scope, "spans": tuple(_hex_span(span) for span in _objects(scope, "spans"))})
+
+
+def _hex_resource_spans(resource: _JsonObject) -> _JsonObject:
+    scope_spans: Final = tuple(_hex_scope_spans(scope) for scope in _objects(resource, "scopeSpans"))
+    return MappingProxyType({**resource, "scopeSpans": scope_spans})
+
+
+def encode_spans_json(spans: Sequence[ReadableSpan]) -> bytes:
+    payload: Final[_JsonObject] = MessageToDict(encode_spans(spans), use_integers_for_enums=True)
+    resource_spans: Final = tuple(_hex_resource_spans(resource) for resource in _objects(payload, "resourceSpans"))
+    hexed: Final[_JsonObject] = MappingProxyType({**payload, "resourceSpans": resource_spans})
+    return json.dumps(hexed, default=dict, separators=(",", ":")).encode()
+
+
+class OTLPJsonSpanExporter(OTLPSpanExporter):
+    def __init__(self, endpoint: str | None, headers: dict[str, str]) -> None:  # mutable-ok: SDK __init__ takes Dict
+        super().__init__(endpoint=endpoint, headers=headers)
+        self._session.headers["Content-Type"] = JSON_CONTENT_TYPE
+
+    def _serialize_spans(self, spans: Sequence[ReadableSpan]) -> bytes:
+        return encode_spans_json(spans)
diff --git a/litellm/integrations/otel/plumbing/providers.py b/litellm/integrations/otel/plumbing/providers.py
index d8da53017ab..90e68b7c2ee 100644
--- a/litellm/integrations/otel/plumbing/providers.py
+++ b/litellm/integrations/otel/plumbing/providers.py
@@ -136,7 +136,8 @@ def parse_headers(raw: str | None) -> dict[str, str]:
 
 
 _IN_MEMORY_KINDS: Final = ("in_memory", "inmemory", "memory")
-_OTLP_HTTP_KINDS: Final = ("otlp_http", "http", "http/protobuf", "http/json")
+_OTLP_HTTP_JSON_KINDS: Final = ("http/json",)
+_OTLP_HTTP_KINDS: Final = ("otlp_http", "http", "http/protobuf", *_OTLP_HTTP_JSON_KINDS)
 _OTLP_GRPC_KINDS: Final = ("otlp_grpc", "grpc")
 
 
@@ -164,6 +165,13 @@ def _exporter_from_spec(spec: ExporterSpec) -> SpanExporter:
         return factory(spec)
     if kind in _IN_MEMORY_KINDS:
         return InMemorySpanExporter()
+    if kind in _OTLP_HTTP_JSON_KINDS:
+        from litellm.integrations.otel.plumbing.otlp_json import OTLPJsonSpanExporter
+
+        return OTLPJsonSpanExporter(
+            endpoint=spec.traces_endpoint or _otlp_traces_endpoint(spec.endpoint),
+            headers=parse_headers(spec.headers),
+        )
     if kind in _OTLP_HTTP_KINDS:
         from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
             OTLPSpanExporter as HTTPExporter,
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index d1b391d57a3..50b87264f3f 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -3584,6 +3584,7 @@ class AllCallbacks(LiteLLMPydanticObjectBase):
         ui_callback_name="OpenTelemetry",
         litellm_callback_params=[
             "OTEL_EXPORTER",
+            "OTEL_EXPORTER_OTLP_PROTOCOL",
             "OTEL_ENDPOINT",
             "OTEL_TRACES_ENDPOINT",
             "OTEL_HEADERS",
diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_components.py b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
index 6676714d7f5..ae41c74944d 100644
--- a/tests/test_litellm/integrations/otel/test_otel_v2_components.py
+++ b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
@@ -6,14 +6,18 @@ import json
 import threading
 from collections.abc import Iterator
 from dataclasses import replace
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from http.server import BaseHTTPRequestHandler, HTTPServer, ThreadingHTTPServer
 
 import pytest
 
 pytest.importorskip("opentelemetry")
 
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (  # noqa: E402
+    ExportTraceServiceRequest,
+)
 from opentelemetry.sdk.metrics import MeterProvider  # noqa: E402
 from opentelemetry.sdk.metrics.export import InMemoryMetricReader  # noqa: E402
+from opentelemetry.sdk.trace import TracerProvider  # noqa: E402
 from opentelemetry.sdk.trace.export import (  # noqa: E402
     BatchSpanProcessor,
     ConsoleSpanExporter,
@@ -541,6 +545,89 @@ def test_build_span_exporter_variants():
     assert "OTLPSpanExporter" in type(http_exporter).__name__
 
 
+def _export_one_trace_to_local_collector(exporter_kind: str) -> tuple[list[dict], tuple[int, int, int]]:
+    """Run a parent/child trace through the configured exporter against a
+    throwaway HTTP collector. Returns the requests as the collector saw them
+    (child first, since it ends first) and (trace_id, parent span_id, child span_id)."""
+    received: list[dict] = []
+
+    class Collector(BaseHTTPRequestHandler):
+        def do_POST(self):
+            body = self.rfile.read(int(self.headers["Content-Length"]))
+            received.append({"path": self.path, "headers": dict(self.headers), "body": body})
+            self.send_response(200)
+            self.end_headers()
+
+        def log_message(self, *_args):
+            pass
+
+    server = HTTPServer(("127.0.0.1", 0), Collector)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    try:
+        config = OpenTelemetryV2Config(
+            exporter=exporter_kind,
+            endpoint=f"http://127.0.0.1:{server.server_port}",
+            headers="x-collector-token=secret",
+        )
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(providers.build_span_exporter(config)))
+        tracer = provider.get_tracer("test")
+        with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent:
+            with tracer.start_as_current_span("child") as child:
+                ids = (
+                    parent.get_span_context().trace_id,
+                    parent.get_span_context().span_id,
+                    child.get_span_context().span_id,
+                )
+        provider.shutdown()
+    finally:
+        server.shutdown()
+        server.server_close()
+    assert len(received) == 2
+    return received, ids
+
+
+def _only_span(request: dict) -> dict:
+    scope_spans = json.loads(request["body"])["resourceSpans"][0]["scopeSpans"][0]["spans"]
+    assert len(scope_spans) == 1
+    return scope_spans[0]
+
+
+def test_http_json_exporter_posts_otlp_json_to_traces_endpoint():
+    """``http/json`` must put the OTLP/JSON mapping on the wire (camelCase
+    fields, integer enums, hex ids) with a JSON content type, so collectors that
+    cannot decode protobuf can ingest the trace. Headers still travel."""
+    (child_request, parent_request), (trace_id, parent_id, child_id) = _export_one_trace_to_local_collector("http/json")
+
+    assert parent_request["path"] == "/v1/traces"
+    assert parent_request["headers"]["Content-Type"] == "application/json"
+    assert parent_request["headers"]["x-collector-token"] == "secret"
+    parent = _only_span(parent_request)
+    assert parent["name"] == "parent"
+    assert parent["kind"] == 2
+    assert parent["traceId"] == format(trace_id, "032x")
+    assert parent["spanId"] == format(parent_id, "016x")
+    assert "parentSpanId" not in parent
+    child = _only_span(child_request)
+    assert child["traceId"] == format(trace_id, "032x")
+    assert child["spanId"] == format(child_id, "016x")
+    assert child["parentSpanId"] == format(parent_id, "016x")
+
+
+def test_http_protobuf_exporter_still_posts_protobuf():
+    (_child_request, parent_request), (trace_id, _parent_id, _child_id) = _export_one_trace_to_local_collector(
+        "http/protobuf"
+    )
+
+    assert parent_request["path"] == "/v1/traces"
+    assert parent_request["headers"]["Content-Type"] == "application/x-protobuf"
+    assert format(trace_id, "032x").encode() not in parent_request["body"]
+    decoded = ExportTraceServiceRequest.FromString(parent_request["body"])
+    span = decoded.resource_spans[0].scope_spans[0].spans[0]
+    assert span.name == "parent"
+    assert span.trace_id == trace_id.to_bytes(16, "big")
+
+
 @pytest.fixture
 def otlp_collector() -> Iterator[tuple[str, list[str]]]:
     received_paths: list[str] = []
@@ -612,6 +699,21 @@ def test_traces_endpoint_per_exporter_coexists_with_default_normalization(otlp_c
     assert sorted(received_paths) == ["/services/collector/traces", "/v1/traces"]
 
 
+def test_http_json_exporter_honors_traces_endpoint(otlp_collector):
+    base_url, received_paths = otlp_collector
+    cfg = OpenTelemetryV2Config(
+        exporters=[
+            {
+                "kind": "http/json",
+                "endpoint": base_url,
+                "traces_endpoint": f"{base_url}/services/collector/traces",
+            }
+        ]
+    )
+    _export_one_span(cfg)
+    assert received_paths == ["/services/collector/traces"]
+
+
 def test_otlp_metric_exporter_uses_cumulative_histogram_temporality():
     """Histograms must export as cumulative, not delta.
 
diff --git a/ui/litellm-dashboard/src/components/callback_info_helpers.tsx b/ui/litellm-dashboard/src/components/callback_info_helpers.tsx
index 4b6f6233fe8..dfa35de1b34 100644
--- a/ui/litellm-dashboard/src/components/callback_info_helpers.tsx
+++ b/ui/litellm-dashboard/src/components/callback_info_helpers.tsx
@@ -158,6 +158,7 @@ export const CALLBACK_CONFIGS: CallbackConfig[] = [
     dynamic_params: {
       otel_endpoint: "text",
       otel_headers: "text",
+      otel_exporter_otlp_protocol: "select",
     },
     description: "OpenTelemetry Logging Integration",
   },
diff --git a/ui/litellm-dashboard/src/components/settings.test.tsx b/ui/litellm-dashboard/src/components/settings.test.tsx
index 762b23f413e..08cb9550646 100644
--- a/ui/litellm-dashboard/src/components/settings.test.tsx
+++ b/ui/litellm-dashboard/src/components/settings.test.tsx
@@ -219,6 +219,89 @@ describe("Settings", () => {
     expect(vi.mocked(setCallbacksCall)).not.toHaveBeenCalled();
   });
 
+  const mockOtelCallback = (variables: Record<string, string | null>) => {
+    mockGetCallbacksCall.mockResolvedValue({
+      callbacks: [{ name: "otel", variables }],
+      available_callbacks: {
+        otel: {
+          litellm_callback_name: "otel",
+          litellm_callback_params: ["OTEL_EXPORTER", "OTEL_EXPORTER_OTLP_PROTOCOL", "OTEL_ENDPOINT", "OTEL_HEADERS"],
+          ui_callback_name: "OpenTelemetry",
+        },
+      },
+      alerts: [],
+    });
+    mockGetCallbackConfigsCall.mockResolvedValue([
+      {
+        id: "otel",
+        displayName: "Open Telemetry",
+        dynamic_params: {
+          otel_endpoint: { type: "text", ui_name: "Endpoint URL", required: true },
+          otel_exporter_otlp_protocol: {
+            type: "select",
+            ui_name: "Export Protocol",
+            options: ["http/protobuf", "http/json"],
+            required: false,
+          },
+        },
+      },
+    ]);
+  };
+
+  const openOtelEditModal = async () => {
+    const user = userEvent.setup();
+    render(<Settings {...defaultProps} />);
+    await user.click(await screen.findByTestId("callback-actions-otel-success"));
+    await user.click(await screen.findByTestId("callback-action-edit"));
+    return user;
+  };
+
+  it("should post the chosen export protocol when a select dynamic param is saved", async () => {
+    mockOtelCallback({ OTEL_ENDPOINT: "http://collector:4318" });
+    const user = await openOtelEditModal();
+
+    expect(await screen.findByLabelText("Endpoint URL")).toHaveValue("http://collector:4318");
+    await user.click(screen.getByLabelText("Export Protocol"));
+    await user.click(await screen.findByRole("option", { name: "http/json" }));
+    expect(screen.getByLabelText("Export Protocol")).toHaveTextContent("http/json");
+
+    await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(vi.mocked(setCallbacksCall)).toHaveBeenCalledWith(
+        "token",
+        expect.objectContaining({
+          environment_variables: expect.objectContaining({
+            callback: "otel",
+            otel_endpoint: "http://collector:4318",
+            otel_exporter_otlp_protocol: "http/json",
+          }),
+        }),
+      );
+    });
+  });
+
+  it("should show the saved export protocol in the edit modal and keep it on an unchanged save", async () => {
+    mockOtelCallback({ OTEL_ENDPOINT: "http://collector:4318", OTEL_EXPORTER_OTLP_PROTOCOL: "http/json" });
+    const user = await openOtelEditModal();
+
+    expect(await screen.findByLabelText("Endpoint URL")).toHaveValue("http://collector:4318");
+    expect(screen.getByLabelText("Export Protocol")).toHaveTextContent("http/json");
+
+    await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(vi.mocked(setCallbacksCall)).toHaveBeenCalledWith("token", {
+        environment_variables: {
+          callback: "otel",
+          otel_endpoint: "http://collector:4318",
+          otel_exporter_otlp_protocol: "http/json",
+        },
+        litellm_settings: { success_callback: ["otel"] },
+      });
+    });
+  });
+
   it("should send the typed webhook url for an alert type when the alerting tab is saved", async () => {
     const user = userEvent.setup();
     render(<Settings {...defaultProps} />);
diff --git a/ui/litellm-dashboard/src/components/settings.tsx b/ui/litellm-dashboard/src/components/settings.tsx
index 9cb55b6ed5c..e549770af6e 100644
--- a/ui/litellm-dashboard/src/components/settings.tsx
+++ b/ui/litellm-dashboard/src/components/settings.tsx
@@ -14,6 +14,7 @@ import {
 } from "@/components/ui/combobox";
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { Switch } from "@/components/ui/switch";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
@@ -59,7 +60,7 @@ interface DynamicParamsFieldsProps {
 }
 
 const DynamicParamsFields: React.FC<DynamicParamsFieldsProps> = ({ params, callbackConfigs, selectedCallback }) => {
-  const { register, formState } = useFormContext<CallbackFormValues>();
+  const { register, control, formState } = useFormContext<CallbackFormValues>();
   const fieldIdPrefix = React.useId();
 
   if (!params || params.length === 0) {
@@ -74,37 +75,63 @@ const DynamicParamsFields: React.FC<DynamicParamsFieldsProps> = ({ params, callb
         const paramType = paramConfig.type || "text";
         const fieldLabel = paramConfig.ui_name || param.replace(/_/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
         const isRequired = paramConfig.required || false;
+        const selectOptions: string[] = Array.isArray(paramConfig.options) ? paramConfig.options : [];
+        const isSelect = paramType === "select" && selectOptions.length > 0;
         const fieldId = `${fieldIdPrefix}-${param}`;
-        const registration = register(
-          param,
-          isRequired ? { required: `Please enter the ${fieldLabel.toLowerCase()}` } : undefined,
-        );
+        const validationRules = isRequired ? { required: `Please enter the ${fieldLabel.toLowerCase()}` } : undefined;
+        const registration = isSelect ? undefined : register(param, validationRules);
 
         return (
           <Field key={param} className="mb-4">
             <FieldLabel htmlFor={fieldId}>
               <span className="text-sm font-medium text-foreground">{fieldLabel} </span>
             </FieldLabel>
-            {paramType === "password" ? (
-              <Input
-                id={fieldId}
-                type="password"
-                placeholder={`Enter your ${fieldLabel.toLowerCase()}`}
-                {...registration}
+            {isSelect && (
+              <Controller
+                control={control}
+                name={param}
+                rules={validationRules}
+                render={({ field }) => (
+                  <Select
+                    items={selectOptions.map((option) => ({ label: option, value: option }))}
+                    value={field.value || null}
+                    onValueChange={(selected: string | null) => field.onChange(selected ?? "")}
+                  >
+                    <SelectTrigger id={fieldId} className="w-full" onBlur={field.onBlur}>
+                      <SelectValue placeholder={`Select ${fieldLabel.toLowerCase()}`} />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {selectOptions.map((option) => (
+                        <SelectItem key={option} value={option}>
+                          {option}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                )}
               />
-            ) : paramType === "number" ? (
-              <Input
-                id={fieldId}
-                type="number"
-                placeholder={`Enter ${fieldLabel.toLowerCase()}`}
-                min={0}
-                max={1}
-                step={0.1}
-                {...registration}
-              />
-            ) : (
-              <Input id={fieldId} placeholder={`Enter your ${fieldLabel.toLowerCase()}`} {...registration} />
             )}
+            {!isSelect &&
+              (paramType === "password" ? (
+                <Input
+                  id={fieldId}
+                  type="password"
+                  placeholder={`Enter your ${fieldLabel.toLowerCase()}`}
+                  {...registration}
+                />
+              ) : paramType === "number" ? (
+                <Input
+                  id={fieldId}
+                  type="number"
+                  placeholder={`Enter ${fieldLabel.toLowerCase()}`}
+                  min={0}
+                  max={1}
+                  step={0.1}
+                  {...registration}
+                />
+              ) : (
+                <Input id={fieldId} placeholder={`Enter your ${fieldLabel.toLowerCase()}`} {...registration} />
+              ))}
             <FieldError errors={[formState.errors[param]]} />
           </Field>
         );
@@ -271,15 +298,22 @@ const Settings: React.FC<SettingsPageProps> = ({ accessToken, userRole, userID,
 
   useEffect(() => {
     if (showEditCallback && selectedEditCallback) {
+      const params = getDynamicParamsForCallback(
+        selectedEditCallback.name,
+        callbackConfigs,
+        selectedEditCallback.variables,
+      );
+      const fieldNameFor = (variable: string) =>
+        params.find((param) => param.toUpperCase() === variable.toUpperCase()) ?? variable;
       const normalized = Object.fromEntries(
-        Object.entries(selectedEditCallback.variables || {}).map(([k, v]) => [k, v ?? ""]),
+        Object.entries(selectedEditCallback.variables || {}).map(([k, v]) => [fieldNameFor(k), v ?? ""]),
       );
       editForm.reset({
         ...normalized,
         callback: selectedEditCallback.name,
       });
     }
-  }, [showEditCallback, selectedEditCallback, editForm]);
+  }, [showEditCallback, selectedEditCallback, editForm, callbackConfigs]);
 
   const handleSwitchChange = (alertName: string) => {
     if (activeAlerts.includes(alertName)) {

From 0f886d9006f6a29101cffd658c05e7f755a4923c Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 15:53:43 -0700
Subject: [PATCH 21/31] perf: move Anthropic, Vertex Anthropic, Ollama and HF
 template fetches off the event loop (#40311)

Direct Anthropic http image inlining, Vertex AI Anthropic forced base64 conversion, Ollama completion image download and the watsonx GPT-OSS Hugging Face chat template lookup all ran synchronous HTTP inside the async request path. Each provider config now transforms through async_inline_remote_media on the async path, the Anthropic handler awaits the config's async_transform_request before dispatch and in the Rust fallback, and watsonx text exposes async_transform_request and always awaits ahf_chat_template

Resolves LIT-7028

Co-authored-by: yassin <yassin@berri.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../prompt_templates/image_handling.py        |  13 +-
 litellm/llms/anthropic/chat/handler.py        | 200 ++++++++----------
 litellm/llms/anthropic/chat/transformation.py |  24 +++
 .../llms/ollama/completion/transformation.py  |  24 +++
 .../anthropic/transformation.py               |   4 +
 litellm/llms/watsonx/chat/transformation.py   |   8 +-
 .../llms/watsonx/completion/transformation.py |  12 +-
 .../chat/test_anthropic_chat_handler.py       |  51 ++++-
 .../test_ollama_completion_transformation.py  |  44 +++-
 ..._vertex_ai_anthropic_image_url_handling.py |  62 +++++-
 .../test_litellm/llms/watsonx/test_watsonx.py |  68 ++++++
 11 files changed, 380 insertions(+), 130 deletions(-)

diff --git a/litellm/litellm_core_utils/prompt_templates/image_handling.py b/litellm/litellm_core_utils/prompt_templates/image_handling.py
index 24f3b8bca7f..c9933422cc3 100644
--- a/litellm/litellm_core_utils/prompt_templates/image_handling.py
+++ b/litellm/litellm_core_utils/prompt_templates/image_handling.py
@@ -183,6 +183,7 @@ class _RemoteSource:
 class RemoteMedia:
     url: str
     fields: Mapping[str, object]
+    part_type: str
 
 
 _NO_FIELDS: Final[Mapping[str, object]] = MappingProxyType({})
@@ -192,6 +193,10 @@ def inline_every_remote_url(_media: RemoteMedia) -> bool:
     return True
 
 
+def inline_remote_image_urls(media: RemoteMedia) -> bool:
+    return media.part_type == "image_url"
+
+
 def _parse_remote_image(fields: Mapping[str, object]) -> _RemoteImage | None:
     if fields.get("type") != "image_url":
         return None
@@ -223,11 +228,11 @@ def _parse_remote_part(part: object) -> _RemoteImage | _RemoteFile | _RemoteSour
 def _remote_media(remote: _RemoteImage | _RemoteFile | _RemoteSource) -> RemoteMedia:
     match remote:
         case _RemoteImage(_, image_url, url):
-            return RemoteMedia(url, image_url if image_url is not None else _NO_FIELDS)
+            return RemoteMedia(url, image_url if image_url is not None else _NO_FIELDS, "image_url")
         case _RemoteFile(_, file, url):
-            return RemoteMedia(url, file)
-        case _RemoteSource(_, source, url):
-            return RemoteMedia(url, source)
+            return RemoteMedia(url, file, "file")
+        case _RemoteSource(part, source, url):
+            return RemoteMedia(url, source, str(part.get("type")))
 
 
 _PDF_FORMAT: Final = MappingProxyType({"format": "application/pdf"})
diff --git a/litellm/llms/anthropic/chat/handler.py b/litellm/llms/anthropic/chat/handler.py
index c82be07a5c5..d1fe4cadf40 100644
--- a/litellm/llms/anthropic/chat/handler.py
+++ b/litellm/llms/anthropic/chat/handler.py
@@ -368,27 +368,92 @@ class AnthropicChatCompletion(BaseLLM):
         if config is None:
             raise ValueError(f"Provider config not found for model: {model} and provider: {custom_llm_provider}")
 
-        def build_request() -> tuple[dict, dict]:  # mutable-ok: rewritten in place downstream
-            """Translate the request the Python way, returning `(headers, data)`.
+        transform_params: Final = {**optional_params, "is_vertex_request": is_vertex_request}
+
+        def finish_request(request_data: dict) -> tuple[dict, dict]:  # mutable-ok: rewritten in place downstream
+            """Filter beta headers and emit pre_call, returning `(headers, data)`.
 
             The pair stays mutable because the streaming path rewrites it in
-            place (`data["stream"] = True`) before sending.
-
-            Shared by the normal path and by the Rust path's fallback, which
-            builds it only when the Rust call did not serve the request.
+            place (`data["stream"] = True`) before sending. A Rust attempt that
+            declined already emitted pre_call for this request, so skip it there.
             """
-            request_data: Final = config.transform_request(
-                model=model,
-                messages=messages,
-                optional_params={**optional_params, "is_vertex_request": is_vertex_request},
-                litellm_params=litellm_params,
-                headers=headers,
-            )
-            return update_request_with_filtered_beta(
+            request_headers, data = update_request_with_filtered_beta(
                 headers=headers,
                 request_data=request_data,
                 provider=custom_llm_provider,
             )
+            if not serves_via_rust:
+                logging_obj.pre_call(
+                    input=messages,
+                    api_key=api_key,
+                    additional_args={
+                        "complete_input_dict": data,
+                        "api_base": api_base,
+                        "headers": request_headers,
+                    },
+                )
+            print_verbose(f"_is_function_call: {_is_function_call}")
+            return request_headers, data
+
+        async def acompletion_dispatch() -> "ModelResponse | CustomStreamWrapper":
+            """Translate then send, so the provider config can inline remote media off the event loop."""
+            request_headers, data = finish_request(
+                await config.async_transform_request(
+                    model=model,
+                    messages=messages,
+                    optional_params=transform_params,
+                    litellm_params=litellm_params,
+                    headers=headers,
+                )
+            )
+            if (
+                stream is True
+            ):  # if function call - fake the streaming (need complete blocks for output parsing in openai format)
+                print_verbose("makes async anthropic streaming POST request")
+                data["stream"] = stream
+                return await self.acompletion_stream_function(
+                    model=model,
+                    messages=messages,
+                    data=data,
+                    api_base=api_base,
+                    custom_prompt_dict=custom_prompt_dict,
+                    model_response=model_response,
+                    print_verbose=print_verbose,
+                    encoding=encoding,
+                    api_key=api_key,
+                    logging_obj=logging_obj,
+                    optional_params=optional_params,
+                    stream=stream,
+                    _is_function_call=_is_function_call,
+                    json_mode=json_mode,
+                    litellm_params=litellm_params,
+                    logger_fn=logger_fn,
+                    headers=request_headers,
+                    timeout=timeout,
+                    client=(client if client is not None and isinstance(client, AsyncHTTPHandler) else None),
+                )
+            return await self.acompletion_function(
+                model=model,
+                messages=messages,
+                data=data,
+                api_base=api_base,
+                custom_prompt_dict=custom_prompt_dict,
+                model_response=model_response,
+                print_verbose=print_verbose,
+                encoding=encoding,
+                api_key=api_key,
+                provider_config=config,
+                logging_obj=logging_obj,
+                optional_params=optional_params,
+                stream=stream,
+                _is_function_call=_is_function_call,
+                litellm_params=litellm_params,
+                logger_fn=logger_fn,
+                headers=request_headers,
+                client=client,
+                json_mode=json_mode,
+                timeout=timeout,
+            )
 
         # The Rust core owns the whole call for the subset it accepts, so ask
         # before transforming: whichever path runs emits pre_call exactly once.
@@ -424,35 +489,6 @@ class AnthropicChatCompletion(BaseLLM):
                 additional_args=rust_logging_args,
             )
             if acompletion is True:
-
-                async def python_fallback() -> "ModelResponse | CustomStreamWrapper":
-                    # pre_call already fired for this request above. The Rust
-                    # path only declines before the provider is called, so this
-                    # is the same attempt continuing, not a second one.
-                    fallback_headers, fallback_data = build_request()
-                    return await self.acompletion_function(
-                        model=model,
-                        messages=messages,
-                        data=fallback_data,
-                        api_base=api_base,
-                        custom_prompt_dict=custom_prompt_dict,
-                        model_response=model_response,
-                        print_verbose=print_verbose,
-                        encoding=encoding,
-                        api_key=api_key,
-                        provider_config=config,
-                        logging_obj=logging_obj,
-                        optional_params=optional_params,
-                        stream=stream,
-                        _is_function_call=_is_function_call,
-                        litellm_params=litellm_params,
-                        logger_fn=logger_fn,
-                        headers=fallback_headers,
-                        client=client,
-                        json_mode=json_mode,
-                        timeout=timeout,
-                    )
-
                 return rust_chat_completions_bridge.achat_completions_or_fallback(
                     model=model,
                     messages=messages,
@@ -464,7 +500,7 @@ class AnthropicChatCompletion(BaseLLM):
                     extra_headers=headers,
                     timeout=timeout,
                     on_response=log_rust_post_call,
-                    python_fallback=python_fallback,
+                    python_fallback=acompletion_dispatch,
                 )
             rust_response: Final = rust_chat_completions_bridge.chat_completions(
                 model=model,
@@ -481,74 +517,18 @@ class AnthropicChatCompletion(BaseLLM):
             if rust_response is not None:
                 return rust_response
 
-        headers, data = build_request()
-
-        ## LOGGING
-        # Reaching here with `serves_via_rust` set means the Rust attempt
-        # declined at call time, before the provider was called, and already
-        # logged this request. That is the same attempt continuing.
-        if not serves_via_rust:
-            logging_obj.pre_call(
-                input=messages,
-                api_key=api_key,
-                additional_args={
-                    "complete_input_dict": data,
-                    "api_base": api_base,
-                    "headers": headers,
-                },
-            )
-        print_verbose(f"_is_function_call: {_is_function_call}")
         if acompletion is True:
-            if (
-                stream is True
-            ):  # if function call - fake the streaming (need complete blocks for output parsing in openai format)
-                print_verbose("makes async anthropic streaming POST request")
-                data["stream"] = stream
-                return self.acompletion_stream_function(
-                    model=model,
-                    messages=messages,
-                    data=data,
-                    api_base=api_base,
-                    custom_prompt_dict=custom_prompt_dict,
-                    model_response=model_response,
-                    print_verbose=print_verbose,
-                    encoding=encoding,
-                    api_key=api_key,
-                    logging_obj=logging_obj,
-                    optional_params=optional_params,
-                    stream=stream,
-                    _is_function_call=_is_function_call,
-                    json_mode=json_mode,
-                    litellm_params=litellm_params,
-                    logger_fn=logger_fn,
-                    headers=headers,
-                    timeout=timeout,
-                    client=(client if client is not None and isinstance(client, AsyncHTTPHandler) else None),
-                )
-            else:
-                return self.acompletion_function(
-                    model=model,
-                    messages=messages,
-                    data=data,
-                    api_base=api_base,
-                    custom_prompt_dict=custom_prompt_dict,
-                    model_response=model_response,
-                    print_verbose=print_verbose,
-                    encoding=encoding,
-                    api_key=api_key,
-                    provider_config=config,
-                    logging_obj=logging_obj,
-                    optional_params=optional_params,
-                    stream=stream,
-                    _is_function_call=_is_function_call,
-                    litellm_params=litellm_params,
-                    logger_fn=logger_fn,
-                    headers=headers,
-                    client=client,
-                    json_mode=json_mode,
-                    timeout=timeout,
-                )
+            return acompletion_dispatch()
         else:
+            headers, data = finish_request(
+                config.transform_request(
+                    model=model,
+                    messages=messages,
+                    optional_params=transform_params,
+                    litellm_params=litellm_params,
+                    headers=headers,
+                )
+            )
             ## COMPLETION CALL
             if (
                 stream is True
diff --git a/litellm/llms/anthropic/chat/transformation.py b/litellm/llms/anthropic/chat/transformation.py
index 5f7ac73c919..5463f1862ad 100644
--- a/litellm/llms/anthropic/chat/transformation.py
+++ b/litellm/llms/anthropic/chat/transformation.py
@@ -26,6 +26,11 @@ from litellm.litellm_core_utils.core_helpers import map_finish_reason
 from litellm.litellm_core_utils.prompt_templates.common_utils import (
     sanitize_input_schema_for_anthropic,
 )
+from litellm.litellm_core_utils.prompt_templates.image_handling import (
+    RemoteMedia,
+    async_inline_remote_media,
+    inline_remote_image_urls,
+)
 from litellm.llms.base_llm.base_utils import type_to_response_format_param
 from litellm.llms.base_llm.chat.transformation import BaseConfig, BaseLLMException
 from litellm.types.llms.anthropic import (
@@ -1840,6 +1845,25 @@ class AnthropicConfig(AnthropicModelInfo, BaseConfig):
                 break
         return headers
 
+    def inlines_remote_media(self, media: RemoteMedia) -> bool:
+        return inline_remote_image_urls(media) and media.url.startswith("http://")
+
+    async def async_transform_request(
+        self,
+        model: str,
+        messages: list[AllMessageValues],  # mutable-ok: BaseConfig signature
+        optional_params: dict[str, object],  # mutable-ok: BaseConfig signature
+        litellm_params: dict[str, object],  # mutable-ok: BaseConfig signature
+        headers: dict[str, object],  # mutable-ok: BaseConfig signature
+    ) -> dict[str, object]:  # mutable-ok: BaseConfig signature
+        return self.transform_request(
+            model=model,
+            messages=await async_inline_remote_media(messages, should_inline=self.inlines_remote_media),
+            optional_params=optional_params,
+            litellm_params=litellm_params,
+            headers=headers,
+        )
+
     def transform_request(
         self,
         model: str,
diff --git a/litellm/llms/ollama/completion/transformation.py b/litellm/llms/ollama/completion/transformation.py
index dccc83efed4..a1340ba1952 100644
--- a/litellm/llms/ollama/completion/transformation.py
+++ b/litellm/llms/ollama/completion/transformation.py
@@ -16,6 +16,10 @@ from litellm.litellm_core_utils.prompt_templates.factory import (
     custom_prompt,
     ollama_pt,
 )
+from litellm.litellm_core_utils.prompt_templates.image_handling import (
+    async_inline_remote_media,
+    inline_remote_image_urls,
+)
 from litellm.llms.base_llm.base_model_iterator import BaseModelResponseIterator
 from litellm.llms.base_llm.chat.transformation import BaseConfig, BaseLLMException
 from litellm.types.llms.openai import AllMessageValues, ChatCompletionUsageBlock
@@ -344,6 +348,26 @@ class OllamaConfig(BaseConfig):
         )
         return model_response
 
+    @property
+    def uses_async_transform_request(self) -> bool:
+        return True
+
+    async def async_transform_request(
+        self,
+        model: str,
+        messages: list[AllMessageValues],  # mutable-ok: BaseConfig signature
+        optional_params: dict[str, object],  # mutable-ok: BaseConfig signature
+        litellm_params: dict[str, object],  # mutable-ok: BaseConfig signature
+        headers: dict[str, object],  # mutable-ok: BaseConfig signature
+    ) -> dict[str, object]:  # mutable-ok: BaseConfig signature
+        return self.transform_request(
+            model=model,
+            messages=await async_inline_remote_media(messages, should_inline=inline_remote_image_urls),
+            optional_params=optional_params,
+            litellm_params=litellm_params,
+            headers=headers,
+        )
+
     def transform_request(
         self,
         model: str,
diff --git a/litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/transformation.py b/litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/transformation.py
index 7579bc8c02e..508f68b3eca 100644
--- a/litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/transformation.py
+++ b/litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/transformation.py
@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Final
 import httpx
 
 import litellm
+from litellm.litellm_core_utils.prompt_templates.image_handling import RemoteMedia, inline_remote_image_urls
 from litellm.llms.base_llm.chat.transformation import LiteLLMLoggingObj
 from litellm.types.llms.openai import AllMessageValues
 from litellm.types.utils import ModelResponse
@@ -51,6 +52,9 @@ class VertexAIAnthropicConfig(AnthropicConfig):
     def custom_llm_provider(self) -> str | None:
         return "vertex_ai"
 
+    def inlines_remote_media(self, media: RemoteMedia) -> bool:
+        return inline_remote_image_urls(media)
+
     def should_strip_billing_metadata(self) -> bool:
         return True
 
diff --git a/litellm/llms/watsonx/chat/transformation.py b/litellm/llms/watsonx/chat/transformation.py
index f9e71f9116e..cc616ab5f9f 100644
--- a/litellm/llms/watsonx/chat/transformation.py
+++ b/litellm/llms/watsonx/chat/transformation.py
@@ -157,11 +157,9 @@ class IBMWatsonXChatConfig(IBMWatsonXMixin, OpenAIGPTConfig):
     @staticmethod
     async def aapply_prompt_template(model: str, messages: list[dict[str, str]]) -> str | None:
         """Apply prompt template (async version)"""
-        import litellm
         from litellm.litellm_core_utils.prompt_templates.factory import (
             ahf_chat_template,
             custom_prompt,
-            hf_chat_template,
             ibm_granite_pt,
             mistral_instruct_pt,
         )
@@ -179,11 +177,7 @@ class IBMWatsonXChatConfig(IBMWatsonXMixin, OpenAIGPTConfig):
             else:
                 hf_model = model
             try:
-                # Use sync if cached, async if not
-                if hf_model in litellm.known_tokenizer_config:
-                    result = hf_chat_template(model=hf_model, messages=messages)
-                else:
-                    result = await ahf_chat_template(model=hf_model, messages=messages)
+                result = await ahf_chat_template(model=hf_model, messages=messages)
                 # Return result if it's truthy (not None and not empty string)
                 # The caller (_aconvert_watsonx_messages_core) will handle None/empty by falling back to default
                 if result:
diff --git a/litellm/llms/watsonx/completion/transformation.py b/litellm/llms/watsonx/completion/transformation.py
index 0b4c9ae917a..2be007336b4 100644
--- a/litellm/llms/watsonx/completion/transformation.py
+++ b/litellm/llms/watsonx/completion/transformation.py
@@ -16,6 +16,7 @@ from ..common_utils import (
     IBMWatsonXMixin,
     WatsonXAIError,
     _get_api_params,
+    aconvert_watsonx_messages_to_prompt,
     convert_watsonx_messages_to_prompt,
 )
 
@@ -236,7 +237,11 @@ class IBMWatsonXAIConfig(IBMWatsonXMixin, BaseConfig):
             **watsonx_auth_payload,
         }
 
-    async def atransform_request(
+    @property
+    def uses_async_transform_request(self) -> bool:
+        return True
+
+    async def async_transform_request(
         self,
         model: str,
         messages: list[AllMessageValues],
@@ -244,11 +249,6 @@ class IBMWatsonXAIConfig(IBMWatsonXMixin, BaseConfig):
         litellm_params: dict,
         headers: dict,
     ) -> dict:
-        """Async version of transform_request"""
-        from litellm.llms.watsonx.common_utils import (
-            aconvert_watsonx_messages_to_prompt,
-        )
-
         provider: Final = model.split("/")[0]
         prompt: Final = await aconvert_watsonx_messages_to_prompt(
             model=model, messages=messages, provider=provider, custom_prompt_dict={}
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 b4b173b20c3..18309595414 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
@@ -9,7 +9,8 @@ import pytest
 import litellm
 from litellm.constants import RESPONSE_FORMAT_TOOL_NAME
 from litellm.llms.anthropic.chat.handler import ModelResponseIterator, make_call
-from litellm.llms.custom_httpx.http_handler import HTTPHandler
+from litellm._uuid import uuid
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler, HTTPHandler
 from litellm.types.llms.openai import (
     ChatCompletionToolCallChunk,
     ChatCompletionToolCallFunctionChunk,
@@ -85,6 +86,54 @@ def test_anthropic_completion_does_not_send_deployment_default_limits():
     assert "default_api_key_tpm_limit" not in request_body
 
 
+async def test_anthropic_async_completion_inlines_http_images_off_the_event_loop(async_only_image_fetch):
+    http_image_url = f"http://img.example/{uuid.uuid4()}.png"
+    https_image_url = f"https://img.example/{uuid.uuid4()}.png"
+    captured = {}
+
+    def handle(request):
+        captured["body"] = json.loads(request.content)
+        return httpx.Response(
+            200,
+            json={
+                "id": "msg_1",
+                "type": "message",
+                "role": "assistant",
+                "model": "claude-sonnet-4-6",
+                "content": [{"type": "text", "text": "Green"}],
+                "stop_reason": "end_turn",
+                "usage": {"input_tokens": 1, "output_tokens": 1},
+            },
+        )
+
+    client = AsyncHTTPHandler()
+    client.client = httpx.AsyncClient(transport=httpx.MockTransport(handle))
+
+    response = await litellm.acompletion(
+        model="anthropic/claude-sonnet-4-6",
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "What colour is this?"},
+                    {"type": "image_url", "image_url": {"url": http_image_url}},
+                    {"type": "image_url", "image_url": {"url": https_image_url}},
+                ],
+            }
+        ],
+        api_key="test-key",
+        client=client,
+    )
+
+    assert response.choices[0].message.content == "Green"
+    assert async_only_image_fetch.fetched == [http_image_url]
+    sources = [part["source"] for part in captured["body"]["messages"][0]["content"] if part["type"] == "image"]
+    assert sources == [
+        {"type": "base64", "media_type": "image/png", "data": async_only_image_fetch.base64_png},
+        {"type": "url", "url": https_image_url},
+    ]
+
+
 def test_redacted_thinking_content_block_delta():
     chunk = {
         "type": "content_block_start",
diff --git a/tests/test_litellm/llms/ollama/test_ollama_completion_transformation.py b/tests/test_litellm/llms/ollama/test_ollama_completion_transformation.py
index eadc2bc9541..b2071155f3f 100644
--- a/tests/test_litellm/llms/ollama/test_ollama_completion_transformation.py
+++ b/tests/test_litellm/llms/ollama/test_ollama_completion_transformation.py
@@ -2,9 +2,11 @@ import json
 from litellm._uuid import uuid
 from unittest.mock import MagicMock, patch
 
+import httpx
 import pytest
 
-
+import litellm
+from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
 from litellm.llms.ollama.completion.transformation import (
     OllamaConfig,
     OllamaTextCompletionResponseIterator,
@@ -502,3 +504,43 @@ class TestOllamaTextCompletionResponseIterator:
         assert result["usage"]["prompt_tokens"] == 10
         assert result["usage"]["completion_tokens"] == 5
         assert result["usage"]["total_tokens"] == 15
+
+
+async def test_ollama_async_completion_inlines_remote_images_off_the_event_loop(async_only_image_fetch):
+    image_url = f"https://img.example/{uuid.uuid4()}.png"
+    captured = {}
+
+    def handle(request):
+        captured["body"] = json.loads(request.content)
+        return httpx.Response(
+            200,
+            json={
+                "model": "llava",
+                "response": "Green",
+                "done": True,
+                "prompt_eval_count": 1,
+                "eval_count": 1,
+            },
+        )
+
+    client = AsyncHTTPHandler()
+    client.client = httpx.AsyncClient(transport=httpx.MockTransport(handle))
+
+    response = await litellm.acompletion(
+        model="ollama/llava",
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "What colour is this?"},
+                    {"type": "image_url", "image_url": {"url": image_url}},
+                ],
+            }
+        ],
+        api_base="http://ollama.example:11434",
+        client=client,
+    )
+
+    assert response.choices[0].message.content == "Green"
+    assert async_only_image_fetch.fetched == [image_url]
+    assert captured["body"]["images"] == [async_only_image_fetch.base64_png]
diff --git a/tests/test_litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/test_vertex_ai_anthropic_image_url_handling.py b/tests/test_litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/test_vertex_ai_anthropic_image_url_handling.py
index fa286f6f609..98071594ebf 100644
--- a/tests/test_litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/test_vertex_ai_anthropic_image_url_handling.py
+++ b/tests/test_litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/test_vertex_ai_anthropic_image_url_handling.py
@@ -6,11 +6,15 @@ Vertex AI Anthropic models don't support URL sources for images.
 LiteLLM should convert image URLs to base64 when using Vertex AI Anthropic.
 """
 
+import json
+import sys
 from unittest.mock import patch, MagicMock
 
+import httpx
 import pytest
 
-
+import litellm
+from litellm._uuid import uuid
 from litellm.litellm_core_utils.prompt_templates.factory import (
     anthropic_messages_pt,
     convert_to_anthropic_tool_result,
@@ -371,3 +375,59 @@ class TestToolMessageImageURLHandling:
                                 assert item["source"]["type"] == "url"
                                 return
         pytest.fail("Could not find image in tool result")
+
+
+async def test_vertex_ai_anthropic_async_completion_inlines_https_images_off_the_event_loop(async_only_image_fetch):
+    from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
+
+    image_url = f"https://img.example/{uuid.uuid4()}.png"
+    captured = {}
+
+    def handle(request):
+        captured["body"] = json.loads(request.content)
+        return httpx.Response(
+            200,
+            json={
+                "id": "msg_1",
+                "type": "message",
+                "role": "assistant",
+                "model": "claude-sonnet-4-6",
+                "content": [{"type": "text", "text": "Green"}],
+                "stop_reason": "end_turn",
+                "usage": {"input_tokens": 1, "output_tokens": 1},
+            },
+        )
+
+    client = AsyncHTTPHandler()
+    client.client = httpx.AsyncClient(transport=httpx.MockTransport(handle))
+    vertexai = MagicMock()
+    vertexai.preview.language_models = MagicMock()
+
+    with (
+        patch.dict(sys.modules, {"vertexai": vertexai}),
+        patch.object(  # test-quality-ok: litellm.acompletion has no seam for Vertex token minting
+            litellm.main.vertex_partner_models_chat_completion,
+            "_ensure_access_token",
+            return_value=("token", "test-project"),
+        ),
+    ):
+        response = await litellm.acompletion(
+            model="vertex_ai/claude-sonnet-4-6",
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "What colour is this?"},
+                        {"type": "image_url", "image_url": {"url": image_url}},
+                    ],
+                }
+            ],
+            vertex_project="test-project",
+            vertex_location="us-east5",
+            client=client,
+        )
+
+    assert response.choices[0].message.content == "Green"
+    assert async_only_image_fetch.fetched == [image_url]
+    sources = [part["source"] for part in captured["body"]["messages"][0]["content"] if part["type"] == "image"]
+    assert sources == [{"type": "base64", "media_type": "image/png", "data": async_only_image_fetch.base64_png}]
diff --git a/tests/test_litellm/llms/watsonx/test_watsonx.py b/tests/test_litellm/llms/watsonx/test_watsonx.py
index 8ac4472b22d..285afffefc0 100644
--- a/tests/test_litellm/llms/watsonx/test_watsonx.py
+++ b/tests/test_litellm/llms/watsonx/test_watsonx.py
@@ -356,6 +356,74 @@ async def test_watsonx_gpt_oss_uses_async_http_handler():
         assert result["status"] == "success", "Should return success status"
 
 
+@pytest.mark.parametrize("tokenizer_config_cached", [False, True], ids=["tokenizer_config", "cached_config_jinja"])
+async def test_watsonx_text_gpt_oss_async_completion_fetches_hf_template_off_the_event_loop(
+    monkeypatch, tokenizer_config_cached
+):
+    import httpx
+
+    from litellm._uuid import uuid
+    from litellm.litellm_core_utils.prompt_templates import huggingface_template_handler
+    from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
+
+    hf_model = f"openai/gpt-oss-{uuid.uuid4()}"
+    chat_template = "{% for m in messages %}<|{{ m['role'] }}|>{{ m['content'] }}{% endfor %}"
+    if tokenizer_config_cached:
+        cached_config = {"status": "success", "tokenizer": {"bos_token": None, "eos_token": None}}
+        monkeypatch.setattr(litellm, "known_tokenizer_config", {hf_model: cached_config})
+        expected_fetch = f"https://huggingface.co/{hf_model}/raw/main/chat_template.jinja"
+    else:
+        monkeypatch.setattr(litellm, "known_tokenizer_config", {})
+        expected_fetch = f"https://huggingface.co/{hf_model}/raw/main/tokenizer_config.json"
+    hf_fetched = []
+    captured = {}
+
+    def forbid_sync_client():
+        raise AssertionError("sync HuggingFace fetch ran on the request path")
+
+    async def serve_hf_file(url, **kwargs):
+        hf_fetched.append(url)
+        if url.endswith(".jinja"):
+            return httpx.Response(200, content=chat_template.encode())
+        return httpx.Response(200, json={"chat_template": chat_template, "bos_token": None, "eos_token": None})
+
+    monkeypatch.setattr(huggingface_template_handler, "_get_httpx_client", forbid_sync_client)
+    monkeypatch.setattr(huggingface_template_handler, "get_async_httpx_client", lambda **kwargs: Mock(get=serve_hf_file))
+
+    def handle(request):
+        captured["body"] = json.loads(request.content)
+        return httpx.Response(
+            200,
+            json={
+                "model_id": hf_model,
+                "results": [
+                    {
+                        "generated_text": "Hi",
+                        "generated_token_count": 1,
+                        "input_token_count": 1,
+                        "stop_reason": "eos_token",
+                    }
+                ],
+            },
+        )
+
+    client = AsyncHTTPHandler()
+    client.client = httpx.AsyncClient(transport=httpx.MockTransport(handle))
+
+    response = await litellm.acompletion(
+        model=f"watsonx_text/{hf_model}",
+        messages=[{"role": "user", "content": "Hi there"}],
+        api_base="https://test-api.watsonx.ai",
+        project_id="test-project-id",
+        token="test-token",
+        client=client,
+    )
+
+    assert response.choices[0].message.content == "Hi"
+    assert hf_fetched == [expected_fetch]
+    assert captured["body"]["input"] == "<|user|>Hi there"
+
+
 def test_watsonx_chat_completion_with_reasoning_effort(monkeypatch):
     """
     Test that 'reasoning_effort' is correctly passed through to the WatsonX API payload.

From 8ce4c050198b957d742fcac3b7a9ee3a407e5738 Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 15:54:11 -0700
Subject: [PATCH 22/31] fix(router): move retry-policy retries off the refusing
 deployment on every router entrypoint (#40306)

Co-authored-by: yassin <yassin@berri.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/router.py                 |  24 +++-
 tests/test_litellm/test_router.py | 227 ++++++++++++++++++++++++++++++
 2 files changed, 250 insertions(+), 1 deletion(-)

diff --git a/litellm/router.py b/litellm/router.py
index e1095fe26f3..934a4ac86a9 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -3656,6 +3656,13 @@ class Router:
         effective_model_info: Final = kwargs.get("model_info") or deployment.get("model_info") or MappingProxyType({})
         self._set_failed_deployment_id_on_exception(exception, MappingProxyType({"model_info": effective_model_info}))
 
+    @staticmethod
+    def _stamp_retry_skip_deployment_id(exception: Exception, kwargs: Mapping[str, object]) -> None:
+        effective_model_info: Final = kwargs.get("model_info")
+        deployment_id: Final = effective_model_info.get("id") if isinstance(effective_model_info, Mapping) else None
+        if isinstance(deployment_id, str) and deployment_id:
+            exception.retry_skip_deployment_id = deployment_id  # pyright: ignore[reportAttributeAccessIssue]  # dynamic stamp, read by _deployment_ids_to_skip_on_retry
+
     def _update_kwargs_with_default_litellm_params(
         self, kwargs: dict, metadata_variable_name: str | None = "metadata"
     ) -> None:
@@ -4358,6 +4365,7 @@ class Router:
                 model=model,
                 messages=[{"role": "user", "content": "prompt"}],
                 specific_deployment=kwargs.pop("specific_deployment", None),
+                request_kwargs=kwargs,
             )
             self._update_kwargs_with_deployment(deployment=deployment, kwargs=kwargs)
             data: Final = deployment["litellm_params"].copy()
@@ -4388,6 +4396,7 @@ class Router:
             verbose_router_logger.info("litellm.image_generation(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def aimage_generation(self, prompt: str, model: str, **kwargs):
@@ -4472,6 +4481,7 @@ class Router:
             verbose_router_logger.info("litellm.aimage_generation(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def atranscription(self, file: FileTypes, model: str, **kwargs):
@@ -4576,6 +4586,7 @@ class Router:
             verbose_router_logger.info("litellm.atranscription(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def aspeech(self, model: str, input: str, voice: str | None = None, **kwargs):
@@ -4690,6 +4701,7 @@ class Router:
             verbose_router_logger.info("litellm.aspeech(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def arerank(self, model: str, **kwargs):
@@ -4748,6 +4760,7 @@ class Router:
             verbose_router_logger.info("litellm.arerank(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     def text_completion(
@@ -4882,6 +4895,7 @@ class Router:
             verbose_router_logger.info("litellm.atext_completion(model=%s)\x1b[31m Exception %s\x1b[0m", model, e)
             if model is not None:
                 self.fail_calls[model] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def aadapter_completion(
@@ -4972,6 +4986,7 @@ class Router:
             verbose_router_logger.info("litellm.aadapter_completion(model=%s)\x1b[31m Exception %s\x1b[0m", model, e)
             if model is not None:
                 self.fail_calls[model] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def _asearch_with_fallbacks(self, original_function: Callable, **kwargs):
@@ -5754,6 +5769,7 @@ class Router:
                 model=model,
                 input=input,
                 specific_deployment=kwargs.pop("specific_deployment", None),
+                request_kwargs=kwargs,
             )
             self._update_kwargs_with_deployment(deployment=deployment, kwargs=kwargs)
             data: Final = deployment["litellm_params"].copy()
@@ -5792,6 +5808,7 @@ class Router:
             verbose_router_logger.info("litellm.embedding(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def aembedding(
@@ -5879,6 +5896,7 @@ class Router:
             verbose_router_logger.info("litellm.aembedding(model=%s)\x1b[31m Exception %s\x1b[0m", model_name, e)
             if model_name is not None:
                 self.fail_calls[model_name] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     #### FILES API ####
@@ -6252,6 +6270,7 @@ class Router:
             )
             if model is not None:
                 self.fail_calls[model] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def aretrieve_batch(
@@ -6472,6 +6491,7 @@ class Router:
             )
             if model is not None:
                 self.fail_calls[model] += 1
+            self._stamp_retry_skip_deployment_id(e, kwargs)
             raise e
 
     async def alist_batches(
@@ -7589,7 +7609,9 @@ class Router:
 
     @staticmethod
     def _deployment_ids_to_skip_on_retry(exception: Exception, already_skipped: object) -> tuple[str, ...]:
-        failed_deployment_id: Final[str | None] = getattr(exception, "failed_deployment_id", None)
+        failed_deployment_id: Final[str | None] = getattr(exception, "retry_skip_deployment_id", None) or getattr(
+            exception, "failed_deployment_id", None
+        )
         status_code: Final = getattr(exception, "status_code", None)
         if not failed_deployment_id or not isinstance(status_code, int):
             return ()
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index 7bfde0def09..bc79c5f6589 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -6,6 +6,7 @@ import logging
 import os
 import threading
 from datetime import datetime
+from collections.abc import Awaitable, Callable, Mapping
 from types import SimpleNamespace
 from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
@@ -27,6 +28,7 @@ from litellm.llms.bedrock.common_utils import BedrockError
 from litellm.llms.anthropic.experimental_pass_through.messages.agentic_streaming_iterator import (
     SERVER_FULFILLED_TOOL_LEAK_ERROR_SSE_BYTES,
 )
+from litellm.types.llms.openai import ChatCompletionRequest
 from litellm.router import (
     MAX_BUFFERED_PRE_CONTENT_ANTHROPIC_CHUNKS,
     FallbackAwareAnthropicMessagesStream,
@@ -13972,6 +13974,31 @@ def test_router_deployment_ids_to_skip_on_retry(status_code, failed_deployment_i
     assert litellm.Router._deployment_ids_to_skip_on_retry(exception, already_skipped) == expected
 
 
+@pytest.mark.parametrize(
+    "kwargs,failed_deployment_id,expected",
+    [
+        ({"model_info": {"id": "rejecting"}}, None, ("rejecting",)),
+        ({"model_info": {"id": "rejecting"}}, "cooldown-target", ("rejecting",)),
+        ({"model_info": {"id": ""}}, None, ()),
+        ({"model_info": {"id": 7}}, None, ()),
+        ({"model_info": "rejecting"}, None, ()),
+        ({}, None, ()),
+        ({}, "cooldown-target", ("cooldown-target",)),
+    ],
+)
+def test_router_retry_skip_stamp_feeds_deployment_ids_to_skip_on_retry(
+    kwargs: Mapping[str, object], failed_deployment_id: str | None, expected: tuple[str, ...]
+):
+    exception = Exception("upstream refused this request")
+    exception.status_code = 400
+    exception.failed_deployment_id = failed_deployment_id
+
+    litellm.Router._stamp_retry_skip_deployment_id(exception, kwargs)
+
+    assert litellm.Router._deployment_ids_to_skip_on_retry(exception, None) == expected
+    assert exception.failed_deployment_id == failed_deployment_id
+
+
 @pytest.mark.parametrize(
     "value,expected",
     [
@@ -14165,6 +14192,206 @@ async def test_router_retry_policy_400_never_returns_to_a_deployment_that_alread
     assert response.choices[0].message.content == "hi back"
 
 
+_LIT_7114_CHAT_OK = {
+    "id": "chatcmpl-lit-7114",
+    "object": "chat.completion",
+    "created": 1,
+    "model": "gpt-5.6",
+    "choices": [{"index": 0, "message": {"role": "assistant", "content": "hi back"}, "finish_reason": "stop"}],
+    "usage": {"prompt_tokens": 1, "completion_tokens": 2, "total_tokens": 3},
+}
+_LIT_7114_EMBEDDING_OK = {
+    "object": "list",
+    "data": [{"object": "embedding", "index": 0, "embedding": [0.1]}],
+    "model": "text-embedding-3-large",
+    "usage": {"prompt_tokens": 1, "total_tokens": 1},
+}
+_LIT_7114_IMAGE_OK = {"created": 1, "data": [{"b64_json": "aGk="}]}
+_LIT_7114_BATCH_OK = {
+    "id": "batch_lit_7114",
+    "object": "batch",
+    "endpoint": "/v1/chat/completions",
+    "input_file_id": "file-lit-7114",
+    "completion_window": "24h",
+    "status": "validating",
+    "created_at": 1,
+}
+
+
+class _PassthroughAdapter(CustomLogger):
+    def translate_completion_input_params(self, kwargs: ChatCompletionRequest) -> ChatCompletionRequest:
+        return ChatCompletionRequest(**kwargs)
+
+    def translate_completion_output_params(self, response: litellm.ModelResponse) -> litellm.ModelResponse:
+        return response
+
+
+def _lit_7114_router(litellm_model: str) -> litellm.Router:
+    api_base_suffix: Final = "" if litellm_model.startswith("cohere/") else "/v1"
+    return litellm.Router(
+        model_list=[
+            {
+                "model_name": "gpt-5.6",
+                "litellm_params": {
+                    "model": litellm_model,
+                    "api_key": "sk-fake",
+                    "api_base": f"https://{host}.local{api_base_suffix}",
+                    "weight": weight,
+                },
+                "model_info": {"id": host},
+            }
+            for host, weight in (("rejecting", 1), ("accepting", 0))
+        ],
+        num_retries=2,
+        retry_policy={"BadRequestErrorRetries": 2},
+        disable_cooldowns=True,
+    )
+
+
+def _lit_7114_mock_upstreams(
+    respx_mock: respx.MockRouter, path: str, refusal_status: int, success_body: Mapping[str, object] | bytes
+) -> tuple[respx.Route, respx.Route]:
+    ok_response: Final = (
+        httpx.Response(200, content=success_body)
+        if isinstance(success_body, bytes)
+        else httpx.Response(200, json=success_body)
+    )
+    rejecting: Final = respx_mock.post(f"https://rejecting.local{path}").mock(
+        return_value=httpx.Response(
+            refusal_status, json={"error": _UPSTREAM_400, "message": "upstream refused this request"}
+        )
+    )
+    accepting: Final = respx_mock.post(f"https://accepting.local{path}").mock(return_value=ok_response)
+    return rejecting, accepting
+
+
+_LIT_7114_ASYNC_ENTRYPOINTS: Final[
+    Mapping[str, tuple[str, str, int, Mapping[str, object] | bytes, Callable[[litellm.Router], Awaitable[object]]]]
+] = {
+    "aembedding": (
+        "openai/text-embedding-3-large",
+        "/v1/embeddings",
+        400,
+        _LIT_7114_EMBEDDING_OK,
+        lambda router: router.aembedding(model="gpt-5.6", input="hi"),
+    ),
+    "aimage_generation": (
+        "openai/gpt-image-1",
+        "/v1/images/generations",
+        400,
+        _LIT_7114_IMAGE_OK,
+        lambda router: router.aimage_generation(model="gpt-5.6", prompt="a cat"),
+    ),
+    "atext_completion": (
+        "text-completion-openai/gpt-3.5-turbo-instruct",
+        "/v1/completions",
+        400,
+        {"id": "c", "object": "text_completion", "created": 1, "model": "i", "choices": [{"text": "hi", "index": 0}]},
+        lambda router: router.atext_completion(model="gpt-5.6", prompt="hi"),
+    ),
+    "aspeech": (
+        "openai/gpt-4o-mini-tts",
+        "/v1/audio/speech",
+        400,
+        b"RIFF",
+        lambda router: router.aspeech(model="gpt-5.6", input="hi", voice="alloy"),
+    ),
+    "atranscription": (
+        "openai/gpt-4o-transcribe",
+        "/v1/audio/transcriptions",
+        400,
+        {"text": "hi"},
+        lambda router: router.atranscription(model="gpt-5.6", file=("hi.wav", b"RIFF", "audio/wav")),
+    ),
+    "arerank": (
+        "cohere/rerank-v3.5",
+        "/v2/rerank",
+        400,
+        {"id": "r", "results": [{"index": 0, "relevance_score": 0.9}], "meta": {}},
+        lambda router: router.arerank(model="gpt-5.6", query="hi", documents=["hi"]),
+    ),
+    "aadapter_completion": (
+        "openai/gpt-5.6",
+        "/v1/chat/completions",
+        400,
+        _LIT_7114_CHAT_OK,
+        lambda router: router.aadapter_completion(
+            adapter_id="lit-7114", model="gpt-5.6", messages=[{"role": "user", "content": "hi"}]
+        ),
+    ),
+    "acreate_batch": (
+        "openai/gpt-5.6",
+        "/v1/batches",
+        401,
+        _LIT_7114_BATCH_OK,
+        lambda router: router.acreate_batch(
+            model="gpt-5.6", completion_window="24h", endpoint="/v1/chat/completions", input_file_id="file-lit-7114"
+        ),
+    ),
+    "acancel_batch": (
+        "openai/gpt-5.6",
+        "/v1/batches/batch_lit_7114/cancel",
+        401,
+        {**_LIT_7114_BATCH_OK, "status": "cancelling"},
+        lambda router: router.acancel_batch(model="gpt-5.6", batch_id="batch_lit_7114"),
+    ),
+}
+
+
+@pytest.mark.parametrize("entrypoint", sorted(_LIT_7114_ASYNC_ENTRYPOINTS))
+@pytest.mark.asyncio
+async def test_router_retry_moves_off_the_refusing_deployment_on_every_async_entrypoint(
+    monkeypatch: pytest.MonkeyPatch, entrypoint: str
+):
+    litellm_model, path, refusal_status, success_body, call = _LIT_7114_ASYNC_ENTRYPOINTS[entrypoint]
+    monkeypatch.setattr(litellm, "disable_aiohttp_transport", True)
+    monkeypatch.setattr(litellm, "adapters", [{"id": "lit-7114", "adapter": _PassthroughAdapter()}])
+    router: Final = _lit_7114_router(litellm_model)
+
+    with respx.mock as respx_mock:
+        rejecting, accepting = _lit_7114_mock_upstreams(respx_mock, path, refusal_status, success_body)
+        response: Final = await call(router)
+
+    assert response is not None
+    assert rejecting.call_count == 1
+    assert accepting.call_count == 1
+
+
+_LIT_7114_SYNC_ENTRYPOINTS: Final[
+    Mapping[str, tuple[str, str, Mapping[str, object], Callable[[litellm.Router], object]]]
+] = {
+    "embedding": (
+        "openai/text-embedding-3-large",
+        "/v1/embeddings",
+        _LIT_7114_EMBEDDING_OK,
+        lambda router: router.embedding(model="gpt-5.6", input="hi"),
+    ),
+    "image_generation": (
+        "openai/gpt-image-1",
+        "/v1/images/generations",
+        _LIT_7114_IMAGE_OK,
+        lambda router: router.image_generation(model="gpt-5.6", prompt="a cat"),
+    ),
+}
+
+
+@pytest.mark.parametrize("entrypoint", sorted(_LIT_7114_SYNC_ENTRYPOINTS))
+def test_router_retry_policy_400_moves_off_the_refusing_deployment_on_every_sync_entrypoint(
+    monkeypatch: pytest.MonkeyPatch, entrypoint: str
+):
+    litellm_model, path, success_body, call = _LIT_7114_SYNC_ENTRYPOINTS[entrypoint]
+    monkeypatch.setattr(litellm, "disable_aiohttp_transport", True)
+    router: Final = _lit_7114_router(litellm_model)
+
+    with respx.mock as respx_mock:
+        rejecting, accepting = _lit_7114_mock_upstreams(respx_mock, path, 400, success_body)
+        response: Final = call(router)
+
+    assert response is not None
+    assert rejecting.call_count == 1
+    assert accepting.call_count == 1
+
+
 def _make_failure_logging_obj():
     return LiteLLMLogging(
         model="gpt-5.6",

From 6d58102bd77be48a1d2d532bce64c8b982923759 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 8 Sep 2026 15:54:13 -0700
Subject: [PATCH 23/31] fix(ui): retain compatible build and test commands

---
 .github/workflows/test-litellm-ui-unit.yml | 4 ++--
 ui/litellm-dashboard/next.config.mjs       | 3 +++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test-litellm-ui-unit.yml b/.github/workflows/test-litellm-ui-unit.yml
index cd58f861a87..b93bf84320d 100644
--- a/.github/workflows/test-litellm-ui-unit.yml
+++ b/.github/workflows/test-litellm-ui-unit.yml
@@ -66,7 +66,7 @@ jobs:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
         run: |
-          full_suite() { npm run test -- --run --pool forks --poolOptions.forks.maxForks=14; }
+          full_suite() { npm run test -- --run --pool forks --maxWorkers=14; }
 
           if [ -z "$BASE_SHA" ]; then
             echo "Push to $GITHUB_REF_NAME: running the full suite"
@@ -95,4 +95,4 @@ jobs:
 
           echo "Pull request: running tests related to ${#changed_files[@]} changed UI files"
           npm run test -- related "${changed_files[@]}" --run --passWithNoTests \
-            --pool forks --poolOptions.forks.maxForks=14
+            --pool forks --maxWorkers=14
diff --git a/ui/litellm-dashboard/next.config.mjs b/ui/litellm-dashboard/next.config.mjs
index 876df2b49cf..128ce0a84a7 100644
--- a/ui/litellm-dashboard/next.config.mjs
+++ b/ui/litellm-dashboard/next.config.mjs
@@ -7,6 +7,9 @@ const __dirname = path.dirname(__filename);
 
 const nextConfig = {
   output: "export",
+  experimental: {
+    useTypeScriptCli: false,
+  },
   compiler: {
     removeConsole: process.env.NODE_ENV === "production" ? { exclude: ["error", "warn"] } : false,
   },

From c6a938731998779f48a086551dd9caa7fea71dcf Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 15:54:31 -0700
Subject: [PATCH 24/31] fix(proxy): default max_idle_connection_lifetime on
 componentized DB URLs (#40285)

* fix(proxy): default max_idle_connection_lifetime on componentized DB URLs

DatabaseURLSettings.apply_to_env() now appends max_idle_connection_lifetime=60
(or DATABASE_MAX_IDLE_CONNECTION_LIFETIME) to DATABASE_URL and DIRECT_URL before
the reader inherits the writer's connection params, so the gateway, backend and
migrations entrypoints get the same idle-connection reaping as the classic CLI.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix(proxy): keep DB URL connection params across IAM/Entra token refresh

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* ci: retrigger proxy-infra after process-tree test flake

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: yassin <yassin@berri.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/proxy/db/db_url_settings.py           |  10 ++
 litellm/proxy/db/prisma_client.py             |   6 +-
 .../proxy/db/test_db_url_settings.py          | 152 +++++++++++++++---
 .../proxy/db/test_prisma_client.py            |  50 ++++++
 4 files changed, 192 insertions(+), 26 deletions(-)

diff --git a/litellm/proxy/db/db_url_settings.py b/litellm/proxy/db/db_url_settings.py
index f28e505246a..4a0231ad9df 100644
--- a/litellm/proxy/db/db_url_settings.py
+++ b/litellm/proxy/db/db_url_settings.py
@@ -64,6 +64,7 @@ DISABLE_PREPARED_STATEMENTS_ENV_VAR: Final = "DATABASE_DISABLE_PREPARED_STATEMEN
 DisablePreparedStatementsFlag = Annotated[
     bool, BeforeValidator(partial(token_auth_flag_enabled, env_var=DISABLE_PREPARED_STATEMENTS_ENV_VAR))
 ]
+MAX_IDLE_CONNECTION_LIFETIME_ENV_VAR: Final = "DATABASE_MAX_IDLE_CONNECTION_LIFETIME"
 
 # schema.prisma pins `provider = "postgresql"`, so these are the only schemes
 # Prisma can actually connect with.
@@ -217,6 +218,9 @@ class DatabaseURLSettings(BaseSettings):
     disable_prepared_statements: DisablePreparedStatementsFlag = Field(
         default=False, validation_alias=DISABLE_PREPARED_STATEMENTS_ENV_VAR
     )
+    max_idle_connection_lifetime: int | None = Field(
+        default=None, validation_alias=MAX_IDLE_CONNECTION_LIFETIME_ENV_VAR
+    )
 
     # Writer
     database_url: str | None = Field(default=None, validation_alias="DATABASE_URL")
@@ -453,6 +457,12 @@ class DatabaseURLSettings(BaseSettings):
                 if url:
                     os.environ[env_var] = add_missing_query_params(url, MappingProxyType({"pgbouncer": "true"}))
 
+        lifetime_params: Final = idle_lifetime_params(self.max_idle_connection_lifetime)
+        for env_var in ("DATABASE_URL", "DIRECT_URL"):
+            url = os.environ.get(env_var)
+            if url:
+                os.environ[env_var] = add_missing_query_params(url, lifetime_params)
+
         # The reader inherits the writer's connection params (pool size, timeouts,
         # pgbouncer mode). Without this the reader pool ignores the configured cap
         # and falls back to Prisma's `num_physical_cpus * 2 + 1` default.
diff --git a/litellm/proxy/db/prisma_client.py b/litellm/proxy/db/prisma_client.py
index 9ea2432f2f5..21b73f27a80 100644
--- a/litellm/proxy/db/prisma_client.py
+++ b/litellm/proxy/db/prisma_client.py
@@ -16,6 +16,7 @@ from datetime import datetime, timedelta
 from typing import Any, Final, Protocol
 
 from litellm._logging import verbose_proxy_logger
+from litellm.proxy.db.db_url_settings import add_missing_query_params, connection_params_from_url
 from litellm.proxy.db.token_auth import (
     DEFAULT_POSTGRES_PORT,
     DatabaseTokenAuth,
@@ -438,7 +439,10 @@ class PrismaWrapper:
             return None
 
         endpoint: Final = self._iam_endpoint if self._iam_endpoint is not None else self._endpoint_from_env()
-        db_url: Final = endpoint.build_url(mint_database_token(auth, endpoint))
+        db_url: Final = add_missing_query_params(
+            endpoint.build_url(mint_database_token(auth, endpoint)),
+            connection_params_from_url(os.environ.get(self._db_url_env_var, "")),
+        )
         os.environ[self._db_url_env_var] = db_url
         return db_url
 
diff --git a/tests/test_litellm/proxy/db/test_db_url_settings.py b/tests/test_litellm/proxy/db/test_db_url_settings.py
index db524625a93..ba342342366 100644
--- a/tests/test_litellm/proxy/db/test_db_url_settings.py
+++ b/tests/test_litellm/proxy/db/test_db_url_settings.py
@@ -35,6 +35,7 @@ _MANAGED_DB_ENV_VARS = (
     "IAM_TOKEN_DB_AUTH",
     "AZURE_POSTGRESQL_AUTH",
     "DATABASE_DISABLE_PREPARED_STATEMENTS",
+    "DATABASE_MAX_IDLE_CONNECTION_LIFETIME",
     "DATABASE_URL",
     "DIRECT_URL",
     "DATABASE_URL_READ_REPLICA",
@@ -111,7 +112,7 @@ def test_assembles_writer_url_when_iam_enabled(monkeypatch):
 
     assert (
         os.environ["DATABASE_URL"]
-        == "postgresql://litellm:WRITER_TOKEN@writer.example.com:5432/litellm_db"
+        == "postgresql://litellm:WRITER_TOKEN@writer.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
     # Reader was never configured, so it must not have been set.
     assert "DATABASE_URL_READ_REPLICA" not in os.environ
@@ -130,7 +131,9 @@ def test_a_pre_encoded_iam_user_survives_url_assembly(monkeypatch):
     with _stub_iam_token("WRITER_TOKEN"):
         assert _apply() is True
 
-    assert os.environ["DATABASE_URL"] == "postgresql://svc%40corp:WRITER_TOKEN@writer.example.com:5432/litellm_db"
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://svc%40corp:WRITER_TOKEN@writer.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
+    )
 
 
 def test_an_unreadable_toggle_fails_the_settings_model(monkeypatch):
@@ -168,7 +171,7 @@ def test_reader_url_assembled_when_host_set_and_url_unset(monkeypatch):
 
     assert (
         os.environ["DATABASE_URL_READ_REPLICA"]
-        == "postgresql://litellm:READER_TOKEN@reader.example.com:5432/litellm_db"
+        == "postgresql://litellm:READER_TOKEN@reader.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -191,7 +194,7 @@ def test_reader_url_not_clobbered_when_already_set(monkeypatch):
 
     assert (
         os.environ["DATABASE_URL_READ_REPLICA"]
-        == "postgresql://app:secret@reader.example.com:5432/litellm_db"
+        == "postgresql://app:secret@reader.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -222,7 +225,8 @@ def test_reader_field_fallbacks_default_to_writer_values(monkeypatch):
 
     assert (
         os.environ["DATABASE_URL_READ_REPLICA"]
-        == "postgresql://litellm:READER_TOKEN@reader.example.com:5432/litellm_db?schema=public"
+        == "postgresql://litellm:READER_TOKEN@reader.example.com:5432/litellm_db"
+        "?schema=public&max_idle_connection_lifetime=60"
     )
 
 
@@ -242,7 +246,7 @@ def test_assembles_writer_url_when_azure_entra_enabled(monkeypatch):
 
     assert os.environ["DATABASE_URL"] == (
         "postgresql://litellm%40contoso.onmicrosoft.com:ENTRA_TOKEN"
-        "@writer.postgres.database.azure.com:5432/litellm_db"
+        "@writer.postgres.database.azure.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
     assert os.environ["AZURE_POSTGRESQL_AUTH"] == "True"
     assert "IAM_TOKEN_DB_AUTH" not in os.environ
@@ -261,7 +265,7 @@ def test_azure_reader_url_assembled_from_writer_fallbacks(monkeypatch):
 
     assert os.environ["DATABASE_URL_READ_REPLICA"] == (
         "postgresql://litellm%40contoso.onmicrosoft.com:ENTRA_TOKEN"
-        "@reader.postgres.database.azure.com:5432/litellm_db?schema=public"
+        "@reader.postgres.database.azure.com:5432/litellm_db?schema=public&max_idle_connection_lifetime=60"
     )
 
 
@@ -357,7 +361,7 @@ def test_assembles_writer_url_from_password(monkeypatch):
     assert _apply() is True
     assert (
         os.environ["DATABASE_URL"]
-        == "postgresql://litellm:s3cr3t@writer.example.com:5432/litellm_db"
+        == "postgresql://litellm:s3cr3t@writer.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -370,7 +374,7 @@ def test_writer_password_is_percent_encoded(monkeypatch):
     assert _apply() is True
     assert (
         os.environ["DATABASE_URL"]
-        == "postgresql://litellm:p%40ss%2Fw%3Ard@writer.example.com:5432/litellm_db"
+        == "postgresql://litellm:p%40ss%2Fw%3Ard@writer.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -388,7 +392,7 @@ def test_writer_url_not_clobbered_when_already_set(monkeypatch):
     assert _apply() is False
     assert (
         os.environ["DATABASE_URL"]
-        == "postgresql://pinned:url@db.example.com:5432/litellm_db"
+        == "postgresql://pinned:url@db.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -400,7 +404,7 @@ def test_writer_url_passwordless(monkeypatch):
     assert _apply() is True
     assert (
         os.environ["DATABASE_URL"]
-        == "postgresql://litellm@writer.example.com:5432/litellm_db"
+        == "postgresql://litellm@writer.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -415,7 +419,7 @@ def test_database_username_alias(monkeypatch):
     assert _apply() is True
     assert (
         os.environ["DATABASE_URL"]
-        == "postgresql://litellm:s3cr3t@writer.example.com:5432/litellm_db"
+        == "postgresql://litellm:s3cr3t@writer.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -429,7 +433,7 @@ def test_password_reader_falls_back_to_writer_password(monkeypatch):
     assert _apply() is True
     assert (
         os.environ["DATABASE_URL_READ_REPLICA"]
-        == "postgresql://litellm:s3cr3t@reader.example.com:5432/litellm_db"
+        == "postgresql://litellm:s3cr3t@reader.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -445,7 +449,7 @@ def test_password_reader_uses_own_credentials(monkeypatch):
     assert _apply() is True
     assert (
         os.environ["DATABASE_URL_READ_REPLICA"]
-        == "postgresql://litellm_ro:ro_pw@reader.example.com:5432/litellm_db"
+        == "postgresql://litellm_ro:ro_pw@reader.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
     )
 
 
@@ -641,19 +645,19 @@ def test_reader_keeps_its_own_options_when_writer_params_are_appended(monkeypatc
     assert query["connection_limit"] == ["3"]
 
 
-def test_reader_url_left_alone_when_writer_has_no_params(monkeypatch):
+def test_reader_url_left_alone_when_nothing_is_missing(monkeypatch):
     """No params to inherit must mean the reader URL is not rewritten at all."""
     monkeypatch.setenv("DATABASE_URL", "postgresql://u:p@writer.example.com:5432/db")
     monkeypatch.setenv(
         "DATABASE_URL_READ_REPLICA",
-        "postgresql://u:p@reader.example.com:5432/db?options=-c%20search_path%3Dapp",
+        "postgresql://u:p@reader.example.com:5432/db?options=-c%20search_path%3Dapp&max_idle_connection_lifetime=45",
     )
 
     _apply()
 
     assert (
         os.environ["DATABASE_URL_READ_REPLICA"]
-        == "postgresql://u:p@reader.example.com:5432/db?options=-c%20search_path%3Dapp"
+        == "postgresql://u:p@reader.example.com:5432/db?options=-c%20search_path%3Dapp&max_idle_connection_lifetime=45"
     )
 
 
@@ -671,7 +675,7 @@ def test_disable_prepared_statements_appends_pgbouncer_to_assembled_writer(monke
 
     assert _apply() is True
     assert os.environ["DATABASE_URL"] == (
-        "postgresql://litellm:s3cr3t@writer.example.com:5432/litellm_db?pgbouncer=true"
+        "postgresql://litellm:s3cr3t@writer.example.com:5432/litellm_db?pgbouncer=true&max_idle_connection_lifetime=60"
     )
     assert "DIRECT_URL" not in os.environ
 
@@ -685,7 +689,9 @@ def test_disable_prepared_statements_appends_pgbouncer_to_pinned_writer(monkeypa
     monkeypatch.setenv("DATABASE_URL", "postgresql://u:p@db.example.com:5432/litellm_db")
 
     assert _apply() is False
-    assert os.environ["DATABASE_URL"] == "postgresql://u:p@db.example.com:5432/litellm_db?pgbouncer=true"
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://u:p@db.example.com:5432/litellm_db?pgbouncer=true&max_idle_connection_lifetime=60"
+    )
 
 
 def test_disable_prepared_statements_respects_a_pinned_pgbouncer_value(monkeypatch):
@@ -694,7 +700,9 @@ def test_disable_prepared_statements_respects_a_pinned_pgbouncer_value(monkeypat
 
     _apply()
 
-    assert os.environ["DATABASE_URL"] == "postgresql://u:p@db.example.com:5432/litellm_db?pgbouncer=false"
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://u:p@db.example.com:5432/litellm_db?pgbouncer=false&max_idle_connection_lifetime=60"
+    )
 
 
 def test_disable_prepared_statements_applies_to_direct_url(monkeypatch):
@@ -704,7 +712,9 @@ def test_disable_prepared_statements_applies_to_direct_url(monkeypatch):
 
     _apply()
 
-    assert os.environ["DIRECT_URL"] == "postgresql://u:p@direct.example.com:5432/litellm_db?pgbouncer=true"
+    assert os.environ["DIRECT_URL"] == (
+        "postgresql://u:p@direct.example.com:5432/litellm_db?pgbouncer=true&max_idle_connection_lifetime=60"
+    )
 
 
 def test_reader_inherits_pgbouncer_from_disable_prepared_statements(monkeypatch):
@@ -724,7 +734,9 @@ def test_disable_prepared_statements_off_leaves_urls_alone(monkeypatch):
 
     _apply()
 
-    assert os.environ["DATABASE_URL"] == "postgresql://u:p@db.example.com:5432/litellm_db"
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://u:p@db.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
+    )
 
 
 def test_disable_prepared_statements_rejects_an_unreadable_value(monkeypatch):
@@ -760,6 +772,7 @@ def test_libpq_verify_full_and_sslrootcert_become_prisma_strict_sslcert(monkeypa
         "sslmode": ["require"],
         "sslcert": ["/certs/rds-bundle.pem"],
         "sslaccept": ["strict"],
+        "max_idle_connection_lifetime": ["60"],
     }
 
 
@@ -768,7 +781,11 @@ def test_libpq_verify_ca_becomes_prisma_strict(monkeypatch):
 
     _apply()
 
-    assert _query(os.environ["DATABASE_URL"]) == {"sslmode": ["require"], "sslaccept": ["strict"]}
+    assert _query(os.environ["DATABASE_URL"]) == {
+        "sslmode": ["require"],
+        "sslaccept": ["strict"],
+        "max_idle_connection_lifetime": ["60"],
+    }
 
 
 def test_sslrootcert_alone_turns_on_strict_verification(monkeypatch):
@@ -784,6 +801,7 @@ def test_sslrootcert_alone_turns_on_strict_verification(monkeypatch):
         "sslmode": ["require"],
         "sslcert": ["/certs/ca.pem"],
         "sslaccept": ["strict"],
+        "max_idle_connection_lifetime": ["60"],
     }
 
 
@@ -800,11 +818,15 @@ def test_pinned_prisma_ssl_params_win_over_libpq_translation(monkeypatch):
         "sslmode": ["require"],
         "sslcert": ["/pinned.pem"],
         "sslaccept": ["accept_invalid_certs"],
+        "max_idle_connection_lifetime": ["60"],
     }
 
 
 def test_prisma_native_ssl_url_is_left_untouched(monkeypatch):
-    url = "postgresql://u:p@db.example.com:5432/litellm_db?sslmode=require&sslcert=/certs/ca.pem&sslaccept=strict"
+    url = (
+        "postgresql://u:p@db.example.com:5432/litellm_db"
+        "?sslmode=require&sslcert=/certs/ca.pem&sslaccept=strict&max_idle_connection_lifetime=60"
+    )
     monkeypatch.setenv("DATABASE_URL", url)
 
     _apply()
@@ -820,4 +842,84 @@ def test_libpq_ssl_translation_covers_direct_url_and_read_replica(monkeypatch):
     _apply()
 
     for env_var in ("DATABASE_URL", "DIRECT_URL", "DATABASE_URL_READ_REPLICA"):
-        assert _query(os.environ[env_var]) == {"sslmode": ["require"], "sslaccept": ["strict"]}, env_var
+        assert _query(os.environ[env_var]) == {
+            "sslmode": ["require"],
+            "sslaccept": ["strict"],
+            "max_idle_connection_lifetime": ["60"],
+        }, env_var
+
+
+def test_default_idle_lifetime_applied_to_pinned_writer_and_direct_url(monkeypatch):
+    monkeypatch.setenv("DATABASE_URL", "postgresql://u:p@db.example.com:5432/litellm_db")
+    monkeypatch.setenv("DIRECT_URL", "postgresql://u:p@direct.example.com:5432/litellm_db")
+
+    assert _apply() is False
+
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://u:p@db.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
+    )
+    assert os.environ["DIRECT_URL"] == (
+        "postgresql://u:p@direct.example.com:5432/litellm_db?max_idle_connection_lifetime=60"
+    )
+
+
+def test_url_pinned_idle_lifetime_wins_over_default_and_env_knob(monkeypatch):
+    monkeypatch.setenv("DATABASE_MAX_IDLE_CONNECTION_LIFETIME", "45")
+    monkeypatch.setenv(
+        "DATABASE_URL", "postgresql://u:p@db.example.com:5432/litellm_db?max_idle_connection_lifetime=300"
+    )
+
+    _apply()
+
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://u:p@db.example.com:5432/litellm_db?max_idle_connection_lifetime=300"
+    )
+
+
+def test_env_knob_overrides_default_idle_lifetime(monkeypatch):
+    monkeypatch.setenv("DATABASE_MAX_IDLE_CONNECTION_LIFETIME", "45")
+    monkeypatch.setenv("DATABASE_URL", "postgresql://u:p@db.example.com:5432/litellm_db")
+    monkeypatch.setenv("DIRECT_URL", "postgresql://u:p@direct.example.com:5432/litellm_db")
+
+    _apply()
+
+    assert os.environ["DATABASE_URL"] == (
+        "postgresql://u:p@db.example.com:5432/litellm_db?max_idle_connection_lifetime=45"
+    )
+    assert os.environ["DIRECT_URL"] == (
+        "postgresql://u:p@direct.example.com:5432/litellm_db?max_idle_connection_lifetime=45"
+    )
+
+
+def test_env_knob_rejects_a_non_integer_value(monkeypatch):
+    monkeypatch.setenv("DATABASE_MAX_IDLE_CONNECTION_LIFETIME", "soon")
+
+    with pytest.raises(ValidationError, match="DATABASE_MAX_IDLE_CONNECTION_LIFETIME"):
+        DatabaseURLSettings.from_env()
+
+
+@pytest.mark.parametrize(("knob", "expected"), [(None, "60"), ("45", "45")])
+def test_reader_inherits_the_writer_idle_lifetime(monkeypatch, knob, expected):
+    if knob is not None:
+        monkeypatch.setenv("DATABASE_MAX_IDLE_CONNECTION_LIFETIME", knob)
+    monkeypatch.setenv("DATABASE_URL", "postgresql://u:p@writer.example.com:5432/db")
+    monkeypatch.setenv("DATABASE_URL_READ_REPLICA", "postgresql://u:p@reader.example.com:5432/db")
+
+    _apply()
+
+    assert os.environ["DATABASE_URL_READ_REPLICA"] == (
+        f"postgresql://u:p@reader.example.com:5432/db?max_idle_connection_lifetime={expected}"
+    )
+
+
+def test_reader_keeps_its_own_pinned_idle_lifetime(monkeypatch):
+    monkeypatch.setenv("DATABASE_URL", "postgresql://u:p@writer.example.com:5432/db")
+    monkeypatch.setenv(
+        "DATABASE_URL_READ_REPLICA", "postgresql://u:p@reader.example.com:5432/db?max_idle_connection_lifetime=120"
+    )
+
+    _apply()
+
+    assert os.environ["DATABASE_URL_READ_REPLICA"] == (
+        "postgresql://u:p@reader.example.com:5432/db?max_idle_connection_lifetime=120"
+    )
diff --git a/tests/test_litellm/proxy/db/test_prisma_client.py b/tests/test_litellm/proxy/db/test_prisma_client.py
index 7f43e483557..963f6a5640f 100644
--- a/tests/test_litellm/proxy/db/test_prisma_client.py
+++ b/tests/test_litellm/proxy/db/test_prisma_client.py
@@ -291,6 +291,56 @@ def test_azure_entra_mint_writes_an_encoded_url_into_the_db_url_env_var(azure_en
     assert os.environ["DATABASE_URL"] == db_url
 
 
+@pytest.mark.parametrize(
+    ("previous_query", "expected_query"),
+    [
+        ("max_idle_connection_lifetime=60", {"max_idle_connection_lifetime": ["60"]}),
+        (
+            "connection_limit=20&pgbouncer=true&max_idle_connection_lifetime=45",
+            {"connection_limit": ["20"], "pgbouncer": ["true"], "max_idle_connection_lifetime": ["45"]},
+        ),
+    ],
+)
+def test_token_refresh_keeps_the_connection_params_of_the_url_it_replaces(
+    azure_env, monkeypatch, previous_query, expected_query
+):
+    old_token = _entra_jwt(60)
+    monkeypatch.setenv(
+        "DATABASE_URL",
+        f"postgresql://litellm%40contoso.onmicrosoft.com:{urllib.parse.quote(old_token, safe='')}"
+        f"@pg.postgres.database.azure.com:5432/litellm_db?{previous_query}",
+    )
+    new_token = _entra_jwt(3600)
+
+    db_url = _azure_wrapper(new_token).get_rds_iam_token()
+
+    assert db_url is not None
+    assert os.environ["DATABASE_URL"] == db_url
+    assert urllib.parse.quote(new_token, safe="") in db_url
+    assert urllib.parse.parse_qs(urllib.parse.urlsplit(db_url).query) == expected_query
+
+
+def test_token_refresh_keeps_the_reader_url_params_separate_from_the_writer(azure_env, monkeypatch):
+    from litellm.proxy.db.token_auth import IAMEndpoint
+
+    monkeypatch.setenv("DATABASE_URL", "postgresql://w:t@pg:5432/litellm_db?max_idle_connection_lifetime=45")
+    monkeypatch.setenv(
+        "DATABASE_URL_READ_REPLICA", "postgresql://r:t@replica:5432/litellm_db?max_idle_connection_lifetime=60"
+    )
+    reader = _azure_wrapper(
+        _entra_jwt(3600),
+        db_url_env_var="DATABASE_URL_READ_REPLICA",
+        iam_endpoint=IAMEndpoint(host="replica", port="5432", user="r", name="litellm_db", schema=None),
+    )
+
+    reader_url = reader.get_rds_iam_token()
+
+    assert reader_url is not None
+    assert reader_url.startswith("postgresql://r:")
+    assert urllib.parse.parse_qs(urllib.parse.urlsplit(reader_url).query) == {"max_idle_connection_lifetime": ["60"]}
+    assert os.environ["DATABASE_URL"].endswith("?max_idle_connection_lifetime=45")
+
+
 def test_azure_entra_refresh_is_scheduled_off_the_jwt_expiry(azure_env):
     """Without reading `exp` this falls back to a fixed 600s interval, which silently
     outlives a token and breaks every reconnect after it lapses (issue #29661)."""

From 4b9c289a7219400317ec41e4dc2816ba7559a542 Mon Sep 17 00:00:00 2001
From: Yassin Kortam <yassin@berri.ai>
Date: Tue, 8 Sep 2026 15:56:52 -0700
Subject: [PATCH 25/31] fix(a2a): forward caller identity headers on
 message/send and message/stream (#40305)

* fix(a2a): forward caller identity headers on message/send and message/stream

_forwarding_headers() stamped X-LiteLLM-User-Id/-Team-Id from the authenticated
caller, but was only wired into the tasks/* and tasks/resubscribe branches. The
primary message/send and message/stream conversational path forwarded
agent_extra_headers unchanged, so a downstream agent never learned which end
user was calling it except on secondary task-management calls. This broke
per-user MCP scoping and per-customer FinOps budget enforcement for any agent
invoked through the normal conversational flow.

Resolves LIT-7342

* fix(a2a): snapshot key-bound caller identity before pre-call processing

user_header_mappings lets add_litellm_data_to_request rewrite
user_api_key_dict.user_id from a client header, so the identity stamped
onto X-LiteLLM-User-Id is now captured before that step runs. Header
tests updated to expect the caller identity on message/send.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* test(a2a): drop redundant docstrings from message identity tests

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* test(a2a): type the message method test helpers

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* test(a2a): make message method test helpers immutable

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../proxy/agent_endpoints/a2a_endpoints.py    |  62 +++---
 .../agent_endpoints/test_a2a_endpoints.py     | 187 ++++++++++++------
 .../agent_endpoints/test_agent_headers.py     |  10 +-
 3 files changed, 164 insertions(+), 95 deletions(-)

diff --git a/litellm/proxy/agent_endpoints/a2a_endpoints.py b/litellm/proxy/agent_endpoints/a2a_endpoints.py
index 28882484db4..95c34f70d7b 100644
--- a/litellm/proxy/agent_endpoints/a2a_endpoints.py
+++ b/litellm/proxy/agent_endpoints/a2a_endpoints.py
@@ -144,31 +144,32 @@ def _validate_push_notification_url(url: str) -> None:
         raise HTTPException(status_code=400, detail=str(e)) from e
 
 
-def _caller_identity_headers(user_api_key_dict: UserAPIKeyAuth) -> dict[str, str]:
-    headers: Final[dict[str, str]] = {}
-    if user_api_key_dict.user_id:
-        headers["X-LiteLLM-User-Id"] = user_api_key_dict.user_id
-    if user_api_key_dict.team_id:
-        headers["X-LiteLLM-Team-Id"] = user_api_key_dict.team_id
-    return headers
+def _caller_identity_headers(user_api_key_dict: UserAPIKeyAuth) -> Mapping[str, str]:
+    return MappingProxyType(
+        {
+            name: value
+            for name, value in (
+                ("X-LiteLLM-User-Id", user_api_key_dict.user_id),
+                ("X-LiteLLM-Team-Id", user_api_key_dict.team_id),
+            )
+            if value
+        }
+    )
 
 
 def _forwarding_headers(
-    user_api_key_dict: UserAPIKeyAuth,
+    caller_identity: Mapping[str, str],
     request_data: Mapping[str, object],
     agent_extra_headers: Mapping[str, str] | None,
-) -> Mapping[str, str] | None:
-    sanitized: Final = (
-        {k: v for k, v in agent_extra_headers.items() if not k.lower().startswith("x-litellm-")}
-        if agent_extra_headers
-        else None
+) -> dict[str, str] | None:
+    passthrough: Final = tuple(
+        (name, value)
+        for name, value in (agent_extra_headers.items() if agent_extra_headers else ())
+        if not name.lower().startswith("x-litellm-")
     )
-    merged: Final = merge_agent_headers(dynamic_headers=sanitized, static_headers=None) or {}
-    identity: Final = _caller_identity_headers(user_api_key_dict)
     trace_id: Final = request_data.get("litellm_trace_id")
-    if trace_id:
-        identity["X-LiteLLM-Trace-Id"] = str(trace_id)
-    merged.update(identity)
+    trace: Final = (("X-LiteLLM-Trace-Id", str(trace_id)),) if trace_id else ()
+    merged: Final = dict((*passthrough, *caller_identity.items(), *trace))
     return merged or None
 
 
@@ -755,6 +756,7 @@ async def invoke_agent_a2a(
             ProxyBaseLLMRequestProcessing,
         )
 
+        caller_identity: Final = _caller_identity_headers(user_api_key_dict)
         processor: Final = ProxyBaseLLMRequestProcessing(data=body)
         data, logging_obj = await processor.common_processing_pre_call_logic(
             request=request,
@@ -793,9 +795,13 @@ async def invoke_agent_a2a(
                     if header_name:
                         dynamic_headers[header_name] = val
 
-        agent_extra_headers = merge_agent_headers(
-            dynamic_headers=dynamic_headers or None,
-            static_headers=static_headers or None,
+        agent_extra_headers = _forwarding_headers(
+            caller_identity=caller_identity,
+            request_data=data,
+            agent_extra_headers=merge_agent_headers(
+                dynamic_headers=dynamic_headers or None,
+                static_headers=static_headers or None,
+            ),
         )
 
         # Databricks App endpoints require a short-lived OAuth M2M token rather
@@ -942,12 +948,7 @@ async def invoke_agent_a2a(
                 "method": method,
                 "params": params,
             }
-            caller_headers: Final = _forwarding_headers(
-                user_api_key_dict=user_api_key_dict,
-                request_data=data,
-                agent_extra_headers=agent_extra_headers,
-            )
-            result = await _forward_jsonrpc(agent_url, forward_body, extra_headers=caller_headers)
+            result = await _forward_jsonrpc(agent_url, forward_body, extra_headers=agent_extra_headers)
             if method == "agent/getAuthenticatedExtendedCard":
                 card: Final = result.get("result")
                 if isinstance(card, dict):
@@ -988,16 +989,11 @@ async def invoke_agent_a2a(
                 "method": method,
                 "params": params,
             }
-            sse_caller_headers: Final = _forwarding_headers(
-                user_api_key_dict=user_api_key_dict,
-                request_data=data,
-                agent_extra_headers=agent_extra_headers,
-            )
             return await _forward_jsonrpc_sse(
                 agent_url,
                 forward_body,
                 request_id=request_id,
-                extra_headers=sse_caller_headers,
+                extra_headers=agent_extra_headers,
                 proxy_logging_obj=proxy_logging_obj,
                 user_api_key_dict=user_api_key_dict,
                 request_data=data,
diff --git a/tests/test_litellm/proxy/agent_endpoints/test_a2a_endpoints.py b/tests/test_litellm/proxy/agent_endpoints/test_a2a_endpoints.py
index 43034f889f6..e0476361074 100644
--- a/tests/test_litellm/proxy/agent_endpoints/test_a2a_endpoints.py
+++ b/tests/test_litellm/proxy/agent_endpoints/test_a2a_endpoints.py
@@ -7,11 +7,24 @@ Tests that invoke_agent_a2a properly integrates with add_litellm_data_to_request
 import json
 import socket
 import sys
-from contextlib import ExitStack
+from collections.abc import Awaitable, Callable, Mapping
+from contextlib import AbstractContextManager, ExitStack
+from dataclasses import dataclass
+from typing import Final
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+from litellm.proxy._types import UserAPIKeyAuth
+
+AddLiteLLMData = Callable[..., Awaitable[dict[str, object]]]
+
+
+@dataclass(frozen=True, slots=True)
+class CapturedAgentCall:
+    request_id: object
+    agent_extra_headers: dict[str, str] | None
+
 
 @pytest.mark.asyncio
 async def test_invoke_agent_a2a_adds_litellm_data():
@@ -364,7 +377,7 @@ def _make_agent_mock(url: str = "http://backend-agent:10001") -> MagicMock:
 
 
 def _make_request_mock(
-    method: str, params: dict, request_id: object = "req-1"
+    method: str, params: Mapping[str, object], request_id: object = "req-1"
 ) -> MagicMock:
     req = MagicMock()
     req.headers = {}
@@ -379,7 +392,9 @@ def _make_request_mock(
     return req
 
 
-def _base_patches(agent: MagicMock):
+def _base_patches(
+    agent: MagicMock, add_litellm_data: AddLiteLLMData | None = None
+) -> list[AbstractContextManager[object]]:
     return [
         patch(
             "litellm.proxy.agent_endpoints.a2a_endpoints._get_agent",
@@ -391,7 +406,7 @@ def _base_patches(agent: MagicMock):
         ),
         patch(
             "litellm.proxy.common_request_processing.add_litellm_data_to_request",
-            new=AsyncMock(side_effect=_add_proxy_data),
+            new=AsyncMock(side_effect=add_litellm_data or _add_proxy_data),
         ),
         patch("litellm.proxy.proxy_server.general_settings", {}),
         patch("litellm.proxy.proxy_server.proxy_config", MagicMock()),
@@ -399,84 +414,67 @@ def _base_patches(agent: MagicMock):
     ]
 
 
-async def _add_proxy_data(data, **kwargs):
-    data["proxy_server_request"] = {
-        "url": "http://localhost:4000",
-        "method": "POST",
-        "headers": {},
-        "body": {},
+async def _add_proxy_data(data: dict[str, object], **kwargs: object) -> dict[str, object]:
+    return {
+        **data,
+        "proxy_server_request": {"url": "http://localhost:4000", "method": "POST", "headers": {}, "body": {}},
+        "metadata": data.get("metadata", {}),
     }
-    data.setdefault("metadata", {})
-    return data
 
 
-@pytest.mark.asyncio
-@pytest.mark.parametrize("method", ["message/send", "message/stream"])
-async def test_message_methods_preserve_numeric_zero_request_id(method: str):
+_HELLO_MESSAGE_PARAMS = {
+    "message": {
+        "role": "user",
+        "parts": [{"kind": "text", "text": "Hello"}],
+        "messageId": "msg-123",
+    }
+}
+
+
+async def _invoke_message_method(
+    method: str,
+    mock_request: MagicMock,
+    user_api_key_dict: UserAPIKeyAuth,
+    add_litellm_data: AddLiteLLMData | None = None,
+) -> CapturedAgentCall:
     from fastapi.responses import JSONResponse
-    from litellm.proxy._types import UserAPIKeyAuth
 
     class MessageSendParams:
-        def __init__(self, **kwargs):
+        def __init__(self, **kwargs: object) -> None:
             self.__dict__.update(kwargs)
 
     class SendMessageRequest:
-        def __init__(self, **kwargs):
+        def __init__(self, **kwargs: object) -> None:
             self.__dict__.update(kwargs)
 
-    agent = _make_agent_mock()
-    params = {
-        "message": {
-            "role": "user",
-            "parts": [{"kind": "text", "text": "Hello"}],
-            "messageId": "msg-123",
-        }
-    }
-    mock_request = _make_request_mock(method, params, request_id=0)
-    user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
-    captured = {}
-
-    async def capture_asend_message(request, **kwargs):
-        captured["request_id"] = request.id
-        response = MagicMock()
+    async def fake_asend_message(request: SendMessageRequest, **kwargs: object) -> MagicMock:
+        response: Final = MagicMock()
         response.model_dump.return_value = {
             "jsonrpc": "2.0",
-            "id": request.id,
+            "id": request.__dict__["id"],
             "result": {"status": "success"},
         }
         return response
 
-    async def capture_stream_message(**kwargs):
-        captured["request_id"] = kwargs["request_id"]
-        return JSONResponse({"jsonrpc": "2.0", "id": kwargs["request_id"]})
+    async def fake_stream_message(request_id: object, **kwargs: object) -> JSONResponse:
+        return JSONResponse({"jsonrpc": "2.0", "id": request_id})
 
-    mock_a2a_types = MagicMock()
+    mock_a2a_types: Final = MagicMock()
     mock_a2a_types.MessageSendParams = MessageSendParams
     mock_a2a_types.SendMessageRequest = SendMessageRequest
+    is_send: Final = method == "message/send"
+    downstream: Final = AsyncMock(side_effect=fake_asend_message if is_send else fake_stream_message)
 
     with ExitStack() as stack:
-        for p in _base_patches(agent):
+        for p in _base_patches(_make_agent_mock(), add_litellm_data):
             stack.enter_context(p)
         stack.enter_context(patch("litellm.a2a_protocol.main.A2A_SDK_AVAILABLE", True))
-        if method == "message/send":
-            stack.enter_context(
-                patch.dict(
-                    sys.modules,
-                    {"a2a": MagicMock(), "a2a.types": mock_a2a_types},
-                )
-            )
-            stack.enter_context(
-                patch(
-                    "litellm.a2a_protocol.asend_message",
-                    new=AsyncMock(side_effect=capture_asend_message),
-                )
-            )
+        if is_send:
+            stack.enter_context(patch.dict(sys.modules, {"a2a": MagicMock(), "a2a.types": mock_a2a_types}))
+            stack.enter_context(patch("litellm.a2a_protocol.asend_message", new=downstream))
         else:
             stack.enter_context(
-                patch(
-                    "litellm.proxy.agent_endpoints.a2a_endpoints._handle_stream_message",
-                    new=AsyncMock(side_effect=capture_stream_message),
-                )
+                patch("litellm.proxy.agent_endpoints.a2a_endpoints._handle_stream_message", new=downstream)
             )
 
         from litellm.proxy.agent_endpoints.a2a_endpoints import invoke_agent_a2a
@@ -488,7 +486,82 @@ async def test_message_methods_preserve_numeric_zero_request_id(method: str):
             user_api_key_dict=user_api_key_dict,
         )
 
-    assert captured["request_id"] == 0
+    kwargs: Final = downstream.call_args.kwargs
+    request_id: Final = kwargs["request"].__dict__["id"] if is_send else kwargs["request_id"]
+    return CapturedAgentCall(request_id=request_id, agent_extra_headers=kwargs.get("agent_extra_headers"))
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["message/send", "message/stream"])
+async def test_message_methods_preserve_numeric_zero_request_id(method: str):
+    mock_request = _make_request_mock(method, _HELLO_MESSAGE_PARAMS, request_id=0)
+    user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
+
+    captured = await _invoke_message_method(method, mock_request, user_api_key_dict)
+
+    assert captured.request_id == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["message/send", "message/stream"])
+async def test_message_methods_forward_caller_identity_headers(method: str):
+    mock_request = _make_request_mock(method, _HELLO_MESSAGE_PARAMS)
+    user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="user-abc", team_id="team-xyz")
+
+    captured = await _invoke_message_method(method, mock_request, user_api_key_dict)
+
+    forwarded_headers = captured.agent_extra_headers or {}
+    assert forwarded_headers.get("X-LiteLLM-User-Id") == "user-abc"
+    assert forwarded_headers.get("X-LiteLLM-Team-Id") == "team-xyz"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["message/send", "message/stream"])
+async def test_message_methods_caller_identity_headers_cannot_be_spoofed(method: str):
+    mock_request = _make_request_mock(method, _HELLO_MESSAGE_PARAMS)
+    mock_request.headers = {
+        "x-a2a-test-agent-x-litellm-user-id": "attacker-user",
+        "x-a2a-test-agent-x-litellm-team-id": "attacker-team",
+    }
+    user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="real-user", team_id="real-team")
+
+    captured = await _invoke_message_method(method, mock_request, user_api_key_dict)
+
+    forwarded_headers = captured.agent_extra_headers or {}
+    assert (
+        forwarded_headers.get("X-LiteLLM-User-Id") == "real-user"
+    ), "authenticated user id must not be overridden by forwarded client headers"
+    assert (
+        forwarded_headers.get("X-LiteLLM-Team-Id") == "real-team"
+    ), "authenticated team id must not be overridden by forwarded client headers"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["message/send", "message/stream"])
+async def test_message_methods_forward_key_bound_identity_not_pre_call_rewrite(method: str):
+    from litellm.proxy.litellm_pre_call_utils import LiteLLMProxyRequestSetup
+
+    mock_request = _make_request_mock(method, _HELLO_MESSAGE_PARAMS)
+    mock_request.headers = {"X-OpenWebUI-User-Id": "header-mapped-user"}
+    user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="key-user", team_id="key-team")
+    general_settings: Final = {
+        "user_header_mappings": [{"header_name": "X-OpenWebUI-User-Id", "litellm_user_role": "internal_user"}]
+    }
+
+    async def apply_user_header_mapping(data: dict[str, object], **kwargs: object) -> dict[str, object]:
+        LiteLLMProxyRequestSetup.add_internal_user_from_user_mapping(
+            general_settings, user_api_key_dict, dict(mock_request.headers)
+        )
+        return await _add_proxy_data(data, **kwargs)
+
+    captured = await _invoke_message_method(
+        method, mock_request, user_api_key_dict, add_litellm_data=apply_user_header_mapping
+    )
+
+    assert user_api_key_dict.user_id == "header-mapped-user", "precondition: pre-call rewrite ran"
+    forwarded_headers = captured.agent_extra_headers or {}
+    assert forwarded_headers.get("X-LiteLLM-User-Id") == "key-user"
+    assert forwarded_headers.get("X-LiteLLM-Team-Id") == "key-team"
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_litellm/proxy/agent_endpoints/test_agent_headers.py b/tests/test_litellm/proxy/agent_endpoints/test_agent_headers.py
index 15864417489..e894f4ad69a 100644
--- a/tests/test_litellm/proxy/agent_endpoints/test_agent_headers.py
+++ b/tests/test_litellm/proxy/agent_endpoints/test_agent_headers.py
@@ -223,7 +223,7 @@ async def test_static_overrides_dynamic():
 
 @pytest.mark.asyncio
 async def test_no_headers():
-    """When no headers are configured, agent_extra_headers is None and behaviour is unchanged."""
+    """When no headers are configured, only the caller identity is forwarded."""
     mock_agent = _make_mock_agent()  # no static_headers or extra_headers
     mock_request = _make_mock_request()
 
@@ -231,7 +231,7 @@ async def test_no_headers():
 
     call_kwargs = mock_asend.call_args.kwargs
     headers = call_kwargs.get("agent_extra_headers")
-    assert headers is None
+    assert headers == {"X-LiteLLM-User-Id": "u1"}
 
 
 # ---------------------------------------------------------------------------
@@ -303,7 +303,7 @@ async def test_convention_unrelated_prefix_not_forwarded():
     mock_asend = await _invoke(mock_agent, mock_request, None)
 
     headers = mock_asend.call_args.kwargs.get("agent_extra_headers")
-    assert headers is None
+    assert headers == {"X-LiteLLM-User-Id": "u1"}
 
 
 # ---------------------------------------------------------------------------
@@ -393,7 +393,7 @@ async def test_non_databricks_agent_skips_oauth_resolution():
 
     mock_resolve.assert_not_called()
     headers = mock_asend.call_args.kwargs.get("agent_extra_headers")
-    assert headers == {"x-custom": "v"}
+    assert headers == {"x-custom": "v", "X-LiteLLM-User-Id": "u1"}
     assert "Authorization" not in headers
 
 
@@ -477,7 +477,7 @@ async def test_convention_header_blocked_by_case_variant_static():
 
     headers = mock_asend.call_args.kwargs.get("agent_extra_headers")
     assert headers is not None
-    assert headers == {"Authorization": "Bearer admin-token"}
+    assert headers == {"Authorization": "Bearer admin-token", "X-LiteLLM-User-Id": "u1"}
     assert "authorization" not in headers
 
 

From 90731576e3e970543633fd2bfd2b032a89a42e48 Mon Sep 17 00:00:00 2001
From: yucheng-berri <yucheng@berri.ai>
Date: Tue, 8 Sep 2026 15:58:58 -0700
Subject: [PATCH 26/31] feat(team): let a team admin manage their own team's
 logging callbacks (#37667)

* feat(team): let a team admin manage their own team's logging callbacks

The team callback endpoints already authorize correctly: POST, GET and DELETE
each call _verify_team_access, which admits a proxy admin, an org admin for the
team, or an admin of that team, and 403s everyone else. The route-permission
layer never let a team admin reach them, so it answered 401 naming proxy admin
and the handler's own check was dead code for the caller it was written for.

Adding the two paths to self_managed_routes is how every other team-admin route
works: /team/member_add, /team/member_delete, /team/member_update and
/team/permissions_update all sit in that list and scope per team inside the
handler. The entries use the :path converter the routes are registered with, so
a team id containing a slash resolves the same way at the gate as at the router.

Because any authenticated caller now reaches these handlers, an unknown team had
to stop being distinguishable from one the caller may not manage. All three
handlers looked the team up and raised a distinct 'does not exist' before the
access check, which would have let any valid key probe for team ids. That branch
now returns the same 403 body _verify_team_access raises, and keeps the
diagnosable error for a proxy admin.

disable_logging stays out of the grant. That is a scope decision rather than a
security boundary, since a team admin holding DELETE can clear callbacks one at
a time; it differs only in also clearing the deprecated callback_settings shape.

* fix(team): reach the callback routes for a team id containing a colon

The route gate expands {team_id:path} to "[^:]+" so a colon-suffixed provider
route is not swallowed, which means the two entries added here matched a team
id with a slash but not one with a colon, while the router accepts both.
team_id is a free-form string, so a team whose id contains a colon kept the
old proxy-admin-only denial and its admin could not manage its own callbacks.
List both spellings rather than relaxing the shared matcher, which every
":path" route depends on. The comment claimed the two matchers agree; they do
not, so it now says what each placeholder actually accepts.

* fix(auth): match a :path placeholder the way the router's converter does

A team id may carry a slash, a colon, or both. The gate expanded {x:path}
to "[^:]+", so an id with a colon in it matched no self_managed_routes
entry and its team admin got the proxy-admin-only denial on a route the
router had already resolved for them. Listing a second {x} spelling covered
a colon or a slash but never both.

Expand {x:path} to ".+" instead, except when the template puts a ":"
literal of its own after the placeholder, which is where the narrower form
was earning its keep: the Google routes end in ":generateContent" and
friends, and there the value has to stop before that suffix rather than
swallow it and match a different verb.

That lets self_managed_routes drop back to the two :path spellings the
router itself mounts.

* test(auth): pin that the callback grant reaches no neighbouring team route

The grant is two templates ending in the callback suffix, and the
placeholder now takes slashes and colons. Every other route under
/team/{team_id} registers an ordinary single-segment placeholder, so no
URL the router sends to one of them can end in the callback suffix.

Pin that, so adding a path-converter route beside these fails here
rather than by handing a caller a handler the grant never covered.

* fix(team): make one entry own a credential family end to end

Every stored entry's callback_vars are flattened into one dict before a
request reads them, and that dict is what the exporter authenticates and
addresses with. So an entry naming only a destination is enough to
redirect a credential written somewhere else: a host on a second entry
pairs with the key pair from the first, and the request carries that key
pair to the new host. A team admin cannot read the team's masked Langfuse
secret, but could add such an entry and receive it.

Reject, for writers who are not proxy admins, an entry using a credential
family another entry already holds. Family rather than callback name,
because langfuse and langfuse_otel configure one Langfuse project and
would otherwise redirect each other, and because a destination like
dd_agent_host that no integration registry lists still pairs with the
Datadog credentials beside it.

A proxy admin already holds every credential the proxy has, so the rule
would buy nothing there and would break configs that predate it. A team
admin who does want to move a family deletes the entry holding it first,
which reveals nothing.

* fix(team): let one integration cover both callback events

The family rule compared variable names only, so a team admin who registered
an integration for the success event could not register the same integration,
with the same values, for the failure event.

Compare the values as well: repeating what the owning entry already stores
flattens to the same dict, so there is nothing to redirect. The stored side is
decrypted first, because the credentials are encrypted at rest and ciphertext
never equals the plaintext coming in.

* fix(team): compare the family's values, not its variable names

Comparing per variable rejected a credential written under its other spelling:
langfuse_secret and langfuse_secret_key are one key, so repeating the stored
secret under the other name read as a new value.

Ask instead whether the value is one the owning entries already carry. A
destination the caller controls is by definition not, so the redirect stays
closed, and no alias table has to stay complete for that to hold.

* fix(team): pin the family's configured variables as well as its values

Asking only whether a value is one the family holds let a held variable be
given another of the family's values, so the exporter would address or
authenticate with it.

Keep the value membership rule for a variable the family does not configure
yet, which is what lets one credential go in under its other spelling, and
require a variable it does configure to keep the value it has. Between them no
value the caller chose can enter the family.

* fix(auth): keep a newline in a :path value visible to the route gate

"." stops at a newline and the router's path converter does not, so a %0A
anywhere in a :path segment left the route unmatched here while still reaching
the handler. Every list built on this matcher inherited that: on a proxy with
DISABLE_ADMIN_ENDPOINTS set, DELETE /v1/mcp/server/abc%0Adef reached the MCP
handler instead of the 403 the same request gets without the %0A.

Match with a class that spans newlines.
---
 litellm/proxy/_types.py                       |   8 +
 litellm/proxy/auth/route_checks.py            |  20 +-
 .../callback_config_validation.py             |  85 ++++++++
 .../team_callback_endpoints.py                |  56 +++++-
 .../proxy/auth/test_route_checks.py           | 188 ++++++++++++++++++
 .../test_team_callback_endpoints.py           | 116 +++++++++++
 6 files changed, 459 insertions(+), 14 deletions(-)

diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index 50b87264f3f..1c8608305a2 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -835,6 +835,14 @@ class LiteLLMRoutes(enum.Enum):
         "/team/daily/activity/aggregated",
         "/team/spend/by_user",
         "/team/{team_id}/members/me",
+        # POST/GET the team's logging callbacks, and DELETE one of them. Every
+        # handler calls _verify_team_access, which admits only a proxy admin, an
+        # org admin for the team, or an admin of this team.
+        #
+        # team_id is a free-form string, so it spells these with the same path
+        # converter the router uses; the gate matches that converter.
+        "/team/{team_id:path}/callback",
+        "/team/{team_id:path}/callback/{callback_name}",
         "/model/new",
         "/model/update",
         "/model/delete",
diff --git a/litellm/proxy/auth/route_checks.py b/litellm/proxy/auth/route_checks.py
index 4dba2497bb9..953e3cf3e88 100644
--- a/litellm/proxy/auth/route_checks.py
+++ b/litellm/proxy/auth/route_checks.py
@@ -497,10 +497,22 @@ class RouteChecks:
 
         def _placeholder_to_regex(match: re.Match) -> str:
             placeholder: Final = match.group(0).strip("{}")
-            if placeholder.endswith(":path"):
-                # allow "/" in the placeholder value, but don't eat the route suffix after ":"
-                return r"[^:]+"
-            return r"[^/]+"
+            if not placeholder.endswith(":path"):
+                return r"[^/]+"
+            # A ":path" placeholder takes whatever the router's own path
+            # converter takes, slashes and colons alike, so an id spelled with
+            # either (or both) still matches the template it was mounted under.
+            #
+            # Unless the template puts a ":" literal of its own after the
+            # placeholder: the Google routes end in ":generateContent" and
+            # friends, and there the value has to stop before that suffix
+            # rather than swallow it and match a different verb.
+            #
+            # "[\s\S]" rather than ".", because "." stops at a newline and the
+            # path converter does not: a %0A anywhere in the value would leave
+            # the route unmatched here while still reaching the handler, which
+            # turns this gate into a bypass for the lists built on it.
+            return r"[^:]+" if ":" in match.string[match.end() :] else r"[\s\S]+"
 
         pattern = re.sub(r"\{[^}]+\}", _placeholder_to_regex, pattern)
         # Anchor the pattern to match the entire string
diff --git a/litellm/proxy/common_utils/callback_config_validation.py b/litellm/proxy/common_utils/callback_config_validation.py
index 7ee3bd8d829..c9d97068313 100644
--- a/litellm/proxy/common_utils/callback_config_validation.py
+++ b/litellm/proxy/common_utils/callback_config_validation.py
@@ -44,6 +44,91 @@ def _langfuse_environment_error(callback_vars: Mapping[str, str]) -> str | None:
     return None
 
 
+# Which credential family a dynamic variable belongs to. The families are the
+# integrations that share one account: every langfuse_* variable configures the
+# same Langfuse project whether it rides the classic callback or the OTel one,
+# and every dd_* variable configures the same Datadog account.
+_VAR_FAMILIES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        "arize_": "Arize",
+        "dd_": "Datadog",
+        "gcs_": "GCS",
+        "humanloop_": "Humanloop",
+        "langfuse_": "Langfuse",
+        "langsmith_": "LangSmith",
+        "newrelic_": "New Relic",
+        "posthog_": "PostHog",
+        "wandb_": "Weights & Biases",
+        "weave_": "Weights & Biases",
+    }
+)
+
+
+def _family_of(var: str) -> str | None:
+    """The credential family ``var`` configures, or ``None`` if it configures none.
+
+    ``turn_off_message_logging`` and friends belong to no backend, so they carry
+    no credentials anyone could redirect.
+    """
+    return next((family for prefix, family in _VAR_FAMILIES.items() if var.startswith(prefix)), None)
+
+
+def cross_entry_family_error(
+    callback_vars: Mapping[str, str] | None,
+    stored_vars_by_entry: Sequence[Mapping[str, str]],
+) -> str | None:
+    """Reject an entry that changes what a family another entry holds resolves to.
+
+    Every stored entry's variables are flattened into one dict before a request
+    reads them, and the flattened dict is what the exporter authenticates and
+    addresses with. So an entry naming only a destination is enough to redirect
+    credentials that were written somewhere else: a host on a second entry pairs
+    with the key from the first, and the request carries that key to the new
+    host.
+
+    Two rules together keep the flattened dict out of the caller's hands. A
+    variable the family already configures has to keep the value it has, so
+    nothing already in use can be moved. A variable the family does not yet
+    configure may only carry a value the family already holds, which is what lets
+    the same credential go in under its other spelling (``langfuse_secret`` and
+    ``langfuse_secret_key`` are one key) without anything here having to list the
+    spellings. Between them, no value the caller chose can enter the family, and
+    repeating the family as it stands is still allowed -- that is how one
+    integration gets registered for both the success and the failure event.
+
+    A team admin who does want to move a family deletes the entry holding it
+    first, which reveals nothing.
+
+    Only the writers this endpoint newly admits are held to this, because a proxy
+    admin already holds every credential the proxy has.
+
+    ``stored_vars_by_entry`` has to arrive decrypted; the credential values are
+    encrypted at rest and ciphertext never equals the plaintext coming in.
+    """
+    if not callback_vars:
+        return None
+    stored_by_var: Final = {
+        var: value for entry in stored_vars_by_entry for var, value in entry.items() if _family_of(var) is not None
+    }
+    family_values: Final = frozenset(
+        (family, value)
+        for entry in stored_vars_by_entry
+        for var, value in entry.items()
+        if (family := _family_of(var)) is not None
+    )
+    held_families: Final = frozenset(family for family, _ in family_values)
+    return next(
+        (
+            f"{family} is already configured by another callback entry on this team. "
+            f"Remove that entry before setting {var} here."
+            for var, value, family in ((v, callback_vars[v], _family_of(v)) for v in callback_vars)
+            if family in held_families
+            and (stored_by_var[var] != value if var in stored_by_var else (family, value) not in family_values)
+        ),
+        None,
+    )
+
+
 def logging_metadata_config_error(metadata: Mapping[str, object] | None) -> str | None:
     """Validate every ``logging`` entry of a team/key metadata payload."""
     if not metadata:
diff --git a/litellm/proxy/management_endpoints/team_callback_endpoints.py b/litellm/proxy/management_endpoints/team_callback_endpoints.py
index fe658a13c24..1932e89717b 100644
--- a/litellm/proxy/management_endpoints/team_callback_endpoints.py
+++ b/litellm/proxy/management_endpoints/team_callback_endpoints.py
@@ -20,6 +20,7 @@ from litellm.proxy._types import (
     LiteLLM_AuditLogs,
     LiteLLM_TeamTable,
     LitellmTableNames,
+    LitellmUserRoles,
     ProxyErrorTypes,
     ProxyException,
     TeamCallbackDeleteResponse,
@@ -28,7 +29,10 @@ from litellm.proxy._types import (
     UserAPIKeyAuth,
 )
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
-from litellm.proxy.common_utils.callback_config_validation import callback_config_error
+from litellm.proxy.common_utils.callback_config_validation import (
+    callback_config_error,
+    cross_entry_family_error,
+)
 from litellm.proxy.common_utils.callback_utils import (
     _CALLBACK_VAR_ENCRYPTED_PREFIX,
     decrypt_callback_vars,
@@ -230,6 +234,22 @@ def _callback_error(status_code: int, message: str) -> HTTPException:
     )
 
 
+def _unknown_team_error(team_id: str, user_api_key_dict: UserAPIKeyAuth, status_code: int) -> HTTPException:
+    """Report an unknown team without telling an unauthorized caller that it is unknown.
+
+    These routes are reachable by any authenticated caller so that a team admin can
+    get as far as _verify_team_access. A distinct "does not exist" would therefore let
+    any valid key probe which team ids exist, so a caller who could not have managed
+    the team either way gets the same 403 body _verify_team_access raises.
+    """
+    if user_api_key_dict.user_role == LitellmUserRoles.PROXY_ADMIN:
+        return _callback_error(status_code, f"Team id = {team_id} does not exist.")
+    return HTTPException(
+        status_code=status.HTTP_403_FORBIDDEN,
+        detail="You do not have access to this team",
+    )
+
+
 @router.post(
     "/team/{team_id:path}/callback",
     tags=["team management"],
@@ -304,10 +324,7 @@ async def add_team_callbacks(
         # Check if team_id exists already
         _existing_team = await prisma_client.get_data(team_id=team_id, table_name="team", query_type="find_unique")
         if _existing_team is None:
-            raise HTTPException(
-                status_code=400,
-                detail={"error": f"Team id = {team_id} does not exist. Please use a different team id."},
-            )
+            raise _unknown_team_error(team_id, user_api_key_dict, status.HTTP_400_BAD_REQUEST)
 
         # IDOR guard: only proxy admins / org admins / team admins of THIS
         # team may write callback credentials. Without this, any
@@ -326,6 +343,28 @@ async def add_team_callbacks(
         if team_callback_settings is None or not isinstance(team_callback_settings, list):
             team_callback_settings = []
 
+        # One entry has to own a credential family end to end. The entries are
+        # flattened into one dict before a request reads them, so an entry
+        # naming only a destination would pair with a key written on another
+        # entry and carry it to that destination -- a key a team admin can read
+        # back nowhere. Repeating a value the owning entry already stores is
+        # fine, which is how one integration covers both events. Proxy admins
+        # are exempt: they already hold every credential the proxy has.
+        if user_api_key_dict.user_role != LitellmUserRoles.PROXY_ADMIN:
+            # Decrypted, because the check compares the incoming values against
+            # the stored ones and the credentials are encrypted at rest.
+            decrypted_logging: Final = decrypt_callback_vars(team_metadata).get("logging")
+            stored_entries: Final = decrypted_logging if isinstance(decrypted_logging, list) else ()
+            stored_entry_vars: Final = [  # mutable-ok: read-only input to the check, never stored
+                entry.get("callback_vars") or {} for entry in stored_entries
+            ]
+            family_error: Final = cross_entry_family_error(data.callback_vars, stored_entry_vars)
+            if family_error is not None:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=family_error,
+                )
+
         ## check if it already exists, for the same callback event
         for callback in team_callback_settings:
             if (
@@ -452,7 +491,7 @@ async def delete_team_callback(
             team_id=team_id, table_name="team", query_type="find_unique"
         )
         if _existing_team is None:
-            raise _callback_error(404, f"Team id = {team_id} does not exist.")
+            raise _unknown_team_error(team_id, user_api_key_dict, status.HTTP_404_NOT_FOUND)
 
         # IDOR guard: only proxy admins / org admins / team admins of THIS team may
         # deregister its callbacks, otherwise any authenticated key holder could
@@ -726,10 +765,7 @@ async def get_team_callbacks(
         # Check if team_id exists
         _existing_team = await prisma_client.get_data(team_id=team_id, table_name="team", query_type="find_unique")
         if _existing_team is None:
-            raise HTTPException(
-                status_code=404,
-                detail={"error": f"Team id = {team_id} does not exist."},
-            )
+            raise _unknown_team_error(team_id, user_api_key_dict, status.HTTP_404_NOT_FOUND)
 
         # IDOR guard: callback metadata holds third-party API credentials
         # (Langfuse / Langsmith / GCS). Only proxy admins / org admins /
diff --git a/tests/test_litellm/proxy/auth/test_route_checks.py b/tests/test_litellm/proxy/auth/test_route_checks.py
index 5b15d4a7d5e..0fd19f518d9 100644
--- a/tests/test_litellm/proxy/auth/test_route_checks.py
+++ b/tests/test_litellm/proxy/auth/test_route_checks.py
@@ -3638,3 +3638,191 @@ def test_agent_registry_route_gate_open_to_non_admin_roles(user_role, method, ro
         valid_token=valid_token,
         request_data={},
     )
+TEAM_CALLBACK_ROUTES = (
+    "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/callback",
+    "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/callback/langfuse",
+    # the routes register team_id with the :path converter, so a team id may
+    # contain a slash
+    "/team/tenant/06bda574/callback",
+    "/team/tenant/06bda574/callback/langfuse",
+    # team_id is a free-form string, so it may also contain a colon
+    "/team/tenant:06bda574/callback",
+    "/team/tenant:06bda574/callback/langfuse",
+    # or both, which is the shape neither a "[^:]+" nor a "[^/]+" expansion
+    # of the placeholder reaches on its own
+    "/team/tenant:acme/prod/callback",
+    "/team/tenant:acme/prod/callback/langfuse",
+)
+
+
+def _gate(route, role) -> str:
+    """Drive the real route gate for a non-proxy-admin caller.
+
+    Reports "allowed" when the gate lets the request through to its handler, and
+    the denial message otherwise, so a caller asserts the verdict as a value
+    instead of on whether an exception escaped.
+    """
+    user_obj = LiteLLM_UserTable(
+        user_id="team_admin_user",
+        user_email="team-admin@example.com",
+        user_role=role,
+    )
+    request = MagicMock(spec=Request)
+    request.query_params = {}
+    try:
+        RouteChecks.non_proxy_admin_allowed_routes_check(
+            user_obj=user_obj,
+            _user_role=role,
+            route=route,
+            request=request,
+            valid_token=UserAPIKeyAuth(user_id="team_admin_user", user_role=role),
+            request_data={},
+        )
+    except Exception as exc:
+        return f"denied: {exc}"
+    return "allowed"
+
+
+def test_team_callback_routes_are_self_managed():
+    """The grant has to come from self_managed_routes specifically.
+
+    That list is the one whose entries carry no role predicate, so the handler
+    decides. Granting the same paths through internal_user_routes instead would
+    look identical for an internal_user while silently denying the org admins and
+    view-only roles that list does not cover.
+    """
+    for template in (
+        "/team/{team_id:path}/callback",
+        "/team/{team_id:path}/callback/{callback_name}",
+    ):
+        assert template in LiteLLMRoutes.self_managed_routes.value
+
+
+@pytest.mark.parametrize("route", TEAM_CALLBACK_ROUTES)
+@pytest.mark.parametrize(
+    "role",
+    [
+        LitellmUserRoles.INTERNAL_USER.value,
+        LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value,
+        LitellmUserRoles.ORG_ADMIN.value,
+    ],
+)
+def test_team_callback_routes_reach_their_handler_for_non_admins(route, role):
+    """A team admin manages their own team's logging callbacks, so the route gate
+    must let a non-proxy-admin through to the handler.
+
+    The handler is what authorizes: every team callback endpoint calls
+    _verify_team_access, which admits only a proxy admin, an org admin for the
+    team, or an admin of that team, and 403s everyone else. Before this, the gate
+    rejected the team admin with a 401 naming proxy admin, so the handler's own
+    check was unreachable for them.
+    """
+    assert _gate(route, role) == "allowed"
+
+
+@pytest.mark.parametrize(
+    "pattern, route, matches",
+    [
+        # a :path placeholder takes what the router's path converter takes
+        ("/team/{team_id:path}/callback", "/team/plain/callback", True),
+        ("/team/{team_id:path}/callback", "/team/tenant/acme/callback", True),
+        ("/team/{team_id:path}/callback", "/team/tenant:acme/callback", True),
+        ("/team/{team_id:path}/callback", "/team/tenant:acme/prod/callback", True),
+        # and still has to reach the template's own suffix
+        ("/team/{team_id:path}/callback", "/team/tenant:acme/disable_logging", False),
+        # a template with a ":" literal after the placeholder keeps the suffix
+        (
+            "/v1beta/models/{model_name:path}:generateContent",
+            "/v1beta/models/gemini-2.5-flash:generateContent",
+            True,
+        ),
+        (
+            "/v1beta/models/{model_name:path}:generateContent",
+            "/v1beta/models/publishers/google/gemini-2.5-flash:generateContent",
+            True,
+        ),
+        # the value must not swallow that suffix and match a different verb
+        (
+            "/v1beta/models/{model_name:path}:generateContent",
+            "/v1beta/models/gemini-2.5-flash:countTokens",
+            False,
+        ),
+        # a %0A in the value reaches the handler through the path converter, so
+        # the gate has to see it too or DISABLE_ADMIN_ENDPOINTS is bypassable
+        ("/v1/mcp/server/{path:path}", "/v1/mcp/server/abc\ndef", True),
+        ("/team/{team_id:path}/callback", "/team/ten\nant/callback", True),
+        ("/v1beta/models/{model_name:path}:generateContent", "/v1beta/models/gem\nini:generateContent", True),
+        # an ordinary placeholder stays one segment
+        ("/team/{team_id}/members/me", "/team/abc/members/me", True),
+        ("/team/{team_id}/members/me", "/team/tenant/abc/members/me", False),
+        ("/team/{team_id}/members/me", "/team/ab\nc/members/me", True),
+    ],
+)
+def test_path_placeholder_matches_what_the_router_accepts(pattern, route, matches):
+    """The gate's placeholder expansion has to agree with the router's.
+
+    A team id may carry a slash, a colon, or both, and the router mounted these
+    paths with the same :path converter, so an id the router routes must not be
+    an id the gate fails to recognize. The one narrowing that stays is a template
+    whose own suffix begins with a colon: there the value stops before it, or
+    ":generateContent" would also match a ":countTokens" request.
+    """
+    assert RouteChecks._route_matches_pattern(route=route, pattern=pattern) is matches
+
+
+# Every other route the proxy mounts under /team/{team_id}, spelled the way it
+# is registered. None of them takes a path converter, so none can be reached by
+# a URL that ends in the callback suffix.
+PROTECTED_TEAM_ROUTES = (
+    "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112",
+    "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/disable_logging",
+    "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/members/me",
+    "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/member/u-1/reset_spend",
+    # the same routes with the callback suffix spliced in, which is the shape a
+    # caller would craft to make a protected route look self-managed
+    "/team/06bda574/callback/disable_logging/x",
+    "/team/06bda574/callback/member/u-1/reset_spend",
+    "/team/06bda574/callback/members/me",
+)
+
+
+@pytest.mark.parametrize("route", PROTECTED_TEAM_ROUTES)
+def test_the_callback_grant_does_not_reach_another_team_route(route):
+    """Widening the callback templates must not hand out any neighbouring route.
+
+    The grant is two templates ending in the callback suffix. Every other team
+    route registers an ordinary single-segment placeholder, so no URL the router
+    sends to one of them can end in "/callback" or "/callback/<name>" -- and the
+    gate must agree, or a crafted team id would carry a caller into a handler
+    the grant never covered.
+    """
+    for template in (
+        "/team/{team_id:path}/callback",
+        "/team/{team_id:path}/callback/{callback_name}",
+    ):
+        assert RouteChecks._route_matches_pattern(route=route, pattern=template) is False
+
+
+def test_team_disable_logging_stays_proxy_admin_only():
+    """disable_logging was left out of the grant, so it must still be rejected at
+    the gate. It is the one team callback route a team admin cannot reach."""
+    verdict = _gate(
+        "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/disable_logging",
+        LitellmUserRoles.INTERNAL_USER.value,
+    )
+
+    assert "Only proxy admin" in verdict
+    assert "disable_logging" in verdict
+
+
+@pytest.mark.parametrize(
+    "route",
+    [
+        "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112",
+        "/team/update",
+        "/team/06bda574-5ca9-43d3-beb8-3b23c2f17112/model/add",
+    ],
+)
+def test_neighbouring_team_routes_stay_closed(route):
+    """The grant is the callback paths and nothing else on the team namespace."""
+    assert "Only proxy admin" in _gate(route, LitellmUserRoles.INTERNAL_USER.value)
diff --git a/tests/test_litellm/proxy/management_endpoints/test_team_callback_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_team_callback_endpoints.py
index 08e931e6405..bdc12dad4bc 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_team_callback_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_team_callback_endpoints.py
@@ -19,6 +19,7 @@ from litellm.proxy._types import (
     LitellmUserRoles,
     UserAPIKeyAuth,
 )
+from litellm.proxy.common_utils.callback_config_validation import cross_entry_family_error
 from litellm.proxy.management_endpoints.team_callback_endpoints import (
     add_team_callbacks,
     delete_team_callback,
@@ -1443,3 +1444,118 @@ async def test_delete_team_callback_route_accepts_team_ids_containing_slashes():
     assert response.json()["data"]["success_callbacks"] == ["langsmith"]
     written = json.loads(mock_prisma.db.litellm_teamtable.update.await_args.kwargs["data"]["metadata"])
     assert [entry["callback_name"] for entry in written["logging"]] == ["langsmith"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "call_handler",
+    [
+        lambda caller: add_team_callbacks(
+            data=AddTeamCallback(
+                callback_name="langfuse",
+                callback_type="success",
+                callback_vars={"langfuse_public_key": "pk", "langfuse_secret_key": "sk"},
+            ),
+            http_request=Mock(spec=Request),
+            team_id="team-does-not-exist",
+            user_api_key_dict=caller,
+        ),
+        lambda caller: get_team_callbacks(
+            http_request=Mock(spec=Request),
+            team_id="team-does-not-exist",
+            user_api_key_dict=caller,
+        ),
+        lambda caller: delete_team_callback(
+            http_request=Mock(spec=Request),
+            team_id="team-does-not-exist",
+            callback_name="langfuse",
+            user_api_key_dict=caller,
+        ),
+    ],
+    ids=["add", "get", "delete"],
+)
+async def test_unknown_team_is_indistinguishable_from_no_access(call_handler, unauthorized_caller):
+    """An unauthorized caller must not learn whether a team id exists.
+
+    These routes are reachable by any authenticated caller so a team admin can get
+    as far as the access check, so a distinct "does not exist" would turn them into
+    a probe for valid team ids. The unknown-team response has to match the
+    no-access one exactly, status and body.
+    """
+    with patch("litellm.proxy.proxy_server.prisma_client") as mock_client:  # test-quality-ok: the handler imports prisma_client from proxy_server at call time, so there is no seam to inject through
+        mock_client.get_data = AsyncMock(return_value=None)
+        with pytest.raises(HTTPException) as unknown_team:
+            await call_handler(unauthorized_caller)
+
+    with patch("litellm.proxy.proxy_server.prisma_client") as mock_client:  # test-quality-ok: the handler imports prisma_client from proxy_server at call time, so there is no seam to inject through
+        mock_client.get_data = AsyncMock(return_value=_team_row())
+        mock_client.db.litellm_teamtable.update = AsyncMock()
+        with patch(  # test-quality-ok: _verify_team_access calls this module-level helper directly, so there is no seam to inject through
+            "litellm.proxy.management_endpoints.team_endpoints._is_user_org_admin_for_team",
+            new_callable=AsyncMock,
+            return_value=False,
+        ):
+            with pytest.raises(HTTPException) as no_access:
+                await call_handler(unauthorized_caller)
+
+    assert unknown_team.value.status_code == no_access.value.status_code == 403
+    assert unknown_team.value.detail == no_access.value.detail
+    assert "does not exist" not in str(unknown_team.value.detail)
+
+
+@pytest.mark.asyncio
+async def test_proxy_admin_still_told_the_team_is_unknown():
+    """The masking is only for callers who could not have managed the team; a proxy
+    admin keeps the diagnosable error."""
+    admin = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin", api_key="sk-admin")
+    with patch("litellm.proxy.proxy_server.prisma_client") as mock_client:  # test-quality-ok: the handler imports prisma_client from proxy_server at call time, so there is no seam to inject through
+        mock_client.get_data = AsyncMock(return_value=None)
+        with pytest.raises(HTTPException) as exc:
+            await get_team_callbacks(
+                http_request=Mock(spec=Request),
+                team_id="team-does-not-exist",
+                user_api_key_dict=admin,
+            )
+
+    assert exc.value.status_code == 404
+    assert "does not exist" in str(exc.value.detail)
+
+
+@pytest.mark.parametrize(
+    "new_vars, stored, rejected",
+    [
+        # the redirect, in every carrier a caller could pick: an entry naming
+        # only a host, pairing with a key pair written on another entry
+        ({"langfuse_host": "http://attacker.invalid"}, [{"langfuse_public_key": "pk", "langfuse_secret_key": "sk"}], True),
+        # the sibling carrier -- langfuse and langfuse_otel are one account
+        ({"langfuse_host": "http://attacker.invalid"}, [{"langfuse_host": "https://us.cloud.langfuse.com", "langfuse_secret_key": "sk"}], True),
+        # a destination variable no integration registry lists
+        ({"dd_agent_host": "attacker.invalid"}, [{"dd_api_key": "k", "dd_site": "us5.datadoghq.com"}], True),
+        # one entry owning its family end to end is the feature
+        ({"langfuse_host": "https://eu.cloud.langfuse.com", "langfuse_public_key": "pk", "langfuse_secret_key": "sk"}, [], False),
+        # a different family alongside an existing one stays fine
+        ({"gcs_bucket_name": "bucket"}, [{"langfuse_public_key": "pk", "langfuse_secret_key": "sk"}], False),
+        ({"langsmith_api_key": "k"}, [{"dd_api_key": "k"}], False),
+        # variables that configure no backend carry nothing to redirect
+        ({"turn_off_message_logging": "true"}, [{"langfuse_secret_key": "sk"}], False),
+        # the same integration registered for a second event: identical values
+        # flatten to the identical dict, so there is nothing to redirect
+        ({"langfuse_host": "https://us.cloud.langfuse.com", "langfuse_public_key": "pk", "langfuse_secret_key": "sk"}, [{"langfuse_host": "https://us.cloud.langfuse.com", "langfuse_public_key": "pk", "langfuse_secret_key": "sk"}], False),
+        # the same credential under its other spelling is the same credential
+        ({"langfuse_secret": "sk"}, [{"langfuse_public_key": "pk", "langfuse_secret_key": "sk"}], False),
+        # a value the family already holds cannot be moved into another of its
+        # variables either; the exporter would address or authenticate with it
+        ({"langfuse_host": "pk"}, [{"langfuse_host": "https://us.cloud.langfuse.com", "langfuse_public_key": "pk"}], True),
+        # the same shape with one value moved is the redirect again
+        ({"langfuse_host": "http://attacker.invalid", "langfuse_public_key": "pk", "langfuse_secret_key": "sk"}, [{"langfuse_host": "https://us.cloud.langfuse.com", "langfuse_public_key": "pk", "langfuse_secret_key": "sk"}], True),
+    ],
+)
+def test_one_entry_owns_a_credential_family(new_vars, stored, rejected):
+    """A team admin must not be able to redirect a credential they cannot read.
+
+    The stored entries are flattened into one dict before a request reads them,
+    so an entry naming only a destination pairs with a key written elsewhere and
+    carries it to that destination.
+    """
+    error = cross_entry_family_error(new_vars, stored)
+    assert (error is not None) is rejected

From bc8305810ff9bd465f464a7efd0abbaae46e3250 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 8 Sep 2026 16:03:34 -0700
Subject: [PATCH 27/31] fix(ui): align SDK mocks and remaining dependency
 patches

---
 ui/litellm-dashboard/package-lock.json        | 298 ++++++++++--------
 ui/litellm-dashboard/package.json             |   4 +-
 .../llm_calls/anthropic_messages.test.tsx     |   4 +-
 .../llm_calls/audio_speech.test.tsx           |  14 +-
 .../llm_calls/audio_transcriptions.test.tsx   |  14 +-
 .../llm_calls/chat_completion.test.tsx        |   4 +-
 .../llm_calls/responses_api.test.tsx          |   4 +-
 7 files changed, 200 insertions(+), 142 deletions(-)

diff --git a/ui/litellm-dashboard/package-lock.json b/ui/litellm-dashboard/package-lock.json
index d920205d203..44360e94392 100644
--- a/ui/litellm-dashboard/package-lock.json
+++ b/ui/litellm-dashboard/package-lock.json
@@ -680,9 +680,9 @@
       }
     },
     "node_modules/@emnapi/runtime": {
-      "version": "1.11.2",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.2.tgz",
-      "integrity": "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==",
+      "version": "1.11.3",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
+      "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1452,9 +1452,9 @@
       }
     },
     "node_modules/@img/sharp-darwin-arm64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.3.tgz",
-      "integrity": "sha512-RMnFX7YQsMoh7lWfcM4NEHHymBX/rLuKNPVM84XE9ONPcaSCDgE7CHIHpSgPcO2xcRthgBy1HfNO319mwhIAkg==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.4.tgz",
+      "integrity": "sha512-Uhfl4V4lhP2nbUVF9+hyH1+luj86f1gUFeo8ALYxFoULoU+G87D43BfeMP8XHsk9boxAnCY/bf2EHwhA7MuGsA==",
       "cpu": [
         "arm64"
       ],
@@ -1470,13 +1470,13 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-darwin-arm64": "1.3.2"
+        "@img/sharp-libvips-darwin-arm64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-darwin-x64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.3.tgz",
-      "integrity": "sha512-Xo+5uFBtLN0BKqieTxiFzFPQAUlBbbH5iBKyRX/z1JrbnYsHTfKJnUfL8+p2TPXr1pXqao4eeL4Rl144uDpK9w==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.4.tgz",
+      "integrity": "sha512-hWniXY3bG5qKpkKrAwPe4y+VTPmf086YQAnkxWh7uA1YrlRouWGa0M0Mxj3ZjnXFkv7/TD1bTy9lGUK26vRvWw==",
       "cpu": [
         "x64"
       ],
@@ -1492,20 +1492,20 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-darwin-x64": "1.3.2"
+        "@img/sharp-libvips-darwin-x64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-freebsd-wasm32": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.3.tgz",
-      "integrity": "sha512-lUxcqWIj2wMQ9BrwNjngcr1gWUr5xgaGThBRqPPalIC2n67Cqj1uPh8NnA/ZhAg8hUbKl+kVHKwgUIwe6ZYPrg==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.4.tgz",
+      "integrity": "sha512-lIsKw/BU+kjB4eZjxrYrZmwOJYi3Ajrv66iAlBmUPyKc3HpnloevB1g3wxGD9P/5BbQ1brBGl65VRRrCvQDEqA==",
       "license": "Apache-2.0",
       "optional": true,
       "os": [
         "freebsd"
       ],
       "dependencies": {
-        "@img/sharp-wasm32": "0.35.3"
+        "@img/sharp-wasm32": "0.35.4"
       },
       "engines": {
         "node": ">=20.9.0"
@@ -1515,9 +1515,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-darwin-arm64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.2.tgz",
-      "integrity": "sha512-9J6ypZFpQBj4YnePGoq/S38w6nz+vqg5WZLrLGY4YuSemdMq47GMLBPO42MzwdGwpg/agZ7xzZcFHa48xlywfg==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.3.tgz",
+      "integrity": "sha512-suTBPTDGrI9WodccaDdwZItTSaBYASlBk1NSfElSHrUfzu3szG6lvIF58+WiFvnfzuK8ZBFS5zE00PxqxnRiPg==",
       "cpu": [
         "arm64"
       ],
@@ -1531,9 +1531,9 @@
       }
     },
     "node_modules/@img/sharp-libvips-darwin-x64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.2.tgz",
-      "integrity": "sha512-m2pW1n6cns9VaubNwsZ+c3CRYjxNQWgJ5gPlnL1nbBcpkBvFm6SCFN5o0psFHI8w9n11NKhFkeEDns98tiqbEw==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.3.tgz",
+      "integrity": "sha512-FVJZ5mITMobmXIz/hPDTw0EintTW5H3WfrxwLqEqjiIihlu+hVRyGrFQ60xl0Lxn7Bt3zdpevPaQi0HEzqz9fw==",
       "cpu": [
         "x64"
       ],
@@ -1547,12 +1547,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-arm": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.2.tgz",
-      "integrity": "sha512-1eMLzy92I4J6rmi4mAT8yC3HxOtniyGELlzGbNMLLeqe052ahFQ0h6LFq+lh5DsDIdYViIDst08abvSbcEdLXQ==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.3.tgz",
+      "integrity": "sha512-3rbU4vqXXc3hY/OiXdl52xZvT0F1yEngWfvqudtPJg/KkyiaQw2DRsFrNzpmLvfavbwOq3qXn36GP8obHRULQA==",
       "cpu": [
         "arm"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1563,12 +1566,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-arm64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.2.tgz",
-      "integrity": "sha512-dqVSFynCox4C/J8kT16V7SIFAns0IjgLwkvYT7p8LQVmJ5OS5b6tI9IGflxTeuBS//zXeFIUbwt5dwxyZ17cnA==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.3.tgz",
+      "integrity": "sha512-0DaL0A6Xu6sQSQFwe4iVCrKWU2cCTItnRsYsCdxAMm9NF6twAA9BKnoqy4hqz4+azQ0JHuA26qiUKsf1XJ/v5A==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1579,12 +1585,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-ppc64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.2.tgz",
-      "integrity": "sha512-3z0NHDxD6n5I9gc05U1eW1AyRm+Gznzq3naMrthPNqE6oYykcogW0l/jfpJdjYnuNl8R7yI9pNbE1XiUeyq0Aw==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.3.tgz",
+      "integrity": "sha512-cdn1OvUBwsXhbC0zSzJnNzf5MZ/mTrobawDvNXBTxe8VtqKAm0sRuEY2Evzovb/w9JMk4TvRxqt1mekSuJz64w==",
       "cpu": [
         "ppc64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1595,12 +1604,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-riscv64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.2.tgz",
-      "integrity": "sha512-bsb4rI+NldGOsXuej2r8OdSS8+zXDVaCWxyWrcv6kneTOlgAHtZABRzBBCwdsPiD90J4myNJuHpg6kA20ImW/w==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.3.tgz",
+      "integrity": "sha512-HjPVx7yKz+0lqdhDlTw1tt90wamBoxhiXpvl1XZpJLiHH4RCJ5yDTqH+VlYPv2fwFs89JFw4c1IexYOcQUi4IQ==",
       "cpu": [
         "riscv64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1611,12 +1623,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-s390x": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.2.tgz",
-      "integrity": "sha512-/ABshyj8gCpyIrNXnHn4LorDJ0HHm1VhXPBlxZ8zAtfVPAaSafXPGn+sUSIRiwaSBy0mmFjSjiXI5mkcwdChKQ==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.3.tgz",
+      "integrity": "sha512-neWLh+3yCNThxnfy3c4BbVBeGgt9aftno+XbT56iK28RgeDs3UOFWviLWlUu0bArYVYJaFDK+RRohbicUNCm8Q==",
       "cpu": [
         "s390x"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1627,12 +1642,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linux-x64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.2.tgz",
-      "integrity": "sha512-ITPEtgffGJ0S6G9dRyw/366tJQqFRcHWPHhC+Stpg3Z8AEMrDrTr2lhdz4f/Y/HMbRh//7Z5mBzEpVdi62Oc3w==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.3.tgz",
+      "integrity": "sha512-4vKmvAst9nrowcqquKFAyZJUDolUaIp8uRiN0mWFguJ1IplC9/pitXtlnnlU4aa/eJw3J7i67V+pwUL+wZGdsA==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1643,12 +1661,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.2.tgz",
-      "integrity": "sha512-zE9EdiUzUmg5mDT5a1rk5fYJ6GWPloTwWBYDS14naqHsL+EaMpDj1AWnpLgh3u0YCORv2Tt50wrcrpYqkP97Kw==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.3.tgz",
+      "integrity": "sha512-Y9kQaLMuNoB0bPYOOdcZMaseNrFpPodIWWMrx+CZyydf2xn68j9WYc6sWWRrDwNkzCQjKYfc68L7jKjGlHMibw==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1659,12 +1680,15 @@
       }
     },
     "node_modules/@img/sharp-libvips-linuxmusl-x64": {
-      "version": "1.3.2",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.2.tgz",
-      "integrity": "sha512-m0lrLiUt+lBYnCFr8qV/65yMR4E/c7/wf78I5eKTdkEakFAlZ9QlzEM3QIhhAwVeUhLAHLcCq7a7Vszq/oFNZQ==",
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.3.tgz",
+      "integrity": "sha512-fj8Mv0HHfD1Rr+4I68+3agJynxDWtBFgicTbSOb9Bke6pIwzGcJ+RX/yHjmiEGFMCavY/dxvem7MyNaJF+wDiw==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1675,12 +1699,15 @@
       }
     },
     "node_modules/@img/sharp-linux-arm": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.3.tgz",
-      "integrity": "sha512-affVWCTLooy8TSxbDx2qkzuDeaWLNVBA+P//FNBirHsXpP2fuBhk5AuboYUnrDnzoXes8GFjpTx0SBFOCRg+FA==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.4.tgz",
+      "integrity": "sha512-7OAS8gI0EReKGVN2HssHlM6umJgxF5VI3xN0p9FA91p/YO+ou5hiNghLdZ5BEHztwaaK5+bLKRf8x/o2L2nk9A==",
       "cpu": [
         "arm"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1693,16 +1720,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-arm": "1.3.2"
+        "@img/sharp-libvips-linux-arm": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linux-arm64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.3.tgz",
-      "integrity": "sha512-QgKDspHPnrU+GQ55XPhGwyhC8acLVOOSyAvo1oVfFmrIXLkDNmGWzAfDZ4xK8oSA1qBQrALcHX0G5UZni/SuFQ==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.4.tgz",
+      "integrity": "sha512-De4jpEnAU8Hd5oT0j1G3uL4ZvTuipVMn7YC6vPaJhy6/7EwEae0SVAoBrUMYQbkLGDm85taVWwuPc1a44LTzCQ==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1715,16 +1745,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-arm64": "1.3.2"
+        "@img/sharp-libvips-linux-arm64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linux-ppc64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.3.tgz",
-      "integrity": "sha512-sMd8rDxmpLOwv/7N44klFjOD5DUO7FLdjiXDI0hoxYaf7Ar262dQIEkosE98bps+5HPLtp/EvNqeqQtOycP/IA==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.4.tgz",
+      "integrity": "sha512-2oYZJeIl4kCcMGk4ouZVjnkCtFrpQFlNEtJ6GbxzhHQchwH0NH/qEb9ykmOl29dqwMq+JhFdZn+1ak2FKhI9fQ==",
       "cpu": [
         "ppc64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1737,16 +1770,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-ppc64": "1.3.2"
+        "@img/sharp-libvips-linux-ppc64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linux-riscv64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.3.tgz",
-      "integrity": "sha512-0Eob78yjlYPfL5vMNWAW55l3R9Y6BQS/gOfe0ZcP9mEz9ohhKSt4im1hayiknXgf8AWrFqMvJcKIdmLmEe7yeQ==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.4.tgz",
+      "integrity": "sha512-cPbNChoRURAWdebDIHSenxRpgEdy7JkPydSnUxRm9VvKD7m0/xVaR/8Fzlu81pk5nHEvHH87UZUA7cTtwnbJSA==",
       "cpu": [
         "riscv64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1759,16 +1795,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-riscv64": "1.3.2"
+        "@img/sharp-libvips-linux-riscv64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linux-s390x": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.3.tgz",
-      "integrity": "sha512-KgAxQ0DxpNOq1rG2t5cgTgShJFGSuU7XO45cqC+1NVOuZnP6tlgZRuSYOfNupGkHID0o3cJOsw4DVeJpMovcGw==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.4.tgz",
+      "integrity": "sha512-RY0JFY8Fd6RonCBtHz+DvadaPkXDSI1AUn6yWL9TipqkZ1vY8w8evqdgyDFnkm4/K1ve1TvZiaePP5oSd4+WVQ==",
       "cpu": [
         "s390x"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1781,16 +1820,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-s390x": "1.3.2"
+        "@img/sharp-libvips-linux-s390x": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linux-x64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.3.tgz",
-      "integrity": "sha512-8pqvxubL2PGdhlPy6GLqzDYMUjyRmKAwKHYKixpdJYBUK7PJ0C029XdsnpFIdgRZG68fZiGdHVWcKPvtiPB4cA==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.4.tgz",
+      "integrity": "sha512-9qvvEAuk8k89TfWUoX2htWjbAMX8p+NxCppjpcg5k6xMsjhBQPTsoIh36h9Qde4WRuGpJeYnOjdosDn/cnv+OA==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1803,16 +1845,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linux-x64": "1.3.2"
+        "@img/sharp-libvips-linux-x64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linuxmusl-arm64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.3.tgz",
-      "integrity": "sha512-Vz0iQjzzcSX3HCbfwFfCSG/9SCIqyO0mH2sXyiHaAYfBk0cRsCWXRyQYX0ovCK/PAQBbTzQ0dsPQHh5MAFL59w==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.4.tgz",
+      "integrity": "sha512-KB5jxpfWQTr0nc3xdHtWChdbifHrBGsd2SM62Eyxrl8afikm+f5qGBU75SJIZBT/S1MC8XyacdlXBMSWq6OURA==",
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1825,16 +1870,19 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linuxmusl-arm64": "1.3.2"
+        "@img/sharp-libvips-linuxmusl-arm64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-linuxmusl-x64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.3.tgz",
-      "integrity": "sha512-6O1NPKcDVj9QEdg7Hx549EX8U0rp6yXQERqru6yRN7fGBn32UvIRJUlWnk+8xDCiG76hXVBbX82NZ/ZKr0euIg==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.4.tgz",
+      "integrity": "sha512-f+eZJZIQNEEd26RPSW+76chwOf1XtA2Y/O+5ocVyLliHkeih3e+jhLVBdNTd2rS3IbNXK8+ug93Vf5ZXtF5Lxg==",
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1847,17 +1895,17 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-libvips-linuxmusl-x64": "1.3.2"
+        "@img/sharp-libvips-linuxmusl-x64": "1.3.3"
       }
     },
     "node_modules/@img/sharp-wasm32": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.3.tgz",
-      "integrity": "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.4.tgz",
+      "integrity": "sha512-zQnl4Kwp7Q6NHsENtU2T/00Zi+w3AQNwz3+UaTyVBy2FpXrzXzGjndpK61onhZjRtRpQXxCTeqw19bVyXOh7jA==",
       "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
       "optional": true,
       "dependencies": {
-        "@emnapi/runtime": "^1.11.1"
+        "@emnapi/runtime": "^1.11.3"
       },
       "engines": {
         "node": ">=20.9.0"
@@ -1867,16 +1915,16 @@
       }
     },
     "node_modules/@img/sharp-webcontainers-wasm32": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.3.tgz",
-      "integrity": "sha512-2rnq7bX3NzeR2T4YWgz8qiG4h3TSdMe+vN1iQXpJleSJ3SM5zQ8Fy2SyyXAWlbxpEZ2Y+Z4u1BePgJEYbSy80Q==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.4.tgz",
+      "integrity": "sha512-ESfNkywmCfPNyaZjxooddJQiQ+l/nTpGEOGthxiLnIHXC/CmcBixnfwUleX9mCz9ovrUUvKMap/pm8RYbzfwaA==",
       "cpu": [
         "wasm32"
       ],
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
-        "@img/sharp-wasm32": "0.35.3"
+        "@img/sharp-wasm32": "0.35.4"
       },
       "engines": {
         "node": ">=20.9.0"
@@ -1886,9 +1934,9 @@
       }
     },
     "node_modules/@img/sharp-win32-arm64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.3.tgz",
-      "integrity": "sha512-4bPwFdMbeC4JQ8L8LOyWp6nsHcboP5fxkp6iPOXz2Vg49R42TuMs2whkJ5OAP4/Ul035qOzy0AecOF9VOscn4w==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.4.tgz",
+      "integrity": "sha512-iNdlBX9gLVvqe2I3uIJSIKTq6wckP/DYxZtcqxm09x5Gi24DnFBmPAWZmr60ZyYMG0xlzo6goG3670ar+RXvRw==",
       "cpu": [
         "arm64"
       ],
@@ -1905,9 +1953,9 @@
       }
     },
     "node_modules/@img/sharp-win32-ia32": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.3.tgz",
-      "integrity": "sha512-r53mXsBN6lFUDiST764SvgwUdHAqM4rPAiDzAmf4fLoB6X/rkfyTrLCg6+g17wJJiCmB3JYgHuUldCWUIRFSXw==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.4.tgz",
+      "integrity": "sha512-kqRsbaa5CS6KHlpxnN7WhE6vAAugXyZButpRdvDWetlv6Qv4N9WTcrWzF7tXfB9T7MsoadqdI8hmwLq6UlLvtw==",
       "cpu": [
         "ia32"
       ],
@@ -1924,9 +1972,9 @@
       }
     },
     "node_modules/@img/sharp-win32-x64": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.3.tgz",
-      "integrity": "sha512-D4y1vNeZrIIJCN+uHaWVtH86B+aCrdMYYjicy9pXHvbGZeGYLLSd3wdVuC37FxVXlU1ARsk84eKWfWMXGYEqvA==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.4.tgz",
+      "integrity": "sha512-XtmnYhBcrORsJ4XJngyzr/EWP0hRZLAZRFaApdKuviyqF78+ylxh2y06ZmtULAMOnObJ3ucpN0AcwSWnMowTRg==",
       "cpu": [
         "x64"
       ],
@@ -7930,9 +7978,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
-      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
       "dev": true,
       "funding": [
         {
@@ -11183,9 +11231,9 @@
       }
     },
     "node_modules/sharp": {
-      "version": "0.35.3",
-      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.3.tgz",
-      "integrity": "sha512-ej0zVHuZGHCiABXcNxeYhpRnPNPAcvbG8RMdBAhDAxLKkCRVSpK3Iyu7qbqw3JMzoj0REeM6f3tJLtVwl0023Q==",
+      "version": "0.35.4",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.4.tgz",
+      "integrity": "sha512-n++8XWcj+jCOr2IOl7h8LbKnGBDY4aPbmprMONBNFdn0ImXqpGVv5zliDs0V9HbmbCQLpbuo2ej9rAoOQTvMDA==",
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
@@ -11200,31 +11248,31 @@
         "url": "https://opencollective.com/libvips"
       },
       "optionalDependencies": {
-        "@img/sharp-darwin-arm64": "0.35.3",
-        "@img/sharp-darwin-x64": "0.35.3",
-        "@img/sharp-freebsd-wasm32": "0.35.3",
-        "@img/sharp-libvips-darwin-arm64": "1.3.2",
-        "@img/sharp-libvips-darwin-x64": "1.3.2",
-        "@img/sharp-libvips-linux-arm": "1.3.2",
-        "@img/sharp-libvips-linux-arm64": "1.3.2",
-        "@img/sharp-libvips-linux-ppc64": "1.3.2",
-        "@img/sharp-libvips-linux-riscv64": "1.3.2",
-        "@img/sharp-libvips-linux-s390x": "1.3.2",
-        "@img/sharp-libvips-linux-x64": "1.3.2",
-        "@img/sharp-libvips-linuxmusl-arm64": "1.3.2",
-        "@img/sharp-libvips-linuxmusl-x64": "1.3.2",
-        "@img/sharp-linux-arm": "0.35.3",
-        "@img/sharp-linux-arm64": "0.35.3",
-        "@img/sharp-linux-ppc64": "0.35.3",
-        "@img/sharp-linux-riscv64": "0.35.3",
-        "@img/sharp-linux-s390x": "0.35.3",
-        "@img/sharp-linux-x64": "0.35.3",
-        "@img/sharp-linuxmusl-arm64": "0.35.3",
-        "@img/sharp-linuxmusl-x64": "0.35.3",
-        "@img/sharp-webcontainers-wasm32": "0.35.3",
-        "@img/sharp-win32-arm64": "0.35.3",
-        "@img/sharp-win32-ia32": "0.35.3",
-        "@img/sharp-win32-x64": "0.35.3"
+        "@img/sharp-darwin-arm64": "0.35.4",
+        "@img/sharp-darwin-x64": "0.35.4",
+        "@img/sharp-freebsd-wasm32": "0.35.4",
+        "@img/sharp-libvips-darwin-arm64": "1.3.3",
+        "@img/sharp-libvips-darwin-x64": "1.3.3",
+        "@img/sharp-libvips-linux-arm": "1.3.3",
+        "@img/sharp-libvips-linux-arm64": "1.3.3",
+        "@img/sharp-libvips-linux-ppc64": "1.3.3",
+        "@img/sharp-libvips-linux-riscv64": "1.3.3",
+        "@img/sharp-libvips-linux-s390x": "1.3.3",
+        "@img/sharp-libvips-linux-x64": "1.3.3",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.3.3",
+        "@img/sharp-libvips-linuxmusl-x64": "1.3.3",
+        "@img/sharp-linux-arm": "0.35.4",
+        "@img/sharp-linux-arm64": "0.35.4",
+        "@img/sharp-linux-ppc64": "0.35.4",
+        "@img/sharp-linux-riscv64": "0.35.4",
+        "@img/sharp-linux-s390x": "0.35.4",
+        "@img/sharp-linux-x64": "0.35.4",
+        "@img/sharp-linuxmusl-arm64": "0.35.4",
+        "@img/sharp-linuxmusl-x64": "0.35.4",
+        "@img/sharp-webcontainers-wasm32": "0.35.4",
+        "@img/sharp-win32-arm64": "0.35.4",
+        "@img/sharp-win32-ia32": "0.35.4",
+        "@img/sharp-win32-x64": "0.35.4"
       },
       "peerDependenciesMeta": {
         "@types/node": {
diff --git a/ui/litellm-dashboard/package.json b/ui/litellm-dashboard/package.json
index 5dd70dff4fe..9786d5c1d6e 100644
--- a/ui/litellm-dashboard/package.json
+++ b/ui/litellm-dashboard/package.json
@@ -96,7 +96,7 @@
   },
   "overrides": {
     "prismjs": "1.30.0",
-    "js-yaml": "4.3.1",
+    "js-yaml": "4.3.2",
     "brace-expansion": "5.0.9",
     "glob": "13.0.0",
     "minimatch": "10.2.4",
@@ -105,7 +105,7 @@
     "axios": "1.13.6",
     "postcss": "8.5.23",
     "esbuild": "0.28.1",
-    "sharp": "^0.35.0"
+    "sharp": "^0.35.4"
   },
   "engines": {
     "node": ">=24.14.1",
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/anthropic_messages.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/anthropic_messages.test.tsx
index 995104d4b7f..96ace129f87 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/anthropic_messages.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/anthropic_messages.test.tsx
@@ -9,7 +9,9 @@ vi.mock("@/components/networking", () => ({
 const mockMessagesStream = vi.fn();
 
 vi.mock("@anthropic-ai/sdk", () => ({
-  default: vi.fn(() => ({ messages: { stream: mockMessagesStream } })),
+  default: vi.fn(function () {
+    return { messages: { stream: mockMessagesStream } };
+  }),
 }));
 
 describe("anthropic_messages prompt cache usage", () => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_speech.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_speech.test.tsx
index dbfe8a39959..17f5d0f28a4 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_speech.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_speech.test.tsx
@@ -20,13 +20,15 @@ describe("audio_speech", () => {
     });
 
     // Mock the OpenAI constructor and its methods
-    (OpenAI as any).mockImplementation(() => ({
-      audio: {
-        speech: {
-          create: mockCreate,
+    (OpenAI as any).mockImplementation(function () {
+      return {
+        audio: {
+          speech: {
+            create: mockCreate,
+          },
         },
-      },
-    }));
+      };
+    });
   });
 
   afterEach(() => {
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_transcriptions.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_transcriptions.test.tsx
index 65b11e7f7d8..52561e5d42e 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_transcriptions.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/playground/llm_calls/audio_transcriptions.test.tsx
@@ -16,13 +16,15 @@ describe("audio_transcription", () => {
     });
 
     // Mock the OpenAI constructor and its methods
-    (OpenAI as any).mockImplementation(() => ({
-      audio: {
-        transcriptions: {
-          create: mockCreate,
+    (OpenAI as any).mockImplementation(function () {
+      return {
+        audio: {
+          transcriptions: {
+            create: mockCreate,
+          },
         },
-      },
-    }));
+      };
+    });
   });
 
   afterEach(() => {
diff --git a/ui/litellm-dashboard/src/components/llm_calls/chat_completion.test.tsx b/ui/litellm-dashboard/src/components/llm_calls/chat_completion.test.tsx
index bc4b4e3a351..08b02cacb21 100644
--- a/ui/litellm-dashboard/src/components/llm_calls/chat_completion.test.tsx
+++ b/ui/litellm-dashboard/src/components/llm_calls/chat_completion.test.tsx
@@ -20,7 +20,9 @@ const mockClient = {
 
 vi.mock("openai", () => ({
   default: {
-    OpenAI: vi.fn(() => mockClient),
+    OpenAI: vi.fn(function () {
+      return mockClient;
+    }),
   },
 }));
 
diff --git a/ui/litellm-dashboard/src/components/llm_calls/responses_api.test.tsx b/ui/litellm-dashboard/src/components/llm_calls/responses_api.test.tsx
index 0b94c093acd..ae5e224cfbf 100644
--- a/ui/litellm-dashboard/src/components/llm_calls/responses_api.test.tsx
+++ b/ui/litellm-dashboard/src/components/llm_calls/responses_api.test.tsx
@@ -16,7 +16,9 @@ const mockClient = {
 
 vi.mock("openai", () => ({
   default: {
-    OpenAI: vi.fn(() => mockClient),
+    OpenAI: vi.fn(function () {
+      return mockClient;
+    }),
   },
 }));
 

From d75176f14a9df30cbb93c3075475981c5a3e3c1b Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 8 Sep 2026 16:13:58 -0700
Subject: [PATCH 28/31] test(ui): align workflow expectations with Vitest 4

---
 tests/test_litellm/test_select_ui_test_scope.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_litellm/test_select_ui_test_scope.py b/tests/test_litellm/test_select_ui_test_scope.py
index c395e07bc79..bc11fb495aa 100644
--- a/tests/test_litellm/test_select_ui_test_scope.py
+++ b/tests/test_litellm/test_select_ui_test_scope.py
@@ -29,7 +29,7 @@ SCOPE_SCRIPT = REPO_ROOT / ".github" / "scripts" / "select_ui_test_scope.sh"
 WORKFLOW = REPO_ROOT / ".github" / "workflows" / "test-litellm-ui-unit.yml"
 STEP_NAME = "Run UI unit tests (Vitest)"
 
-FULL_SUITE_ARGV = ["run", "test", "--", "--run", "--pool", "forks", "--poolOptions.forks.maxForks=14"]
+FULL_SUITE_ARGV = ["run", "test", "--", "--run", "--pool", "forks", "--maxWorkers=14"]
 
 NON_SRC_FILES = [
     "package.json",
@@ -135,7 +135,7 @@ def _related_argv(changed: list[str]) -> list[str]:
         "--passWithNoTests",
         "--pool",
         "forks",
-        "--poolOptions.forks.maxForks=14",
+        "--maxWorkers=14",
     ]
 
 

From b624fd8c4f30eb15b0e55ccf410640806297784a Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 16:18:06 -0700
Subject: [PATCH 29/31] fix(mlflow): prevent _stream_id_to_span leak and mlflow
 2.x end_trace TypeError (#39049)

---
 litellm/integrations/mlflow.py                | 28 ++++----
 .../test_litellm/integrations/test_mlflow.py  | 67 +++++++++++++++++++
 2 files changed, 81 insertions(+), 14 deletions(-)

diff --git a/litellm/integrations/mlflow.py b/litellm/integrations/mlflow.py
index a2f0b7cf39c..8731e96440f 100644
--- a/litellm/integrations/mlflow.py
+++ b/litellm/integrations/mlflow.py
@@ -133,17 +133,17 @@ class MlflowLogger(CustomLogger):
         if final_response:
             end_time_ns: Final = int(end_time.timestamp() * 1e9)
 
-            self._extract_and_set_chat_attributes(span, kwargs, final_response)
-            self._end_span_or_trace(
-                span=span,
-                outputs=final_response,
-                status=SpanStatusCode.OK,
-                end_time_ns=end_time_ns,
-            )
-
-            # Remove the stream_id from the map
-            with self._lock:
-                self._stream_id_to_span.pop(litellm_call_id)
+            try:
+                self._extract_and_set_chat_attributes(span, kwargs, final_response)
+                self._end_span_or_trace(
+                    span=span,
+                    outputs=final_response,
+                    status=SpanStatusCode.OK,
+                    end_time_ns=end_time_ns,
+                )
+            finally:
+                with self._lock:
+                    self._stream_id_to_span.pop(litellm_call_id, None)
 
     def _add_chunk_events(self, span, response_obj):
         from mlflow.entities import SpanEvent
@@ -282,15 +282,15 @@ class MlflowLogger(CustomLogger):
         """End an MLflow span or a trace."""
         if span.parent_id is None:
             self._client.end_trace(
-                trace_id=span.request_id,
+                span.request_id,
                 outputs=outputs,
                 status=status,
                 end_time_ns=end_time_ns,
             )
         else:
             self._client.end_span(
-                trace_id=span.request_id,
-                span_id=span.span_id,
+                span.request_id,
+                span.span_id,
                 outputs=outputs,
                 status=status,
                 end_time_ns=end_time_ns,
diff --git a/tests/test_litellm/integrations/test_mlflow.py b/tests/test_litellm/integrations/test_mlflow.py
index 61010f8531c..f828c34a9ff 100644
--- a/tests/test_litellm/integrations/test_mlflow.py
+++ b/tests/test_litellm/integrations/test_mlflow.py
@@ -195,3 +195,70 @@ def test_mlflow_stream_handler_uses_async_complete_response():
             is final_response
         )
         assert "abc123" not in mlflow_logger._stream_id_to_span
+
+
+def test_mlflow_stream_handler_pops_span_when_end_raises():
+    modules = _mock_mlflow_modules()
+    with patch.dict("sys.modules", modules):
+        from litellm.integrations.mlflow import MlflowLogger
+
+        mlflow_logger = MlflowLogger()
+        mlflow_logger._start_span_or_trace = MagicMock(return_value="mock_span")
+        mlflow_logger._end_span_or_trace = MagicMock(
+            side_effect=TypeError("unexpected keyword argument 'trace_id'")
+        )
+        mlflow_logger._extract_and_set_chat_attributes = MagicMock()
+
+        response_obj = MagicMock()
+        response_obj.choices = []
+
+        kwargs = {
+            "litellm_call_id": "leak123",
+            "complete_streaming_response": MagicMock(),
+        }
+
+        with pytest.raises(TypeError):
+            mlflow_logger._handle_stream_event(
+                kwargs=kwargs,
+                response_obj=response_obj,
+                start_time=datetime.utcnow(),
+                end_time=datetime.utcnow(),
+            )
+
+        assert "leak123" not in mlflow_logger._stream_id_to_span
+
+
+class _Mlflow2StyleClient:
+    """Mimics the mlflow 2.x client signatures, which have no trace_id kwarg."""
+
+    def __init__(self):
+        self.ended_traces = []
+        self.ended_spans = []
+
+    def end_trace(self, request_id, outputs=None, attributes=None, status="OK", end_time_ns=None):
+        self.ended_traces.append(request_id)
+
+    def end_span(self, request_id, span_id, outputs=None, attributes=None, status="OK", end_time_ns=None):
+        self.ended_spans.append((request_id, span_id))
+
+
+def test_mlflow_end_span_or_trace_works_with_mlflow_2x_client():
+    modules = _mock_mlflow_modules()
+    with patch.dict("sys.modules", modules):
+        from litellm.integrations.mlflow import MlflowLogger
+
+        mlflow_logger = MlflowLogger()
+        client = _Mlflow2StyleClient()
+        mlflow_logger._client = client
+
+        root_span = MagicMock(parent_id=None, request_id="req-1")
+        mlflow_logger._end_span_or_trace(
+            span=root_span, outputs="out", end_time_ns=1, status="OK"
+        )
+        assert client.ended_traces == ["req-1"]
+
+        child_span = MagicMock(parent_id="parent-1", request_id="req-2", span_id="span-2")
+        mlflow_logger._end_span_or_trace(
+            span=child_span, outputs="out", end_time_ns=1, status="OK"
+        )
+        assert client.ended_spans == [("req-2", "span-2")]

From 3165951e6d0b795290ddb18453984a14bff9bf5c Mon Sep 17 00:00:00 2001
From: yucheng-berri <yucheng@berri.ai>
Date: Tue, 8 Sep 2026 16:23:21 -0700
Subject: [PATCH 30/31] feat(otel v2): send a key's or team's whole trace to
 its own destination (#39654)

* feat(otel v2): send a key's or team's whole trace to its own destination

A key or team that configures its own Langfuse, Arize, Weave or New Relic
credentials used to get a single detached span in its account while the rest of
the request trace stayed on the operator's backend, so neither side held a
complete trace. Resolve the destination during auth, forward every span of the
request to it, and hold the same request back from the operator's exporter for
that backend, so the tenant gets the tree the operator would have seen and the
operator gets nothing for that request.

Also let a credential-mandatory preset build without the operator's own env
credentials. Without that, a proxy whose teams each bring their own account fell
back to the legacy integration and never ran a line of the v2 path.

* fix(otel v2): validate tenant destinations and match each backend's own endpoint

Review round on the tenant destination routing.

- A key/team Langfuse host is user-supplied input, so it goes through the
  proxy's SSRF guard. A private address is refused, the operator keeps the
  trace, and the warning names user_url_allowed_hosts. The operator's own
  LANGFUSE_HOST is not checked.
- Arize and Weave destinations now resolve their endpoint and transport
  through the backend's own config, so an ARIZE_HTTP_ENDPOINT collector and
  a self-hosted WANDB_HOST are honoured instead of the cloud default.
- A half-configured backend no longer resolves: several dynamic header
  builders gate each credential separately, so an api key with no space id
  produced a non-empty but unusable header set that suppressed the
  operator's exporter.
- A callback_type of "failure" no longer takes over the trace. The
  destination is resolved during auth, before the outcome is known.
- The fan-out cache evicts without shutting the processor down, matching
  ArizePhoenixLogger: a concurrent on_end may still hold it.
- The stdout placeholder is identified by what it does rather than by
  equality with an import-time default, so an operator's OTEL_EXPORTER_OTLP_*
  collector survives the credential-less path.

* refactor(otel v2): reuse the proxy's own destination allowlist for tenant hosts

A tenant-supplied Langfuse host is the same threat as a URL-valued `model`, so
it now goes through `is_url_destination_allowed_by_host` against
`provider_url_destination_allowed_hosts` instead of a second, DNS-based check
of its own. The DNS lookup would have blocked the asyncio auth path on a
hostname the caller picked, and its cached verdicts could blackhole a real host
after one resolver blip.

Evicting a destination processor now retires it to drain rather than shutting it
down, since `on_end` hands a processor back and exports outside the lock. The
retirees are capped so they cannot accumulate a thread each.

`credential_gated_exporters` tells the synthesized stdout placeholder from a
real exporter by transport rather than by the literal kind `console`, so an
unrecognized kind is not mistaken for a configured collector, and an exporter
the operator did configure survives. That also stops a weave test's env writes
from making this look like a real OTLP exporter later in the same CI worker.

* fix(otel v2): read the tenant's stored callback config the way the sibling parser does

Three divergences between the destination resolver and
`convert_key_logging_metadata_to_callback`, which read the same stored config:

- A key whose callbacks are disabled stores an empty list, and `or` treated that
  as "the key configured nothing", so the request inherited the team's
  destination. The sibling parser treats an empty list as configured.
- Two entries naming one backend now merge their `callback_vars` last-wins,
  matching the sibling, instead of the resolver taking the first entry and the
  per-request tracer routing taking the last.
- `credential_gated_exporters` dropped any exporter whose kind had no transport,
  which also dropped an `in_memory` exporter the operator asked for. The
  placeholder is the spec with every field still at its default, so that is what
  the predicate now says.

Arize's `allow_missing_credentials` branch was unreachable: `get_arize_config`
resolves every credential with `os.environ.get` and always supplies an endpoint,
so it never raises. Dropped it and corrected the protocol docstring.

* fix(otel v2): keep the destination merge immutable

The per-backend var merge seeded a plain dict and the gated exporter list a plain
list, both of which the LIT budget counts. Wrap the merge in MappingProxyType and
hand the exporters back as a tuple.

* fix(otel v2): scope the fan-out to its own backend and close shed processors off the export path

Three problems in the fan-out, two of them in the eviction added last round:

- Every v2 logger carries its own provider and emits its own copy of a gen-AI
  span, so a proxy running two of them handed the tenant the same model call
  twice. A provider now forwards only destinations for the backend it speaks
  for; the tenant's own backend always has a logger, since naming it in the key
  or team config is what builds one. Reproduced live against a self-hosted
  Langfuse on an arize-only proxy and on the bare `otel` callback.
- Eviction could close a processor another thread was still exporting through,
  which drops that span. Exports are now counted, and a retired processor is
  closed only once its count reaches zero.
- That close ran inside `on_end`, where `shutdown` flushes over the network, so
  one unreachable tenant collector stalled every other tenant's spans. It now
  runs on a short-lived thread, which also retires the retiree cap: a retiree
  drains as soon as its export finishes.

* fix(otel v2): deliver tenant destinations from the published global provider

Scoping the fan-out by callback name in the previous commit left every backend
that is not the canonical logger with a one-span trace: only the published
global provider sees the FastAPI server span, the auth span and the post-call
database spans, so an arize-only proxy handed a team's Langfuse just the model
call. Attach the fan-out once, to that provider, and let it forward every
destination.

An overridden backend now skips per-request tracer routing outright rather than
only clearing its credential headers, since a key or team otel_service_name was
still enough to detach the model call onto a second provider. The destination
carries that service name as a resource attribute instead.

Shed processors drain on a two-thread pool rather than a thread each, so a
tenant cycling its destination config cannot spawn threads as fast as it sends
requests.

* fix(otel v2): drain shed destination processors on daemon workers

A ThreadPoolExecutor joins its workers at interpreter exit, so one unreachable
tenant collector would hold the whole proxy open for its export timeout on the
way down. Two long-lived daemon workers off a queue keep the thread count
bounded without blocking shutdown.

* fix(otel v2): give the fan-out its own drain pool instead of a lazy singleton

functools.lru_cache does not hold a lock across the call it caches, so
concurrent first evictions each finish building a queue and start its
workers, and every queue but the winner is abandoned with two daemon
threads blocked on it forever.

* fix(otel v2): close no destination processor under a span still in flight

The fan-out now refuses new work once shutdown starts and waits out the
spans already being forwarded, so teardown neither drops a trace mid-forward
nor hands the next caller an exporter nothing will ever close. The wait is
bounded so a dead collector cannot hold the proxy open.

* fix(otel v2): retire the drain workers with the fan-out that started them

A proxy that rebuilds its telemetry builds another fan-out, so workers that
outlive the one that started them are two more threads per reload. Shutdown
now retires them once everything queued is closed, and a processor shed
afterwards is closed inline rather than queued to nobody.

* fix(otel v2): guard the fan-out's closed state with the lock that gates it

An Event read on its own leaves room for shutdown to run in the gap. A cache
miss then inserted a live exporter into a map that had been cleared, and a
shed processor landed behind sentinels every drain worker had exited on.
The drain pool takes its queue by injection so both interleavings are
reachable from a test without patching.

* feat(otel v2): let a tenant destination export alongside the operator's own

Override stays the default: a key or team destination replaces the operator's
exporter for that backend. Operators running one org-wide backend across every
team set litellm_settings.otel_tenant_destination_mode to additive, and the
same trace lands in both places. A team that names the operator's own project
is still written once, since the fan-out skips a destination the operator's
exporter is already sending that span to.

* fix(otel v2): let a straggling export close its own destination processor

Shutdown waits out the exports in flight, but the wait has to be bounded or a
tenant collector that stops answering holds the proxy open on the way down.
Past the bound it closed everything anyway, which is the case it was written to
avoid: a processor closed under the span it is carrying loses that span.

Keep the bound and retire the stragglers instead. The thread still exporting one
closes it through the drain as soon as its export returns, so teardown stays
bounded and no span is dropped mid-forward.

* fix(otel v2): identify a destination account by its credentials, not its header names

Under additive the fan-out skips a destination the operator's own exporter
already writes to, so the same account is not written twice. It compared header
names as well as values, and one account answers to more than one spelling:
the operator's Arize exporter sends space_id where a team destination sends
arize-space-id, so every span landed in the operator's own space twice.

The credentials are the identity. Compare those and leave the spelling to each
backend.

* fix(otel v2): keep the credential's role in a destination's account identity

Comparing values alone folds two accounts together whenever they hold the same
strings in different roles, and the second team would then get no trace at all.
Compare the credential under a normalized name instead, and fold the one alias
that actually exists: Arize's space_id and arize-space-id.

* fix(otel v2): build one destination processor per destination, not per racing span

Building outside the cache lock meant a cold cache met by a burst of concurrent
requests constructed an exporter per thread, kept one, and handed the rest to the
drain, so a batch worker and a connection pool per losing thread sat in a queue
two workers service.

Build under the lock that reads the cache. Opening an exporter connects to
nothing, so the lock is held for a constructor, once per destination, and the
race it was avoiding stops existing.

* fix(otel v2): bound the teardown that closes a destination, not the one that never blocks

The five-second bound guarded the wait for spans still inside on_end, but a
batching processor's on_end only queues the span and returns, so that counter is
empty and the bound engaged against nothing. The blocking half was the serial
close, which flushes over the network and joins the SDK's own worker thread with
no timeout of its own, so a single tenant collector that answers and never
finishes held process teardown open for as long as it liked.

Hand every close to the drain, whose workers are daemons, and give the whole
teardown one deadline.

* fix(otel v2): preserve operator spans on destination failure

* fix(otel v2): anchor destinations off the published provider, refuse headerless tenant transports

set_tracer_provider keeps the first provider it is handed, so a process whose
OTel global was claimed before the proxy published (auto-instrumentation, a
legacy logger) had no fan-out on the global and auth anchored no destination.
Auth now reads the fan-out off the registered logger's own provider.

A destination whose protocol maps to a headerless exporter kind is no longer
buildable: the console fallback would drop the tenant's credentials and print
the spans to stdout while the operator's exporter stood down for them.

* fix(otel): anchor tenant fan-out to the published provider

A legacy v1 logger can occupy proxy_server.open_telemetry_logger, in which case
the proxy publishes with registered=None and the fan-out lands on a v2 logger
taken from _in_memory_loggers. Reading the registered slot found no v2 logger
and the OTel global belonged to v1, so auth refused every tenant destination.

* fix(otel): preserve registered provider fallback

* test(otel): cover pre-publish provider fallback

* fix(otel): attach fan-out on fallback provider

* fix(otel): serialize first fan-out attach

* fix(otel): keep the operator's database endpoint out of tenant traces

A database span forwarded to a key or team destination carried the proxy's own
Postgres host, port and schema, and on failure the Prisma error text naming them.
The fan-out now hands tenants a view of each database span without those keys,
its events or its status text, while the operator's own copy is untouched and
model endpoints such as server.address on the LLM span still travel

* fix(otel): keep relabelled spans in the fan-out and honour disabled callbacks for destinations

A key or team otel_service_name used to move a backend's span onto a second
provider even when another backend had a destination, so the fan-out never saw
the model call and the tenant's trace lost it. A service name alone now stays on
the published provider whenever the request has a destination; credential and
project routing to a tenant's own account is unchanged

Destinations now skip a backend the request disabled dynamically, reading the
x-litellm-disable-callbacks header and the key's litellm_disabled_callbacks with
the same precedence and premium gate dispatch applies, so a disabled backend is
neither delivered to nor withheld from the operator

* test(otel): project routing survives a sibling backend destination

* docs(otel): state why a disabled backend still routes its own span

* fix(otel): keep a degraded backend's spans off a collector another v2 logger already serves

* test(otel): a credentialed preset beside another v2 logger keeps every exporter

* fix(otel): keep credentialless fallback on base path

* test(otel): cover legacy callback carrier rejection

* fix(otel): preserve valid exporter beside gated preset

* fix(otel): avoid console export without operator destination

* refactor(otel): share the console placeholder check with the presets

* fix(otel): bound shed destination processors waiting on a dead collector

* fix(otel): preserve explicit console exporters

* fix(otel): avoid mutable field-set construction

* fix(otel): close drain saturation race

* fix(otel): drop captured request headers from tenant spans

* test(otel v2): give the newrelic dispatch tests operator credentials, since a credential-less preset now falls back

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix(otel): rebuild an anchored destination's processor past drain saturation

A destination deliverable() accepted at auth can be evicted by other tenants' auths
before its request's spans end, and that eviction is what tips the drain over. The
saturation gate then refused the rebuild at on_end, and with the operator's exporter
already stood down for that backend the span went nowhere. The gate now applies only
while a request decides whether to anchor

* fix(otel): hold destination eviction while the drain is saturated

An anchored destination evicted by other tenants' auths is rebuilt on its
next span, and that rebuild evicted another anchored one, so with more
destinations in flight than the cache holds every span cost one more
processor, one more batch thread and one more close queued behind a collector
that never answers. Eviction now holds while the drain is saturated, so the
cache keeps one entry per destination in flight and trims back to its cap on
the next hit or build once the drain has room

* fix(otel): keep the proxy's own error text out of tenant traces

A tenant destination received every span the request produced, error text
included, so a Prisma failure during auth handed a team admin's collector the
operator's Postgres endpoint, and the exception event on any failed span carried
a stack trace naming the proxy's install paths.

Spans the tenant's own call produced (the model call, MCP, guardrails) keep their
error text. Every other span keeps the failure without the prose: its type, its
provider error code and its status code, with the message, the events and the
status description dropped. Stack traces come off every span, attribute and event
alike.

A destination's resource attributes now merge onto the span's resource instead of
rebuilding one per span, which was re-running resource detection on every export.

* fix(otel): redact tenant URL query parameters

* fix(otel): close final tenant routing gaps

* fix(otel): refresh destinations for stateful MCP messages

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/__init__.py                           |    3 +
 litellm/integrations/otel/logger.py           |   55 +-
 litellm/integrations/otel/mappers/legacy.py   |    3 +-
 litellm/integrations/otel/model/config.py     |    6 +-
 .../integrations/otel/model/destination.py    |   49 +
 litellm/integrations/otel/model/semconv.py    |    3 +
 litellm/integrations/otel/plumbing/context.py |   68 +-
 .../integrations/otel/plumbing/providers.py   |  690 ++++-
 litellm/integrations/otel/plumbing/routing.py |   16 +-
 litellm/integrations/otel/presets/agentops.py |    1 +
 litellm/integrations/otel/presets/arize.py    |    6 +-
 litellm/integrations/otel/presets/base.py     |   14 +-
 .../integrations/otel/presets/destinations.py |  152 +
 litellm/integrations/otel/presets/langfuse.py |   23 +-
 .../integrations/otel/presets/langtrace.py    |    1 +
 litellm/integrations/otel/presets/levo.py     |    1 +
 litellm/integrations/otel/presets/newrelic.py |    1 +
 litellm/integrations/otel/presets/phoenix.py  |    1 +
 litellm/integrations/otel/presets/utils.py    |   31 +
 litellm/integrations/otel/presets/weave.py    |   21 +-
 litellm/integrations/weave/weave_otel.py      |   20 +-
 litellm/litellm_core_utils/litellm_logging.py |   57 +-
 .../proxy/_experimental/mcp_server/server.py  |   66 +-
 litellm/proxy/auth/user_api_key_auth.py       |   38 +
 litellm/proxy/litellm_pre_call_utils.py       |  140 +
 .../otel/test_otel_v2_destinations.py         | 2719 +++++++++++++++++
 .../integrations/otel/test_otel_v2_logger.py  |    4 +-
 .../test_litellm_logging.py                   |    9 +-
 .../mcp_server/test_mcp_server.py             |   69 +
 29 files changed, 4214 insertions(+), 53 deletions(-)
 create mode 100644 litellm/integrations/otel/model/destination.py
 create mode 100644 litellm/integrations/otel/presets/destinations.py
 create mode 100644 tests/test_litellm/integrations/otel/test_otel_v2_destinations.py

diff --git a/litellm/__init__.py b/litellm/__init__.py
index fc6dc35fe55..ede8a73453d 100644
--- a/litellm/__init__.py
+++ b/litellm/__init__.py
@@ -326,6 +326,9 @@ ssl_certificate: Optional[str] = None
 user_url_validation: bool = True
 user_url_allowed_hosts: List[str] = []
 provider_url_destination_allowed_hosts: List[str] = []
+#: "override" (default) or "additive": whether a key or team destination replaces
+#: the operator's exporter for that backend or exports alongside it.
+otel_tenant_destination_mode: str | None = None
 ssl_ecdh_curve: Optional[str] = None  # Set to 'X25519' to disable PQC and improve performance
 disable_streaming_logging: bool = False
 disable_token_counter: bool = False
diff --git a/litellm/integrations/otel/logger.py b/litellm/integrations/otel/logger.py
index 5519896a961..630aa313dc9 100644
--- a/litellm/integrations/otel/logger.py
+++ b/litellm/integrations/otel/logger.py
@@ -16,9 +16,11 @@ from opentelemetry.trace import (
     Span,
     Tracer,
     get_current_span,
+    get_tracer_provider,
     set_span_in_context,
     use_span,
 )
+from opentelemetry.trace import TracerProvider as ApiTracerProvider
 
 import litellm
 from litellm._logging import verbose_logger
@@ -63,6 +65,7 @@ from litellm.integrations.otel.plumbing.metrics import (
     create_genai_metrics,
 )
 from litellm.integrations.otel.plumbing.providers import (
+    attach_tenant_fan_out,
     build_tracer_provider,
     get_event_logger,
     get_meter,
@@ -85,6 +88,7 @@ if TYPE_CHECKING:
     )
 
 LITELLM_TRACER_NAME: Final = "litellm"
+_published_v2_provider: ApiTracerProvider | None = None
 
 
 def _span_error_from_exception(
@@ -180,7 +184,9 @@ class OpenTelemetryV2(CustomLogger):
         self.config: OpenTelemetryV2Config = config or OpenTelemetryV2Config(**kwargs)
         self.callback_name = callback_name
         self._tracer_provider: TracerProvider = (
-            tracer_provider if tracer_provider is not None else build_tracer_provider(self.config)
+            tracer_provider
+            if tracer_provider is not None
+            else build_tracer_provider(self.config, tenant_overrides=True)
         )
         self.tracer: Tracer = get_tracer(self._tracer_provider, LITELLM_TRACER_NAME)
         self._metrics_recorder = self._init_metrics(meter_provider)
@@ -195,6 +201,11 @@ class OpenTelemetryV2(CustomLogger):
         self._open_llm_calls: OrderedDict[str, _LLMCallSpan] = OrderedDict()
         self._init_otel_logger_on_litellm_proxy()
 
+    @property
+    def tracer_provider(self) -> TracerProvider:
+        """The provider this logger emits through, read-only to its callers."""
+        return self._tracer_provider
+
     def _init_metrics(self, meter_provider: "MeterProvider | None") -> "GenAIMetricRecorder | None":
         """Create the six GenAI histograms when metrics are enabled, else ``None``.
 
@@ -863,12 +874,33 @@ def publish_global_otel_v2_provider(
     ``opentelemetry.trace.set_tracer_provider``) are injected so the publish step is
     unit-testable without reading or mutating real global OTel state. Returns the
     logger whose provider was published.
+
+    The published provider is also the one that fans spans out to key/team
+    destinations, because it is the only provider the whole request tree passes
+    through; see :func:`attach_tenant_fan_out`. It is remembered for
+    :func:`fan_out_provider` because neither the OTel global (``set_tracer_provider``
+    keeps the first provider it was ever handed) nor
+    ``proxy_server.open_telemetry_logger`` (a legacy v1 logger can hold that slot)
+    reliably leads back to it.
     """
+    global _published_v2_provider
     logger: Final = select_global_otel_v2_logger(in_memory_loggers, registered=registered)
-    set_global_provider(logger._tracer_provider)
+    attach_tenant_fan_out(logger.tracer_provider, *_v2_configs(in_memory_loggers, logger))
+    set_global_provider(logger.tracer_provider)
+    _published_v2_provider = logger.tracer_provider  # rebind-ok: startup records the one provider carrying the fan-out
     return logger
 
 
+def _v2_configs(in_memory_loggers: Sequence[object], logger: "OpenTelemetryV2") -> tuple[OpenTelemetryV2Config, ...]:
+    """Every v2 logger's config, the published logger's first.
+
+    Each preset keeps its own provider and exporters, so the accounts the operator
+    writes to are spread over all of them, not held by the published logger alone.
+    """
+    others: Final = tuple(cb.config for cb in in_memory_loggers if isinstance(cb, OpenTelemetryV2) and cb is not logger)
+    return (logger.config, *others)
+
+
 def _registered_v2_logger() -> "OpenTelemetryV2 | None":
     try:
         from litellm.proxy import proxy_server
@@ -904,6 +936,25 @@ def seed_request_identity(user_api_key_dict: object, model: str | None = None) -
         logger.seed_request_identity(user_api_key_dict, model=model)
 
 
+def fan_out_provider() -> ApiTracerProvider:
+    """The provider :func:`publish_global_otel_v2_provider` gave the tenant fan-out.
+
+    Read off the publish itself, not the OTel global and not the registered logger:
+    the global keeps whichever provider claimed it first (auto-instrumentation, a
+    legacy logger), and the registered slot can hold a v1 logger while the publish
+    picked a v2 one from ``_in_memory_loggers``. Either detour lands on a provider
+    with no fan-out and drops every destination at auth.
+    """
+    published: Final = _published_v2_provider
+    if published is not None:
+        return published
+    logger: Final = _registered_v2_logger()
+    if logger is not None:
+        attach_tenant_fan_out(logger.tracer_provider, logger.config)
+        return logger.tracer_provider
+    return get_tracer_provider()
+
+
 @contextmanager
 def phase_span(name: str) -> "Iterator[Span | None]":
     logger: Final = _registered_v2_logger()
diff --git a/litellm/integrations/otel/mappers/legacy.py b/litellm/integrations/otel/mappers/legacy.py
index 37475acb8f7..d25c25cd127 100644
--- a/litellm/integrations/otel/mappers/legacy.py
+++ b/litellm/integrations/otel/mappers/legacy.py
@@ -23,6 +23,7 @@ from litellm.integrations.otel.model.payloads import (
     ServiceSpanData,
     ToolDefinition,
 )
+from litellm.integrations.otel.model.semconv import Error
 
 # Attribute keys in the semconv-ai / Traceloop vocabulary.
 _LEGACY_SYSTEM: Final = "gen_ai.system"
@@ -36,7 +37,7 @@ _LEGACY_PRESENCE_PENALTY: Final = "llm.presence_penalty"
 _LEGACY_STOP_SEQUENCES: Final = "llm.chat.stop_sequences"
 _LEGACY_SERVICE: Final = "service"
 _LEGACY_CALL_TYPE: Final = "call_type"
-_LEGACY_ERROR: Final = "error"
+_LEGACY_ERROR: Final = Error.MESSAGE_LEGACY
 
 
 class LegacyMapper:
diff --git a/litellm/integrations/otel/model/config.py b/litellm/integrations/otel/model/config.py
index 422c8409411..bd542ddc20c 100644
--- a/litellm/integrations/otel/model/config.py
+++ b/litellm/integrations/otel/model/config.py
@@ -269,7 +269,9 @@ class OpenTelemetryV2Config(BaseSettings):
         if (self.endpoint or self.traces_endpoint) and self.exporter == "console":
             self.exporter = "otlp_http"
         # When no explicit destinations are given, fold the single-destination
-        # shorthand into one spec so the provider always has a destination.
+        # shorthand into one spec so the provider always has a destination. A spec
+        # with no fields set is how the presets tell "nothing configured" from an
+        # operator who asked for the console by name.
         if not self.exporters:
             self.exporters = [
                 ExporterSpec(
@@ -278,6 +280,8 @@ class OpenTelemetryV2Config(BaseSettings):
                     traces_endpoint=self.traces_endpoint,
                     headers=self.headers,
                 )
+                if not self.model_fields_set.isdisjoint(("exporter", "endpoint", "headers"))
+                else ExporterSpec()
             ]
         # Ensure ``genai`` is always present and first.
         names = list(self.mapper_names)
diff --git a/litellm/integrations/otel/model/destination.py b/litellm/integrations/otel/model/destination.py
new file mode 100644
index 00000000000..299253cac77
--- /dev/null
+++ b/litellm/integrations/otel/model/destination.py
@@ -0,0 +1,49 @@
+"""The resolved OTLP destination a request's traces export to.
+
+Backend-agnostic on purpose: every OTEL backend reduces to an endpoint plus auth
+headers. The per-backend field mapping lives in ``presets.destinations``.
+"""
+
+from collections.abc import Mapping
+from typing import Final
+from urllib.parse import quote
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OtelDestination(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    endpoint: str
+    headers: Mapping[str, str] = Field(default_factory=dict)
+    resource_attributes: Mapping[str, str] = Field(default_factory=dict)
+    callback_name: str | None = None
+    protocol: str | None = Field(
+        default=None,
+        description=(
+            "OTLP transport, defaulting to the backend's own. Not derivable from the "
+            "scheme: Arize's ``https://otlp.arize.com/v1`` is gRPC."
+        ),
+    )
+
+    def header_string(self) -> str:
+        """Render headers as the ``k=v,k2=v2`` form an ``ExporterSpec`` expects.
+
+        Values are percent-encoded because ``providers.parse_headers`` decodes them
+        with the SDK's W3C-Baggage parser: a value carrying a ``,`` or ``=`` (a
+        Langfuse project name, a base64 Authorization payload ending in ``==``)
+        would otherwise be split into bogus pairs on the way back out.
+        """
+        return ",".join(f"{key}={quote(value, safe='')}" for key, value in self.headers.items())
+
+    def cache_key(self) -> tuple[str, tuple[tuple[str, str], ...], tuple[tuple[str, str], ...], str | None]:
+        """Identity for processor reuse, so one destination means one exporter."""
+        return (
+            self.endpoint,
+            tuple(sorted(self.headers.items())),
+            tuple(sorted(self.resource_attributes.items())),
+            self.protocol,
+        )
+
+
+NO_DESTINATIONS: Final[tuple[OtelDestination, ...]] = ()
diff --git a/litellm/integrations/otel/model/semconv.py b/litellm/integrations/otel/model/semconv.py
index af5327cbd41..d3628005bac 100644
--- a/litellm/integrations/otel/model/semconv.py
+++ b/litellm/integrations/otel/model/semconv.py
@@ -204,6 +204,9 @@ class Error:
 
     TYPE: Final = "error.type"
     MESSAGE: Final = "error.message"
+    # The same text under the bare key the semconv-ai / Traceloop vocabulary uses
+    # (see ``LegacyMapper``), so anything reading or redacting error text covers both.
+    MESSAGE_LEGACY: Final = "error"
 
 
 class LiteLLMError:
diff --git a/litellm/integrations/otel/plumbing/context.py b/litellm/integrations/otel/plumbing/context.py
index aa7cc8e2afd..21e61c71fb7 100644
--- a/litellm/integrations/otel/plumbing/context.py
+++ b/litellm/integrations/otel/plumbing/context.py
@@ -1,8 +1,9 @@
 """Trace-context + Baggage helpers."""
 
+import os
 from collections.abc import Mapping
 from contextvars import ContextVar, Token
-from typing import Final
+from typing import TYPE_CHECKING, Final
 
 from opentelemetry import baggage
 from opentelemetry.context import Context, get_current
@@ -21,6 +22,9 @@ from opentelemetry.trace.propagation.tracecontext import (
 
 from litellm.integrations.otel.model.semconv import HTTP
 
+if TYPE_CHECKING:
+    from litellm.integrations.otel.model.destination import OtelDestination
+
 _PROPAGATOR: Final = TraceContextTextMapPropagator()
 
 # The request's root span — the FastAPI-owned SERVER span — captured ONCE when the
@@ -304,3 +308,65 @@ def extract_traceparent(headers: Mapping[str, str]) -> Context | None:
         return None
     carrier: Final = {str(key).lower(): value for key, value in headers.items()}
     return _PROPAGATOR.extract(carrier)
+
+
+# The OTLP destinations this request's key or team pointed its traces at, resolved
+# once during auth. A ``ContextVar`` for the same reason the root span above is one:
+# it rides the request task's context into the ``asyncio.create_task`` children that
+# close the LLM span, and it is visible to every ``SpanProcessor.on_end`` that fires
+# on the request task. Stateful MCP handlers set and reset it per message; the
+# request-task value otherwise dies with that task.
+_request_destinations: Final['ContextVar[tuple["OtelDestination", ...]]'] = ContextVar(
+    "litellm_otel_request_destinations", default=()
+)
+
+
+def set_request_destinations(destinations: 'tuple["OtelDestination", ...]') -> "Token[tuple[OtelDestination, ...]]":
+    """Anchor the destinations this request exports to and return a reset token."""
+    return _request_destinations.set(destinations)
+
+
+def reset_request_destinations(token: "Token[tuple[OtelDestination, ...]]") -> None:
+    _request_destinations.reset(token)
+
+
+def request_destinations() -> 'tuple["OtelDestination", ...]':
+    """The destinations resolved for this request, empty outside a proxy request."""
+    return _request_destinations.get()
+
+
+#: ``litellm_settings: otel_tenant_destination_mode`` and its env equivalent.
+ADDITIVE_DESTINATION_MODE: Final = "additive"
+OTEL_TENANT_DESTINATION_MODE_ENV: Final = "LITELLM_OTEL_TENANT_DESTINATION_MODE"
+
+
+def tenant_destinations_are_additive() -> bool:
+    """Whether a tenant destination exports alongside the operator's own exporter.
+
+    Override is the default: the tenant's traffic reaches the tenant's account and
+    nowhere else. Operators running one org-wide backend across every team set this
+    to ``additive`` so the same trace lands in both places.
+    """
+    import litellm
+
+    configured: Final = litellm.otel_tenant_destination_mode or os.environ.get(OTEL_TENANT_DESTINATION_MODE_ENV)
+    return isinstance(configured, str) and configured.strip().lower() == ADDITIVE_DESTINATION_MODE
+
+
+def destination_backends() -> frozenset[str]:
+    """Backends this request resolved a tenant destination for.
+
+    The fan-out already carries the whole trace to those destinations, so the
+    per-request tracer route must never send a second copy, in either mode.
+    """
+    return frozenset(d.callback_name for d in _request_destinations.get() if d.callback_name)
+
+
+def suppressed_backends() -> frozenset[str]:
+    """Backends whose operator-level exporters this request must NOT reach.
+
+    Empty under ``additive``, where the operator keeps its copy of every span.
+    """
+    if tenant_destinations_are_additive():
+        return frozenset()
+    return destination_backends()
diff --git a/litellm/integrations/otel/plumbing/providers.py b/litellm/integrations/otel/plumbing/providers.py
index 90e68b7c2ee..81f22c8c642 100644
--- a/litellm/integrations/otel/plumbing/providers.py
+++ b/litellm/integrations/otel/plumbing/providers.py
@@ -1,9 +1,14 @@
 """Provider / exporter factory + the Baggage span processor."""
 
-from collections.abc import Callable, Iterable
+import queue
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, Literal
 
-from opentelemetry import _logs, baggage, metrics
+from opentelemetry import _logs, baggage, metrics, trace
 from opentelemetry._events import EventLogger
 from opentelemetry._logs import LoggerProvider, NoOpLoggerProvider
 from opentelemetry.context import Context
@@ -19,7 +24,8 @@ from opentelemetry.sdk._logs.export import (
 )
 from opentelemetry.sdk.metrics import MeterProvider as SDKMeterProvider
 from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, TracerProvider
+from opentelemetry.sdk.trace import Event, ReadableSpan, SpanProcessor, TracerProvider
+from opentelemetry.sdk.trace import Span as SDKSpan
 from opentelemetry.sdk.trace.export import (
     BatchSpanProcessor,
     ConsoleSpanExporter,
@@ -29,18 +35,35 @@ from opentelemetry.sdk.trace.export import (
 from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
     InMemorySpanExporter,
 )
-from opentelemetry.trace import Span, SpanKind, Tracer
+from opentelemetry.trace import Span, SpanKind, Status, Tracer
 from opentelemetry.util.re import parse_env_headers
+from opentelemetry.util.types import Attributes, AttributeValue
 
+from litellm._logging import verbose_logger
 from litellm._version import version as litellm_version
 from litellm.integrations.otel.model.config import ExporterSpec, OpenTelemetryV2Config
-from litellm.integrations.otel.model.semconv import LiteLLM
+from litellm.integrations.otel.model.semconv import (
+    DB,
+    MCP,
+    Error,
+    ExceptionEvent,
+    GenAI,
+    LiteLLM,
+    LiteLLMError,
+    Server,
+)
 from litellm.integrations.otel.model.spans import LiteLLMSpanKind
+from litellm.integrations.otel.plumbing.context import (
+    request_destinations,
+    suppressed_backends,
+)
 
 if TYPE_CHECKING:
     from opentelemetry.metrics import Meter
     from opentelemetry.sdk.metrics.export import MetricReader
 
+    from litellm.integrations.otel.model.destination import OtelDestination
+
 _SPAN_KIND_BY_ROLE_KIND: Final[dict[LiteLLMSpanKind, SpanKind]] = {
     LiteLLMSpanKind.SERVER: SpanKind.SERVER,
     LiteLLMSpanKind.CLIENT: SpanKind.CLIENT,
@@ -202,6 +225,555 @@ def _processor_for(exporter: SpanExporter, use_simple: bool | None) -> SpanProce
     return SimpleSpanProcessor(exporter) if use_simple else BatchSpanProcessor(exporter)
 
 
+#: Distinct tenant destinations whose exporters stay alive. Each holds a connection
+#: pool and a batch thread, so the cache is bounded and evicts least-recently-used.
+_MAX_CACHED_DESTINATION_PROCESSORS: Final = 32
+
+#: Workers closing shed destination processors, bounding the threads a tenant can
+#: create by cycling its destination config.
+_DRAIN_WORKERS: Final = 2
+
+#: Shed processors waiting to be closed before the fan-out stops building new ones.
+#: Each still owns a batch thread until its close returns, and a collector that never
+#: answers makes every close take the exporter's full timeout, so past this many the
+#: operator's exporter keeps the span instead (see ``deliverable``).
+_MAX_PENDING_DRAINS: Final = 64
+
+#: How long ``shutdown`` waits for spans already being forwarded, so teardown closes
+#: no processor under one. Bounded: an exporter that never returns must not hold the
+#: proxy open.
+_SHUTDOWN_DRAIN_SECONDS: Final = 5.0
+
+#: An exporter's account: its normalized endpoint and the credentials it presents.
+_SinkKey = tuple[str, tuple[tuple[str, str], ...]]
+
+#: Header names that spell one credential two ways. Arize's operator exporter sends
+#: ``space_id`` where a tenant destination sends ``arize-space-id``.
+_CREDENTIAL_ALIASES: Final = MappingProxyType({"arize_space_id": "space_id"})
+
+
+class _DrainPool:
+    """Closes shed destination processors off the span-export path.
+
+    ``shutdown`` flushes over the network and is reached from ``on_end``, so closing
+    one inline would let a single unreachable tenant collector stall every other
+    tenant's spans behind it. A fixed set of workers rather than a thread per
+    processor means a tenant cycling its destination config cannot spawn threads as
+    fast as it can send requests; slow shutdowns queue behind each other.
+
+    The workers are daemons and belong to the fan-out that sheds the processors, so
+    neither an unreachable collector nor a lazily built process-wide singleton can
+    hold the proxy open on the way down.
+    """
+
+    def __init__(
+        self,
+        workers: int = _DRAIN_WORKERS,
+        pending: "queue.Queue[SpanProcessor | None] | None" = None,
+        capacity: int = _MAX_PENDING_DRAINS,
+    ) -> None:
+        self._workers: Final = workers
+        self._capacity: Final = capacity
+        self._lock: Final = threading.Lock()
+        self._closed = False
+        self._backlog = 0  # guarded by ``_lock``: submitted processors whose close has not returned
+        self._pending: Final[queue.Queue[SpanProcessor | None]] = pending if pending is not None else queue.Queue()
+        self._threads: Final = tuple(
+            threading.Thread(target=self._drain_until_closed, daemon=True, name="litellm-otel-destination-drain")
+            for _ in range(workers)
+        )
+        for worker in self._threads:
+            worker.start()
+
+    def submit(self, processor: SpanProcessor) -> None:
+        """Queue ``processor`` for closing, or hand it off once the pool is retired.
+
+        The check and the put share one lock. Reading a closed flag on its own leaves
+        room for :meth:`close` to run in between, and the processor would land behind
+        the sentinels every worker has already exited on.
+
+        Past close there is no worker left to take it, and the caller is whichever
+        thread just ended a span, so closing it inline would park that thread on a
+        network flush the shutdown deadline has already stopped waiting for. The extra
+        thread is bounded by the same close: the fan-out stops handing processors out
+        at that point, so only the ones already exporting when it happened arrive here.
+        """
+        with self._lock:
+            if not self._closed:
+                self._backlog += 1
+                self._pending.put(processor)
+                return
+        threading.Thread(
+            target=_shutdown_quietly,
+            args=(processor,),
+            daemon=True,
+            name="litellm-otel-destination-drain-straggler",
+        ).start()
+
+    def saturated(self) -> bool:
+        """Whether enough closes are outstanding that building another processor must wait.
+
+        The workers close in order and each close blocks for as long as its exporter
+        does, so a collector that stopped answering would otherwise turn every new
+        destination into one more batch thread parked behind them, for as long as the
+        tenants keep rotating. Holding the count here rather than reading the queue
+        keeps the two processors a worker is mid-close on in the total.
+        """
+        with self._lock:
+            return self._backlog >= self._capacity
+
+    def close(self, timeout: float | None = None) -> None:
+        """Retire the workers once they have closed everything already queued.
+
+        A proxy that rebuilds its telemetry builds another fan-out, so workers that
+        outlive the one that started them are two more threads per reload, forever.
+
+        ``timeout`` bounds how long the caller waits for that draining to finish. The
+        workers are daemons, so whatever is still flushing when it expires is dropped
+        by the interpreter rather than holding it open.
+        """
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            for _ in range(self._workers):
+                self._pending.put(None)
+        if timeout is None:
+            return
+        deadline: Final = time.monotonic() + timeout
+        for worker in self._threads:
+            worker.join(timeout=max(0.0, deadline - time.monotonic()))
+
+    def _drain_until_closed(self) -> None:
+        while True:
+            processor: SpanProcessor | None = self._pending.get()  # rebind-ok: loop variable
+            if processor is None:
+                return
+            _shutdown_quietly(processor)
+            with self._lock:
+                self._backlog -= 1
+
+
+_NO_ATTRIBUTES: Final[Mapping[str, AttributeValue]] = MappingProxyType({})
+_DB_SYSTEM_KEYS: Final = frozenset({DB.SYSTEM_NAME, DB.SYSTEM_LEGACY})
+# Keys on a database span that describe the proxy's own datastore: its host, its
+# port, and its schema.
+_DATASTORE_ENDPOINT_KEYS: Final = frozenset({Server.ADDRESS, Server.PORT, DB.NAMESPACE})
+# A span carrying one of these describes the tenant's own call (the model call, the
+# MCP call, the guardrail), so its error text is theirs to see. Every other span is
+# the proxy's own work, whose error text names the operator's infrastructure.
+_TENANT_OWNED_KEYS: Final = frozenset({GenAI.OPERATION_NAME, MCP.METHOD_NAME, LiteLLM.GUARDRAIL_NAME})
+_PROXY_ERROR_TEXT_KEYS: Final = frozenset({Error.MESSAGE, Error.MESSAGE_LEGACY})
+# A guardrail that never answered carries the exception it raised as its response,
+# which names the operator's guardrail endpoint. The second spelling is the legacy
+# status the request-level logger still maps.
+_GUARDRAIL_UNREACHABLE_STATUSES: Final = frozenset({"guardrail_failed_to_respond", "failure"})
+# Attribute prefixes the FastAPI instrumentor uses for headers the operator opted to
+# capture (``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_*``). The request
+# side carries the caller's bearer token verbatim.
+_CAPTURED_HEADER_PREFIXES: Final = ("http.request.header.", "http.response.header.")
+# The instrumentor stamps the request URL on the server span with its query string,
+# under the old convention and the new one, and litellm accepts a virtual key as a
+# ``?key=`` query parameter.
+_URL_KEYS: Final = frozenset({"http.url", "http.target", "url.full"})
+_URL_QUERY_KEY: Final = "url.query"
+
+
+class _TenantSpanView(ReadableSpan):
+    """A ``ReadableSpan`` view for one destination, leaving the operator's own span alone."""
+
+    def __init__(
+        self,
+        inner: ReadableSpan,
+        resource: Resource,
+        attributes: Attributes,
+        events: Sequence[Event],
+        status: Status,
+    ) -> None:
+        super().__init__(
+            name=inner.name,
+            context=inner.context,
+            parent=inner.parent,
+            resource=resource,
+            attributes=attributes,
+            events=events,
+            links=inner.links,
+            kind=inner.kind,
+            status=status,
+            start_time=inner.start_time,
+            end_time=inner.end_time,
+            instrumentation_scope=inner.instrumentation_scope,
+        )
+
+
+def _is_database_span(attributes: Mapping[str, AttributeValue]) -> bool:
+    return any(key in attributes for key in _DB_SYSTEM_KEYS)
+
+
+def _is_tenant_owned_span(attributes: Mapping[str, AttributeValue]) -> bool:
+    return any(key in attributes for key in _TENANT_OWNED_KEYS)
+
+
+def _guardrail_unreachable(attributes: Mapping[str, AttributeValue]) -> bool:
+    return attributes.get(LiteLLM.GUARDRAIL_STATUS) in _GUARDRAIL_UNREACHABLE_STATUSES
+
+
+def _tenant_visible(key: str, database: bool, owned: bool, unreachable_guardrail: bool) -> bool:
+    if key.startswith(_CAPTURED_HEADER_PREFIXES) or key in (LiteLLMError.STACK_TRACE, _URL_QUERY_KEY):
+        return False
+    if database and key in _DATASTORE_ENDPOINT_KEYS:
+        return False
+    if unreachable_guardrail and key == LiteLLM.GUARDRAIL_RESPONSE:
+        return False
+    return owned or key not in _PROXY_ERROR_TEXT_KEYS
+
+
+def _without_query(key: str, value: AttributeValue) -> AttributeValue:
+    if key not in _URL_KEYS or not isinstance(value, str):
+        return value
+    return value.partition("?")[0]
+
+
+def _same_attributes(kept: Mapping[str, AttributeValue], attributes: Mapping[str, AttributeValue]) -> bool:
+    return len(kept) == len(attributes) and all(kept[key] is value for key, value in attributes.items())
+
+
+def _without_stack_trace(event: Event) -> Event:
+    attributes: Final = event.attributes or _NO_ATTRIBUTES
+    if ExceptionEvent.STACKTRACE not in attributes:
+        return event
+    return Event(
+        name=event.name,
+        attributes=MappingProxyType(
+            {key: value for key, value in attributes.items() if key != ExceptionEvent.STACKTRACE}
+        ),
+        timestamp=event.timestamp,
+    )
+
+
+def _for_destination(span: ReadableSpan, destination: "OtelDestination") -> ReadableSpan:
+    """The view of ``span`` a tenant destination receives.
+
+    A span the tenant's own call produced keeps its error text. Every other span is
+    the proxy's own work (the request root, auth, the database), and its error text,
+    its events and its status description come off, since a Prisma failure there
+    spells out the operator's Postgres endpoint. A database span loses that endpoint
+    too, and a guardrail that failed to respond loses its response text, which is the
+    exception it raised and names the operator's guardrail endpoint. Stack traces walk
+    the operator's install and come off every span, as do the headers the operator
+    captures on the server span, whose request side holds the caller's bearer token,
+    and the query string of the request URL, which can hold the same key. The span
+    itself stays, so the tenant still gets the whole trace tree.
+    """
+    extra: Final = destination.resource_attributes
+    attributes: Final = span.attributes or _NO_ATTRIBUTES
+    database: Final = _is_database_span(attributes)
+    owned: Final = _is_tenant_owned_span(attributes)
+    unreachable: Final = _guardrail_unreachable(attributes)
+    kept: Final = MappingProxyType(
+        {
+            key: _without_query(key, value)
+            for key, value in attributes.items()
+            if _tenant_visible(key, database, owned, unreachable)
+        }
+    )
+    recorded: Final = span.events
+    events: Final = tuple(_without_stack_trace(event) for event in recorded) if owned else ()
+    unchanged: Final = owned and _same_attributes(kept, attributes) and all(a is b for a, b in zip(events, recorded))
+    if not extra and unchanged:
+        return span
+    resource: Final = span.resource.merge(Resource(extra)) if extra else span.resource
+    status: Final = span.status if owned else Status(span.status.status_code)
+    return _TenantSpanView(span, resource, kept, events, status)
+
+
+class TenantFanOutSpanProcessor(SpanProcessor):
+    """Export every finished span to each destination this request resolved.
+
+    Destinations ride a request-scoped ``ContextVar`` set during auth, so concurrent
+    requests stay isolated. The forwarded view keeps the original trace and parent
+    ids, so the tenant gets the same tree the operator would have received.
+
+    Exactly one provider carries this processor, the one published as the OTel global
+    (see :func:`attach_tenant_fan_out`). That provider is the only one every span
+    passes through: the FastAPI server span, the auth span and the post-call database
+    spans are emitted on the global, while a second v2 logger's provider sees only
+    that logger's own gen-AI span. Attaching the fan-out per logger would hand a
+    tenant a one-span trace whenever its backend is not the global one, and two
+    copies of the model call whenever it is.
+    """
+
+    def __init__(
+        self,
+        processor_factory: 'Callable[["OtelDestination"], SpanProcessor | None] | None' = None,
+        shutdown_drain_seconds: float = _SHUTDOWN_DRAIN_SECONDS,
+        operator_sinks: frozenset[_SinkKey] = frozenset(),
+        pending_drains: int = _MAX_PENDING_DRAINS,
+        drain_pool: _DrainPool | None = None,
+    ) -> None:
+        self._operator_sinks: Final = operator_sinks
+        self._drain_seconds: Final = shutdown_drain_seconds
+        self._lock: Final = threading.Condition()
+        self._closed = False  # guarded by ``_lock``: an unlocked read races the teardown it gates
+        self._build: Final = processor_factory if processor_factory is not None else _destination_processor
+        self._processors: OrderedDict[object, SpanProcessor] = OrderedDict()  # mutable-ok: bounded LRU
+        self._retired: OrderedDict[int, SpanProcessor] = OrderedDict()  # mutable-ok: drains as exports finish
+        self._exporting: dict[int, int] = {}  # mutable-ok: per-processor in-flight export count
+        self._drain: Final = drain_pool if drain_pool is not None else _DrainPool(capacity=pending_drains)
+
+    def on_start(self, span: SDKSpan, parent_context: Context | None = None) -> None:
+        return None
+
+    def on_end(self, span: ReadableSpan) -> None:
+        suppressed: Final = suppressed_backends()
+        for destination in request_destinations():
+            if self._operator_already_writes(destination, suppressed):
+                continue
+            processor = self._acquire(destination)  # rebind-ok: loop variable; pyright forbids Final in a loop
+            if processor is None:
+                continue
+            try:
+                processor.on_end(_for_destination(span, destination))
+            except Exception as exc:  # noqa: BLE001  # one destination's failure must not cost the others their span
+                verbose_logger.debug("OTel V2 fan-out: forwarding to %s failed: %s", destination.endpoint, exc)
+            finally:
+                self._release(processor)
+
+    def _operator_already_writes(self, destination: "OtelDestination", suppressed: frozenset[str]) -> bool:
+        """Whether the operator's own exporter is sending this span to the same account.
+
+        Only reachable under ``additive``, where nothing is suppressed: a team that
+        names the operator's own project would otherwise have every span written
+        there twice, once by the operator's exporter and once by the fan-out.
+        """
+        return (
+            destination.callback_name not in suppressed
+            and _sink_key(destination.endpoint, destination.headers) in self._operator_sinks
+        )
+
+    def shutdown(self) -> None:
+        """Close every destination processor, once the spans in flight have landed.
+
+        ``on_end`` runs on whichever thread ends a span and can reach this fan-out
+        while the SDK is tearing the provider down, so closing blind would drop a
+        trace mid-forward and would hand the next caller a fresh exporter nothing
+        will ever close. Refusing new work and then waiting out the in-flight ones
+        keeps both from happening. A straggler past the bound is retired instead of
+        closed: the thread still exporting it closes it through the drain as soon as
+        its export returns, so no span is dropped mid-forward.
+
+        Every close then goes to the drain rather than running here. Closing a
+        destination processor flushes it over the network and the SDK joins its own
+        worker with no timeout of its own, so one tenant collector that answers but
+        never finishes a response would otherwise hold process teardown open for as
+        long as it likes. The drain's workers are daemons, and the whole teardown
+        shares one deadline.
+        """
+        deadline: Final = time.monotonic() + self._drain_seconds
+        with self._lock:
+            self._closed = True
+            self._lock.wait_for(lambda: not self._exporting, timeout=self._drain_seconds)
+            live: Final = tuple((id(p), p) for p in (*self._processors.values(), *self._retired.values()))
+            closing: Final = tuple(p for ident, p in live if ident not in self._exporting)
+            self._processors.clear()
+            self._retired = OrderedDict(  # mutable-ok: the same bounded map, keeping only what is still exporting
+                (ident, p) for ident, p in live if ident in self._exporting
+            )
+        for processor in closing:
+            self._drain.submit(processor)
+        self._drain.close(timeout=max(0.0, deadline - time.monotonic()))
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        results: Final = tuple(self._flush_one(processor, timeout_millis) for processor in self._snapshot())
+        return all(results)
+
+    def _snapshot(self) -> tuple[SpanProcessor, ...]:
+        with self._lock:
+            return (*self._processors.values(), *self._retired.values())
+
+    @staticmethod
+    def _flush_one(processor: SpanProcessor, timeout_millis: int) -> bool:
+        try:
+            return processor.force_flush(timeout_millis)
+        except Exception:  # noqa: BLE001  # one exporter's flush failure must not fail the whole flush
+            return False
+
+    def deliverable(self, destinations: Iterable["OtelDestination"]) -> tuple["OtelDestination", ...]:
+        """The subset of ``destinations`` this fan-out can actually export to.
+
+        A destination whose exporter will not build (a protocol whose package is not
+        installed, a malformed endpoint) has to be dropped before the request anchors
+        it, not when its first span ends. By then the operator's own exporter has been
+        told to hold that backend's spans back for this request, so dropping there
+        loses the span outright instead of leaving it where it would have gone with no
+        override at all.
+        """
+        return tuple(destination for destination in destinations if self._buildable(destination))
+
+    def _buildable(self, destination: "OtelDestination") -> bool:
+        """Whether a processor for ``destination`` exists or can be built right now."""
+        with self._lock:
+            if self._closed:
+                return False
+            built: Final = self._cached_or_built_locked(destination, anchored=False)
+            drained: Final = self._drainable_locked()
+            for shed in drained:
+                self._drain.submit(shed)
+            return built is not None
+
+    def _acquire(self, destination: "OtelDestination") -> SpanProcessor | None:
+        """The processor for ``destination``, marked busy until ``_release``.
+
+        The build happens under the same lock that reads the cache, so a cold cache
+        met by a burst of concurrent requests yields one exporter rather than one per
+        thread with all but the winner shed. Building an exporter opens no connection,
+        so the cost of holding the lock is a constructor, once per destination.
+        """
+        with self._lock:
+            if self._closed:
+                return None
+            processor: Final = self._cached_or_built_locked(destination, anchored=True)
+            if processor is None:
+                return None
+            self._exporting[id(processor)] = self._exporting.get(id(processor), 0) + 1
+            drained: Final = self._drainable_locked()
+            for shed in drained:
+                self._drain.submit(shed)
+            return processor
+
+    def _cached_or_built_locked(self, destination: "OtelDestination", *, anchored: bool) -> SpanProcessor | None:
+        """The cached processor for ``destination``, or a new one if the drain can take it.
+
+        Every build past the cache cap sheds one processor into the drain, so while the
+        shed ones are stuck closing against a collector that stopped answering, a
+        destination that is not yet anchored is refused rather than parked behind them:
+        ``deliverable`` then leaves its spans with the operator's exporter until the
+        drain catches up. One the request already anchored is rebuilt regardless. The
+        operator's exporter has stood down for it, so refusing here would drop the span,
+        and other tenants' auths can evict it in the meantime, with that eviction being
+        what tips the drain over. Eviction holds while the drain is saturated, so such a
+        rebuild costs the cache one entry rather than shedding another processor, and
+        the total stays at one per destination in flight.
+        """
+        key: Final = destination.cache_key()
+        if (cached := self._processors.get(key)) is not None:
+            self._processors.move_to_end(key)
+            self._retire_overflow_locked()
+            return cached
+        if not anchored and self._drain.saturated():
+            verbose_logger.debug("OTel V2 fan-out: drain saturated, not building for %s", destination.endpoint)
+            return None
+        return self._build_locked(destination, key)
+
+    def _build_locked(self, destination: "OtelDestination", key: object) -> SpanProcessor | None:
+        built: Final = self._build(destination)
+        if built is None:
+            return None
+        self._processors[key] = built
+        self._retire_overflow_locked()
+        return built
+
+    def _release(self, processor: SpanProcessor) -> None:
+        with self._lock:
+            remaining: Final = self._exporting.get(id(processor), 1) - 1
+            if remaining > 0:
+                self._exporting[id(processor)] = remaining
+            else:
+                self._exporting.pop(id(processor), None)
+                if not self._exporting:
+                    self._lock.notify_all()
+            drained: Final = self._drainable_locked()
+            for retired in drained:
+                self._drain.submit(retired)
+
+    def _retire_overflow_locked(self) -> None:
+        """Move the LRU processor out of the cache once it is past the cap, drain permitting.
+
+        Eviction is what feeds the drain, and a destination a request already anchored
+        is rebuilt on its next span, which would shed another one. While the shed ones
+        are stuck closing against a collector that stopped answering, evicting would
+        churn the cache at one more processor, and one more batch thread, per span.
+        Holding above the cap instead keeps the total at one processor per destination
+        in flight, since ``deliverable`` anchors no new destination while the drain is
+        saturated. Once it has room again, every hit and build trims one entry.
+        """
+        if len(self._processors) <= _MAX_CACHED_DESTINATION_PROCESSORS or self._drain.saturated():
+            return
+        _, evicted = self._processors.popitem(last=False)
+        self._retired[id(evicted)] = evicted
+
+    def _drainable_locked(self) -> tuple[SpanProcessor, ...]:
+        """Retired processors no thread is exporting through, removed from the list.
+
+        ``on_end`` holds a processor across an export, so closing an evicted one there
+        drops the span it is holding. A retiree is out of the cache and can never be
+        handed out again, so once its export count reaches zero it stays there.
+        """
+        idle: Final = tuple(key for key in self._retired if self._exporting.get(key, 0) == 0)
+        return tuple(self._retired.pop(key) for key in idle)
+
+
+def _destination_processor(destination: "OtelDestination") -> SpanProcessor | None:
+    """A batching OTLP processor aimed at ``destination``, or ``None`` if unbuildable.
+
+    A protocol that resolves to a headerless exporter is unbuildable too: the
+    console fallback would swallow the tenant's credentials and print its spans to
+    the proxy's stdout while the operator's exporter stands down for them.
+    """
+    kind: Final = destination.protocol or "otlp_http"
+    if exporter_transport(kind) == "headerless":
+        verbose_logger.debug("OTel V2 fan-out: no OTLP transport for protocol %r at %s", kind, destination.endpoint)
+        return None
+    try:
+        spec: Final = ExporterSpec(
+            kind=kind,
+            endpoint=destination.endpoint,
+            headers=destination.header_string(),
+            owner=None,
+        )
+        return _processor_for(_exporter_from_spec(spec), use_simple=False)
+    except Exception as exc:  # noqa: BLE001  # a malformed destination must not break the request or the other destinations
+        verbose_logger.debug("OTel V2 fan-out: no processor for %s: %s", destination.endpoint, exc)
+        return None
+
+
+def _shutdown_quietly(processor: SpanProcessor) -> None:
+    try:
+        processor.shutdown()
+    except Exception as exc:  # noqa: BLE001  # defensive: shedding a spare processor must not raise
+        verbose_logger.debug("OTel V2 fan-out: discarding processor failed: %s", exc)
+
+
+class _OverriddenBackendFilter(SpanProcessor):
+    """Hold a span back from ``owner``'s operator-level exporter when the request
+    pointed ``owner`` at a tenant's own account.
+
+    Wrapping is the only place this works: ``SynchronousMultiSpanProcessor.on_end``
+    ignores return values, so a sibling processor can never veto the export.
+
+    Under ``additive`` mode nothing is suppressed, so the wrapper passes every span
+    straight through and the operator keeps its copy.
+    """
+
+    def __init__(self, inner: SpanProcessor, owner: str) -> None:
+        self._inner: Final = inner
+        self._owner: Final = owner
+
+    def on_start(self, span: SDKSpan, parent_context: Context | None = None) -> None:
+        self._inner.on_start(span, parent_context)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        if self._owner in suppressed_backends():
+            return
+        self._inner.on_end(span)
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._inner.force_flush(timeout_millis)
+
+
 def build_span_exporter(config: OpenTelemetryV2Config) -> SpanExporter:
     """Build a single exporter from the top-level config fields.
 
@@ -452,6 +1024,7 @@ def build_tracer_provider(
     exporter: SpanExporter | None = None,
     baggage_processor: SpanProcessor | None = None,
     use_simple_processor: bool | None = None,
+    tenant_overrides: bool = False,
 ) -> TracerProvider:
     """Build the shared :class:`TracerProvider`.
 
@@ -460,6 +1033,13 @@ def build_tracer_provider(
     ``config.exporters`` entry — this is what fans spans out to multiple
     backends. ``exporter`` and ``use_simple_processor`` are explicit overrides:
     pass a single exporter to attach exactly that one (used by tests).
+
+    ``tenant_overrides`` wraps each owned exporter so a request that pointed that
+    backend at a key's or team's own account skips it. Every v2 logger's provider
+    wants it, since any of them may own the overridden backend; delivering to the
+    tenant is a separate job, done once by :func:`attach_tenant_fan_out`. The
+    per-tenant providers this same function builds must leave it off, or they would
+    filter out the very spans they exist to carry.
     """
     provider: Final = TracerProvider(resource=build_resource(config))
     if baggage_processor is None:
@@ -476,15 +1056,107 @@ def build_tracer_provider(
         if spec.requires_headers and not spec.headers:
             continue
         exp = _exporter_from_spec(spec)
+        processor = _processor_for(
+            exp,
+            (spec.use_simple_processor if spec.use_simple_processor is not None else use_simple_processor),
+        )
+        owner = spec.owner.value if spec.owner is not None else None
         provider.add_span_processor(
-            _processor_for(
-                exp,
-                (spec.use_simple_processor if spec.use_simple_processor is not None else use_simple_processor),
-            )
+            _OverriddenBackendFilter(processor, owner) if tenant_overrides and owner is not None else processor
         )
     return provider
 
 
+_FAN_OUT_ATTACH_LOCK: Final = threading.Lock()
+
+
+def attach_tenant_fan_out(provider: TracerProvider, *configs: OpenTelemetryV2Config) -> None:
+    """Give ``provider`` the fan-out that delivers spans to key/team destinations.
+
+    Called on the one provider published as the OTel global, and idempotent so a
+    second publish (a test, a re-initialized proxy) cannot double-export. Concurrent
+    first calls (requests racing to anchor before any publish) serialize on one lock
+    so exactly one fan-out lands. ``configs`` name the operator's own exporters, one
+    config per v2 logger since each keeps its own provider and still writes its
+    account, so an additive destination pointing at any of them is delivered once
+    rather than twice.
+    """
+    with _FAN_OUT_ATTACH_LOCK:
+        if any(isinstance(processor, TenantFanOutSpanProcessor) for processor in _attached_processors(provider)):
+            return
+        provider.add_span_processor(TenantFanOutSpanProcessor(operator_sinks=operator_sink_keys(*configs)))
+
+
+def deliverable_destinations(
+    destinations: Iterable["OtelDestination"],
+    provider: trace.TracerProvider | None = None,
+) -> tuple["OtelDestination", ...]:
+    """The destinations a request can anchor, given what is published to carry them.
+
+    Anchoring a destination is what tells the operator's own exporter to stand down
+    for that backend, so one nothing can deliver has to be dropped here: with no
+    fan-out attached, or with an exporter that will not build, the request keeps
+    exactly the routing it would have had without any override.
+    """
+    fan_out: Final = next(
+        (
+            processor
+            for processor in _attached_processors(provider if provider is not None else trace.get_tracer_provider())
+            if isinstance(processor, TenantFanOutSpanProcessor)
+        ),
+        None,
+    )
+    return fan_out.deliverable(destinations) if fan_out is not None else ()
+
+
+def operator_sink_keys(*configs: OpenTelemetryV2Config) -> frozenset[_SinkKey]:
+    """The accounts the operator's own exporters write to, in destination terms.
+
+    Every v2 logger's config counts, since each logger exports through its own
+    provider. An exporter with no endpoint of its own resolves one from the
+    environment at export time, so it has no comparable identity and is left out,
+    and so is one that never reaches the wire: a console kind ignores the endpoint,
+    and a header-gated spec with no credentials is skipped when the provider is built.
+    """
+    return frozenset(
+        key
+        for config in configs
+        for spec in config.exporters
+        if _exports_to_the_wire(spec) and (key := _sink_key(spec.endpoint, parse_headers(spec.headers))) is not None
+    )
+
+
+def _exports_to_the_wire(spec: ExporterSpec) -> bool:
+    """Whether ``build_tracer_provider`` gives ``spec`` an exporter that sends OTLP."""
+    return exporter_transport(spec.kind) != "headerless" and not (spec.requires_headers and not spec.headers)
+
+
+def _sink_key(endpoint: str | None, headers: Mapping[str, str]) -> "_SinkKey | None":
+    """The account an exporter writes to, or ``None`` when it has no fixed one.
+
+    Normalized on the three counts that make one account look like two: the operator's
+    spec carries the signal path a tenant destination leaves for the exporter to
+    append, header names survive one round trip lowercased and the other not, and one
+    credential answers to more than one name (see :data:`_CREDENTIAL_ALIASES`).
+    """
+    normalized: Final = _otlp_traces_endpoint(endpoint)
+    if normalized is None:
+        return None
+    return (normalized, tuple(sorted((_credential_name(name), value) for name, value in headers.items())))
+
+
+def _credential_name(header: str) -> str:
+    """The credential a header carries, under whichever name the backend spells it."""
+    normalized: Final = header.strip().lower().replace("-", "_")
+    return _CREDENTIAL_ALIASES.get(normalized, normalized)
+
+
+def _attached_processors(provider: trace.TracerProvider) -> "tuple[SpanProcessor, ...]":
+    """The processors already on ``provider``, or empty when the SDK hides them."""
+    multi: Final = getattr(provider, "_active_span_processor", None)
+    return tuple(getattr(multi, "_span_processors", ()))
+
+
 def get_tracer(provider: TracerProvider, name: str = "litellm") -> Tracer:
     # Stamp the instrumentation scope with the LiteLLM package version so every
     # emitted span carries a deterministic ``scope.version`` (the standard OTel
diff --git a/litellm/integrations/otel/plumbing/routing.py b/litellm/integrations/otel/plumbing/routing.py
index 227e18f3663..f78d18d943c 100644
--- a/litellm/integrations/otel/plumbing/routing.py
+++ b/litellm/integrations/otel/plumbing/routing.py
@@ -25,6 +25,7 @@ from opentelemetry.trace import Tracer
 from litellm._logging import verbose_logger
 from litellm.constants import OTEL_SERVICE_NAME_METADATA_KEYS
 from litellm.integrations.otel.model.config import ExporterSpec, OpenTelemetryV2Config
+from litellm.integrations.otel.plumbing.context import destination_backends
 from litellm.integrations.otel.plumbing.providers import (
     build_tracer_provider,
     exporter_transport,
@@ -231,10 +232,21 @@ class TenantTracerCache:
         concurrent overflow eviction can't shut it down between selection and
         the caller's span start. The caller must ``release`` it exactly once.
         """
+        # A backend with a destination is delivered by the fan-out processor, which
+        # carries the whole trace and already carries this tenant's credentials and
+        # service name. Routing here too would detach this span onto a second provider,
+        # so the tenant would get the request tree plus a stray one-span trace.
+        if self._callback_name is not None and self._callback_name in destination_backends():
+            return TenantRoute(tracer=default, detached=False)
         credential_headers: Final = self._credential_headers(dynamic_params)
         project_headers: Final = self._project_headers(auth_metadata)
         service_name: Final = tenant_service_name(auth_metadata)
-        if not credential_headers and not project_headers and service_name is None:
+        tenant_account: Final = bool(credential_headers) or bool(project_headers)
+        # A service name on its own only relabels the operator's own backend, so moving
+        # the span to a second provider for it while some other backend has a
+        # destination would drop the model call out of the trace the fan-out delivers.
+        # The destination stamps the same service name itself.
+        if not tenant_account and (service_name is None or destination_backends()):
             return TenantRoute(tracer=default, detached=False)
         # A fixed per-integration region endpoint (New Relic us/eu), never a
         # caller-supplied host; ``None`` keeps the preset's own endpoint.
@@ -255,7 +267,7 @@ class TenantTracerCache:
             _shutdown_provider(evicted)
         return TenantRoute(
             tracer=get_tracer(provider, self._tracer_name),
-            detached=bool(project_headers) or bool(credential_headers),
+            detached=tenant_account,
             provider=provider,
         )
 
diff --git a/litellm/integrations/otel/presets/agentops.py b/litellm/integrations/otel/presets/agentops.py
index f45b1cd3cff..965213f2ee4 100644
--- a/litellm/integrations/otel/presets/agentops.py
+++ b/litellm/integrations/otel/presets/agentops.py
@@ -39,6 +39,7 @@ class _AgentOpsSettings(BaseSettings):
 def agentops_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
     """Build the AgentOps config without any network I/O.
 
diff --git a/litellm/integrations/otel/presets/arize.py b/litellm/integrations/otel/presets/arize.py
index ee0de675657..d7ce87f5552 100644
--- a/litellm/integrations/otel/presets/arize.py
+++ b/litellm/integrations/otel/presets/arize.py
@@ -26,10 +26,12 @@ class _ArizeSettings(BaseSettings):
 def arize_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
+    base: Final = config_overrides or OpenTelemetryV2Config()
+    mappers: Final = ensure_mappers(base.mapper_names, "openinference")
     arize_cfg: Final = _V1ArizeLogger.get_arize_config()
     headers: Final = _arize_headers(arize_cfg)
-    base: Final = config_overrides or OpenTelemetryV2Config()
     return base.model_copy(
         update={
             "exporters": [
@@ -41,7 +43,7 @@ def arize_preset(
                     owner=ExporterOwner.ARIZE_AX,
                 ),
             ],
-            "mapper_names": ensure_mappers(base.mapper_names, "openinference"),
+            "mapper_names": mappers,
             "resource_attributes": {
                 **base.resource_attributes,
                 **({"model_id": arize_cfg.project_name} if arize_cfg.project_name else {}),
diff --git a/litellm/integrations/otel/presets/base.py b/litellm/integrations/otel/presets/base.py
index 3b9991f86a4..3a768a08a4f 100644
--- a/litellm/integrations/otel/presets/base.py
+++ b/litellm/integrations/otel/presets/base.py
@@ -18,6 +18,18 @@ class Preset(Protocol):
 
     ``config_overrides`` lets one preset layer onto another's config (or onto
     test-supplied defaults); the factory calls presets with no arguments.
+
+    ``allow_missing_credentials`` lets a credential-mandatory backend (langfuse and
+    weave) degrade to an exporter-less, mapper-only config instead of raising when the
+    operator set no env credentials of their own. That is a real
+    deployment: every team brings its own account and the operator keeps none, and
+    without it the whole V2 path silently falls back to the legacy integration, so
+    no team destination is ever reached. Credential-optional backends ignore it.
     """
 
-    def __call__(self, *, config_overrides: OpenTelemetryV2Config | None = None) -> OpenTelemetryV2Config: ...
+    def __call__(
+        self,
+        *,
+        config_overrides: OpenTelemetryV2Config | None = None,
+        allow_missing_credentials: bool = False,
+    ) -> OpenTelemetryV2Config: ...
diff --git a/litellm/integrations/otel/presets/destinations.py b/litellm/integrations/otel/presets/destinations.py
new file mode 100644
index 00000000000..2bf9bfa5261
--- /dev/null
+++ b/litellm/integrations/otel/presets/destinations.py
@@ -0,0 +1,152 @@
+"""Map a key's or team's callback vars to the OTLP destination its traces export to.
+
+Header building is delegated to each preset's existing ``*_dynamic_headers`` builder,
+so a destination authenticates exactly the way the per-request tracer route already
+did; only the endpoint and transport need a per-backend rule.
+"""
+
+import os
+from collections.abc import Callable, Mapping
+from functools import lru_cache
+from types import MappingProxyType
+from typing import Final
+
+import litellm
+from litellm._logging import verbose_logger
+from litellm.integrations.otel.model.destination import OtelDestination
+from litellm.litellm_core_utils.url_utils import is_url_destination_allowed_by_host
+from litellm.types.utils import StandardCallbackDynamicParams
+
+#: An endpoint plus the OTLP transport to reach it with, or ``None`` when the backend
+#: names no destination. The transport is ``None`` where the backend has only one.
+_Destination = tuple[str, str | None]
+
+
+@lru_cache(maxsize=128)
+def _warn_host_not_allowlisted(host: str) -> None:
+    """Cached so one misconfigured team logs once rather than once per request."""
+    verbose_logger.warning(
+        "OTel V2: not exporting to key/team Langfuse host '%s'. Add it to "
+        "litellm_settings.provider_url_destination_allowed_hosts to permit it",
+        host,
+    )
+
+
+def _langfuse_destination(params: StandardCallbackDynamicParams) -> "_Destination | None":
+    """The tenant's own Langfuse host, else the operator's, else Langfuse US cloud.
+
+    A host the tenant named has to be allowlisted by the operator, the same way a
+    URL-valued ``model`` is: anyone who can mint a key can write it, and it becomes an
+    endpoint the proxy posts the request's whole trace to, carrying the tenant's own
+    credentials. The operator's own ``LANGFUSE_HOST`` is not checked, since an internal
+    collector there is a deployment choice.
+    """
+    from litellm.integrations.langfuse.langfuse_otel import (
+        LANGFUSE_CLOUD_US_ENDPOINT,
+        LangfuseOtelLogger,
+    )
+
+    tenant_host: Final = params.get("langfuse_host") or None
+    host: Final = tenant_host or LangfuseOtelLogger._get_langfuse_otel_host()  # pyright: ignore[reportPrivateUsage]  # reuse the backend's own env host resolver rather than duplicating it
+    if not host:
+        return (LANGFUSE_CLOUD_US_ENDPOINT, None)
+    normalized: Final = host if host.startswith("http") else f"https://{host}"
+    endpoint: Final = f"{normalized.rstrip('/')}/api/public/otel"
+    if tenant_host is None:
+        return (endpoint, None)
+    if not is_url_destination_allowed_by_host(endpoint, litellm.provider_url_destination_allowed_hosts):
+        _warn_host_not_allowlisted(host)
+        return None
+    return (endpoint, None)
+
+
+def _arize_destination(params: StandardCallbackDynamicParams) -> "_Destination | None":
+    from litellm.integrations.arize.arize import ArizeLogger
+
+    config: Final = ArizeLogger.get_arize_config()
+    return (config.endpoint, config.protocol)
+
+
+def _weave_destination(params: StandardCallbackDynamicParams) -> "_Destination | None":
+    from litellm.integrations.weave.weave_otel import weave_otel_endpoint
+
+    return (weave_otel_endpoint(os.environ.get("WANDB_HOST")), None)
+
+
+def _newrelic_destination(params: StandardCallbackDynamicParams) -> "_Destination | None":
+    from litellm.integrations.otel.presets.newrelic import newrelic_dynamic_endpoint
+
+    endpoint: Final = newrelic_dynamic_endpoint(params)
+    return (endpoint, None) if endpoint else None
+
+
+#: Callback name -> destination resolver. A backend is destination-capable exactly
+#: when it appears here AND in ``DYNAMIC_HEADERS_BY_CALLBACK``: without a header
+#: builder the destination would carry no tenant credentials, and the exporter
+#: would post the tenant's traffic to the operator's account.
+_DESTINATION_BY_CALLBACK: Final[Mapping[str, Callable[[StandardCallbackDynamicParams], "_Destination | None"]]] = (
+    MappingProxyType(
+        {
+            "langfuse_otel": _langfuse_destination,
+            "arize": _arize_destination,
+            "weave_otel": _weave_destination,
+            "newrelic": _newrelic_destination,
+        }
+    )
+)
+
+#: Headers a destination must carry to authenticate. Several dynamic-header builders
+#: gate each credential independently, so a half-configured backend yields a non-empty
+#: but unusable header set; accepting it would suppress the operator's own exporter and
+#: send the request's whole trace where it cannot be stored.
+_REQUIRED_HEADERS_BY_CALLBACK: Final[Mapping[str, frozenset[str]]] = MappingProxyType(
+    {
+        "langfuse_otel": frozenset({"Authorization"}),
+        "arize": frozenset({"arize-space-id", "api_key"}),
+        "weave_otel": frozenset({"Authorization", "project_id"}),
+        "newrelic": frozenset({"api-key"}),
+    }
+)
+
+_NO_ATTRS: Final[Mapping[str, str]] = MappingProxyType({})
+
+
+def destination_capable_backends() -> frozenset[str]:
+    """Backends a key or team can point at its own account."""
+    from litellm.integrations.otel.presets import DYNAMIC_HEADERS_BY_CALLBACK
+
+    return frozenset(_DESTINATION_BY_CALLBACK) & frozenset(DYNAMIC_HEADERS_BY_CALLBACK)
+
+
+def destination_for(
+    callback_name: str,
+    params: StandardCallbackDynamicParams,
+    service_name: str | None = None,
+) -> OtelDestination | None:
+    """The destination ``params`` names for ``callback_name``, or ``None``.
+
+    ``None`` means the caller configured nothing usable for this backend, so the
+    request keeps the operator's global exporters. ``service_name`` is the key's or
+    team's ``otel_service_name``, which the per-request tracer route applies when the
+    backend is not overridden and the destination has to apply once it is.
+    """
+    from litellm.integrations.otel.presets import DYNAMIC_HEADERS_BY_CALLBACK
+
+    header_builder: Final = DYNAMIC_HEADERS_BY_CALLBACK.get(callback_name)
+    destination_builder: Final = _DESTINATION_BY_CALLBACK.get(callback_name)
+    if header_builder is None or destination_builder is None:
+        return None
+    headers: Final = header_builder(params)
+    if not headers or not _REQUIRED_HEADERS_BY_CALLBACK[callback_name] <= frozenset(headers):
+        return None
+    resolved: Final = destination_builder(params)
+    if resolved is None:
+        return None
+    endpoint, protocol = resolved
+    return OtelDestination(
+        endpoint=endpoint,
+        headers=MappingProxyType(dict(headers)),  # mutable-ok: MappingProxyType needs a concrete mapping to wrap
+        resource_attributes=MappingProxyType({"service.name": service_name}) if service_name else _NO_ATTRS,
+        callback_name=callback_name,
+        protocol=protocol,
+    )
diff --git a/litellm/integrations/otel/presets/langfuse.py b/litellm/integrations/otel/presets/langfuse.py
index c2f64422eff..9149e0c0d94 100644
--- a/litellm/integrations/otel/presets/langfuse.py
+++ b/litellm/integrations/otel/presets/langfuse.py
@@ -10,17 +10,32 @@ from litellm.integrations.otel.model.config import (
     ExporterSpec,
     OpenTelemetryV2Config,
 )
-from litellm.integrations.otel.presets.utils import ensure_mappers
+from litellm.integrations.otel.presets.utils import (
+    credential_gated_exporters,
+    ensure_mappers,
+)
 from litellm.types.utils import StandardCallbackDynamicParams
 
 
 def langfuse_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
-    cfg: Final = _V1Langfuse.get_langfuse_otel_config()
-    kind: Final = cfg.exporter if isinstance(cfg.exporter, str) else "otlp_http"
     base: Final = config_overrides or OpenTelemetryV2Config()
+    mappers: Final = ensure_mappers(base.mapper_names, "langfuse")
+    try:
+        cfg: Final = _V1Langfuse.get_langfuse_otel_config()
+    except Exception:
+        if not allow_missing_credentials:
+            raise
+        return base.model_copy(
+            update={  # mutable-ok: pydantic model_copy takes a plain update mapping
+                "exporters": credential_gated_exporters(base.exporters, ExporterOwner.LANGFUSE_OTEL),
+                "mapper_names": mappers,
+            }
+        )
+    kind: Final = cfg.exporter if isinstance(cfg.exporter, str) else "otlp_http"
     return base.model_copy(
         update={
             "exporters": [
@@ -32,7 +47,7 @@ def langfuse_preset(
                     owner=ExporterOwner.LANGFUSE_OTEL,
                 ),
             ],
-            "mapper_names": ensure_mappers(base.mapper_names, "langfuse"),
+            "mapper_names": mappers,
         }
     )
 
diff --git a/litellm/integrations/otel/presets/langtrace.py b/litellm/integrations/otel/presets/langtrace.py
index c88e4715ab0..2312575f04a 100644
--- a/litellm/integrations/otel/presets/langtrace.py
+++ b/litellm/integrations/otel/presets/langtrace.py
@@ -9,6 +9,7 @@ from litellm.integrations.otel.presets.utils import ensure_mappers
 def langtrace_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
     """Compose the Langtrace mapper on top of the customer's OTLP destination.
 
diff --git a/litellm/integrations/otel/presets/levo.py b/litellm/integrations/otel/presets/levo.py
index 41b3758cf3e..c1580cf7a5b 100644
--- a/litellm/integrations/otel/presets/levo.py
+++ b/litellm/integrations/otel/presets/levo.py
@@ -13,6 +13,7 @@ from litellm.integrations.otel.model.config import (
 def levo_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
     cfg: Final = _V1Levo.get_levo_config()
     base: Final = config_overrides or OpenTelemetryV2Config()
diff --git a/litellm/integrations/otel/presets/newrelic.py b/litellm/integrations/otel/presets/newrelic.py
index 4660a707355..771b3f643c8 100644
--- a/litellm/integrations/otel/presets/newrelic.py
+++ b/litellm/integrations/otel/presets/newrelic.py
@@ -44,6 +44,7 @@ class _NewRelicSettings(BaseSettings):
 def newrelic_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
     settings: Final = _NewRelicSettings()
     base: Final = config_overrides or OpenTelemetryV2Config()
diff --git a/litellm/integrations/otel/presets/phoenix.py b/litellm/integrations/otel/presets/phoenix.py
index eef407b6c1b..f4f34ee7525 100644
--- a/litellm/integrations/otel/presets/phoenix.py
+++ b/litellm/integrations/otel/presets/phoenix.py
@@ -60,6 +60,7 @@ def phoenix_project_headers(auth_metadata: Mapping[str, str] | None) -> Mapping[
 def phoenix_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
     cfg: Final = _V1Phoenix.get_arize_phoenix_config()
     headers: Final = cfg.otlp_auth_headers if hasattr(cfg, "otlp_auth_headers") else None
diff --git a/litellm/integrations/otel/presets/utils.py b/litellm/integrations/otel/presets/utils.py
index 328569d3daf..1270c41e77b 100644
--- a/litellm/integrations/otel/presets/utils.py
+++ b/litellm/integrations/otel/presets/utils.py
@@ -3,6 +3,8 @@
 from collections.abc import Iterable
 from typing import Final
 
+from litellm.integrations.otel.model.config import ExporterOwner, ExporterSpec
+
 
 def ensure_mappers(mapper_names: Iterable[str], *names: str) -> list[str]:
     """Return ``mapper_names`` with each of ``names`` appended if not already present.
@@ -15,3 +17,32 @@ def ensure_mappers(mapper_names: Iterable[str], *names: str) -> list[str]:
         if name not in result:
             result.append(name)
     return result
+
+
+def credential_gated_exporters(
+    exporters: "Iterable[ExporterSpec]", owner: "ExporterOwner"
+) -> "tuple[ExporterSpec, ...]":
+    """``exporters`` with the operator's destination replaced by a header-gated one.
+
+    Used when a credential-mandatory backend is asked to build without the operator's
+    own credentials, so only key/team destinations receive spans. Two things have to
+    happen for that to mean "export nowhere": the placeholder console spec that
+    ``OpenTelemetryV2Config`` folds in for an empty exporter list is dropped, or every
+    span would be printed to stdout, and the gated spec keeps the owner so the
+    override filter still recognises which backend this provider speaks for.
+    """
+    return (
+        *(spec for spec in exporters if not is_unconfigured_placeholder(spec)),
+        ExporterSpec(owner=owner, requires_headers=True),
+    )
+
+
+def is_unconfigured_placeholder(spec: "ExporterSpec") -> bool:
+    """Whether ``spec`` is the one ``_normalize`` folds in when nothing was configured.
+
+    No field set is what says the operator asked for nothing: an exporter they did
+    configure survives, even ``OTEL_EXPORTER=console`` whose value matches the default,
+    and so does the gated spec this module appends, which would otherwise eat itself
+    when one preset layers onto another.
+    """
+    return not spec.model_fields_set
diff --git a/litellm/integrations/otel/presets/weave.py b/litellm/integrations/otel/presets/weave.py
index 51d0ad01093..644cd39ad36 100644
--- a/litellm/integrations/otel/presets/weave.py
+++ b/litellm/integrations/otel/presets/weave.py
@@ -7,7 +7,10 @@ from litellm.integrations.otel.model.config import (
     ExporterSpec,
     OpenTelemetryV2Config,
 )
-from litellm.integrations.otel.presets.utils import ensure_mappers
+from litellm.integrations.otel.presets.utils import (
+    credential_gated_exporters,
+    ensure_mappers,
+)
 from litellm.integrations.weave.weave_otel import (
     _get_weave_authorization_header,
     get_weave_otel_config,
@@ -18,9 +21,21 @@ from litellm.types.utils import StandardCallbackDynamicParams
 def weave_preset(
     *,
     config_overrides: OpenTelemetryV2Config | None = None,
+    allow_missing_credentials: bool = False,
 ) -> OpenTelemetryV2Config:
-    weave_cfg: Final = get_weave_otel_config()
     base: Final = config_overrides or OpenTelemetryV2Config()
+    mappers: Final = ensure_mappers(base.mapper_names, "openinference", "weave")
+    try:
+        weave_cfg: Final = get_weave_otel_config()
+    except Exception:
+        if not allow_missing_credentials:
+            raise
+        return base.model_copy(
+            update={  # mutable-ok: pydantic model_copy takes a plain update mapping
+                "exporters": credential_gated_exporters(base.exporters, ExporterOwner.WEAVE_OTEL),
+                "mapper_names": mappers,
+            }
+        )
     return base.model_copy(
         update={
             "exporters": [
@@ -33,7 +48,7 @@ def weave_preset(
                 ),
             ],
             # Weave consumes OpenInference + a small Weave-specific overlay.
-            "mapper_names": ensure_mappers(base.mapper_names, "openinference", "weave"),
+            "mapper_names": mappers,
         }
     )
 
diff --git a/litellm/integrations/weave/weave_otel.py b/litellm/integrations/weave/weave_otel.py
index f2cc64a9ba2..50289263f38 100644
--- a/litellm/integrations/weave/weave_otel.py
+++ b/litellm/integrations/weave/weave_otel.py
@@ -117,6 +117,14 @@ def _get_weave_authorization_header(api_key: str) -> str:
     return f"Basic {auth_header}"
 
 
+def weave_otel_endpoint(host: str | None) -> str:
+    """The OTLP traces endpoint for a self-managed ``host``, else Weave cloud."""
+    if not host:
+        return WEAVE_BASE_URL + WEAVE_OTEL_ENDPOINT
+    normalized: Final = host if host.startswith("http") else f"https://{host}"
+    return normalized.rstrip("/") + WEAVE_OTEL_ENDPOINT
+
+
 def get_weave_otel_config() -> WeaveOtelConfig:
     """
     Retrieves the Weave OpenTelemetry configuration based on environment variables.
@@ -134,7 +142,6 @@ def get_weave_otel_config() -> WeaveOtelConfig:
     """
     api_key: Final = os.getenv("WANDB_API_KEY")
     project_id: Final = os.getenv("WANDB_PROJECT_ID")
-    host = os.getenv("WANDB_HOST")
 
     if not api_key:
         raise ValueError("WANDB_API_KEY must be set for Weave OpenTelemetry integration.")
@@ -144,15 +151,8 @@ def get_weave_otel_config() -> WeaveOtelConfig:
             "WANDB_PROJECT_ID must be set for Weave OpenTelemetry integration. Format: <entity>/<project_name>"
         )
 
-    if host:
-        if not host.startswith("http"):
-            host = "https://" + host
-        # Self-managed instances use a different path
-        endpoint = host.rstrip("/") + WEAVE_OTEL_ENDPOINT
-        verbose_logger.debug("Using Weave OTEL endpoint from host: %s", endpoint)
-    else:
-        endpoint = WEAVE_BASE_URL + WEAVE_OTEL_ENDPOINT
-        verbose_logger.debug("Using Weave cloud endpoint: %s", endpoint)
+    endpoint: Final = weave_otel_endpoint(os.getenv("WANDB_HOST"))
+    verbose_logger.debug("Using Weave OTEL endpoint: %s", endpoint)
 
     # Weave uses Basic auth with format: api:<WANDB_API_KEY>
     auth_header: Final = _get_weave_authorization_header(api_key=api_key)
diff --git a/litellm/litellm_core_utils/litellm_logging.py b/litellm/litellm_core_utils/litellm_logging.py
index c5fcf0bd2a0..b0d6db20b31 100644
--- a/litellm/litellm_core_utils/litellm_logging.py
+++ b/litellm/litellm_core_utils/litellm_logging.py
@@ -202,6 +202,7 @@ if TYPE_CHECKING:
     from mcp.types import EmbeddedResource, ImageContent, TextContent
 
     from litellm.integrations.otel.logger import OpenTelemetryV2
+    from litellm.integrations.otel.model.config import ExporterSpec, OpenTelemetryV2Config
     from litellm.llms.base_llm.passthrough.transformation import BasePassthroughConfig
 try:
     from litellm_enterprise.enterprise_callbacks.callback_controls import (
@@ -4850,31 +4851,83 @@ def _maybe_construct_otel_v2(callback_name: str, _in_memory_loggers: list[Custom
 
     Returns ``None`` when V2 is off OR when there's no preset registered for
     ``callback_name`` — callers should then fall through to the legacy path.
+
+    A preset that needs operator credentials it cannot find is allowed to build
+    only when this request has a key/team destination for that backend and another
+    V2 logger is already registered to carry the fan-out. The resulting logger keeps
+    only its credential-gated exporter, while the registered logger owns operator
+    delivery. Without that carrier, a preset that raises or that ends up with nothing
+    but its gated exporter and the default console placeholder returns ``None``, so the
+    caller falls through to the legacy path exactly as before V2 landed.
     """
     from litellm.integrations.otel.model.config import is_otel_v2_enabled
 
     if not is_otel_v2_enabled():
         return None
     from litellm.integrations.otel.logger import OpenTelemetryV2, build_otel_v2_logger
+    from litellm.integrations.otel.plumbing.context import destination_backends
     from litellm.integrations.otel.presets import PRESET_BY_CALLBACK
 
     preset_fn: Final = PRESET_BY_CALLBACK.get(callback_name)
     if preset_fn is None:
         return None
+    serves_a_destination: Final = callback_name in destination_backends()
+    has_v2_logger: Final = any(isinstance(callback, OpenTelemetryV2) for callback in _in_memory_loggers)
+    carried: Final = serves_a_destination and has_v2_logger
     for callback in _in_memory_loggers:
-        if isinstance(callback, OpenTelemetryV2) and getattr(callback, "callback_name", None) == callback_name:
+        if (
+            isinstance(callback, OpenTelemetryV2)
+            and getattr(callback, "callback_name", None) == callback_name
+            and (serves_a_destination or not _exports_nowhere(callback.config))
+        ):
             return callback
     try:
-        config: Final = preset_fn()
+        built: Final = preset_fn(allow_missing_credentials=carried)
     except Exception:
         # If env vars are missing or the preset raises, defer to the legacy path
         # so customers get the same error story they had before V2 landed.
         return None
+    gated: Final = _is_credential_gated(built)
+    if gated and not carried and not _has_operator_exporter(built):
+        return None
+    config: Final = _only_the_gated_exporter(built) if gated and carried else built
+    if _exports_nowhere(config):
+        verbose_logger.warning(
+            "OTel V2: no operator credentials for '%s'; only key/team destinations will receive its traces",
+            callback_name,
+        )
     v2_logger: Final = build_otel_v2_logger(config=config, callback_name=callback_name)
     _in_memory_loggers.append(v2_logger)
     return v2_logger
 
 
+def _exports_nowhere(config: "OpenTelemetryV2Config") -> bool:
+    """Whether every exporter in ``config`` is waiting on credentials it never got."""
+    return all(_is_gated(spec) for spec in config.exporters)
+
+
+def _is_credential_gated(config: "OpenTelemetryV2Config") -> bool:
+    """Whether the preset built without the operator's own credentials for its backend."""
+    return any(_is_gated(spec) for spec in config.exporters)
+
+
+def _has_operator_exporter(config: "OpenTelemetryV2Config") -> bool:
+    """Whether the operator configured somewhere real to export, beyond the default console placeholder."""
+    from litellm.integrations.otel.presets.utils import is_unconfigured_placeholder
+
+    return any(not _is_gated(spec) and not is_unconfigured_placeholder(spec) for spec in config.exporters)
+
+
+def _only_the_gated_exporter(config: "OpenTelemetryV2Config") -> "OpenTelemetryV2Config":
+    return config.model_copy(
+        update={"exporters": [spec for spec in config.exporters if _is_gated(spec)]}  # mutable-ok: model_copy update
+    )
+
+
+def _is_gated(spec: "ExporterSpec") -> bool:
+    return spec.requires_headers and not spec.headers
+
+
 def _maybe_auto_initialize_arize_phoenix(_in_memory_loggers: list[CustomLogger]) -> None:
     """
     Auto-initialize ArizePhoenixLogger when Phoenix env vars are detected.
diff --git a/litellm/proxy/_experimental/mcp_server/server.py b/litellm/proxy/_experimental/mcp_server/server.py
index a44a041fdff..1b1e77d27ef 100644
--- a/litellm/proxy/_experimental/mcp_server/server.py
+++ b/litellm/proxy/_experimental/mcp_server/server.py
@@ -19,7 +19,7 @@ from typing import TYPE_CHECKING, Any, Final, Protocol
 
 import httpx
 from fastapi import FastAPI, HTTPException
-from pydantic import AnyUrl, ConfigDict
+from pydantic import AnyUrl, ConfigDict, TypeAdapter, ValidationError
 from starlette.requests import Request as StarletteRequest
 from starlette.responses import JSONResponse
 from starlette.types import Message, Receive, Scope, Send
@@ -108,9 +108,9 @@ _MAX_STATEFUL_SESSIONS_PER_OWNER: Final = 100
 # prevents an authenticated client from forcing the proxy to buffer an
 # arbitrarily large body just to make a routing decision.
 _MCP_ROUTING_PEEK_MAX_BYTES: Final = 4096
-# ASGI scope key holding the tracing span of the request carrying an MCP
-# message, written on the request task and read back by the message handler.
+# ASGI scope keys carrying OTel request state into a stateful MCP message handler.
 _MCP_TRANSPORT_SPAN_SCOPE_KEY: Final = "litellm_otel_transport_span"
+_MCP_DESTINATIONS_SCOPE_KEY: Final = "litellm_otel_request_destinations"
 
 
 def _invalidate_byok_cred_cache(user_id: str, server_id: str) -> None:
@@ -328,18 +328,17 @@ def _otel_publish_transport_span_on_scope(scope: Scope) -> None:
         scope[_MCP_TRANSPORT_SPAN_SCOPE_KEY] = span
 
 
-def _otel_transport_span_from_message(req_ctx: object) -> object:
-    """The tracing span of the HTTP request that carried this MCP message.
-
-    Read off that request's ASGI scope, reached through the ``Request`` the
-    streamable-HTTP transport attaches to each message, so it is this message's
-    transport and not whichever request happens to have touched the session last.
-    Returns whatever the scope holds; the otel plumbing validates it."""
+def _otel_value_from_message_scope(req_ctx: object, key: str) -> object:
     request: Final = getattr(req_ctx, "request", None)
     scope: Final = getattr(request, "scope", None)
     if not isinstance(scope, Mapping):
         return None
-    return scope.get(_MCP_TRANSPORT_SPAN_SCOPE_KEY)
+    return scope.get(key)
+
+
+def _otel_transport_span_from_message(req_ctx: object) -> object:
+    """The tracing span of the HTTP request that carried this MCP message."""
+    return _otel_value_from_message_scope(req_ctx, _MCP_TRANSPORT_SPAN_SCOPE_KEY)
 
 
 def _otel_set_mcp_transport_span(span: object) -> object:
@@ -372,6 +371,44 @@ def _otel_reset_mcp_transport_span(token: object) -> None:
         return
 
 
+def _otel_publish_request_destinations_on_scope(scope: Scope) -> None:
+    try:
+        from litellm.integrations.otel.plumbing.context import request_destinations
+
+        scope[_MCP_DESTINATIONS_SCOPE_KEY] = request_destinations()
+    except ImportError:
+        return
+
+
+def _otel_set_mcp_request_destinations(req_ctx: object) -> object:
+    destinations: Final = _otel_value_from_message_scope(req_ctx, _MCP_DESTINATIONS_SCOPE_KEY)
+    if not isinstance(destinations, tuple):
+        return None
+    try:
+        from litellm.integrations.otel.model.destination import OtelDestination
+        from litellm.integrations.otel.plumbing.context import set_request_destinations
+
+        destination_adapter: Final[TypeAdapter[tuple[OtelDestination, ...]]] = TypeAdapter(
+            tuple[OtelDestination, ...],
+            config=ConfigDict(revalidate_instances="always"),
+        )
+        validated_destinations: Final = destination_adapter.validate_python(destinations, strict=True)
+        return set_request_destinations(validated_destinations)
+    except (ImportError, ValidationError):
+        return None
+
+
+def _otel_reset_mcp_request_destinations(token: object) -> None:
+    if token is None:
+        return
+    try:
+        from litellm.integrations.otel.plumbing.context import reset_request_destinations
+
+        reset_request_destinations(token)
+    except ImportError:
+        return
+
+
 def _proxy_exception_to_http_exception(exc: ProxyException) -> HTTPException:
     """Map a ``ProxyException`` to an ``HTTPException`` that preserves its real
     status code and headers.
@@ -763,10 +800,12 @@ if MCP_AVAILABLE:
             _session_reset_token = active_mcp_session_var.set(req_ctx.session)
         _trace_token = None
         _transport_token = None
+        _destinations_token = None
 
         try:
             _trace_token = _otel_set_mcp_trace_carrier(_mcp_meta_trace_carrier(req_ctx))
             _transport_token = _otel_set_mcp_transport_span(_otel_transport_span_from_message(req_ctx))
+            _destinations_token = _otel_set_mcp_request_destinations(req_ctx)
             # Get user authentication from context variable
             (
                 user_api_key_auth,
@@ -828,6 +867,7 @@ if MCP_AVAILABLE:
             # This prevents the HTTP stream from failing and allows the client to get a response
             return []
         finally:
+            _otel_reset_mcp_request_destinations(_destinations_token)
             _otel_reset_mcp_transport_span(_transport_token)
             _otel_reset_mcp_trace_carrier(_trace_token)
             if _session_reset_token is not None:
@@ -1021,10 +1061,12 @@ if MCP_AVAILABLE:
             _session_reset_token = active_mcp_session_var.set(req_ctx.session)
         _trace_token = None
         _transport_token = None
+        _destinations_token = None
 
         try:
             _trace_token = _otel_set_mcp_trace_carrier(_mcp_meta_trace_carrier(req_ctx))
             _transport_token = _otel_set_mcp_transport_span(_otel_transport_span_from_message(req_ctx))
+            _destinations_token = _otel_set_mcp_request_destinations(req_ctx)
             # Validate arguments
             (
                 user_api_key_auth,
@@ -1163,6 +1205,7 @@ if MCP_AVAILABLE:
 
             return response
         finally:
+            _otel_reset_mcp_request_destinations(_destinations_token)
             _otel_reset_mcp_transport_span(_transport_token)
             _otel_reset_mcp_trace_carrier(_trace_token)
             if _session_reset_token is not None:
@@ -4493,6 +4536,7 @@ if MCP_AVAILABLE:
 
             async def _dispatch() -> None:
                 _otel_publish_transport_span_on_scope(scope)
+                _otel_publish_request_destinations_on_scope(scope)
                 auth_user: Final = _set_or_update_auth_context(
                     user_api_key_auth=user_api_key_auth,
                     mcp_auth_header=mcp_auth_header,
diff --git a/litellm/proxy/auth/user_api_key_auth.py b/litellm/proxy/auth/user_api_key_auth.py
index d8679627bc3..5a2a20f8f59 100644
--- a/litellm/proxy/auth/user_api_key_auth.py
+++ b/litellm/proxy/auth/user_api_key_auth.py
@@ -2837,6 +2837,43 @@ async def _authorize_authenticated_request(
 
 
 @tracer.wrap()
+def _seed_request_destinations(user_api_key_dict: UserAPIKeyAuth, request: Request | None = None) -> None:
+    """Anchor the OTLP destinations this key or team overrides its traces to.
+
+    Called inside the ``auth`` phase span so that span reaches the tenant's account
+    as well, and on the request task so the ``ContextVar`` is inherited by the logging
+    tasks that close the LLM span. Best-effort: trace routing must never fail auth.
+
+    ``request`` carries the headers, so a backend this request disabled with
+    ``x-litellm-disable-callbacks`` resolves to no destination.
+
+    Only destinations the published fan-out can build are anchored. Anchoring one is
+    what tells the operator's exporter to hold that backend's spans back under
+    ``override``, so an unbuildable one would leave the span with nowhere to go.
+
+    The ``postgres`` spans under ``auth`` close before this runs, because they are the
+    reads that resolve the identity being read here. They never reach the tenant's
+    account, and they are never withheld from the operator's backend, whichever mode
+    is set.
+    """
+    try:
+        from litellm.integrations.otel.logger import fan_out_provider
+        from litellm.integrations.otel.plumbing.context import set_request_destinations
+        from litellm.integrations.otel.plumbing.providers import deliverable_destinations
+        from litellm.proxy.litellm_pre_call_utils import (
+            resolve_tenant_otel_destinations,
+        )
+
+        set_request_destinations(
+            deliverable_destinations(
+                resolve_tenant_otel_destinations(user_api_key_dict, _safe_get_request_headers(request)),
+                fan_out_provider(),
+            )
+        )
+    except Exception as exc:  # noqa: BLE001  # telemetry routing is best-effort and must never break authentication
+        verbose_proxy_logger.debug("OTel V2: tenant destination resolution failed: %s", exc)
+
+
 async def user_api_key_auth(
     request: Request,
     api_key: str = fastapi.Security(api_key_header),
@@ -2883,6 +2920,7 @@ async def user_api_key_auth(
                 raise body_parse_exception
             raise
         user_api_key_auth_obj.budget_reservation = None
+        _seed_request_destinations(user_api_key_auth_obj, request)
 
         # A body that never parsed is authenticated (so the trace carries identity
         # and this ``auth`` span) but not authorized: there is no model to check it
diff --git a/litellm/proxy/litellm_pre_call_utils.py b/litellm/proxy/litellm_pre_call_utils.py
index 12798c92eba..d0eb75bc29a 100644
--- a/litellm/proxy/litellm_pre_call_utils.py
+++ b/litellm/proxy/litellm_pre_call_utils.py
@@ -10,6 +10,7 @@ from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, cast
 
 from fastapi import HTTPException, Request
+from pydantic import TypeAdapter
 from pydantic import ValidationError as PydanticValidationError
 from starlette.datastructures import Headers
 
@@ -28,6 +29,7 @@ from litellm.constants import (
     SESSION_DEPLOYMENT_AFFINITY_TTL_METADATA_KEY,
     SESSION_ID_GENERATED_METADATA_KEY,
     SESSION_ID_OMITTED_METADATA_KEY,
+    X_LITELLM_DISABLE_CALLBACKS,
 )
 from litellm.litellm_core_utils.credential_accessor import CredentialAccessor
 from litellm.litellm_core_utils.initialize_dynamic_callback_params import (
@@ -159,6 +161,7 @@ from litellm.types.utils import (
     CustomPricingLiteLLMParams,
     LlmProviders,
     ProviderSpecificHeader,
+    StandardCallbackDynamicParams,
     StandardLoggingUserAPIKeyMetadata,
     SupportedCacheControls,
 )
@@ -172,6 +175,7 @@ _ENABLE_TEAM_STALE_ALIAS_BYPASS: bool | None = None
 
 
 if TYPE_CHECKING:
+    from litellm.integrations.otel.model.destination import OtelDestination
     from litellm.proxy.proxy_server import ProxyConfig as _ProxyConfig
     from litellm.types.proxy.policy_engine import Policy, PolicyMatchContext
 
@@ -975,6 +979,142 @@ def _get_dynamic_logging_metadata(
     return callback_settings_obj
 
 
+_TENANT_OTEL_PARAMS: Final = TypeAdapter(StandardCallbackDynamicParams)
+
+
+def _tenant_otel_params(callback_vars: Mapping[str, str]) -> StandardCallbackDynamicParams:
+    try:
+        return _TENANT_OTEL_PARAMS.validate_python(callback_vars)
+    except PydanticValidationError:
+        return StandardCallbackDynamicParams()
+
+
+_NO_REQUEST_HEADERS: Final[Mapping[str, str]] = MappingProxyType({})
+
+
+def _dynamically_disabled_backends(
+    user_api_key_dict: UserAPIKeyAuth,
+    request_headers: Mapping[str, str] | None,
+) -> frozenset[str]:
+    """The callbacks this request turned off, read the way dispatch reads them.
+
+    Same sources, precedence, and premium gate ``EnterpriseCallbackControls`` applies
+    before it skips a callback: the ``x-litellm-disable-callbacks`` header wins over the
+    key's stored list, team settings are not a source, and a non-premium proxy honours
+    neither. A destination has to agree with that decision, or a backend the key turned
+    off would still be exported to, now through the fan-out instead of the callback.
+    """
+    from litellm.proxy.proxy_server import premium_user
+
+    if litellm.allow_dynamic_callback_disabling is not True or not premium_user:
+        return frozenset()
+    header: Final = (request_headers if request_headers is not None else _NO_REQUEST_HEADERS).get(
+        X_LITELLM_DISABLE_CALLBACKS
+    )
+    if header is not None:
+        return frozenset(name.strip().lower() for name in header.split(","))
+    metadata: Final = user_api_key_dict.metadata
+    disabled: Final = metadata.get("litellm_disabled_callbacks") if metadata else None
+    if not isinstance(disabled, list):
+        return frozenset()
+    return frozenset(name.lower() for name in disabled if isinstance(name, str))
+
+
+def resolve_tenant_otel_destinations(
+    user_api_key_dict: UserAPIKeyAuth,
+    request_headers: Mapping[str, str] | None = None,
+) -> "tuple[OtelDestination, ...]":
+    """The OTLP destinations this request's key or team config overrides its traces to.
+
+    Key settings win over team settings outright, the same precedence
+    ``_get_dynamic_logging_metadata`` applies, so one caller never exports the same
+    backend to two accounts. An empty key-level list counts as configured, since that
+    is what disabling a key's callbacks writes. Returns empty when OTEL V2 is off, when
+    neither level named a destination-capable backend, or when the config is
+    incomplete, and the request then keeps the operator's own exporters.
+
+    Two entries naming the same backend merge their ``callback_vars`` last-wins, the
+    way ``convert_key_logging_metadata_to_callback`` merges them, so the destination
+    and the per-request tracer routing cannot read one config two ways.
+
+    A ``failure``-only entry is skipped: a destination is resolved during auth, before
+    the request has an outcome, so honouring the filter would mean holding every span
+    back until the call finishes. Those entries keep today's behaviour instead, where
+    the tenant's credentials reach the backend through per-request tracer routing and
+    the operator's exporter is left alone.
+
+    A backend the request disabled dynamically, through the key's
+    ``litellm_disabled_callbacks`` or the ``x-litellm-disable-callbacks`` header in
+    ``request_headers``, resolves to no destination, so the fan-out never carries the
+    request tree to that account and the operator's exporter is never suppressed for
+    it. That leaves the request exactly where it stood before destinations existed:
+    the OTel V2 logger itself is not on the disable list's class registry, so its own
+    span still routes to the tenant's credentials the way it did then.
+    """
+    from litellm.integrations.otel.model.config import is_otel_v2_enabled
+    from litellm.integrations.otel.presets.destinations import destination_for
+
+    if not is_otel_v2_enabled():
+        return ()
+    key_entries: Final = KeyAndTeamLoggingSettings.get_key_dynamic_logging_settings(user_api_key_dict)
+    entries: Final = (
+        key_entries
+        if key_entries is not None
+        else KeyAndTeamLoggingSettings.get_team_dynamic_logging_settings(user_api_key_dict)
+    )
+    if not entries:
+        return ()
+    disabled: Final = _dynamically_disabled_backends(user_api_key_dict, request_headers)
+    callbacks: Final = tuple(
+        callback
+        for item in entries
+        if (callback := _get_validated_callback_metadata(item=item, source="otel-destination")) is not None
+        if callback.callback_type != "failure"
+        if callback.callback_name.lower() not in disabled
+    )
+    return tuple(
+        destination
+        for name in dict.fromkeys(callback.callback_name for callback in callbacks)
+        if (
+            destination := destination_for(
+                name,
+                _tenant_otel_params(
+                    MappingProxyType(
+                        {
+                            var: value
+                            for callback in callbacks
+                            if callback.callback_name == name
+                            for var, value in callback.callback_vars.items()
+                        }
+                    )
+                ),
+                _tenant_service_name(user_api_key_dict),
+            )
+        )
+        is not None
+    )
+
+
+def _tenant_service_name(user_api_key_dict: UserAPIKeyAuth) -> str | None:
+    """The ``service.name`` this key or team configured, the key winning over its team.
+
+    Same fields and same precedence the request-metadata build applies, read straight
+    off the auth object because destinations resolve during auth, before that metadata
+    is assembled.
+    """
+    sources: Final = (user_api_key_dict.metadata, user_api_key_dict.team_metadata)
+    return next(
+        (
+            stripped
+            for source in sources
+            if source
+            for field in OTEL_SERVICE_NAME_METADATA_KEYS
+            if isinstance(value := source.get(field), str) and (stripped := value.strip())
+        ),
+        None,
+    )
+
+
 def clean_headers(
     headers: Headers,
     litellm_key_header_name: str | None = None,
diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_destinations.py b/tests/test_litellm/integrations/otel/test_otel_v2_destinations.py
new file mode 100644
index 00000000000..1799381bada
--- /dev/null
+++ b/tests/test_litellm/integrations/otel/test_otel_v2_destinations.py
@@ -0,0 +1,2719 @@
+"""Key/team OTLP destinations override the operator's exporters for that backend."""
+
+import contextvars
+import time
+from collections.abc import Mapping
+from types import MappingProxyType
+
+import pytest
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import Status, StatusCode
+
+import litellm
+from litellm.integrations.custom_logger import CustomLogger
+from litellm.integrations.otel import logger as otel_logger
+from litellm.integrations.otel.logger import (
+    OpenTelemetryV2,
+    build_otel_v2_logger,
+    fan_out_provider,
+    publish_global_otel_v2_provider,
+)
+from litellm.integrations.otel.model.config import (
+    ExporterOwner,
+    ExporterSpec,
+    OpenTelemetryV2Config,
+    is_otel_v2_enabled,
+)
+from litellm.integrations.otel.model.destination import OtelDestination
+from litellm.integrations.otel.plumbing import providers as otel_providers
+from litellm.integrations.otel.plumbing.context import (
+    destination_backends,
+    request_destinations,
+    set_request_destinations,
+)
+from litellm.integrations.otel.plumbing.providers import (
+    TenantFanOutSpanProcessor,
+    _OverriddenBackendFilter,
+    _sink_key,
+    build_tracer_provider,
+    deliverable_destinations,
+    operator_sink_keys,
+)
+from litellm.integrations.otel.plumbing.routing import TenantTracerCache, get_tracer
+from litellm.integrations.otel.presets.arize import arize_preset
+from litellm.integrations.otel.presets.destinations import (
+    destination_capable_backends,
+    destination_for,
+)
+from litellm.integrations.otel.presets.langfuse import langfuse_preset
+from litellm.proxy._types import UserAPIKeyAuth
+from litellm.proxy.litellm_pre_call_utils import resolve_tenant_otel_destinations
+from litellm.types.utils import StandardCallbackDynamicParams
+
+LANGFUSE_DEST = OtelDestination(
+    endpoint="http://tenant.local/api/public/otel",
+    headers={"Authorization": "Basic dGVuYW50"},
+    callback_name="langfuse_otel",
+)
+
+
+@pytest.fixture
+def allow_test_hosts(monkeypatch):
+    """A tenant-supplied host must be allowlisted by the operator. Allowlist the ones
+    these fixtures name so the resolution tests stay about resolution;
+    ``TestTenantHostSsrfGuard`` covers the guard itself."""
+    monkeypatch.setattr(
+        litellm, "provider_url_destination_allowed_hosts", ["team.local", "key.local", "x"], raising=False
+    )
+
+
+@pytest.fixture(autouse=True)
+def isolate_published_provider(monkeypatch):
+    """Publishing records the fan-out carrier in module state; one test's publish must
+    not become the next test's provider."""
+    monkeypatch.setattr(otel_logger, "_published_v2_provider", None)
+
+
+def in_fresh_context(fn, *args):
+    """Run ``fn`` in its own context so one test's destinations never leak."""
+    return contextvars.copy_context().run(fn, *args)
+
+
+def emit(provider: TracerProvider, name: str = "chat gpt-4") -> None:
+    with get_tracer(provider, "litellm").start_as_current_span(name):
+        pass
+
+
+def wired_provider(dest_exporter: InMemorySpanExporter, global_exporter: InMemorySpanExporter) -> TracerProvider:
+    """The operator's provider: one owned exporter plus the tenant fan-out."""
+    provider = TracerProvider()
+    provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(global_exporter), "langfuse_otel"))
+    provider.add_span_processor(
+        TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+    )
+    return provider
+
+
+class TestOverrideSuppression:
+    def test_operator_exporter_keeps_the_span_when_no_destination_is_resolved(self):
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        in_fresh_context(emit, provider)
+
+        assert [s.name for s in global_exporter.get_finished_spans()] == ["chat gpt-4"]
+        assert dest_exporter.get_finished_spans() == ()
+
+    def test_operator_exporter_is_skipped_once_the_backend_is_overridden(self):
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            emit(provider)
+
+        in_fresh_context(run)
+
+        assert global_exporter.get_finished_spans() == ()
+        assert [s.name for s in dest_exporter.get_finished_spans()] == ["chat gpt-4"]
+
+    def test_a_backend_the_request_did_not_override_still_exports(self):
+        arize_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(arize_exporter), "arize"))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            emit(provider)
+
+        in_fresh_context(run)
+
+        assert [s.name for s in arize_exporter.get_finished_spans()] == ["chat gpt-4"]
+
+
+class TestRoutingMode:
+    """The operator's choice between replacing its own exporter and exporting alongside it.
+
+    One org-wide backend across every team is a real deployment, and losing it the
+    moment a team configures its own is what ``additive`` exists to prevent.
+    """
+
+    OPERATOR_SINK = ("https://cloud.langfuse.com/api/public/otel/v1/traces", (("authorization", "Basic op"),))
+    #: What a tenant destination for that same project looks like before normalizing:
+    #: no signal path yet, and the header name cased the way the backend writes it.
+    SAME_ACCOUNT_ENDPOINT = "https://cloud.langfuse.com/api/public/otel"
+
+    @staticmethod
+    def _additive(monkeypatch):
+        monkeypatch.setattr(litellm, "otel_tenant_destination_mode", "additive", raising=False)
+
+    @staticmethod
+    def _tree(provider):
+        tracer = get_tracer(provider, "litellm")
+        with tracer.start_as_current_span("POST /v1/chat/completions"):
+            with tracer.start_as_current_span("auth /v1/chat/completions"):
+                pass
+            with tracer.start_as_current_span("chat gpt-4"):
+                pass
+
+    def _run(self, provider, destinations=(LANGFUSE_DEST,)):
+        def run():
+            set_request_destinations(destinations)
+            self._tree(provider)
+
+        in_fresh_context(run)
+
+    def test_global_only_keeps_every_span_and_delivers_to_nobody(self):
+        """No team destination resolved, so the operator's backbone is untouched."""
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        self._run(provider, destinations=())
+
+        assert len(global_exporter.get_finished_spans()) == 3
+        assert dest_exporter.get_finished_spans() == ()
+
+    def test_team_only_gets_the_whole_tree_with_no_operator_exporter(self):
+        """A deployment with no operator credentials still gives the team its trace."""
+        dest_exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+
+        self._run(provider)
+
+        assert {s.name for s in dest_exporter.get_finished_spans()} == {
+            "POST /v1/chat/completions",
+            "auth /v1/chat/completions",
+            "chat gpt-4",
+        }
+
+    def test_additive_gives_the_operator_and_the_team_the_same_tree(self, monkeypatch):
+        self._additive(monkeypatch)
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        self._run(provider)
+
+        names = {"POST /v1/chat/completions", "auth /v1/chat/completions", "chat gpt-4"}
+        assert {s.name for s in global_exporter.get_finished_spans()} == names
+        assert {s.name for s in dest_exporter.get_finished_spans()} == names
+        assert len(global_exporter.get_finished_spans()) == 3, "the operator must not get a span twice"
+
+    def test_override_moves_the_tree_off_the_operator(self):
+        """The default, unchanged: the tenant's traffic reaches the tenant and nowhere else."""
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        self._run(provider)
+
+        assert global_exporter.get_finished_spans() == ()
+        assert len(dest_exporter.get_finished_spans()) == 3
+
+    def test_a_team_naming_the_operators_own_project_is_written_once(self, monkeypatch):
+        """Fanning out to two accounts is the point. Writing the same account twice
+        is a duplicate the operator would see in their own project."""
+        self._additive(monkeypatch)
+        shared = InMemorySpanExporter()
+        same = OtelDestination(
+            endpoint=self.SAME_ACCOUNT_ENDPOINT,
+            headers=MappingProxyType({"Authorization": "Basic op"}),
+            callback_name="langfuse_otel",
+        )
+        provider = TracerProvider()
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(shared), "langfuse_otel"))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(
+                processor_factory=lambda _d: SimpleSpanProcessor(shared),
+                operator_sinks=frozenset({self.OPERATOR_SINK}),
+            )
+        )
+
+        self._run(provider, destinations=(same,))
+
+        assert len(shared.get_finished_spans()) == 3, "the same account received the trace twice"
+
+    def test_in_override_a_team_naming_the_operators_project_still_gets_the_trace(self):
+        """Override suppresses the operator's own exporter, so the fan-out is the only
+        thing left delivering. Skipping it on a matching account leaves the team with
+        nothing at all."""
+        shared = InMemorySpanExporter()
+        same = OtelDestination(
+            endpoint=self.SAME_ACCOUNT_ENDPOINT,
+            headers=MappingProxyType({"Authorization": "Basic op"}),
+            callback_name="langfuse_otel",
+        )
+        provider = TracerProvider()
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(shared), "langfuse_otel"))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(
+                processor_factory=lambda _d: SimpleSpanProcessor(shared),
+                operator_sinks=frozenset({self.OPERATOR_SINK}),
+            )
+        )
+
+        self._run(provider, destinations=(same,))
+
+        assert len(shared.get_finished_spans()) == 3, "the team's own destination received nothing"
+
+    def test_a_team_naming_a_different_project_still_gets_its_copy(self, monkeypatch):
+        """The dedup keys on the account, so a second project is still a second copy."""
+        self._additive(monkeypatch)
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(global_exporter), "langfuse_otel"))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(
+                processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter),
+                operator_sinks=frozenset({self.OPERATOR_SINK}),
+            )
+        )
+
+        self._run(provider)
+
+        assert len(global_exporter.get_finished_spans()) == 3
+        assert len(dest_exporter.get_finished_spans()) == 3
+
+    @pytest.mark.parametrize("additive", [True, False])
+    def test_a_failing_team_destination_leaves_the_operator_alone(self, monkeypatch, additive):
+        """A tenant collector that raises on every span must not cost the operator
+        its own telemetry, nor take the request down with it."""
+        if additive:
+            self._additive(monkeypatch)
+        global_exporter, arize_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+
+        class Exploding(SimpleSpanProcessor):
+            def on_end(self, span):
+                raise RuntimeError("tenant collector is down")
+
+        provider = TracerProvider()
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(global_exporter), "langfuse_otel"))
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(arize_exporter), "arize"))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: Exploding(InMemorySpanExporter()))
+        )
+
+        self._run(provider)
+
+        assert len(arize_exporter.get_finished_spans()) == 3, "an unrelated backend lost spans"
+        assert len(global_exporter.get_finished_spans()) == (3 if additive else 0)
+
+    def test_the_env_var_turns_additive_on_without_a_config_file(self, monkeypatch):
+        monkeypatch.setattr(litellm, "otel_tenant_destination_mode", None, raising=False)
+        monkeypatch.setenv("LITELLM_OTEL_TENANT_DESTINATION_MODE", "Additive")
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        self._run(provider)
+
+        assert len(global_exporter.get_finished_spans()) == 3
+        assert len(dest_exporter.get_finished_spans()) == 3
+
+    def test_an_unrecognized_mode_stays_on_override(self, monkeypatch):
+        monkeypatch.setattr(litellm, "otel_tenant_destination_mode", "both", raising=False)
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        self._run(provider)
+
+        assert global_exporter.get_finished_spans() == ()
+
+    def test_operator_sink_keys_skips_an_exporter_with_no_endpoint_of_its_own(self):
+        """Such an exporter resolves its endpoint from the environment at export
+        time, so it has no identity to compare a destination against."""
+        config = OpenTelemetryV2Config(
+            exporters=(
+                ExporterSpec(kind="otlp_http", endpoint=self.OPERATOR_SINK[0], headers="authorization=Basic op"),
+                ExporterSpec(kind="otlp_http", endpoint=None, headers="authorization=Basic other"),
+            )
+        )
+
+        assert operator_sink_keys(config) == frozenset({self.OPERATOR_SINK})
+
+    def test_operator_sink_keys_skips_exporters_that_never_reach_the_wire(self):
+        """A console kind ignores the endpoint and a header-gated spec with no
+        credentials is dropped when the provider is built, so treating either as an
+        account the operator writes to would silently withhold a team's own spans
+        under additive."""
+        config = OpenTelemetryV2Config(
+            exporters=(
+                ExporterSpec(kind="otlp_http", endpoint=self.OPERATOR_SINK[0], headers="authorization=Basic op"),
+                ExporterSpec(kind="console", endpoint="http://team.local/v1/traces"),
+                ExporterSpec(kind="otlp_http", endpoint="http://gated.local/v1/traces", requires_headers=True),
+            )
+        )
+
+        assert operator_sink_keys(config) == frozenset({self.OPERATOR_SINK})
+
+    def test_operator_sink_keys_spans_every_config_it_is_handed(self):
+        first = OpenTelemetryV2Config(
+            exporters=(
+                ExporterSpec(
+                    kind="otlp_http",
+                    endpoint=self.OPERATOR_SINK[0],
+                    headers="authorization=Basic op",
+                ),
+            )
+        )
+        second = OpenTelemetryV2Config(
+            exporters=(
+                ExporterSpec(
+                    kind="otlp_http",
+                    endpoint="https://otlp.arize.com/v1/traces",
+                    headers="space_id=s,api_key=k",
+                ),
+            )
+        )
+
+        assert operator_sink_keys(first, second) == {
+            self.OPERATOR_SINK,
+            _sink_key("https://otlp.arize.com/v1/traces", {"space_id": "s", "api_key": "k"}),
+        }
+
+    def test_a_team_pointing_at_a_credential_less_operator_exporter_still_gets_its_spans(self, monkeypatch):
+        """Under additive the fan-out skips a destination the operator already writes
+        to. An exporter the provider never built writes nothing, so skipping it would
+        cost the team every span."""
+        monkeypatch.setenv("LITELLM_OTEL_TENANT_DESTINATION_MODE", "additive")
+        gated_endpoint = "http://gated.local/v1/traces"
+        destination = OtelDestination(endpoint=gated_endpoint, callback_name="newrelic")
+        config = OpenTelemetryV2Config(
+            exporters=(ExporterSpec(kind="otlp_http", endpoint=gated_endpoint, requires_headers=True),)
+        )
+        dest_exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(
+                processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter),
+                operator_sinks=operator_sink_keys(config),
+            )
+        )
+
+        def run():
+            set_request_destinations((destination,))
+            emit(provider)
+
+        in_fresh_context(run)
+
+        assert [s.name for s in dest_exporter.get_finished_spans()] == ["chat gpt-4"]
+
+    def test_the_operators_own_langfuse_and_a_team_naming_it_are_one_account(self, monkeypatch):
+        """The two sides are built by different code that writes the endpoint and the
+        header names differently, so comparing them raw silently never matches."""
+        monkeypatch.setenv("LANGFUSE_HOST", "https://lf.internal")
+        monkeypatch.setenv("LANGFUSE_PUBLIC_KEY", "pk-op")
+        monkeypatch.setenv("LANGFUSE_SECRET_KEY", "sk-op")
+        monkeypatch.setattr(litellm, "provider_url_destination_allowed_hosts", ["lf.internal"], raising=False)
+        operator = operator_sink_keys(langfuse_preset())
+
+        def sink(public_key, secret_key):
+            destination = destination_for(
+                "langfuse_otel",
+                StandardCallbackDynamicParams(
+                    langfuse_public_key=public_key,
+                    langfuse_secret_key=secret_key,
+                    langfuse_host="https://lf.internal",
+                ),
+            )
+            assert destination is not None
+            return _sink_key(destination.endpoint, destination.headers)
+
+        assert sink("pk-op", "sk-op") in operator, "a team naming the operator's own project"
+        assert sink("pk-team", "sk-team") not in operator, "a different project on the same server"
+
+    def test_two_accounts_holding_the_same_strings_in_different_roles_are_not_one(self):
+        """The values alone are not the identity. Two accounts can hold the same pair
+        of strings with the space id and the api key the other way round, and folding
+        them together would leave the second one's team with no trace at all."""
+        endpoint = "https://otlp.arize.com/v1"
+
+        assert _sink_key(endpoint, {"space_id": "a", "api_key": "b"}) != _sink_key(
+            endpoint, {"space_id": "b", "api_key": "a"}
+        )
+
+    def test_the_operators_own_arize_space_and_a_team_naming_it_are_one_account(self, monkeypatch):
+        """One account answers to two header names here: the operator's exporter sends
+        ``space_id`` and a team destination sends ``arize-space-id``. Keyed on the names,
+        additive would write the operator's own space twice for every request."""
+        monkeypatch.setenv("ARIZE_SPACE_ID", "space-op")
+        monkeypatch.setenv("ARIZE_API_KEY", "key-op")
+        monkeypatch.delenv("ARIZE_SPACE_KEY", raising=False)
+        operator = operator_sink_keys(arize_preset())
+
+        def sink(space, api_key):
+            destination = destination_for(
+                "arize",
+                StandardCallbackDynamicParams(arize_space_key=space, arize_api_key=api_key),
+            )
+            assert destination is not None
+            return _sink_key(destination.endpoint, destination.headers)
+
+        assert sink("space-op", "key-op") in operator, "a team naming the operator's own space"
+        assert sink("space-team", "key-team") not in operator, "a different Arize space"
+
+
+class TestFanOut:
+    def test_every_span_of_the_request_reaches_the_destination_in_one_trace(self):
+        """The whole tree, gen-AI span included, parented as the operator would see it."""
+        dest_exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+        tracer = get_tracer(provider, "litellm")
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            with tracer.start_as_current_span("POST /v1/chat/completions"):
+                with tracer.start_as_current_span("auth /v1/chat/completions"):
+                    pass
+                with tracer.start_as_current_span("chat gpt-4"):
+                    pass
+
+        in_fresh_context(run)
+
+        spans = dest_exporter.get_finished_spans()
+        by_name = {s.name: s for s in spans}
+        assert set(by_name) == {"POST /v1/chat/completions", "auth /v1/chat/completions", "chat gpt-4"}
+        root = by_name["POST /v1/chat/completions"]
+        assert len({s.context.trace_id for s in spans}) == 1, "the tenant must receive one connected trace"
+        for child in ("auth /v1/chat/completions", "chat gpt-4"):
+            assert by_name[child].parent.span_id == root.context.span_id
+
+    def test_a_team_naming_two_backends_gets_the_trace_at_both(self):
+        """The fan-out rides one provider, so it cannot skip a destination on the
+        grounds that some other backend owns it: nothing else would deliver it."""
+        langfuse, arize = InMemorySpanExporter(), InMemorySpanExporter()
+        by_endpoint = {"http://a.local": langfuse, "http://b.local": arize}
+        provider = TracerProvider()
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda d: SimpleSpanProcessor(by_endpoint[d.endpoint]))
+        )
+
+        def run():
+            set_request_destinations(
+                (
+                    OtelDestination(endpoint="http://a.local", callback_name="langfuse_otel"),
+                    OtelDestination(endpoint="http://b.local", callback_name="arize"),
+                )
+            )
+            emit(provider)
+
+        in_fresh_context(run)
+
+        assert [s.name for s in langfuse.get_finished_spans()] == ["chat gpt-4"]
+        assert [s.name for s in arize.get_finished_spans()] == ["chat gpt-4"]
+
+    def test_a_destination_carries_the_tenants_service_name(self):
+        """An overridden backend skips per-request tracer routing, so the service name
+        that route used to apply has to travel on the destination instead."""
+        dest = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest)))
+
+        def run():
+            set_request_destinations(
+                (
+                    OtelDestination(
+                        endpoint="http://a.local",
+                        callback_name="langfuse_otel",
+                        resource_attributes={"service.name": "team-checkout"},
+                    ),
+                )
+            )
+            emit(provider)
+
+        in_fresh_context(run)
+
+        assert {s.resource.attributes["service.name"] for s in dest.get_finished_spans()} == {"team-checkout"}
+
+    def test_the_operators_database_endpoint_does_not_ride_along_to_the_tenant(self):
+        """A database span describes the proxy's own Postgres, so the tenant gets the
+        span and its timing without the host, the port, the schema or the error text
+        that names them. The operator's own copy keeps everything."""
+        dest_exporter, operator_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(operator_exporter))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+        tracer = get_tracer(provider, "litellm")
+        unreachable = "Can't reach database server at db.internal.example:15400"
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            with tracer.start_as_current_span("postgres get_data") as db_span:
+                db_span.set_attributes(
+                    {
+                        "db.system.name": "postgresql",
+                        "db.system": "postgresql",
+                        "db.operation.name": "get_data",
+                        "server.address": "db.internal.example",
+                        "server.port": 15400,
+                        "db.namespace": "litellm",
+                        "error.type": "PrismaError",
+                        "error.message": unreachable,
+                        "error": unreachable,
+                        "litellm.provider.error.stack_trace": f"Traceback: {unreachable}",
+                    }
+                )
+                db_span.add_event("exception", {"exception.message": unreachable})
+                db_span.set_status(Status(StatusCode.ERROR, unreachable))
+            with tracer.start_as_current_span("chat claude-haiku") as llm_span:
+                llm_span.set_attribute("server.address", "api.anthropic.com")
+
+        in_fresh_context(run)
+
+        tenant = {s.name: s for s in dest_exporter.get_finished_spans()}
+        operator = {s.name: s for s in operator_exporter.get_finished_spans()}
+        assert set(tenant) == {"postgres get_data", "chat claude-haiku"}, "the tenant keeps the whole tree"
+        tenant_db = tenant["postgres get_data"]
+        assert dict(tenant_db.attributes) == {
+            "db.system.name": "postgresql",
+            "db.system": "postgresql",
+            "db.operation.name": "get_data",
+            "error.type": "PrismaError",
+        }
+        assert list(tenant_db.events) == []
+        assert tenant_db.status.status_code is StatusCode.ERROR, "the tenant still sees that the call failed"
+        assert tenant_db.status.description is None
+        assert "db.internal.example" not in tenant_db.to_json()
+        assert tenant["chat claude-haiku"].attributes["server.address"] == "api.anthropic.com", (
+            "only the operator's datastore is redacted, never the model endpoint"
+        )
+        operator_db = operator["postgres get_data"]
+        assert operator_db.attributes["server.address"] == "db.internal.example"
+        assert operator_db.attributes["server.port"] == 15400
+        assert operator_db.attributes["db.namespace"] == "litellm"
+        assert operator_db.attributes["error.message"] == unreachable
+        assert operator_db.attributes["error"] == unreachable
+        assert operator_db.status.description == unreachable
+        assert [event.name for event in operator_db.events] == ["exception"]
+
+    @pytest.mark.parametrize("failure_status", ["guardrail_failed_to_respond", "failure"])
+    def test_a_guardrails_failure_text_does_not_ride_along_to_the_tenant(self, failure_status):
+        dest_exporter, operator_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(operator_exporter))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+        tracer = get_tracer(provider, "litellm")
+        unreachable = "Cannot connect to host guardrail.internal.example:9000"
+        verdict = '{"action": "block", "categories": ["pii"]}'
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            with tracer.start_as_current_span("POST /v1/chat/completions"):
+                with tracer.start_as_current_span("execute_guardrail pii") as down:
+                    down.set_attributes(
+                        {
+                            "litellm.guardrail.name": "pii",
+                            "litellm.guardrail.status": failure_status,
+                            "litellm.guardrail.response": unreachable,
+                        }
+                    )
+                with tracer.start_as_current_span("execute_guardrail toxicity") as up:
+                    up.set_attributes(
+                        {
+                            "litellm.guardrail.name": "toxicity",
+                            "litellm.guardrail.status": "guardrail_intervened",
+                            "litellm.guardrail.response": verdict,
+                        }
+                    )
+
+        in_fresh_context(run)
+
+        tenant = {s.name: s for s in dest_exporter.get_finished_spans()}
+        operator = {s.name: s for s in operator_exporter.get_finished_spans()}
+        assert dict(tenant["execute_guardrail pii"].attributes) == {
+            "litellm.guardrail.name": "pii",
+            "litellm.guardrail.status": failure_status,
+        }
+        assert "guardrail.internal.example" not in tenant["execute_guardrail pii"].to_json()
+        assert tenant["execute_guardrail toxicity"].attributes["litellm.guardrail.response"] == verdict
+        assert operator["execute_guardrail pii"].attributes["litellm.guardrail.response"] == unreachable
+
+    def test_the_callers_key_in_the_query_string_does_not_ride_along_to_the_tenant(self):
+        """A Google AI Studio style request authenticates with ``?key=<virtual key>``,
+        and the instrumentor stamps the full request URL on the server span. The
+        tenant keeps the URL up to the query string, and the operator's copy keeps it
+        whole."""
+        dest_exporter, operator_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(operator_exporter))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+        tracer = get_tracer(provider, "litellm")
+        path = "/v1beta/models/gemini-2.5-flash:generateContent"
+        query = "key=sk-another-members-virtual-key&alt=sse"
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            with tracer.start_as_current_span(f"POST {path}") as server_span:
+                server_span.set_attributes(
+                    {
+                        "http.method": "POST",
+                        "http.route": path,
+                        "http.target": f"{path}?{query}",
+                        "http.url": f"http://proxy.example:4000{path}?{query}",
+                        "url.path": path,
+                        "url.query": query,
+                        "http.status_code": 200,
+                    }
+                )
+                with tracer.start_as_current_span("generate_content gemini-2.5-flash") as llm_span:
+                    llm_span.set_attributes(
+                        {
+                            "gen_ai.operation.name": "generate_content",
+                            "url.full": f"https://generativelanguage.googleapis.com{path}?key=AIza-operator-provider-key",
+                        }
+                    )
+
+        in_fresh_context(run)
+
+        tenant = {s.name: s for s in dest_exporter.get_finished_spans()}
+        assert dict(tenant[f"POST {path}"].attributes) == {
+            "http.method": "POST",
+            "http.route": path,
+            "http.target": path,
+            "http.url": f"http://proxy.example:4000{path}",
+            "url.path": path,
+            "http.status_code": 200,
+        }
+        assert "sk-another-members-virtual-key" not in tenant[f"POST {path}"].to_json()
+        assert tenant["generate_content gemini-2.5-flash"].attributes["url.full"] == (
+            f"https://generativelanguage.googleapis.com{path}"
+        ), "the tenant's own span keeps its error text, and still loses a query string"
+        operator = {s.name: s for s in operator_exporter.get_finished_spans()}
+        assert operator[f"POST {path}"].attributes["http.url"] == f"http://proxy.example:4000{path}?{query}"
+        assert operator[f"POST {path}"].attributes["url.query"] == query
+        assert "AIza-operator-provider-key" in operator["generate_content gemini-2.5-flash"].to_json()
+
+    def test_captured_request_headers_do_not_ride_along_to_the_tenant(self):
+        """With ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST`` set, the
+        server span carries the caller's bearer token. A team admin's collector must
+        not receive it, while the operator's own copy keeps it and the tenant keeps the
+        rest of the span."""
+        dest_exporter, operator_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(operator_exporter))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+        tracer = get_tracer(provider, "litellm")
+        bearer = "Bearer sk-another-members-virtual-key"
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            with tracer.start_as_current_span("POST /v1/chat/completions") as server_span:
+                server_span.set_attributes(
+                    {
+                        "http.request.method": "POST",
+                        "http.route": "/v1/chat/completions",
+                        "http.request.header.authorization": (bearer,),
+                        "http.request.header.x_litellm_api_key": (bearer,),
+                        "http.response.header.set_cookie": ("session=abc",),
+                    }
+                )
+                server_span.set_status(Status(StatusCode.ERROR))
+
+        in_fresh_context(run)
+
+        tenant = dest_exporter.get_finished_spans()[0]
+        assert dict(tenant.attributes) == {"http.request.method": "POST", "http.route": "/v1/chat/completions"}
+        assert bearer not in tenant.to_json()
+        assert tenant.status.status_code is StatusCode.ERROR
+        operator = operator_exporter.get_finished_spans()[0]
+        assert operator.attributes["http.request.header.authorization"] == (bearer,)
+        assert operator.attributes["http.response.header.set_cookie"] == ("session=abc",)
+
+    def test_the_proxys_own_error_text_does_not_ride_along_to_the_tenant(self):
+        """Postgres failing during auth surfaces as a ``ProxyException`` whose message
+        quotes the Prisma error, so the auth span and the request root carry the
+        operator's database endpoint in ``error.message``, in the exception event and
+        in the status description. None of it is the tenant's, so it all comes off,
+        while the failure itself (its type, its code, its status) stays. The tenant's
+        own model call keeps its error text, less the stack trace that walks the
+        operator's install. The operator's copy keeps everything."""
+        dest_exporter, operator_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(operator_exporter))
+        provider.add_span_processor(
+            TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest_exporter))
+        )
+        tracer = get_tracer(provider, "litellm")
+        unreachable = "Authentication Error, Can't reach database server at db.internal.example:15400"
+        install = "/srv/litellm/.venv/lib/python3.13/site-packages/opentelemetry/trace/__init__.py"
+        provider_error = "AnthropicException - invalid x-api-key"
+
+        def fail(span, message: str) -> None:
+            span.set_attributes(
+                {
+                    "error.type": "ProxyException",
+                    "error.message": message,
+                    "litellm.provider.error.code": "500",
+                    "litellm.provider.error.stack_trace": f"Traceback\n  File {install}\n{message}",
+                }
+            )
+            span.add_event(
+                "exception",
+                {"exception.type": "ProxyException", "exception.message": message, "exception.stacktrace": install},
+            )
+            span.set_status(Status(StatusCode.ERROR, message))
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            with tracer.start_as_current_span("POST /v1/chat/completions") as root:
+                with tracer.start_as_current_span("auth /v1/chat/completions") as auth:
+                    fail(auth, unreachable)
+                with tracer.start_as_current_span("chat claude-haiku") as llm:
+                    llm.set_attribute("gen_ai.operation.name", "chat")
+                    fail(llm, provider_error)
+                fail(root, unreachable)
+
+        in_fresh_context(run)
+
+        tenant = {s.name: s for s in dest_exporter.get_finished_spans()}
+        operator = {s.name: s for s in operator_exporter.get_finished_spans()}
+        assert set(tenant) == {"POST /v1/chat/completions", "auth /v1/chat/completions", "chat claude-haiku"}
+        for name in ("POST /v1/chat/completions", "auth /v1/chat/completions"):
+            proxy_span = tenant[name]
+            assert dict(proxy_span.attributes) == {"error.type": "ProxyException", "litellm.provider.error.code": "500"}
+            assert list(proxy_span.events) == []
+            assert proxy_span.status.status_code is StatusCode.ERROR
+            assert proxy_span.status.description is None
+            assert "db.internal.example" not in proxy_span.to_json()
+            assert install not in proxy_span.to_json()
+        llm_span = tenant["chat claude-haiku"]
+        assert llm_span.attributes["error.message"] == provider_error, "the tenant's own call keeps its error text"
+        assert "litellm.provider.error.stack_trace" not in llm_span.attributes
+        assert llm_span.status.description == provider_error
+        assert [dict(event.attributes) for event in llm_span.events] == [
+            {"exception.type": "ProxyException", "exception.message": provider_error}
+        ]
+        assert install not in llm_span.to_json()
+        for name, message in (("auth /v1/chat/completions", unreachable), ("chat claude-haiku", provider_error)):
+            assert operator[name].attributes["error.message"] == message
+            assert install in operator[name].attributes["litellm.provider.error.stack_trace"]
+            assert operator[name].events[0].attributes["exception.stacktrace"] == install
+            assert operator[name].status.description == message
+
+    def test_a_tenants_service_name_is_layered_onto_the_operators_resource(self):
+        """The destination's ``service.name`` replaces the operator's on the tenant's
+        copy and every other resource attribute travels unchanged. Nothing is detected
+        afresh per span, so no attribute the operator did not configure appears."""
+        dest = InMemorySpanExporter()
+        provider = TracerProvider(
+            resource=Resource({"service.name": "litellm-proxy", "deployment.environment.name": "prod"})
+        )
+        provider.add_span_processor(TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(dest)))
+
+        def run():
+            set_request_destinations(
+                (
+                    OtelDestination(
+                        endpoint="http://a.local",
+                        callback_name="langfuse_otel",
+                        resource_attributes={"service.name": "team-checkout"},
+                    ),
+                )
+            )
+            emit(provider)
+
+        in_fresh_context(run)
+
+        (span,) = dest.get_finished_spans()
+        assert dict(span.resource.attributes) == {
+            "service.name": "team-checkout",
+            "deployment.environment.name": "prod",
+        }
+
+    def test_a_destination_that_cannot_build_a_processor_is_skipped_quietly(self):
+        """An unbuildable destination must not cost the caller its request."""
+        attempts = []
+        reached_the_end = []
+
+        def factory(destination):
+            attempts.append(destination.endpoint)
+
+        provider = TracerProvider()
+        provider.add_span_processor(TenantFanOutSpanProcessor(processor_factory=factory))
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            emit(provider)
+            reached_the_end.append(True)
+
+        in_fresh_context(run)
+
+        assert attempts == [LANGFUSE_DEST.endpoint]
+        assert reached_the_end == [True]
+
+    def test_an_unbuildable_destination_leaves_the_span_with_the_operator(self):
+        """Anchoring the destination is what makes the operator's exporter stand down
+        for the backend, so a destination nothing can deliver to must never be anchored,
+        or the span reaches neither account."""
+        global_exporter = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(_OverriddenBackendFilter(SimpleSpanProcessor(global_exporter), "langfuse_otel"))
+        provider.add_span_processor(TenantFanOutSpanProcessor(processor_factory=lambda _d: None))
+
+        def run():
+            set_request_destinations(deliverable_destinations((LANGFUSE_DEST,), provider))
+            emit(provider)
+            return request_destinations()
+
+        anchored = in_fresh_context(run)
+
+        assert anchored == ()
+        assert [s.name for s in global_exporter.get_finished_spans()] == ["chat gpt-4"]
+
+    def test_a_buildable_destination_is_still_anchored_and_still_overrides(self):
+        global_exporter, dest_exporter = InMemorySpanExporter(), InMemorySpanExporter()
+        provider = wired_provider(dest_exporter, global_exporter)
+
+        def run():
+            set_request_destinations(deliverable_destinations((LANGFUSE_DEST,), provider))
+            emit(provider)
+            return request_destinations()
+
+        anchored = in_fresh_context(run)
+
+        assert anchored == (LANGFUSE_DEST,)
+        assert global_exporter.get_finished_spans() == ()
+        assert [s.name for s in dest_exporter.get_finished_spans()] == ["chat gpt-4"]
+
+    def test_only_the_unbuildable_destination_is_dropped_from_a_mixed_set(self):
+        dest_exporter = InMemorySpanExporter()
+        other = LANGFUSE_DEST.model_copy(update={"endpoint": "http://broken.local/otel"})
+        fan_out = TenantFanOutSpanProcessor(
+            processor_factory=lambda d: None if d.endpoint == other.endpoint else SimpleSpanProcessor(dest_exporter)
+        )
+
+        assert fan_out.deliverable((other, LANGFUSE_DEST)) == (LANGFUSE_DEST,)
+
+    def test_no_fan_out_means_nothing_is_anchored(self):
+        """With nothing to carry the spans to the tenant, anchoring would only stop the
+        operator's exporter from writing them."""
+        provider = TracerProvider()
+
+        assert deliverable_destinations((LANGFUSE_DEST,), provider) == ()
+
+    def test_a_protocol_with_no_otlp_transport_is_not_deliverable(self):
+        """An unknown exporter kind falls back to the console exporter, which ignores the
+        tenant's credentials and prints its spans to the proxy's stdout. Treating that as
+        deliverable would stand the operator's exporter down for spans nobody stores."""
+        typo = LANGFUSE_DEST.model_copy(update={"protocol": "consle"})
+        fan_out = TenantFanOutSpanProcessor()
+        try:
+            assert fan_out.deliverable((typo, LANGFUSE_DEST)) == (LANGFUSE_DEST,)
+        finally:
+            fan_out.shutdown()
+
+    def test_a_closed_fan_out_anchors_nothing(self):
+        fan_out = TenantFanOutSpanProcessor(processor_factory=lambda _d: SimpleSpanProcessor(InMemorySpanExporter()))
+        provider = TracerProvider()
+        provider.add_span_processor(fan_out)
+        fan_out.shutdown()
+
+        assert deliverable_destinations((LANGFUSE_DEST,), provider) == ()
+
+    def test_the_processor_built_to_check_deliverability_is_the_one_that_exports(self):
+        built = []
+
+        def factory(_destination):
+            built.append(SimpleSpanProcessor(InMemorySpanExporter()))
+            return built[-1]
+
+        provider = TracerProvider()
+        provider.add_span_processor(TenantFanOutSpanProcessor(processor_factory=factory))
+
+        def run():
+            set_request_destinations(deliverable_destinations((LANGFUSE_DEST,), provider))
+            emit(provider)
+
+        in_fresh_context(run)
+
+        assert len(built) == 1
+
+    def test_one_processor_is_reused_across_spans_of_the_same_destination(self):
+        built = []
+
+        def factory(_destination):
+            processor = SimpleSpanProcessor(InMemorySpanExporter())
+            built.append(processor)
+            return processor
+
+        provider = TracerProvider()
+        provider.add_span_processor(TenantFanOutSpanProcessor(processor_factory=factory))
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            emit(provider, "one")
+            emit(provider, "two")
+
+        in_fresh_context(run)
+
+        assert len(built) == 1
+
+
+class TestProviderWiring:
+    def test_build_tracer_provider_only_filters_when_asked(self):
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.LANGFUSE_OTEL)])
+        operator = build_tracer_provider(config, tenant_overrides=True)
+        tenant = build_tracer_provider(config)
+
+        def kinds(provider):
+            return [type(p).__name__ for p in provider._active_span_processor._span_processors]
+
+        assert "_OverriddenBackendFilter" in kinds(operator)
+        assert "_OverriddenBackendFilter" not in kinds(tenant), "a per-tenant provider must not filter itself out"
+        assert "TenantFanOutSpanProcessor" not in kinds(operator), "delivery belongs to the published global alone"
+        assert "TenantFanOutSpanProcessor" not in kinds(tenant)
+
+    def test_only_the_published_global_provider_delivers_to_tenants(self):
+        """A second v2 logger's provider never sees the server, auth or database spans,
+        so fanning out from it would hand the tenant a one-span trace. Publishing is
+        what picks the one provider the whole request tree passes through."""
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.ARIZE_AX)])
+        published, other = OpenTelemetryV2(config=config, callback_name="arize"), OpenTelemetryV2(config=config)
+
+        publish_global_otel_v2_provider([other], lambda _p: None, registered=published)
+
+        def kinds(logger):
+            return [type(p).__name__ for p in logger._tracer_provider._active_span_processor._span_processors]
+
+        assert kinds(published).count("TenantFanOutSpanProcessor") == 1
+        assert "TenantFanOutSpanProcessor" not in kinds(other)
+
+    @pytest.mark.parametrize("canonical", ["langfuse_otel", "arize"])
+    def test_publishing_tells_the_fan_out_about_every_v2_loggers_account(self, monkeypatch, canonical):
+        monkeypatch.setenv("LITELLM_OTEL_TENANT_DESTINATION_MODE", "additive")
+        shared = InMemorySpanExporter()
+        monkeypatch.setattr(otel_providers, "_destination_processor", lambda _d: SimpleSpanProcessor(shared))
+        accounts = {
+            "langfuse_otel": (
+                "https://cloud.langfuse.com/api/public/otel/v1/traces",
+                "authorization=Basic op",
+            ),
+            "arize": (
+                "https://otlp.arize.com/v1/traces",
+                "space_id=space-op,api_key=key-op",
+            ),
+        }
+        loggers = {
+            name: OpenTelemetryV2(
+                config=OpenTelemetryV2Config(
+                    exporters=(ExporterSpec(kind="otlp_http", endpoint=endpoint, headers=headers),)
+                ),
+                callback_name=name,
+                tracer_provider=TracerProvider(),
+            )
+            for name, (endpoint, headers) in accounts.items()
+        }
+        other = "arize" if canonical == "langfuse_otel" else "langfuse_otel"
+        published = publish_global_otel_v2_provider(
+            [loggers[other]],
+            lambda _p: None,
+            registered=loggers[canonical],
+        )
+
+        def destination(name, headers):
+            return OtelDestination(endpoint=accounts[name][0], headers=headers, callback_name=name)
+
+        def run(destinations):
+            set_request_destinations(destinations)
+            emit(published.tracer_provider)
+
+        in_fresh_context(run, (destination(canonical, dict(pair.split("=") for pair in accounts[canonical][1].split(","))),))
+        in_fresh_context(run, (destination(other, dict(pair.split("=") for pair in accounts[other][1].split(","))),))
+        assert shared.get_finished_spans() == (), "an account the operator already writes to was written twice"
+
+        in_fresh_context(run, (destination(other, {"authorization": "Basic team"}),))
+        assert [s.name for s in shared.get_finished_spans()] == ["chat gpt-4"]
+
+    def test_publishing_twice_does_not_double_export(self):
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.ARIZE_AX)])
+        logger = OpenTelemetryV2(config=config, callback_name="arize")
+
+        publish_global_otel_v2_provider([], lambda _p: None, registered=logger)
+        publish_global_otel_v2_provider([], lambda _p: None, registered=logger)
+
+        kinds = [type(p).__name__ for p in logger._tracer_provider._active_span_processor._span_processors]
+        assert kinds.count("TenantFanOutSpanProcessor") == 1
+
+    def test_anchoring_reads_the_fan_out_off_the_published_provider_not_the_otel_global(self, monkeypatch):
+        """``set_tracer_provider`` keeps the first provider it was handed. When
+        auto-instrumentation or a legacy logger claimed it before the proxy published,
+        the OTel global carries no fan-out, so reading it there would refuse every
+        destination the published provider delivers."""
+        from litellm.proxy import proxy_server
+
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.LANGFUSE_OTEL)])
+        logger = OpenTelemetryV2(config=config, callback_name="langfuse_otel")
+        publish_global_otel_v2_provider([], lambda _p: None, registered=logger)
+        monkeypatch.setattr(proxy_server, "open_telemetry_logger", logger)
+        claimed_first = TracerProvider()
+
+        assert fan_out_provider() is logger.tracer_provider
+        assert deliverable_destinations((LANGFUSE_DEST,), claimed_first) == ()
+        assert deliverable_destinations((LANGFUSE_DEST,), fan_out_provider()) == (LANGFUSE_DEST,)
+
+    def test_a_legacy_v1_logger_holding_the_registered_slot_does_not_hide_the_fan_out(self, monkeypatch):
+        """The proxy publishes with ``registered=None`` when ``open_telemetry_logger``
+        holds a v1 logger, so the fan-out lands on a v2 logger taken from
+        ``_in_memory_loggers``. Reading the registered slot finds no v2 logger there and
+        the OTel global belongs to v1, so both detours refuse every destination the
+        published provider delivers."""
+        from litellm.integrations.opentelemetry import OpenTelemetry
+        from litellm.proxy import proxy_server
+
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.LANGFUSE_OTEL)])
+        v2 = OpenTelemetryV2(config=config, callback_name="langfuse_otel")
+        publish_global_otel_v2_provider([v2], lambda _p: None, registered=None)
+        monkeypatch.setattr(proxy_server, "open_telemetry_logger", OpenTelemetry())
+
+        assert fan_out_provider() is v2.tracer_provider
+        assert deliverable_destinations((LANGFUSE_DEST,), fan_out_provider()) == (LANGFUSE_DEST,)
+
+    def test_without_a_publish_anchoring_attaches_fan_out_to_registered_v2_logger(self, monkeypatch):
+        from litellm.proxy import proxy_server
+
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.LANGFUSE_OTEL)])
+        logger = OpenTelemetryV2(config=config, callback_name="langfuse_otel")
+        monkeypatch.setattr(proxy_server, "open_telemetry_logger", logger)
+
+        assert fan_out_provider() is logger.tracer_provider
+        assert deliverable_destinations((LANGFUSE_DEST,), fan_out_provider()) == (LANGFUSE_DEST,)
+
+    def test_concurrent_anchoring_attaches_exactly_one_fan_out(self):
+        """Requests race to anchor when the startup publish never ran, and a fan-out
+        attached twice delivers every tenant span twice."""
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import attach_tenant_fan_out
+
+        class SlowAttachProvider(TracerProvider):
+            def add_span_processor(self, span_processor):
+                time.sleep(0.05)
+                super().add_span_processor(span_processor)
+
+        provider = SlowAttachProvider()
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.LANGFUSE_OTEL)])
+        barrier = threading.Barrier(8)
+
+        def anchor():
+            barrier.wait(timeout=10)
+            attach_tenant_fan_out(provider, config)
+
+        threads = [threading.Thread(target=anchor) for _ in range(8)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join(timeout=10)
+
+        kinds = [type(p).__name__ for p in provider._active_span_processor._span_processors]
+        assert kinds.count("TenantFanOutSpanProcessor") == 1, f"one fan-out per provider, got {kinds}"
+
+    def test_without_a_publish_anchoring_falls_back_to_the_otel_global(self, monkeypatch):
+        from opentelemetry import trace
+
+        from litellm.proxy import proxy_server
+
+        monkeypatch.setattr(proxy_server, "open_telemetry_logger", None)
+
+        assert fan_out_provider() is trace.get_tracer_provider()
+
+    def test_auth_seeds_the_request_with_destinations_the_registered_logger_can_deliver(
+        self, monkeypatch, allow_test_hosts
+    ):
+        from litellm.proxy import proxy_server
+        from litellm.proxy.auth.user_api_key_auth import _seed_request_destinations
+
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+        config = OpenTelemetryV2Config(exporters=[ExporterSpec(kind="in_memory", owner=ExporterOwner.LANGFUSE_OTEL)])
+        logger = OpenTelemetryV2(config=config, callback_name="langfuse_otel")
+        publish_global_otel_v2_provider([], lambda _p: None, registered=logger)
+        monkeypatch.setattr(proxy_server, "open_telemetry_logger", logger)
+        auth = UserAPIKeyAuth(
+            team_metadata={
+                "logging": [
+                    {
+                        "callback_name": "langfuse_otel",
+                        "callback_type": "success",
+                        "callback_vars": {
+                            "langfuse_public_key": "pk-team",
+                            "langfuse_secret_key": "sk-team",
+                            "langfuse_host": "http://team.local",
+                        },
+                    }
+                ]
+            }
+        )
+        expected = resolve_tenant_otel_destinations(auth)
+        assert expected, "the fixture must resolve to a destination for the test to mean anything"
+
+        def run():
+            _seed_request_destinations(auth)
+            return request_destinations()
+
+        assert deliverable_destinations(expected, TracerProvider()) == ()
+        assert in_fresh_context(run) == expected
+
+
+class TestRouting:
+    def test_an_overridden_backend_is_not_detached_onto_a_second_provider(self):
+        config = OpenTelemetryV2Config(
+            exporters=[ExporterSpec(kind="otlp_http", endpoint="http://op.local", owner=ExporterOwner.LANGFUSE_OTEL)]
+        )
+        cache = TenantTracerCache(config, "langfuse_otel", "litellm")
+        default = get_tracer(TracerProvider(), "litellm")
+        params = {"langfuse_public_key": "pk", "langfuse_secret_key": "sk"}
+
+        assert cache.route_for(default, params).detached is True
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return cache.route_for(default, params)
+
+        route = in_fresh_context(run)
+        assert route.detached is False
+        assert route.tracer is default
+        assert route.provider is None
+
+    def test_an_overridden_backend_does_not_detach_on_a_service_name_either(self):
+        """A key or team service name is its own reason to build a second provider, so
+        clearing only the credentials would still take the model call out of the tree."""
+        config = OpenTelemetryV2Config(
+            exporters=[ExporterSpec(kind="otlp_http", endpoint="http://op.local", owner=ExporterOwner.LANGFUSE_OTEL)]
+        )
+        cache = TenantTracerCache(config, "langfuse_otel", "litellm")
+        default = get_tracer(TracerProvider(), "litellm")
+        auth_metadata = {"otel_service_name": "team-checkout"}
+
+        assert cache.route_for(default, None, auth_metadata).detached is False
+        assert cache.route_for(default, None, auth_metadata).tracer is not default
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return cache.route_for(default, None, auth_metadata)
+
+        route = in_fresh_context(run)
+        assert route.tracer is default, "the fan-out carries the service name on the destination instead"
+        assert route.provider is None
+
+    @pytest.mark.parametrize("callback_name", ["arize", None])
+    def test_a_service_name_does_not_detach_a_backend_the_destination_does_not_name(self, callback_name):
+        """The fan-out only sees spans on the published provider, so relabelling this
+        logger's span onto a second provider would drop the model call out of the
+        trace another backend's destination receives."""
+        config = OpenTelemetryV2Config(
+            exporters=[ExporterSpec(kind="otlp_http", endpoint="http://op.local", owner=ExporterOwner.ARIZE_AX)]
+        )
+        cache = TenantTracerCache(config, callback_name, "litellm")
+        default = get_tracer(TracerProvider(), "litellm")
+        auth_metadata = {"otel_service_name": "team-checkout"}
+
+        relabelled = cache.route_for(default, None, auth_metadata)
+        assert relabelled.tracer is not default
+        cache.release(relabelled.provider)
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return cache.route_for(default, None, auth_metadata)
+
+        route = in_fresh_context(run)
+        assert route.tracer is default
+        assert route.detached is False
+        assert route.provider is None
+
+    @pytest.mark.parametrize(
+        ("owner", "params", "auth_metadata"),
+        [
+            (ExporterOwner.ARIZE_AX, {"arize_space_key": "space", "arize_api_key": "key"}, {}),
+            (ExporterOwner.ARIZE_PHOENIX, None, {"phoenix_project_name": "team-project"}),
+        ],
+    )
+    def test_a_backend_pointed_at_its_own_account_still_routes_next_to_another_backend_destination(
+        self, owner, params, auth_metadata
+    ):
+        """Credentials or a project name the tenant's own account for this backend, which
+        the other backend's destination cannot stand in for."""
+        config = OpenTelemetryV2Config(
+            exporters=[ExporterSpec(kind="otlp_http", endpoint="http://op.local", owner=owner)]
+        )
+        cache = TenantTracerCache(config, owner.value, "litellm")
+        default = get_tracer(TracerProvider(), "litellm")
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return cache.route_for(default, params, {"otel_service_name": "team-checkout", **auth_metadata})
+
+        route = in_fresh_context(run)
+        assert route.tracer is not default
+        assert route.detached is True
+        cache.release(route.provider)
+
+
+@pytest.mark.usefixtures("allow_test_hosts")
+class TestDestinationResolution:
+    def test_a_langfuse_key_pair_and_host_become_a_destination(self, monkeypatch):
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+        auth = UserAPIKeyAuth(
+            team_metadata={
+                "logging": [
+                    {
+                        "callback_name": "langfuse_otel",
+                        "callback_type": "success",
+                        "callback_vars": {
+                            "langfuse_public_key": "pk-team",
+                            "langfuse_secret_key": "sk-team",
+                            "langfuse_host": "http://team.local",
+                        },
+                    }
+                ]
+            }
+        )
+
+        destinations = resolve_tenant_otel_destinations(auth)
+
+        assert [d.endpoint for d in destinations] == ["http://team.local/api/public/otel"]
+        assert destinations[0].callback_name == "langfuse_otel"
+
+    def test_a_keys_service_name_outranks_its_teams_on_the_destination(self, monkeypatch):
+        """The key/team ``otel_service_name`` used to reach the backend through
+        per-request tracer routing, which an overridden backend skips."""
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+        auth = UserAPIKeyAuth(
+            metadata={"otel_service_name": "key-svc"},
+            team_metadata={
+                "otel_service_name": "team-svc",
+                "logging": [
+                    {
+                        "callback_name": "langfuse_otel",
+                        "callback_type": "success",
+                        "callback_vars": {
+                            "langfuse_public_key": "pk-team",
+                            "langfuse_secret_key": "sk-team",
+                            "langfuse_host": "http://team.local",
+                        },
+                    }
+                ],
+            },
+        )
+
+        destinations = resolve_tenant_otel_destinations(auth)
+
+        assert dict(destinations[0].resource_attributes) == {"service.name": "key-svc"}
+
+    def test_a_team_that_named_no_service_name_gets_no_resource_override(self, monkeypatch):
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+        auth = UserAPIKeyAuth(
+            team_metadata={
+                "otel_service_name": "   ",
+                "logging": [
+                    {
+                        "callback_name": "langfuse_otel",
+                        "callback_type": "success",
+                        "callback_vars": {
+                            "langfuse_public_key": "pk-team",
+                            "langfuse_secret_key": "sk-team",
+                            "langfuse_host": "http://team.local",
+                        },
+                    }
+                ],
+            }
+        )
+
+        destinations = resolve_tenant_otel_destinations(auth)
+
+        assert dict(destinations[0].resource_attributes) == {}
+
+    def test_the_key_wins_over_the_team_for_the_same_backend(self, monkeypatch):
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+
+        def entry(host: str) -> Mapping[str, object]:
+            return {
+                "callback_name": "langfuse_otel",
+                "callback_type": "success",
+                "callback_vars": {
+                    "langfuse_public_key": "pk",
+                    "langfuse_secret_key": "sk",
+                    "langfuse_host": host,
+                },
+            }
+
+        auth = UserAPIKeyAuth(
+            metadata={"logging": [entry("http://key.local")]},
+            team_metadata={"logging": [entry("http://team.local")]},
+        )
+
+        assert [d.endpoint for d in resolve_tenant_otel_destinations(auth)] == ["http://key.local/api/public/otel"]
+
+    def test_nothing_resolves_while_otel_v2_is_off(self, monkeypatch):
+        monkeypatch.delenv("LITELLM_OTEL_V2", raising=False)
+        is_otel_v2_enabled.cache_clear()
+        auth = UserAPIKeyAuth(
+            team_metadata={
+                "logging": [
+                    {
+                        "callback_name": "langfuse_otel",
+                        "callback_type": "success",
+                        "callback_vars": {"langfuse_public_key": "pk", "langfuse_secret_key": "sk"},
+                    }
+                ]
+            }
+        )
+
+        assert resolve_tenant_otel_destinations(auth) == ()
+
+    def test_a_host_without_its_key_pair_resolves_to_nothing(self):
+        assert destination_for("langfuse_otel", {"langfuse_host": "http://team.local"}) is None
+
+    def test_a_backend_with_no_dynamic_credentials_has_no_destination(self):
+        assert "arize_phoenix" not in destination_capable_backends()
+        assert destination_for("arize_phoenix", {"arize_api_key": "k"}) is None
+
+    def test_the_destination_header_string_survives_the_exporter_round_trip(self):
+        from litellm.integrations.otel.plumbing.providers import parse_headers
+
+        destination = destination_for(
+            "langfuse_otel",
+            {"langfuse_public_key": "pk", "langfuse_secret_key": "sk", "langfuse_host": "http://x"},
+        )
+        assert parse_headers(destination.header_string())["authorization"] == destination.headers["Authorization"]
+
+
+#: Anything that makes ``OpenTelemetryV2Config`` synthesize a real operator destination.
+_OTEL_SHORTHAND_ENV = (
+    "OTEL_ENDPOINT",
+    "OTEL_HEADERS",
+    "OTEL_EXPORTER",
+    "OTEL_EXPORTER_OTLP_ENDPOINT",
+    "OTEL_EXPORTER_OTLP_HEADERS",
+    "OTEL_EXPORTER_OTLP_PROTOCOL",
+)
+
+
+def credential_less_proxy(monkeypatch) -> None:
+    """An operator with no Langfuse account and no generic OTLP collector."""
+    for name in ("LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", *_OTEL_SHORTHAND_ENV):
+        monkeypatch.delenv(name, raising=False)
+    with pytest.raises(ValueError, match="LANGFUSE_PUBLIC_KEY"):
+        langfuse_preset()
+
+
+class TestPresetDegradation:
+    def test_a_credential_less_langfuse_exports_nowhere_instead_of_to_the_console(self, monkeypatch, capfd):
+        """``_normalize`` folds a console exporter in for an empty list, which would
+        print every span on a proxy whose teams bring their own credentials."""
+        credential_less_proxy(monkeypatch)
+
+        config = langfuse_preset(allow_missing_credentials=True)
+        provider = build_tracer_provider(config, tenant_overrides=True)
+        capfd.readouterr()
+        in_fresh_context(emit, provider)
+        provider.force_flush()
+
+        assert '"name": "chat gpt-4"' not in capfd.readouterr().out
+        assert "langfuse" in config.mapper_names
+
+    def test_langfuse_still_raises_for_a_global_callback_with_no_credentials(self, monkeypatch):
+        monkeypatch.delenv("LANGFUSE_PUBLIC_KEY", raising=False)
+        monkeypatch.delenv("LANGFUSE_SECRET_KEY", raising=False)
+
+        with pytest.raises(ValueError, match="LANGFUSE_PUBLIC_KEY"):
+            langfuse_preset()
+
+    def test_a_credential_less_proxy_builds_the_gated_logger_beside_a_v2_carrier(self, monkeypatch):
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        credential_less_proxy(monkeypatch)
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        carrier = build_otel_v2_logger(OpenTelemetryV2Config(exporter="in_memory"))
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return _maybe_construct_otel_v2("langfuse_otel", [carrier])
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(run)
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is not None
+        assert all(spec.requires_headers and not spec.headers for spec in logger.config.exporters)
+
+    def test_a_credential_less_proxy_with_no_destinations_falls_back_to_the_legacy_path(self, monkeypatch):
+        """Nothing can use a credential-less langfuse here, so the operator has to get
+        the same story as before v2: the legacy integration, not a global provider
+        that exports nowhere."""
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        credential_less_proxy(monkeypatch)
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(_maybe_construct_otel_v2, "langfuse_otel", [])
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is None
+
+    def test_a_valid_newrelic_base_exporter_survives_without_a_license_key(self, monkeypatch):
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        monkeypatch.delenv("NEW_RELIC_LICENSE_KEY", raising=False)
+        monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://collector.local:4318")
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(_maybe_construct_otel_v2, "newrelic", [])
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is not None
+        assert [spec.endpoint for spec in logger.config.exporters] == [
+            "http://collector.local:4318",
+            "https://otlp.nr-data.net",
+        ]
+
+    def test_a_credentialless_newrelic_without_a_base_exporter_falls_back(self, monkeypatch):
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        monkeypatch.delenv("NEW_RELIC_LICENSE_KEY", raising=False)
+        for name in _OTEL_SHORTHAND_ENV:
+            monkeypatch.delenv(name, raising=False)
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(_maybe_construct_otel_v2, "newrelic", [])
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is None
+
+    def test_an_explicit_console_exporter_keeps_a_credentialless_preset_on_v2(self, monkeypatch, capfd):
+        """``OTEL_EXPORTER=console`` reads exactly like the placeholder ``_normalize``
+        folds in, but the operator asked for it, so a credential-less New Relic keeps
+        the V2 logger and its spans reach stdout instead of the legacy path."""
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        monkeypatch.delenv("NEW_RELIC_LICENSE_KEY", raising=False)
+        for name in _OTEL_SHORTHAND_ENV:
+            monkeypatch.delenv(name, raising=False)
+        monkeypatch.setenv("OTEL_EXPORTER", "console")
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(_maybe_construct_otel_v2, "newrelic", [])
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is not None
+        assert logger.config.exporters[0].kind == "console"
+        assert not logger.config.exporters[0].requires_headers
+
+    def test_a_destination_for_one_backend_does_not_degrade_another(self, monkeypatch):
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        credential_less_proxy(monkeypatch)
+        monkeypatch.delenv("WANDB_API_KEY", raising=False)
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return _maybe_construct_otel_v2("weave_otel", [])
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(run)
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is None
+
+    def test_the_exporter_less_logger_is_not_reused_by_a_request_without_destinations(self, monkeypatch):
+        """Reusing it would let one team's destination decide how every later request
+        without one is logged, long after the degrade was justified."""
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        credential_less_proxy(monkeypatch)
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        loggers = [build_otel_v2_logger(OpenTelemetryV2Config(exporter="in_memory"))]
+
+        def with_destination():
+            set_request_destinations((LANGFUSE_DEST,))
+            return _maybe_construct_otel_v2("langfuse_otel", loggers)
+
+        is_otel_v2_enabled.cache_clear()
+        degraded = in_fresh_context(with_destination)
+        plain = in_fresh_context(_maybe_construct_otel_v2, "langfuse_otel", loggers)
+        is_otel_v2_enabled.cache_clear()
+
+        assert degraded is not None
+        assert plain is None
+
+    def test_a_credentialed_logger_is_still_reused_across_requests(self, monkeypatch):
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        monkeypatch.setenv("LANGFUSE_PUBLIC_KEY", "pk-lf-1")
+        monkeypatch.setenv("LANGFUSE_SECRET_KEY", "sk-lf-1")
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        loggers = []
+
+        is_otel_v2_enabled.cache_clear()
+        first = in_fresh_context(_maybe_construct_otel_v2, "langfuse_otel", loggers)
+        second = in_fresh_context(_maybe_construct_otel_v2, "langfuse_otel", loggers)
+        is_otel_v2_enabled.cache_clear()
+
+        assert first is not None
+        assert second is first
+
+    @staticmethod
+    def _degraded_langfuse_beside(loggers, monkeypatch):
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        credential_less_proxy(monkeypatch)
+        monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://collector.local:4318")
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return _maybe_construct_otel_v2("langfuse_otel", loggers)
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(run)
+        is_otel_v2_enabled.cache_clear()
+        assert logger is not None
+        return logger
+
+    def test_a_degraded_logger_beside_another_v2_logger_leaves_the_collector_to_it(self, monkeypatch):
+        """The other logger's provider already exports every span to the operator's
+        collector, so a second model span from this one would land there twice."""
+        collector_logger = build_otel_v2_logger(OpenTelemetryV2Config(exporter="in_memory"))
+
+        logger = self._degraded_langfuse_beside([collector_logger], monkeypatch)
+
+        assert [spec.endpoint for spec in logger.config.exporters] == [None]
+        assert all(spec.requires_headers and not spec.headers for spec in logger.config.exporters)
+
+    @pytest.mark.parametrize("registered", [(), (CustomLogger(),)])
+    def test_a_credential_less_proxy_with_a_destination_but_no_v2_carrier_falls_back(self, monkeypatch, registered):
+        """Only a V2 logger publishes the provider the fan-out rides on, so a legacy
+        callback beside this one leaves the destination just as unreachable as no
+        callback at all, and the operator keeps the pre-V2 story."""
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        credential_less_proxy(monkeypatch)
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+
+        def run():
+            set_request_destinations((LANGFUSE_DEST,))
+            return _maybe_construct_otel_v2("langfuse_otel", list(registered))
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(run)
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is None
+
+    def test_a_credentialed_logger_beside_another_v2_logger_keeps_every_exporter(self, monkeypatch):
+        """Only a degraded preset gives the collector up; an operator who configured
+        both the backend and the collector still exports to both, as on base."""
+        from litellm.litellm_core_utils.litellm_logging import _maybe_construct_otel_v2
+
+        monkeypatch.setenv("LANGFUSE_PUBLIC_KEY", "pk-lf-1")
+        monkeypatch.setenv("LANGFUSE_SECRET_KEY", "sk-lf-1")
+        monkeypatch.setenv("LANGFUSE_HOST", "https://cloud.langfuse.com")
+        monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://collector.local:4318")
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        collector_logger = build_otel_v2_logger(OpenTelemetryV2Config(exporter="in_memory"))
+
+        is_otel_v2_enabled.cache_clear()
+        logger = in_fresh_context(_maybe_construct_otel_v2, "langfuse_otel", [collector_logger])
+        is_otel_v2_enabled.cache_clear()
+
+        assert logger is not None
+        assert [spec.endpoint for spec in logger.config.exporters] == [
+            "http://collector.local:4318",
+            "https://cloud.langfuse.com/api/public/otel",
+        ]
+        assert all(spec.headers for spec in logger.config.exporters if spec.requires_headers)
+
+
+class TestContextIsolation:
+    def test_destinations_do_not_leak_between_requests(self):
+        def first():
+            set_request_destinations((LANGFUSE_DEST,))
+            return destination_backends()
+
+        assert in_fresh_context(first) == frozenset({"langfuse_otel"})
+        assert in_fresh_context(request_destinations) == ()
+
+
+class TestOperatorShorthandSurvivesDegradation:
+    def test_a_generic_otlp_collector_keeps_receiving_when_langfuse_has_no_credentials(self, monkeypatch):
+        """Only the stdout placeholder is dropped. An operator who set the standard
+        OTLP env vars configured a real destination and must keep it."""
+        monkeypatch.delenv("LANGFUSE_PUBLIC_KEY", raising=False)
+        monkeypatch.delenv("LANGFUSE_SECRET_KEY", raising=False)
+        monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://collector.local:4318")
+
+        config = langfuse_preset(allow_missing_credentials=True)
+
+        assert [spec.endpoint for spec in config.exporters] == ["http://collector.local:4318", None]
+        assert [spec.kind for spec in config.exporters] == ["otlp_http", "console"]
+
+    def test_the_stdout_placeholder_is_still_dropped_when_it_is_the_only_exporter(self, monkeypatch):
+        credential_less_proxy(monkeypatch)
+
+        config = langfuse_preset(allow_missing_credentials=True)
+
+        assert all(spec.requires_headers and not spec.headers for spec in config.exporters)
+
+
+class TestBackendEndpointParity:
+    def test_arize_follows_its_own_http_endpoint_instead_of_the_grpc_default(self, monkeypatch):
+        monkeypatch.delenv("ARIZE_ENDPOINT", raising=False)
+        monkeypatch.setenv("ARIZE_HTTP_ENDPOINT", "https://otlp.arize.com/v1/traces")
+
+        destination = destination_for("arize", {"arize_space_id": "s", "arize_api_key": "k"})
+
+        assert destination.endpoint == "https://otlp.arize.com/v1/traces"
+        assert destination.protocol == "otlp_http"
+
+    def test_arize_uses_grpc_when_nothing_is_configured(self, monkeypatch):
+        monkeypatch.delenv("ARIZE_ENDPOINT", raising=False)
+        monkeypatch.delenv("ARIZE_HTTP_ENDPOINT", raising=False)
+
+        destination = destination_for("arize", {"arize_space_id": "s", "arize_api_key": "k"})
+
+        assert destination.endpoint == "https://otlp.arize.com/v1"
+        assert destination.protocol == "otlp_grpc"
+
+    def test_weave_follows_a_self_hosted_wandb_host(self, monkeypatch):
+        monkeypatch.setenv("WANDB_HOST", "weave.internal.example")
+
+        destination = destination_for("weave_otel", {"wandb_api_key": "k", "weave_project_id": "e/p"})
+
+        assert destination.endpoint == "https://weave.internal.example/otel/v1/traces"
+
+    def test_weave_uses_the_cloud_endpoint_without_a_host(self, monkeypatch):
+        monkeypatch.delenv("WANDB_HOST", raising=False)
+
+        destination = destination_for("weave_otel", {"wandb_api_key": "k", "weave_project_id": "e/p"})
+
+        assert destination.endpoint == "https://trace.wandb.ai/otel/v1/traces"
+
+
+class TestIncompleteCredentials:
+    """Half a credential set builds a non-empty but unusable header dict. Accepting it
+    would suppress the operator's exporter and send the trace where it cannot land."""
+
+    @pytest.mark.parametrize(
+        "callback_name,callback_vars",
+        [
+            ("arize", {"arize_api_key": "k"}),
+            ("arize", {"arize_space_id": "s"}),
+            ("weave_otel", {"wandb_api_key": "k"}),
+            ("weave_otel", {"weave_project_id": "e/p"}),
+            ("langfuse_otel", {"langfuse_public_key": "pk"}),
+        ],
+    )
+    def test_a_partial_credential_set_resolves_to_nothing(self, callback_name, callback_vars):
+        assert destination_for(callback_name, callback_vars) is None
+
+    @pytest.mark.parametrize(
+        "callback_name,callback_vars",
+        [
+            ("arize", {"arize_space_id": "s", "arize_api_key": "k"}),
+            ("weave_otel", {"wandb_api_key": "k", "weave_project_id": "e/p"}),
+            ("newrelic", {"newrelic_api_key": "k"}),
+        ],
+    )
+    def test_a_complete_credential_set_resolves(self, callback_name, callback_vars):
+        assert destination_for(callback_name, callback_vars) is not None
+
+
+@pytest.mark.usefixtures("allow_test_hosts")
+class TestCallbackTypeFilter:
+    @staticmethod
+    def _auth(callback_type: str | None) -> UserAPIKeyAuth:
+        return UserAPIKeyAuth(
+            team_metadata={
+                "logging": [
+                    {
+                        "callback_name": "langfuse_otel",
+                        "callback_type": callback_type,
+                        "callback_vars": {
+                            "langfuse_public_key": "pk",
+                            "langfuse_secret_key": "sk",
+                            "langfuse_host": "http://team.local",
+                        },
+                    }
+                ]
+            }
+        )
+
+    @pytest.mark.parametrize("callback_type", ["success", "success_and_failure", None])
+    def test_an_entry_that_wants_success_traces_gets_the_whole_trace(self, monkeypatch, callback_type):
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+
+        assert resolve_tenant_otel_destinations(self._auth(callback_type)) != ()
+
+    def test_a_failure_only_entry_does_not_take_over_the_trace(self, monkeypatch):
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        is_otel_v2_enabled.cache_clear()
+
+        assert resolve_tenant_otel_destinations(self._auth("failure")) == ()
+
+
+class TestTenantConfigAgreement:
+    """The destination resolver and ``convert_key_logging_metadata_to_callback`` read
+    the same stored config, so they must not read it two different ways."""
+
+    @pytest.fixture(autouse=True)
+    def _v2_on(self, monkeypatch):
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        monkeypatch.setattr(
+            litellm, "provider_url_destination_allowed_hosts", ["team.local", "key.local"], raising=False
+        )
+        is_otel_v2_enabled.cache_clear()
+        yield
+        is_otel_v2_enabled.cache_clear()
+
+    @staticmethod
+    def _entry(host, **extra):
+        return {
+            "callback_name": "langfuse_otel",
+            "callback_vars": {"langfuse_public_key": "pk", "langfuse_secret_key": "sk", "langfuse_host": host, **extra},
+        }
+
+    def test_a_key_that_disabled_its_callbacks_does_not_fall_back_to_the_team(self):
+        """Disabling a key's callbacks stores an empty list, which the sibling parser
+        reads as 'the key configured none'."""
+        auth = UserAPIKeyAuth(
+            metadata={"logging": []},
+            team_metadata={"logging": [self._entry("http://team.local")]},
+        )
+
+        assert resolve_tenant_otel_destinations(auth) == ()
+
+    def test_two_entries_for_one_backend_merge_their_vars_last_wins(self):
+        auth = UserAPIKeyAuth(
+            team_metadata={
+                "logging": [
+                    self._entry("http://team.local"),
+                    {"callback_name": "langfuse_otel", "callback_vars": {"langfuse_host": "http://key.local"}},
+                ]
+            }
+        )
+
+        destinations = resolve_tenant_otel_destinations(auth)
+
+        assert [d.endpoint for d in destinations] == ["http://key.local/api/public/otel"]
+
+    @pytest.fixture
+    def premium(self, monkeypatch):
+        from litellm.proxy import proxy_server
+
+        monkeypatch.setattr(proxy_server, "premium_user", True)
+        monkeypatch.setattr(litellm, "allow_dynamic_callback_disabling", True)
+
+    @pytest.mark.usefixtures("premium")
+    def test_a_backend_the_key_disabled_resolves_to_no_destination(self):
+        """Dispatch skips a callback named in the key's ``litellm_disabled_callbacks``,
+        so the fan-out must not deliver to it either."""
+        auth = UserAPIKeyAuth(
+            metadata={"litellm_disabled_callbacks": ["Langfuse_OTEL"]},
+            team_metadata={"logging": [self._entry("http://team.local")]},
+        )
+
+        assert resolve_tenant_otel_destinations(auth) == ()
+
+    @pytest.mark.usefixtures("premium")
+    @pytest.mark.parametrize(
+        ("header", "resolved"),
+        [
+            ("langfuse_otel", False),
+            (" LANGFUSE_OTEL ,arize", False),
+            ("arize", True),
+        ],
+    )
+    def test_the_disable_header_wins_over_the_key_list(self, header, resolved):
+        """Same precedence as dispatch: a header that names other backends re-enables
+        the one the key stored."""
+        auth = UserAPIKeyAuth(
+            metadata={"litellm_disabled_callbacks": ["langfuse_otel"]},
+            team_metadata={"logging": [self._entry("http://team.local")]},
+        )
+
+        destinations = resolve_tenant_otel_destinations(auth, {"x-litellm-disable-callbacks": header})
+
+        assert bool(destinations) is resolved
+
+    def test_a_non_premium_proxy_ignores_the_disabled_list_like_dispatch_does(self, monkeypatch):
+        from litellm.proxy import proxy_server
+
+        monkeypatch.setattr(proxy_server, "premium_user", False)
+        auth = UserAPIKeyAuth(
+            metadata={"litellm_disabled_callbacks": ["langfuse_otel"]},
+            team_metadata={"logging": [self._entry("http://team.local")]},
+        )
+
+        assert resolve_tenant_otel_destinations(auth, {"x-litellm-disable-callbacks": "langfuse_otel"}) != ()
+
+
+class TestEvictionSafety:
+    class Recording(SimpleSpanProcessor):
+        def __init__(self):
+            super().__init__(InMemorySpanExporter())
+            self.shutdown_calls = 0
+
+        def shutdown(self):
+            self.shutdown_calls += 1
+
+    def _fan_out(self):
+        built = []
+
+        def factory(_destination):
+            built.append(self.Recording())
+            return built[-1]
+
+        return TenantFanOutSpanProcessor(processor_factory=factory), built
+
+    @staticmethod
+    def _dest(index):
+        return LANGFUSE_DEST.model_copy(update={"endpoint": f"http://d{index}/otel"})
+
+    @staticmethod
+    def _settle(fan_out, processor=None):
+        """Wait for retirement to clear and, when given, for the drain to run.
+
+        The drain pool is shared and bounded, so a shed processor is closed once a
+        worker picks it up rather than the moment it is handed over.
+        """
+        for _ in range(500):
+            if not fan_out._retired and (processor is None or processor.shutdown_calls):
+                return
+            time.sleep(0.02)
+
+    def test_a_processor_still_exporting_a_span_is_not_closed_under_it(self):
+        """``on_end`` holds a processor across the export, so closing an evicted one
+        there drops the span it is holding."""
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        fan_out, built = self._fan_out()
+        held = fan_out._acquire(self._dest(0))
+        for index in range(1, _MAX_CACHED_DESTINATION_PROCESSORS + 1):
+            fan_out._acquire(self._dest(index))
+            fan_out._release(built[-1])
+
+        assert held.shutdown_calls == 0
+        assert id(held) in fan_out._retired
+
+        fan_out._release(held)
+        self._settle(fan_out, held)
+
+        assert held.shutdown_calls == 1
+
+    def test_a_recently_used_destination_is_not_the_one_evicted(self):
+        """Without the refresh the cache sheds by insertion order, so the busiest
+        destination is the one whose exporter is rebuilt on every overflow."""
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        fan_out, built = self._fan_out()
+        for index in range(_MAX_CACHED_DESTINATION_PROCESSORS):
+            fan_out._release(fan_out._acquire(self._dest(index)))
+        fan_out._release(fan_out._acquire(self._dest(0)))
+        fan_out._release(fan_out._acquire(self._dest(_MAX_CACHED_DESTINATION_PROCESSORS)))
+        self._settle(fan_out, built[1])
+
+        assert built[1].shutdown_calls == 1
+        assert built[0].shutdown_calls == 0, "the destination used most recently was the one shed"
+
+    def test_an_idle_evicted_processor_is_closed_off_the_export_path(self):
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        fan_out, built = self._fan_out()
+        for index in range(_MAX_CACHED_DESTINATION_PROCESSORS + 1):
+            fan_out._acquire(self._dest(index))
+            fan_out._release(built[-1])
+        self._settle(fan_out, built[0])
+
+        assert built[0].shutdown_calls == 1
+        assert len(fan_out._processors) == _MAX_CACHED_DESTINATION_PROCESSORS
+
+    def test_a_slow_collector_does_not_hold_up_the_export_path(self):
+        """``shutdown`` flushes over the network and is reached from ``on_end``, so
+        closing a shed processor inline lets one unreachable tenant collector stall
+        every other tenant's spans."""
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        class Slow(self.Recording):
+            def shutdown(self):
+                time.sleep(3)
+                super().shutdown()
+
+        built = []
+
+        def factory(_destination):
+            built.append(Slow())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory)
+        started = time.monotonic()
+        for index in range(_MAX_CACHED_DESTINATION_PROCESSORS + 1):
+            fan_out._acquire(self._dest(index))
+            fan_out._release(built[-1])
+
+        assert time.monotonic() - started < 2
+
+    def test_shedding_many_processors_does_not_spawn_a_thread_each(self):
+        """A tenant that cycles its destination config sheds a processor per request,
+        so a thread per shed processor is a thread per request against a slow
+        collector."""
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        release = threading.Event()
+
+        class Blocking(self.Recording):
+            def shutdown(self):
+                release.wait(timeout=10)
+                super().shutdown()
+
+        built = []
+
+        def factory(_destination):
+            built.append(Blocking())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory)
+        before = self._drain_workers()
+        try:
+            for index in range(_MAX_CACHED_DESTINATION_PROCESSORS + 30):
+                fan_out._acquire(self._dest(index))
+                fan_out._release(built[-1])
+            grew = self._drain_workers() - before
+            assert grew == 0, f"one drain thread per shed processor: {grew} new threads"
+        finally:
+            release.set()
+            self._settle(fan_out, built[0])
+
+    def test_a_saturated_drain_leaves_new_destinations_with_the_operator(self):
+        """A shed processor keeps its batch thread until its close returns, and against
+        a collector that never answers every close waits out the exporter's timeout.
+        Tenants rotating past the cache cap would otherwise queue one more processor,
+        and one more thread, per request for as long as the outage lasts."""
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        release = threading.Event()
+
+        class Blocking(self.Recording):
+            def shutdown(self):
+                release.wait(timeout=10)
+                super().shutdown()
+
+        built = []
+
+        def factory(_destination):
+            built.append(Blocking())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory, pending_drains=3)
+        try:
+            anchored = tuple(
+                fan_out.deliverable((self._dest(index),)) for index in range(_MAX_CACHED_DESTINATION_PROCESSORS + 40)
+            )
+
+            assert len(built) == _MAX_CACHED_DESTINATION_PROCESSORS + 3, "a processor per request during the outage"
+            assert sum(1 for accepted in anchored if accepted) == len(built), "anchored what it could not build"
+            assert fan_out.deliverable((self._dest(999),)) == (), "the span would vanish instead of staying with the operator"
+        finally:
+            release.set()
+        for _ in range(500):
+            if not fan_out._drain.saturated():
+                break
+            time.sleep(0.02)
+
+        assert fan_out.deliverable((self._dest(999),)) == (self._dest(999),), "the fan-out never recovered"
+
+    def test_an_anchored_destination_evicted_under_a_saturated_drain_still_gets_the_span(self):
+        """``deliverable`` accepted the destination, so the operator's exporter has stood
+        down for it. Other tenants' auths can then evict it, and the eviction is what
+        tips the drain into saturation, so refusing the rebuild at ``on_end`` would drop
+        the span outright."""
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        release = threading.Event()
+
+        class Blocking(self.Recording):
+            def shutdown(self):
+                release.wait(timeout=10)
+                super().shutdown()
+
+        built = []
+
+        def factory(_destination):
+            built.append(Blocking())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(
+            processor_factory=factory, pending_drains=_MAX_CACHED_DESTINATION_PROCESSORS + 1
+        )
+        provider = TracerProvider()
+        provider.add_span_processor(fan_out)
+        tracer = get_tracer(provider, "litellm")
+        anchored = self._dest(0)
+        try:
+            for index in range(1, _MAX_CACHED_DESTINATION_PROCESSORS + 1):
+                assert fan_out.deliverable((self._dest(index),))
+            assert fan_out.deliverable((anchored,)) == (anchored,)
+            first = built[-1]
+            for index in range(_MAX_CACHED_DESTINATION_PROCESSORS + 1, 2 * _MAX_CACHED_DESTINATION_PROCESSORS + 1):
+                assert fan_out.deliverable((self._dest(index),))
+            assert fan_out._drain.saturated(), "the anchored destination's own eviction saturates the drain"
+            assert first not in fan_out._processors.values(), "the anchored destination was not evicted"
+
+            def run():
+                set_request_destinations((anchored,))
+                with tracer.start_as_current_span("chat anthropic"):
+                    pass
+
+            before = len(built)
+            in_fresh_context(run)
+            assert len(built) == before + 1, "the anchored destination was not rebuilt, so its span went nowhere"
+            assert [span.name for span in built[-1].span_exporter.get_finished_spans()] == ["chat anthropic"]
+            assert first.span_exporter.get_finished_spans() == (), "the shed processor was handed out again"
+        finally:
+            release.set()
+
+    def _saturated_by_anchoring(self, pending_drains, extra):
+        """A fan-out whose drain ``extra`` anchorings past the cache cap have saturated.
+
+        Returns it with the processors built, the destinations that anchored, and the
+        event that lets the blocked closes finish.
+        """
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        release = threading.Event()
+
+        class Blocking(self.Recording):
+            def shutdown(self):
+                release.wait(timeout=10)
+                super().shutdown()
+
+        built = []
+
+        def factory(_destination):
+            built.append(Blocking())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory, pending_drains=pending_drains)
+        destinations = tuple(self._dest(index) for index in range(_MAX_CACHED_DESTINATION_PROCESSORS + extra))
+        anchored = tuple(destination for destination in destinations if fan_out.deliverable((destination,)))
+        assert fan_out._drain.saturated(), "anchoring past the cap did not saturate the drain"
+        assert len(anchored) > _MAX_CACHED_DESTINATION_PROCESSORS, "not enough destinations in flight to churn"
+        return fan_out, built, anchored, release
+
+    def test_anchored_rebuilds_under_a_saturated_drain_do_not_grow_with_the_spans(self):
+        """Every anchored rebuild past the cap evicts another anchored destination, whose
+        next span rebuilds it in turn. With more destinations in flight than the cache
+        holds, each span would then cost one more processor, one more batch thread and
+        one more close queued behind a collector that never answers."""
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        fan_out, built, anchored, release = self._saturated_by_anchoring(pending_drains=4, extra=8)
+        try:
+            after_anchoring = len(built)
+            for _ in range(5):
+                for destination in anchored:
+                    fan_out._release(fan_out._acquire(destination))
+
+            rebuilt = len(built) - after_anchoring
+            assert rebuilt == len(anchored) - _MAX_CACHED_DESTINATION_PROCESSORS, (
+                f"{rebuilt} rebuilds over 5 rounds of {len(anchored)} anchored destinations: one per evicted one expected"
+            )
+            assert len(fan_out._processors) == len(anchored), "an anchored destination was shed under a saturated drain"
+            assert all(destination in fan_out.deliverable((destination,)) for destination in anchored)
+        finally:
+            release.set()
+
+    def test_the_cache_returns_to_its_cap_once_the_drain_has_room(self):
+        """Holding above the cap is for the outage only: with the drain caught up, the
+        entries kept for the destinations in flight are the ones to shed."""
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        fan_out, built, anchored, release = self._saturated_by_anchoring(pending_drains=4, extra=8)
+        for destination in anchored:
+            fan_out._release(fan_out._acquire(destination))
+        assert len(fan_out._processors) > _MAX_CACHED_DESTINATION_PROCESSORS
+
+        release.set()
+        for _ in range(500):
+            for destination in anchored[-4:]:
+                fan_out._release(fan_out._acquire(destination))
+            if len(fan_out._processors) <= _MAX_CACHED_DESTINATION_PROCESSORS:
+                break
+            time.sleep(0.02)
+
+        assert len(fan_out._processors) == _MAX_CACHED_DESTINATION_PROCESSORS, "the cache never came back to its cap"
+        shed = len(built) - _MAX_CACHED_DESTINATION_PROCESSORS
+        for _ in range(500):
+            if sum(processor.shutdown_calls for processor in built) == shed:
+                break
+            time.sleep(0.02)
+
+        assert sum(processor.shutdown_calls for processor in built) == shed, "a shed processor was never closed"
+
+    def test_concurrent_eviction_cannot_build_between_retirement_and_drain_submission(self):
+        """A second request cannot build while the first eviction is being handed to
+        the drain, or concurrent churn can outrun the pending-drain limit."""
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import (
+            _DrainPool,
+            _MAX_CACHED_DESTINATION_PROCESSORS,
+        )
+
+        class GatedDrain(_DrainPool):
+            def __init__(self):
+                super().__init__(workers=0)
+                self.started = threading.Event()
+                self.release = threading.Event()
+
+            def saturated(self):
+                return False
+
+            def submit(self, processor):
+                if not self.started.is_set():
+                    self.started.set()
+                    self.release.wait(timeout=5)
+
+        built = []
+
+        def factory(_destination):
+            built.append(self.Recording())
+            return built[-1]
+
+        drain = GatedDrain()
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory, drain_pool=drain)
+        for index in range(_MAX_CACHED_DESTINATION_PROCESSORS):
+            fan_out._release(fan_out._acquire(self._dest(index)))
+
+        first = threading.Thread(target=lambda: fan_out._release(fan_out._acquire(self._dest(32))))
+        first.start()
+        assert drain.started.wait(timeout=5)
+        second = threading.Thread(target=lambda: fan_out._release(fan_out._acquire(self._dest(33))))
+        second.start()
+        time.sleep(0.1)
+
+        assert len(built) == _MAX_CACHED_DESTINATION_PROCESSORS + 1
+
+        drain.release.set()
+        first.join(timeout=5)
+        second.join(timeout=5)
+        assert not first.is_alive() and not second.is_alive()
+        assert len(built) == _MAX_CACHED_DESTINATION_PROCESSORS + 2
+
+    def test_drain_workers_are_daemons(self):
+        """Python joins a ThreadPoolExecutor's workers at interpreter exit, so one
+        unreachable tenant collector would hold the proxy open for its export
+        timeout on the way down."""
+        import threading
+
+        self._fan_out()
+        workers = [t for t in threading.enumerate() if t.name.startswith("litellm-otel-destination-drain")]
+
+        assert workers, "no drain worker was started"
+        assert all(t.daemon for t in workers), "a non-daemon drain worker blocks interpreter exit"
+
+    def test_a_burst_of_first_evictions_starts_one_set_of_drain_workers(self):
+        """A drain pool built lazily on first use is not built once: several threads
+        can each finish the build, and every pool but the winner is left with its
+        workers blocked on a queue nothing will ever feed again."""
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import (
+            _DRAIN_WORKERS,
+            _MAX_CACHED_DESTINATION_PROCESSORS,
+        )
+
+        for _ in range(3):
+            before = self._drain_workers()
+            fan_out, built = self._fan_out()
+            for index in range(_MAX_CACHED_DESTINATION_PROCESSORS):
+                fan_out._release(fan_out._acquire(self._dest(index)))
+            barrier = threading.Barrier(16)
+
+            def shed(index, fan_out=fan_out, barrier=barrier):
+                barrier.wait(timeout=10)
+                fan_out._release(fan_out._acquire(self._dest(index)))
+
+            threads = [
+                threading.Thread(target=shed, args=(_MAX_CACHED_DESTINATION_PROCESSORS + index,)) for index in range(16)
+            ]
+            for thread in threads:
+                thread.start()
+            for thread in threads:
+                thread.join(timeout=10)
+            self._settle(fan_out)
+
+            assert self._drain_workers() - before == _DRAIN_WORKERS
+
+    @staticmethod
+    def _drain_workers():
+        import threading
+
+        return len([t for t in threading.enumerate() if t.name.startswith("litellm-otel-destination-drain")])
+
+    def test_shutdown_does_not_close_a_processor_under_an_in_flight_export(self):
+        """``on_end`` runs on whichever thread ends a span, so it reaches the fan-out
+        while the SDK tears the provider down."""
+        import threading
+
+        fan_out, _ = self._fan_out()
+        held = fan_out._acquire(self._dest(0))
+        closed = threading.Thread(target=fan_out.shutdown)
+        closed.start()
+        try:
+            time.sleep(0.3)
+
+            assert held.shutdown_calls == 0, "closed a processor with a span still being forwarded"
+        finally:
+            fan_out._release(held)
+            closed.join(timeout=10)
+
+        assert held.shutdown_calls == 1
+
+    def test_a_closed_fan_out_builds_no_new_processor(self):
+        """A processor built after shutdown is one nothing will ever close, and it
+        exports to a tenant on a provider the SDK has already torn down."""
+        fan_out, built = self._fan_out()
+        fan_out.shutdown()
+
+        assert fan_out._acquire(self._dest(0)) is None
+        assert built == []
+
+    def test_shutdown_gives_up_on_an_export_that_never_finishes(self):
+        """The wait is bounded: an exporter stuck on a dead collector must not hold
+        the proxy open on the way down."""
+        import threading
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=lambda _d: self.Recording(), shutdown_drain_seconds=0.2)
+        fan_out._acquire(self._dest(0))
+        closed = threading.Thread(target=fan_out.shutdown)
+        closed.start()
+        closed.join(timeout=5)
+
+        assert not closed.is_alive(), "shutdown blocked on an export that never finished"
+
+    def test_shutdown_retires_the_drain_workers(self):
+        """A proxy that rebuilds its telemetry builds another fan-out, so workers that
+        outlive the one that started them are two more threads per reload."""
+        from litellm.integrations.otel.plumbing.providers import _DRAIN_WORKERS
+
+        before = self._drain_workers()
+        fan_out, _ = self._fan_out()
+        assert self._drain_workers() - before == _DRAIN_WORKERS
+
+        fan_out.shutdown()
+        for _ in range(500):
+            if self._drain_workers() == before:
+                break
+            time.sleep(0.02)
+
+        assert self._drain_workers() == before, "the drain workers outlived their fan-out"
+
+    def test_a_processor_shed_after_shutdown_is_still_closed(self):
+        """``close`` retires the workers, so anything handed to the pool afterwards
+        would sit in a queue nobody reads."""
+        fan_out, _ = self._fan_out()
+        stray = self.Recording()
+        fan_out.shutdown()
+        fan_out._drain.submit(stray)
+
+        for _ in range(500):
+            if stray.shutdown_calls:
+                break
+            time.sleep(0.02)
+
+        assert stray.shutdown_calls == 1
+
+    def test_releasing_a_straggler_after_shutdown_does_not_block_the_span_thread(self):
+        """The teardown deadline has already expired by then, so closing the straggler
+        inline would park whichever thread just ended a span on the very flush the
+        deadline gave up waiting for."""
+        import threading
+
+        never = threading.Event()
+
+        class Stuck(self.Recording):
+            def shutdown(self):
+                never.wait()
+
+        def factory(_destination):
+            return Stuck()
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory, shutdown_drain_seconds=0.05)
+        held = fan_out._acquire(self._dest(0))
+        fan_out.shutdown()
+
+        released = threading.Event()
+        caller = threading.Thread(target=lambda: (fan_out._release(held), released.set()), daemon=True)
+        caller.start()
+        came_back = released.wait(timeout=5)
+        never.set()
+
+        assert came_back, "the thread that ended the span was left holding a stuck teardown"
+
+    def test_shutdown_waits_out_an_export_that_lands_inside_the_bound(self):
+        """Without the wait the closing is left to a daemon thread, which the
+        interpreter can retire before it runs, so the last spans never reach the
+        tenant."""
+        import threading
+
+        fan_out, built = self._fan_out()
+        held = fan_out._acquire(self._dest(0))
+        threading.Timer(0.2, lambda: fan_out._release(held)).start()
+
+        fan_out.shutdown()
+
+        assert held.shutdown_calls == 1, "shutdown returned before the export it should have waited out"
+
+    def test_a_straggler_past_the_drain_bound_is_closed_by_its_own_thread(self):
+        """The wait is bounded so one dead collector cannot hold the proxy open, which
+        means a processor still exporting when it expires has to be left to the thread
+        holding it rather than closed under the span it is carrying."""
+        built = []
+
+        def factory(_destination):
+            built.append(self.Recording())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory, shutdown_drain_seconds=0.05)
+        held = fan_out._acquire(self._dest(0))
+
+        fan_out.shutdown()
+
+        assert held.shutdown_calls == 0
+
+        fan_out._release(held)
+        self._settle(fan_out, held)
+
+        assert held.shutdown_calls == 1
+
+    def test_a_processor_built_while_shutdown_waits_is_still_closed(self):
+        """Shutdown cannot slip between the build and the insert, which would leave a
+        live exporter, with its batch thread and its connection pool, in a map nothing
+        will read again."""
+        import threading
+
+        built = []
+
+        def slow(_destination):
+            time.sleep(0.4)
+            built.append(self.Recording())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=slow, shutdown_drain_seconds=0.05)
+        acquired = []
+        caller = threading.Thread(target=lambda: acquired.append(fan_out._acquire(self._dest(0))))
+        caller.start()
+        time.sleep(0.1)
+        fan_out.shutdown()
+        caller.join(timeout=10)
+
+        assert acquired == built, "the build shutdown waited out was thrown away"
+
+        fan_out._release(built[0])
+        self._settle(fan_out, built[0])
+
+        assert built[0].shutdown_calls == 1, "the exporter outlived the fan-out"
+        assert fan_out._processors == {}, "an exporter was left in a cleared cache"
+
+    def test_shutdown_returns_when_a_destination_never_finishes_closing(self):
+        """Closing an exporter flushes over the network and the SDK joins its own
+        worker with no timeout, so a tenant collector that answers but never finishes
+        a response would hold process teardown open for as long as it likes."""
+        import threading
+
+        never = threading.Event()
+
+        class Stuck(self.Recording):
+            def shutdown(self):
+                never.wait()
+
+        built = []
+
+        def factory(_destination):
+            built.append(Stuck())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory, shutdown_drain_seconds=0.3)
+        fan_out._release(fan_out._acquire(self._dest(0)))
+        returned = threading.Event()
+        threading.Thread(target=lambda: (fan_out.shutdown(), returned.set()), daemon=True).start()
+
+        came_back = returned.wait(timeout=8)
+        never.set()
+
+        assert came_back, "shutdown never returned while a collector held its exporter open"
+
+    def test_a_cold_cache_met_by_a_burst_builds_one_processor_per_destination(self):
+        """Building outside the cache lock let every thread of the burst construct its
+        own exporter, each with a batch thread and a connection pool, and shed all but
+        one into the drain."""
+        import threading
+
+        built = []
+
+        def factory(_destination):
+            time.sleep(0.01)
+            built.append(self.Recording())
+            return built[-1]
+
+        fan_out = TenantFanOutSpanProcessor(processor_factory=factory)
+        ready = threading.Barrier(8)
+
+        def acquire():
+            ready.wait()
+            fan_out._release(fan_out._acquire(self._dest(0)))
+
+        callers = [threading.Thread(target=acquire) for _ in range(8)]
+        for caller in callers:
+            caller.start()
+        for caller in callers:
+            caller.join(timeout=10)
+
+        assert len(built) == 1, f"one destination, {len(built)} exporters built"
+
+    def test_a_submit_racing_close_is_never_stranded_behind_the_sentinels(self):
+        """A submit that read the closed state and then let ``close`` run queues its
+        processor after every sentinel, where the workers have already exited."""
+        import queue
+        import threading
+
+        from litellm.integrations.otel.plumbing.providers import _DrainPool
+
+        at_the_put, close_returned = threading.Event(), threading.Event()
+
+        class Gated(queue.Queue):
+            def put(self, item, *args, **kwargs):
+                if item is not None:
+                    at_the_put.set()
+                    close_returned.wait(timeout=1)
+                super().put(item, *args, **kwargs)
+
+        pool = _DrainPool(pending=Gated())
+        submitted = self.Recording()
+        submitter = threading.Thread(target=pool.submit, args=(submitted,))
+        submitter.start()
+        assert at_the_put.wait(timeout=5)
+        closer = threading.Thread(target=pool.close)
+        closer.start()
+        closer.join(timeout=1.5)
+        close_returned.set()
+        submitter.join(timeout=5)
+        closer.join(timeout=5)
+        for _ in range(250):
+            if submitted.shutdown_calls:
+                break
+            time.sleep(0.02)
+
+        assert submitted.shutdown_calls == 1, "a processor was queued behind the sentinels and never closed"
+
+    def test_a_retired_processor_is_still_closed_after_shutdown(self):
+        """Eviction and shutdown can both land while a span is being forwarded, and the
+        evicted processor still has to be closed once that export returns."""
+        from litellm.integrations.otel.plumbing.providers import _MAX_CACHED_DESTINATION_PROCESSORS
+
+        fan_out, built = self._fan_out()
+        held = fan_out._acquire(self._dest(0))
+        for index in range(1, _MAX_CACHED_DESTINATION_PROCESSORS + 1):
+            fan_out._acquire(self._dest(index))
+            fan_out._release(built[-1])
+        fan_out.shutdown()
+
+        assert held.shutdown_calls == 0
+
+        fan_out._release(held)
+        self._settle(fan_out, held)
+
+        assert held.shutdown_calls == 1
+
+
+class TestCredentialGatedExporters:
+    def test_layering_a_second_preset_does_not_eat_the_first_gated_exporter(self, monkeypatch):
+        """``base.Preset`` advertises ``config_overrides`` layering, and the gated spec
+        is itself a console exporter with no endpoint."""
+        credential_less_proxy(monkeypatch)
+        from litellm.integrations.otel.presets.utils import credential_gated_exporters
+
+        once = credential_gated_exporters((), ExporterOwner.LANGFUSE_OTEL)
+        twice = credential_gated_exporters(once, ExporterOwner.WEAVE_OTEL)
+
+        assert [spec.owner for spec in twice] == [ExporterOwner.LANGFUSE_OTEL, ExporterOwner.WEAVE_OTEL]
+
+    def test_an_exporter_the_operator_configured_survives(self):
+        from litellm.integrations.otel.presets.utils import credential_gated_exporters
+
+        operator_console = ExporterSpec(kind="console", use_simple_processor=True)
+
+        kept = credential_gated_exporters((operator_console,), ExporterOwner.LANGFUSE_OTEL)
+
+        assert kept[0] == operator_console
+
+    def test_an_otlp_exporter_on_its_default_endpoint_survives(self):
+        """``OTEL_EXPORTER=otlp_http`` with no endpoint is a real collector on the SDK's
+        default port, not the placeholder, so the transport is what tells them apart."""
+        from litellm.integrations.otel.presets.utils import credential_gated_exporters
+
+        operator_otlp = ExporterSpec(kind="otlp_http", endpoint=None, headers=None)
+
+        kept = credential_gated_exporters((operator_otlp,), ExporterOwner.LANGFUSE_OTEL)
+
+        assert kept[0] == operator_otlp
+
+    def test_an_in_memory_exporter_the_operator_asked_for_survives(self):
+        """``OTEL_EXPORTER=in_memory`` stores spans, so it is a destination the operator
+        chose, not the placeholder that stands in for choosing nothing."""
+        from litellm.integrations.otel.presets.utils import credential_gated_exporters
+
+        operator_memory = ExporterSpec(kind="in_memory", endpoint=None, headers=None)
+
+        kept = credential_gated_exporters((operator_memory,), ExporterOwner.LANGFUSE_OTEL)
+
+        assert kept[0] == operator_memory
+
+    def test_the_synthesized_stdout_placeholder_is_dropped(self, monkeypatch):
+        from litellm.integrations.otel.presets.utils import credential_gated_exporters
+
+        for name in _OTEL_SHORTHAND_ENV:
+            monkeypatch.delenv(name, raising=False)
+        placeholder = OpenTelemetryV2Config().exporters[0]
+
+        kept = credential_gated_exporters((placeholder,), ExporterOwner.LANGFUSE_OTEL)
+
+        assert [spec.owner for spec in kept] == [ExporterOwner.LANGFUSE_OTEL]
+
+    def test_a_console_exporter_the_operator_named_survives(self, monkeypatch):
+        """Same kind, endpoint and headers as the placeholder; only the fact that the
+        operator set ``OTEL_EXPORTER`` tells them apart."""
+        from litellm.integrations.otel.presets.utils import credential_gated_exporters
+
+        for name in _OTEL_SHORTHAND_ENV:
+            monkeypatch.delenv(name, raising=False)
+        monkeypatch.setenv("OTEL_EXPORTER", "console")
+        operator_console = OpenTelemetryV2Config().exporters[0]
+
+        kept = credential_gated_exporters((operator_console,), ExporterOwner.LANGFUSE_OTEL)
+
+        assert kept[0] is operator_console
+
+
+class TestTenantHostSsrfGuard:
+    """Anyone who can mint a key can write ``langfuse_host``, so the host it names has
+    to be one the operator approved."""
+
+    @pytest.fixture(autouse=True)
+    def _guard_on(self, monkeypatch):
+        from litellm.integrations.otel.presets.destinations import _warn_host_not_allowlisted
+
+        monkeypatch.setattr(litellm, "provider_url_destination_allowed_hosts", [], raising=False)
+        _warn_host_not_allowlisted.cache_clear()
+        yield
+        _warn_host_not_allowlisted.cache_clear()
+
+    @staticmethod
+    def _langfuse(host: str) -> Mapping[str, str]:
+        return {"langfuse_public_key": "pk", "langfuse_secret_key": "sk", "langfuse_host": host}
+
+    @pytest.mark.parametrize(
+        "host",
+        [
+            "http://127.0.0.1:9111",
+            "http://169.254.169.254",
+            "http://10.0.0.5:3000",
+            "https://collector.example.com",
+            "https://langfuse.corp:99999",
+            "ftp://collector.example.com",
+        ],
+    )
+    def test_a_host_the_operator_never_approved_resolves_to_nothing(self, host):
+        assert destination_for("langfuse_otel", self._langfuse(host)) is None
+
+    def test_userinfo_naming_an_allowlisted_host_does_not_smuggle_a_second_one(self, monkeypatch):
+        """``https://allowed@10.0.0.5`` reads as the allowlisted host to the eye and
+        posts to 10.0.0.5 on the wire."""
+        monkeypatch.setattr(litellm, "provider_url_destination_allowed_hosts", ["collector.example.com"], raising=False)
+
+        assert destination_for("langfuse_otel", self._langfuse("https://collector.example.com@10.0.0.5")) is None
+
+    def test_a_malformed_host_does_not_take_the_other_backends_with_it(self, monkeypatch):
+        """``urlparse(...).port`` raises a bare ValueError, which would escape
+        ``destination_for`` and kill the whole resolution."""
+        monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+        monkeypatch.setenv("NEW_RELIC_OTEL_ENDPOINT", "https://otlp.nr-data.net")
+        monkeypatch.setattr(litellm, "provider_url_destination_allowed_hosts", ["collector.example.com"], raising=False)
+        is_otel_v2_enabled.cache_clear()
+        auth = UserAPIKeyAuth(
+            token="hashed",
+            team_metadata={
+                "logging": [
+                    {"callback_name": "langfuse_otel", "callback_vars": self._langfuse("https://lf.corp:99999")},
+                    {"callback_name": "newrelic", "callback_vars": {"newrelic_api_key": "nr"}},
+                ]
+            },
+        )
+
+        assert [d.callback_name for d in resolve_tenant_otel_destinations(auth)] == ["newrelic"]
+
+    def test_the_operator_can_allowlist_its_teams_internal_langfuse(self, monkeypatch):
+        monkeypatch.setattr(litellm, "provider_url_destination_allowed_hosts", ["127.0.0.1:9111"], raising=False)
+
+        destination = destination_for("langfuse_otel", self._langfuse("http://127.0.0.1:9111"))
+
+        assert destination.endpoint == "http://127.0.0.1:9111/api/public/otel"
+
+    def test_the_operators_own_internal_host_is_never_blocked(self, monkeypatch):
+        """The operator configures ``LANGFUSE_HOST`` themselves, so an internal
+        collector there is a deployment choice rather than caller-supplied input."""
+        monkeypatch.setenv("LANGFUSE_HOST", "http://127.0.0.1:9111")
+
+        destination = destination_for("langfuse_otel", {"langfuse_public_key": "pk", "langfuse_secret_key": "sk"})
+
+        assert destination.endpoint == "http://127.0.0.1:9111/api/public/otel"
+
+    def test_an_allowlisted_host_is_taken_without_resolving_it(self, monkeypatch):
+        """The check runs on the asyncio auth path, so it must not block on a name the
+        caller chose. ``.invalid`` never resolves, and it is still accepted."""
+        monkeypatch.setattr(litellm, "provider_url_destination_allowed_hosts", ["lf.invalid"], raising=False)
+
+        destination = destination_for("langfuse_otel", self._langfuse("https://lf.invalid"))
+
+        assert destination.endpoint == "https://lf.invalid/api/public/otel"
+
+    def test_a_rejected_host_is_warned_about_once(self, caplog):
+        with caplog.at_level("WARNING", logger="LiteLLM"):
+            for _ in range(3):
+                destination_for("langfuse_otel", self._langfuse("http://10.0.0.5:3000"))
+
+        assert sum("provider_url_destination_allowed_hosts" in record.message for record in caplog.records) == 1
diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_logger.py b/tests/test_litellm/integrations/otel/test_otel_v2_logger.py
index b735abaf7bf..2869c804c07 100644
--- a/tests/test_litellm/integrations/otel/test_otel_v2_logger.py
+++ b/tests/test_litellm/integrations/otel/test_otel_v2_logger.py
@@ -2041,7 +2041,7 @@ def test_select_global_otel_v2_logger_builds_one_when_none_registered():
     assert isinstance(chosen, OpenTelemetryV2)
 
 
-def test_publish_global_otel_v2_provider_sets_selected_logger_provider():
+def test_publish_global_otel_v2_provider_sets_selected_logger_provider(monkeypatch):
     """The startup publish must set the OTel global provider to the *selected*
     logger's provider (the preset logger that owns every exporter), so the FastAPI
     server span and the gen-ai spans share one provider and one trace.
@@ -2051,8 +2051,10 @@ def test_publish_global_otel_v2_provider_sets_selected_logger_provider():
     test would otherwise miss: that the published provider is the selected logger's,
     not some other.
     """
+    from litellm.integrations.otel import logger as otel_logger
     from litellm.integrations.otel.logger import publish_global_otel_v2_provider
 
+    monkeypatch.setattr(otel_logger, "_published_v2_provider", None)
     cfg = OpenTelemetryV2Config(exporter="in_memory")
     tp = providers.build_tracer_provider(cfg)
     preset_logger = OpenTelemetryV2(
diff --git a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
index b6366bc803e..6aa77745e3d 100644
--- a/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
+++ b/tests/test_litellm/litellm_core_utils/test_litellm_logging.py
@@ -6074,15 +6074,17 @@ def test_prompt_hooks_skip_prompt_managers_when_no_prompt_id(logging_obj, tmp_pa
         for hook in [cb for cb in litellm.callbacks if isinstance(cb, VectorStorePreCallHook)]:
             litellm.logging_callback_manager.remove_callback_from_list_by_object(litellm.callbacks, hook)
 def test_newrelic_dispatch_prefers_otel_v2_when_flag_on(monkeypatch):
-    """With LITELLM_OTEL_V2 on, the "newrelic" callback builds the OTel v2
-    logger (per-team credential routing); with the flag off (default) it keeps
-    the legacy agent-based logger, so existing deployments are untouched."""
+    """With LITELLM_OTEL_V2 on and operator credentials present, the "newrelic"
+    callback builds the OTel v2 logger (per-team credential routing); with the
+    flag off (default) it keeps the legacy agent-based logger, so existing
+    deployments are untouched."""
     from litellm.integrations.otel.logger import OpenTelemetryV2
     from litellm.integrations.otel.model.config import is_otel_v2_enabled
     from litellm.litellm_core_utils import litellm_logging as logging_module
 
     logging_module._in_memory_loggers.clear()
     monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+    monkeypatch.setenv("NEW_RELIC_LICENSE_KEY", "test-license-key")
     is_otel_v2_enabled.cache_clear()
     try:
         v2_logger = logging_module._init_custom_logger_compatible_class(
@@ -6137,6 +6139,7 @@ def test_get_custom_logger_compatible_class_finds_v2_newrelic(monkeypatch):
 
     logging_module._in_memory_loggers.clear()
     monkeypatch.setenv("LITELLM_OTEL_V2", "true")
+    monkeypatch.setenv("NEW_RELIC_LICENSE_KEY", "test-license-key")
     is_otel_v2_enabled.cache_clear()
     try:
         created = logging_module._init_custom_logger_compatible_class(
diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py
index 79a2a27bb6d..9b6eaba3177 100644
--- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py
+++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py
@@ -7638,6 +7638,75 @@ class TestMCPMetaTraceCarrier:
         assert _mcp_meta_trace_carrier(SimpleNamespace(meta=only_progress)) is None
 
 
+@pytest.mark.asyncio
+async def test_stateful_mcp_tool_call_uses_current_requests_otel_destinations() -> None:
+    from types import SimpleNamespace
+
+    from mcp.server.lowlevel.server import request_ctx
+    from mcp.shared.context import RequestContext
+
+    from litellm.integrations.otel.model.destination import OtelDestination
+    from litellm.integrations.otel.plumbing.context import (
+        request_destinations,
+        reset_request_destinations,
+        set_request_destinations,
+    )
+    from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
+        global_mcp_server_manager,
+    )
+    from litellm.proxy._experimental.mcp_server.server import (
+        _MCP_DESTINATIONS_SCOPE_KEY,
+        mcp_server_tool_call,
+        set_auth_context,
+    )
+    from litellm.proxy._experimental.mcp_server.tool_registry import (
+        global_mcp_tool_registry,
+    )
+
+    initialized_destination = OtelDestination(endpoint="https://initialize.example", callback_name="langfuse_otel")
+    current_destination = OtelDestination(endpoint="https://current.example", callback_name="arize")
+    server = MCPServer(
+        server_id="otel-context-test",
+        name="otelcontext",
+        transport=MCPTransport.http,
+        allow_all_keys=True,
+    )
+
+    async def observe_destinations() -> str:
+        assert request_destinations() == (current_destination,)
+        return "ok"
+
+    global_mcp_server_manager.registry[server.server_id] = server
+    global_mcp_server_manager.tool_name_to_mcp_server_name_mapping["otelcontext-observe"] = server.name
+    global_mcp_tool_registry.register_tool(
+        name="otelcontext-observe",
+        description="Observe request destinations",
+        input_schema={"type": "object"},
+        handler=observe_destinations,
+    )
+    set_auth_context(None, raw_headers={})
+    destinations_token = set_request_destinations((initialized_destination,))
+    scope = {_MCP_DESTINATIONS_SCOPE_KEY: (current_destination,)}
+    current_request_context = RequestContext(
+        request_id=1,
+        meta=None,
+        session=SimpleNamespace(),
+        lifespan_context=None,
+        request=SimpleNamespace(scope=scope),
+    )
+    request_token = request_ctx.set(current_request_context)
+    try:
+        result = await mcp_server_tool_call("otelcontext-observe", {})
+        assert result.isError is False
+        assert request_destinations() == (initialized_destination,)
+    finally:
+        request_ctx.reset(request_token)
+        reset_request_destinations(destinations_token)
+        global_mcp_tool_registry.tools.pop("otelcontext-observe", None)
+        global_mcp_server_manager.registry.pop(server.server_id, None)
+        global_mcp_server_manager.tool_name_to_mcp_server_name_mapping.pop("otelcontext-observe", None)
+
+
 @pytest.mark.asyncio
 async def test_get_allowed_mcp_servers_includes_active_servers_submitted_by_user():
     """BYOM submitters can see approved servers they submitted without allow_all_keys."""

From 075655c7eede921e176a4772ac6d53e119ff9c28 Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 16:55:40 -0700
Subject: [PATCH 31/31] test(azure_sentinel): pin batch_size as a per-request
 bound under concurrent events (#40320)

* test(azure_sentinel): pin batch_size as a per-request bound under concurrent events

Adds a regression test to the mapped Azure Sentinel test file for the concurrency scenario from LIT-6920: 40 records logged concurrently at batch_size=5 while each ingestion request is still in flight. Asserts no request carries more than batch_size records, every record arrives exactly once in order, and the queue is empty afterwards. Runs for both the standard log queue and the audit log queue.

The test fails on the tree before #39880 (whole shared queue serialized per threshold send, then cleared) and passes on current staging. It is independent of the size-split coverage that #39880 added for LIT-5899.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* test(azure_sentinel): gate the first send on events so later records provably arrive while it is in flight

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: yucheng <yucheng@berri.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../integrations/test_azure_sentinel.py       | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/tests/test_litellm/integrations/test_azure_sentinel.py b/tests/test_litellm/integrations/test_azure_sentinel.py
index 038197c06c5..ecb7afd4ffb 100644
--- a/tests/test_litellm/integrations/test_azure_sentinel.py
+++ b/tests/test_litellm/integrations/test_azure_sentinel.py
@@ -867,6 +867,45 @@ async def test_azure_sentinel_concurrent_threshold_sends_collapse_into_one_attem
     assert getattr(logger, queue_attr) == []
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("queue_attr, send_method, build_payloads", QUEUE_CASES)
+async def test_azure_sentinel_batch_size_bounds_every_request_under_concurrent_events(
+    queue_attr, send_method, build_payloads
+):
+    """Lowering batch_size is the documented way to stay under the ingestion cap, so no request may
+    carry more than batch_size records even when events keep landing while a send is on the wire,
+    and every one of those records still has to arrive exactly once."""
+    logger = _build_logger(batch_size=5)
+    records = build_payloads(40)
+
+    attempts = []
+    first_send_started = asyncio.Event()
+    release_first_send = asyncio.Event()
+
+    async def _on_ingest(data):
+        attempts.append([record["id"] for record in json.loads(data.decode("utf-8"))])
+        if len(attempts) == 1:
+            first_send_started.set()
+            await release_first_send.wait()
+        return _accepted()
+
+    _install_ingestion(logger, _on_ingest)
+
+    sends = [asyncio.create_task(_log(logger, queue_attr, record)) for record in records]
+    await asyncio.wait_for(first_send_started.wait(), timeout=10)
+
+    assert attempts == [[record["id"] for record in records[:5]]]
+    assert getattr(logger, queue_attr) == records[5:]
+
+    release_first_send.set()
+    await asyncio.wait_for(asyncio.gather(*sends), timeout=10)
+    await logger.flush_queue()
+
+    assert max(len(attempt) for attempt in attempts) <= 5
+    assert [record_id for attempt in attempts for record_id in attempt] == [record["id"] for record in records]
+    assert getattr(logger, queue_attr) == []
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize("queue_attr, send_method, build_payloads", QUEUE_CASES)
 async def test_azure_sentinel_requeues_a_cancelled_send(