Merge remote-tracking branch 'origin/litellm_internal_staging' into litellm_lit6103_tool_reference_passthrough

basedpyright-code-budget.json

@@ -84,7 +84,7 @@
     "limit": 56
   },
   "reportPrivateUsage": {
-    "limit": 1810
+    "limit": 1808
   },
   "reportRedeclaration": {
     "limit": 8
@@ -135,7 +135,7 @@
     "limit": 21
   },
   "reportUnusedFunction": {
-    "limit": 139
+    "limit": 138
   },
   "reportUnusedImport": {
     "limit": 544

enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py

@@ -1,6 +1,8 @@
 """
 Polls LiteLLM_ManagedObjectTable to check if the response is complete.
-Cost tracking is handled automatically by the get-responses call.
+Cost tracking is handled by the get-responses call, which prices normally only because the
+poll stamps itself with BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN; user-facing reads of the
+same route are non-inference and free.
 """
 
 from datetime import datetime, timedelta, timezone
@@ -9,12 +11,14 @@ from typing import TYPE_CHECKING, Dict, Optional, cast
 import litellm
 from litellm._logging import verbose_proxy_logger
 from litellm.constants import (
+    INTERNAL_CALL_ORIGIN_METADATA_KEY,
     MANAGED_OBJECT_STALENESS_CUTOFF_DAYS,
     MAX_OBJECTS_PER_POLL_CYCLE,
     STALE_OBJECT_CLEANUP_BATCH_SIZE,
 )
 from litellm.responses.utils import ResponsesAPIRequestUtils
 from litellm.types.llms.openai import ResponsesAPIResponse
+from litellm.types.utils import BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN
 
 if TYPE_CHECKING:
     from litellm.proxy.utils import PrismaClient, ProxyLogging
@@ -113,7 +117,8 @@ class CheckResponsesCost:
         Check if background responses are complete and track their cost.
         - Get all status="queued" or "in_progress" and file_purpose="response" jobs
         - Query the provider to check if response is complete
-        - Cost is automatically tracked by the get-responses call
+        - Cost is tracked by the get-responses call, billed because the poll is stamped
+          with BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN
         - Mark responses in a terminal state as complete in the database
         """
         try:
@@ -153,6 +158,7 @@ class CheckResponsesCost:
                 # Prepare metadata with model information for cost tracking
                 litellm_metadata = {
                     "user_api_key_user_id": job.created_by or "default-user-id",
+                    INTERNAL_CALL_ORIGIN_METADATA_KEY: BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN,
                 }
                 
                 # Add model information if available

litellm/constants.py

@@ -1364,8 +1364,6 @@ X_LITELLM_DISABLE_CALLBACKS: Final = "x-litellm-disable-callbacks"
 LITELLM_METADATA_FIELD: Final = "litellm_metadata"
 OLD_LITELLM_METADATA_FIELD: Final = "metadata"
 RETURN_RAW_MODEL_NAME_METADATA_KEY: Final = "_complexity_router_return_raw_model_name"
-AUTO_ROUTED_REQUEST_METADATA_KEY: Final = "_auto_routed_request"
-ROUTER_MODEL_NAME_RESPONSE_FIELD: Final = "router_model_name"
 SESSION_DEPLOYMENT_AFFINITY_TTL_METADATA_KEY: Final = "_session_deployment_affinity_ttl"
 CONSUMED_REQUEST_TAGS_METADATA_KEY: Final = "_consumed_request_tags"
 INTERNAL_CALL_ORIGIN_METADATA_KEY: Final = "internal_call_origin"
@@ -1814,6 +1812,43 @@ BROWSER_SECURITY_HEADERS: Final[frozenset[str]] = frozenset(
 
 UNSAFE_PROXY_RESPONSE_HEADERS: Final[frozenset[str]] = HTTP_FRAMING_HEADERS | BROWSER_SECURITY_HEADERS
 
+# A retrieved response replays the usage of the call that created it, so pricing these
+# read/management routes like inference bills the same tokens twice.
+NON_INFERENCE_CALL_TYPES: Final[frozenset[str]] = frozenset(
+    {
+        "get_responses",
+        "aget_responses",
+        "delete_responses",
+        "adelete_responses",
+        "cancel_responses",
+        "acancel_responses",
+        "list_input_items",
+        "alist_input_items",
+        "vector_store_create",
+        "avector_store_create",
+        "vector_store_retrieve",
+        "avector_store_retrieve",
+        "vector_store_list",
+        "avector_store_list",
+        "vector_store_update",
+        "avector_store_update",
+        "vector_store_delete",
+        "avector_store_delete",
+        "vector_store_file_create",
+        "avector_store_file_create",
+        "vector_store_file_list",
+        "avector_store_file_list",
+        "vector_store_file_retrieve",
+        "avector_store_file_retrieve",
+        "vector_store_file_content",
+        "avector_store_file_content",
+        "vector_store_file_update",
+        "avector_store_file_update",
+        "vector_store_file_delete",
+        "avector_store_file_delete",
+    }
+)
+
 # PTU reservation rollup writes rows to LiteLLM_DailyTeamSpend with this
 # sentinel api_key so PTU flat cost stays distinguishable from real per-request
 # spend under the table's composite unique constraint.

litellm/google_genai/streaming_iterator.py

@@ -2,6 +2,7 @@ import asyncio
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Final
 
+import litellm
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
 from litellm.proxy.pass_through_endpoints.success_handler import (
     PassThroughEndpointLogging,
@@ -65,6 +66,7 @@ class BaseGoogleGenAIGenerateContentStreamingIterator:
         litellm_logging_obj: LiteLLMLoggingObj,
         request_body: dict,
         model: str,
+        custom_llm_provider: str,
         hidden_params: dict[str, Any] | None = None,
     ):
         self.litellm_logging_obj = litellm_logging_obj
@@ -72,6 +74,10 @@ class BaseGoogleGenAIGenerateContentStreamingIterator:
         self.start_time = datetime.now()
         self.collected_chunks: list[bytes] = []
         self.model = model
+        self.custom_llm_provider = custom_llm_provider
+        self.endpoint_type: Final = (
+            EndpointType.GEMINI if custom_llm_provider == litellm.LlmProviders.GEMINI.value else EndpointType.VERTEX_AI
+        )
         self._hidden_params: dict[str, Any] = hidden_params or {}
 
     async def _handle_async_streaming_logging(
@@ -89,7 +95,7 @@ class BaseGoogleGenAIGenerateContentStreamingIterator:
                 passthrough_success_handler_obj=GLOBAL_PASS_THROUGH_SUCCESS_HANDLER_OBJ,
                 url_route="/v1/generateContent",
                 request_body=self.request_body or {},
-                endpoint_type=EndpointType.VERTEX_AI,
+                endpoint_type=self.endpoint_type,
                 start_time=self.start_time,
                 raw_bytes=self.collected_chunks,
                 end_time=end_time,
@@ -118,13 +124,13 @@ class GoogleGenAIGenerateContentStreamingIterator(BaseGoogleGenAIGenerateContent
             litellm_logging_obj=logging_obj,
             request_body=request_body or {},
             model=model,
+            custom_llm_provider=custom_llm_provider,
             hidden_params=hidden_params,
         )
         self.response = response
         self.model = model
         self.generate_content_provider_config = generate_content_provider_config
         self.litellm_metadata = litellm_metadata
-        self.custom_llm_provider = custom_llm_provider
         # Gemini streamGenerateContent uses SSE line framing; iter_lines keeps
         # large inlineData payloads (e.g. image/jpeg) intact within one event.
         self.stream_iterator = response.iter_lines()
@@ -169,13 +175,13 @@ class AsyncGoogleGenAIGenerateContentStreamingIterator(BaseGoogleGenAIGenerateCo
             litellm_logging_obj=logging_obj,
             request_body=request_body or {},
             model=model,
+            custom_llm_provider=custom_llm_provider,
             hidden_params=hidden_params,
         )
         self.response = response
         self.model = model
         self.generate_content_provider_config = generate_content_provider_config
         self.litellm_metadata = litellm_metadata
-        self.custom_llm_provider = custom_llm_provider
         # Gemini streamGenerateContent uses SSE line framing; aiter_lines keeps
         # large inlineData payloads (e.g. image/jpeg) intact within one event.
         self.stream_iterator = response.aiter_lines()

litellm/integrations/opentelemetry.py

@@ -22,6 +22,7 @@ from litellm.integrations.opentelemetry_utils.gen_ai_semconv import (
 )
 from litellm.integrations.otel.model.db_endpoint import db_span_attributes
 from litellm.integrations.otel.model.semconv import Metric
+from litellm.litellm_core_utils.internal_call_metadata import is_unbilled_non_inference_call_from_params
 from litellm.litellm_core_utils.safe_json_dumps import safe_dumps
 from litellm.litellm_core_utils.secret_redaction import redact_string
 from litellm.litellm_core_utils.service_tier_utils import (
@@ -1643,7 +1644,12 @@ class OpenTelemetry(OTELGenAISemconvMixin, CustomLogger):
 
         if self._operation_duration_histogram:
             self._operation_duration_histogram.record(duration_s, attributes=common_attrs)
-            if response_obj and (usage := response_obj.get("usage")) and self._token_usage_histogram:
+            if (
+                self._token_usage_histogram
+                and response_obj
+                and not is_unbilled_non_inference_call_from_params(kwargs.get("call_type"), params, response_obj)
+                and (usage := response_obj.get("usage"))
+            ):
                 in_attrs: Final = {**common_attrs, TOKEN_TYPE_ATTRIBUTE: "input"}
                 out_attrs: Final = {**common_attrs, TOKEN_TYPE_ATTRIBUTE: "output"}
                 self._token_usage_histogram.record(usage.get("prompt_tokens", 0), attributes=in_attrs)
@@ -1719,6 +1725,11 @@ class OpenTelemetry(OTELGenAISemconvMixin, CustomLogger):
         if not self._time_per_output_token_histogram:
             return
 
+        if is_unbilled_non_inference_call_from_params(
+            kwargs.get("call_type"), kwargs.get("litellm_params"), response_obj
+        ):
+            return
+
         # Get completion tokens from response_obj
         completion_tokens = None
         if response_obj and (usage := response_obj.get("usage")):
@@ -2488,7 +2499,14 @@ class OpenTelemetry(OTELGenAISemconvMixin, CustomLogger):
 
             self._set_service_tier_attributes(span=span, standard_logging_payload=standard_logging_payload)
 
-            usage: Final = response_obj and response_obj.get("usage")
+            usage: Final = (
+                response_obj.get("usage")
+                if response_obj
+                and not is_unbilled_non_inference_call_from_params(
+                    kwargs.get("call_type"), litellm_params, response_obj
+                )
+                else None
+            )
             if usage:
                 self.safe_set_attribute(
                     span=span,

litellm/integrations/otel/model/semconv.py

@@ -32,6 +32,7 @@ class GenAIOperation(str, Enum):
     EXECUTE_TOOL = "execute_tool"  # MCP tool-call spans
     LITELLM_VECTOR_STORE_MANAGEMENT = "litellm.vector_store_management"
     LITELLM_VECTOR_STORE_FILE_MANAGEMENT = "litellm.vector_store_file_management"
+    LITELLM_RESPONSES_MANAGEMENT = "litellm.responses_management"
     LITELLM_MODERATION = "litellm.moderation"
 
 
@@ -383,6 +384,14 @@ _OPERATION_BY_CALL_TYPE: Final[dict[str, GenAIOperation]] = {
     "aembedding": GenAIOperation.EMBEDDINGS,
     "responses": GenAIOperation.CHAT,
     "aresponses": GenAIOperation.CHAT,
+    "get_responses": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "aget_responses": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "delete_responses": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "adelete_responses": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "cancel_responses": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "acancel_responses": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "list_input_items": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
+    "alist_input_items": GenAIOperation.LITELLM_RESPONSES_MANAGEMENT,
     "image_generation": GenAIOperation.GENERATE_CONTENT,
     "aimage_generation": GenAIOperation.GENERATE_CONTENT,
     "moderation": GenAIOperation.LITELLM_MODERATION,

litellm/integrations/otel/plumbing/metrics.py

@@ -32,6 +32,7 @@ from litellm.integrations.otel.model.semconv import (
     resolve_provider,
 )
 from litellm.integrations.otel.model.utils import to_seconds
+from litellm.litellm_core_utils.internal_call_metadata import is_unbilled_non_inference_call_from_params
 from litellm.litellm_core_utils.safe_json_dumps import safe_dumps
 
 
@@ -198,16 +199,21 @@ class GenAIMetricRecorder:
     ) -> None:
         common_attrs: Final = self._filter_attributes(self._bounded_attributes(kwargs))
         duration_s: Final = (end_time - start_time).total_seconds()
+        usage_is_replayed: Final = is_unbilled_non_inference_call_from_params(
+            kwargs.get("call_type"), kwargs.get("litellm_params"), response_obj
+        )
 
         self._metrics.operation_duration.record(duration_s, attributes=common_attrs)
-        self._record_token_usage(response_obj, common_attrs)
+        if not usage_is_replayed:
+            self._record_token_usage(response_obj, common_attrs)
 
         cost: Final = kwargs.get("response_cost")
         if cost:
             self._metrics.token_cost.record(cost, attributes=common_attrs)
 
         self._record_time_to_first_token(kwargs, common_attrs)
-        self._record_time_per_output_token(kwargs, response_obj, end_time, duration_s, common_attrs)
+        if not usage_is_replayed:
+            self._record_time_per_output_token(kwargs, response_obj, end_time, duration_s, common_attrs)
         self._record_response_duration(kwargs, end_time, common_attrs)
 
     def record_failure(

litellm/litellm_core_utils/internal_call_metadata.py

@@ -20,8 +20,8 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Final
 
-from litellm.constants import INTERNAL_CALL_ORIGIN_METADATA_KEY
-from litellm.types.utils import InternalCallOrigin
+from litellm.constants import INTERNAL_CALL_ORIGIN_METADATA_KEY, NON_INFERENCE_CALL_TYPES
+from litellm.types.utils import BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN, InternalCallOrigin
 
 BUDGET_RESERVATION_METADATA_KEYS: Final = frozenset({"user_api_key_budget_reservation"})
 
@@ -45,6 +45,60 @@ budget-checked like the request that spawned it. Everything else on the parent's
 be a lie on a sub-call that runs after it returned."""
 
 
+def is_background_response(response: object) -> bool:
+    """Whether a retrieved object is a response created with ``background=true``.
+
+    Such a create returns ``status="queued"`` and no usage at all, so nothing has billed the
+    job by the time anyone reads it back. Accepts the response as a mapping or a model,
+    because the callers hold it in both shapes.
+    """
+    if isinstance(response, Mapping):
+        return response.get("background") is True
+    return getattr(response, "background", None) is True
+
+
+def is_unbilled_non_inference_call(
+    call_type: str | None,
+    metadata: Mapping[str, object] | None,
+    response: object,
+) -> bool:
+    """A read/management route priced at zero, because the usage it reports belongs to the
+    call that created the object it just read.
+
+    Retrieving a background response is the exception, and the enterprise cost poller's read
+    is the same exception seen from the other side: that job's create billed nothing, so its
+    retrieval is the only place the spend is ever visible. Pricing those at zero would lose
+    the spend rather than deduplicate it.
+    """
+    if call_type not in NON_INFERENCE_CALL_TYPES:
+        return False
+    if is_background_response(response):
+        return False
+    if metadata is None:
+        return True
+    return metadata.get(INTERNAL_CALL_ORIGIN_METADATA_KEY) != BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN
+
+
+def is_unbilled_non_inference_call_from_params(
+    call_type: str | None,
+    litellm_params: Mapping[str, object] | None,
+    response: object,
+) -> bool:
+    """:func:`is_unbilled_non_inference_call` for callers holding raw ``litellm_params``.
+
+    The call-type membership test runs first so that inference traffic, which is every
+    request in a normal workload, never pays for the metadata merge behind it.
+    """
+    if call_type not in NON_INFERENCE_CALL_TYPES:
+        return False
+    from litellm.litellm_core_utils.litellm_logging import StandardLoggingPayloadSetup
+
+    metadata: Final = (
+        StandardLoggingPayloadSetup.merge_litellm_metadata(litellm_params) if litellm_params is not None else None
+    )
+    return is_unbilled_non_inference_call(call_type, metadata, response)
+
+
 def sanitize_user_api_key_auth(auth: object) -> object:
     """Copy of the auth object with its budget reservation removed; the cost callback
     falls back to reading the reservation from inside the auth object."""

litellm/litellm_core_utils/litellm_logging.py

@@ -64,6 +64,7 @@ from litellm.integrations.mlflow import MlflowLogger
 from litellm.integrations.sqs import SQSLogger
 from litellm.litellm_core_utils.core_helpers import is_expected_client_error, reconstruct_model_name
 from litellm.litellm_core_utils.get_litellm_params import get_litellm_params
+from litellm.litellm_core_utils.internal_call_metadata import is_unbilled_non_inference_call
 from litellm.litellm_core_utils.llm_cost_calc.guardrail_cost import (
     cost_breakdown_with_guardrail,
     guardrail_information_cost,
@@ -1586,6 +1587,11 @@ class Logging(LiteLLMLoggingBaseClass):
         if cache_hit is True:
             return 0.0
 
+        if is_unbilled_non_inference_call(
+            self.call_type, StandardLoggingPayloadSetup.merge_litellm_metadata(self.litellm_params), result
+        ):
+            return 0.0
+
         transformed_result: Final = self._generate_content_result_as_model_response(result)
         if transformed_result is not None:
             result = transformed_result
@@ -5057,7 +5063,7 @@ class StandardLoggingPayloadSetup:
         return messages
 
     @staticmethod
-    def merge_litellm_metadata(litellm_params: dict) -> dict:
+    def merge_litellm_metadata(litellm_params: Mapping[str, object]) -> dict:
         """
         Merge both litellm_metadata and metadata from litellm_params.
 
@@ -5819,7 +5825,7 @@ def get_standard_logging_object_payload(
         cache_hit: Final = kwargs.get("cache_hit", False)
         # Extract usage as a plain dict, avoiding Pydantic round-trip
         raw_usage_dict: Final = StandardLoggingPayloadSetup.get_usage_as_dict(
-            response_obj=response_obj,
+            response_obj=None if is_unbilled_non_inference_call(call_type, metadata, response_obj) else response_obj,
             combined_usage_object=cast(Usage | None, kwargs.get("combined_usage_object")),
         )
         usage_dict: Final = (

litellm/litellm_core_utils/llm_cost_calc/tool_call_cost_tracking.py

@@ -7,7 +7,7 @@ from typing import Any, Final, Literal
 
 import litellm
 from litellm.constants import OPENAI_FILE_SEARCH_COST_PER_1K_CALLS
-from litellm.litellm_core_utils.llm_cost_calc.utils import _get_web_search_requests
+from litellm.litellm_core_utils.llm_cost_calc.utils import get_web_search_requests
 from litellm.types.llms.openai import (
     FileSearchTool,
     ResponsesAPIResponse,
@@ -368,7 +368,7 @@ class StandardBuiltInToolCostTracking:
             get_anthropic_web_search_requests_from_response,
         )
 
-        if usage is not None and (_get_web_search_requests(getattr(usage, "server_tool_use", None)) is not None):
+        if usage is not None and (get_web_search_requests(getattr(usage, "server_tool_use", None)) is not None):
             return usage
         web_search_requests: Final = get_anthropic_web_search_requests_from_response(response_object)
         if web_search_requests is None:
@@ -416,7 +416,7 @@ class StandardBuiltInToolCostTracking:
                 # Anthropic Claude (direct API and Vertex AI) uses server_tool_use.web_search_requests.
                 # Without this check, Claude ModelResponse always falls through to return False
                 # and _handle_web_search_cost() is never called.
-                if hasattr(usage, "server_tool_use") and _get_web_search_requests(usage.server_tool_use) is not None:
+                if hasattr(usage, "server_tool_use") and get_web_search_requests(usage.server_tool_use) is not None:
                     return True
                 # xAI reports usage.server_side_tool_usage_details.web_search_calls; a searched
                 # answer with no url_citation annotations has no other chat-path signal
@@ -431,7 +431,7 @@ class StandardBuiltInToolCostTracking:
         elif usage is not None:
             if (
                 hasattr(usage, "server_tool_use")
-                and _get_web_search_requests(usage.server_tool_use) is not None
+                and get_web_search_requests(usage.server_tool_use) is not None
                 or (
                     hasattr(usage, "prompt_tokens_details")
                     and usage.prompt_tokens_details is not None

litellm/litellm_core_utils/llm_cost_calc/utils.py

@@ -72,7 +72,7 @@ def _get_token_detail_value(details: object, key: str) -> int | None:
     return value if isinstance(value, int) else None
 
 
-def _get_web_search_requests(server_tool_use: Any) -> int | None:
+def get_web_search_requests(server_tool_use: Any) -> int | None:
     """
     Tolerantly read ``web_search_requests`` from a ``server_tool_use`` value
     that may be ``None``, a ``dict``, a ``ServerToolUse`` pydantic instance,
@@ -889,11 +889,22 @@ def generic_cost_per_token(
     total_details: Final = text_tokens + cache_hit + audio_tokens + cache_creation + image_tokens + video_tokens
     has_double_counting: Final = (cache_hit > 0 or cache_creation > 0) and total_details > usage.prompt_tokens
 
-    if (text_tokens == 0 and prompt_tokens_details["image_count"] == 0) or has_double_counting:
-        text_tokens = usage.prompt_tokens - cache_hit - audio_tokens - cache_creation - image_tokens - video_tokens
+    if has_double_counting:
+        # cached and per-modality counts are both subsets of prompt_tokens and may overlap, so a
+        # modality can only bill what the cache did not already cover or the overlap is billed twice
+        uncached_budget: Final = max(usage.prompt_tokens - cache_hit - cache_creation, 0)
+        billable_audio: Final = min(audio_tokens, uncached_budget)
+        billable_image: Final = min(image_tokens, uncached_budget - billable_audio)
+        billable_video: Final = min(video_tokens, uncached_budget - billable_audio - billable_image)
+        prompt_tokens_details["audio_tokens"] = billable_audio
+        prompt_tokens_details["image_tokens"] = billable_image
+        prompt_tokens_details["video_tokens"] = billable_video
+        prompt_tokens_details["text_tokens"] = uncached_budget - billable_audio - billable_image - billable_video
+    elif text_tokens == 0 and prompt_tokens_details["image_count"] == 0:
         # Clamp to zero: inconsistent streaming usage
-        text_tokens = max(text_tokens, 0)
-        prompt_tokens_details["text_tokens"] = text_tokens
+        prompt_tokens_details["text_tokens"] = max(
+            usage.prompt_tokens - cache_hit - audio_tokens - cache_creation - image_tokens - video_tokens, 0
+        )
 
     (
         prompt_base_cost,

litellm/llms/anthropic/cost_calculation.py

@@ -8,9 +8,9 @@ from typing import TYPE_CHECKING, Final, Optional
 from pydantic import BaseModel, ValidationError
 
 from litellm.litellm_core_utils.llm_cost_calc.utils import (
-    _get_web_search_requests,
     generic_cost_per_token,
     get_provider_specific_geo_multiplier,
+    get_web_search_requests,
 )
 
 if TYPE_CHECKING:
@@ -104,7 +104,7 @@ def get_cost_for_anthropic_web_search(
 
     if usage is None:
         return 0.0
-    web_search_requests: Final = _get_web_search_requests(getattr(usage, "server_tool_use", None))
+    web_search_requests: Final = get_web_search_requests(getattr(usage, "server_tool_use", None))
     if web_search_requests is None:
         return 0.0
 

litellm/llms/anthropic/experimental_pass_through/adapters/transformation.py

@@ -99,6 +99,7 @@ from litellm.types.llms.anthropic import (
     ContextManagementResponse,
     MessageBlockDelta,
     MessageDelta,
+    ServerToolUsage,
     StreamingContentBlockDeltaType,
     UsageDelta,
     UsageIteration,
@@ -1314,10 +1315,24 @@ class LiteLLMAnthropicMessagesAdapter:
             return explicit_value
         return cls._first_positive_prompt_tokens_detail_value(usage, ("cache_creation_tokens", "cache_write_tokens"))
 
+    @classmethod
+    def _get_web_search_request_count(cls, usage: Usage) -> int:
+        from litellm.litellm_core_utils.llm_cost_calc.utils import (
+            get_web_search_requests,
+        )
+
+        from_server_tool_use: Final = cls._positive_int(
+            get_web_search_requests(getattr(usage, "server_tool_use", None))
+        )
+        if from_server_tool_use > 0:
+            return from_server_tool_use
+        return cls._first_positive_prompt_tokens_detail_value(usage, ("web_search_requests",))
+
     @classmethod
     def _translate_openai_usage_to_anthropic_usage_delta(cls, usage: Usage) -> UsageDelta:
         cache_read_input_tokens: Final = cls._get_cache_read_input_tokens(usage)
         cache_creation_input_tokens: Final = cls._get_cache_creation_input_tokens(usage)
+        web_search_requests: Final = cls._get_web_search_request_count(usage)
         input_tokens: Final = max(
             (usage.prompt_tokens or 0) - cache_read_input_tokens - cache_creation_input_tokens,
             0,
@@ -1331,6 +1346,11 @@ class LiteLLMAnthropicMessagesAdapter:
             usage_delta["cache_creation_input_tokens"] = cache_creation_input_tokens
         if cache_read_input_tokens > 0:
             usage_delta["cache_read_input_tokens"] = cache_read_input_tokens
+        if web_search_requests > 0:
+            return UsageDelta(
+                **usage_delta,
+                server_tool_use=ServerToolUsage(web_search_requests=web_search_requests),
+            )
         return usage_delta
 
     @classmethod

litellm/llms/gemini/cost_calculator.py

@@ -39,28 +39,33 @@ def cost_per_web_search_request(usage: "Usage", model_info: "ModelInfo") -> floa
     ``model_info`` when available, falling back to $0.035 for models not
     yet updated in the pricing JSON.
     """
+    from litellm.litellm_core_utils.llm_cost_calc.utils import get_web_search_requests
     from litellm.types.utils import PromptTokensDetailsWrapper
 
     _DEFAULT_COST: Final = 35e-3
     search_costs: Final = model_info.get("search_context_cost_per_query") or {}
     _cost: Final = search_costs.get("search_context_size_medium", _DEFAULT_COST)
 
-    number_of_web_search_requests = 0
-    if (
-        usage is not None
-        and usage.prompt_tokens_details is not None
-        and isinstance(usage.prompt_tokens_details, PromptTokensDetailsWrapper)
-        and hasattr(usage.prompt_tokens_details, "web_search_requests")
-        and usage.prompt_tokens_details.web_search_requests is not None
-    ):
-        number_of_web_search_requests = usage.prompt_tokens_details.web_search_requests
+    requests_from_prompt_details: Final = (
+        usage.prompt_tokens_details.web_search_requests
+        if (
+            usage is not None
+            and usage.prompt_tokens_details is not None
+            and isinstance(usage.prompt_tokens_details, PromptTokensDetailsWrapper)
+            and hasattr(usage.prompt_tokens_details, "web_search_requests")
+            and usage.prompt_tokens_details.web_search_requests is not None
+        )
+        else None
+    )
+    requests_from_server_tool_use: Final = get_web_search_requests(getattr(usage, "server_tool_use", None))
+    number_of_web_search_requests: Final = requests_from_prompt_details or requests_from_server_tool_use or 0
 
-    # per_prompt billing: clamp to 1 (flat fee per grounded API call)
     billing_mode: Final = model_info.get("web_search_billing_unit") or "per_prompt"
-    if number_of_web_search_requests > 0 and billing_mode == "per_prompt":
-        number_of_web_search_requests = 1
+    billable_requests: Final = (
+        1 if (number_of_web_search_requests > 0 and billing_mode == "per_prompt") else number_of_web_search_requests
+    )
 
-    return _cost * number_of_web_search_requests
+    return _cost * billable_requests
 
 
 GOOGLE_MAPS_GROUNDING_DEFAULT_COST_PER_QUERY: Final = 14e-3

litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py

@@ -46,6 +46,7 @@ from litellm.proxy._types import (
 )
 from litellm.proxy.auth.ip_address_utils import IPAddressUtils
 from litellm.proxy.auth.user_api_key_auth import (
+    _get_bearer_token_or_received_api_key,  # pyright: ignore[reportPrivateUsage]  # shared x-litellm-api-key parser lives with user_api_key_auth
     _run_centralized_common_checks,
     user_api_key_auth,
 )
@@ -429,7 +430,10 @@ class MCPRequestHandler:
             # An explicit x-litellm-api-key is always a LiteLLM credential, even
             # for a delegated server, so validate it: identity / spend / rate
             # limits resolve and any stored upstream token can be forwarded.
-            validated_user_api_key_auth = await user_api_key_auth(api_key=litellm_api_key, request=request)
+            validated_user_api_key_auth = await user_api_key_auth(
+                api_key=f"Bearer {_get_bearer_token_or_received_api_key(litellm_api_key)}",
+                request=request,
+            )
         elif MCPRequestHandler._target_servers_delegate_auth_to_upstream(
             path=request_route,
             mcp_servers=mcp_servers,

litellm/proxy/common_request_processing.py

@@ -21,14 +21,13 @@ import litellm
 from litellm._logging import _redact_string, verbose_proxy_logger
 from litellm._uuid import uuid
 from litellm.constants import (
-    AUTO_ROUTED_REQUEST_METADATA_KEY,
     DD_TRACER_STREAMING_CHUNK_YIELD_RESOURCE,
     DEFAULT_MAX_RECURSE_DEPTH,
     LITELLM_DETAILED_TIMING,
     LITELLM_HTTP_STATUS_CLIENT_DISCONNECTED,
     MAX_PAYLOAD_SIZE_FOR_DEBUG_LOG,
+    NON_INFERENCE_CALL_TYPES,
     RETURN_RAW_MODEL_NAME_METADATA_KEY,
-    ROUTER_MODEL_NAME_RESPONSE_FIELD,
     STREAM_SSE_DATA_PREFIX,
     STREAM_SSE_KEEPALIVE_PING_BYTES,
     UNSAFE_PROXY_RESPONSE_HEADERS,
@@ -39,6 +38,7 @@ from litellm.litellm_core_utils.dd_tracing import NullTracer, tracer
 from litellm.litellm_core_utils.get_supported_openai_params import (
     get_supported_openai_params,
 )
+from litellm.litellm_core_utils.internal_call_metadata import is_unbilled_non_inference_call_from_params
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
 from litellm.litellm_core_utils.llm_cost_calc.guardrail_cost import guardrail_information_cost
 from litellm.litellm_core_utils.llm_response_utils.get_headers import (
@@ -1302,15 +1302,51 @@ def _uncached_input_cost(
     return input_cost - (cache_read_cost or 0.0) - (cache_creation_cost or 0.0)
 
 
+_ZERO_COST_BREAKDOWN: Final = CostBreakdownHeaderValues(
+    original_cost=0.0,
+    discount_amount=0.0,
+    margin_total_amount=0.0,
+    margin_percent=0.0,
+    input_cost=0.0,
+    output_cost=0.0,
+    tool_usage_cost=0.0,
+)
+"""The component split a call priced at zero advertises, so a client reading the cost headers off a
+read or management route still finds the whole family rather than a partially populated one."""
+
+
+def _totals_to_zero(response_cost: float | str | None) -> bool:
+    """Whether the total these headers carry is zero, counting a total no route ever priced as one.
+
+    A component split is only reported as zero alongside a total that agrees with it, so a read
+    that did price normally never advertises a real total beside an all-zero split.
+    """
+    if response_cost is None or response_cost == "":
+        return True
+    try:
+        return float(response_cost) == 0.0
+    except (TypeError, ValueError):
+        return False
+
+
 def _get_cost_breakdown_from_logging_obj(
     litellm_logging_obj: LiteLLMLoggingObj | None,
+    response_cost: float | str | None = None,
 ) -> CostBreakdownHeaderValues:
-    """Extract discount, margin, and per-component cost information from logging object's cost breakdown."""
+    """Extract discount, margin, and per-component cost information from logging object's cost breakdown.
+
+    A non-inference call that priced at zero never records a breakdown, so its components are
+    reported as zero here. Any such call that did price normally (retrieving a background response,
+    and the cost poller's read of one) reports the breakdown it stored, or nothing at all when the
+    breakdown has not landed yet.
+    """
     if not litellm_logging_obj or not hasattr(litellm_logging_obj, "cost_breakdown"):
         return CostBreakdownHeaderValues()
 
     cost_breakdown: Final = litellm_logging_obj.cost_breakdown
     if not cost_breakdown:
+        if litellm_logging_obj.call_type in NON_INFERENCE_CALL_TYPES and _totals_to_zero(response_cost):
+            return _ZERO_COST_BREAKDOWN
         return CostBreakdownHeaderValues()
 
     return CostBreakdownHeaderValues(
@@ -1459,7 +1495,9 @@ class ProxyBaseLLMRequestProcessing:
         exclude_values: Final = {"", None, "None"}
         hidden_params = hidden_params or {}
 
-        cost_breakdown: Final = _get_cost_breakdown_from_logging_obj(litellm_logging_obj=litellm_logging_obj)
+        cost_breakdown: Final = _get_cost_breakdown_from_logging_obj(
+            litellm_logging_obj=litellm_logging_obj, response_cost=response_cost
+        )
 
         # Calculate updated spend for header (include current response_cost)
         current_spend: Final = user_api_key_dict.spend or 0.0
@@ -2036,54 +2074,6 @@ class ProxyBaseLLMRequestProcessing:
                 return deployment
         return None
 
-    @staticmethod
-    def get_router_selected_model_name(
-        litellm_logging_obj: LiteLLMLoggingObj | None,
-    ) -> str | None:
-        """Model group an auto-routing strategy selected, or None if none fired.
-
-        The marker and ``deployment_model_name`` are written by different bucket
-        resolvers (``get_or_create_metadata_bucket`` vs
-        ``_get_router_metadata_variable_name``), so they can land in different
-        buckets on the same request. Resolve each across both.
-        """
-        litellm_params: Final = getattr(litellm_logging_obj, "litellm_params", None)
-        if not isinstance(litellm_params, dict):
-            return None
-        buckets: Final = tuple(
-            bucket for key in ("litellm_metadata", "metadata") if isinstance(bucket := litellm_params.get(key), dict)
-        )
-        if not any(bucket.get(AUTO_ROUTED_REQUEST_METADATA_KEY) is True for bucket in buckets):
-            return None
-        return next(
-            (
-                model_group
-                for bucket in buckets
-                if isinstance(model_group := bucket.get("deployment_model_name"), str) and model_group
-            ),
-            None,
-        )
-
-    @staticmethod
-    def set_router_selected_model_field(
-        *,
-        response_obj: object,
-        router_model_name: str | None,
-    ) -> None:
-        if not router_model_name:
-            return
-        if isinstance(response_obj, dict):
-            response_obj[ROUTER_MODEL_NAME_RESPONSE_FIELD] = router_model_name
-            return
-        try:
-            setattr(response_obj, ROUTER_MODEL_NAME_RESPONSE_FIELD, router_model_name)
-        except (AttributeError, TypeError, ValueError):
-            verbose_proxy_logger.debug(
-                "Could not set %s on response object of type %s",
-                ROUTER_MODEL_NAME_RESPONSE_FIELD,
-                type(response_obj),
-            )
-
     @staticmethod
     def _response_cost_from_logging_obj(
         *,
@@ -2582,20 +2572,21 @@ class ProxyBaseLLMRequestProcessing:
                 log_context=f"litellm_call_id={logging_obj.litellm_call_id}",
                 return_raw_model_name=_should_return_raw_model_name(self.data),
             )
-        self.set_router_selected_model_field(
-            response_obj=response,
-            router_model_name=self.get_router_selected_model_name(logging_obj),
-        )
 
         hidden_params = get_hidden_params_dict(response)  # get any updated response headers
         additional_headers = hidden_params.get("additional_headers", {}) or {}
 
         recover_response_cost: Final = not response_cost and hidden_params.get("response_cost") is None
-        llm_cost_for_headers: Final = (
+        computed_cost_for_headers: Final = (
             self._response_cost_from_logging_obj(response=response, logging_obj=logging_obj) or ""
             if recover_response_cost
             else response_cost
         )
+        llm_cost_for_headers: Final = (
+            0.0
+            if is_unbilled_non_inference_call_from_params(logging_obj.call_type, logging_obj.litellm_params, response)
+            else computed_cost_for_headers
+        )
         _, request_metadata_bucket = get_or_create_metadata_bucket(self.data)
         guardrail_cost_for_headers: Final = guardrail_information_cost(
             request_metadata_bucket.get("standard_logging_guardrail_information")

litellm/proxy/management_endpoints/auto_router_endpoints.py

@@ -195,7 +195,7 @@ def _models_this_test_can_call(config: RequestComplexityRouterConfig) -> tuple[s
         model
         for model in (
             config.classifier_llm_config.model
-            if config.classifier_type == "llm" and config.classifier_llm_config is not None
+            if config.uses_llm_classifier and config.classifier_llm_config is not None
             else None,
             config.embedding_model if config.semantic_keyword_matching else None,
         )

litellm/proxy/management_endpoints/budget_management_endpoints.py

@@ -13,6 +13,7 @@ All /budget management endpoints
 
 #### BUDGET TABLE MANAGEMENT ####
 import math
+from collections.abc import Mapping
 from typing import Final
 
 from fastapi import APIRouter, Depends, HTTPException
@@ -178,13 +179,17 @@ async def update_budget(
         else {}
     )
 
-    response: Final = await BudgetRepository(prisma_client).table.update(
-        where={"budget_id": budget_obj.budget_id},
-        data={
+    budget_obj_jsonified: Final[Mapping[str, object]] = jsonify_object(
+        {
             **budget_obj.model_dump(exclude_unset=True),
             **recomputed_reset_at,
             "updated_by": user_api_key_dict.user_id or litellm_proxy_admin_name,
-        },
+        }
+    )
+
+    response: Final = await BudgetRepository(prisma_client).table.update(
+        where={"budget_id": budget_obj.budget_id},
+        data=budget_obj_jsonified,
     )
 
     return response

litellm/proxy/management_endpoints/scim/scim_v2.py

@@ -6,6 +6,7 @@ This is an enterprise feature and requires a premium license.
 
 import re
 from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
+from copy import deepcopy
 from dataclasses import dataclass
 from functools import partial
 from itertools import chain
@@ -2375,6 +2376,37 @@ async def get_group(
         raise handle_exception_on_proxy(e)
 
 
+def _new_team_request_with_defaults(
+    team_id: str,
+    team_alias: str | None,
+    members_with_roles: Sequence[Member],
+) -> NewTeamRequest:
+    """Build the SCIM group's team request, applying litellm.default_team_params
+    (including models) the same way SSO auto-created teams do."""
+    default_params: Final = litellm.default_team_params
+    defaults: Final[Mapping[str, object]] = (
+        deepcopy(default_params)
+        if isinstance(default_params, dict)
+        else default_params.model_dump(exclude_none=True)
+        if default_params is not None
+        else {}
+    )
+    default_metadata: Final = defaults.get("metadata")
+    metadata: Final = {
+        **(default_metadata if isinstance(default_metadata, dict) else {}),
+        SCIM_MANAGED_TEAM_METADATA_KEY: True,
+    }
+    return NewTeamRequest.model_validate(
+        {
+            **defaults,
+            "team_id": team_id,
+            "team_alias": team_alias,
+            "members_with_roles": members_with_roles,
+            "metadata": metadata,
+        }
+    )
+
+
 @scim_router.post(
     "/Groups",
     response_model=SCIMGroup,
@@ -2412,11 +2444,10 @@ async def create_group(
 
         # Create team in database
         created_team: Final = await new_team(
-            data=NewTeamRequest(
+            data=_new_team_request_with_defaults(
                 team_id=team_id,
                 team_alias=group.displayName,
                 members_with_roles=members_with_roles,
-                metadata={SCIM_MANAGED_TEAM_METADATA_KEY: True},
             ),
             http_request=Request(scope={"type": "http", "path": "/scim/v2/Groups"}),
             user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN),

litellm/proxy/pass_through_endpoints/llm_provider_handlers/vertex_passthrough_logging_handler.py

@@ -615,7 +615,7 @@ class VertexPassthroughLoggingHandler:
         response_cost: Final = litellm.completion_cost(
             completion_response=litellm_model_response,
             model=model,
-            custom_llm_provider="vertex_ai",
+            custom_llm_provider=custom_llm_provider,
             vertex_location=vertex_location,
         )
 

litellm/proxy/pass_through_endpoints/streaming_handler.py

@@ -17,6 +17,9 @@ from litellm.types.utils import StandardPassThroughResponseObject
 from .llm_provider_handlers.anthropic_passthrough_logging_handler import (
     AnthropicPassthroughLoggingHandler,
 )
+from .llm_provider_handlers.gemini_passthrough_logging_handler import (
+    GeminiPassthroughLoggingHandler,
+)
 from .llm_provider_handlers.openai_passthrough_logging_handler import (
     OpenAIPassthroughLoggingHandler,
 )
@@ -243,6 +246,26 @@ class PassThroughStreamingHandler:
             )
             standard_logging_response_object = vertex_passthrough_logging_handler_result["result"]
             kwargs = vertex_passthrough_logging_handler_result["kwargs"]
+        elif endpoint_type == EndpointType.GEMINI:
+            gemini_passthrough_logging_handler_result: Final = (
+                GeminiPassthroughLoggingHandler._handle_logging_gemini_collected_chunks(  # pyright: ignore[reportPrivateUsage]  # mirrors sibling handler dispatch
+                    litellm_logging_obj=litellm_logging_obj,
+                    passthrough_success_handler_obj=passthrough_success_handler_obj,
+                    url_route=url_route,
+                    request_body=request_body,
+                    endpoint_type=endpoint_type,
+                    start_time=start_time,
+                    all_chunks=all_chunks,
+                    end_time=end_time,
+                    model=model,
+                )
+            )
+            standard_logging_response_object = (  # rebind-ok: branch bind in shared if/elif dispatch
+                gemini_passthrough_logging_handler_result["result"]
+            )
+            kwargs = (  # rebind-ok: branch bind in shared if/elif dispatch
+                gemini_passthrough_logging_handler_result["kwargs"]
+            )
         elif endpoint_type == EndpointType.OPENAI:
             openai_passthrough_logging_handler_result: Final = (
                 OpenAIPassthroughLoggingHandler._handle_logging_openai_collected_chunks(

litellm/proxy/prompts/prompt_endpoints.py

@@ -1021,19 +1021,7 @@ async def delete_prompt(
         # Delete versions from the database (scoped to environment if provided)
         await _prompt_table(prisma_client).delete_many(where=delete_where)
 
-        # Remove matching prompts from memory — scope to environment if provided
-        if environment:
-            prompts_to_delete: Final = [
-                pid
-                for pid, prompt in IN_MEMORY_PROMPT_REGISTRY.IN_MEMORY_PROMPTS.items()
-                if get_base_prompt_id(prompt_id=pid) == base_prompt_id and prompt.environment == environment
-            ]
-            for pid in prompts_to_delete:
-                del IN_MEMORY_PROMPT_REGISTRY.IN_MEMORY_PROMPTS[pid]
-                if pid in IN_MEMORY_PROMPT_REGISTRY.prompt_id_to_custom_prompt:
-                    del IN_MEMORY_PROMPT_REGISTRY.prompt_id_to_custom_prompt[pid]
-        else:
-            IN_MEMORY_PROMPT_REGISTRY.delete_prompts_by_base_id(base_prompt_id)
+        IN_MEMORY_PROMPT_REGISTRY.delete_prompts_by_base_id(base_prompt_id, environment=environment or None)
 
         env_msg: Final = f" from {environment}" if environment else ""
         return {"message": f"Prompt {base_prompt_id} deleted successfully{env_msg}"}

litellm/proxy/prompts/prompt_registry.py

@@ -195,12 +195,22 @@ class InMemoryPromptRegistry:
         """
         return self.prompt_id_to_custom_prompt.get(prompt_id)
 
-    def delete_prompts_by_base_id(self, base_prompt_id: str) -> list[str]:
+    def remove_prompt(self, prompt_id: str) -> None:
+        import litellm
+
+        self.IN_MEMORY_PROMPTS.pop(prompt_id, None)
+        stale_callback: Final = self.prompt_id_to_custom_prompt.pop(prompt_id, None)
+        if stale_callback is not None:
+            litellm.logging_callback_manager.remove_callback_from_all_lists(stale_callback)
+
+    def delete_prompts_by_base_id(self, base_prompt_id: str, environment: str | None = None) -> list[str]:
         """
-        Delete all prompts matching the given base prompt ID from memory.
+        Delete all prompts matching the given base prompt ID from memory, along with their
+        registered callbacks; scoped to one environment when given.
 
         Args:
             base_prompt_id: The base prompt ID (without version suffix)
+            environment: When set, only delete prompts deployed to this environment
 
         Returns:
             List of prompt IDs that were deleted
@@ -208,13 +218,14 @@ class InMemoryPromptRegistry:
         from litellm.proxy.prompts.prompt_endpoints import get_base_prompt_id
 
         prompts_to_delete: Final = [
-            pid for pid in self.IN_MEMORY_PROMPTS if get_base_prompt_id(prompt_id=pid) == base_prompt_id
+            pid
+            for pid, prompt in self.IN_MEMORY_PROMPTS.items()
+            if get_base_prompt_id(prompt_id=pid) == base_prompt_id
+            and (environment is None or prompt.environment == environment)
         ]
 
         for pid in prompts_to_delete:
-            del self.IN_MEMORY_PROMPTS[pid]
-            if pid in self.prompt_id_to_custom_prompt:
-                del self.prompt_id_to_custom_prompt[pid]
+            self.remove_prompt(prompt_id=pid)
 
         return prompts_to_delete
 

litellm/proxy/proxy_server.py

@@ -248,7 +248,6 @@ from litellm.constants import (
     PROXY_BUDGET_RESCHEDULER_MAX_TIME,
     PROXY_BUDGET_RESCHEDULER_MIN_TIME,
     PROXY_CONFIG_RELOAD_INTERVAL_SECONDS,
-    ROUTER_MODEL_NAME_RESPONSE_FIELD,
     WEEKLY_SPEND_REPORT_JOB_ID,
 )
 from litellm.exceptions import RejectedRequestError
@@ -7269,6 +7268,7 @@ class ProxyConfig:
                 return None
 
         try:
+            prompt_ids_loaded_before_db_read: Final = frozenset(IN_MEMORY_PROMPT_REGISTRY.IN_MEMORY_PROMPTS)
             prompts_in_db: Final[Sequence[object]] = await PromptRepository(prisma_client).table.find_many()
             parsed_specs: Final[tuple[PromptSpec, ...]] = tuple(
                 spec for row in prompts_in_db if (spec := parse_row(row)) is not None
@@ -7291,6 +7291,18 @@ class ProxyConfig:
                         prompt_spec.prompt_id,
                         prompt_sync_error,
                     )
+            # An unparsable row still exists in the DB, so skip the sweep rather than unload its in-memory copy
+            every_row_parsed: Final = len(parsed_specs) == len(prompts_in_db)
+            if every_row_parsed:
+                deleted_db_prompt_ids: Final = tuple(
+                    prompt_id
+                    for prompt_id in prompt_ids_loaded_before_db_read
+                    if (loaded_spec := IN_MEMORY_PROMPT_REGISTRY.IN_MEMORY_PROMPTS.get(prompt_id)) is not None
+                    and loaded_spec.prompt_info.prompt_type == "db"
+                    and prompt_id not in newest_spec_per_id
+                )
+                for deleted_prompt_id in deleted_db_prompt_ids:
+                    IN_MEMORY_PROMPT_REGISTRY.remove_prompt(prompt_id=deleted_prompt_id)
         except Exception as e:
             verbose_proxy_logger.debug("litellm.proxy.proxy_server.py::ProxyConfig:_init_prompts_in_db - %s", e)
 
@@ -8044,10 +8056,6 @@ def _fast_serialize_simple_model_response_stream(
     for top_level_key in ("id", "object", "created"):
         if payload[top_level_key] is None:
             payload.pop(top_level_key)
-
-    router_model_name: Final = getattr(chunk, ROUTER_MODEL_NAME_RESPONSE_FIELD, None)
-    if router_model_name is not None:
-        payload[ROUTER_MODEL_NAME_RESPONSE_FIELD] = router_model_name
     return orjson.dumps(payload)
 
 
@@ -8345,9 +8353,6 @@ async def async_data_generator(
         model_mismatch_logged = False
         fallback_metadata_event_sent = False
         include_fallback_errors: Final = _should_include_fallback_errors(request_data)
-        # Fallbacks resolve on the first ``__anext__``, so the selected group is read
-        # per chunk off this object rather than snapshotted here.
-        router_logging_obj: Final = request_data.get("litellm_logging_obj")
         # Use a running string instead of list + join to avoid O(n^2) overhead.
         # Previously "".join(str_so_far_parts) was called every chunk, re-joining
         # the entire accumulated response. String += is O(n) amortized total.
@@ -8437,10 +8442,6 @@ async def async_data_generator(
                 fallback_was_attempted=fallback_was_attempted,
                 fallback_model_from_metadata=fallback_model_from_metadata,
             )
-            ProxyBaseLLMRequestProcessing.set_router_selected_model_field(
-                response_obj=chunk,
-                router_model_name=ProxyBaseLLMRequestProcessing.get_router_selected_model_name(router_logging_obj),
-            )
 
             if strip_stream_usage and _is_injected_stream_usage_artifact(chunk):
                 if pending_fallback_event:

litellm/proxy/spend_tracking/spend_management_endpoints.py

@@ -18,7 +18,7 @@ from typing import (
 )
 
 import fastapi
-from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from typing_extensions import ReadOnly
 
 import litellm
@@ -208,9 +208,18 @@ async def _find_spend_logs(
     prisma_client: PrismaClient,
     where: Mapping[str, object],
     order: Mapping[str, str],
+    take: int,
+    http_response: Response,
 ) -> Sequence[_SupportsModelDump]:
-    """Read spend log rows as Prisma model instances."""
-    return await _spend_logs_table(prisma_client).find_many(where=where, order=order)
+    """Read spend log rows as Prisma model instances, capped at ``take`` rows."""
+    rows: Final = await _spend_logs_table(prisma_client).find_many(where=where, order=order, take=take)
+    if len(rows) == take:
+        http_response.headers["x-litellm-spend-logs-truncated"] = "true"
+        verbose_proxy_logger.warning(
+            "/spend/logs result truncated to the %s most recent rows; use /spend/logs/v2 for paginated access",
+            take,
+        )
+    return rows
 
 
 async def _find_spend_log_row(prisma_client: PrismaClient, request_id: str) -> _SpendLogOwnershipRow | None:
@@ -2851,6 +2860,7 @@ async def ui_view_request_response_for_request_id(
     },
 )
 async def view_spend_logs(
+    fastapi_response: Response,
     api_key: str | None = fastapi.Query(
         default=None,
         description="Get spend logs based on api key",
@@ -2881,6 +2891,8 @@ async def view_spend_logs(
     [DEPRECATED] This endpoint is not paginated and can cause performance issues.
     Please use `/spend/logs/v2` instead for paginated access to spend logs.
 
+    Row results are capped at 10,000 most recent entries per response.
+
     View all spend logs, if request_id is provided, only logs for that request_id will be returned
 
     When start_date and end_date are provided:
@@ -2931,7 +2943,6 @@ async def view_spend_logs(
             raise Exception(
                 "Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys"
             )
-        spend_logs = []
         if (
             start_date is not None
             and isinstance(start_date, str)
@@ -2970,6 +2981,8 @@ async def view_spend_logs(
                     prisma_client,
                     where=filter_query,
                     order={"startTime": "desc"},
+                    take=SPEND_LOGS_PAGINATION_COUNT_CAP,
+                    http_response=fastapi_response,
                 )
                 return data
 
@@ -3040,14 +3053,12 @@ async def view_spend_logs(
             if user_id is not None and isinstance(user_id, str):
                 scoped_filter["user"] = user_id
 
-            if not scoped_filter:
-                spend_logs = await prisma_client.get_data(table_name="spend", query_type="find_all")
-                return spend_logs
-
             data = await _find_spend_logs(
                 prisma_client,
                 where=scoped_filter,
                 order={"startTime": "desc"},
+                take=SPEND_LOGS_PAGINATION_COUNT_CAP,
+                http_response=fastapi_response,
             )
             return data
 

litellm/proxy/spend_tracking/spend_tracking_utils.py

@@ -22,6 +22,7 @@ from litellm.litellm_core_utils.core_helpers import (
     get_litellm_metadata_from_kwargs,
     reconstruct_model_name,
 )
+from litellm.litellm_core_utils.internal_call_metadata import is_unbilled_non_inference_call
 from litellm.litellm_core_utils.litellm_logging import is_valid_sha256_hash
 from litellm.litellm_core_utils.safe_json_dumps import safe_dumps, strip_null_bytes
 from litellm.proxy._types import SpendLogsMetadata, SpendLogsPayload
@@ -277,7 +278,7 @@ def get_logging_payload(kwargs, response_obj, start_time, end_time) -> SpendLogs
     usage: dict = {}
     if call_type in ["ocr", "aocr"]:
         usage = _extract_usage_for_ocr_call(response_obj, response_obj_dict)
-    else:
+    elif not is_unbilled_non_inference_call(call_type, metadata, response_obj_dict):
         # Use response_obj_dict instead of response_obj to avoid calling .get() on Pydantic models
         _usage: Final = response_obj_dict.get("usage", None) or {}
         if isinstance(_usage, litellm.Usage):

litellm/router.py

@@ -45,7 +45,6 @@ from litellm.caching.caching import (
     RedisClusterCache,
 )
 from litellm.constants import (
-    AUTO_ROUTED_REQUEST_METADATA_KEY,
     CONSUMED_REQUEST_TAGS_METADATA_KEY,
     DEFAULT_AUTO_ROUTER_MAX_INPUT_CHARS,
     DEFAULT_HEALTH_CHECK_INTERVAL,
@@ -12164,9 +12163,6 @@ class Router:
             self._stamp_or_clear_metadata_key(
                 request_kwargs=request_kwargs, key=CONSUMED_REQUEST_TAGS_METADATA_KEY, value=None
             )
-            self._stamp_or_clear_metadata_key(
-                request_kwargs=request_kwargs, key=AUTO_ROUTED_REQUEST_METADATA_KEY, value=None
-            )
             return None
 
         pre_routing_hook_response: Final = await selected_strategy.strategy.async_pre_routing_hook(
@@ -12194,13 +12190,6 @@ class Router:
                 request_tags=_get_tags_from_request_kwargs(request_kwargs),
             ),
         )
-        # Gates the proxy's `router_model_name` response field; the body `model` is
-        # always restamped back to the alias the client sent.
-        self._stamp_or_clear_metadata_key(
-            request_kwargs=request_kwargs,
-            key=AUTO_ROUTED_REQUEST_METADATA_KEY,
-            value=(True if pre_routing_hook_response is not None else None),
-        )
 
         # `model` (the alias, e.g. "smart-router") is never the deployment actually
         # called - apply the router marker's own litellm_params to the request,

litellm/router_strategy/complexity_router/README.md

@@ -178,6 +178,50 @@ response = litellm.completion(
 
 ## Special Behaviors
 
+### Heuristic-first chaining
+
+`classifier_type: heuristic_first` runs the local scorer on every request and only calls the LLM
+classifier for the ones the scorer could not place cheaply. It takes the same classifier settings as
+`classifier_type: llm`, plus `heuristic_first_max_tier`:
+
+```yaml
+model_list:
+  - model_name: smart-router
+    litellm_params:
+      model: auto_router/complexity_router
+      complexity_router_config:
+        classifier_type: heuristic_first
+        heuristic_first_max_tier: SIMPLE
+        classifier_llm_config:
+          model: gpt-4o-mini
+        tiers:
+          SIMPLE: gpt-4o-mini
+          MEDIUM: gpt-4o
+          COMPLEX: claude-sonnet-4
+          REASONING: o1-preview
+```
+
+A request short-circuits, meaning it routes on the scorer's own tier with no classifier call, when
+two things hold: the scorer landed at or below `heuristic_first_max_tier`, and it produced at least
+one signal. Everything else goes to the classifier, which then decides as it normally would.
+
+The signal requirement is what keeps this from quietly routing everything to your cheapest model.
+A prompt where no dimension fires scores exactly 0.0, which is below `simple_medium`, so the score
+to tier mapping calls it SIMPLE by default rather than by evidence. Around half of general traffic
+scores that way. Those requests reach the classifier instead, which is the whole reason to configure
+one. Note the converse too: the score is not a confidence, and a prompt that fires a single weak
+signal and still lands under the boundary does short-circuit, so a lower threshold buys accuracy and
+a higher one buys savings.
+
+`heuristic_first_max_tier` names a built-in tier and may not name the highest one, since that would
+short-circuit everything and leave the classifier unreachable. Operator-defined tier sets
+(`tier_definitions`) are not supported here, because the scorer only produces the built-in tiers.
+When the classifier call fails, the fallback works exactly as it does under `classifier_type: llm`,
+except that the heuristic outcome is the one already computed rather than a second scoring pass.
+
+Spend logs record `routing_decision.cause` as `heuristic_first_short_circuit` when the classifier
+was skipped, and `llm_classifier` when it ran, so the two are told apart per request.
+
 ### Reasoning Override
 
 If 2+ reasoning markers are detected in the user message, the request is promoted to the REASONING tier even when the weighted score maps lower, so complex reasoning tasks get the appropriate model. The promotion requires the score to reach `reasoning_override_min_score`, which tracks `tier_boundaries.simple_medium` unless set, so stock phrases on an otherwise trivial prompt cannot buy the top tier. Set it to `0` to promote on the markers alone.

litellm/router_strategy/complexity_router/complexity_router.py

@@ -719,6 +719,7 @@ class ClassificationOutcome(NamedTuple):
         "heuristic_scorer",
         "reasoning_override",
         "llm_classifier",
+        "heuristic_first_short_circuit",
         "classifier_plugin",
         "classifier_fallback",
         "default_model_fallback",
@@ -859,7 +860,7 @@ class ComplexityRouter(CustomLogger):
 
         # Both are pure functions of the config, so building them per classifier call would
         # re-run create_model and the schema conversion on every request for the same result.
-        llm_classifier_configured: Final = self.config.classifier_type == "llm" and (
+        llm_classifier_configured: Final = self.config.uses_llm_classifier and (
             self.config.classifier_llm_config is not None
         )
         self._classifier_system_prompt: str | None = (
@@ -1237,17 +1238,63 @@ class ComplexityRouter(CustomLogger):
         """
         Classify a prompt by complexity, using the LLM classifier when configured.
 
-        Falls back to the local heuristic scorer if classifier_type is "heuristic". If the LLM call
-        or the classifier plugin fails, times out, or produces no usable tier, the configured
-        fallback_tier wins on a custom tier set, and classifier_fallback otherwise decides between
-        the heuristic scorer and default_model. The outcome's `cause` reports which path actually ran.
+        Falls back to the local heuristic scorer if classifier_type is "heuristic". Under
+        "heuristic_first" the scorer runs first and the classifier is called only for requests it
+        could not place at or below heuristic_first_max_tier. If the LLM call or the classifier
+        plugin fails, times out, or produces no usable tier, the configured fallback_tier wins on a
+        custom tier set, and classifier_fallback otherwise decides between the heuristic scorer and
+        default_model. The outcome's `cause` reports which path actually ran.
         """
         if self.config.classifier_type == "custom":
             return await self._classify_with_plugin(prompt, system_prompt, request_kwargs, raw_messages)
+        if self.config.classifier_type == "heuristic_first" and self.config.classifier_llm_config is not None:
+            return await self._classify_heuristic_first(prompt, system_prompt, request_kwargs, messages)
         if self.config.classifier_type != "llm" or self.config.classifier_llm_config is None:
             tier, score, signals, cause = self._score_and_classify(prompt, system_prompt)
             return ClassificationOutcome(tier=tier, score=score, signals=signals, cause=cause)
+        return await self._llm_classifier_outcome(prompt, system_prompt, request_kwargs, messages)
 
+    async def _classify_heuristic_first(
+        self,
+        prompt: str,
+        system_prompt: str | None,
+        request_kwargs: dict[str, Any] | None,  # mutable-ok: handed to _classify_with_llm as-is
+        messages: Sequence[Mapping[str, object]] | None,
+    ) -> ClassificationOutcome:
+        """Score locally, and only pay for the classifier call when the scorer did not confidently
+        place the request at or below heuristic_first_max_tier.
+
+        Confidence is `signals`, not `score`. A prompt where no dimension fired scores exactly 0.0,
+        which is below simple_medium and so lands SIMPLE by default rather than by evidence, and a
+        threshold check alone would hand that traffic to the cheapest model without ever consulting
+        the classifier. Scores also go negative when simple indicators fire, so a score threshold
+        would reject exactly the trivial prompts this path exists to serve.
+        """
+        tier, score, signals, cause = self._score_and_classify(prompt, system_prompt)
+        scored: Final = ClassificationOutcome(tier=tier, score=score, signals=signals, cause=cause)
+        threshold: Final = self.config.heuristic_first_max_tier
+        decided_cheaply: Final = (
+            threshold is not None
+            and bool(signals)
+            and self._active_tier_severity(tier) <= self._active_tier_severity(threshold)
+        )
+        if decided_cheaply:
+            return ClassificationOutcome(tier=tier, score=score, signals=signals, cause="heuristic_first_short_circuit")
+        return await self._llm_classifier_outcome(prompt, system_prompt, request_kwargs, messages, scored=scored)
+
+    async def _llm_classifier_outcome(
+        self,
+        prompt: str,
+        system_prompt: str | None,
+        request_kwargs: dict[str, Any] | None,  # mutable-ok: handed to _classify_with_llm as-is
+        messages: Sequence[Mapping[str, object]] | None,
+        scored: ClassificationOutcome | None = None,
+    ) -> ClassificationOutcome:
+        """Call the LLM classifier and turn its verdict, or its failure, into an outcome.
+
+        `scored` is the heuristic outcome the caller already computed, which only "heuristic_first"
+        has. It is handed to the failure path so a classifier error does not re-run the scorer.
+        """
         try:
             tier, classifier_cost = await self._classify_with_llm(prompt, system_prompt, request_kwargs, messages)
             return ClassificationOutcome(
@@ -1258,11 +1305,20 @@ class ComplexityRouter(CustomLogger):
                 classifier_cost=classifier_cost,
             )
         except Exception as e:  # noqa: BLE001 -- external LLM call can fail in many distinct ways (timeout, provider error, validation, parse error); any failure must fall back to the configured fallback path
-            return self._classifier_failure_outcome(f"LLM classifier failed ({e})", prompt, system_prompt)
+            return self._classifier_failure_outcome(f"LLM classifier failed ({e})", prompt, system_prompt, scored)
 
-    def _classifier_failure_outcome(self, reason: str, prompt: str, system_prompt: str | None) -> ClassificationOutcome:
+    def _classifier_failure_outcome(
+        self,
+        reason: str,
+        prompt: str,
+        system_prompt: str | None,
+        scored: ClassificationOutcome | None = None,
+    ) -> ClassificationOutcome:
         """The outcome when the LLM classifier or classifier plugin produced no usable tier:
-        fallback_tier on a custom tier set, classifier_fallback otherwise."""
+        fallback_tier on a custom tier set, classifier_fallback otherwise.
+
+        A caller that already scored the prompt passes `scored` so the heuristic arm returns that
+        verdict instead of running the same scan again on the request path."""
         fallback_tier: Final = self.config.fallback_tier
         if fallback_tier is not None:
             verbose_router_logger.warning("ComplexityRouter: %s, routing to fallback_tier %s", reason, fallback_tier)
@@ -1277,6 +1333,8 @@ class ComplexityRouter(CustomLogger):
         )
         if self.config.classifier_fallback == "default_model":
             return self._default_model_fallback_outcome()
+        if scored is not None:
+            return scored
         tier, score, signals, cause = self._score_and_classify(prompt, system_prompt)
         return ClassificationOutcome(tier=tier, score=score, signals=signals, cause=cause)
 

litellm/router_strategy/complexity_router/config.py

@@ -38,6 +38,11 @@ class ClassificationRubric(str, Enum):
 # routers get the calibrated rubric without changing what is already running.
 DEFAULT_CLASSIFICATION_RUBRIC: Final[ClassificationRubric] = ClassificationRubric.LEGACY
 
+# The classifier_type values that can call classifier_llm_config.model. Every consumer asking
+# "is the classifier model a real dependency of this router" resolves it here, including the ones
+# that only hold the raw config mapping and cannot reach ComplexityRouterConfig.uses_llm_classifier.
+LLM_CLASSIFIER_TYPES: Final[frozenset[str]] = frozenset({"llm", "heuristic_first"})
+
 
 TIER_SEVERITY_ORDER: Final[tuple[ComplexityTier, ...]] = (
     ComplexityTier.SIMPLE,
@@ -591,13 +596,30 @@ class ComplexityRouterConfig(BaseModel):
     )
 
     # Classifier strategy
-    classifier_type: Literal["heuristic", "llm", "custom"] = Field(
+    classifier_type: Literal["heuristic", "llm", "custom", "heuristic_first"] = Field(
         default="heuristic",
-        description="Classification strategy: local regex/keyword scoring, an LLM call, or a custom classifier plugin",
+        description=(
+            "Classification strategy: local regex/keyword scoring, an LLM call, a custom classifier "
+            "plugin, or 'heuristic_first', which scores locally and only pays for the LLM classifier "
+            "when the local scorer does not confidently land a cheap tier"
+        ),
     )
     classifier_llm_config: ClassifierLLMConfig | None = Field(
         default=None,
-        description="Configuration for the LLM classifier; required when classifier_type is 'llm'",
+        description="Configuration for the LLM classifier; required when classifier_type is 'llm' or 'heuristic_first'",
+    )
+    heuristic_first_max_tier: str | None = Field(
+        default=None,
+        description=(
+            "The highest tier the local scorer may decide on its own; required when classifier_type is "
+            "'heuristic_first' and rejected otherwise. A request whose heuristic tier is at or below this "
+            "one skips the LLM classifier and routes straight to that heuristic tier, so the classifier "
+            "call is only paid for on traffic the scorer could not place cheaply. The scorer must also "
+            "have produced at least one signal: a prompt where no dimension fired scores 0.0 and would "
+            "otherwise land SIMPLE by default rather than by evidence, which is how a chained router "
+            "would silently send unclassified traffic to the cheapest model. Names a built-in tier, and "
+            "may not name the highest one, since that would make the LLM classifier unreachable."
+        ),
     )
     classifier_plugin: ClassifierPlugin | None = Field(
         default=None,
@@ -626,7 +648,7 @@ class ComplexityRouterConfig(BaseModel):
             "which is what a classifier on some other taxonomy wants: a prompt that grades data "
             "sensitivity has no use for a complexity score, and scoring one produces a tier unrelated to "
             "what the operator configured. Requires default_model when set to 'default_model'. Only "
-            "applies when classifier_type is 'llm' or 'custom'."
+            "applies when classifier_type is 'llm', 'custom', or 'heuristic_first'."
         ),
     )
 
@@ -936,8 +958,8 @@ class ComplexityRouterConfig(BaseModel):
 
     @model_validator(mode="after")
     def _validate_classifier_config(self) -> "ComplexityRouterConfig":
-        if self.classifier_type == "llm" and self.classifier_llm_config is None:
-            raise ValueError("classifier_llm_config is required when classifier_type is 'llm'")
+        if self.uses_llm_classifier and self.classifier_llm_config is None:
+            raise ValueError(f"classifier_llm_config is required when classifier_type is {self.classifier_type!r}")
         if self.classifier_type == "custom" and self.classifier_plugin is None:
             raise ValueError("classifier_plugin is required when classifier_type is 'custom'")
         if self.classifier_plugin is not None and self.classifier_type != "custom":
@@ -947,6 +969,49 @@ class ComplexityRouterConfig(BaseModel):
             )
         return self
 
+    @field_validator("heuristic_first_max_tier", mode="before")
+    @classmethod
+    def _coerce_heuristic_first_max_tier(cls, value: object) -> object:
+        if isinstance(value, ComplexityTier):
+            return value.value
+        if isinstance(value, str):
+            return value.strip()
+        return value
+
+    @model_validator(mode="after")
+    def _validate_heuristic_first_max_tier(self) -> "ComplexityRouterConfig":
+        if self.classifier_type != "heuristic_first":
+            if self.heuristic_first_max_tier is not None:
+                raise ValueError(
+                    f"heuristic_first_max_tier is set but classifier_type is {self.classifier_type!r}; "
+                    "the local scorer would never gate the classifier. Set classifier_type "
+                    "'heuristic_first' or remove heuristic_first_max_tier"
+                )
+            return self
+        threshold: Final = self.heuristic_first_max_tier
+        if threshold is None:
+            raise ValueError(
+                "heuristic_first_max_tier is required when classifier_type is 'heuristic_first': without a "
+                "threshold there is nothing to decide whether a request escalates to the LLM classifier"
+            )
+        names: Final = self.tier_names()
+        if threshold not in names:
+            raise ValueError(
+                f"heuristic_first_max_tier {threshold!r} is not an active tier: it must name one of {', '.join(names)}"
+            )
+        if threshold == names[-1]:
+            raise ValueError(
+                f"heuristic_first_max_tier {threshold} is the highest tier, so every request would short-circuit "
+                "and the LLM classifier would never run; name a lower tier or use classifier_type 'heuristic'"
+            )
+        if threshold not in self.tiers:
+            raise ValueError(
+                f"heuristic_first_max_tier {threshold} has no model configured in tiers; a threshold pointing at "
+                "an unconfigured tier would route short-circuited requests to the default fallback instead of the "
+                "pool the operator intended"
+            )
+        return self
+
     @field_validator("fallback_tier", "classification_prompt")
     @classmethod
     def _reject_blank_optional_text(cls, value: str | None) -> str | None:
@@ -969,6 +1034,14 @@ class ComplexityRouterConfig(BaseModel):
         """True when the operator replaced the built-in tier set via tier_definitions."""
         return self.tier_definitions is not None
 
+    @property
+    def uses_llm_classifier(self) -> bool:
+        """True when this router can call classifier_llm_config.model, so the model is a real
+        dependency: authorized against the caller's key, counted in the health graph, and given a
+        prebuilt rubric. 'heuristic_first' only calls it for traffic the local scorer escalates,
+        which still makes it a dependency on every one of those requests."""
+        return self.classifier_type in LLM_CLASSIFIER_TYPES
+
     def tier_names(self) -> tuple[str, ...]:
         """The active tier names: the defined names, or the built-in set in severity order."""
         if self.tier_definitions is not None:
@@ -1063,7 +1136,7 @@ class ComplexityRouterConfig(BaseModel):
         )
         if duplicated:
             raise ValueError(f"tier_definitions names must be unique (case-insensitive): {', '.join(duplicated)}")
-        if self.classifier_type == "heuristic":
+        if self.classifier_type in ("heuristic", "heuristic_first"):
             raise ValueError(
                 "tier_definitions requires classifier_type 'llm' or 'custom': the heuristic scorer only "
                 "produces the built-in tiers"

litellm/router_utils/auto_router_model_naming.py

@@ -15,6 +15,8 @@ from dataclasses import dataclass
 from types import MappingProxyType
 from typing import Final, Literal, TypeAlias
 
+from litellm.router_strategy.complexity_router.config import LLM_CLASSIFIER_TYPES
+
 AUTO_ROUTER_MODEL_PREFIX: Final = "auto_router/"
 
 StrategyRouterKind = Literal["semantic", "complexity", "adaptive", "quality"]
@@ -144,7 +146,11 @@ def strategy_router_dependencies(
         dict.fromkeys(
             tuple(dep for tier in _mapping(complexity.get("tiers")).values() for dep in _pool(tier, "tier"))
             + _named(litellm_params.get("complexity_router_default_model"), "default")
-            + (_named(classifier.get("model"), "classifier") if complexity.get("classifier_type") == "llm" else ())
+            + (
+                _named(classifier.get("model"), "classifier")
+                if complexity.get("classifier_type") in LLM_CLASSIFIER_TYPES
+                else ()
+            )
             + (
                 _named(complexity.get("embedding_model"), "embedding")
                 if complexity.get("semantic_keyword_matching")

litellm/types/llms/anthropic.py

@@ -507,11 +507,16 @@ class MessageDelta(TypedDict, total=False):
     stop_reason: str | None
 
 
+class ServerToolUsage(TypedDict, total=False):
+    web_search_requests: ReadOnly[int]
+
+
 class UsageDelta(TypedDict, total=False):
     input_tokens: int
     output_tokens: int
     cache_creation_input_tokens: int
     cache_read_input_tokens: int
+    server_tool_use: ReadOnly[ServerToolUsage]
 
 
 class AppliedEdit(TypedDict, total=False):

litellm/types/llms/anthropic_messages/anthropic_response.py

@@ -1,11 +1,12 @@
 from typing import Any, Literal, TypeAlias
 
-from typing_extensions import NotRequired, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict
 
 from litellm.types.llms.anthropic import (
     AnthropicResponseContentBlockText,
     AnthropicResponseContentBlockToolUse,
     ContextManagementResponse,
+    ServerToolUsage,
 )
 
 
@@ -71,6 +72,11 @@ class AnthropicUsage(TypedDict, total=False):
     cache_creation_input_tokens: int
     cache_read_input_tokens: int
 
+    """
+    Server-side tool usage (e.g. web search request counts)
+    """
+    server_tool_use: NotRequired[ReadOnly[ServerToolUsage]]
+
 
 class AnthropicMessagesResponse(TypedDict, total=False):
     """

litellm/types/passthrough_endpoints/pass_through_endpoints.py

@@ -22,6 +22,7 @@ LITELLM_PASS_THROUGH_ENDPOINT_MARKER: Final = "__litellm_pass_through_endpoint__
 
 class EndpointType(str, Enum):
     VERTEX_AI = "vertex-ai"
+    GEMINI = "gemini"
     ANTHROPIC = "anthropic"
     OPENAI = "openai"
     GENERIC = "generic"

litellm/types/utils.py

@@ -2808,6 +2808,12 @@ RoutingDecisionCause = Literal[
     # meant anything that filtered `signals` silently changed what the row claimed.
     "reasoning_override",
     "llm_classifier",
+    # classifier_type 'heuristic_first': the local scorer produced at least one signal and landed at
+    # or below heuristic_first_max_tier, so it decided the tier and the LLM classifier was never
+    # called. Distinct from "heuristic_scorer", which is a router whose only classifier IS the
+    # scorer, and from "classifier_fallback", which is the scorer running because a call failed:
+    # only this cause means an LLM classifier was configured, reachable, and deliberately skipped.
+    "heuristic_first_short_circuit",
     # The operator's classifier plugin (classifier_type 'custom') decided the tier.
     "classifier_plugin",
     # The LLM classifier or classifier plugin failed on a router with an operator-defined
@@ -2834,13 +2840,19 @@ RoutingDecisionCause = Literal[
 ]
 
 
-InternalCallOrigin = Literal["autorouter_classifier", "shadow_eval_router", "shadow_eval_judge"]
+InternalCallOrigin = Literal[
+    "autorouter_classifier",
+    "shadow_eval_router",
+    "shadow_eval_judge",
+    "background_response_cost_poll",
+]
 """Which internal litellm feature originated a billed sub-call, so a spend log row
 records that it is not traffic the caller sent."""
 
 AUTOROUTER_CLASSIFIER_CALL_ORIGIN: Final[InternalCallOrigin] = "autorouter_classifier"
 SHADOW_EVAL_ROUTER_CALL_ORIGIN: Final[InternalCallOrigin] = "shadow_eval_router"
 SHADOW_EVAL_JUDGE_CALL_ORIGIN: Final[InternalCallOrigin] = "shadow_eval_judge"
+BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN: Final[InternalCallOrigin] = "background_response_cost_poll"
 
 
 class StandardLoggingRoutingDecision(TypedDict, total=False):

litellm/utils.py

@@ -74,6 +74,7 @@ from litellm.constants import (
     MAX_RETRY_DELAY,
     MAX_TOKEN_TRIMMING_ATTEMPTS,
     MINIMUM_PROMPT_CACHE_TOKEN_COUNT_OVERRIDE,
+    NON_INFERENCE_CALL_TYPES,
     OPENAI_EMBEDDING_PARAMS,
     TOOL_CHOICE_OBJECT_TOKEN_COUNT,
 )
@@ -1109,6 +1110,8 @@ def function_setup(
             except Exception as e:
                 verbose_logger.debug("Error extracting messages from Google contents: %s", e)
                 messages = "default-message-value"
+        elif call_type in NON_INFERENCE_CALL_TYPES:
+            messages = []  # mutable-ok: loggers require a list here and Logging copies it
         else:
             messages = "default-message-value"
         stream = False

tests/e2e/management/test_budget_customer_user_org_e2e.py

@@ -163,12 +163,6 @@ class TestBudgetManagement:
             f"/budget/list never included the created budget {budget_id}",
         )
 
-    @pytest.mark.skip(
-        reason=(
-            "stage red: product gap, /budget/update 500s on any model_max_budget "
-            "(prisma Json arg + unquoted GraphQL interpolation)"
-        )
-    )
     @pytest.mark.covers("mgmt.budget.update.accepts_model_max_budget")
     def test_update_accepts_per_model_budgets_including_punctuated_names(
         self, client: ManagementClient, resources: ResourceManager

tests/proxy_unit_tests/test_check_responses_cost.py

@@ -753,3 +753,41 @@ class TestCheckResponsesCost:
         call_kwargs = mock_aget.call_args[1]
         assert "model" not in call_kwargs.get("litellm_metadata", {})
         assert "model_group" not in call_kwargs.get("litellm_metadata", {})
+
+    @pytest.mark.asyncio
+    async def test_poll_stamps_internal_call_origin_so_the_read_is_billed(
+        self, check_responses_cost_instance, mock_prisma_client
+    ):
+        """A background create returns queued with no usage, so this poll's retrieval is the only
+        place the job's spend is ever seen. Without the origin stamp it is priced at zero like a
+        user-facing read (LIT-5602) and the job is never billed."""
+        from litellm.constants import INTERNAL_CALL_ORIGIN_METADATA_KEY
+        from litellm.litellm_core_utils.internal_call_metadata import (
+            is_unbilled_non_inference_call,
+        )
+
+        mock_job = MagicMock()
+        mock_job.unified_object_id = "resp_test_billed"
+        mock_job.created_by = "test-user"
+        mock_job.id = "job-billed"
+        mock_job.file_object = {"model": "gpt-5", "id": "resp_test_billed"}
+
+        mock_prisma_client.db.litellm_managedobjecttable.find_many = AsyncMock(
+            return_value=[mock_job]
+        )
+        mock_prisma_client.db.litellm_managedobjecttable.update_many = AsyncMock(
+            return_value=0
+        )
+
+        mock_response = MagicMock()
+        mock_response.status = "completed"
+
+        with patch("litellm.aget_responses", new_callable=AsyncMock) as mock_aget:
+            mock_aget.return_value = mock_response
+            await check_responses_cost_instance.check_responses_cost()
+
+        metadata = mock_aget.call_args[1]["litellm_metadata"]
+        foreground_read = {"background": False}
+        assert metadata[INTERNAL_CALL_ORIGIN_METADATA_KEY] == "background_response_cost_poll"
+        assert is_unbilled_non_inference_call("aget_responses", metadata, foreground_read) is False
+        assert is_unbilled_non_inference_call("aget_responses", None, foreground_read) is True

tests/test_litellm/google_genai/test_google_genai_streaming_iterator.py

@@ -8,6 +8,36 @@ from litellm.google_genai.streaming_iterator import (
     GoogleGenAIGenerateContentStreamingIterator,
 )
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+from litellm.types.passthrough_endpoints.pass_through_endpoints import EndpointType
+
+
+@pytest.mark.parametrize(
+    "custom_llm_provider, expected_endpoint_type",
+    [("gemini", EndpointType.GEMINI), ("vertex_ai", EndpointType.VERTEX_AI)],
+)
+@pytest.mark.parametrize(
+    "iterator_cls",
+    [
+        AsyncGoogleGenAIGenerateContentStreamingIterator,
+        GoogleGenAIGenerateContentStreamingIterator,
+    ],
+)
+def test_streaming_logging_targets_the_provider_that_served_the_request(
+    iterator_cls: type,
+    custom_llm_provider: str,
+    expected_endpoint_type: EndpointType,
+):
+    """Routing every google stream through the vertex handler bills gemini/* at vertex_ai/ rates."""
+    iterator = iterator_cls(
+        response=MagicMock(),
+        model="gemini-3.1-flash-image",
+        logging_obj=MagicMock(spec=LiteLLMLoggingObj),
+        generate_content_provider_config=MagicMock(),
+        litellm_metadata={},
+        custom_llm_provider=custom_llm_provider,
+    )
+
+    assert iterator.endpoint_type is expected_endpoint_type
 
 
 def _large_inline_data_event() -> str:
@@ -53,9 +83,7 @@ async def test_async_streaming_iterator_yields_complete_sse_events():
     assert chunk.startswith(b"data: ")
     assert chunk.endswith(b"\n\n")
     assert (
-        json.loads(chunk[len(b"data: ") : -2])["candidates"][0]["content"]["parts"][0][
-            "inlineData"
-        ]["mimeType"]
+        json.loads(chunk[len(b"data: ") : -2])["candidates"][0]["content"]["parts"][0]["inlineData"]["mimeType"]
         == "image/jpeg"
     )
 
@@ -76,9 +104,9 @@ def test_sync_streaming_iterator_yields_complete_sse_events():
     chunk = next(iterator)
     assert chunk.startswith(b"data: ")
     assert chunk.endswith(b"\n\n")
-    assert json.loads(chunk[len(b"data: ") : -2])["candidates"][0]["content"]["parts"][
-        0
-    ]["inlineData"]["data"].startswith("A")
+    assert json.loads(chunk[len(b"data: ") : -2])["candidates"][0]["content"]["parts"][0]["inlineData"][
+        "data"
+    ].startswith("A")
 
 
 @pytest.mark.asyncio

tests/test_litellm/integrations/otel/test_otel_v2_metrics.py

@@ -201,6 +201,36 @@ def test_time_to_first_token_is_streaming_only():
     assert names == set(ALL_METRICS) - {TIME_TO_FIRST_TOKEN}
 
 
+def test_response_read_does_not_replay_the_generation_usage():
+    """A responses-management read returns the ORIGINAL generation's usage on the
+    object it fetches. Recording it would add those tokens again on every poll, so
+    the two usage-derived instruments are skipped while the duration ones, which
+    describe the read itself, still fire."""
+    metrics = _drive_success(InMemoryMetricReader(), call_type="aget_responses")
+
+    assert TOKEN_USAGE not in metrics
+    assert TIME_PER_OUTPUT_TOKEN not in metrics
+    assert OPERATION_DURATION in metrics
+    assert RESPONSE_DURATION in metrics
+
+
+def test_background_response_read_still_records_usage():
+    """A background=true create returns no usage, so its completed read is the only
+    place the generation's tokens are ever seen. Skipping it would lose them
+    entirely rather than deduplicate them."""
+    reader = InMemoryMetricReader()
+    logger = _logger(reader, enable_metrics=True)
+    kwargs, response_obj, start, end = _build_call(call_type="aget_responses")
+    response_obj["background"] = True
+    asyncio.run(logger.async_log_success_event(kwargs, response_obj, start, end))
+
+    metrics = _metrics_by_name(reader)
+    by_type = {dp.attributes[TOKEN_TYPE]: dp for dp in metrics[TOKEN_USAGE]}
+    assert by_type["input"].sum == PROMPT_TOKENS
+    assert by_type["output"].sum == COMPLETION_TOKENS
+    assert TIME_PER_OUTPUT_TOKEN in metrics
+
+
 def test_metrics_disabled_records_nothing():
     """enable_metrics=False: the recorder is never built, so the injected reader
     sees no gen_ai.client.* series even though the success hook runs."""

tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py

@@ -268,6 +268,27 @@ def test_vector_store_file_management_is_not_chat(call_type):
     assert resolve_operation(call_type).value == "litellm.vector_store_file_management"
 
 
+@pytest.mark.parametrize(
+    "call_type",
+    [
+        f"{prefix}{operation}"
+        for operation in ("get_responses", "delete_responses", "cancel_responses", "list_input_items")
+        for prefix in ("", "a")
+    ],
+)
+def test_responses_management_is_not_chat(call_type):
+    """Fetching, deleting or cancelling a stored response runs no inference, so it must not
+    read as a chat completion: the retrieved object replays the original call's tokens and
+    would inflate the chat series on every read. Regression test for LIT-5602."""
+    assert resolve_operation(call_type) is GenAIOperation.LITELLM_RESPONSES_MANAGEMENT
+    assert resolve_operation(call_type).value == "litellm.responses_management"
+
+
+def test_creating_a_response_is_still_chat():
+    """Guards the test above: ``/v1/responses`` itself is a chat completion."""
+    assert resolve_operation("aresponses") is GenAIOperation.CHAT
+
+
 _NON_CHAT_ROUTES: Final = (
     ("image_generation", GenAIOperation.GENERATE_CONTENT, GenAIOutputType.IMAGE),
     ("speech", GenAIOperation.GENERATE_CONTENT, GenAIOutputType.SPEECH),

tests/test_litellm/integrations/test_opentelemetry.py

@@ -6345,3 +6345,95 @@ class TestOpenTelemetryDatabaseSemconvAttributes(unittest.TestCase):
         span = self._service_span(ServiceTypes.DB, "get_data", None)
         self.assertEqual(span.attributes["db.system.name"], "postgresql")
         self.assertNotIn("server.address", span.attributes)
+
+
+class TestOpenTelemetryNonInferenceUsage(unittest.TestCase):
+    """Reading a stored response replays the usage of the call that created it, so emitting those
+    token counts again on the read's span reports the same tokens a second time. Regression tests
+    for LIT-5602, covering the legacy emitter that runs by default."""
+
+    USAGE = {"prompt_tokens": 4000, "completion_tokens": 2000, "total_tokens": 6000}
+    TOKEN_KEYS = frozenset({"gen_ai.usage.input_tokens", "gen_ai.usage.output_tokens", "gen_ai.usage.total_tokens"})
+    BACKGROUND_POLL = {"internal_call_origin": "background_response_cost_poll"}
+    RESPONSE_OBJ = {"id": "resp_lit5602", "model": "gpt-4o", "usage": USAGE}
+    BACKGROUND_RESPONSE_OBJ = {**RESPONSE_OBJ, "background": True}
+
+    def _kwargs(self, call_type, litellm_metadata=None):
+        return {
+            "model": "gpt-4o",
+            "call_type": call_type,
+            "optional_params": {},
+            "litellm_params": {
+                "custom_llm_provider": "openai",
+                "litellm_metadata": litellm_metadata or {},
+            },
+            "standard_logging_object": {"id": "lit5602", "call_type": call_type, "metadata": {}},
+        }
+
+    def _token_attributes_on_span(self, call_type, litellm_metadata=None, response_obj=None):
+        otel = OpenTelemetry()
+        mock_span = MagicMock()
+        otel.set_attributes(
+            span=mock_span,
+            kwargs=self._kwargs(call_type, litellm_metadata),
+            response_obj=response_obj or dict(self.RESPONSE_OBJ),
+        )
+        return {call[0][0] for call in mock_span.set_attribute.call_args_list if call[0][0] in self.TOKEN_KEYS}
+
+    def _token_histogram_calls(self, call_type, litellm_metadata=None, response_obj=None):
+        otel = OpenTelemetry()
+        otel._operation_duration_histogram = MagicMock()
+        otel._token_usage_histogram = MagicMock()
+        otel._cost_histogram = None
+        now = datetime.now()
+        otel._record_metrics(
+            self._kwargs(call_type, litellm_metadata), response_obj or dict(self.RESPONSE_OBJ), now, now
+        )
+        return otel._token_usage_histogram.record.call_count
+
+    def _time_per_output_token_calls(self, call_type, litellm_metadata=None, response_obj=None):
+        otel = OpenTelemetry()
+        otel._time_per_output_token_histogram = MagicMock()
+        now = datetime.now()
+        otel._record_time_per_output_token_metric(
+            self._kwargs(call_type, litellm_metadata), response_obj or dict(self.RESPONSE_OBJ), now, 1.0, {}
+        )
+        return otel._time_per_output_token_histogram.record.call_count
+
+    def test_inference_call_still_reports_its_tokens_on_the_span(self):
+        self.assertEqual(self._token_attributes_on_span("acompletion"), set(self.TOKEN_KEYS))
+
+    def test_response_read_does_not_report_the_retrieved_tokens_on_the_span(self):
+        self.assertEqual(self._token_attributes_on_span("aget_responses"), set())
+
+    def test_background_cost_poll_read_still_reports_its_tokens_on_the_span(self):
+        self.assertEqual(self._token_attributes_on_span("aget_responses", self.BACKGROUND_POLL), set(self.TOKEN_KEYS))
+
+    def test_inference_call_still_records_the_token_usage_histogram(self):
+        self.assertEqual(self._token_histogram_calls("acompletion"), 2)
+
+    def test_response_read_does_not_record_the_token_usage_histogram(self):
+        self.assertEqual(self._token_histogram_calls("aget_responses"), 0)
+
+    def test_background_cost_poll_read_still_records_the_token_usage_histogram(self):
+        self.assertEqual(self._token_histogram_calls("aget_responses", self.BACKGROUND_POLL), 2)
+
+    def test_background_response_read_still_reports_its_tokens_on_the_span(self):
+        self.assertEqual(
+            self._token_attributes_on_span("aget_responses", response_obj=self.BACKGROUND_RESPONSE_OBJ),
+            set(self.TOKEN_KEYS),
+        )
+
+    def test_background_response_read_still_records_the_token_usage_histogram(self):
+        self.assertEqual(self._token_histogram_calls("aget_responses", response_obj=self.BACKGROUND_RESPONSE_OBJ), 2)
+
+    def test_inference_call_still_records_time_per_output_token(self):
+        self.assertEqual(self._time_per_output_token_calls("acompletion"), 1)
+
+    def test_response_read_does_not_divide_its_latency_by_the_retrieved_token_count(self):
+        self.assertEqual(self._time_per_output_token_calls("aget_responses"), 0)
+
+    def test_background_response_read_still_records_time_per_output_token(self):
+        self.assertEqual(
+            self._time_per_output_token_calls("aget_responses", response_obj=self.BACKGROUND_RESPONSE_OBJ), 1
+        )

tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py

@@ -1552,6 +1552,76 @@ def test_string_cost_values():
     assert round(completion_cost, 12) == round(expected_completion_cost, 12)
 
 
+def test_generic_cost_per_token_overlapping_cached_and_image_tokens():
+    """Some providers report cached_tokens and image_tokens as overlapping subsets of
+    prompt_tokens. Billing each in full charged the overlap twice, once at the cache rate
+    and again at the input rate."""
+    model = "litellm-test-overlapping-cached-image"
+    litellm.register_model(
+        {
+            model: {
+                "litellm_provider": "openai",
+                "mode": "chat",
+                "input_cost_per_token": 1e-6,
+                "cache_read_input_token_cost": 1e-7,
+                "output_cost_per_token": 2e-6,
+            }
+        }
+    )
+    usage = Usage(
+        prompt_tokens=100,
+        completion_tokens=10,
+        total_tokens=110,
+        prompt_tokens_details=PromptTokensDetailsWrapper(
+            text_tokens=None, cached_tokens=90, image_tokens=80
+        ),
+    )
+
+    prompt_cost, completion_cost = generic_cost_per_token(
+        model=model, usage=usage, custom_llm_provider="openai"
+    )
+
+    # 90 cached at 1e-7, the remaining 10 uncached tokens once at 1e-6
+    assert prompt_cost == pytest.approx(90 * 1e-7 + 10 * 1e-6)
+    assert completion_cost == pytest.approx(10 * 2e-6)
+
+
+def test_generic_cost_per_token_warm_prefix_cache_spanning_text_and_image_tokens():
+    """xAI reports text_tokens + image_tokens = prompt_tokens with cached_tokens overlapping
+    both, so a warm prefix cache covering the whole image exceeds the text-only count.
+    Observed live on grok-4.6 (issue #37281): the image tokens were billed a second time at
+    the full input rate on top of the cache-read bucket, 0.003500 in vs the provider's own
+    0.001274 bill."""
+    model = "litellm-test-warm-prefix-cache-overlap"
+    litellm.register_model(
+        {
+            model: {
+                "litellm_provider": "openai",
+                "mode": "chat",
+                "input_cost_per_token": 2e-6,
+                "cache_read_input_token_cost": 5e-7,
+                "output_cost_per_token": 6e-6,
+            }
+        }
+    )
+    usage = Usage(
+        prompt_tokens=2461,
+        completion_tokens=440,
+        total_tokens=2901,
+        prompt_tokens_details=PromptTokensDetailsWrapper(
+            text_tokens=1319, cached_tokens=2432, image_tokens=1142
+        ),
+    )
+
+    prompt_cost, completion_cost = generic_cost_per_token(
+        model=model, usage=usage, custom_llm_provider="openai"
+    )
+
+    # 2432 cached at the cache-read rate, the 29 uncached tokens once at the input rate
+    assert prompt_cost == pytest.approx(2432 * 5e-7 + 29 * 2e-6)
+    assert completion_cost == pytest.approx(440 * 6e-6)
+
+
 def test_calculate_cost_component_with_string_values():
     """Test the calculate_cost_component function directly with string cost values."""
     from litellm.litellm_core_utils.llm_cost_calc.utils import calculate_cost_component

tests/test_litellm/litellm_core_utils/llm_cost_calc/test_tool_call_cost_tracking_dict_safety.py

@@ -8,10 +8,9 @@ See https://github.com/BerriAI/litellm/issues/26153.
 
 import pytest
 
-
 from litellm.litellm_core_utils.llm_cost_calc.tool_call_cost_tracking import (
     StandardBuiltInToolCostTracking,
-    _get_web_search_requests,
+    get_web_search_requests,
 )
 from litellm.types.utils import ModelResponse, ServerToolUse, Usage
 
@@ -28,25 +27,25 @@ class _UsageWithDictServerToolUse:
 
 
 def test_get_web_search_requests_handles_none():
-    assert _get_web_search_requests(None) is None
+    assert get_web_search_requests(None) is None
 
 
 def test_get_web_search_requests_handles_dict():
-    assert _get_web_search_requests({"web_search_requests": 5}) == 5
+    assert get_web_search_requests({"web_search_requests": 5}) == 5
 
 
 def test_get_web_search_requests_handles_dict_missing_key():
-    assert _get_web_search_requests({}) is None
+    assert get_web_search_requests({}) is None
 
 
 def test_get_web_search_requests_handles_pydantic():
     stu = ServerToolUse(web_search_requests=7)
-    assert _get_web_search_requests(stu) == 7
+    assert get_web_search_requests(stu) == 7
 
 
 def test_get_web_search_requests_handles_pydantic_with_none_value():
     stu = ServerToolUse()
-    assert _get_web_search_requests(stu) is None
+    assert get_web_search_requests(stu) is None
 
 
 def test_response_object_includes_web_search_call_with_dict_server_tool_use():

tests/test_litellm/litellm_core_utils/test_litellm_logging.py

@@ -5225,6 +5225,197 @@ async def test_restore_correlation_context_works_across_asyncio_task_boundary():
         session_id_var.set("")
 
 
+class TestNonInferenceCallTypesAreNotBilled:
+    """A retrieved response replays the usage of the call that created it, so pricing a read
+    of it double bills the same tokens. Regression tests for LIT-5602."""
+
+    RETRIEVED_RESPONSE_USAGE = {"input_tokens": 4000, "output_tokens": 2000, "total_tokens": 6000}
+
+    BACKGROUND_POLL_METADATA = {"internal_call_origin": "background_response_cost_poll"}
+
+    def _logging_obj(self, call_type: str, litellm_metadata: dict | None = None):
+        from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+
+        obj = LiteLLMLoggingObj(
+            model="gpt-4o",
+            messages=[],
+            stream=False,
+            call_type=call_type,
+            start_time=time.time(),
+            litellm_call_id=f"lit5602-{call_type}",
+            function_id="fn-lit5602",
+        )
+        obj.update_environment_variables(
+            model="gpt-4o",
+            user="",
+            optional_params={},
+            litellm_params={
+                "api_base": "",
+                "custom_llm_provider": "openai",
+                "litellm_metadata": litellm_metadata or {},
+            },
+        )
+        return obj
+
+    def _retrieved_response(self, background: bool | None = None):
+        from litellm.types.llms.openai import ResponsesAPIResponse
+
+        return ResponsesAPIResponse(
+            id="resp_lit5602",
+            created_at=1234567890,
+            model="gpt-4o",
+            output=[],
+            usage=self.RETRIEVED_RESPONSE_USAGE,
+            background=background,
+        )
+
+    def test_creating_a_response_is_still_priced(self):
+        """Guards the tests below: the same response object must cost money on the create path."""
+        cost = self._logging_obj("aresponses")._response_cost_calculator(result=self._retrieved_response())
+        assert cost is not None and cost > 0
+
+    @pytest.mark.parametrize(
+        "call_type",
+        [
+            "aget_responses",
+            "adelete_responses",
+            "acancel_responses",
+            "alist_input_items",
+            "avector_store_delete",
+            "avector_store_file_content",
+            "avector_store_file_delete",
+        ],
+    )
+    def test_read_and_management_calls_cost_nothing(self, call_type):
+        cost = self._logging_obj(call_type)._response_cost_calculator(result=self._retrieved_response())
+        assert cost == 0.0
+
+    def test_retrieved_usage_is_not_re_reported_in_standard_logging_payload(self):
+        from litellm.litellm_core_utils.litellm_logging import (
+            get_standard_logging_object_payload,
+        )
+
+        from datetime import datetime
+
+        logging_obj = self._logging_obj("aget_responses")
+        now = datetime.now()
+        payload = get_standard_logging_object_payload(
+            kwargs={
+                "litellm_call_id": "lit5602-payload",
+                "model": "gpt-4o",
+                "call_type": "aget_responses",
+                "litellm_params": {},
+            },
+            init_response_obj=self._retrieved_response(),
+            start_time=now,
+            end_time=now,
+            logging_obj=logging_obj,
+            status="success",
+        )
+
+        assert payload is not None
+        assert payload["prompt_tokens"] == 0
+        assert payload["completion_tokens"] == 0
+        assert payload["total_tokens"] == 0
+        assert payload["response_cost"] == 0.0
+
+    def test_background_cost_poll_read_is_still_priced(self):
+        """A background create returns queued with no usage, so the poller's read carries the job's
+        only billable usage. Zeroing it there means background jobs are never billed."""
+        cost = self._logging_obj(
+            "aget_responses", litellm_metadata=self.BACKGROUND_POLL_METADATA
+        )._response_cost_calculator(result=self._retrieved_response())
+        assert cost is not None and cost > 0
+
+    def test_background_cost_poll_reports_usage_in_standard_logging_payload(self):
+        from datetime import datetime
+
+        from litellm.litellm_core_utils.litellm_logging import (
+            get_standard_logging_object_payload,
+        )
+
+        now = datetime.now()
+        payload = get_standard_logging_object_payload(
+            kwargs={
+                "litellm_call_id": "lit5602-poll-payload",
+                "model": "gpt-4o",
+                "call_type": "aget_responses",
+                "litellm_params": {"litellm_metadata": self.BACKGROUND_POLL_METADATA},
+            },
+            init_response_obj=self._retrieved_response(),
+            start_time=now,
+            end_time=now,
+            logging_obj=self._logging_obj(
+                "aget_responses", litellm_metadata=self.BACKGROUND_POLL_METADATA
+            ),
+            status="success",
+        )
+
+        assert payload is not None
+        assert payload["total_tokens"] == 6000
+
+    def test_reading_a_background_response_is_still_priced(self):
+        """A background create answers queued with no usage at all, so whoever reads the finished
+        job is the first and only caller to see its tokens. Zeroing that read bills the job nothing."""
+        cost = self._logging_obj("aget_responses")._response_cost_calculator(
+            result=self._retrieved_response(background=True)
+        )
+        assert cost is not None and cost > 0
+
+    def test_reading_a_background_response_reports_usage_in_standard_logging_payload(self):
+        from datetime import datetime
+
+        from litellm.litellm_core_utils.litellm_logging import (
+            get_standard_logging_object_payload,
+        )
+
+        now = datetime.now()
+        payload = get_standard_logging_object_payload(
+            kwargs={
+                "litellm_call_id": "lit5602-background-payload",
+                "model": "gpt-4o",
+                "call_type": "aget_responses",
+                "litellm_params": {},
+            },
+            init_response_obj=self._retrieved_response(background=True),
+            start_time=now,
+            end_time=now,
+            logging_obj=self._logging_obj("aget_responses"),
+            status="success",
+        )
+
+        assert payload is not None
+        assert payload["total_tokens"] == 6000
+
+    def test_reading_a_foreground_response_is_still_free(self):
+        """Guards the test above against a blanket exemption: an explicit background=false read was
+        already billed by its create and must stay at zero."""
+        cost = self._logging_obj("aget_responses")._response_cost_calculator(
+            result=self._retrieved_response(background=False)
+        )
+        assert cost == 0.0
+
+    def _read_call_messages(self):
+        logging_obj, _ = litellm.utils.function_setup(
+            original_function="aget_responses",
+            rules_obj=litellm.utils.Rules(),
+            start_time=time.time(),
+            **{"litellm_call_id": "lit5602-setup", "response_id": "resp_lit5602"},
+        )
+        return logging_obj.model_call_details["messages"]
+
+    def test_read_calls_do_not_log_a_placeholder_chat_message(self):
+        assert self._read_call_messages() == []
+
+    def test_read_call_messages_survive_a_logger_that_walks_them(self):
+        """Loggers reach into this value expecting a chat history and branch on it being a list.
+        An empty list reads as no messages; a tuple matches no branch and crashes the success hook,
+        and None is not iterable where other loggers walk it."""
+        from litellm.integrations.lunary import parse_messages
+
+        assert parse_messages(self._read_call_messages()) == []
+
+
 def _build_success_payload(logging_obj, kwargs):
     import datetime
 

tests/test_litellm/llms/anthropic/experimental_pass_through/adapters/test_anthropic_experimental_pass_through_adapters_transformation.py

@@ -4066,3 +4066,98 @@ def test_tool_result_without_translatable_content_still_answers_its_tool_use(too
         {"role": "tool", "tool_call_id": "toolu_01", "content": ""},
     ]
     assert result[0]["role"] == "assistant"
+
+
+def _openai_response_with_usage(usage: Usage) -> ModelResponse:
+    return ModelResponse(
+        id="resp_web_search",
+        model="gemini-3-flash-preview",
+        choices=[
+            Choices(
+                finish_reason="stop",
+                index=0,
+                message=Message(role="assistant", content="searched"),
+            )
+        ],
+        usage=usage,
+    )
+
+
+def test_translate_openai_response_to_anthropic_maps_gemini_web_search_usage():
+    from litellm.types.utils import PromptTokensDetailsWrapper
+
+    usage = Usage(
+        prompt_tokens=385,
+        completion_tokens=566,
+        total_tokens=951,
+        prompt_tokens_details=PromptTokensDetailsWrapper(text_tokens=385, web_search_requests=2),
+    )
+
+    anthropic_response = LiteLLMAnthropicMessagesAdapter().translate_openai_response_to_anthropic(
+        response=_openai_response_with_usage(usage)
+    )
+
+    assert anthropic_response["usage"]["server_tool_use"] == {"web_search_requests": 2}
+
+
+def test_translate_openai_response_to_anthropic_maps_server_tool_use_web_search_usage():
+    from litellm.types.utils import ServerToolUse
+
+    usage = Usage(
+        prompt_tokens=100,
+        completion_tokens=40,
+        total_tokens=140,
+        server_tool_use=ServerToolUse(web_search_requests=3),
+    )
+
+    anthropic_response = LiteLLMAnthropicMessagesAdapter().translate_openai_response_to_anthropic(
+        response=_openai_response_with_usage(usage)
+    )
+
+    assert anthropic_response["usage"]["server_tool_use"] == {"web_search_requests": 3}
+
+
+def test_translate_openai_response_to_anthropic_omits_server_tool_use_without_web_search():
+    usage = Usage(prompt_tokens=100, completion_tokens=40, total_tokens=140)
+
+    anthropic_response = LiteLLMAnthropicMessagesAdapter().translate_openai_response_to_anthropic(
+        response=_openai_response_with_usage(usage)
+    )
+
+    assert "server_tool_use" not in anthropic_response["usage"]
+
+
+def test_completion_cost_on_translated_anthropic_response_includes_web_search():
+    from litellm.types.utils import PromptTokensDetailsWrapper
+
+    adapter = LiteLLMAnthropicMessagesAdapter()
+    with_search = adapter.translate_openai_response_to_anthropic(
+        response=_openai_response_with_usage(
+            Usage(
+                prompt_tokens=385,
+                completion_tokens=566,
+                total_tokens=951,
+                prompt_tokens_details=PromptTokensDetailsWrapper(text_tokens=385, web_search_requests=2),
+            )
+        )
+    )
+    without_search = adapter.translate_openai_response_to_anthropic(
+        response=_openai_response_with_usage(Usage(prompt_tokens=385, completion_tokens=566, total_tokens=951))
+    )
+
+    cost_with_search = litellm.completion_cost(
+        completion_response=with_search,
+        model="gemini/gemini-3-flash-preview",
+        call_type="anthropic_messages",
+    )
+    cost_without_search = litellm.completion_cost(
+        completion_response=without_search,
+        model="gemini/gemini-3-flash-preview",
+        call_type="anthropic_messages",
+    )
+
+    per_query_cost = litellm.model_cost["gemini/gemini-3-flash-preview"]["search_context_cost_per_query"][
+        "search_context_size_medium"
+    ]
+    assert per_query_cost > 0
+    assert cost_with_search - cost_without_search == pytest.approx(2 * per_query_cost)

tests/test_litellm/llms/anthropic/test_cost_calculation_dict_safety.py

@@ -8,10 +8,9 @@ See https://github.com/BerriAI/litellm/issues/26153.
 
 import pytest
 
-
 from litellm.llms.anthropic.cost_calculation import (
-    _get_web_search_requests,
     get_cost_for_anthropic_web_search,
+    get_web_search_requests,
 )
 from litellm.types.utils import ModelInfo, ServerToolUse
 
@@ -33,19 +32,19 @@ def _make_model_info(cost_per_query: float = 0.01) -> ModelInfo:
 
 
 def test_get_web_search_requests_handles_none():
-    assert _get_web_search_requests(None) is None
+    assert get_web_search_requests(None) is None
 
 
 def test_get_web_search_requests_handles_dict():
-    assert _get_web_search_requests({"web_search_requests": 4}) == 4
+    assert get_web_search_requests({"web_search_requests": 4}) == 4
 
 
 def test_get_web_search_requests_handles_dict_missing_key():
-    assert _get_web_search_requests({}) is None
+    assert get_web_search_requests({}) is None
 
 
 def test_get_web_search_requests_handles_pydantic():
-    assert _get_web_search_requests(ServerToolUse(web_search_requests=2)) == 2
+    assert get_web_search_requests(ServerToolUse(web_search_requests=2)) == 2
 
 
 def test_get_cost_for_anthropic_web_search_with_dict_server_tool_use():

tests/test_litellm/llms/gemini/test_cost_calculator.py

@@ -84,6 +84,65 @@ def test_no_usage_details():
     assert cost == 0.0
 
 
+def _make_server_tool_use_usage(web_search_requests: int) -> Usage:
+    from litellm.types.utils import ServerToolUse
+
+    return Usage(
+        prompt_tokens=100,
+        completion_tokens=50,
+        total_tokens=150,
+        server_tool_use=ServerToolUse(web_search_requests=web_search_requests),
+    )
+
+
+def test_server_tool_use_fallback_per_query_billing():
+    """Usage reconstructed from an Anthropic-format response carries the count in
+    server_tool_use, not prompt_tokens_details; per_query billing prices each request."""
+    model_info = {
+        "key": "gemini/gemini-3-flash-preview",
+        "web_search_billing_unit": "per_query",
+        "search_context_cost_per_query": {
+            "search_context_size_medium": 0.014,
+        },
+    }
+    cost = cost_per_web_search_request(usage=_make_server_tool_use_usage(3), model_info=model_info)
+    assert cost == pytest.approx(0.014 * 3)
+
+
+def test_server_tool_use_fallback_per_prompt_clamps_to_one():
+    """per_prompt billing clamps the server_tool_use count to one grounded prompt."""
+    model_info = {
+        "key": "gemini/gemini-2.5-flash",
+        "search_context_cost_per_query": {
+            "search_context_size_medium": 0.035,
+        },
+    }
+    cost = cost_per_web_search_request(usage=_make_server_tool_use_usage(4), model_info=model_info)
+    assert cost == pytest.approx(0.035 * 1)
+
+
+def test_prompt_tokens_details_take_precedence_over_server_tool_use():
+    """The native Gemini field wins when both counts are present."""
+    from litellm.types.utils import ServerToolUse
+
+    model_info = {
+        "key": "gemini/gemini-3-flash-preview",
+        "web_search_billing_unit": "per_query",
+        "search_context_cost_per_query": {
+            "search_context_size_medium": 0.014,
+        },
+    }
+    usage = Usage(
+        prompt_tokens=100,
+        completion_tokens=50,
+        total_tokens=150,
+        prompt_tokens_details=PromptTokensDetailsWrapper(web_search_requests=2),
+        server_tool_use=ServerToolUse(web_search_requests=5),
+    )
+    cost = cost_per_web_search_request(usage=usage, model_info=model_info)
+    assert cost == pytest.approx(0.014 * 2)
+
+
 def _make_maps_usage(google_maps_grounding_requests: int) -> Usage:
     return Usage(
         prompt_tokens=100,

tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py

@@ -1082,11 +1082,38 @@ class TestMCPOAuth2AuthFlow:
             # LiteLLM key should be used for auth
             mock_auth.assert_called_once()
             call_args = mock_auth.call_args
-            assert call_args.kwargs["api_key"] == "sk-litellm-valid-key"
+            assert call_args.kwargs["api_key"] == "Bearer sk-litellm-valid-key"
 
             # OAuth2 headers should still contain the Authorization token
             assert oauth2_headers.get("Authorization") == "Bearer atlassian-oauth2-token"
 
+    @pytest.mark.parametrize(
+        "header_value",
+        [b"sk-litellm-valid-key", b"Bearer sk-litellm-valid-key", b"bearer sk-litellm-valid-key"],
+    )
+    async def test_x_litellm_api_key_survives_bearer_only_strip(self, header_value):
+        from litellm.proxy.auth.user_api_key_auth import _get_bearer_token
+
+        scope = {
+            "type": "http",
+            "method": "POST",
+            "path": "/mcp/some_server",
+            "headers": [(b"x-litellm-api-key", header_value)],
+        }
+
+        async def mock_user_api_key_auth(api_key, request):
+            return UserAPIKeyAuth(api_key=api_key, user_id="test-user")
+
+        with patch(  # test-quality-ok: capturing the exact api_key handed to key validation is the regression under test
+            "litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp.user_api_key_auth",
+            side_effect=mock_user_api_key_auth,
+        ) as mock_auth:
+            auth_result, *_rest = await MCPRequestHandler.process_mcp_request(scope)
+
+        mock_auth.assert_called_once()
+        assert _get_bearer_token(api_key=mock_auth.call_args.kwargs["api_key"]) == "sk-litellm-valid-key"
+        assert auth_result.user_id == "test-user"
+
     async def test_litellm_key_in_authorization_backward_compat(self):
         """
         Backward compatibility: when only Authorization header is present
@@ -3007,7 +3034,7 @@ class TestMCPCustomHeaderName:
                 # Verify the mock was called
                 mock_auth.assert_called_once()
                 call_args = mock_auth.call_args
-                assert call_args.kwargs["api_key"] == "test-api-key"
+                assert call_args.kwargs["api_key"] == "Bearer test-api-key"
 
     def test_get_mcp_server_auth_headers_from_headers(self):
         """Test _get_mcp_server_auth_headers_from_headers method"""
@@ -6254,7 +6281,7 @@ class TestMCPDcrBridgeDelegateAdmission:
             ) = await MCPRequestHandler.process_mcp_request(scope)
 
         mock_auth.assert_called_once()
-        assert mock_auth.call_args.kwargs["api_key"] == "sk-explicit-litellm-key"
+        assert mock_auth.call_args.kwargs["api_key"] == "Bearer sk-explicit-litellm-key"
         # The explicit-key arm admitted; the envelope arm never ran, so no inner token is injected.
         assert auth_result.user_id == "litellm-key-user"
         assert mcp_server_auth_headers == {}

tests/test_litellm/proxy/management_endpoints/scim/test_scim_v2_endpoints.py

@@ -4415,6 +4415,69 @@ async def test_create_group_stamps_scim_provenance(mocker, scim_upsert_user_enab
     assert new_team_mock.call_args.kwargs["data"].metadata == {SCIM_MANAGED_TEAM_METADATA_KEY: True}
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("as_pydantic", [False, True])
+async def test_create_group_applies_default_team_params(
+    mocker: MockerFixture,
+    monkeypatch: pytest.MonkeyPatch,
+    scim_upsert_user_enabled: None,
+    as_pydantic: bool,
+):
+    """SCIM-created teams must honor litellm_settings.default_team_params, including
+    models, the same way SSO auto-created teams do."""
+    import litellm
+    from litellm.types.proxy.management_endpoints.ui_sso import DefaultTeamSSOParams
+
+    default_params = {
+        "models": ["no-default-models"],
+        "max_budget": 25.0,
+        "budget_duration": "30d",
+        "tpm_limit": 100,
+        "rpm_limit": 10,
+    }
+    monkeypatch.setattr(
+        litellm,
+        "default_team_params",
+        DefaultTeamSSOParams(**default_params) if as_pydantic else default_params,
+    )
+
+    scim_group = SCIMGroup(
+        schemas=["urn:ietf:params:scim:schemas:core:2.0:Group"],
+        id="defaults-group",
+        displayName="Defaults.Apps",
+        members=[],
+    )
+
+    mocker.patch(  # test-quality-ok: endpoint collaborators are module-level, not injectable into create_group
+        "litellm.proxy.management_endpoints.scim.scim_v2._get_prisma_client_or_raise_exception",
+        AsyncMock(return_value=_member_resolution_prisma(mocker, users=set(), teams=set())),
+    )
+    new_team_mock = mocker.patch(  # test-quality-ok: endpoint collaborators are module-level, not injectable into create_group
+        "litellm.proxy.management_endpoints.scim.scim_v2.new_team",
+        AsyncMock(return_value=mocker.MagicMock()),
+    )
+    mocker.patch(  # test-quality-ok: endpoint collaborators are module-level, not injectable into create_group
+        "litellm.proxy.management_endpoints.scim.scim_v2.ScimTransformations.transform_litellm_team_to_scim_group",
+        AsyncMock(return_value=scim_group),
+    )
+    mocker.patch(  # test-quality-ok: endpoint collaborators are module-level, not injectable into create_group
+        "litellm.proxy.management_endpoints.scim.scim_v2._recompute_scim_member_roles",
+        AsyncMock(),
+    )
+
+    await create_group(group=scim_group)
+
+    team_request = new_team_mock.call_args.kwargs["data"]
+    assert team_request.models == ["no-default-models"]
+    assert team_request.max_budget == 25.0
+    assert team_request.budget_duration == "30d"
+    assert team_request.tpm_limit == 100
+    assert team_request.rpm_limit == 10
+    assert team_request.team_id == "defaults-group"
+    assert team_request.team_alias == "Defaults.Apps"
+    assert team_request.metadata == {SCIM_MANAGED_TEAM_METADATA_KEY: True}
+
+
 @pytest.mark.asyncio
 async def test_update_group_stamps_scim_provenance(mocker, scim_upsert_user_enabled):
     """A PUT full sync adopts a team the identity provider now owns, and the stamp has

tests/test_litellm/proxy/management_endpoints/test_budget_endpoints.py

@@ -1,7 +1,9 @@
 # tests/test_budget_endpoints.py
 
+import json
 import types
 from datetime import datetime, timedelta, timezone
+from typing import Final
 import pytest
 from unittest.mock import AsyncMock, MagicMock
 from fastapi.testclient import TestClient
@@ -388,3 +390,34 @@ async def test_update_budget_duration_none_does_not_recompute(client_and_mocks):
 
     assert "budget_duration" in captured and captured["budget_duration"] is None
     assert "budget_reset_at" not in captured
+
+
+@pytest.mark.asyncio
+async def test_update_budget_serializes_model_max_budget_for_prisma(
+    client_and_mocks, monkeypatch
+):
+    monkeypatch.setattr(ps, "premium_user", True)
+
+    client, _, mock_table = client_and_mocks
+    captured: Final = _capture_update_data(mock_table)
+
+    resp: Final = client.post(
+        "/budget/update",
+        json={
+            "budget_id": "budget_per_model",
+            "model_max_budget": {
+                "gpt4o": {"budget_limit": 5.0, "time_period": "1d"},
+                "glm-5.2": {"budget_limit": 7.5, "time_period": "30d"},
+            },
+        },
+    )
+    assert resp.status_code == 200, resp.text
+
+    stored: Final = captured["model_max_budget"]
+    assert isinstance(stored, str), (
+        f"model_max_budget must reach prisma as a JSON string, got {type(stored).__name__}"
+    )
+    assert json.loads(stored) == {
+        "gpt4o": {"max_budget": 5.0, "budget_duration": "1d"},
+        "glm-5.2": {"max_budget": 7.5, "budget_duration": "30d"},
+    }

tests/test_litellm/proxy/pass_through_endpoints/test_streaming_handler.py

@@ -0,0 +1,130 @@
+import json
+from collections.abc import Iterator
+from datetime import datetime
+from unittest.mock import MagicMock
+
+import pytest
+
+import litellm
+from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
+from litellm.proxy.pass_through_endpoints.llm_provider_handlers.vertex_passthrough_logging_handler import (
+    VertexPassthroughLoggingHandler,
+)
+from litellm.proxy.pass_through_endpoints.streaming_handler import (
+    PassThroughStreamingHandler,
+)
+from litellm.proxy.pass_through_endpoints.success_handler import (
+    PassThroughEndpointLogging,
+)
+from litellm.types.passthrough_endpoints.pass_through_endpoints import EndpointType
+
+MODEL = "gemini-stream-pricing-probe"
+PROMPT_TOKENS = 1000
+COMPLETION_TOKENS = 1000
+GEMINI_INPUT_RATE = 1e-07
+GEMINI_OUTPUT_RATE = 4e-07
+VERTEX_INPUT_RATE = 1.5e-07
+VERTEX_OUTPUT_RATE = 6e-07
+GEMINI_COST = PROMPT_TOKENS * GEMINI_INPUT_RATE + COMPLETION_TOKENS * GEMINI_OUTPUT_RATE
+VERTEX_COST = PROMPT_TOKENS * VERTEX_INPUT_RATE + COMPLETION_TOKENS * VERTEX_OUTPUT_RATE
+
+
+@pytest.fixture(autouse=True)
+def divergent_rate_cards(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    monkeypatch.setitem(
+        litellm.model_cost,
+        f"gemini/{MODEL}",
+        {
+            "input_cost_per_token": GEMINI_INPUT_RATE,
+            "output_cost_per_token": GEMINI_OUTPUT_RATE,
+            "litellm_provider": "gemini",
+            "mode": "chat",
+        },
+    )
+    monkeypatch.setitem(
+        litellm.model_cost,
+        f"vertex_ai/{MODEL}",
+        {
+            "input_cost_per_token": VERTEX_INPUT_RATE,
+            "output_cost_per_token": VERTEX_OUTPUT_RATE,
+            "litellm_provider": "vertex_ai",
+            "mode": "chat",
+        },
+    )
+    litellm.get_model_info.cache_clear()
+    yield
+    litellm.get_model_info.cache_clear()
+
+
+def _chunks() -> list[str]:
+    payload = {
+        "candidates": [
+            {
+                "content": {"parts": [{"text": "hi"}], "role": "model"},
+                "finishReason": "STOP",
+                "index": 0,
+            }
+        ],
+        "usageMetadata": {
+            "promptTokenCount": PROMPT_TOKENS,
+            "candidatesTokenCount": COMPLETION_TOKENS,
+            "totalTokenCount": PROMPT_TOKENS + COMPLETION_TOKENS,
+        },
+        "modelVersion": MODEL,
+    }
+    return [f"data: {json.dumps(payload)}"]
+
+
+def _logging_obj() -> LiteLLMLoggingObj:
+    logging_obj = MagicMock(spec=LiteLLMLoggingObj)
+    logging_obj.model_call_details = {}
+    logging_obj.optional_params = {}
+    logging_obj.litellm_call_id = "test-call-id"
+    return logging_obj
+
+
+@pytest.mark.parametrize(
+    "endpoint_type, expected_provider, expected_cost",
+    [
+        (EndpointType.GEMINI, "gemini", GEMINI_COST),
+        (EndpointType.VERTEX_AI, "vertex_ai", VERTEX_COST),
+    ],
+)
+def test_streaming_generate_content_bills_against_the_requested_provider(
+    endpoint_type, expected_provider, expected_cost
+):
+    logging_obj = _logging_obj()
+
+    _, kwargs = PassThroughStreamingHandler._build_passthrough_logging_result(
+        litellm_logging_obj=logging_obj,
+        passthrough_success_handler_obj=PassThroughEndpointLogging(),
+        url_route="/v1/generateContent",
+        request_body={},
+        endpoint_type=endpoint_type,
+        start_time=datetime.now(),
+        raw_bytes=[chunk.encode("utf-8") for chunk in _chunks()],
+        end_time=datetime.now(),
+        model=MODEL,
+    )
+
+    assert kwargs["response_cost"] == pytest.approx(expected_cost)
+    assert logging_obj.model_call_details["custom_llm_provider"] == expected_provider
+
+
+def test_vertex_generate_content_payload_prices_gemini_urls_at_gemini_rates():
+    logging_obj = _logging_obj()
+
+    result = VertexPassthroughLoggingHandler._handle_logging_vertex_collected_chunks(
+        litellm_logging_obj=logging_obj,
+        passthrough_success_handler_obj=PassThroughEndpointLogging(),
+        url_route=f"https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:streamGenerateContent",
+        request_body={},
+        endpoint_type=EndpointType.VERTEX_AI,
+        start_time=datetime.now(),
+        all_chunks=_chunks(),
+        model=MODEL,
+        end_time=datetime.now(),
+    )
+
+    assert result["kwargs"]["response_cost"] == pytest.approx(GEMINI_COST)
+    assert logging_obj.model_call_details["custom_llm_provider"] == "gemini"

tests/test_litellm/proxy/prompts/test_prompt_endpoints_crud.py

@@ -79,7 +79,7 @@ async def test_delete_prompt_success():
 
             # 2. Memory deletion should use base ID
             mock_registry.delete_prompts_by_base_id.assert_called_once_with(
-                expected_base_id
+                expected_base_id, environment=None
             )
 
             assert response == {
@@ -150,7 +150,7 @@ async def test_delete_prompt_by_base_id_success():
 
             # 2. Memory deletion should use base ID
             mock_registry.delete_prompts_by_base_id.assert_called_once_with(
-                expected_base_id
+                expected_base_id, environment=None
             )
 
             assert response == {
@@ -158,6 +158,37 @@ async def test_delete_prompt_by_base_id_success():
             }
 
 
+@pytest.mark.asyncio
+async def test_delete_prompt_environment_scope_reaches_db_and_registry():
+    from litellm.proxy.prompts.prompt_endpoints import delete_prompt
+
+    mock_user_auth = UserAPIKeyAuth(api_key="sk-1234", user_role=LitellmUserRoles.PROXY_ADMIN)
+    mock_prisma_client = MagicMock()
+    mock_prisma_client.db.litellm_prompttable.delete_many = AsyncMock(return_value=None)
+
+    with patch(  # test-quality-ok: stubs the collaborator so the test pins what the endpoint deletes
+        "litellm.proxy.prompts.prompt_registry.IN_MEMORY_PROMPT_REGISTRY"
+    ) as mock_registry:
+        mock_registry.get_prompt_by_id.return_value = PromptSpec(
+            prompt_id="test_prompt.v2",
+            litellm_params=PromptLiteLLMParams(prompt_id="test_prompt", prompt_integration="dotprompt"),
+            prompt_info=PromptInfo(prompt_type="db"),
+        )
+
+        with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client):  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+            response = await delete_prompt(
+                prompt_id="test_prompt.v2",
+                environment="production",
+                user_api_key_dict=mock_user_auth,
+            )
+
+    mock_prisma_client.db.litellm_prompttable.delete_many.assert_called_once_with(
+        where={"prompt_id": "test_prompt", "environment": "production"}
+    )
+    mock_registry.delete_prompts_by_base_id.assert_called_once_with("test_prompt", environment="production")
+    assert response == {"message": "Prompt test_prompt deleted successfully from production"}
+
+
 @pytest.mark.asyncio
 async def test_get_prompt_info_by_base_id():
     """

tests/test_litellm/proxy/prompts/test_prompt_registry.py

@@ -88,3 +88,55 @@ def test_reload_prompt_keeps_the_old_template_when_the_replacement_fails(isolate
     assert registry.get_prompt_callback_by_id("greeting.v1") is old_callback
     assert _served_content(registry) == "begin every reply with AHOY"
     assert isolated_callbacks == [old_callback]
+
+
+def _versioned_prompt_spec(version: int, environment: str) -> PromptSpec:
+    return PromptSpec(
+        prompt_id=f"greeting.v{version}",
+        litellm_params=PromptLiteLLMParams(
+            prompt_id="greeting",
+            prompt_integration="dotprompt",
+            prompt_data={"content": f"begin every reply with AHOY v{version}", "metadata": {}},
+        ),
+        prompt_info=PromptInfo(prompt_type="db", environment=environment),
+        version=version,
+        environment=environment,
+    )
+
+
+def test_delete_prompts_by_base_id_removes_the_callbacks_from_litellm_callbacks(isolated_callbacks: list) -> None:
+    registry = InMemoryPromptRegistry()
+    registry.initialize_prompt(prompt=_versioned_prompt_spec(1, "development"))
+    registry.initialize_prompt(prompt=_versioned_prompt_spec(2, "development"))
+    assert len(isolated_callbacks) == 1
+
+    deleted = registry.delete_prompts_by_base_id("greeting")
+
+    assert sorted(deleted) == ["greeting.v1", "greeting.v2"]
+    assert registry.get_prompt_by_id("greeting.v1") is None
+    assert registry.get_prompt_callback_by_id("greeting.v2") is None
+    assert isolated_callbacks == []
+
+
+def test_delete_prompts_by_base_id_environment_scope_keeps_other_environments(isolated_callbacks: list) -> None:
+    registry = InMemoryPromptRegistry()
+    registry.initialize_prompt(prompt=_versioned_prompt_spec(1, "development"))
+    registry.initialize_prompt(prompt=_versioned_prompt_spec(2, "production"))
+    production_callback = registry.get_prompt_callback_by_id("greeting.v2")
+
+    deleted = registry.delete_prompts_by_base_id("greeting", environment="development")
+
+    assert deleted == ["greeting.v1"]
+    assert registry.get_prompt_by_id("greeting.v1") is None
+    assert registry.get_prompt_by_id("greeting.v2") is not None
+    assert registry.get_prompt_callback_by_id("greeting.v2") is production_callback
+
+
+def test_remove_prompt_is_a_no_op_for_an_unknown_id(isolated_callbacks: list) -> None:
+    registry = InMemoryPromptRegistry()
+    registry.initialize_prompt(prompt=_versioned_prompt_spec(1, "development"))
+
+    registry.remove_prompt(prompt_id="not_there.v1")
+
+    assert registry.get_prompt_by_id("greeting.v1") is not None
+    assert len(isolated_callbacks) == 1

tests/test_litellm/proxy/spend_tracking/test_spend_management_endpoints.py

@@ -3135,6 +3135,90 @@ async def test_view_spend_logs_summarize_parameter(client, monkeypatch):
         app.dependency_overrides.pop(ps.user_api_key_auth, None)
 
 
+@pytest.mark.asyncio
+async def test_view_spend_logs_bounds_row_count(client, monkeypatch):
+    """Every /spend/logs read path must send take=SPEND_LOGS_PAGINATION_COUNT_CAP to Prisma (LIT-6284)."""
+    captured_find_many_kwargs = []
+
+    class MockDB:
+        def __init__(self):
+            self.litellm_spendlogs = self
+            self.available_rows = 0
+
+        async def find_many(self, *args, **kwargs):
+            captured_find_many_kwargs.append(kwargs)
+            return [{}] * min(kwargs.get("take", 0), self.available_rows)
+
+    class MockPrismaClient:
+        def __init__(self):
+            self.db = MockDB()
+
+        def hash_token(self, token):
+            return f"hashed-{token}"
+
+    mock_prisma_client = MockPrismaClient()
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+    app.dependency_overrides[ps.user_api_key_auth] = lambda: UserAPIKeyAuth(
+        user_role=LitellmUserRoles.PROXY_ADMIN
+    )
+    start_date = (
+        datetime.datetime.now(timezone.utc) - datetime.timedelta(days=2)
+    ).strftime("%Y-%m-%d")
+    end_date = datetime.datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    try:
+        response = client.get(
+            "/spend/logs",
+            headers={"Authorization": "Bearer sk-test"},
+        )
+        assert response.status_code == 200
+        assert (
+            captured_find_many_kwargs[-1].get("take")
+            == spend_management_endpoints.SPEND_LOGS_PAGINATION_COUNT_CAP
+        )
+        assert "x-litellm-spend-logs-truncated" not in response.headers
+
+        response = client.get(
+            "/spend/logs",
+            params={"user_id": "test-user"},
+            headers={"Authorization": "Bearer sk-test"},
+        )
+        assert response.status_code == 200
+        assert captured_find_many_kwargs[-1].get("where") == {"user": "test-user"}
+        assert (
+            captured_find_many_kwargs[-1].get("take")
+            == spend_management_endpoints.SPEND_LOGS_PAGINATION_COUNT_CAP
+        )
+
+        response = client.get(
+            "/spend/logs",
+            params={
+                "start_date": start_date,
+                "end_date": end_date,
+                "summarize": "false",
+            },
+            headers={"Authorization": "Bearer sk-test"},
+        )
+        assert response.status_code == 200
+        assert "startTime" in captured_find_many_kwargs[-1].get("where", {})
+        assert (
+            captured_find_many_kwargs[-1].get("take")
+            == spend_management_endpoints.SPEND_LOGS_PAGINATION_COUNT_CAP
+        )
+
+        mock_prisma_client.db.available_rows = (
+            spend_management_endpoints.SPEND_LOGS_PAGINATION_COUNT_CAP
+        )
+        response = client.get(
+            "/spend/logs",
+            headers={"Authorization": "Bearer sk-test"},
+        )
+        assert response.status_code == 200
+        assert len(response.json()) == spend_management_endpoints.SPEND_LOGS_PAGINATION_COUNT_CAP
+        assert response.headers["x-litellm-spend-logs-truncated"] == "true"
+    finally:
+        app.dependency_overrides.pop(ps.user_api_key_auth, None)
+
+
 @pytest.mark.asyncio
 async def test_view_spend_tags(client, monkeypatch):
     """Test the /spend/tags endpoint"""

tests/test_litellm/proxy/spend_tracking/test_spend_tracking_utils.py

@@ -3274,6 +3274,82 @@ def test_user_traffic_carries_no_internal_call_origin():
     assert metadata["internal_call_origin"] is None
 
 
+def _spend_log_for_call_type(
+    call_type: str, internal_call_origin: str | None = None, background: bool | None = None
+) -> dict:
+    from litellm.types.llms.openai import ResponsesAPIResponse
+
+    return cast(
+        dict,
+        get_logging_payload(
+            kwargs={
+                "model": "gpt-4o",
+                "call_type": call_type,
+                "response_cost": 0.0,
+                "litellm_params": {
+                    "metadata": {
+                        "user_api_key": "test-key",
+                        "internal_call_origin": internal_call_origin,
+                    }
+                },
+            },
+            response_obj=ResponsesAPIResponse(
+                id="resp_lit5602",
+                created_at=1234567890,
+                model="gpt-4o",
+                output=[],
+                usage={"input_tokens": 4000, "output_tokens": 2000, "total_tokens": 6000},
+                background=background,
+            ),
+            start_time=datetime.datetime.now(timezone.utc),
+            end_time=datetime.datetime.now(timezone.utc),
+        ),
+    )
+
+
+def test_spend_log_for_response_retrieval_does_not_replay_the_created_responses_tokens():
+    """A retrieved response carries the usage of the call that created it, so counting it again
+    bills the same tokens twice. Regression test for LIT-5602."""
+    payload = _spend_log_for_call_type("aget_responses")
+
+    assert payload["prompt_tokens"] == 0
+    assert payload["completion_tokens"] == 0
+    assert payload["total_tokens"] == 0
+    assert payload["spend"] == 0.0
+
+
+def test_spend_log_for_background_response_cost_poll_counts_tokens():
+    """The poller's read is where a background job's usage first shows up, so dropping it there
+    leaves the job unbilled forever."""
+    payload = _spend_log_for_call_type("aget_responses", internal_call_origin="background_response_cost_poll")
+
+    assert payload["total_tokens"] == 6000
+
+
+def test_spend_log_for_background_response_retrieval_counts_tokens():
+    """A background create answers queued carrying no usage, so its retrieval is the first and only
+    place the job's tokens are ever visible. Zeroing that read bills the whole job nothing on any
+    proxy that is not running the enterprise cost poller."""
+    payload = _spend_log_for_call_type("aget_responses", background=True)
+
+    assert payload["total_tokens"] == 6000
+
+
+def test_spend_log_for_foreground_response_retrieval_still_counts_nothing():
+    """Guards the test above against a blanket exemption: an explicit background=false read was
+    already billed by its create and must stay at zero."""
+    payload = _spend_log_for_call_type("aget_responses", background=False)
+
+    assert payload["total_tokens"] == 0
+
+
+def test_spend_log_for_response_creation_still_counts_tokens():
+    """Guards the test above: the same response object must still be counted on the create path."""
+    payload = _spend_log_for_call_type("aresponses")
+
+    assert payload["total_tokens"] == 6000
+
+
 REDACTED_RESPONSE_PLACEHOLDER: Final = {"text": "redacted-by-litellm"}
 CONSTANT_ID_FROM_HASHED_PLACEHOLDER: Final = "00fcbef15a3b0097e14b0ca016ed30a0"
 

tests/test_litellm/proxy/test_common_request_processing.py

@@ -13,11 +13,7 @@ from fastapi.responses import JSONResponse, StreamingResponse
 
 import litellm
 from litellm._uuid import uuid
-from litellm.constants import (
-    AUTO_ROUTED_REQUEST_METADATA_KEY,
-    RETURN_RAW_MODEL_NAME_METADATA_KEY,
-    ROUTER_MODEL_NAME_RESPONSE_FIELD,
-)
+from litellm.constants import RETURN_RAW_MODEL_NAME_METADATA_KEY
 from litellm.integrations.custom_logger import CustomLogger
 from litellm.integrations.opentelemetry import UserAPIKeyAuth
 from litellm.proxy.common_request_processing import (
@@ -30,6 +26,7 @@ from litellm.proxy.common_request_processing import (
     _ClientDisconnectedBeforeFirstChunk,
     _extract_error_from_sse_chunk,
     _get_cost_breakdown_from_logging_obj,
+    CostBreakdownHeaderValues,
     _has_attribute_error_in_chain,
     _is_azure_model_router_request,
     open_sse_before_first_byte,
@@ -5022,6 +5019,169 @@ class TestResponseCostHeaderForTypedDictResponses:
         assert fastapi_response.headers["x-litellm-response-cost"] == "0.00123"
 
 
+class TestCostHeadersForCallsPricedAtZero:
+    """
+    Regression for LIT-5602. Pricing responses reads and vector-store management routes at
+    zero dropped the entire x-litellm-response-cost family off those replies: the header
+    build reads a falsy zero as "this response never recorded a cost" and filters it out,
+    and a call that returns before pricing stores no cost breakdown for the component
+    headers to read. A client parsing the cost off a read got a KeyError where it had
+    previously been handed a number. Those calls now advertise the whole family at zero.
+    """
+
+    @staticmethod
+    def _responses_read(*, background=False):
+        from litellm.types.llms.openai import ResponsesAPIResponse
+
+        return ResponsesAPIResponse(
+            id="resp_lit5602",
+            created_at=0,
+            model="gpt-4.1-mini",
+            object="response",
+            output=[],
+            status="completed",
+            background=background,
+            usage={"input_tokens": 10, "output_tokens": 5, "total_tokens": 15},
+        )
+
+    @staticmethod
+    def _logging_obj(*, call_type, recovered_cost=0.0):
+        logging_obj = MagicMock()
+        logging_obj.litellm_call_id = "call-lit5602"
+        logging_obj.call_type = call_type
+        logging_obj.litellm_params = {}
+        logging_obj.cost_breakdown = None
+        logging_obj.model_call_details = {"response_cost": recovered_cost}
+        logging_obj._response_cost_calculator = MagicMock(return_value=recovered_cost)
+        logging_obj._enqueue_deferred_logging = None
+        logging_obj._on_deferred_stream_complete = None
+        return logging_obj
+
+    async def _drive(self, *, monkeypatch, response, logging_obj, route_type):
+        import litellm.proxy.common_request_processing as crp
+        from litellm.proxy._types import UserAPIKeyAuth as RealUserAPIKeyAuth
+
+        async def fake_route_request(**kwargs):
+            async def _llm_call():
+                return response
+
+            return _llm_call()
+
+        monkeypatch.setattr(crp, "route_request", fake_route_request)
+
+        async def fake_post_call_success_hook(data, user_api_key_dict, response):
+            return response
+
+        proxy_logging_obj = MagicMock(spec=ProxyLogging)
+        proxy_logging_obj.during_call_hook = AsyncMock(return_value=None)
+        proxy_logging_obj.update_request_status = AsyncMock(return_value=None)
+        proxy_logging_obj.post_call_response_headers_hook = AsyncMock(return_value={})
+        proxy_logging_obj.post_call_success_hook = fake_post_call_success_hook
+
+        fastapi_response = Response()
+        processing_obj = ProxyBaseLLMRequestProcessing(data={"litellm_logging_obj": logging_obj})
+
+        with patch.object(
+            ProxyBaseLLMRequestProcessing, "_has_post_call_guardrails", return_value=False
+        ):
+            await processing_obj.base_process_llm_request(
+                request=MagicMock(spec=Request, headers={}),
+                fastapi_response=fastapi_response,
+                user_api_key_dict=RealUserAPIKeyAuth(api_key="sk-test"),
+                route_type=route_type,
+                proxy_logging_obj=proxy_logging_obj,
+                general_settings={},
+                proxy_config=MagicMock(spec=ProxyConfig),
+                select_data_generator=None,
+                llm_router=None,
+                skip_pre_call_logic=True,
+            )
+        return fastapi_response
+
+    @pytest.mark.asyncio
+    async def test_responses_read_emits_the_cost_header_family_at_zero(self, monkeypatch):
+        fastapi_response = await self._drive(
+            monkeypatch=monkeypatch,
+            response=self._responses_read(),
+            logging_obj=self._logging_obj(call_type="aget_responses"),
+            route_type="aget_responses",
+        )
+
+        assert fastapi_response.headers["x-litellm-response-cost"] == "0.0"
+        for component in (
+            "original",
+            "discount-amount",
+            "margin-amount",
+            "margin-percent",
+            "input",
+            "output",
+            "tool-usage",
+        ):
+            assert fastapi_response.headers[f"x-litellm-response-cost-{component}"] == "0.0"
+
+    @pytest.mark.asyncio
+    async def test_reading_a_background_response_keeps_its_real_cost(self, monkeypatch):
+        fastapi_response = await self._drive(
+            monkeypatch=monkeypatch,
+            response=self._responses_read(background=True),
+            logging_obj=self._logging_obj(call_type="aget_responses", recovered_cost=0.00042),
+            route_type="aget_responses",
+        )
+
+        assert float(fastapi_response.headers["x-litellm-response-cost"]) == pytest.approx(0.00042)
+
+    @pytest.mark.asyncio
+    async def test_an_inference_call_without_a_recorded_cost_still_omits_the_header(self, monkeypatch):
+        """A chat completion has no zero-priced route, so a falsy cost there means the cost was
+        never recorded and the header stays absent rather than advertising a made-up zero."""
+        fastapi_response = await self._drive(
+            monkeypatch=monkeypatch,
+            response=SimpleNamespace(_hidden_params={}),
+            logging_obj=self._logging_obj(call_type="acompletion"),
+            route_type="acompletion",
+        )
+
+        assert "x-litellm-response-cost" not in fastapi_response.headers
+
+    def test_cost_breakdown_reports_zero_components_for_a_call_priced_at_zero(self):
+        breakdown = _get_cost_breakdown_from_logging_obj(
+            litellm_logging_obj=self._logging_obj(call_type="aget_responses")
+        )
+
+        assert breakdown.original_cost == 0.0
+        assert breakdown.input_cost == 0.0
+        assert breakdown.output_cost == 0.0
+        assert breakdown.tool_usage_cost == 0.0
+
+    def test_cost_breakdown_stays_empty_for_an_inference_call(self):
+        breakdown = _get_cost_breakdown_from_logging_obj(
+            litellm_logging_obj=self._logging_obj(call_type="acompletion")
+        )
+
+        assert breakdown == CostBreakdownHeaderValues()
+
+    def test_cost_breakdown_never_zeroes_the_split_under_a_real_total(self):
+        """Reading a background response prices normally, so a breakdown that has not landed by the
+        time headers are built is reported as absent rather than as a zero split contradicting the
+        real total alongside it."""
+        breakdown = _get_cost_breakdown_from_logging_obj(
+            litellm_logging_obj=self._logging_obj(call_type="aget_responses"),
+            response_cost=1.96e-05,
+        )
+
+        assert breakdown == CostBreakdownHeaderValues()
+
+    def test_cost_breakdown_reports_zero_components_under_a_zero_total(self):
+        breakdown = _get_cost_breakdown_from_logging_obj(
+            litellm_logging_obj=self._logging_obj(call_type="aget_responses"),
+            response_cost=0.0,
+        )
+
+        assert breakdown.original_cost == 0.0
+        assert breakdown.input_cost == 0.0
+        assert breakdown.output_cost == 0.0
+
+
 class TestPreCallWithFallbacksOnLocalRateLimit:
 
     @pytest.mark.asyncio
@@ -7223,128 +7383,6 @@ async def test_a_broken_hook_does_not_replace_the_real_error_with_its_own_bug():
     assert "audit backend" not in collected[-2].decode()
 
 
-class TestRouterModelNameOnNonStreamingResponse:
-    """
-    The proxy restamps the response body `model` back to the client-requested
-    alias, so an auto-routed request (auto_router / complexity_router /
-    adaptive_router / quality_router) had no body-level surface naming the model
-    group that actually served it. `router_model_name` is now set on the response
-    whenever the router marked the request as auto-routed.
-    """
-
-    @staticmethod
-    def _logging_obj(*, metadata_bucket, bucket_name="metadata"):
-        logging_obj = MagicMock()
-        logging_obj.litellm_call_id = "call-auto-routed"
-        logging_obj.cost_breakdown = None
-        logging_obj.model_call_details = {}
-        logging_obj.litellm_params = {bucket_name: metadata_bucket}
-        logging_obj._enqueue_deferred_logging = None
-        logging_obj._on_deferred_stream_complete = None
-        return logging_obj
-
-    async def _drive(self, *, monkeypatch, logging_obj):
-        import litellm.proxy.common_request_processing as crp
-        from litellm.proxy._types import UserAPIKeyAuth as RealUserAPIKeyAuth
-        from litellm.types.utils import ModelResponse
-
-        response = ModelResponse(
-            model="deep-model",
-            choices=[{"index": 0, "message": {"role": "assistant", "content": "hi"}, "finish_reason": "stop"}],
-        )
-
-        async def fake_route_request(**kwargs):
-            async def _llm_call():
-                return response
-
-            return _llm_call()
-
-        monkeypatch.setattr(crp, "route_request", fake_route_request)
-
-        async def fake_post_call_success_hook(data, user_api_key_dict, response):
-            return response
-
-        proxy_logging_obj = MagicMock(spec=ProxyLogging)
-        proxy_logging_obj.during_call_hook = AsyncMock(return_value=None)
-        proxy_logging_obj.update_request_status = AsyncMock(return_value=None)
-        proxy_logging_obj.post_call_response_headers_hook = AsyncMock(return_value={})
-        proxy_logging_obj.post_call_success_hook = fake_post_call_success_hook
-
-        processing_obj = ProxyBaseLLMRequestProcessing(
-            data={"model": "smart-route", "litellm_logging_obj": logging_obj}
-        )
-
-        with patch.object(ProxyBaseLLMRequestProcessing, "_has_post_call_guardrails", return_value=False):
-            return await processing_obj.base_process_llm_request(
-                request=MagicMock(spec=Request, headers={}),
-                fastapi_response=Response(),
-                user_api_key_dict=RealUserAPIKeyAuth(api_key="sk-test"),
-                route_type="acompletion",
-                proxy_logging_obj=proxy_logging_obj,
-                general_settings={},
-                proxy_config=MagicMock(spec=ProxyConfig),
-                select_data_generator=None,
-                llm_router=None,
-                skip_pre_call_logic=True,
-            )
-
-    @pytest.mark.asyncio
-    async def test_auto_routed_request_carries_router_model_name(self, monkeypatch):
-        result = await self._drive(
-            monkeypatch=monkeypatch,
-            logging_obj=self._logging_obj(
-                metadata_bucket={
-                    AUTO_ROUTED_REQUEST_METADATA_KEY: True,
-                    "deployment_model_name": "deep-model",
-                }
-            ),
-        )
-
-        assert result.model == "smart-route"
-        assert result.model_dump(exclude_none=True, exclude_unset=True)[ROUTER_MODEL_NAME_RESPONSE_FIELD] == (
-            "deep-model"
-        )
-
-    @pytest.mark.asyncio
-    async def test_marker_and_model_name_in_different_buckets(self, monkeypatch):
-        logging_obj = self._logging_obj(metadata_bucket={AUTO_ROUTED_REQUEST_METADATA_KEY: True})
-        logging_obj.litellm_params["litellm_metadata"] = {"deployment_model_name": "deep-model"}
-
-        result = await self._drive(monkeypatch=monkeypatch, logging_obj=logging_obj)
-
-        assert result.model_dump(exclude_none=True, exclude_unset=True)[ROUTER_MODEL_NAME_RESPONSE_FIELD] == (
-            "deep-model"
-        )
-
-    @pytest.mark.asyncio
-    async def test_plain_model_group_request_has_no_router_model_name(self, monkeypatch):
-        result = await self._drive(
-            monkeypatch=monkeypatch,
-            logging_obj=self._logging_obj(metadata_bucket={"deployment_model_name": "deep-model"}),
-        )
-
-        assert ROUTER_MODEL_NAME_RESPONSE_FIELD not in result.model_dump(exclude_none=True, exclude_unset=True)
-
-    @pytest.mark.asyncio
-    async def test_typeddict_response_gets_router_model_name(self):
-        from litellm.types.utils import AnthropicMessagesResponse
-
-        response: AnthropicMessagesResponse = {"id": "msg_1", "model": "smart-route", "type": "message"}
-        ProxyBaseLLMRequestProcessing.set_router_selected_model_field(
-            response_obj=response,
-            router_model_name=ProxyBaseLLMRequestProcessing.get_router_selected_model_name(
-                self._logging_obj(
-                    metadata_bucket={
-                        AUTO_ROUTED_REQUEST_METADATA_KEY: True,
-                        "deployment_model_name": "deep-model",
-                    }
-                )
-            ),
-        )
-
-        assert response[ROUTER_MODEL_NAME_RESPONSE_FIELD] == "deep-model"
-
-
 @pytest.mark.parametrize(
     "exc,expect_traceback",
     [

tests/test_litellm/proxy/test_proxy_server.py

@@ -11492,6 +11492,150 @@ async def test_init_prompts_in_db_serves_the_newest_row_when_environments_collid
         IN_MEMORY_PROMPT_REGISTRY.delete_prompts_by_base_id("greeting_env")
 
 
+def _prompt_db_row(prompt_id: str, litellm_params: str) -> MagicMock:
+    row = MagicMock()
+    row.model_dump.return_value = {
+        "prompt_id": prompt_id,
+        "version": 1,
+        "environment": "development",
+        "created_by": None,
+        "litellm_params": litellm_params,
+        "prompt_info": json.dumps({"prompt_type": "db"}),
+        "created_at": None,
+        "updated_at": None,
+    }
+    return row
+
+
+def _dotprompt_params(prompt_id: str) -> str:
+    return json.dumps(
+        {
+            "prompt_id": prompt_id,
+            "prompt_integration": "dotprompt",
+            "prompt_data": {"content": "Begin every reply with AHOY", "metadata": {}},
+        }
+    )
+
+
+@pytest.mark.asyncio
+async def test_init_prompts_in_db_unloads_rows_deleted_on_another_worker(monkeypatch):
+    from litellm.proxy.prompts.prompt_registry import IN_MEMORY_PROMPT_REGISTRY
+    from litellm.proxy.proxy_server import ProxyConfig
+
+    monkeypatch.setattr(litellm, "callbacks", [])
+
+    prisma_client = MagicMock()
+    try:
+        prisma_client.db.litellm_prompttable.find_many = AsyncMock(
+            return_value=[_prompt_db_row("greeting_del", _dotprompt_params("greeting_del"))]
+        )
+        await ProxyConfig()._init_prompts_in_db(prisma_client=prisma_client)
+        assert IN_MEMORY_PROMPT_REGISTRY.get_prompt_callback_by_id("greeting_del.v1") is not None
+
+        prisma_client.db.litellm_prompttable.find_many = AsyncMock(return_value=[])
+        await ProxyConfig()._init_prompts_in_db(prisma_client=prisma_client)
+
+        assert IN_MEMORY_PROMPT_REGISTRY.get_prompt_by_id("greeting_del.v1") is None
+        assert IN_MEMORY_PROMPT_REGISTRY.get_prompt_callback_by_id("greeting_del.v1") is None
+        assert litellm.callbacks == []
+    finally:
+        IN_MEMORY_PROMPT_REGISTRY.delete_prompts_by_base_id("greeting_del")
+
+
+@pytest.mark.asyncio
+async def test_init_prompts_in_db_keeps_config_prompts_when_their_id_has_no_db_row(monkeypatch):
+    from litellm.proxy.prompts.prompt_registry import IN_MEMORY_PROMPT_REGISTRY
+    from litellm.proxy.proxy_server import ProxyConfig
+    from litellm.types.prompts.init_prompts import PromptInfo, PromptLiteLLMParams, PromptSpec
+
+    monkeypatch.setattr(litellm, "callbacks", [])
+
+    config_prompt = PromptSpec(
+        prompt_id="greeting_cfg",
+        litellm_params=PromptLiteLLMParams(
+            prompt_id="greeting_cfg",
+            prompt_integration="dotprompt",
+            prompt_data={"content": "Begin every reply with AHOY", "metadata": {}},
+        ),
+        prompt_info=PromptInfo(prompt_type="config"),
+    )
+
+    prisma_client = MagicMock()
+    try:
+        IN_MEMORY_PROMPT_REGISTRY.initialize_prompt(prompt=config_prompt)
+        prisma_client.db.litellm_prompttable.find_many = AsyncMock(return_value=[])
+
+        await ProxyConfig()._init_prompts_in_db(prisma_client=prisma_client)
+
+        assert IN_MEMORY_PROMPT_REGISTRY.get_prompt_callback_by_id("greeting_cfg") is not None
+        assert len(litellm.callbacks) == 1
+    finally:
+        IN_MEMORY_PROMPT_REGISTRY.remove_prompt(prompt_id="greeting_cfg")
+
+
+@pytest.mark.asyncio
+async def test_init_prompts_in_db_keeps_the_in_memory_copy_when_a_row_fails_to_parse(monkeypatch):
+    from litellm.proxy.prompts.prompt_registry import IN_MEMORY_PROMPT_REGISTRY
+    from litellm.proxy.proxy_server import ProxyConfig
+
+    monkeypatch.setattr(litellm, "callbacks", [])
+
+    prisma_client = MagicMock()
+    try:
+        prisma_client.db.litellm_prompttable.find_many = AsyncMock(
+            return_value=[_prompt_db_row("greeting_broken", _dotprompt_params("greeting_broken"))]
+        )
+        await ProxyConfig()._init_prompts_in_db(prisma_client=prisma_client)
+        loaded_callback = IN_MEMORY_PROMPT_REGISTRY.get_prompt_callback_by_id("greeting_broken.v1")
+        assert loaded_callback is not None
+
+        prisma_client.db.litellm_prompttable.find_many = AsyncMock(
+            return_value=[_prompt_db_row("greeting_broken", "this is not json")]
+        )
+        await ProxyConfig()._init_prompts_in_db(prisma_client=prisma_client)
+
+        assert IN_MEMORY_PROMPT_REGISTRY.get_prompt_callback_by_id("greeting_broken.v1") is loaded_callback
+        assert litellm.callbacks == [loaded_callback]
+    finally:
+        IN_MEMORY_PROMPT_REGISTRY.delete_prompts_by_base_id("greeting_broken")
+
+
+@pytest.mark.asyncio
+async def test_init_prompts_in_db_keeps_a_prompt_created_while_the_sync_was_reading(monkeypatch):
+    from litellm.proxy.prompts.prompt_registry import IN_MEMORY_PROMPT_REGISTRY
+    from litellm.proxy.proxy_server import ProxyConfig
+    from litellm.types.prompts.init_prompts import PromptInfo, PromptLiteLLMParams, PromptSpec
+
+    monkeypatch.setattr(litellm, "callbacks", [])
+
+    prisma_client = MagicMock()
+    try:
+
+        async def create_prompt_behind_the_select() -> list:
+            IN_MEMORY_PROMPT_REGISTRY.initialize_prompt(
+                prompt=PromptSpec(
+                    prompt_id="greeting_race.v1",
+                    litellm_params=PromptLiteLLMParams(
+                        prompt_id="greeting_race",
+                        prompt_integration="dotprompt",
+                        prompt_data={"content": "Begin every reply with AHOY", "metadata": {}},
+                    ),
+                    prompt_info=PromptInfo(prompt_type="db"),
+                )
+            )
+            return []
+
+        prisma_client.db.litellm_prompttable.find_many = AsyncMock(side_effect=create_prompt_behind_the_select)
+        await ProxyConfig()._init_prompts_in_db(prisma_client=prisma_client)
+
+        surviving_callback = IN_MEMORY_PROMPT_REGISTRY.get_prompt_callback_by_id("greeting_race.v1")
+        assert IN_MEMORY_PROMPT_REGISTRY.get_prompt_by_id("greeting_race.v1") is not None
+        assert surviving_callback is not None
+        assert litellm.callbacks == [surviving_callback]
+    finally:
+        IN_MEMORY_PROMPT_REGISTRY.delete_prompts_by_base_id("greeting_race")
+
+
 class TestEmbeddingsFailureHookRequestData:
     @pytest.mark.asyncio
     async def test_failure_hook_gets_post_setup_data_with_logging_obj(self):
@@ -11535,157 +11679,6 @@ class TestEmbeddingsFailureHookRequestData:
         assert hook_request_data["litellm_logging_obj"] is logging_obj_sentinel
 
 
-class TestRouterModelNameOnStreamingChunks:
-    """
-    Streaming chunks get the body `model` restamped to the client-requested alias
-    just like non-streaming responses, so an auto-routed request had no way to
-    name the model group that served it without reading response headers. Every
-    emitted chunk now carries `router_model_name`.
-
-    These assert on the serialized SSE bytes, not on the chunk objects. The fast
-    path (`_fast_serialize_simple_model_response_stream`) hand-builds a
-    closed-set dict, so a chunk object can carry the field while the wire drops
-    it, and an object-level assertion would pass against that bug.
-    """
-
-    @staticmethod
-    def _chunk(*, with_usage=False):
-        from litellm.types.utils import ModelResponseStream
-
-        return ModelResponseStream(
-            model="smart-route",
-            choices=[{"index": 0, "delta": {"role": "assistant", "content": "hi"}}],
-            usage={"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2} if with_usage else None,
-        )
-
-    @staticmethod
-    def _request_data(*, auto_routed):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        logging_obj = MagicMock()
-        logging_obj.litellm_params = {
-            "metadata": {
-                **({AUTO_ROUTED_REQUEST_METADATA_KEY: True} if auto_routed else {}),
-                "deployment_model_name": "deep-model",
-            }
-        }
-        return {"model": "smart-route", "litellm_logging_obj": logging_obj}
-
-    async def _drive(self, *, chunks, request_data, on_yield=None):
-        from litellm.proxy._types import UserAPIKeyAuth
-        from litellm.proxy.proxy_server import async_data_generator
-        from litellm.proxy.utils import ProxyLogging
-
-        class MockStream:
-            def __aiter__(self):
-                return self._stream()
-
-            async def _stream(self):
-                for index, chunk in enumerate(chunks):
-                    if on_yield is not None:
-                        on_yield(index)
-                    yield chunk
-
-        mock_response = MockStream()
-        mock_response.aclose = AsyncMock()
-
-        proxy_logging_obj = MagicMock(spec=ProxyLogging)
-        proxy_logging_obj.has_streaming_callbacks.return_value = False
-        proxy_logging_obj.needs_iterator_wrap.return_value = False
-        proxy_logging_obj.needs_per_chunk_streaming_hook.return_value = False
-        proxy_logging_obj.async_post_call_streaming_iterator_hook = MagicMock()
-        proxy_logging_obj.async_post_call_streaming_hook = AsyncMock()
-        proxy_logging_obj.post_call_failure_hook = AsyncMock()
-
-        with patch("litellm.proxy.proxy_server.proxy_logging_obj", proxy_logging_obj):
-            with patch.object(ProxyLogging, "_fire_deferred_stream_logging"):
-                return [
-                    data
-                    async for data in async_data_generator(mock_response, MagicMock(spec=UserAPIKeyAuth), request_data)
-                ]
-
-    @staticmethod
-    def _data_frames(emitted):
-        return [
-            frame.decode() if isinstance(frame, bytes) else frame
-            for frame in emitted
-            if b"[DONE]" not in (frame if isinstance(frame, bytes) else frame.encode())
-        ]
-
-    @pytest.mark.asyncio
-    async def test_fast_path_chunk_carries_router_model_name_on_the_wire(self):
-        emitted = await self._drive(chunks=[self._chunk()], request_data=self._request_data(auto_routed=True))
-
-        frames = self._data_frames(emitted)
-        assert frames
-        assert all('"router_model_name":"deep-model"' in frame for frame in frames)
-        assert all('"model":"smart-route"' in frame for frame in frames)
-
-    @pytest.mark.asyncio
-    async def test_slow_path_chunk_carries_router_model_name_on_the_wire(self):
-        emitted = await self._drive(
-            chunks=[self._chunk(with_usage=True)], request_data=self._request_data(auto_routed=True)
-        )
-
-        frames = self._data_frames(emitted)
-        assert frames
-        assert all('"router_model_name":"deep-model"' in frame for frame in frames)
-
-    @pytest.mark.asyncio
-    async def test_plain_model_group_stream_has_no_router_model_name(self):
-        emitted = await self._drive(
-            chunks=[self._chunk(), self._chunk(with_usage=True)],
-            request_data=self._request_data(auto_routed=False),
-        )
-
-        frames = self._data_frames(emitted)
-        assert frames
-        assert all("router_model_name" not in frame for frame in frames)
-
-    @pytest.mark.asyncio
-    async def test_fallback_out_of_the_routed_group_drops_the_field(self):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        request_data = self._request_data(auto_routed=True)
-        bucket = request_data["litellm_logging_obj"].litellm_params["metadata"]
-
-        def fall_back(index):
-            if index == 1:
-                bucket.pop(AUTO_ROUTED_REQUEST_METADATA_KEY)
-                bucket["deployment_model_name"] = "backup-model"
-
-        emitted = await self._drive(
-            chunks=[self._chunk(), self._chunk(), self._chunk()],
-            request_data=request_data,
-            on_yield=fall_back,
-        )
-
-        frames = self._data_frames(emitted)
-        assert len(frames) >= 3
-        assert '"router_model_name":"deep-model"' in frames[0]
-        assert all("router_model_name" not in frame for frame in frames[1:])
-
-    @pytest.mark.asyncio
-    async def test_fallback_to_another_auto_router_reports_the_new_tier(self):
-        request_data = self._request_data(auto_routed=True)
-        bucket = request_data["litellm_logging_obj"].litellm_params["metadata"]
-
-        def fall_back(index):
-            if index == 1:
-                bucket["deployment_model_name"] = "backup-tier"
-
-        emitted = await self._drive(
-            chunks=[self._chunk(), self._chunk(), self._chunk()],
-            request_data=request_data,
-            on_yield=fall_back,
-        )
-
-        frames = self._data_frames(emitted)
-        assert len(frames) >= 3
-        assert '"router_model_name":"deep-model"' in frames[0]
-        assert all('"router_model_name":"backup-tier"' in frame for frame in frames[1:])
-
-
 @pytest.mark.asyncio
 async def test_authoritative_floor_spend_keeps_a_reset_marker_written_during_the_db_read():
     """A team-member spend reset writes the post-reset floor to the spend_db_floor marker

tests/test_litellm/router_strategy/test_complexity_router.py

@@ -1810,9 +1810,7 @@ class TestLLMClassifier:
         "request_kwargs",
         [
             pytest.param({"metadata": {"user_api_key": "sk-abc"}}, id="metadata-bucket"),
-            pytest.param(
-                {"litellm_metadata": {"user_api_key": "sk-abc"}}, id="litellm-metadata-bucket"
-            ),
+            pytest.param({"litellm_metadata": {"user_api_key": "sk-abc"}}, id="litellm-metadata-bucket"),
             pytest.param({}, id="no-caller-context"),
             pytest.param(None, id="no-request-kwargs"),
         ],
@@ -6044,7 +6042,8 @@ class TestContextAwareClassifier:
         turn = (
             "We run a multi-region gateway and last night the eu-west pod returned 502s on the "
             "streaming path only, for thirty minutes, while non-streaming stayed healthy the whole "
-            "window and the cooldown map was mid-failover. " + "Filler sentence to push past the cap. " * 4
+            "window and the cooldown map was mid-failover. "
+            + "Filler sentence to push past the cap. " * 4
             + "Now rewrite the streaming retry path and prove it cannot livelock."
         )
 
@@ -8889,3 +8888,210 @@ async def test_session_pin_survives_json_list_round_trip(mock_router_instance):
     assert response.model == "shared"
     assert response.litellm_params == {"reasoning_effort": "low"}
     assert cache.async_set_cache.call_args.kwargs["value"] == {"model": "shared", "tier": "SIMPLE"}
+
+
+HEURISTIC_FIRST_TIERS: dict[str, str] = {
+    "SIMPLE": "gpt-4o-mini",
+    "MEDIUM": "gpt-4o",
+    "COMPLEX": "claude-sonnet-4-20250514",
+    "REASONING": "o1-preview",
+}
+
+# The scorer maps a weighted score to a tier against these, and PR #37910 is retuning the shipped
+# defaults, so every heuristic_first test pins them rather than inheriting DEFAULT_TIER_BOUNDARIES.
+HEURISTIC_FIRST_BOUNDARIES: dict[str, float] = {
+    "simple_medium": 0.15,
+    "medium_complex": 0.35,
+    "complex_reasoning": 0.60,
+}
+
+# Scores 0.0 with an empty signals tuple: no dimension fires, so the scorer has no opinion and the
+# score-to-tier mapping lands SIMPLE purely by default. This is the population the permutation
+# control measured at ~zero information, and the prompt that must always escalate.
+NO_SIGNAL_PROMPT = (
+    "A distributed ledger must guarantee linearizability across five regions while tolerating one "
+    "region partition and bounded clock skew. Derive the minimum quorum configuration and prove why "
+    "a smaller quorum violates linearizability."
+)
+
+
+def _heuristic_first_router(mock_router_instance, **config_overrides):
+    config = {
+        "tiers": dict(HEURISTIC_FIRST_TIERS),
+        "tier_boundaries": dict(HEURISTIC_FIRST_BOUNDARIES),
+        "classifier_type": "heuristic_first",
+        "heuristic_first_max_tier": "SIMPLE",
+        "classifier_llm_config": {"model": "haiku-classifier", "timeout_ms": 400},
+        **config_overrides,
+    }
+    return ComplexityRouter(
+        model_name="test-complexity-router",
+        litellm_router_instance=mock_router_instance,
+        complexity_router_config=config,
+    )
+
+
+class TestHeuristicFirstConfig:
+    """Config validation for classifier_type='heuristic_first'."""
+
+    @pytest.mark.parametrize(
+        "overrides, expected",
+        [
+            ({"classifier_llm_config": None}, "classifier_llm_config is required"),
+            ({"heuristic_first_max_tier": None}, "heuristic_first_max_tier is required"),
+            ({"heuristic_first_max_tier": "REASONING"}, "is the highest tier"),
+            ({"heuristic_first_max_tier": "NOPE"}, "is not an active tier"),
+            (
+                {
+                    "tiers": {"SIMPLE": "gpt-4o-mini", "COMPLEX": "c", "REASONING": "r"},
+                    "heuristic_first_max_tier": "MEDIUM",
+                },
+                "has no model configured in tiers",
+            ),
+        ],
+    )
+    def test_rejects_incoherent_config(self, overrides, expected):
+        config = {
+            "tiers": dict(HEURISTIC_FIRST_TIERS),
+            "classifier_type": "heuristic_first",
+            "heuristic_first_max_tier": "SIMPLE",
+            "classifier_llm_config": {"model": "haiku-classifier"},
+            **overrides,
+        }
+        with pytest.raises(ValidationError, match=expected):
+            ComplexityRouterConfig(**config)
+
+    @pytest.mark.parametrize("classifier_type", ["heuristic", "llm", "custom"])
+    def test_threshold_rejected_on_every_other_classifier_type(self, classifier_type):
+        """A threshold on a router with no heuristic gate is a silent no-op, so it is refused
+        rather than accepted and ignored."""
+        config: dict[str, object] = {
+            "tiers": dict(HEURISTIC_FIRST_TIERS),
+            "classifier_type": classifier_type,
+            "heuristic_first_max_tier": "SIMPLE",
+        }
+        if classifier_type == "llm":
+            config["classifier_llm_config"] = {"model": "haiku-classifier"}
+        if classifier_type == "custom":
+            config["classifier_plugin"] = _FixedTierClassifier("SIMPLE")
+        with pytest.raises(ValidationError, match="heuristic_first_max_tier is set but classifier_type"):
+            ComplexityRouterConfig(**config)
+
+    def test_custom_tier_set_is_rejected(self):
+        """The scorer only emits the four built-in tiers, so it cannot gate a replaced tier set."""
+        with pytest.raises(ValidationError, match="tier_definitions requires classifier_type"):
+            ComplexityRouterConfig(
+                classifier_type="heuristic_first",
+                heuristic_first_max_tier="lo",
+                classifier_llm_config={"model": "haiku-classifier"},
+                tier_definitions=[{"name": "lo", "description": "x"}, {"name": "hi", "description": "y"}],
+                tiers={"lo": "gpt-4o-mini", "hi": "gpt-4o"},
+            )
+
+    def test_classifier_model_is_a_dependency(self):
+        """uses_llm_classifier is what tells the health graph and the routing-test authorizer that
+        the classifier model is really called, so heuristic_first must answer True."""
+        config = ComplexityRouterConfig(
+            tiers=dict(HEURISTIC_FIRST_TIERS),
+            classifier_type="heuristic_first",
+            heuristic_first_max_tier="SIMPLE",
+            classifier_llm_config={"model": "haiku-classifier"},
+        )
+        assert config.uses_llm_classifier is True
+        assert ComplexityRouterConfig(tiers=dict(HEURISTIC_FIRST_TIERS)).uses_llm_classifier is False
+
+
+class TestHeuristicFirst:
+    """Behavior of the heuristic-first chain: when the classifier call is skipped, and when it is not."""
+
+    @pytest.mark.asyncio
+    async def test_signalled_cheap_prompt_short_circuits(self, mock_router_instance):
+        """A prompt the scorer actually placed at or below the threshold must not reach the LLM."""
+        mock_router_instance.acompletion = AsyncMock()
+        router = _heuristic_first_router(mock_router_instance)
+        outcome = await router.aclassify("thanks so much, appreciate it")
+        mock_router_instance.acompletion.assert_not_called()
+        assert outcome.tier == ComplexityTier.SIMPLE
+        assert outcome.cause == "heuristic_first_short_circuit"
+        assert outcome.score is not None
+        assert outcome.signals
+        assert outcome.classifier_cost is None
+
+    @pytest.mark.asyncio
+    async def test_no_signal_prompt_escalates_even_though_it_scores_simple(self, mock_router_instance):
+        """The core guard. This prompt scores 0.0 and the mapping calls it SIMPLE, which is at the
+        threshold, so a bare tier comparison would short-circuit it to the cheapest model. No
+        dimension fired, so the scorer has no opinion and the classifier must decide."""
+        mock_router_instance.acompletion = AsyncMock(return_value=_llm_response('{"tier": "COMPLEX"}'))
+        router = _heuristic_first_router(mock_router_instance)
+
+        tier, score, signals, _cause = router._score_and_classify(NO_SIGNAL_PROMPT)
+        assert (tier, score, signals) == (ComplexityTier.SIMPLE, 0.0, ())
+
+        outcome = await router.aclassify(NO_SIGNAL_PROMPT)
+        mock_router_instance.acompletion.assert_awaited_once()
+        assert outcome.tier == ComplexityTier.COMPLEX
+        assert outcome.cause == "llm_classifier"
+
+    @pytest.mark.asyncio
+    async def test_signalled_prompt_above_threshold_escalates(self, mock_router_instance):
+        """The scorer had an opinion, but it was above the threshold, so the classifier decides."""
+        mock_router_instance.acompletion = AsyncMock(return_value=_llm_response('{"tier": "REASONING"}'))
+        router = _heuristic_first_router(mock_router_instance)
+
+        tier, _score, signals, _cause = router._score_and_classify("write a python function to reverse a string")
+        assert tier == ComplexityTier.MEDIUM and signals
+
+        outcome = await router.aclassify("write a python function to reverse a string")
+        mock_router_instance.acompletion.assert_awaited_once()
+        assert outcome.tier == ComplexityTier.REASONING
+        assert outcome.cause == "llm_classifier"
+
+    @pytest.mark.asyncio
+    async def test_raising_threshold_short_circuits_what_it_previously_escalated(self, mock_router_instance):
+        """The threshold is the knob: the same signalled MEDIUM prompt escalates at SIMPLE and
+        short-circuits at MEDIUM."""
+        mock_router_instance.acompletion = AsyncMock(return_value=_llm_response('{"tier": "REASONING"}'))
+        router = _heuristic_first_router(mock_router_instance, heuristic_first_max_tier="MEDIUM")
+        outcome = await router.aclassify("write a python function to reverse a string")
+        mock_router_instance.acompletion.assert_not_called()
+        assert outcome.tier == ComplexityTier.MEDIUM
+        assert outcome.cause == "heuristic_first_short_circuit"
+
+    @pytest.mark.asyncio
+    async def test_reasoning_override_never_short_circuits(self, mock_router_instance):
+        """A reasoning-override prompt lands REASONING, which outranks every legal threshold, so it
+        always reaches the classifier."""
+        mock_router_instance.acompletion = AsyncMock(return_value=_llm_response('{"tier": "MEDIUM"}'))
+        router = _heuristic_first_router(mock_router_instance, heuristic_first_max_tier="COMPLEX")
+        outcome = await router.aclassify(
+            "think step by step and analyze the tradeoffs, then reason through the consequences carefully"
+        )
+        mock_router_instance.acompletion.assert_awaited_once()
+        assert outcome.cause == "llm_classifier"
+
+    @pytest.mark.asyncio
+    async def test_classifier_failure_falls_back_to_the_scorer(self, mock_router_instance):
+        """An escalated request whose classifier call fails still gets the scorer's own verdict,
+        the same way classifier_type='llm' does, rather than erroring out."""
+        mock_router_instance.acompletion = AsyncMock(side_effect=RuntimeError("classifier exploded"))
+        router = _heuristic_first_router(mock_router_instance)
+        expected_tier, expected_score, expected_signals, _cause = router._score_and_classify(NO_SIGNAL_PROMPT)
+
+        outcome = await router.aclassify(NO_SIGNAL_PROMPT)
+
+        assert outcome.tier == expected_tier
+        assert outcome.score == expected_score
+        assert outcome.signals == expected_signals
+        assert outcome.cause == "heuristic_scorer"
+
+    @pytest.mark.asyncio
+    async def test_classifier_failure_honors_default_model_fallback(self, mock_router_instance):
+        """classifier_fallback='default_model' still wins over the heuristic outcome, same as it
+        does for classifier_type='llm'."""
+        mock_router_instance.acompletion = AsyncMock(side_effect=RuntimeError("classifier exploded"))
+        router = _heuristic_first_router(
+            mock_router_instance, classifier_fallback="default_model", default_model="gpt-4o"
+        )
+        outcome = await router.aclassify(NO_SIGNAL_PROMPT)
+        assert outcome.cause == "default_model_fallback"

tests/test_litellm/test_router.py

@@ -8765,96 +8765,6 @@ def test_get_router_model_info_keeps_explicit_pricing_overrides():
     assert litellm.get_model_info(model="anthropic/claude-sonnet-4-5")["input_cost_per_token"] != 1e-08
 
 
-class TestAutoRoutedRequestMarker:
-    """The proxy exposes the routed model group in the response body only when an
-    auto-routing strategy actually picked it. The marker is what separates that from
-    ordinary model-group routing, so it must clear on any re-entry (fallbacks reuse the
-    same request_kwargs) that routes plainly."""
-
-    class _RewriteStrategy:
-        async def async_pre_routing_hook(
-            self, model, request_kwargs, messages=None, input=None, specific_deployment=False
-        ):
-            from litellm.types.router import PreRoutingHookResponse
-
-            return PreRoutingHookResponse(model="gemini-flash", messages=messages)
-
-    class _AbstainStrategy:
-        async def async_pre_routing_hook(
-            self, model, request_kwargs, messages=None, input=None, specific_deployment=False
-        ):
-            return None
-
-    @classmethod
-    def _router(cls, strategy) -> "litellm.Router":
-        from litellm.types.router import TaggedPreRoutingStrategy
-
-        router = litellm.Router(
-            model_list=[
-                {"model_name": "smart-route", "litellm_params": {"model": "openai/gpt-4o"}},
-                {"model_name": "gemini-flash", "litellm_params": {"model": "gemini/gemini-3.6-flash"}},
-            ],
-        )
-        router.auto_routers = {"smart-route": [TaggedPreRoutingStrategy(tags=(), strategy=strategy)]}
-        return router
-
-    @pytest.mark.asyncio
-    async def test_marks_the_request_when_an_auto_routing_strategy_picked_the_group(self):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        router = self._router(self._RewriteStrategy())
-        request_kwargs = {"metadata": {}}
-
-        await router.async_pre_routing_hook(model="smart-route", request_kwargs=request_kwargs)
-
-        assert request_kwargs["metadata"][AUTO_ROUTED_REQUEST_METADATA_KEY] is True
-
-    @pytest.mark.asyncio
-    async def test_marks_into_litellm_metadata_when_the_request_uses_that_bucket(self):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        router = self._router(self._RewriteStrategy())
-        request_kwargs = {"litellm_metadata": {}}
-
-        await router.async_pre_routing_hook(model="smart-route", request_kwargs=request_kwargs)
-
-        assert request_kwargs["litellm_metadata"][AUTO_ROUTED_REQUEST_METADATA_KEY] is True
-
-    @pytest.mark.asyncio
-    async def test_no_marker_when_the_group_has_no_auto_routing_strategy(self):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        router = self._router(self._RewriteStrategy())
-        request_kwargs = {"metadata": {}}
-
-        await router.async_pre_routing_hook(model="gemini-flash", request_kwargs=request_kwargs)
-
-        assert AUTO_ROUTED_REQUEST_METADATA_KEY not in request_kwargs["metadata"]
-
-    @pytest.mark.asyncio
-    async def test_no_marker_when_the_strategy_declined_to_route(self):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        router = self._router(self._AbstainStrategy())
-        request_kwargs = {"metadata": {}}
-
-        await router.async_pre_routing_hook(model="smart-route", request_kwargs=request_kwargs)
-
-        assert AUTO_ROUTED_REQUEST_METADATA_KEY not in request_kwargs["metadata"]
-
-    @pytest.mark.asyncio
-    async def test_fallback_reentry_with_a_plain_group_clears_the_stale_marker(self):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
-        router = self._router(self._RewriteStrategy())
-        request_kwargs = {"metadata": {}}
-
-        await router.async_pre_routing_hook(model="smart-route", request_kwargs=request_kwargs)
-        await router.async_pre_routing_hook(model="gemini-flash", request_kwargs=request_kwargs)
-
-        assert AUTO_ROUTED_REQUEST_METADATA_KEY not in request_kwargs["metadata"]
-
-
 class TestModelGroupAliasReachesPreRoutingStrategies:
     """A `model_group_alias` whose target is a strategy router must dispatch exactly like the
     router's own model_name. The four strategy registries are keyed by the marker deployment's
@@ -8912,8 +8822,6 @@ class TestModelGroupAliasReachesPreRoutingStrategies:
     @pytest.mark.parametrize("registry_name", REGISTRY_NAMES)
     @pytest.mark.asyncio
     async def test_alias_dispatches_to_the_strategy_registered_under_the_target(self, registry_name):
-        from litellm.constants import AUTO_ROUTED_REQUEST_METADATA_KEY
-
         router = self._router(registry_name)
         request_kwargs = {"metadata": {}}
 
@@ -8923,7 +8831,6 @@ class TestModelGroupAliasReachesPreRoutingStrategies:
 
         assert response is not None
         assert response.model == "gemini-flash"
-        assert request_kwargs["metadata"][AUTO_ROUTED_REQUEST_METADATA_KEY] is True
 
     @pytest.mark.asyncio
     async def test_alias_call_still_forwards_the_marker_own_params_to_the_routed_tier(self):

type-discipline-budget.json

@@ -27,7 +27,7 @@
     "limit": 0
   },
   "LIT010": {
-    "limit": 16619
+    "limit": 16616
   },
   "LIT011": {
     "limit": 5583

ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/components/AutoRouters/autoRouterRows.ts

@@ -54,8 +54,14 @@ const asStringArray = (value: unknown): string[] =>
 
 const dedupe = (models: string[]): string[] => Array.from(new Set(models));
 
+const COMPLEXITY_TYPE_LABELS: Record<string, string> = {
+  llm: "LLM Classifier",
+  heuristic_first: "Heuristic first",
+  custom: "Custom classifier",
+};
+
 export const complexityTypeLabel = (config: Record<string, unknown>): string =>
-  config.classifier_type === "llm" ? "LLM Classifier" : "Heuristic";
+  (typeof config.classifier_type === "string" && COMPLEXITY_TYPE_LABELS[config.classifier_type]) || "Heuristic";
 
 interface Presentation {
   typeLabel: string;

ui/litellm-dashboard/src/components/TeamsPage/TeamsTable.tsx

@@ -2,6 +2,7 @@
 
 import { useOrganizations } from "@/app/(dashboard)/hooks/organizations/useOrganizations";
 import { useTeamsTable } from "@/app/(dashboard)/hooks/teams/useTeams";
+import useAuthorized from "@/app/(dashboard)/hooks/useAuthorized";
 import {
   DataTable,
   DataTableFilterDrawer,
@@ -9,14 +10,17 @@ import {
   DataTableToolbar,
 } from "@/components/shared/DataTable";
 import { SearchSelect } from "@/components/shared/SearchSelect";
+import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { DEBOUNCE_WAIT_MS } from "@/utils/debounceConstants";
 import { useDebouncedValue } from "@tanstack/react-pacer/debouncer";
 import { ColumnFiltersState, OnChangeFn, PaginationState, SortingState } from "@tanstack/react-table";
+import { Download } from "lucide-react";
 import React, { useCallback, useMemo, useState } from "react";
 
 import { Team } from "../key_team_helpers/key_list";
 import { getTeamTableColumns, TEAM_TABLE_HIDDEN_COLUMNS } from "./teamTableColumns";
+import { exportTeamsToCsv } from "./teamsCsvExport";
 
 interface TeamsTableProps {
   userRole: string | null;
@@ -49,7 +53,9 @@ export function TeamsTable({ userRole, userID, onSelectTeam, onEditTeam, onDelet
   const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
   const [filtersOpen, setFiltersOpen] = useState(false);
   const [searchInput, setSearchInput] = useState("");
+  const [isExporting, setIsExporting] = useState(false);
   const [searchQuery] = useDebouncedValue(searchInput, { wait: DEBOUNCE_WAIT_MS });
+  const { accessToken } = useAuthorized();
 
   const getFilterValue = useCallback(
     (columnId: string): string | undefined => {
@@ -61,16 +67,19 @@ export function TeamsTable({ userRole, userID, onSelectTeam, onEditTeam, onDelet
 
   const isAdminView = userRole === "Admin" || userRole === "Admin Viewer";
 
-  const teamListOptions = {
-    organizationID: getFilterValue("org_id"),
-    team_alias: getFilterValue("alias"),
-    teamID: getFilterValue("team_id"),
-    search: searchQuery.trim() || undefined,
-    searchTeamIdMatch: "prefix" as const,
-    userID: isAdminView ? undefined : userID ?? undefined,
-    sortBy: sorting[0]?.id,
-    sortOrder: toSortOrder(sorting),
-  };
+  const teamListOptions = useMemo(
+    () => ({
+      organizationID: getFilterValue("org_id"),
+      team_alias: getFilterValue("alias"),
+      teamID: getFilterValue("team_id"),
+      search: searchQuery.trim() || undefined,
+      searchTeamIdMatch: "prefix" as const,
+      userID: isAdminView ? undefined : userID ?? undefined,
+      sortBy: sorting[0]?.id,
+      sortOrder: toSortOrder(sorting),
+    }),
+    [getFilterValue, searchQuery, isAdminView, userID, sorting],
+  );
 
   const {
     data: teamsResponse,
@@ -97,6 +106,16 @@ export function TeamsTable({ userRole, userID, onSelectTeam, onEditTeam, onDelet
     setTablePagination((prev) => ({ ...prev, pageIndex: 0 }));
   }, []);
 
+  const handleExportCsv = useCallback(async () => {
+    if (!accessToken || isExporting) return;
+    setIsExporting(true);
+    try {
+      await exportTeamsToCsv(accessToken, teamListOptions);
+    } finally {
+      setIsExporting(false);
+    }
+  }, [accessToken, isExporting, teamListOptions]);
+
   const columns = useMemo(() => {
     const columnDeps = { organizations, userRole, onSelectTeam, onEditTeam, onDeleteTeam };
     return getTeamTableColumns(columnDeps);
@@ -159,7 +178,18 @@ export function TeamsTable({ userRole, userID, onSelectTeam, onEditTeam, onDelet
             onOpenFilters={() => setFiltersOpen(true)}
             filterLabels={FILTER_LABELS}
             formatFilterValue={formatFilterValue}
-          />
+          >
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleExportCsv}
+              disabled={isExporting}
+              data-testid="teams-export-csv"
+            >
+              <Download />
+              {isExporting ? "Exporting..." : "Export CSV"}
+            </Button>
+          </DataTableToolbar>
           <DataTableFilterDrawer
             table={table}
             open={filtersOpen}

ui/litellm-dashboard/src/components/TeamsPage/teamsCsvExport.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { TeamsResponse } from "@/app/(dashboard)/hooks/teams/useTeams";
+
+import type { Team } from "../key_team_helpers/key_list";
+import {
+  buildTeamsCsv,
+  buildTeamsCsvRows,
+  collectTeamMemberBudgetIds,
+  fetchAllTeams,
+  TEAMS_EXPORT_PAGE_SIZE,
+} from "./teamsCsvExport";
+
+const makeTeam = (overrides: Partial<Team>): Team =>
+  ({
+    team_id: "team-1",
+    team_alias: "alias-1",
+    models: [],
+    max_budget: null,
+    budget_duration: null,
+    tpm_limit: null,
+    rpm_limit: null,
+    organization_id: "org-1",
+    created_at: "2026-01-01T00:00:00Z",
+    keys: [],
+    members_with_roles: [],
+    spend: 0,
+    ...overrides,
+  }) as Team;
+
+const makePage = (teams: Team[], page: number, totalPages: number): TeamsResponse => ({
+  teams,
+  total: teams.length,
+  page,
+  page_size: TEAMS_EXPORT_PAGE_SIZE,
+  total_pages: totalPages,
+});
+
+describe("fetchAllTeams", () => {
+  it("returns the single page without extra requests", async () => {
+    const fetchPage = vi.fn().mockResolvedValue(makePage([makeTeam({ team_id: "a" })], 1, 1));
+    const teams = await fetchAllTeams(fetchPage);
+    expect(teams.map((t) => t.team_id)).toEqual(["a"]);
+    expect(fetchPage).toHaveBeenCalledTimes(1);
+    expect(fetchPage).toHaveBeenCalledWith(1, TEAMS_EXPORT_PAGE_SIZE);
+  });
+
+  it("fetches and concatenates every page in order", async () => {
+    const fetchPage = vi
+      .fn()
+      .mockImplementation(async (page: number) => makePage([makeTeam({ team_id: `team-${page}` })], page, 3));
+    const teams = await fetchAllTeams(fetchPage);
+    expect(teams.map((t) => t.team_id)).toEqual(["team-1", "team-2", "team-3"]);
+    expect(fetchPage).toHaveBeenCalledTimes(3);
+    expect(fetchPage).toHaveBeenCalledWith(2, TEAMS_EXPORT_PAGE_SIZE);
+    expect(fetchPage).toHaveBeenCalledWith(3, TEAMS_EXPORT_PAGE_SIZE);
+  });
+});
+
+describe("collectTeamMemberBudgetIds", () => {
+  it("dedupes ids and skips teams without a member budget", () => {
+    const teams = [
+      makeTeam({ team_id: "a", metadata: { team_member_budget_id: "bud-1" } }),
+      makeTeam({ team_id: "b", metadata: { team_member_budget_id: "bud-1" } }),
+      makeTeam({ team_id: "c", metadata: {} }),
+      makeTeam({ team_id: "d", metadata: { team_member_budget_id: "" } }),
+      makeTeam({ team_id: "e" }),
+      makeTeam({ team_id: "f", metadata: { team_member_budget_id: "bud-2" } }),
+    ];
+    expect(collectTeamMemberBudgetIds(teams)).toEqual(["bud-1", "bud-2"]);
+  });
+});
+
+describe("buildTeamsCsvRows", () => {
+  it("maps configured limits, spend, models, and rate limits", () => {
+    const teamFields: Partial<Team> = {
+      team_id: "team-42",
+      team_alias: "finance",
+      organization_id: "org-9",
+      models: ["gpt-4o", "claude-sonnet-4-5"],
+      max_budget: 250,
+      budget_duration: "30d",
+      budget_reset_at: "2026-02-01T00:00:00Z",
+      spend: 12.5,
+      tpm_limit: 1000,
+      rpm_limit: 50,
+      members_count: 7,
+      keys_count: 3,
+      blocked: false,
+    };
+    const [row] = buildTeamsCsvRows([makeTeam(teamFields)], []);
+    const expectedRow = {
+      "Team Alias": "finance",
+      "Team ID": "team-42",
+      "Organization ID": "org-9",
+      Models: "gpt-4o, claude-sonnet-4-5",
+      "Max Budget (USD)": 250,
+      "Budget Duration": "30d",
+      "Budget Reset At": "2026-02-01T00:00:00Z",
+      "Spend (USD)": 12.5,
+      "TPM Limit": 1000,
+      "RPM Limit": 50,
+      "Team Member Budget (USD)": "",
+      "Team Member Budget Duration": "",
+      "Team Member TPM Limit": "",
+      "Team Member RPM Limit": "",
+      Members: 7,
+      Keys: 3,
+      Blocked: false,
+      "Created At": "2026-01-01T00:00:00Z",
+    };
+    expect(row).toEqual(expectedRow);
+  });
+
+  it("joins team member budget rows by budget id from metadata", () => {
+    const teams = [
+      makeTeam({ team_id: "a", metadata: { team_member_budget_id: "bud-1" } }),
+      makeTeam({ team_id: "b" }),
+    ];
+    const rows = buildTeamsCsvRows(teams, [
+      { budget_id: "bud-1", max_budget: 25, budget_duration: "7d", tpm_limit: 200, rpm_limit: 10 },
+    ]);
+    expect(rows[0]["Team Member Budget (USD)"]).toBe(25);
+    expect(rows[0]["Team Member Budget Duration"]).toBe("7d");
+    expect(rows[0]["Team Member TPM Limit"]).toBe(200);
+    expect(rows[0]["Team Member RPM Limit"]).toBe(10);
+    expect(rows[1]["Team Member Budget (USD)"]).toBe("");
+  });
+
+  it("falls back to members_with_roles and keys lengths when counts are absent", () => {
+    const team = makeTeam({
+      members_with_roles: [
+        { user_id: "u1", role: "admin" },
+        { user_id: "u2", role: "user" },
+      ],
+      keys: [{ token: "t" } as Team["keys"][number]],
+    });
+    const [row] = buildTeamsCsvRows([team], []);
+    expect(row.Members).toBe(2);
+    expect(row.Keys).toBe(1);
+  });
+});
+
+describe("buildTeamsCsv", () => {
+  it("produces a header row and quotes values containing commas", () => {
+    const csv = buildTeamsCsv([makeTeam({ team_alias: "sales, emea", models: ["m1", "m2"] })], []);
+    const [header, row] = csv.split("\r\n");
+    expect(header).toBe(
+      "Team Alias,Team ID,Organization ID,Models,Max Budget (USD),Budget Duration,Budget Reset At,Spend (USD)," +
+        "TPM Limit,RPM Limit,Team Member Budget (USD),Team Member Budget Duration,Team Member TPM Limit," +
+        "Team Member RPM Limit,Members,Keys,Blocked,Created At",
+    );
+    expect(row).toContain('"sales, emea"');
+    expect(row).toContain('"m1, m2"');
+  });
+
+  it("neutralizes formula-leading values so spreadsheets render them as text", () => {
+    const csv = buildTeamsCsv([makeTeam({ team_alias: "=SUM(A1:A9)" })], []);
+    const [, row] = csv.split("\r\n");
+    expect(row).toContain('"\'=SUM(A1:A9)"');
+    expect(row).not.toContain("=SUM(A1:A9),");
+  });
+});

ui/litellm-dashboard/src/components/TeamsPage/teamsCsvExport.ts

@@ -0,0 +1,95 @@
+import Papa from "papaparse";
+
+import { TeamListCallOptions, TeamsResponse, teamListCall } from "@/app/(dashboard)/hooks/teams/useTeams";
+
+import { Team } from "../key_team_helpers/key_list";
+import { apiClient } from "../networking";
+
+export interface TeamMemberBudget {
+  budget_id: string;
+  max_budget?: number | null;
+  budget_duration?: string | null;
+  tpm_limit?: number | null;
+  rpm_limit?: number | null;
+}
+
+export const TEAMS_EXPORT_PAGE_SIZE = 100;
+
+type FetchTeamsPage = (page: number, pageSize: number) => Promise<TeamsResponse>;
+
+export const fetchAllTeams = async (fetchPage: FetchTeamsPage): Promise<Team[]> => {
+  const firstPage = await fetchPage(1, TEAMS_EXPORT_PAGE_SIZE);
+  const totalPages = firstPage.total_pages ?? 1;
+  if (totalPages <= 1) return firstPage.teams;
+
+  const remainingPages = await Promise.all(
+    Array.from({ length: totalPages - 1 }, (_, i) => fetchPage(i + 2, TEAMS_EXPORT_PAGE_SIZE)),
+  );
+  return [firstPage, ...remainingPages].flatMap((page) => page.teams);
+};
+
+const teamMemberBudgetId = (team: Team): string | null => {
+  const id = team.metadata?.team_member_budget_id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+};
+
+export const collectTeamMemberBudgetIds = (teams: Team[]): string[] =>
+  Array.from(new Set(teams.map(teamMemberBudgetId).filter((id): id is string => id !== null)));
+
+const cell = (value: string | number | boolean | null | undefined): string | number | boolean => value ?? "";
+
+export const buildTeamsCsvRows = (
+  teams: Team[],
+  budgets: TeamMemberBudget[],
+): Record<string, string | number | boolean>[] => {
+  const budgetsById = new Map(budgets.map((budget) => [budget.budget_id, budget]));
+  return teams.map((team) => {
+    const budgetId = teamMemberBudgetId(team);
+    const memberBudget = budgetId ? budgetsById.get(budgetId) : undefined;
+    return {
+      "Team Alias": cell(team.team_alias),
+      "Team ID": cell(team.team_id),
+      "Organization ID": cell(team.organization_id),
+      Models: (team.models ?? []).join(", "),
+      "Max Budget (USD)": cell(team.max_budget),
+      "Budget Duration": cell(team.budget_duration),
+      "Budget Reset At": cell(team.budget_reset_at),
+      "Spend (USD)": cell(team.spend),
+      "TPM Limit": cell(team.tpm_limit),
+      "RPM Limit": cell(team.rpm_limit),
+      "Team Member Budget (USD)": cell(memberBudget?.max_budget),
+      "Team Member Budget Duration": cell(memberBudget?.budget_duration),
+      "Team Member TPM Limit": cell(memberBudget?.tpm_limit),
+      "Team Member RPM Limit": cell(memberBudget?.rpm_limit),
+      Members: cell(team.members_count ?? team.members_with_roles?.length),
+      Keys: cell(team.keys_count ?? team.keys?.length),
+      Blocked: cell(team.blocked),
+      "Created At": cell(team.created_at),
+    };
+  });
+};
+
+export const buildTeamsCsv = (teams: Team[], budgets: TeamMemberBudget[]): string =>
+  Papa.unparse(buildTeamsCsvRows(teams, budgets), { escapeFormulae: true });
+
+const downloadCsv = (csv: string, fileName: string): void => {
+  const blob = new Blob([csv], { type: "text/csv;charset=utf-8;" });
+  const url = window.URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = fileName;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  window.URL.revokeObjectURL(url);
+};
+
+export const exportTeamsToCsv = async (accessToken: string, options: TeamListCallOptions): Promise<number> => {
+  const teams = await fetchAllTeams((page, pageSize) => teamListCall(accessToken, page, pageSize, options));
+  const budgetIds = collectTeamMemberBudgetIds(teams);
+  const budgets = budgetIds.length
+    ? await apiClient.post<TeamMemberBudget[]>("/budget/info", { accessToken, body: { budgets: budgetIds } })
+    : [];
+  downloadCsv(buildTeamsCsv(teams, budgets), `teams_export_${new Date().toISOString().split("T")[0]}.csv`);
+  return teams.length;
+};

ui/litellm-dashboard/src/components/add_model/ClassificationMethodConfig.tsx

@@ -27,6 +27,10 @@ import {
   CLASSIFICATION_RUBRIC_KEYS,
   ClassificationRubric,
   effectiveTierLabel,
+  heuristicScoringRole,
+  usesLlmClassifier,
+  DEFAULT_HEURISTIC_FIRST_MAX_TIER,
+  HEURISTIC_FIRST_MAX_TIER_KEYS,
 } from "./ComplexityRouterConfig";
 
 const DEFAULT_SCORING_EXPLANATION =
@@ -49,7 +53,7 @@ const CUSTOM_PROMPT_WITH_DEFAULT_MODEL_FALLBACK =
  */
 const scoringExplanation = (value: ComplexityRouterConfigValue): string => {
   const usesCustomPrompt =
-    value.classifier_type === "llm" && Boolean(value.classifier_llm_config?.system_prompt?.trim());
+    usesLlmClassifier(value.classifier_type) && Boolean(value.classifier_llm_config?.system_prompt?.trim());
   if (!usesCustomPrompt) return DEFAULT_SCORING_EXPLANATION;
   return value.classifier_fallback === "default_model"
     ? CUSTOM_PROMPT_WITH_DEFAULT_MODEL_FALLBACK
@@ -148,7 +152,7 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
 }) => {
   const hasDefaultModel = Boolean(defaultModel);
   const classifierModelMissing =
-    showValidationErrors && value.classifier_type === "llm" && !value.classifier_llm_config?.model;
+    showValidationErrors && usesLlmClassifier(value.classifier_type) && !value.classifier_llm_config?.model;
   const usesCustomPrompt = Boolean(value.classifier_llm_config?.system_prompt?.trim());
   const contextBudget = value.classifier_context_budget_chars ?? DEFAULT_CLASSIFIER_CONTEXT_BUDGET_CHARS;
   const contextBudgetQuotesNothing = contextBudget > 0 && contextBudget < MIN_QUOTED_CONTEXT_TURN_CHARS;
@@ -158,29 +162,35 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
     const nextValue: ComplexityRouterConfigValue = {
       ...value,
       classifier_type: classifierType,
-      classifier_llm_config:
-        classifierType === "llm"
-          ? value.classifier_llm_config ?? {
-              model: "",
-              timeout_ms: DEFAULT_CLASSIFIER_TIMEOUT_MS,
-              classification_rubric: NEW_CLASSIFIER_CLASSIFICATION_RUBRIC,
-            }
+      classifier_llm_config: usesLlmClassifier(classifierType)
+        ? value.classifier_llm_config ?? {
+            model: "",
+            timeout_ms: DEFAULT_CLASSIFIER_TIMEOUT_MS,
+            classification_rubric: NEW_CLASSIFIER_CLASSIFICATION_RUBRIC,
+          }
+        : undefined,
+      classifier_context_window_size: usesLlmClassifier(classifierType)
+        ? value.classifier_context_window_size ?? DEFAULT_CLASSIFIER_CONTEXT_WINDOW_SIZE
+        : undefined,
+      classifier_context_budget_chars: usesLlmClassifier(classifierType)
+        ? value.classifier_context_budget_chars ?? DEFAULT_CLASSIFIER_CONTEXT_BUDGET_CHARS
+        : undefined,
+      classifier_context_include_assistant_turns: usesLlmClassifier(classifierType)
+        ? value.classifier_context_include_assistant_turns
+        : undefined,
+      classifier_fallback: usesLlmClassifier(classifierType) ? value.classifier_fallback : undefined,
+      heuristic_first_max_tier:
+        classifierType === "heuristic_first"
+          ? value.heuristic_first_max_tier ?? DEFAULT_HEURISTIC_FIRST_MAX_TIER
           : undefined,
-      classifier_context_window_size:
-        classifierType === "llm"
-          ? value.classifier_context_window_size ?? DEFAULT_CLASSIFIER_CONTEXT_WINDOW_SIZE
-          : undefined,
-      classifier_context_budget_chars:
-        classifierType === "llm"
-          ? value.classifier_context_budget_chars ?? DEFAULT_CLASSIFIER_CONTEXT_BUDGET_CHARS
-          : undefined,
-      classifier_context_include_assistant_turns:
-        classifierType === "llm" ? value.classifier_context_include_assistant_turns : undefined,
-      classifier_fallback: classifierType === "llm" ? value.classifier_fallback : undefined,
     };
     onChange(nextValue);
   };
 
+  const handleHeuristicFirstMaxTierChange = (tier: string) => {
+    onChange({ ...value, heuristic_first_max_tier: tier });
+  };
+
   const handleClassifierModelChange = (model: string) => {
     onChange({
       ...value,
@@ -265,7 +275,7 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
             <span>
               <strong className="font-semibold">Heuristic</strong>{" "}
               <span className="text-muted-foreground">
-                (default) — rule-based scoring, no API calls, &lt;1ms latency
+                (default), rule-based scoring with no API calls and &lt;1ms latency
               </span>
             </span>
           </Label>
@@ -273,13 +283,47 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
             <RadioGroupItem value="llm" className="mt-0.5" />
             <span>
               <strong className="font-semibold">LLM Classifier</strong>{" "}
-              <span className="text-muted-foreground">— use a model to decide the tier (e.g. a small/fast model)</span>
+              <span className="text-muted-foreground">calls a model to decide the tier (e.g. a small/fast model)</span>
+            </span>
+          </Label>
+          <Label className="items-start font-normal leading-normal">
+            <RadioGroupItem value="heuristic_first" className="mt-0.5" />
+            <span>
+              <strong className="font-semibold">Heuristic first</strong>{" "}
+              <span className="text-muted-foreground">
+                scores locally, and only pays for the classifier when the score does not confidently land a cheap tier
+              </span>
             </span>
           </Label>
         </div>
       </RadioGroup>
 
-      {value.classifier_type === "llm" && (
+      {value.classifier_type === "heuristic_first" && (
+        <div className="mt-4 space-y-2">
+          <strong className="block font-semibold">Decide locally up to</strong>
+          <Select
+            value={value.heuristic_first_max_tier}
+            onValueChange={(tier: unknown) => handleHeuristicFirstMaxTierChange(tier as string)}
+          >
+            <SelectTrigger className="w-full">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {HEURISTIC_FIRST_MAX_TIER_KEYS.map((tier) => (
+                <SelectItem key={tier} value={tier}>
+                  {effectiveTierLabel(tier, value.tier_labels)}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+          <p className="text-sm text-muted-foreground">
+            A request the scorer places at or below this tier routes there without a classifier call. Anything the
+            scorer places higher, and anything it found no signal for at all, goes to the classifier instead
+          </p>
+        </div>
+      )}
+
+      {usesLlmClassifier(value.classifier_type) && (
         <div className="mt-4 space-y-3">
           <div>
             <strong className="block mb-1 font-semibold">Classifier Model</strong>
@@ -459,7 +503,7 @@ const ClassificationMethodConfig: React.FC<ClassificationMethodConfigProps> = ({
         </div>
       )}
 
-      {value.classifier_type === "heuristic" && (
+      {heuristicScoringRole(value) !== "never" && (
         <div className="mt-4">
           <div className="flex items-center gap-2 mb-1">
             <strong className="font-semibold">Custom Technical Keywords</strong>

ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.test.tsx

@@ -1012,3 +1012,47 @@ describe("ComplexityRouterConfig per-model effort filtering", () => {
     );
   });
 });
+
+describe("ComplexityRouterConfig custom technical keywords", () => {
+  const openClassificationPanel = (value: ComplexityRouterConfigValue) => {
+    renderWithProviders(<ComplexityRouterConfig modelInfo={mockModelInfo} value={value} onChange={vi.fn()} />);
+    fireEvent.click(screen.getByText("Advanced: Classification Method"));
+  };
+
+  const llmConfig = { model: "gpt-3.5-turbo", timeout_ms: 3000 };
+
+  it.each([
+    ["heuristic", { ...defaultValue, classifier_type: "heuristic" as const }],
+    [
+      "heuristic_first",
+      {
+        ...defaultValue,
+        classifier_type: "heuristic_first" as const,
+        heuristic_first_max_tier: "SIMPLE",
+        classifier_llm_config: llmConfig,
+      },
+    ],
+    [
+      "llm falling back to the scorer",
+      {
+        ...defaultValue,
+        classifier_type: "llm" as const,
+        classifier_llm_config: llmConfig,
+        classifier_fallback: "heuristic" as const,
+      },
+    ],
+  ])("offers the keywords on a router whose scorer runs: %s", (_label, value) => {
+    openClassificationPanel(value);
+    expect(screen.getByText("Custom Technical Keywords")).toBeInTheDocument();
+  });
+
+  it("hides the keywords when the scorer never runs, so they cannot imply an effect they have none", () => {
+    openClassificationPanel({
+      ...defaultValue,
+      classifier_type: "llm",
+      classifier_llm_config: llmConfig,
+      classifier_fallback: "default_model",
+    });
+    expect(screen.queryByText("Custom Technical Keywords")).not.toBeInTheDocument();
+  });
+});

ui/litellm-dashboard/src/components/add_model/ComplexityRouterConfig.tsx

@@ -95,7 +95,15 @@ export interface ClassifierLLMConfig {
   system_prompt?: string;
 }
 
-export type ClassifierType = "heuristic" | "llm";
+export type ClassifierType = "heuristic" | "llm" | "heuristic_first";
+
+/**
+ * Whether this router can call classifier_llm_config.model. Mirrors the backend's
+ * ComplexityRouterConfig.uses_llm_classifier, and is the single gate for every classifier-only
+ * control and payload key, so a new chaining type cannot strip knobs the operator set.
+ */
+export const usesLlmClassifier = (classifierType: ClassifierType): boolean =>
+  classifierType === "llm" || classifierType === "heuristic_first";
 
 export type ClassifierFallback = "heuristic" | "default_model";
 
@@ -113,13 +121,14 @@ export type HeuristicScoringRole = "decides" | "fallback_only" | "never";
 /**
  * Whether the heuristic scorer runs on this router at all, which is what gates its knobs. An LLM
  * classifier still falls back to the scorer unless the fallback is the default model, so the gate cannot be
- * a plain classifier_type check.
+ * a plain classifier_type check. Under heuristic_first the scorer runs first on every request and
+ * decides outright whenever it lands at or below the threshold.
  */
 export const heuristicScoringRoleFor = (
   classifierType: ClassifierType,
   classifierFallback: ClassifierFallback | undefined,
 ): HeuristicScoringRole => {
-  if (classifierType === "heuristic") return "decides";
+  if (classifierType === "heuristic" || classifierType === "heuristic_first") return "decides";
   return (classifierFallback ?? DEFAULT_CLASSIFIER_FALLBACK) === "heuristic" ? "fallback_only" : "never";
 };
 
@@ -142,6 +151,8 @@ export interface ComplexityRouterConfigValue {
   classifier_context_per_turn_chars?: number;
   classifier_context_include_assistant_turns?: boolean;
   classifier_fallback?: ClassifierFallback;
+  /** Highest tier the scorer may decide alone under heuristic_first. Required by that type, rejected by the others. */
+  heuristic_first_max_tier?: string;
   session_affinity?: boolean;
   deployment_affinity?: boolean;
   /** Tier floor for coding-agent plan-mode requests. Unset means detection is off, matching the backend. */
@@ -223,6 +234,14 @@ export const TIER_KEYS = Object.keys(TIER_DESCRIPTIONS) as Array<keyof Complexit
 export const effectiveTierLabel = (tier: keyof ComplexityTiers, tierLabels: ComplexityTierLabels | undefined): string =>
   tierLabels?.[tier]?.trim() || TIER_DESCRIPTIONS[tier].label;
 
+export const DEFAULT_HEURISTIC_FIRST_MAX_TIER = "SIMPLE";
+
+/**
+ * Tiers the heuristic_first threshold may name. The top tier is excluded because it would short
+ * circuit every request and leave the classifier unreachable, which the backend rejects.
+ */
+export const HEURISTIC_FIRST_MAX_TIER_KEYS = TIER_KEYS.slice(0, -1);
+
 const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
   modelInfo,
   value,
@@ -314,7 +333,7 @@ const ComplexityRouterConfig: React.FC<ComplexityRouterConfigProps> = ({
       <span className="block mb-4 text-xs text-muted-foreground">
         Rename a tier to use your own vocabulary in the dashboard and your spend logs. Renaming doesn&apos;t change how
         requests are classified, and callers never see these names.
-        {value.classifier_type === "llm" &&
+        {usesLlmClassifier(value.classifier_type) &&
           " Your classifier model reads these names, so clearer ones can sharpen its choices."}
       </span>
 

ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.test.tsx

@@ -5,6 +5,8 @@ import AddAutoRouterTab from "./add_auto_router_tab";
 import { toast } from "@/lib/toast";
 import { handleAddAutoRouterSubmit } from "./handle_add_auto_router_submit";
 import { getMissingTiersError } from "./build_complexity_router_config";
+import { getSubmitBlockedReason } from "./add_auto_router_tab";
+import { buildModelAvailability } from "@/lib/autorouter_presets";
 import { testAutoRouterRouting } from "../networking";
 import { ModelGroup } from "@/components/llm_calls/fetch_models";
 import { getAllPresets, getPresetByKey, getRequiredModelsInPreset } from "@/lib/autorouter_presets";
@@ -864,3 +866,38 @@ describe("AddAutoRouterTab", () => {
     });
   });
 });
+
+describe("getSubmitBlockedReason", () => {
+  const tiers = {
+    SIMPLE: ["gpt-4o-mini"],
+    MEDIUM: ["gpt-4o-mini"],
+    COMPLEX: ["gpt-4o-mini"],
+    REASONING: ["gpt-4o-mini"],
+  };
+  const availability = buildModelAvailability(["gpt-4o-mini"], []);
+  const referenced = {
+    tiers,
+    classifierType: "heuristic" as const,
+    classifierLlmConfig: undefined,
+    semanticMatchingEnabled: false,
+    embeddingModel: undefined,
+    defaultModel: undefined,
+  };
+
+  it("lets a complete heuristic router through", () => {
+    expect(getSubmitBlockedReason({ tiers, classifier_type: "heuristic" }, [], referenced, availability)).toBeNull();
+  });
+
+  it("blocks an LLM classifier with no model, which the button previously left enabled", () => {
+    expect(getSubmitBlockedReason({ tiers, classifier_type: "llm" }, [], referenced, availability)).toContain(
+      "Please select a classifier model",
+    );
+  });
+
+  it("blocks a keyword rule aimed at a tier this router does not have", () => {
+    const rules = [{ id: "r1", keywords: ["audit"], tier: "AUDIT" }];
+    expect(getSubmitBlockedReason({ tiers, classifier_type: "heuristic" }, rules, referenced, availability)).toContain(
+      "no longer has",
+    );
+  });
+});

ui/litellm-dashboard/src/components/add_model/add_auto_router_tab.tsx

@@ -34,6 +34,7 @@ import {
   BuildComplexityRouterConfigParams,
   buildComplexityRouterConfig,
   getKeywordTierRulesError,
+  getClassifierModelError,
   getMissingTiersError,
   getPlanModeTierError,
   getSemanticConfigError,
@@ -116,7 +117,7 @@ const tierConfigSummary = (config: ComplexityRouterConfigValue): string => {
 // itself and to say what is missing, so the two can never give different answers. Checks the
 // config actually being built, not which preset (if any) it came from: a preset only ever
 // prefills once (handlePresetChange), and everything after that is edited exactly like Custom.
-const getSubmitBlockedReason = (
+export const getSubmitBlockedReason = (
   config: ComplexityRouterConfigValue,
   keywordTierRules: KeywordTierRule[],
   referencedModelsParams: Parameters<typeof getReferencedModelsError>[0],
@@ -125,7 +126,8 @@ const getSubmitBlockedReason = (
   getMissingTiersError(activeTierRows(config)) ??
   getTierLabelsError(config.tier_labels) ??
   getPlanModeTierError(config.plan_mode_min_tier, activeTierRows(config)) ??
-  getKeywordTierRulesError(keywordTierRules) ??
+  getKeywordTierRulesError(keywordTierRules, activeTierRows(config)) ??
+  getClassifierModelError(config) ??
   getReferencedModelsError(referencedModelsParams, availability);
 
 const autoRouterSchema = (requiresTeamScope: boolean) =>
@@ -342,6 +344,7 @@ const AddAutoRouterTab: React.FC<AddAutoRouterTabProps> = ({
     tiers: complexityRouterConfig.tiers,
     defaultModel: complexityRouterConfig.default_model,
     planModeMinTier: complexityRouterConfig.plan_mode_min_tier,
+    heuristicFirstMaxTier: complexityRouterConfig.heuristic_first_max_tier,
     tierLabels: complexityRouterConfig.tier_labels,
     classifierType: complexityRouterConfig.classifier_type,
     classifierLlmConfig: complexityRouterConfig.classifier_llm_config,
@@ -370,50 +373,21 @@ const AddAutoRouterTab: React.FC<AddAutoRouterTabProps> = ({
   };
 
   const submitRecommendedRouter = async (name: string) => {
-    const { tiers, tierLabels, classifierType, classifierLlmConfig } = complexityRouterConfigParams;
+    const { tiers } = complexityRouterConfigParams;
 
-    const missingTiersError = getMissingTiersError(activeTierRows(complexityRouterConfig));
-    if (missingTiersError) {
+    // The one answer the submit button reads, so a disabled button and a refused submit cannot
+    // disagree about why. The handler needs it in its own right: the form fires this on Enter
+    // regardless of the button's disabled state.
+    const blockedReason =
+      getSubmitBlockedReason(
+        complexityRouterConfig,
+        keywordTierRules,
+        referencedModelsParams,
+        groupsOnlyAvailability,
+      ) ?? getSemanticConfigError({ semanticMatchingEnabled, embeddingModel, keywordTierRules });
+    if (blockedReason) {
       setShowValidationErrors(true);
-      toast.fromError(missingTiersError);
-      return;
-    }
-
-    const tierLabelsError = getTierLabelsError(tierLabels);
-    if (tierLabelsError) {
-      setShowValidationErrors(true);
-      toast.fromError(tierLabelsError);
-      return;
-    }
-
-    if (classifierType === "llm" && !classifierLlmConfig?.model) {
-      setShowValidationErrors(true);
-      toast.fromError("Please select a classifier model, or switch back to Heuristic");
-      return;
-    }
-
-    const keywordRulesError = getKeywordTierRulesError(keywordTierRules);
-    if (keywordRulesError) {
-      setShowValidationErrors(true);
-      toast.fromError(keywordRulesError);
-      return;
-    }
-
-    const semanticError = getSemanticConfigError({ semanticMatchingEnabled, embeddingModel, keywordTierRules });
-    if (semanticError) {
-      setShowValidationErrors(true);
-      toast.fromError(semanticError);
-      return;
-    }
-
-    // submitBlockedReason already disables the button for this, but the form's submit handler (wired to
-    // this same function) fires on Enter regardless of the button's disabled state - without this check,
-    // Enter in the name field could still create a router referencing a model that disappeared from
-    // availableModelSet after the tiers were filled in.
-    const referencedModelsError = getReferencedModelsError(referencedModelsParams, groupsOnlyAvailability);
-    if (referencedModelsError) {
-      setShowValidationErrors(true);
-      toast.fromError(referencedModelsError);
+      toast.fromError(blockedReason);
       return;
     }
 

ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.test.ts

@@ -3,6 +3,7 @@ import {
   getPlanModeTierError,
   normalizeClassifierLlmConfig,
   getKeywordTierRulesError,
+  getClassifierModelError,
   getMissingTiersError,
   getSemanticConfigError,
   getTierLabelsError,
@@ -334,21 +335,24 @@ describe("getSemanticConfigError", () => {
 describe("getKeywordTierRulesError", () => {
   it("returns null when every rule carries a keyword", () => {
     expect(
-      getKeywordTierRulesError([
-        { id: "r1", keywords: ["invoice"], tier: "MEDIUM" },
-        { id: "r2", keywords: ["deploy to k8s"], tier: "REASONING" },
-      ]),
+      getKeywordTierRulesError(
+        [
+          { id: "r1", keywords: ["invoice"], tier: "MEDIUM" },
+          { id: "r2", keywords: ["deploy to k8s"], tier: "REASONING" },
+        ],
+        activeTierRows({ tiers }),
+      ),
     ).toBeNull();
   });
 
   it("returns null when there are no rules at all, since the section is optional", () => {
-    expect(getKeywordTierRulesError([])).toBeNull();
+    expect(getKeywordTierRulesError([], activeTierRows({ tiers }))).toBeNull();
   });
 
   // The whole point of the ticket: the semantic toggle is off by default, and an unfilled row
   // used to be discarded silently on an otherwise successful create.
   it("rejects a row left empty while semantic matching is off", () => {
-    expect(getKeywordTierRulesError([{ id: "r1", keywords: [], tier: "COMPLEX" }])).toBe(
+    expect(getKeywordTierRulesError([{ id: "r1", keywords: [], tier: "COMPLEX" }], activeTierRows({ tiers }))).toBe(
       "Add at least one keyword to keyword rule(s): 1",
     );
   });
@@ -357,7 +361,9 @@ describe("getKeywordTierRulesError", () => {
     ["whitespace only", ["   "]],
     ["blank strings, as an unfilled row between filled ones leaves behind", ["", " ", ""]],
   ])("treats %s as empty rather than as a keyword", (_label, keywords) => {
-    expect(getKeywordTierRulesError([{ id: "r1", keywords, tier: "SIMPLE" }])).toMatch(/keyword rule\(s\): 1/);
+    expect(getKeywordTierRulesError([{ id: "r1", keywords, tier: "SIMPLE" }], activeTierRows({ tiers }))).toMatch(
+      /keyword rule\(s\): 1/,
+    );
   });
 
   // Row numbers have to survive rules that are fine, or the message points at the wrong input.
@@ -373,7 +379,9 @@ describe("getKeywordTierRulesError", () => {
   });
 
   it("keeps a keyword whose surrounding whitespace is the only thing trimmed", () => {
-    expect(getKeywordTierRulesError([{ id: "r1", keywords: ["  invoice  "], tier: "MEDIUM" }])).toBeNull();
+    expect(
+      getKeywordTierRulesError([{ id: "r1", keywords: ["  invoice  "], tier: "MEDIUM" }], activeTierRows({ tiers })),
+    ).toBeNull();
   });
 });
 
@@ -674,3 +682,80 @@ describe("buildComplexityRouterConfig tier model params", () => {
     });
   });
 });
+
+describe("getClassifierModelError", () => {
+  it("stays quiet for a heuristic router, which needs no classifier model", () => {
+    expect(getClassifierModelError({ classifier_type: "heuristic" })).toBeNull();
+  });
+
+  it("blocks an LLM classifier with no model, which the router cannot start without", () => {
+    expect(getClassifierModelError({ classifier_type: "llm" })).toBe(
+      "Please select a classifier model, or switch back to Heuristic",
+    );
+  });
+
+  it("stays quiet once a model is chosen", () => {
+    expect(
+      getClassifierModelError({ classifier_type: "llm", classifier_llm_config: { model: "m", timeout_ms: 3000 } }),
+    ).toBeNull();
+  });
+});
+
+describe("getKeywordTierRulesError orphaned tiers", () => {
+  const rows = activeTierRows({ tiers });
+
+  it("accepts a rule naming a tier the router has", () => {
+    expect(getKeywordTierRulesError([{ id: "r1", keywords: ["k"], tier: "COMPLEX" }], rows)).toBeNull();
+  });
+
+  it("names the rule pointing at a tier this router does not have", () => {
+    expect(getKeywordTierRulesError([{ id: "r1", keywords: ["k"], tier: "AUDIT" }], rows)).toBe(
+      "Keyword rule(s) 1 route to a tier this router no longer has",
+    );
+  });
+
+  it("rejects a differently cased tier, because _validate_keyword_rule_tiers matches exactly", () => {
+    expect(getKeywordTierRulesError([{ id: "r1", keywords: ["k"], tier: "complex" }], rows)).toBe(
+      "Keyword rule(s) 1 route to a tier this router no longer has",
+    );
+  });
+
+  it("reports an empty keyword row before an orphaned tier, since that is the nearer problem", () => {
+    expect(getKeywordTierRulesError([{ id: "r1", keywords: [], tier: "AUDIT" }], rows)).toContain(
+      "Add at least one keyword",
+    );
+  });
+});
+
+describe("heuristic_first", () => {
+  const heuristicFirstParams: BuildComplexityRouterConfigParams = {
+    ...baseParams,
+    classifierType: "heuristic_first",
+    heuristicFirstMaxTier: "SIMPLE",
+    classifierLlmConfig: { model: "gpt-4o-mini", timeout_ms: 3000 },
+    classifierContextWindowSize: 5,
+    classifierContextBudgetChars: 4000,
+    classifierFallback: "default_model",
+  };
+
+  it("emits heuristic_first_max_tier", () => {
+    const config = buildComplexityRouterConfig(heuristicFirstParams);
+    expect(config.classifier_type).toBe("heuristic_first");
+    expect(config.heuristic_first_max_tier).toBe("SIMPLE");
+  });
+
+  it("keeps every classifier key the operator set, since heuristic_first still calls the classifier", () => {
+    const config = buildComplexityRouterConfig(heuristicFirstParams);
+    expect(config.classifier_llm_config).toEqual({ model: "gpt-4o-mini", timeout_ms: 3000 });
+    expect(config.classifier_context_window_size).toBe(5);
+    expect(config.classifier_context_budget_chars).toBe(4000);
+    expect(config.classifier_fallback).toBe("default_model");
+  });
+
+  it("omits heuristic_first_max_tier on every other classifier type, which the backend rejects it on", () => {
+    for (const classifierType of ["heuristic", "llm"] as const) {
+      const config = buildComplexityRouterConfig({ ...heuristicFirstParams, classifierType });
+      expect(config.heuristic_first_max_tier).toBeUndefined();
+    }
+  });
+});

ui/litellm-dashboard/src/components/add_model/build_complexity_router_config.ts

@@ -9,6 +9,7 @@ import {
   ClassifierLLMConfig,
   ClassifierType,
   ComplexityTierLabels,
+  ComplexityRouterConfigValue,
   ComplexityTiers,
   DimensionWeights,
   TIER_KEYS,
@@ -17,6 +18,7 @@ import {
   TokenThresholds,
   effectiveTierLabel,
   heuristicScoringRoleFor,
+  usesLlmClassifier,
 } from "./ComplexityRouterConfig";
 
 /**
@@ -85,6 +87,7 @@ export interface BuildComplexityRouterConfigParams {
   classifierContextBudgetChars: number | undefined;
   classifierContextIncludeAssistantTurns: boolean | undefined;
   classifierFallback: ClassifierFallback | undefined;
+  heuristicFirstMaxTier: string | undefined;
   sessionAffinity: boolean;
   deploymentAffinity: boolean;
   customTechnicalKeywords: string[];
@@ -117,6 +120,7 @@ export interface ComplexityRouterConfigPayload {
   classifier_context_per_turn_chars?: number;
   classifier_context_include_assistant_turns?: boolean;
   classifier_fallback?: ClassifierFallback;
+  heuristic_first_max_tier?: string;
   session_affinity: boolean;
   deployment_affinity: boolean;
   custom_technical_keywords?: string[];
@@ -187,12 +191,30 @@ export const getPlanModeTierError = (planModeMinTier: string | undefined, rows:
   return `The plan-mode minimum tier (${floor ? activeTierName(floor) : planModeMinTier}) has no models. Add one or turn the override off.`;
 };
 
-export const getKeywordTierRulesError = (keywordTierRules: KeywordTierRule[]): string | null => {
+// The tier is a free string since #37413, and _validate_keyword_rule_tiers matches it EXACTLY, so a
+// rule naming a tier this router does not have is a raw 400 unless the gate catches it first.
+export const getKeywordTierRulesError = (
+  keywordTierRules: KeywordTierRule[],
+  rows: readonly TierRow[],
+): string | null => {
   const emptyRows = emptyKeywordTierRuleIndexes(keywordTierRules);
-  if (emptyRows.length === 0) return null;
-  return `Add at least one keyword to keyword rule(s): ${emptyRows.map((index) => index + 1).join(", ")}`;
+  if (emptyRows.length > 0)
+    return `Add at least one keyword to keyword rule(s): ${emptyRows.map((index) => index + 1).join(", ")}`;
+  const names = rows.map(activeTierName);
+  const orphaned = keywordTierRules.flatMap((rule, index) => (names.includes(rule.tier) ? [] : [index + 1]));
+  if (orphaned.length === 0) return null;
+  return `Keyword rule(s) ${orphaned.join(", ")} route to a tier this router no longer has`;
 };
 
+// The submit gate and the submit handler both read this, so a disabled button and a refused submit
+// cannot disagree about why.
+export const getClassifierModelError = (
+  config: Pick<ComplexityRouterConfigValue, "classifier_type" | "classifier_llm_config">,
+): string | null =>
+  usesLlmClassifier(config.classifier_type) && !config.classifier_llm_config?.model
+    ? "Please select a classifier model, or switch back to Heuristic"
+    : null;
+
 export const getSemanticConfigError = ({
   semanticMatchingEnabled,
   embeddingModel,
@@ -217,6 +239,7 @@ export const buildComplexityRouterConfig = ({
   classifierContextBudgetChars,
   classifierContextIncludeAssistantTurns,
   classifierFallback,
+  heuristicFirstMaxTier,
   sessionAffinity,
   deploymentAffinity,
   customTechnicalKeywords,
@@ -257,18 +280,21 @@ export const buildComplexityRouterConfig = ({
     ...(planModeMinTier?.trim() && { plan_mode_min_tier: planModeMinTier }),
     ...(cleanedTierLabels && { tier_labels: cleanedTierLabels }),
     classifier_type: classifierType,
-    ...(classifierType === "llm" &&
+    ...(usesLlmClassifier(classifierType) &&
       classifierLlmConfig && { classifier_llm_config: normalizeClassifierLlmConfig(classifierLlmConfig) }),
-    ...(classifierType === "llm" && classifierFallback !== undefined && { classifier_fallback: classifierFallback }),
-    ...(classifierType === "llm" &&
+    ...(usesLlmClassifier(classifierType) &&
+      classifierFallback !== undefined && { classifier_fallback: classifierFallback }),
+    ...(classifierType === "heuristic_first" &&
+      heuristicFirstMaxTier?.trim() && { heuristic_first_max_tier: heuristicFirstMaxTier }),
+    ...(usesLlmClassifier(classifierType) &&
       classifierContextWindowSize !== undefined && {
         classifier_context_window_size: classifierContextWindowSize,
       }),
-    ...(classifierType === "llm" &&
+    ...(usesLlmClassifier(classifierType) &&
       classifierContextBudgetChars !== undefined && {
         classifier_context_budget_chars: classifierContextBudgetChars,
       }),
-    ...(classifierType === "llm" &&
+    ...(usesLlmClassifier(classifierType) &&
       classifierContextIncludeAssistantTurns !== undefined && {
         classifier_context_include_assistant_turns: classifierContextIncludeAssistantTurns,
       }),

ui/litellm-dashboard/src/components/edit_auto_router/build_updated_complexity_router_config.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import { buildUpdatedComplexityRouterConfig, type KeywordMatchingState } from "./edit_auto_router_modal";
+import {
+  MANAGED_COMPLEXITY_ROUTER_KEYS,
+  buildUpdatedComplexityRouterConfig,
+  hydrateComplexityRouterConfig,
+  type KeywordMatchingState,
+} from "./edit_auto_router_modal";
 
 const STORED = {
   tiers: { SIMPLE: ["gpt-4o-mini"], MEDIUM: [], COMPLEX: [], REASONING: [] },
@@ -440,3 +445,48 @@ describe("buildUpdatedComplexityRouterConfig tier model params", () => {
     expect(result).not.toHaveProperty("tier_model_configs");
   });
 });
+
+describe("managed keys survive an untouched open-and-save", () => {
+  // Every managed key is rewritten from form state on save, so one the hydrator forgets is silently
+  // dropped from the saved config. This config sets each managed key to a value that actually
+  // applies, so an untouched open-and-save must return every one of them.
+  const STORED_ALL_MANAGED: Record<string, unknown> = {
+    tiers: { SIMPLE: ["gpt-4o-mini"], MEDIUM: ["gpt-4o"], COMPLEX: ["opus"], REASONING: ["o1"] },
+    tier_model_configs: { REASONING: [{ model_name: "o1", litellm_params: { reasoning_effort: "high" } }] },
+    default_model: "gpt-4o",
+    plan_mode_min_tier: "COMPLEX",
+    tier_labels: { SIMPLE: "Cheap" },
+    classifier_type: "heuristic_first",
+    heuristic_first_max_tier: "SIMPLE",
+    classifier_llm_config: { model: "gpt-4o-mini", timeout_ms: 3000 },
+    classifier_context_window_size: 5,
+    classifier_context_budget_chars: 4000,
+    classifier_context_include_assistant_turns: true,
+    classifier_fallback: "default_model",
+    session_affinity: true,
+    deployment_affinity: false,
+    adaptive: true,
+    adaptive_weights: { quality: 0.4, cost: 0.6 },
+    tier_distance_penalty: 0.25,
+    adaptive_eligible: "all",
+    return_raw_model_name: true,
+    tier_boundaries: { simple_medium: 0.2, medium_complex: 0.4, complex_reasoning: 0.7 },
+    token_thresholds: { simple: 20, complex: 500 },
+    dimension_weights: { tokenCount: 0.1 },
+    reasoning_override_min_score: 0.3,
+  };
+
+  it("carries every managed key through hydrate then save", () => {
+    const hydrated = hydrateComplexityRouterConfig(STORED_ALL_MANAGED, undefined);
+    const saved = buildUpdatedComplexityRouterConfig(STORED_ALL_MANAGED, hydrated);
+
+    const dropped = [...MANAGED_COMPLEXITY_ROUTER_KEYS].filter((key) => saved[key] === undefined);
+    expect(dropped).toEqual([]);
+  });
+
+  it("round-trips the heuristic_first threshold, which save requires and the backend rejects without", () => {
+    const hydrated = hydrateComplexityRouterConfig(STORED_ALL_MANAGED, undefined);
+    expect(hydrated.heuristic_first_max_tier).toBe("SIMPLE");
+    expect(buildUpdatedComplexityRouterConfig(STORED_ALL_MANAGED, hydrated).heuristic_first_max_tier).toBe("SIMPLE");
+  });
+});

ui/litellm-dashboard/src/components/edit_auto_router/edit_auto_router_modal.tsx

@@ -20,6 +20,7 @@ import { isComplexityRouter } from "../add_model/auto_router_strategies";
 import {
   type BuildComplexityRouterConfigParams,
   buildComplexityRouterConfig,
+  getClassifierModelError,
   getKeywordTierRulesError,
   getSemanticConfigError,
   getPlanModeTierError,
@@ -36,6 +37,10 @@ import {
   hydrateTokenThresholds,
 } from "../add_model/heuristic_scoring_knobs";
 import ComplexityRouterConfig, {
+  AdaptiveEligible,
+  AdaptiveRouterWeights,
+  ClassifierLLMConfig,
+  ClassifierType,
   ComplexityRouterConfigValue,
   ComplexityTiers,
   DEFAULT_ADAPTIVE_WEIGHTS,
@@ -64,7 +69,101 @@ interface EditAutoRouterModalProps {
 // Keys this modal rewrites from its own form state on save. Anything absent from this set is
 // carried through untouched from the stored config, so a key only belongs here once the modal
 // actually renders a control that can set it.
-const MANAGED_COMPLEXITY_ROUTER_KEYS = new Set([
+/** The complexity_router_config as it comes back from the proxy, before any hydration. Fields the
+ * hydrators validate themselves stay `unknown`; the ones assigned straight through carry their type. */
+export interface StoredComplexityRouterConfig {
+  tiers?: Partial<Record<keyof ComplexityTiers, unknown>>;
+  tier_model_configs?: unknown;
+  default_model?: string | null;
+  plan_mode_min_tier?: unknown;
+  heuristic_first_max_tier?: unknown;
+  tier_labels?: unknown;
+  classifier_type?: ClassifierType;
+  classifier_llm_config?: ClassifierLLMConfig;
+  classifier_context_window_size?: unknown;
+  classifier_context_budget_chars?: unknown;
+  classifier_context_include_assistant_turns?: unknown;
+  classifier_fallback?: unknown;
+  tier_boundaries?: unknown;
+  token_thresholds?: unknown;
+  dimension_weights?: unknown;
+  reasoning_override_min_score?: unknown;
+  session_affinity?: unknown;
+  deployment_affinity?: unknown;
+  adaptive?: boolean;
+  adaptive_weights?: AdaptiveRouterWeights;
+  tier_distance_penalty?: number;
+  adaptive_eligible?: AdaptiveEligible;
+  return_raw_model_name?: boolean;
+}
+
+/**
+ * The stored complexity_router_config as form state. Every key in MANAGED_COMPLEXITY_ROUTER_KEYS is
+ * rewritten from this state on save, so a key missing here is silently dropped from the saved config.
+ */
+export const hydrateComplexityRouterConfig = (
+  parsedConfig: StoredComplexityRouterConfig,
+  complexityRouterDefaultModel: string | null | undefined,
+): ComplexityRouterConfigValue => {
+  const hydratedTiers: ComplexityTiers = {
+    SIMPLE: normalizeTierModels(parsedConfig.tiers?.SIMPLE),
+    MEDIUM: normalizeTierModels(parsedConfig.tiers?.MEDIUM),
+    COMPLEX: normalizeTierModels(parsedConfig.tiers?.COMPLEX),
+    REASONING: normalizeTierModels(parsedConfig.tiers?.REASONING),
+  };
+
+  return {
+    tiers: hydratedTiers,
+    tier_model_params: hydrateTierModelParams(parsedConfig.tiers, parsedConfig.tier_model_configs),
+    default_model: hydratePinnedDefaultModel(parsedConfig.default_model, complexityRouterDefaultModel, {
+      tiers: hydratedTiers,
+    }),
+    plan_mode_min_tier:
+      typeof parsedConfig.plan_mode_min_tier === "string" && parsedConfig.plan_mode_min_tier.trim() !== ""
+        ? parsedConfig.plan_mode_min_tier
+        : undefined,
+    tier_labels: hydrateTierLabels(parsedConfig.tier_labels),
+    classifier_type: parsedConfig.classifier_type || "heuristic",
+    classifier_llm_config: parsedConfig.classifier_llm_config,
+    classifier_context_window_size:
+      typeof parsedConfig.classifier_context_window_size === "number"
+        ? parsedConfig.classifier_context_window_size
+        : undefined,
+    classifier_context_budget_chars:
+      typeof parsedConfig.classifier_context_budget_chars === "number"
+        ? parsedConfig.classifier_context_budget_chars
+        : undefined,
+    classifier_context_include_assistant_turns:
+      typeof parsedConfig.classifier_context_include_assistant_turns === "boolean"
+        ? parsedConfig.classifier_context_include_assistant_turns
+        : undefined,
+    classifier_fallback:
+      parsedConfig.classifier_fallback === "default_model" || parsedConfig.classifier_fallback === "heuristic"
+        ? parsedConfig.classifier_fallback
+        : undefined,
+    heuristic_first_max_tier:
+      typeof parsedConfig.heuristic_first_max_tier === "string" && parsedConfig.heuristic_first_max_tier.trim() !== ""
+        ? parsedConfig.heuristic_first_max_tier
+        : undefined,
+    tier_boundaries: hydrateTierBoundaries(parsedConfig.tier_boundaries),
+    token_thresholds: hydrateTokenThresholds(parsedConfig.token_thresholds),
+    dimension_weights: hydrateDimensionWeights(parsedConfig.dimension_weights),
+    reasoning_override_min_score: hydrateReasoningOverrideMinScore(parsedConfig.reasoning_override_min_score),
+    session_affinity:
+      typeof parsedConfig.session_affinity === "boolean" ? parsedConfig.session_affinity : DEFAULT_SESSION_AFFINITY,
+    deployment_affinity:
+      typeof parsedConfig.deployment_affinity === "boolean"
+        ? parsedConfig.deployment_affinity
+        : DEFAULT_DEPLOYMENT_AFFINITY,
+    adaptive: parsedConfig.adaptive || false,
+    adaptive_weights: parsedConfig.adaptive_weights,
+    tier_distance_penalty: parsedConfig.tier_distance_penalty,
+    adaptive_eligible: parsedConfig.adaptive_eligible || "all",
+    return_raw_model_name: parsedConfig.return_raw_model_name || false,
+  };
+};
+
+export const MANAGED_COMPLEXITY_ROUTER_KEYS = new Set([
   "tiers",
   "tier_model_configs",
   "default_model",
@@ -76,6 +175,7 @@ const MANAGED_COMPLEXITY_ROUTER_KEYS = new Set([
   "classifier_context_budget_chars",
   "classifier_context_include_assistant_turns",
   "classifier_fallback",
+  "heuristic_first_max_tier",
   "session_affinity",
   "deployment_affinity",
   "adaptive",
@@ -149,6 +249,7 @@ export const buildUpdatedComplexityRouterConfig = (
     tiers: value.tiers,
     defaultModel: value.default_model,
     planModeMinTier: value.plan_mode_min_tier,
+    heuristicFirstMaxTier: value.heuristic_first_max_tier,
     tierLabels: value.tier_labels,
     classifierType: value.classifier_type,
     classifierLlmConfig: value.classifier_llm_config,
@@ -268,7 +369,8 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
         : null) ??
       getTierLabelsError(complexityRouterConfig.tier_labels) ??
       getPlanModeTierError(complexityRouterConfig.plan_mode_min_tier, activeTierRows(complexityRouterConfig)) ??
-      getKeywordTierRulesError(keywordTierRules);
+      getKeywordTierRulesError(keywordTierRules, activeTierRows(complexityRouterConfig)) ??
+      getClassifierModelError(complexityRouterConfig);
 
   useEffect(() => {
     if (isVisible && modelData) {
@@ -312,62 +414,10 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
           parsedConfig = JSON.parse(parsedConfig);
         }
 
-        const hydratedTiers: ComplexityTiers = {
-          SIMPLE: normalizeTierModels(parsedConfig.tiers?.SIMPLE),
-          MEDIUM: normalizeTierModels(parsedConfig.tiers?.MEDIUM),
-          COMPLEX: normalizeTierModels(parsedConfig.tiers?.COMPLEX),
-          REASONING: normalizeTierModels(parsedConfig.tiers?.REASONING),
-        };
-
-        const hydratedComplexityRouterConfig: ComplexityRouterConfigValue = {
-          tiers: hydratedTiers,
-          tier_model_params: hydrateTierModelParams(parsedConfig.tiers, parsedConfig.tier_model_configs),
-          default_model: hydratePinnedDefaultModel(
-            parsedConfig.default_model,
-            modelData.litellm_params?.complexity_router_default_model,
-            { tiers: hydratedTiers },
-          ),
-          plan_mode_min_tier:
-            typeof parsedConfig.plan_mode_min_tier === "string" && parsedConfig.plan_mode_min_tier.trim() !== ""
-              ? parsedConfig.plan_mode_min_tier
-              : undefined,
-          tier_labels: hydrateTierLabels(parsedConfig.tier_labels),
-          classifier_type: parsedConfig.classifier_type || "heuristic",
-          classifier_llm_config: parsedConfig.classifier_llm_config,
-          classifier_context_window_size:
-            typeof parsedConfig.classifier_context_window_size === "number"
-              ? parsedConfig.classifier_context_window_size
-              : undefined,
-          classifier_context_budget_chars:
-            typeof parsedConfig.classifier_context_budget_chars === "number"
-              ? parsedConfig.classifier_context_budget_chars
-              : undefined,
-          classifier_context_include_assistant_turns:
-            typeof parsedConfig.classifier_context_include_assistant_turns === "boolean"
-              ? parsedConfig.classifier_context_include_assistant_turns
-              : undefined,
-          classifier_fallback:
-            parsedConfig.classifier_fallback === "default_model" || parsedConfig.classifier_fallback === "heuristic"
-              ? parsedConfig.classifier_fallback
-              : undefined,
-          tier_boundaries: hydrateTierBoundaries(parsedConfig.tier_boundaries),
-          token_thresholds: hydrateTokenThresholds(parsedConfig.token_thresholds),
-          dimension_weights: hydrateDimensionWeights(parsedConfig.dimension_weights),
-          reasoning_override_min_score: hydrateReasoningOverrideMinScore(parsedConfig.reasoning_override_min_score),
-          session_affinity:
-            typeof parsedConfig.session_affinity === "boolean"
-              ? parsedConfig.session_affinity
-              : DEFAULT_SESSION_AFFINITY,
-          deployment_affinity:
-            typeof parsedConfig.deployment_affinity === "boolean"
-              ? parsedConfig.deployment_affinity
-              : DEFAULT_DEPLOYMENT_AFFINITY,
-          adaptive: parsedConfig.adaptive || false,
-          adaptive_weights: parsedConfig.adaptive_weights,
-          tier_distance_penalty: parsedConfig.tier_distance_penalty,
-          adaptive_eligible: parsedConfig.adaptive_eligible || "all",
-          return_raw_model_name: parsedConfig.return_raw_model_name || false,
-        };
+        const hydratedComplexityRouterConfig = hydrateComplexityRouterConfig(
+          parsedConfig,
+          modelData.litellm_params?.complexity_router_default_model,
+        );
         setComplexityRouterConfig(hydratedComplexityRouterConfig);
         setCustomTechnicalKeywords(
           Array.isArray(parsedConfig.custom_technical_keywords) ? parsedConfig.custom_technical_keywords : [],
@@ -428,16 +478,17 @@ const EditAutoRouterModal: React.FC<EditAutoRouterModalProps> = ({
         toast.fromError("Please select at least one model for a complexity tier");
         return;
       }
-      if (classifier_type === "llm" && !classifier_llm_config?.model) {
+      const classifierError = getClassifierModelError(complexityRouterConfig);
+      if (classifierError) {
         setShowValidationErrors(true);
-        toast.fromError("Please select a classifier model, or switch back to Heuristic");
+        toast.fromError(classifierError);
         return;
       }
       // Same guards the create form applies (add_auto_router_tab.tsx). The backend rejects a
       // keyword rule with no keyword, and semantic_keyword_matching without an embedding model
       // or keyword rules (complexity_router/config.py), so without these a save fails as a raw
       // 400 instead of an inline message.
-      const keywordRulesError = getKeywordTierRulesError(keywordTierRules);
+      const keywordRulesError = getKeywordTierRulesError(keywordTierRules, activeTierRows(complexityRouterConfig));
       if (keywordRulesError) {
         setShowValidationErrors(true);
         toast.fromError(keywordRulesError);

ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx

@@ -13,6 +13,9 @@ export interface Team {
   tpm_limit: number | null;
   rpm_limit: number | null;
   organization_id: string;
+  metadata?: Record<string, unknown> | null;
+  budget_reset_at?: string | null;
+  blocked?: boolean;
   created_at: string;
   updated_at?: string | null;
   keys: KeyResponse[];

ui/litellm-dashboard/src/components/view_logs/LogDetailsDrawer/RoutingDecisionCard.tsx

@@ -72,6 +72,20 @@ function describeReasoningOverride(tierLabel: string | undefined, floor: number
   return `Heuristic, ${tierLabel ?? "REASONING"} override (2 or more reasoning markers, score of at least ${stated})`;
 }
 
+const CONSTANT_CAUSE_LABELS: Record<string, string> = {
+  heuristic_scorer: "Heuristic scorer",
+  heuristic_first_short_circuit: "Heuristic scorer, classifier skipped",
+  classifier_plugin: "Custom classifier plugin",
+  semantic_keyword_match: "Semantic keyword match",
+  session_affinity_pin: "Pinned to session",
+  session_affinity_escalation: "Escalated from session pin",
+  quality_tier: "Quality tier mapping",
+  bandit: "Adaptive bandit",
+  default_fallback: "Default model, no route matched",
+  classifier_fallback: "Fallback tier, LLM classifier failed",
+  default_model_fallback: "Default model, LLM classifier failed",
+};
+
 function describeCause(decision: RoutingDecision): string {
   const {
     cause,
@@ -81,35 +95,19 @@ function describeCause(decision: RoutingDecision): string {
     reasoning_override_min_score: overrideFloor,
   } = decision;
 
+  const constant = cause ? CONSTANT_CAUSE_LABELS[cause] : undefined;
+  if (constant) return constant;
+
   switch (cause) {
-    case "heuristic_scorer":
-      return "Heuristic scorer";
     case "reasoning_override":
       return describeReasoningOverride(tierLabel, overrideFloor);
     case "llm_classifier":
       return classifierModel ? `LLM classifier (${classifierModel})` : "LLM classifier";
     case "literal_keyword_match":
-      return matchedKeyword ? `Keyword match: "${matchedKeyword}"` : "Keyword match";
-    case "semantic_keyword_match":
-      return "Semantic keyword match";
-    case "plan_mode":
-      return describePlanModeFloor(matchedKeyword);
-    case "session_affinity_pin":
-      return "Pinned to session";
-    case "session_affinity_escalation":
-      return "Escalated from session pin";
-    case "quality_tier":
-      return "Quality tier mapping";
     case "keyword":
       return matchedKeyword ? `Keyword match: "${matchedKeyword}"` : "Keyword match";
-    case "bandit":
-      return "Adaptive bandit";
-    case "default_fallback":
-      return "Default model, no route matched";
-    case "classifier_fallback":
-      return "Fallback tier, LLM classifier failed";
-    case "default_model_fallback":
-      return "Default model, LLM classifier failed";
+    case "plan_mode":
+      return describePlanModeFloor(matchedKeyword);
     default:
       return cause ?? "Unknown";
   }

ui/litellm-dashboard/src/lib/autorouter_presets.ts

@@ -8,6 +8,7 @@ import {
   ClassifierLLMConfig,
   DEFAULT_SESSION_AFFINITY,
   DEFAULT_DEPLOYMENT_AFFINITY,
+  usesLlmClassifier,
 } from "@/components/add_model/ComplexityRouterConfig";
 import { KeywordTierRule } from "@/components/add_model/KeywordTierRules";
 import { hydrateKeywordTierRules } from "@/components/add_model/complexity_router_keywords";
@@ -177,7 +178,7 @@ export const getMissingModelsInPreset = (preset: AutoRouterPreset, availability:
 // Checks the config actually being built (whether it arrived via a preset prefill or was typed by
 // hand - the two are indistinguishable once the caller has started editing), not a preset's
 // original bundled model list. Only counts classifier_llm_config/embedding_model as referenced
-// when buildComplexityRouterConfig would actually emit them (classifierType === "llm",
+// when buildComplexityRouterConfig would actually emit them (usesLlmClassifier(classifierType),
 // semanticMatchingEnabled) - otherwise a dormant selection left over from a toggle no longer in
 // effect would block submit for a model that was never going to be submitted.
 export const getReferencedModelsError = (
@@ -195,7 +196,7 @@ export const getReferencedModelsError = (
     {
       tiers: params.tiers,
       default_model: params.defaultModel,
-      classifier_llm_config: params.classifierType === "llm" ? params.classifierLlmConfig : undefined,
+      classifier_llm_config: usesLlmClassifier(params.classifierType) ? params.classifierLlmConfig : undefined,
       embedding_model: params.semanticMatchingEnabled ? params.embeddingModel : undefined,
     },
     availability,

ui/litellm-dashboard/src/lib/http/schema.d.ts

@@ -13176,6 +13176,8 @@ export interface paths {
          * @description [DEPRECATED] This endpoint is not paginated and can cause performance issues.
          *     Please use `/spend/logs/v2` instead for paginated access to spend logs.
          *
+         *     Row results are capped at 10,000 most recent entries per response.
+         *
          *     View all spend logs, if request_id is provided, only logs for that request_id will be returned
          *
          *     When start_date and end_date are provided:
@@ -32586,12 +32588,12 @@ export interface components {
             classifier_context_window_size: number;
             /**
              * Classifier Fallback
-             * @description What classifies the request when the LLM classifier errors, times out, or returns an unparseable response. 'heuristic' runs the local complexity scorer, which is right when the classifier grades complexity too. 'default_model' skips scoring and routes to default_model, which is what a classifier on some other taxonomy wants: a prompt that grades data sensitivity has no use for a complexity score, and scoring one produces a tier unrelated to what the operator configured. Requires default_model when set to 'default_model'. Only applies when classifier_type is 'llm' or 'custom'.
+             * @description What classifies the request when the LLM classifier errors, times out, or returns an unparseable response. 'heuristic' runs the local complexity scorer, which is right when the classifier grades complexity too. 'default_model' skips scoring and routes to default_model, which is what a classifier on some other taxonomy wants: a prompt that grades data sensitivity has no use for a complexity score, and scoring one produces a tier unrelated to what the operator configured. Requires default_model when set to 'default_model'. Only applies when classifier_type is 'llm', 'custom', or 'heuristic_first'.
              * @default heuristic
              * @enum {string}
              */
             classifier_fallback: "heuristic" | "default_model";
-            /** @description Configuration for the LLM classifier; required when classifier_type is 'llm' */
+            /** @description Configuration for the LLM classifier; required when classifier_type is 'llm' or 'heuristic_first' */
             classifier_llm_config?: components["schemas"]["ClassifierLLMConfig"] | null;
             /**
              * Classifier Plugin
@@ -32606,11 +32608,11 @@ export interface components {
             classifier_plugin_timeout_ms: number;
             /**
              * Classifier Type
-             * @description Classification strategy: local regex/keyword scoring, an LLM call, or a custom classifier plugin
+             * @description Classification strategy: local regex/keyword scoring, an LLM call, a custom classifier plugin, or 'heuristic_first', which scores locally and only pays for the LLM classifier when the local scorer does not confidently land a cheap tier
              * @default heuristic
              * @enum {string}
              */
-            classifier_type: "heuristic" | "llm" | "custom";
+            classifier_type: "heuristic" | "llm" | "custom" | "heuristic_first";
             /**
              * Code Keywords
              * @description Keywords indicating code-related content
@@ -32654,6 +32656,11 @@ export interface components {
              * @description Tier routed to when the LLM classifier fails (timeout, provider error, or an unparseable reply). Required with tier_definitions and must name a defined tier; the heuristic scorer cannot produce custom tiers, so this replaces the heuristic fallback for custom tier sets.
              */
             fallback_tier?: string | null;
+            /**
+             * Heuristic First Max Tier
+             * @description The highest tier the local scorer may decide on its own; required when classifier_type is 'heuristic_first' and rejected otherwise. A request whose heuristic tier is at or below this one skips the LLM classifier and routes straight to that heuristic tier, so the classifier call is only paid for on traffic the scorer could not place cheaply. The scorer must also have produced at least one signal: a prompt where no dimension fired scores 0.0 and would otherwise land SIMPLE by default rather than by evidence, which is how a chained router would silently send unclassified traffic to the cheapest model. Names a built-in tier, and may not name the highest one, since that would make the LLM classifier unreachable.
+             */
+            heuristic_first_max_tier?: string | null;
             /**
              * Keyword Tier Rules
              * @description Rules that force a specific tier when their keywords match the prompt
@@ -33713,7 +33720,7 @@ export interface components {
              * Cause
              * @enum {string}
              */
-            cause?: "heuristic_scorer" | "reasoning_override" | "llm_classifier" | "classifier_plugin" | "classifier_fallback" | "default_model_fallback" | "literal_keyword_match" | "semantic_keyword_match" | "plan_mode" | "session_affinity_pin" | "session_affinity_escalation" | "default_fallback" | "keyword" | "quality_tier" | "bandit";
+            cause?: "heuristic_scorer" | "reasoning_override" | "llm_classifier" | "heuristic_first_short_circuit" | "classifier_plugin" | "classifier_fallback" | "default_model_fallback" | "literal_keyword_match" | "semantic_keyword_match" | "plan_mode" | "session_affinity_pin" | "session_affinity_escalation" | "default_fallback" | "keyword" | "quality_tier" | "bandit";
             /** Classifier Cost */
             classifier_cost?: number;
             /** Classifier Model */