From 99ef233a69b6fef335a8b8177de6dbd4b77aa100 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Thu, 15 Jan 2026 13:30:43 +0530 Subject: [PATCH 001/511] fix: Preserved nullable object fields by carrying schema properties --- litellm/llms/vertex_ai/common_utils.py | 18 ++++++- .../test_amazing_vertex_completion.py | 54 +++++++++++++++++++ 2 files changed, 70 insertions(+), 2 deletions(-) diff --git a/litellm/llms/vertex_ai/common_utils.py b/litellm/llms/vertex_ai/common_utils.py index 1864ef734c0..63decfea854 100644 --- a/litellm/llms/vertex_ai/common_utils.py +++ b/litellm/llms/vertex_ai/common_utils.py @@ -1,4 +1,5 @@ import re +from copy import deepcopy from enum import Enum from typing import Any, Dict, List, Literal, Optional, Set, Tuple, Union, get_type_hints @@ -617,7 +618,7 @@ def convert_anyof_null_to_nullable(schema, depth=0): if anyof is not None: contains_null = False for atype in anyof: - if atype == {"type": "null"}: + if isinstance(atype, dict) and atype.get("type") == "null": # remove null type anyof.remove(atype) contains_null = True @@ -735,7 +736,20 @@ def _convert_schema_types(schema, depth=0): type_val = schema["type"] if isinstance(type_val, list) and len(type_val) > 1: # Convert ["string", "number"] -> {"anyOf": [{"type": "STRING"}, {"type": "NUMBER"}]} - schema["anyOf"] = [{"type": t} for t in type_val if isinstance(t, str)] + # Preserve other schema fields by copying them into each non-null anyOf item. + base_schema = {k: v for k, v in schema.items() if k not in {"type", "anyOf"}} + any_of: List[Dict[str, Any]] = [] + for t in type_val: + if not isinstance(t, str): + continue + if t == "null": + # Keep null entry minimal so we can strip it later. + any_of.append({"type": "null"}) + continue + item_schema = deepcopy(base_schema) + item_schema["type"] = t + any_of.append(item_schema) + schema["anyOf"] = any_of schema.pop("type") elif isinstance(type_val, list) and len(type_val) == 1: schema["type"] = type_val[0] diff --git a/tests/local_testing/test_amazing_vertex_completion.py b/tests/local_testing/test_amazing_vertex_completion.py index 0373f5f4356..745c90201f3 100644 --- a/tests/local_testing/test_amazing_vertex_completion.py +++ b/tests/local_testing/test_amazing_vertex_completion.py @@ -3598,6 +3598,60 @@ def test_vertex_schema_test(): print(response) +def test_gemini_nullable_object_tool_schema_httpx(): + """ + Ensure nullable object tool params preserve nested properties in Vertex schema conversion. + """ + load_vertex_ai_credentials() + litellm._turn_on_debug() + + + tools = [{ + "type": "function", + "strict": True, + "function": { + "name": "create_support_ticket", + "description": "Create a paid user support ticket", + "parameters": { + "type": "object", + "additionalProperties": False, + "required": ["ticket_id", "customer_context"], + "properties": { + "ticket_id": { + "type": "string", + "description": "Unique identifier for the support ticket" + }, + "customer_context": { + "type": ["object", "null"], + "description": "Context about the paid customer, if available", + "additionalProperties": False, + "required": ["user_id", "plan"], + "properties": { + "user_id": { + "type": "string", + "description": "Internal user identifier" + }, + "plan": { + "type": "string", + "description": "Subscription plan name (e.g. pro, enterprise)" + } + } + } + } + } + } + }] + + response = litellm.completion( + model="vertex_ai/gemini-2.5-flash", + messages=[{"role": "user", "content": "call the tool"}], + tools=tools, + tool_choice="required", + ) + + print(response) + + def test_vertex_ai_response_id(): """Test that litellm preserves the response ID from Vertex AI's API for non-streaming responses""" from litellm.llms.custom_httpx.http_handler import HTTPHandler From 52519c26814b260e20e8c55de54ee548ddc5ad70 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Fri, 16 Jan 2026 18:09:15 +0530 Subject: [PATCH 002/511] Fix: _convert_schema_types --- litellm/llms/vertex_ai/common_utils.py | 34 +++++++++++++++++++++----- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/litellm/llms/vertex_ai/common_utils.py b/litellm/llms/vertex_ai/common_utils.py index 63decfea854..e7d73e421a8 100644 --- a/litellm/llms/vertex_ai/common_utils.py +++ b/litellm/llms/vertex_ai/common_utils.py @@ -735,9 +735,15 @@ def _convert_schema_types(schema, depth=0): if "type" in schema: type_val = schema["type"] if isinstance(type_val, list) and len(type_val) > 1: - # Convert ["string", "number"] -> {"anyOf": [{"type": "STRING"}, {"type": "NUMBER"}]} - # Preserve other schema fields by copying them into each non-null anyOf item. - base_schema = {k: v for k, v in schema.items() if k not in {"type", "anyOf"}} + # Convert type arrays to anyOf format + # For object types, we need to move object-specific fields into the anyOf item + # For primitive types, we only include the type field + + # Fields that should stay at parent level (metadata) + metadata_fields = {"description", "title", "default", "examples"} + # Fields that are specific to object/array types and should move into anyOf + type_specific_fields = {"properties", "required", "additionalProperties", "items", "minItems", "maxItems", "minProperties", "maxProperties"} + any_of: List[Dict[str, Any]] = [] for t in type_val: if not isinstance(t, str): @@ -746,9 +752,25 @@ def _convert_schema_types(schema, depth=0): # Keep null entry minimal so we can strip it later. any_of.append({"type": "null"}) continue - item_schema = deepcopy(base_schema) - item_schema["type"] = t - any_of.append(item_schema) + + # For object/array types, include type-specific fields + if t in ("object", "array"): + item_schema = {"type": t} + # Move type-specific fields into this anyOf item + for field in type_specific_fields: + if field in schema: + item_schema[field] = deepcopy(schema[field]) + any_of.append(item_schema) + else: + # For primitive types, only include the type + any_of.append({"type": t}) + + # Remove type-specific fields from parent if we moved them into anyOf + has_object_or_array = any(t in ("object", "array") for t in type_val if isinstance(t, str)) + if has_object_or_array: + for field in type_specific_fields: + schema.pop(field, None) + schema["anyOf"] = any_of schema.pop("type") elif isinstance(type_val, list) and len(type_val) == 1: From f28340a39d95dd736578eea8b1b390688932bc9e Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Fri, 16 Jan 2026 18:15:18 +0530 Subject: [PATCH 003/511] Fix all mypy issues --- litellm/llms/vertex_ai/common_utils.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/litellm/llms/vertex_ai/common_utils.py b/litellm/llms/vertex_ai/common_utils.py index e7d73e421a8..54a6ba3ad7a 100644 --- a/litellm/llms/vertex_ai/common_utils.py +++ b/litellm/llms/vertex_ai/common_utils.py @@ -735,12 +735,7 @@ def _convert_schema_types(schema, depth=0): if "type" in schema: type_val = schema["type"] if isinstance(type_val, list) and len(type_val) > 1: - # Convert type arrays to anyOf format - # For object types, we need to move object-specific fields into the anyOf item - # For primitive types, we only include the type field - - # Fields that should stay at parent level (metadata) - metadata_fields = {"description", "title", "default", "examples"} + # Convert type arrays to anyOf format # Fields that are specific to object/array types and should move into anyOf type_specific_fields = {"properties", "required", "additionalProperties", "items", "minItems", "maxItems", "minProperties", "maxProperties"} From ac5c5ee302729a9833277e99b74afbef7948b51e Mon Sep 17 00:00:00 2001 From: Quentin Machu Date: Mon, 26 Jan 2026 17:42:56 -0500 Subject: [PATCH 004/511] fix: Search tools not found when using per-request routers **Root Cause:** When API keys or teams have router_settings configured, the proxy creates per-request Router instances from user_config. These new routers were missing search_tools from the main router, causing "search tool not found" errors despite search_tools being configured. **The Fix:** 1. **common_request_processing.py (lines 554-556):** Pass search_tools from main router to user_config so per-request routers inherit them 2. **proxy_server.py (line 3171):** Remove `if len(_model_list) > 0` check to allow router creation with empty model list (needed for search-tools-only use case) 3. **proxy_server.py (line 746):** Remove redundant search_tools loading code (already handled by _init_search_tools_in_db() called during startup) --- litellm/proxy/common_request_processing.py | 7 ++++++- litellm/proxy/proxy_server.py | 23 +++++++++++----------- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/litellm/proxy/common_request_processing.py b/litellm/proxy/common_request_processing.py index 0d3e61b75c7..4f0c59474f1 100644 --- a/litellm/proxy/common_request_processing.py +++ b/litellm/proxy/common_request_processing.py @@ -547,9 +547,14 @@ class ProxyBaseLLMRequestProcessing: # Get model_list from current router model_list = llm_router.get_model_list() if model_list is not None: - # Create user_config with model_list and router_settings + # Create user_config with model_list, search_tools, and router_settings # This creates a per-request router with the hierarchical settings user_config = {"model_list": model_list, **router_settings} + + # Include search_tools from main router so per-request router has them + if hasattr(llm_router, "search_tools") and llm_router.search_tools: + user_config["search_tools"] = llm_router.search_tools + self.data["user_config"] = user_config if "messages" in self.data and self.data["messages"]: diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index 16cdd9da64b..056367243f9 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -3173,17 +3173,18 @@ class ProxyConfig: _model_list: list = self.decrypt_model_list_from_db( new_models=models_list ) - if len(_model_list) > 0: - verbose_proxy_logger.debug(f"_model_list: {_model_list}") - llm_router = litellm.Router( - model_list=_model_list, - router_general_settings=RouterGeneralSettings( - async_only_mode=True # only init async clients - ), - search_tools=search_tools, - ignore_invalid_deployments=True, - ) - verbose_proxy_logger.debug(f"updated llm_router: {llm_router}") + # Create router even with empty model list to support search_tools + # Router can function with model_list=[] and only search_tools + verbose_proxy_logger.debug(f"_model_list: {_model_list}") + llm_router = litellm.Router( + model_list=_model_list, + router_general_settings=RouterGeneralSettings( + async_only_mode=True # only init async clients + ), + search_tools=search_tools, + ignore_invalid_deployments=True, + ) + verbose_proxy_logger.debug(f"updated llm_router: {llm_router}") else: verbose_proxy_logger.debug(f"len new_models: {len(models_list)}") ## DELETE MODEL LOGIC From d57d1e67a36b31863d63838cfd1256c97aeeec3d Mon Sep 17 00:00:00 2001 From: naaa760 Date: Sat, 31 Jan 2026 13:39:25 +0530 Subject: [PATCH 005/511] fix: allow Management keys to access user/daily/activity and team/daily/activity --- litellm/proxy/_types.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index bf99347ef6e..d64f036fa7a 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -511,6 +511,8 @@ class LiteLLMRoutes(enum.Enum): "/user/delete", "/user/info", "/user/list", + "/user/daily/activity", + "/user/daily/activity/aggregated", # team "/team/new", "/team/update", @@ -523,6 +525,7 @@ class LiteLLMRoutes(enum.Enum): "/team/available", "/team/permissions_list", "/team/permissions_update", + "/team/daily/activity", # model "/model/new", "/model/update", From a9eae5937fb58a53047e581d4950b10b956286ce Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Sat, 31 Jan 2026 16:04:52 -0800 Subject: [PATCH 006/511] Override router settings --- litellm/proxy/common_request_processing.py | 16 +-- litellm/proxy/route_llm_request.py | 35 +++-- litellm/router.py | 11 +- .../proxy/test_common_request_processing.py | 34 +++-- .../proxy/test_route_llm_request.py | 131 ++++++++++++------ 5 files changed, 144 insertions(+), 83 deletions(-) diff --git a/litellm/proxy/common_request_processing.py b/litellm/proxy/common_request_processing.py index b69f175e5d2..ee38d56c855 100644 --- a/litellm/proxy/common_request_processing.py +++ b/litellm/proxy/common_request_processing.py @@ -626,20 +626,10 @@ class ProxyBaseLLMRequestProcessing: ) # If router_settings found (from key, team, or global), apply them - # This ensures key/team settings override global settings + # Pass settings as per-request overrides instead of creating a new Router + # This avoids expensive Router instantiation on each request if router_settings is not None and router_settings: - # Get model_list from current router - model_list = llm_router.get_model_list() - if model_list is not None: - # Create user_config with model_list, search_tools, and router_settings - # This creates a per-request router with the hierarchical settings - user_config = {"model_list": model_list, **router_settings} - - # Include search_tools from main router so per-request router has them - if hasattr(llm_router, "search_tools") and llm_router.search_tools: - user_config["search_tools"] = llm_router.search_tools - - self.data["user_config"] = user_config + self.data["router_settings_override"] = router_settings if "messages" in self.data and self.data["messages"]: logging_obj.update_messages(self.data["messages"]) diff --git a/litellm/proxy/route_llm_request.py b/litellm/proxy/route_llm_request.py index c6a93164d49..e2749eb8187 100644 --- a/litellm/proxy/route_llm_request.py +++ b/litellm/proxy/route_llm_request.py @@ -197,18 +197,33 @@ async def route_request( models = [model.strip() for model in data.pop("model").split(",")] return llm_router.abatch_completion(models=models, **data) - elif "user_config" in data: - router_config = data.pop("user_config") + elif "router_settings_override" in data: + # Apply per-request router settings overrides from key/team config + # Instead of creating a new Router (expensive), merge settings into kwargs + # The Router already supports per-request overrides for these settings + override_settings = data.pop("router_settings_override") - # Filter router_config to only include valid Router.__init__ arguments - # This prevents TypeError when invalid parameters are stored in the database - valid_args = litellm.Router.get_valid_args() - filtered_config = {k: v for k, v in router_config.items() if k in valid_args} + # Settings that the Router accepts as per-request kwargs + # These override the global router settings for this specific request + per_request_settings = [ + "fallbacks", + "context_window_fallbacks", + "content_policy_fallbacks", + "num_retries", + "timeout", + "model_group_retry_policy", + ] - user_router = litellm.Router(**filtered_config) - ret_val = getattr(user_router, f"{route_type}")(**data) - user_router.discard() - return ret_val + # Merge override settings into data (only if not already set in request) + for key in per_request_settings: + if key in override_settings and key not in data: + data[key] = override_settings[key] + + # Use main router with overridden kwargs + if llm_router is not None: + return getattr(llm_router, f"{route_type}")(**data) + else: + return getattr(litellm, f"{route_type}")(**data) elif llm_router is not None: # Skip model-based routing for container operations if route_type in [ diff --git a/litellm/router.py b/litellm/router.py index 6c191c8ab03..ed480d6468a 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -4880,6 +4880,10 @@ class Router: content_policy_fallbacks = kwargs.pop( "content_policy_fallbacks", self.content_policy_fallbacks ) + # Support per-request model_group_retry_policy override (from key/team settings) + model_group_retry_policy = kwargs.pop( + "model_group_retry_policy", self.model_group_retry_policy + ) model_group: Optional[str] = kwargs.get("model") num_retries = kwargs.pop("num_retries") @@ -4928,7 +4932,7 @@ class Router: _retry_policy_applies = False if ( self.retry_policy is not None - or self.model_group_retry_policy is not None + or model_group_retry_policy is not None ): # get num_retries from retry policy # Use the model_group captured at the start of the function, or get it from metadata @@ -4936,9 +4940,12 @@ class Router: _model_group_for_retry_policy = ( model_group or _metadata.get("model_group") or kwargs.get("model") ) - _retry_policy_retries = self.get_num_retries_from_retry_policy( + # Use per-request model_group_retry_policy if provided, otherwise use self + _retry_policy_retries = _get_num_retries_from_retry_policy( exception=original_exception, model_group=_model_group_for_retry_policy, + model_group_retry_policy=model_group_retry_policy, + retry_policy=self.retry_policy, ) if _retry_policy_retries is not None: num_retries = _retry_policy_retries diff --git a/tests/test_litellm/proxy/test_common_request_processing.py b/tests/test_litellm/proxy/test_common_request_processing.py index 6edcdab15c0..d2abe80977a 100644 --- a/tests/test_litellm/proxy/test_common_request_processing.py +++ b/tests/test_litellm/proxy/test_common_request_processing.py @@ -78,9 +78,16 @@ class TestProxyBaseLLMRequestProcessing: assert data_passed["litellm_call_id"] == returned_data["litellm_call_id"] @pytest.mark.asyncio - async def test_should_apply_hierarchical_router_settings_to_user_config( + async def test_should_apply_hierarchical_router_settings_as_override( self, monkeypatch ): + """ + Test that hierarchical router settings are stored as router_settings_override + instead of creating a full user_config with model_list. + + This approach avoids expensive per-request Router instantiation by passing + settings as kwargs overrides to the main router. + """ processing_obj = ProxyBaseLLMRequestProcessing(data={}) mock_request = MagicMock(spec=Request) mock_request.headers = {} @@ -117,12 +124,7 @@ class TestProxyBaseLLMRequestProcessing: return_value=mock_router_settings ) - mock_model_list = [ - {"model_name": "gpt-3.5-turbo", "litellm_params": {"model": "gpt-3.5-turbo"}}, - {"model_name": "gpt-4", "litellm_params": {"model": "gpt-4"}}, - ] mock_llm_router = MagicMock() - mock_llm_router.get_model_list = MagicMock(return_value=mock_model_list) mock_prisma_client = MagicMock() monkeypatch.setattr( @@ -146,14 +148,20 @@ class TestProxyBaseLLMRequestProcessing: user_api_key_dict=mock_user_api_key_dict, prisma_client=mock_prisma_client, ) - mock_llm_router.get_model_list.assert_called_once() + # get_model_list should NOT be called - we no longer copy model list for per-request routers + mock_llm_router.get_model_list.assert_not_called() - assert "user_config" in returned_data - user_config = returned_data["user_config"] - assert user_config["model_list"] == mock_model_list - assert user_config["routing_strategy"] == "least-busy" - assert user_config["timeout"] == 30.0 - assert user_config["num_retries"] == 3 + # Settings should be stored as router_settings_override (not user_config) + # This allows passing them as kwargs to the main router instead of creating a new one + assert "router_settings_override" in returned_data + assert "user_config" not in returned_data + + router_settings_override = returned_data["router_settings_override"] + assert router_settings_override["routing_strategy"] == "least-busy" + assert router_settings_override["timeout"] == 30.0 + assert router_settings_override["num_retries"] == 3 + # model_list should NOT be in the override settings + assert "model_list" not in router_settings_override @pytest.mark.asyncio async def test_stream_timeout_header_processing(self): diff --git a/tests/test_litellm/proxy/test_route_llm_request.py b/tests/test_litellm/proxy/test_route_llm_request.py index 90eace63714..1283d2ccbe7 100644 --- a/tests/test_litellm/proxy/test_route_llm_request.py +++ b/tests/test_litellm/proxy/test_route_llm_request.py @@ -137,62 +137,103 @@ async def test_route_request_no_model_required_with_router_settings_and_no_route @pytest.mark.asyncio -async def test_route_request_with_invalid_router_params(): +async def test_route_request_with_router_settings_override(): """ - Test that route_request filters out invalid Router init params from 'user_config'. - This covers the fix for https://github.com/BerriAI/litellm/issues/19693 + Test that route_request handles router_settings_override by merging settings into kwargs + instead of creating a new Router (which is expensive and was the old behavior). """ - import litellm - from litellm.router import Router - from unittest.mock import AsyncMock - - # Mock data with user_config containing invalid keys (simulating DB entry) + # Mock data with router_settings_override containing per-request settings data = { "model": "gpt-3.5-turbo", - "user_config": { - "model_list": [ - { - "model_name": "gpt-3.5-turbo", - "litellm_params": {"model": "gpt-3.5-turbo", "api_key": "test"}, - } - ], - "model_alias_map": {"alias": "real_model"}, # INVALID PARAM - "invalid_garbage_key": "crash_me", # INVALID PARAM + "messages": [{"role": "user", "content": "Hello"}], + "router_settings_override": { + "fallbacks": [{"gpt-3.5-turbo": ["gpt-4"]}], + "num_retries": 5, + "timeout": 30, + "model_group_retry_policy": {"gpt-3.5-turbo": {"RateLimitErrorRetries": 3}}, + # These settings should be ignored (not in per_request_settings list) + "routing_strategy": "least-busy", + "model_group_alias": {"alias": "real_model"}, }, } - # We expect Router(**config) to succeed because of the filtering. - # If filtering fails, this will raise TypeError and fail the test. + llm_router = MagicMock() + llm_router.acompletion.return_value = "success" + + response = await route_request(data, llm_router, None, "acompletion") + + assert response == "success" + # Verify the router method was called with merged settings + call_kwargs = llm_router.acompletion.call_args[1] + assert call_kwargs["fallbacks"] == [{"gpt-3.5-turbo": ["gpt-4"]}] + assert call_kwargs["num_retries"] == 5 + assert call_kwargs["timeout"] == 30 + assert call_kwargs["model_group_retry_policy"] == {"gpt-3.5-turbo": {"RateLimitErrorRetries": 3}} + # Verify unsupported settings were NOT merged + assert "routing_strategy" not in call_kwargs + assert "model_group_alias" not in call_kwargs + # Verify router_settings_override was removed from data + assert "router_settings_override" not in call_kwargs + + +@pytest.mark.asyncio +async def test_route_request_with_router_settings_override_no_router(): + """ + Test that router_settings_override works when no router is provided, + falling back to litellm module directly. + """ + import litellm + + data = { + "model": "gpt-3.5-turbo", + "messages": [{"role": "user", "content": "Hello"}], + "router_settings_override": { + "fallbacks": [{"gpt-3.5-turbo": ["gpt-4"]}], + "num_retries": 3, + }, + } + + # Use MagicMock explicitly to avoid auto-AsyncMock behavior in Python 3.12+ + mock_completion = MagicMock(return_value="success") + original_acompletion = litellm.acompletion + litellm.acompletion = mock_completion + try: - # route_request calls getattr(user_router, route_type)(**data) - # We'll mock the internal call to avoid making real network requests - with pytest.MonkeyPatch.context() as m: - # Mock the method that gets called on the router instance - # We don't easily have access to the instance created INSIDE existing route_request - # So we will wrap litellm.Router to spy on it or verify it doesn't crash + response = await route_request(data, None, None, "acompletion") - original_router_init = litellm.Router.__init__ + assert response == "success" + # Verify litellm.acompletion was called with merged settings + call_kwargs = mock_completion.call_args[1] + assert call_kwargs["fallbacks"] == [{"gpt-3.5-turbo": ["gpt-4"]}] + assert call_kwargs["num_retries"] == 3 + finally: + litellm.acompletion = original_acompletion - def safe_router_init(self, **kwargs): - # Verify that invalid keys are NOT present in kwargs - assert "model_alias_map" not in kwargs - assert "invalid_garbage_key" not in kwargs - # Call original init (which would raise TypeError if invalid keys were present) - original_router_init(self, **kwargs) - m.setattr(litellm.Router, "__init__", safe_router_init) +@pytest.mark.asyncio +async def test_route_request_with_router_settings_override_preserves_existing(): + """ + Test that router_settings_override does not override settings already in the request. + Request-level settings take precedence over key/team settings. + """ + data = { + "model": "gpt-3.5-turbo", + "messages": [{"role": "user", "content": "Hello"}], + "num_retries": 10, # Request-level setting + "router_settings_override": { + "num_retries": 3, # Key/team setting - should NOT override + "timeout": 30, # Key/team setting - should be applied + }, + } - # Use 'acompletion' as the route_type - # We also need to mock the completion method to avoid real calls - m.setattr(Router, "acompletion", AsyncMock(return_value="success")) + llm_router = MagicMock() + llm_router.acompletion.return_value = "success" - response = await route_request(data, None, None, "acompletion") - assert response == "success" + response = await route_request(data, llm_router, None, "acompletion") - except TypeError as e: - pytest.fail( - f"route_request raised TypeError, implying invalid params were passed to Router: {e}" - ) - except Exception: - # Other exceptions might happen (e.g. valid config issues) but we care about TypeError here - pass + assert response == "success" + call_kwargs = llm_router.acompletion.call_args[1] + # Request-level num_retries should take precedence + assert call_kwargs["num_retries"] == 10 + # Key/team timeout should be applied since not in request + assert call_kwargs["timeout"] == 30 From 32b1ff7d1128a450f2ae35bc4315dccba36e67a9 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Mon, 2 Feb 2026 17:25:16 -0800 Subject: [PATCH 007/511] option to hide community engagement buttons --- .../CommunityEngagementButtons.test.tsx | 50 +++++++++++++++++++ .../CommunityEngagementButtons.tsx | 36 +++++++++++++ .../src/components/navbar.test.tsx | 39 ++++++--------- .../src/components/navbar.tsx | 24 ++------- 4 files changed, 103 insertions(+), 46 deletions(-) create mode 100644 ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.test.tsx create mode 100644 ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.tsx diff --git a/ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.test.tsx b/ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.test.tsx new file mode 100644 index 00000000000..6994def858b --- /dev/null +++ b/ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.test.tsx @@ -0,0 +1,50 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { renderWithProviders, screen } from "../../../../tests/test-utils"; +import { CommunityEngagementButtons } from "./CommunityEngagementButtons"; + +let mockUseDisableShowPromptsImpl = () => false; + +vi.mock("@/app/(dashboard)/hooks/useDisableShowPrompts", () => ({ + useDisableShowPrompts: () => mockUseDisableShowPromptsImpl(), +})); + +describe("CommunityEngagementButtons", () => { + beforeEach(() => { + vi.clearAllMocks(); + mockUseDisableShowPromptsImpl = () => false; + }); + + it("should render", () => { + renderWithProviders(); + expect(screen.getByRole("link", { name: /join slack/i })).toBeInTheDocument(); + }); + + it("should render Join Slack button with correct link", () => { + renderWithProviders(); + + const joinSlackLink = screen.getByRole("link", { name: /join slack/i }); + expect(joinSlackLink).toBeInTheDocument(); + expect(joinSlackLink).toHaveAttribute("href", "https://www.litellm.ai/support"); + expect(joinSlackLink).toHaveAttribute("target", "_blank"); + expect(joinSlackLink).toHaveAttribute("rel", "noopener noreferrer"); + }); + + it("should render Star us on GitHub button with correct link", () => { + renderWithProviders(); + + const starOnGithubLink = screen.getByRole("link", { name: /star us on github/i }); + expect(starOnGithubLink).toBeInTheDocument(); + expect(starOnGithubLink).toHaveAttribute("href", "https://github.com/BerriAI/litellm"); + expect(starOnGithubLink).toHaveAttribute("target", "_blank"); + expect(starOnGithubLink).toHaveAttribute("rel", "noopener noreferrer"); + }); + + it("should not render buttons when prompts are disabled", () => { + mockUseDisableShowPromptsImpl = () => true; + + renderWithProviders(); + + expect(screen.queryByRole("link", { name: /join slack/i })).not.toBeInTheDocument(); + expect(screen.queryByRole("link", { name: /star us on github/i })).not.toBeInTheDocument(); + }); +}); diff --git a/ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.tsx b/ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.tsx new file mode 100644 index 00000000000..649bcc0b589 --- /dev/null +++ b/ui/litellm-dashboard/src/components/Navbar/CommunityEngagementButtons/CommunityEngagementButtons.tsx @@ -0,0 +1,36 @@ +import { useDisableShowPrompts } from "@/app/(dashboard)/hooks/useDisableShowPrompts"; +import { GithubOutlined, SlackOutlined } from "@ant-design/icons"; +import { Button } from "antd"; +import React from "react"; + +export const CommunityEngagementButtons: React.FC = () => { + const disableShowPrompts = useDisableShowPrompts(); + + // Hide buttons if prompts are disabled + if (disableShowPrompts) { + return null; + } + + return ( + <> + + + + ); +}; diff --git a/ui/litellm-dashboard/src/components/navbar.test.tsx b/ui/litellm-dashboard/src/components/navbar.test.tsx index a2996f70587..125187e2340 100644 --- a/ui/litellm-dashboard/src/components/navbar.test.tsx +++ b/ui/litellm-dashboard/src/components/navbar.test.tsx @@ -12,11 +12,24 @@ vi.mock("@/utils/proxyUtils", () => ({ fetchProxySettings: vi.fn(), })); +// Mock CommunityEngagementButtons component +vi.mock("./Navbar/CommunityEngagementButtons/CommunityEngagementButtons", () => ({ + CommunityEngagementButtons: () => ( + + ), +})); + // Create mock functions that can be controlled in tests let mockUseThemeImpl = () => ({ logoUrl: null as string | null }); let mockUseHealthReadinessImpl = () => ({ data: null as any }); let mockGetLocalStorageItemImpl = (key: string) => null as string | null; -let mockUseDisableShowPromptsImpl = () => false; let mockUseAuthorizedImpl = () => ({ userId: "test-user", userEmail: "test@example.com", @@ -32,10 +45,6 @@ vi.mock("@/app/(dashboard)/hooks/healthReadiness/useHealthReadiness", () => ({ useHealthReadiness: () => mockUseHealthReadinessImpl(), })); -vi.mock("@/app/(dashboard)/hooks/useDisableShowPrompts", () => ({ - useDisableShowPrompts: () => mockUseDisableShowPromptsImpl(), -})); - vi.mock("@/app/(dashboard)/hooks/useAuthorized", () => ({ default: () => mockUseAuthorizedImpl(), })); @@ -79,26 +88,6 @@ describe("Navbar", () => { expect(screen.getByText("User")).toBeInTheDocument(); }); - it("should render Join Slack button with correct link", () => { - renderWithProviders(); - - const joinSlackLink = screen.getByRole("link", { name: /join slack/i }); - expect(joinSlackLink).toBeInTheDocument(); - expect(joinSlackLink).toHaveAttribute("href", "https://www.litellm.ai/support"); - expect(joinSlackLink).toHaveAttribute("target", "_blank"); - expect(joinSlackLink).toHaveAttribute("rel", "noopener noreferrer"); - }); - - it("should render Star us on GitHub button with correct link", () => { - renderWithProviders(); - - const starOnGithubLink = screen.getByRole("link", { name: /star us on github/i }); - expect(starOnGithubLink).toBeInTheDocument(); - expect(starOnGithubLink).toHaveAttribute("href", "https://github.com/BerriAI/litellm"); - expect(starOnGithubLink).toHaveAttribute("target", "_blank"); - expect(starOnGithubLink).toHaveAttribute("rel", "noopener noreferrer"); - }); - it("should display user information in dropdown", async () => { const user = userEvent.setup(); renderWithProviders(); diff --git a/ui/litellm-dashboard/src/components/navbar.tsx b/ui/litellm-dashboard/src/components/navbar.tsx index 3649ca76238..2ffa0632f27 100644 --- a/ui/litellm-dashboard/src/components/navbar.tsx +++ b/ui/litellm-dashboard/src/components/navbar.tsx @@ -4,16 +4,15 @@ import { useTheme } from "@/contexts/ThemeContext"; import { clearTokenCookies } from "@/utils/cookieUtils"; import { fetchProxySettings } from "@/utils/proxyUtils"; import { - GithubOutlined, MenuFoldOutlined, MenuUnfoldOutlined, MoonOutlined, - SlackOutlined, SunOutlined, } from "@ant-design/icons"; -import { Button, Switch, Tag } from "antd"; +import { Switch, Tag } from "antd"; import Link from "next/link"; import React, { useEffect, useState } from "react"; +import { CommunityEngagementButtons } from "./Navbar/CommunityEngagementButtons/CommunityEngagementButtons"; import UserDropdown from "./Navbar/UserDropdown/UserDropdown"; interface NavbarProps { @@ -129,24 +128,7 @@ const Navbar: React.FC = ({ {/* Right side nav items */}
- - + {/* Dark mode is currently a work in progress. To test, you can change 'false' to 'true' below. Do not set this to true by default until all components are confirmed to support dark mode styles. */} {false && Date: Mon, 2 Feb 2026 17:57:35 -0800 Subject: [PATCH 008/511] Migrate Default Team settings to use reusable Model Select --- .../ModelSelect/ModelSelect.test.tsx | 682 +++++++++--------- .../components/ModelSelect/ModelSelect.tsx | 12 +- .../src/components/TeamSSOSettings.test.tsx | 636 +++++++++++++++- .../src/components/TeamSSOSettings.tsx | 22 +- 4 files changed, 974 insertions(+), 378 deletions(-) diff --git a/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.test.tsx b/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.test.tsx index 3052f790098..6da2f82a2f1 100644 --- a/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.test.tsx +++ b/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.test.tsx @@ -37,12 +37,19 @@ vi.mock("antd", async (importOriginal) => { mode, ...props }: any) => { + // Simulate maxTagCount responsive behavior - if value length > 5, call maxTagPlaceholder + const shouldShowPlaceholder = maxTagCount === "responsive" && Array.isArray(value) && value.length > 5; + const visibleValues = shouldShowPlaceholder ? value.slice(0, 5) : value; + const omittedValues = shouldShowPlaceholder + ? value.slice(5).map((v: string) => ({ value: v, label: v })) + : []; + return (
+ {shouldShowPlaceholder && maxTagPlaceholder && ( +
{maxTagPlaceholder(omittedValues)}
+ )}
); }, @@ -82,6 +92,24 @@ const mockUseTeam = vi.mocked(useTeam); const mockUseOrganization = vi.mocked(useOrganization); const mockUseCurrentUser = vi.mocked(useCurrentUser); +const createMockOrganization = (models: string[]): Organization => ({ + organization_id: "org-1", + organization_alias: "Test Org", + budget_id: "budget-1", + metadata: {}, + models, + spend: 0, + model_spend: {}, + created_at: "2024-01-01", + created_by: "user-1", + updated_at: "2024-01-01", + updated_by: "user-1", + litellm_budget_table: null, + teams: null, + users: null, + members: null, +}); + describe("ModelSelect", () => { const mockProxyModels: ProxyModel[] = [ { id: "gpt-4", object: "model", created: 1234567890, owned_by: "openai" }, @@ -112,125 +140,44 @@ describe("ModelSelect", () => { } as any); }); - it("should render", async () => { + it("should render with all option groups", async () => { renderWithProviders( , ); await waitFor(() => { expect(screen.getByTestId("model-select")).toBeInTheDocument(); - }); - }); - - it("should show skeleton loader when loading", () => { - mockUseAllProxyModels.mockReturnValue({ - data: undefined, - isLoading: true, - } as any); - - renderWithProviders(); - - expect(screen.getByTestId("skeleton-input")).toBeInTheDocument(); - expect(screen.queryByTestId("model-select")).not.toBeInTheDocument(); - }); - - it("should show skeleton loader when team is loading", () => { - mockUseTeam.mockReturnValue({ - data: undefined, - isLoading: true, - } as any); - - renderWithProviders(); - - expect(screen.getByTestId("skeleton-input")).toBeInTheDocument(); - }); - - it("should show skeleton loader when organization is loading", () => { - mockUseOrganization.mockReturnValue({ - data: undefined, - isLoading: true, - } as any); - - renderWithProviders(); - - expect(screen.getByTestId("skeleton-input")).toBeInTheDocument(); - }); - - it("should show skeleton loader when current user is loading", () => { - mockUseCurrentUser.mockReturnValue({ - data: undefined, - isLoading: true, - } as any); - - renderWithProviders(); - - expect(screen.getByTestId("skeleton-input")).toBeInTheDocument(); - }); - - it("should render special options group", async () => { - const mockOrganization: Organization = { - organization_id: "org-1", - organization_alias: "Test Org", - budget_id: "budget-1", - metadata: {}, - models: ["all-proxy-models"], - spend: 0, - model_spend: {}, - created_at: "2024-01-01", - created_by: "user-1", - updated_at: "2024-01-01", - updated_by: "user-1", - litellm_budget_table: null, - teams: null, - users: null, - members: null, - }; - - mockUseOrganization.mockReturnValue({ - data: mockOrganization, - isLoading: false, - } as any); - - renderWithProviders( - , - ); - - await waitFor(() => { - const select = screen.getByTestId("model-select"); - expect(select).toBeInTheDocument(); - expect(screen.getByText("All Proxy Models")).toBeInTheDocument(); - expect(screen.getByText("No Default Models")).toBeInTheDocument(); - }); - }); - - it("should render wildcard options group", async () => { - renderWithProviders( - , - ); - - await waitFor(() => { + expect(screen.getByText("gpt-4")).toBeInTheDocument(); + expect(screen.getByText("claude-3")).toBeInTheDocument(); expect(screen.getByText("All Openai models")).toBeInTheDocument(); expect(screen.getByText("All Anthropic models")).toBeInTheDocument(); }); }); - it("should render regular models group", async () => { - renderWithProviders( - , - ); + it("should show skeleton loader when any data is loading", () => { + const loadingScenarios = [ + { hook: mockUseAllProxyModels, context: "user" as const }, + { hook: mockUseTeam, context: "team" as const, props: { teamID: "team-1" } }, + { hook: mockUseOrganization, context: "organization" as const, props: { organizationID: "org-1" } }, + { hook: mockUseCurrentUser, context: "user" as const }, + ]; - await waitFor(() => { - expect(screen.getByText("gpt-4")).toBeInTheDocument(); - expect(screen.getByText("claude-3")).toBeInTheDocument(); + loadingScenarios.forEach(({ hook, context, props = {} }) => { + hook.mockReturnValue({ + data: undefined, + isLoading: true, + } as any); + + const { unmount } = renderWithProviders( + , + ); + + expect(screen.getByTestId("skeleton-input")).toBeInTheDocument(); + unmount(); }); }); - it("should call onChange when selecting a regular model", async () => { + it("should handle model selection and onChange", async () => { const user = userEvent.setup(); renderWithProviders( , @@ -242,32 +189,16 @@ describe("ModelSelect", () => { const select = screen.getByRole("listbox"); await user.selectOptions(select, "gpt-4"); - expect(mockOnChange).toHaveBeenCalledWith(["gpt-4"]); + + await user.selectOptions(select, ["gpt-4", "claude-3"]); + expect(mockOnChange).toHaveBeenCalled(); }); - it("should call onChange with only last special option when multiple special options are selected", async () => { + it("should handle special options correctly", async () => { const user = userEvent.setup(); - const mockOrganization: Organization = { - organization_id: "org-1", - organization_alias: "Test Org", - budget_id: "budget-1", - metadata: {}, - models: ["all-proxy-models"], - spend: 0, - model_spend: {}, - created_at: "2024-01-01", - created_by: "user-1", - updated_at: "2024-01-01", - updated_by: "user-1", - litellm_budget_table: null, - teams: null, - users: null, - members: null, - }; - mockUseOrganization.mockReturnValue({ - data: mockOrganization, + data: createMockOrganization(["all-proxy-models"]), isLoading: false, } as any); @@ -281,16 +212,16 @@ describe("ModelSelect", () => { ); await waitFor(() => { - expect(screen.getByTestId("model-select")).toBeInTheDocument(); + expect(screen.getByText("All Proxy Models")).toBeInTheDocument(); + expect(screen.getByText("No Default Models")).toBeInTheDocument(); }); const select = screen.getByRole("listbox"); await user.selectOptions(select, ["all-proxy-models", "no-default-models"]); - expect(mockOnChange).toHaveBeenCalledWith(["no-default-models"]); }); - it("should disable regular models when special option is selected", async () => { + it("should disable models when special option is selected", async () => { renderWithProviders( { ); await waitFor(() => { - const gpt4Option = screen.getByRole("option", { name: "gpt-4" }); - expect(gpt4Option).toBeDisabled(); + expect(screen.getByRole("option", { name: "gpt-4" })).toBeDisabled(); + expect(screen.getByRole("option", { name: "All Openai models" })).toBeDisabled(); }); }); - it("should disable wildcard models when special option is selected", async () => { - renderWithProviders( - , - ); + it("should filter models based on context", async () => { + const testCases = [ + { + name: "user context with includeUserModels", + context: "user" as const, + options: { includeUserModels: true }, + setup: () => { + mockUseCurrentUser.mockReturnValue({ + data: { models: ["gpt-4"] }, + isLoading: false, + } as any); + }, + expectedVisible: ["gpt-4"], + expectedHidden: ["claude-3"], + }, + { + name: "user context without includeUserModels", + context: "user" as const, + options: {}, + setup: () => { + mockUseCurrentUser.mockReturnValue({ + data: { models: ["gpt-4"] }, + isLoading: false, + } as any); + }, + expectedVisible: [], + expectedHidden: ["gpt-4", "claude-3"], + }, + { + name: "team context without organization", + context: "team" as const, + options: {}, + props: { teamID: "team-1" }, + setup: () => { + mockUseTeam.mockReturnValue({ + data: { team_id: "team-1", team_alias: "Test Team", models: [] }, + isLoading: false, + } as any); + mockUseOrganization.mockReturnValue({ + data: undefined, + isLoading: false, + } as any); + }, + expectedVisible: ["gpt-4", "claude-3"], + expectedHidden: [], + }, + { + name: "team context with organization having all-proxy-models", + context: "team" as const, + options: {}, + props: { teamID: "team-1", organizationID: "org-1" }, + setup: () => { + mockUseTeam.mockReturnValue({ + data: { team_id: "team-1", team_alias: "Test Team", models: [] }, + isLoading: false, + } as any); + mockUseOrganization.mockReturnValue({ + data: createMockOrganization(["all-proxy-models"]), + isLoading: false, + } as any); + }, + expectedVisible: ["gpt-4", "claude-3"], + expectedHidden: [], + }, + { + name: "team context with organization filtering models", + context: "team" as const, + options: {}, + props: { teamID: "team-1", organizationID: "org-1" }, + setup: () => { + mockUseTeam.mockReturnValue({ + data: { team_id: "team-1", team_alias: "Test Team", models: [] }, + isLoading: false, + } as any); + mockUseOrganization.mockReturnValue({ + data: createMockOrganization(["gpt-4"]), + isLoading: false, + } as any); + }, + expectedVisible: ["gpt-4"], + expectedHidden: ["claude-3"], + }, + { + name: "organization context", + context: "organization" as const, + options: {}, + props: { organizationID: "org-1" }, + setup: () => { + mockUseOrganization.mockReturnValue({ + data: createMockOrganization(["gpt-4"]), + isLoading: false, + } as any); + }, + expectedVisible: ["gpt-4", "claude-3"], + expectedHidden: [], + }, + { + name: "global context", + context: "global" as const, + options: {}, + setup: () => { }, + expectedVisible: ["gpt-4", "claude-3"], + expectedHidden: [], + }, + ]; - await waitFor(() => { - const openaiWildcardOption = screen.getByRole("option", { name: "All Openai models" }); - expect(openaiWildcardOption).toBeDisabled(); - }); + for (const testCase of testCases) { + testCase.setup(); + const { unmount } = renderWithProviders( + , + ); + + await waitFor(() => { + testCase.expectedVisible.forEach((model) => { + expect(screen.getByText(model)).toBeInTheDocument(); + }); + testCase.expectedHidden.forEach((model) => { + expect(screen.queryByText(model)).not.toBeInTheDocument(); + }); + }); + + unmount(); + vi.clearAllMocks(); + mockUseAllProxyModels.mockReturnValue({ + data: { data: mockProxyModels }, + isLoading: false, + } as any); + } }); - it("should disable other special options when one special option is selected", async () => { - const mockOrganization: Organization = { - organization_id: "org-1", - organization_alias: "Test Org", - budget_id: "budget-1", - metadata: {}, - models: ["all-proxy-models"], - spend: 0, - model_spend: {}, - created_at: "2024-01-01", - created_by: "user-1", - updated_at: "2024-01-01", - updated_by: "user-1", - litellm_budget_table: null, - teams: null, - users: null, - members: null, - }; + it("should show All Proxy Models option based on conditions", async () => { + const testCases = [ + { + name: "when showAllProxyModelsOverride is true", + context: "user" as const, + options: { showAllProxyModelsOverride: true, includeSpecialOptions: true }, + setup: () => { }, + shouldShow: true, + }, + { + name: "when organization has all-proxy-models", + context: "organization" as const, + options: { includeSpecialOptions: true }, + props: { organizationID: "org-1" }, + setup: () => { + mockUseOrganization.mockReturnValue({ + data: createMockOrganization(["all-proxy-models"]), + isLoading: false, + } as any); + }, + shouldShow: true, + }, + { + name: "when organization has empty models array", + context: "organization" as const, + options: { includeSpecialOptions: true }, + props: { organizationID: "org-1" }, + setup: () => { + mockUseOrganization.mockReturnValue({ + data: createMockOrganization([]), + isLoading: false, + } as any); + }, + shouldShow: true, + }, + { + name: "when context is global", + context: "global" as const, + options: { includeSpecialOptions: true }, + setup: () => { }, + shouldShow: true, + }, + { + name: "when organization has specific models", + context: "organization" as const, + options: { includeSpecialOptions: true }, + props: { organizationID: "org-1" }, + setup: () => { + mockUseOrganization.mockReturnValue({ + data: createMockOrganization(["gpt-4"]), + isLoading: false, + } as any); + }, + shouldShow: false, + }, + ]; - mockUseOrganization.mockReturnValue({ - data: mockOrganization, - isLoading: false, - } as any); + for (const testCase of testCases) { + testCase.setup(); + const { unmount } = renderWithProviders( + , + ); - renderWithProviders( - , - ); + await waitFor(() => { + if (testCase.shouldShow) { + expect(screen.getByText("All Proxy Models")).toBeInTheDocument(); + } else { + expect(screen.queryByText("All Proxy Models")).not.toBeInTheDocument(); + expect(screen.getByText("No Default Models")).toBeInTheDocument(); + } + }); - await waitFor(() => { - const noDefaultOption = screen.getByRole("option", { name: "No Default Models" }); - expect(noDefaultOption).toBeDisabled(); - }); - }); - - it("should filter models when showAllProxyModelsOverride is true", async () => { - renderWithProviders( - , - ); - - await waitFor(() => { - expect(screen.getByText("gpt-4")).toBeInTheDocument(); - expect(screen.getByText("claude-3")).toBeInTheDocument(); - }); - }); - - it("should filter models when organization has all-proxy-models in models array", async () => { - const mockOrganization: Organization = { - organization_id: "org-1", - organization_alias: "Test Org", - budget_id: "budget-1", - metadata: {}, - models: ["all-proxy-models"], - spend: 0, - model_spend: {}, - created_at: "2024-01-01", - created_by: "user-1", - updated_at: "2024-01-01", - updated_by: "user-1", - litellm_budget_table: null, - teams: null, - users: null, - members: null, - }; - - mockUseOrganization.mockReturnValue({ - data: mockOrganization, - isLoading: false, - } as any); - - renderWithProviders(); - - await waitFor(() => { - expect(screen.getByText("gpt-4")).toBeInTheDocument(); - expect(screen.getByText("claude-3")).toBeInTheDocument(); - }); - }); - - it("should show all models when organization context is used", async () => { - const mockOrganization: Organization = { - organization_id: "org-1", - organization_alias: "Test Org", - budget_id: "budget-1", - metadata: {}, - models: ["gpt-4"], - spend: 0, - model_spend: {}, - created_at: "2024-01-01", - created_by: "user-1", - updated_at: "2024-01-01", - updated_by: "user-1", - litellm_budget_table: null, - teams: null, - users: null, - members: null, - }; - - mockUseOrganization.mockReturnValue({ - data: mockOrganization, - isLoading: false, - } as any); - - renderWithProviders(); - - await waitFor(() => { - expect(screen.getByText("gpt-4")).toBeInTheDocument(); - expect(screen.getByText("claude-3")).toBeInTheDocument(); - }); - }); - - it("should use custom dataTestId when provided", async () => { - renderWithProviders( - , - ); - - await waitFor(() => { - expect(screen.getByTestId("custom-test-id")).toBeInTheDocument(); - }); - }); - - it("should handle multiple model selections", async () => { - const user = userEvent.setup(); - renderWithProviders( - , - ); - - await waitFor(() => { - expect(screen.getByTestId("model-select")).toBeInTheDocument(); - }); - - const select = screen.getByRole("listbox"); - await user.selectOptions(select, "gpt-4"); - expect(mockOnChange).toHaveBeenCalledWith(["gpt-4"]); - - await user.selectOptions(select, "claude-3"); - expect(mockOnChange).toHaveBeenCalled(); - const allCalls = mockOnChange.mock.calls.map((call) => call[0]); - expect(allCalls.some((call) => Array.isArray(call) && call.includes("gpt-4"))).toBe(true); - expect(allCalls.some((call) => Array.isArray(call) && call.includes("claude-3"))).toBe(true); - }); - - it("should capitalize provider name in wildcard options", async () => { - renderWithProviders( - , - ); - - await waitFor(() => { - expect(screen.getByText("All Openai models")).toBeInTheDocument(); - expect(screen.getByText("All Anthropic models")).toBeInTheDocument(); - }); + unmount(); + vi.clearAllMocks(); + mockUseAllProxyModels.mockReturnValue({ + data: { data: mockProxyModels }, + isLoading: false, + } as any); + } }); it("should deduplicate models with same id", async () => { @@ -505,52 +479,29 @@ describe("ModelSelect", () => { }); }); - it("should filter models based on user context with includeUserModels option", async () => { - mockUseCurrentUser.mockReturnValue({ - data: { models: ["gpt-4"] }, - isLoading: false, - } as any); - - renderWithProviders(); + it("should use custom dataTestId when provided", async () => { + renderWithProviders( + , + ); await waitFor(() => { - expect(screen.getByText("gpt-4")).toBeInTheDocument(); - expect(screen.queryByText("claude-3")).not.toBeInTheDocument(); + expect(screen.getByTestId("custom-test-id")).toBeInTheDocument(); }); }); - it("should filter models based on team context", async () => { - const mockTeam = { - team_id: "team-1", - team_alias: "Test Team", - models: ["gpt-4"], - }; - - const mockOrganization: Organization = { - organization_id: "org-1", - organization_alias: "Test Org", - budget_id: "budget-1", - metadata: {}, - models: ["gpt-4"], - spend: 0, - model_spend: {}, - created_at: "2024-01-01", - created_by: "user-1", - updated_at: "2024-01-01", - updated_by: "user-1", - litellm_budget_table: null, - teams: null, - users: null, - members: null, - }; - + it("should return all proxy models for team context when organization has empty models array", async () => { mockUseTeam.mockReturnValue({ - data: mockTeam, + data: { team_id: "team-1", team_alias: "Test Team", models: [] }, isLoading: false, } as any); mockUseOrganization.mockReturnValue({ - data: mockOrganization, + data: createMockOrganization([]), isLoading: false, } as any); @@ -558,7 +509,62 @@ describe("ModelSelect", () => { await waitFor(() => { expect(screen.getByText("gpt-4")).toBeInTheDocument(); - expect(screen.queryByText("claude-3")).not.toBeInTheDocument(); + expect(screen.getByText("claude-3")).toBeInTheDocument(); + }); + }); + + it("should disable No Default Models when all-proxy-models is selected", async () => { + mockUseOrganization.mockReturnValue({ + data: createMockOrganization(["all-proxy-models"]), + isLoading: false, + } as any); + + renderWithProviders( + , + ); + + await waitFor(() => { + const noDefaultOption = screen.getByRole("option", { name: "No Default Models" }); + expect(noDefaultOption).toBeDisabled(); + }); + }); + + it("should render maxTagPlaceholder when many items are selected", async () => { + // Create many models to trigger maxTagCount responsive behavior + const manyModels: ProxyModel[] = Array.from({ length: 20 }, (_, i) => ({ + id: `model-${i}`, + object: "model", + created: 1234567890, + owned_by: "test", + })); + + mockUseAllProxyModels.mockReturnValue({ + data: { data: manyModels }, + isLoading: false, + } as any); + + const selectedValues = manyModels.slice(0, 10).map((m) => m.id); + + renderWithProviders( + , + ); + + await waitFor(() => { + expect(screen.getByTestId("model-select")).toBeInTheDocument(); + // Verify maxTagPlaceholder is rendered with omitted values + expect(screen.getByTestId("max-tag-placeholder")).toBeInTheDocument(); + expect(screen.getByText(/\+5 more/)).toBeInTheDocument(); }); }); }); diff --git a/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.tsx b/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.tsx index 78ccdddd81b..2b7399c4565 100644 --- a/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.tsx +++ b/ui/litellm-dashboard/src/components/ModelSelect/ModelSelect.tsx @@ -30,10 +30,11 @@ export interface ModelSelectProps { showAllProxyModelsOverride?: boolean; includeSpecialOptions?: boolean; }; - context: "team" | "organization" | "user"; + context: "team" | "organization" | "user" | "global"; dataTestId?: string; value?: string[]; onChange: (values: string[]) => void; + style?: React.CSSProperties; } type FilterContextArgs = { @@ -65,6 +66,10 @@ const contextFilters: Record { return allProxyModels; }, + + global: ({ allProxyModels }) => { + return allProxyModels; + }, }; const filterModels = ( @@ -84,7 +89,7 @@ const filterModels = ( }; export const ModelSelect = (props: ModelSelectProps) => { - const { teamID, organizationID, options, context, dataTestId, value = [], onChange } = props; + const { teamID, organizationID, options, context, dataTestId, value = [], onChange, style } = props; const { includeUserModels, showAllTeamModelsOption, showAllProxyModelsOverride, includeSpecialOptions } = options || {}; const { data: allProxyModels, isLoading: isLoadingAllProxyModels } = useAllProxyModels(); @@ -98,7 +103,7 @@ export const ModelSelect = (props: ModelSelectProps) => { const organizationHasAllProxyModels = organization?.models.includes(MODEL_SELECT_ALL_PROXY_MODELS_SPECIAL_VALUE.value) || organization?.models.length === 0; const shouldShowAllProxyModels = showAllProxyModelsOverride || - (organizationHasAllProxyModels && includeSpecialOptions); + (organizationHasAllProxyModels && includeSpecialOptions) || context === "global"; if (isLoading) { return ; @@ -134,6 +139,7 @@ export const ModelSelect = (props: ModelSelectProps) => { data-testid={dataTestId} value={value} onChange={handleChange} + style={style} options={[ includeSpecialOptions ? { diff --git a/ui/litellm-dashboard/src/components/TeamSSOSettings.test.tsx b/ui/litellm-dashboard/src/components/TeamSSOSettings.test.tsx index f5e43fc3d5f..34085df8f10 100644 --- a/ui/litellm-dashboard/src/components/TeamSSOSettings.test.tsx +++ b/ui/litellm-dashboard/src/components/TeamSSOSettings.test.tsx @@ -1,63 +1,653 @@ -import { screen } from "@testing-library/react"; +import React from "react"; +import { screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; import { beforeEach, describe, expect, it, vi } from "vitest"; import { renderWithProviders } from "../../tests/test-utils"; import TeamSSOSettings from "./TeamSSOSettings"; import * as networking from "./networking"; +import NotificationsManager from "./molecules/notifications_manager"; -// Mock the networking functions vi.mock("./networking"); -// Mock the budget duration dropdown +vi.mock("@tremor/react", async (importOriginal) => { + const actual = await importOriginal(); + const React = await import("react"); + return { + ...actual, + Card: ({ children }: { children: React.ReactNode }) => React.createElement("div", { "data-testid": "card" }, children), + Title: ({ children }: { children: React.ReactNode }) => React.createElement("h2", {}, children), + Text: ({ children }: { children: React.ReactNode }) => React.createElement("span", {}, children), + Divider: () => React.createElement("hr", {}), + TextInput: ({ value, onChange, placeholder, className }: any) => + React.createElement("input", { + type: "text", + value: value || "", + onChange, + placeholder, + className, + }), + }; +}); + vi.mock("./common_components/budget_duration_dropdown", () => ({ default: ({ value, onChange }: { value: string | null; onChange: (value: string) => void }) => ( - onChange(e.target.value)} + aria-label="Budget duration" + > ), - getBudgetDurationLabel: vi.fn((value: string) => value), + getBudgetDurationLabel: vi.fn((value: string) => `Budget: ${value}`), })); -// Mock the model display name helper vi.mock("./key_team_helpers/fetch_available_models_team_key", () => ({ getModelDisplayName: vi.fn((model: string) => model), })); +vi.mock("./ModelSelect/ModelSelect", () => ({ + ModelSelect: ({ value, onChange }: { value: string[]; onChange: (value: string[]) => void }) => ( + + ), +})); + +vi.mock("antd", async (importOriginal) => { + const actual = await importOriginal(); + const React = await import("react"); + const SelectComponent = ({ + value, + onChange, + mode, + children, + className, + }: { + value: any; + onChange: (value: any) => void; + mode?: string; + children: React.ReactNode; + className?: string; + }) => { + const isMultiple = mode === "multiple"; + const selectValue = isMultiple ? (Array.isArray(value) ? value : []) : value || ""; + return React.createElement( + "select", + { + multiple: isMultiple, + value: selectValue, + onChange: (e: React.ChangeEvent) => { + const selectedValues = Array.from(e.target.selectedOptions, (option) => option.value); + onChange(isMultiple ? selectedValues : selectedValues[0] || undefined); + }, + className, + "aria-label": "Select", + role: "listbox", + }, + children, + ); + }; + SelectComponent.Option = ({ value: optionValue, children: optionChildren }: { value: string; children: React.ReactNode }) => + React.createElement("option", { value: optionValue }, optionChildren); + return { + ...actual, + Spin: ({ size }: { size?: string }) => React.createElement("div", { "data-testid": "spinner", "data-size": size }), + Switch: ({ checked, onChange }: { checked: boolean; onChange: (checked: boolean) => void }) => + React.createElement("input", { + type: "checkbox", + role: "switch", + checked: checked, + onChange: (e) => onChange(e.target.checked), + "aria-label": "Toggle switch", + }), + Select: SelectComponent, + Typography: { + Paragraph: ({ children }: { children: React.ReactNode }) => React.createElement("p", {}, children), + }, + }; +}); + +const mockGetDefaultTeamSettings = vi.mocked(networking.getDefaultTeamSettings); +const mockUpdateDefaultTeamSettings = vi.mocked(networking.updateDefaultTeamSettings); +const mockModelAvailableCall = vi.mocked(networking.modelAvailableCall); +const mockNotificationsManager = vi.mocked(NotificationsManager); + describe("TeamSSOSettings", () => { + const defaultProps = { + accessToken: "test-token", + userID: "test-user", + userRole: "admin", + }; + + const mockSettings = { + values: { + budget_duration: "monthly", + max_budget: 1000, + enabled: true, + allowed_models: ["gpt-4", "claude-3"], + models: ["gpt-4"], + status: "active", + }, + field_schema: { + description: "Default team settings schema", + properties: { + budget_duration: { + type: "string", + description: "Budget duration setting", + }, + max_budget: { + type: "number", + description: "Maximum budget amount", + }, + enabled: { + type: "boolean", + description: "Enable feature", + }, + allowed_models: { + type: "array", + items: { + enum: ["gpt-4", "claude-3", "gpt-3.5-turbo"], + }, + description: "Allowed models", + }, + models: { + type: "array", + description: "Selected models", + }, + status: { + type: "string", + enum: ["active", "inactive", "pending"], + description: "Status", + }, + }, + }, + }; + beforeEach(() => { vi.clearAllMocks(); + mockModelAvailableCall.mockResolvedValue({ + data: [{ id: "gpt-4" }, { id: "claude-3" }], + }); }); - it("renders the component", async () => { - // Mock successful API responses - vi.mocked(networking.getDefaultTeamSettings).mockResolvedValue({ + it("should render", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Default Team Settings")).toBeInTheDocument(); + }); + }); + + it("should show loading spinner while fetching settings", () => { + mockGetDefaultTeamSettings.mockImplementation(() => new Promise(() => { })); + + renderWithProviders(); + + expect(screen.getByTestId("spinner")).toBeInTheDocument(); + }); + + it("should display message when no settings are available", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(null as any); + + renderWithProviders(); + + await waitFor(() => { + expect( + screen.getByText("No team settings available or you do not have permission to view them."), + ).toBeInTheDocument(); + }); + }); + + it("should not fetch settings when access token is null", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(mockGetDefaultTeamSettings).not.toHaveBeenCalled(); + }); + }); + + it("should display settings fields with correct values", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Budget Duration")).toBeInTheDocument(); + expect(screen.getByText("Max Budget")).toBeInTheDocument(); + }); + + expect(screen.getByText("Budget: monthly")).toBeInTheDocument(); + expect(screen.getByText("1000")).toBeInTheDocument(); + const enabledTexts = screen.getAllByText("Enabled"); + expect(enabledTexts.length).toBeGreaterThan(0); + }); + + it("should display 'Not set' for null values", async () => { + const settingsWithNulls = { + ...mockSettings, values: { - budget_duration: "monthly", - max_budget: 1000, + ...mockSettings.values, + max_budget: null, }, + }; + mockGetDefaultTeamSettings.mockResolvedValue(settingsWithNulls); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Not set")).toBeInTheDocument(); + }); + }); + + it("should toggle edit mode when edit button is clicked", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + expect(screen.getByRole("button", { name: "Cancel" })).toBeInTheDocument(); + expect(screen.getByRole("button", { name: "Save Changes" })).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "Edit Settings" })).not.toBeInTheDocument(); + }); + + it("should cancel edit mode and reset values", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + const cancelButton = screen.getByRole("button", { name: "Cancel" }); + await userEvent.click(cancelButton); + + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "Cancel" })).not.toBeInTheDocument(); + }); + + it("should save settings when save button is clicked", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + mockUpdateDefaultTeamSettings.mockResolvedValue({ + settings: mockSettings.values, + }); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Save Changes" })).toBeInTheDocument(); + }); + + const saveButton = screen.getByRole("button", { name: "Save Changes" }); + await userEvent.click(saveButton); + + await waitFor(() => { + expect(mockUpdateDefaultTeamSettings).toHaveBeenCalledWith("test-token", mockSettings.values); + }); + + expect(mockNotificationsManager.success).toHaveBeenCalledWith("Default team settings updated successfully"); + }); + + it("should show error notification when save fails", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + mockUpdateDefaultTeamSettings.mockRejectedValue(new Error("Save failed")); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Save Changes" })).toBeInTheDocument(); + }); + + const saveButton = screen.getByRole("button", { name: "Save Changes" }); + await userEvent.click(saveButton); + + await waitFor(() => { + expect(mockNotificationsManager.fromBackend).toHaveBeenCalledWith("Failed to update team settings"); + }); + }); + + it("should render boolean field as switch in edit mode", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + const switchElement = screen.getByRole("switch"); + expect(switchElement).toBeInTheDocument(); + expect(switchElement).toBeChecked(); + }); + }); + + it("should update boolean value when switch is toggled", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByRole("switch")).toBeInTheDocument(); + }); + + const switchElement = screen.getByRole("switch"); + await userEvent.click(switchElement); + + expect(switchElement).not.toBeChecked(); + }); + + it("should render budget duration dropdown in edit mode", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByLabelText("Budget duration")).toBeInTheDocument(); + }); + }); + + it("should update budget duration when dropdown value changes", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByLabelText("Budget duration")).toBeInTheDocument(); + }); + + const dropdown = screen.getByLabelText("Budget duration"); + await userEvent.selectOptions(dropdown, "daily"); + + expect(dropdown).toHaveValue("daily"); + }); + + it("should render text input for string fields in edit mode", async () => { + const settingsWithString = { + ...mockSettings, field_schema: { - description: "Default team settings", + ...mockSettings.field_schema, properties: { - budget_duration: { + ...mockSettings.field_schema.properties, + team_name: { type: "string", - description: "Budget duration", - }, - max_budget: { - type: "number", - description: "Maximum budget", + description: "Team name", }, }, }, + values: { + ...mockSettings.values, + team_name: "Test Team", + }, + }; + mockGetDefaultTeamSettings.mockResolvedValue(settingsWithString); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); }); - vi.mocked(networking.modelAvailableCall).mockResolvedValue({ - data: [{ id: "gpt-4" }, { id: "claude-3" }], + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + const textInput = screen.getByDisplayValue("Test Team"); + expect(textInput).toBeInTheDocument(); + }); + }); + + it("should render enum select for string enum fields in edit mode", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); }); - renderWithProviders(); + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); - const container = await screen.findByText("Default Team Settings"); - expect(container).toBeInTheDocument(); + await waitFor(() => { + const statusSelect = screen.getAllByRole("listbox")[0]; + expect(statusSelect).toBeInTheDocument(); + }); + }); + + it("should render multi-select for array enum fields in edit mode", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + const multiSelects = screen.getAllByRole("listbox"); + expect(multiSelects.length).toBeGreaterThan(0); + }); + }); + + it("should render ModelSelect for models field in edit mode", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByTestId("model-select")).toBeInTheDocument(); + }); + }); + + it("should display models as badges in view mode", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + const gpt4Elements = screen.getAllByText("gpt-4"); + expect(gpt4Elements.length).toBeGreaterThan(0); + }); + }); + + it("should display 'None' for empty arrays in view mode", async () => { + const settingsWithEmptyArray = { + ...mockSettings, + values: { + ...mockSettings.values, + models: [], + }, + }; + mockGetDefaultTeamSettings.mockResolvedValue(settingsWithEmptyArray); + + renderWithProviders(); + + await waitFor(() => { + const noneTexts = screen.getAllByText("None"); + expect(noneTexts.length).toBeGreaterThan(0); + }); + }); + + it("should display schema description when available", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Default team settings schema")).toBeInTheDocument(); + }); + }); + + it("should show error notification when fetching settings fails", async () => { + mockGetDefaultTeamSettings.mockRejectedValue(new Error("Fetch failed")); + + renderWithProviders(); + + await waitFor(() => { + expect(mockNotificationsManager.fromBackend).toHaveBeenCalledWith("Failed to fetch team settings"); + }); + }); + + it("should handle model fetch error gracefully", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + mockModelAvailableCall.mockRejectedValue(new Error("Model fetch failed")); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Default Team Settings")).toBeInTheDocument(); + }); + }); + + it("should disable cancel button while saving", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + mockUpdateDefaultTeamSettings.mockImplementation( + () => new Promise((resolve) => setTimeout(() => resolve({ settings: mockSettings.values }), 100)), + ); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Edit Settings" })).toBeInTheDocument(); + }); + + const editButton = screen.getByRole("button", { name: "Edit Settings" }); + await userEvent.click(editButton); + + await waitFor(() => { + expect(screen.getByRole("button", { name: "Save Changes" })).toBeInTheDocument(); + }); + + const saveButton = screen.getByRole("button", { name: "Save Changes" }); + await userEvent.click(saveButton); + + const cancelButton = screen.getByRole("button", { name: "Cancel" }); + expect(cancelButton).toBeDisabled(); + }); + + it("should display field descriptions", async () => { + mockGetDefaultTeamSettings.mockResolvedValue(mockSettings); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Budget duration setting")).toBeInTheDocument(); + expect(screen.getByText("Maximum budget amount")).toBeInTheDocument(); + }); + }); + + it("should format field names by replacing underscores and capitalizing", async () => { + const settingsWithUnderscores = { + ...mockSettings, + field_schema: { + ...mockSettings.field_schema, + properties: { + ...mockSettings.field_schema.properties, + max_budget_per_user: { + type: "number", + description: "Max budget per user", + }, + }, + }, + values: { + ...mockSettings.values, + max_budget_per_user: 500, + }, + }; + mockGetDefaultTeamSettings.mockResolvedValue(settingsWithUnderscores); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Max Budget Per User")).toBeInTheDocument(); + }); + }); + + it("should display 'No schema information available' when schema is missing", async () => { + const settingsWithoutSchema = { + values: {}, + field_schema: null, + }; + mockGetDefaultTeamSettings.mockResolvedValue(settingsWithoutSchema); + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("No schema information available")).toBeInTheDocument(); + }); }); }); diff --git a/ui/litellm-dashboard/src/components/TeamSSOSettings.tsx b/ui/litellm-dashboard/src/components/TeamSSOSettings.tsx index 8537b108cdc..33bfc783afd 100644 --- a/ui/litellm-dashboard/src/components/TeamSSOSettings.tsx +++ b/ui/litellm-dashboard/src/components/TeamSSOSettings.tsx @@ -5,6 +5,7 @@ import { getDefaultTeamSettings, updateDefaultTeamSettings, modelAvailableCall } import BudgetDurationDropdown, { getBudgetDurationLabel } from "./common_components/budget_duration_dropdown"; import { getModelDisplayName } from "./key_team_helpers/fetch_available_models_team_key"; import NotificationsManager from "./molecules/notifications_manager"; +import { ModelSelect } from "./ModelSelect/ModelSelect"; interface TeamSSOSettingsProps { accessToken: string | null; @@ -116,22 +117,15 @@ const TeamSSOSettings: React.FC = ({ accessToken, userID, ); } else if (key === "models") { return ( - + context="global" + style={{ width: "100%" }} + options={{ + includeSpecialOptions: true, + }} + /> ); } else if (type === "string" && property.enum) { return ( From c8f9af175866e72967f8bff25f19ef0c6d31bfe6 Mon Sep 17 00:00:00 2001 From: Ishaan Jaffer Date: Mon, 2 Feb 2026 19:00:10 -0800 Subject: [PATCH 009/511] fix mypy lint --- litellm/proxy/_experimental/mcp_server/semantic_tool_filter.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/litellm/proxy/_experimental/mcp_server/semantic_tool_filter.py b/litellm/proxy/_experimental/mcp_server/semantic_tool_filter.py index b01bf142385..e5cb6a0098d 100644 --- a/litellm/proxy/_experimental/mcp_server/semantic_tool_filter.py +++ b/litellm/proxy/_experimental/mcp_server/semantic_tool_filter.py @@ -81,6 +81,9 @@ class SemanticMCPToolFilter: def _extract_tool_info(self, tool) -> tuple[str, str]: """Extract name and description from MCP tool or OpenAI function dict.""" + name: str + description: str + if isinstance(tool, dict): # OpenAI function format name = tool.get("name", "") From 610ef7b4cfda925b3e0dc3955ed84f31b5470e39 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Mon, 2 Feb 2026 19:04:18 -0800 Subject: [PATCH 010/511] chore: antd modal deprecated props --- .../src/components/AIHub/ModelHubTable.tsx | 8 ++--- .../src/components/OldTeams.tsx | 2 +- .../src/components/SSOModals.tsx | 6 ++-- .../src/components/admins.tsx | 10 +++--- .../src/components/budgets/budget_modal.tsx | 2 +- .../components/budgets/edit_budget_modal.tsx | 2 +- .../components/bulk_create_users_button.tsx | 32 +++++++++---------- .../src/components/cloudzero_export_modal.tsx | 2 +- .../src/components/create_user_button.tsx | 2 +- .../edit_auto_router_modal.tsx | 2 +- .../edit_model/edit_model_modal.tsx | 6 ++-- .../src/components/edit_user.tsx | 2 +- .../model_add/CredentialDeleteModal.tsx | 2 +- .../model_add/reuse_credentials.tsx | 2 +- .../src/components/onboarding_link.tsx | 2 +- .../organisms/create_key_button.tsx | 4 +-- .../components/organization/add_org_admin.tsx | 2 +- .../src/components/request_model_access.tsx | 2 +- .../components/CreateTagModal.tsx | 2 +- .../VectorStoreForm.tsx | 2 +- 20 files changed, 47 insertions(+), 47 deletions(-) diff --git a/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx b/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx index 23bfb7d219f..4843713e5a6 100644 --- a/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx +++ b/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx @@ -483,7 +483,7 @@ const ModelHubTable: React.FC = ({ accessToken, publicPage, = ({ accessToken, publicPage, = ({ {canCreateOrManageTeams(userRole, userID, organizations) && ( = ({ <> = ({ {/* Clear Confirmation Modal */} setIsClearConfirmModalVisible(false)} okText="Yes, Clear" @@ -536,7 +536,7 @@ const SSOModals: React.FC = ({ = ({ const isLocal = process.env.NODE_ENV === "development"; if (isLocal != true) { - console.log = function () {}; + console.log = function () { }; } const baseUrl = useBaseUrl(); @@ -565,7 +565,7 @@ const AdminPanel: React.FC = ({ setIsAllowedIPModalVisible(false)} footer={[ , ]} width={1000} - destroyOnClose + destroyOnHidden >
diff --git a/ui/litellm-dashboard/src/components/edit_model/edit_model_modal.tsx b/ui/litellm-dashboard/src/components/edit_model/edit_model_modal.tsx index 88753b7df3b..95ceb65d10d 100644 --- a/ui/litellm-dashboard/src/components/edit_model/edit_model_modal.tsx +++ b/ui/litellm-dashboard/src/components/edit_model/edit_model_modal.tsx @@ -53,8 +53,8 @@ export const handleEditModelSubmit = async ( model_info: model_info_model_id !== undefined ? { - id: model_info_model_id, - } + id: model_info_model_id, + } : undefined, }; @@ -119,7 +119,7 @@ const EditModelModal: React.FC = ({ visible, onCancel, mode return ( = ({ visible, possibleUIRoles, } return ( - +
= ({ footer={null} onCancel={handleCancel} closable={true} - destroyOnClose={true} + destroyOnHidden={true} maskClosable={false} >
diff --git a/ui/litellm-dashboard/src/components/model_add/reuse_credentials.tsx b/ui/litellm-dashboard/src/components/model_add/reuse_credentials.tsx index fb0e3724571..e16c0b73ac3 100644 --- a/ui/litellm-dashboard/src/components/model_add/reuse_credentials.tsx +++ b/ui/litellm-dashboard/src/components/model_add/reuse_credentials.tsx @@ -32,7 +32,7 @@ const ReuseCredentialsModal: React.FC = ({ return ( { onCancel(); form.resetFields(); diff --git a/ui/litellm-dashboard/src/components/onboarding_link.tsx b/ui/litellm-dashboard/src/components/onboarding_link.tsx index f339afda054..e6461d26a47 100644 --- a/ui/litellm-dashboard/src/components/onboarding_link.tsx +++ b/ui/litellm-dashboard/src/components/onboarding_link.tsx @@ -63,7 +63,7 @@ export default function OnboardingModal({ return ( = ({ team, teams, data, addKey }) => { {isCreateUserModalVisible && ( setIsCreateUserModalVisible(false)} footer={null} width={800} @@ -1359,7 +1359,7 @@ const CreateKey: React.FC = ({ team, teams, data, addKey }) => { )} {apiKey && ( - + Save your Key diff --git a/ui/litellm-dashboard/src/components/organization/add_org_admin.tsx b/ui/litellm-dashboard/src/components/organization/add_org_admin.tsx index 6f50dc45f7a..309a6fdfcd4 100644 --- a/ui/litellm-dashboard/src/components/organization/add_org_admin.tsx +++ b/ui/litellm-dashboard/src/components/organization/add_org_admin.tsx @@ -45,7 +45,7 @@ const AddOrgAdmin: FC = ({ userRole, userID, selectedOrganizat = ({ userModels, accessToken, = ({ visible, onCancel, onSu }; return ( - + diff --git a/ui/litellm-dashboard/src/components/vector_store_management/VectorStoreForm.tsx b/ui/litellm-dashboard/src/components/vector_store_management/VectorStoreForm.tsx index 506543eb42e..18b5bd87d14 100644 --- a/ui/litellm-dashboard/src/components/vector_store_management/VectorStoreForm.tsx +++ b/ui/litellm-dashboard/src/components/vector_store_management/VectorStoreForm.tsx @@ -108,7 +108,7 @@ const VectorStoreForm: React.FC = ({ }; return ( - + Date: Tue, 3 Feb 2026 08:44:55 +0530 Subject: [PATCH 011/511] feat(guardrails): implement team-based isolation guardrails mgmnt (#19889) * feat(guardrails): implement team-based isolation guardrails mgmnt * fix lint errors * add allow_team_guardrail_config for admin permissions --- .../migration.sql | 8 + litellm/proxy/_types.py | 10 +- litellm/proxy/auth/login_utils.py | 60 +- .../proxy/guardrails/guardrail_endpoints.py | 280 +++++-- .../proxy/guardrails/guardrail_registry.py | 99 ++- .../management_endpoints/team_endpoints.py | 279 +++---- litellm/proxy/schema.prisma | 5 +- litellm/types/guardrails.py | 10 + schema.prisma | 5 +- .../guardrails/test_guardrail_endpoints.py | 773 ++++++++++-------- .../guardrails/test_guardrail_team_access.py | 295 +++++++ .../src/components/team/team_info.tsx | 87 +- 12 files changed, 1293 insertions(+), 618 deletions(-) create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260202204523_add_allow_team_guardrail_config/migration.sql create mode 100644 tests/test_litellm/proxy/guardrails/test_guardrail_team_access.py diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260202204523_add_allow_team_guardrail_config/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260202204523_add_allow_team_guardrail_config/migration.sql new file mode 100644 index 00000000000..706a2f25e95 --- /dev/null +++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260202204523_add_allow_team_guardrail_config/migration.sql @@ -0,0 +1,8 @@ +-- AlterTable +ALTER TABLE "LiteLLM_GuardrailsTable" ADD COLUMN "team_id" TEXT; + +-- AlterTable +ALTER TABLE "LiteLLM_TeamTable" ADD COLUMN "allow_team_guardrail_config" BOOLEAN NOT NULL DEFAULT false; + +-- AlterTable +ALTER TABLE "LiteLLM_DeletedTeamTable" ADD COLUMN "allow_team_guardrail_config" BOOLEAN NOT NULL DEFAULT false; \ No newline at end of file diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 045d2fd5f14..e84eabde6be 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -358,7 +358,6 @@ class LiteLLMRoutes(enum.Enum): "/v1/vector_stores/{vector_store_id}/files/{file_id}/content", "/vector_store/list", "/v1/vector_store/list", - # search "/search", "/v1/search", @@ -630,6 +629,9 @@ class LiteLLMRoutes(enum.Enum): "/model/{model_id}/update", "/prompt/list", "/prompt/info", + "/guardrails", + "/guardrails/{guardrail_id}", + "/v2/guardrails/list", ] # routes that manage their own allowed/disallowed logic ## Org Admin Routes ## @@ -1477,6 +1479,9 @@ class TeamBase(LiteLLMPydanticObjectBase): members: list = [] members_with_roles: List[Member] = [] team_member_permissions: Optional[List[str]] = None + allow_team_guardrail_config: Optional[ + bool + ] = None # if True, team admin can configure guardrails for this team metadata: Optional[dict] = None tpm_limit: Optional[int] = None rpm_limit: Optional[int] = None @@ -1574,6 +1579,9 @@ class UpdateTeamRequest(LiteLLMPydanticObjectBase): model_tpm_limit: Optional[Dict[str, int]] = None allowed_vector_store_indexes: Optional[List[AllowedVectorStoreIndexItem]] = None router_settings: Optional[dict] = None + allow_team_guardrail_config: Optional[ + bool + ] = None # if True, team admin can configure guardrails for this team class ResetTeamBudgetRequest(LiteLLMPydanticObjectBase): diff --git a/litellm/proxy/auth/login_utils.py b/litellm/proxy/auth/login_utils.py index 4df773dec2b..3bd56177d71 100644 --- a/litellm/proxy/auth/login_utils.py +++ b/litellm/proxy/auth/login_utils.py @@ -34,6 +34,58 @@ from litellm.secret_managers.main import get_secret_bool from litellm.types.proxy.ui_sso import ReturnedUITokenObject +async def expire_previous_ui_session_tokens( + user_id: str, prisma_client: Optional[PrismaClient] +) -> None: + """ + Expire (block) all other valid UI session tokens for a user. + + This prevents accumulation of multiple valid UI session tokens that + are supposed to be short-lived test keys. Only affects keys with + team_id = "litellm-dashboard" and that haven't expired yet. + + Args: + user_id: The user ID whose previous UI session tokens should be expired + prisma_client: Database client for performing the update + """ + if prisma_client is None: + return + + try: + from datetime import datetime, timezone + + current_time = datetime.now(timezone.utc) + + # Find all unblocked AND non-expired UI session tokens for this user + ui_session_tokens = await prisma_client.db.litellm_verificationtoken.find_many( + where={ + "user_id": user_id, + "team_id": "litellm-dashboard", + "OR": [ + {"blocked": None}, # Tokens that have never been blocked (null) + {"blocked": False}, # Tokens explicitly set to not blocked + ], + "expires": {"gt": current_time}, # Only get tokens that haven't expired + } + ) + + if not ui_session_tokens: + return + + # Block all the found tokens + tokens_to_block = [token.token for token in ui_session_tokens if token.token] + + if tokens_to_block: + await prisma_client.db.litellm_verificationtoken.update_many( + where={"token": {"in": tokens_to_block}}, data={"blocked": True} + ) + + except Exception: + # Silently fail - don't block login if cleanup fails + # This is a best-effort operation + pass + + def get_ui_credentials(master_key: Optional[str]) -> tuple[str, str]: """ Get UI username and password from environment variables or master key. @@ -245,6 +297,11 @@ async def authenticate_user( # noqa: PLR0915 ) user_email = getattr(_user_row, "user_email", "unknown") _password = getattr(_user_row, "password", "unknown") + user_team_id = getattr(_user_row, "team_id", "litellm-dashboard") + + # if user_team_id is None, set it to "litellm-dashboard" + if user_team_id is None: + user_team_id = "litellm-dashboard" if _password is None: raise ProxyException( @@ -271,7 +328,7 @@ async def authenticate_user( # noqa: PLR0915 "config": {}, "spend": 0, "user_id": user_id, - "team_id": "litellm-dashboard", + "team_id": user_team_id, }, ) else: @@ -340,4 +397,3 @@ def create_ui_token_object( disabled_non_admin_personal_key_creation=disabled_non_admin_personal_key_creation, server_root_path=get_server_root_path(), ) - diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py index 3ce819439cb..b80b02fdc6f 100644 --- a/litellm/proxy/guardrails/guardrail_endpoints.py +++ b/litellm/proxy/guardrails/guardrail_endpoints.py @@ -11,7 +11,7 @@ from pydantic import BaseModel from litellm._logging import verbose_proxy_logger from litellm.constants import DEFAULT_MAX_RECURSE_DEPTH from litellm.integrations.custom_guardrail import CustomGuardrail -from litellm.proxy._types import UserAPIKeyAuth +from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth from litellm.proxy.auth.user_api_key_auth import user_api_key_auth from litellm.proxy.guardrails.guardrail_registry import GuardrailRegistry from litellm.types.guardrails import ( @@ -32,6 +32,8 @@ from litellm.types.guardrails import ( PresidioPresidioConfigModelUserInterface, SupportedGuardrailIntegrations, ToolPermissionGuardrailConfigModel, + CreateGuardrailRequest, + UpdateGuardrailRequest, ) #### GUARDRAILS ENDPOINTS #### @@ -40,6 +42,37 @@ router = APIRouter() GUARDRAIL_REGISTRY = GuardrailRegistry() +async def _check_team_can_configure_guardrails( + user_api_key_dict: UserAPIKeyAuth, + team_id: Optional[str], + prisma_client: Any, + user_api_key_cache: Any, +) -> None: + """ + If the user is not proxy admin and team_id is set, verify the team has + allow_team_guardrail_config enabled. Raise HTTPException 403 otherwise. + """ + if team_id is None or team_id == "litellm-dashboard": + return + user_role = getattr(user_api_key_dict, "user_role", None) + if user_role == LitellmUserRoles.PROXY_ADMIN: + return + from litellm.proxy.auth.auth_checks import get_team_object + + team_table = await get_team_object( + team_id=team_id, + prisma_client=prisma_client, + user_api_key_cache=user_api_key_cache, + check_db_only=True, + ) + allow_config = getattr(team_table, "allow_team_guardrail_config", False) + if not allow_config: + raise HTTPException( + status_code=403, + detail="Guardrail configuration is not enabled for this team. Contact your administrator to enable it.", + ) + + def _get_guardrails_list_response( guardrails_config: List[Dict], ) -> ListGuardrailsResponse: @@ -64,9 +97,19 @@ def _get_guardrails_list_response( dependencies=[Depends(user_api_key_auth)], response_model=ListGuardrailsResponse, ) -async def list_guardrails(): +@router.get( + "/v2/guardrails/list", + tags=["Guardrails"], + dependencies=[Depends(user_api_key_auth)], + response_model=ListGuardrailsResponse, +) +async def list_guardrails( + user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), +): """ - List the guardrails that are available on the proxy server + List the guardrails that are available in the database using GuardrailRegistry + + Now supports both DB-persisted and In-Memory (Config) guardrails. 👉 [Guardrail docs](https://docs.litellm.ai/docs/proxy/guardrails/quick_start) @@ -75,59 +118,6 @@ async def list_guardrails(): curl -X GET "http://localhost:4000/guardrails/list" -H "Authorization: Bearer " ``` - Example Response: - ```json - { - "guardrails": [ - { - "guardrail_name": "bedrock-pre-guard", - "guardrail_info": { - "params": [ - { - "name": "toxicity_score", - "type": "float", - "description": "Score between 0-1 indicating content toxicity level" - }, - { - "name": "pii_detection", - "type": "boolean" - } - ] - } - } - ] - } - ``` - """ - from litellm.proxy.proxy_server import proxy_config - - config = proxy_config.config - - _guardrails_config = cast(Optional[list[dict]], config.get("guardrails")) - - if _guardrails_config is None: - return _get_guardrails_list_response([]) - - return _get_guardrails_list_response(_guardrails_config) - - -@router.get( - "/v2/guardrails/list", - tags=["Guardrails"], - dependencies=[Depends(user_api_key_auth)], - response_model=ListGuardrailsResponse, -) -async def list_guardrails_v2(): - """ - List the guardrails that are available in the database using GuardrailRegistry - - 👉 [Guardrail docs](https://docs.litellm.ai/docs/proxy/guardrails/quick_start) - - Example Request: - ```bash - curl -X GET "http://localhost:4000/v2/guardrails/list" -H "Authorization: Bearer " - ``` - Example Response: ```json { @@ -139,12 +129,14 @@ async def list_guardrails_v2(): "guardrail": "bedrock", "mode": "pre_call", "guardrailIdentifier": "ff6ujrregl1q", - "guardrailVersion": "DRAFT", + "guardrailVersion": "1.0", "default_on": true }, "guardrail_info": { - "description": "Bedrock content moderation guardrail" - } + "description": "Updated Bedrock content moderation guardrail" + }, + "created_at": "2023-11-09T12:34:56.789Z", + "updated_at": "2023-11-09T13:45:12.345Z" } ] } @@ -153,12 +145,29 @@ async def list_guardrails_v2(): from litellm.proxy.guardrails.guardrail_registry import IN_MEMORY_GUARDRAIL_HANDLER from litellm.proxy.proxy_server import prisma_client + # Check if DB is connected if prisma_client is None: - raise HTTPException(status_code=500, detail="Prisma client not initialized") + # Fallback to config only if DB is missing (though prisma_client usually exists) + from litellm.proxy.proxy_server import proxy_config + + config = proxy_config.config + _guardrails_config = cast(Optional[list[dict]], config.get("guardrails")) + if _guardrails_config is None: + return _get_guardrails_list_response([]) + return _get_guardrails_list_response(_guardrails_config) try: + team_id = getattr(user_api_key_dict, "team_id", None) + user_role = getattr(user_api_key_dict, "user_role", None) + + filter_team_id = None + if user_role != LitellmUserRoles.PROXY_ADMIN or ( + team_id is not None and team_id != "litellm-dashboard" + ): + filter_team_id = team_id + guardrails = await GUARDRAIL_REGISTRY.get_all_guardrails_from_db( - prisma_client=prisma_client + prisma_client=prisma_client, team_id=filter_team_id ) guardrail_configs: List[GuardrailInfoResponse] = [] @@ -173,6 +182,7 @@ async def list_guardrails_v2(): created_at=guardrail.get("created_at"), updated_at=guardrail.get("updated_at"), guardrail_definition_location="db", + team_id=guardrail.get("team_id"), ) ) seen_guardrail_ids.add(guardrail.get("guardrail_id")) @@ -180,6 +190,15 @@ async def list_guardrails_v2(): # get guardrails initialized on litellm config.yaml in_memory_guardrails = IN_MEMORY_GUARDRAIL_HANDLER.list_in_memory_guardrails() for guardrail in in_memory_guardrails: + # Check access for in-memory guardrails too + if filter_team_id: + g_team = guardrail.get("team_id") + + # If guardrail has a team_id, it must match. + # If guardrail has NO team_id, it is likely a global config guardrail, so we usually allow it. + if g_team and g_team != filter_team_id: + continue + # only add guardrails that are not in DB guardrail list already if guardrail.get("guardrail_id") not in seen_guardrail_ids: guardrail_configs.append( @@ -189,6 +208,7 @@ async def list_guardrails_v2(): litellm_params=dict(guardrail.get("litellm_params") or {}), guardrail_info=dict(guardrail.get("guardrail_info") or {}), guardrail_definition_location="config", + team_id=guardrail.get("team_id"), ) ) seen_guardrail_ids.add(guardrail.get("guardrail_id")) @@ -199,16 +219,15 @@ async def list_guardrails_v2(): raise HTTPException(status_code=500, detail=str(e)) -class CreateGuardrailRequest(BaseModel): - guardrail: Guardrail - - @router.post( "/guardrails", tags=["Guardrails"], dependencies=[Depends(user_api_key_auth)], ) -async def create_guardrail(request: CreateGuardrailRequest): +async def create_guardrail( + request: CreateGuardrailRequest, + user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), +): """ Create a new guardrail @@ -257,14 +276,21 @@ async def create_guardrail(request: CreateGuardrailRequest): ``` """ from litellm.proxy.guardrails.guardrail_registry import IN_MEMORY_GUARDRAIL_HANDLER - from litellm.proxy.proxy_server import prisma_client + from litellm.proxy.proxy_server import prisma_client, user_api_key_cache if prisma_client is None: raise HTTPException(status_code=500, detail="Prisma client not initialized") try: + team_id = getattr(user_api_key_dict, "team_id", None) + await _check_team_can_configure_guardrails( + user_api_key_dict=user_api_key_dict, + team_id=team_id, + prisma_client=prisma_client, + user_api_key_cache=user_api_key_cache, + ) result = await GUARDRAIL_REGISTRY.add_guardrail_to_db( - guardrail=request.guardrail, prisma_client=prisma_client + guardrail=request.guardrail, prisma_client=prisma_client, team_id=team_id ) guardrail_name = result.get("guardrail_name", "Unknown") @@ -283,21 +309,23 @@ async def create_guardrail(request: CreateGuardrailRequest): ) return result + except HTTPException: + raise except Exception as e: verbose_proxy_logger.exception(f"Error adding guardrail to db: {e}") raise HTTPException(status_code=500, detail=str(e)) -class UpdateGuardrailRequest(BaseModel): - guardrail: Guardrail - - @router.put( "/guardrails/{guardrail_id}", tags=["Guardrails"], dependencies=[Depends(user_api_key_auth)], ) -async def update_guardrail(guardrail_id: str, request: UpdateGuardrailRequest): +async def update_guardrail( + guardrail_id: str, + request: UpdateGuardrailRequest, + user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), +): """ Update an existing guardrail @@ -346,7 +374,7 @@ async def update_guardrail(guardrail_id: str, request: UpdateGuardrailRequest): ``` """ from litellm.proxy.guardrails.guardrail_registry import IN_MEMORY_GUARDRAIL_HANDLER - from litellm.proxy.proxy_server import prisma_client + from litellm.proxy.proxy_server import prisma_client, user_api_key_cache if prisma_client is None: raise HTTPException(status_code=500, detail="Prisma client not initialized") @@ -362,6 +390,25 @@ async def update_guardrail(guardrail_id: str, request: UpdateGuardrailRequest): status_code=404, detail=f"Guardrail with ID {guardrail_id} not found" ) + if existing_guardrail.get("team_id"): + team_id = getattr(user_api_key_dict, "team_id", None) + if getattr( + user_api_key_dict, "user_role", None + ) != LitellmUserRoles.PROXY_ADMIN or ( + team_id is not None and team_id != "litellm-dashboard" + ): + if existing_guardrail.get("team_id") != team_id: + raise HTTPException( + status_code=403, + detail="Not authorized to access this guardrail", + ) + await _check_team_can_configure_guardrails( + user_api_key_dict=user_api_key_dict, + team_id=existing_guardrail.get("team_id"), + prisma_client=prisma_client, + user_api_key_cache=user_api_key_cache, + ) + result = await GUARDRAIL_REGISTRY.update_guardrail_in_db( guardrail_id=guardrail_id, guardrail=request.guardrail, @@ -394,7 +441,9 @@ async def update_guardrail(guardrail_id: str, request: UpdateGuardrailRequest): tags=["Guardrails"], dependencies=[Depends(user_api_key_auth)], ) -async def delete_guardrail(guardrail_id: str): +async def delete_guardrail( + guardrail_id: str, user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth) +): """ Delete a guardrail @@ -414,7 +463,7 @@ async def delete_guardrail(guardrail_id: str): ``` """ from litellm.proxy.guardrails.guardrail_registry import IN_MEMORY_GUARDRAIL_HANDLER - from litellm.proxy.proxy_server import prisma_client + from litellm.proxy.proxy_server import prisma_client, user_api_key_cache if prisma_client is None: raise HTTPException(status_code=500, detail="Prisma client not initialized") @@ -430,6 +479,25 @@ async def delete_guardrail(guardrail_id: str): status_code=404, detail=f"Guardrail with ID {guardrail_id} not found" ) + if existing_guardrail.get("team_id"): + team_id = getattr(user_api_key_dict, "team_id", None) + if getattr( + user_api_key_dict, "user_role", None + ) != LitellmUserRoles.PROXY_ADMIN or ( + team_id is not None and team_id != "litellm-dashboard" + ): + if existing_guardrail.get("team_id") != team_id: + raise HTTPException( + status_code=403, + detail="Not authorized to access this guardrail", + ) + await _check_team_can_configure_guardrails( + user_api_key_dict=user_api_key_dict, + team_id=existing_guardrail.get("team_id"), + prisma_client=prisma_client, + user_api_key_cache=user_api_key_cache, + ) + result = await GUARDRAIL_REGISTRY.delete_guardrail_from_db( guardrail_id=guardrail_id, prisma_client=prisma_client ) @@ -460,7 +528,11 @@ async def delete_guardrail(guardrail_id: str): tags=["Guardrails"], dependencies=[Depends(user_api_key_auth)], ) -async def patch_guardrail(guardrail_id: str, request: PatchGuardrailRequest): +async def patch_guardrail( + guardrail_id: str, + request: PatchGuardrailRequest, + user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), +): """ Partially update an existing guardrail @@ -507,7 +579,7 @@ async def patch_guardrail(guardrail_id: str, request: PatchGuardrailRequest): ``` """ from litellm.proxy.guardrails.guardrail_registry import IN_MEMORY_GUARDRAIL_HANDLER - from litellm.proxy.proxy_server import prisma_client + from litellm.proxy.proxy_server import prisma_client, user_api_key_cache if prisma_client is None: raise HTTPException(status_code=500, detail="Prisma client not initialized") @@ -523,6 +595,25 @@ async def patch_guardrail(guardrail_id: str, request: PatchGuardrailRequest): status_code=404, detail=f"Guardrail with ID {guardrail_id} not found" ) + if existing_guardrail.get("team_id"): + team_id = getattr(user_api_key_dict, "team_id", None) + if getattr( + user_api_key_dict, "user_role", None + ) != LitellmUserRoles.PROXY_ADMIN or ( + team_id is not None and team_id != "litellm-dashboard" + ): + if existing_guardrail.get("team_id") != team_id: + raise HTTPException( + status_code=403, + detail="Not authorized to access this guardrail", + ) + await _check_team_can_configure_guardrails( + user_api_key_dict=user_api_key_dict, + team_id=existing_guardrail.get("team_id"), + prisma_client=prisma_client, + user_api_key_cache=user_api_key_cache, + ) + # Create updated guardrail object guardrail_name = ( request.guardrail_name @@ -594,7 +685,10 @@ async def patch_guardrail(guardrail_id: str, request: PatchGuardrailRequest): tags=["Guardrails"], dependencies=[Depends(user_api_key_auth)], ) -async def get_guardrail_info(guardrail_id: str): +async def get_guardrail_info( + guardrail_id: str, + user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), +): """ Get detailed information about a specific guardrail by ID @@ -653,6 +747,19 @@ async def get_guardrail_info(guardrail_id: str): status_code=404, detail=f"Guardrail with ID {guardrail_id} not found" ) + if result.get("team_id"): + team_id = getattr(user_api_key_dict, "team_id", None) + if getattr( + user_api_key_dict, "user_role", None + ) != LitellmUserRoles.PROXY_ADMIN or ( + team_id is not None and team_id != "litellm-dashboard" + ): + if result.get("team_id") != team_id: + raise HTTPException( + status_code=403, + detail="Not authorized to access this guardrail", + ) + litellm_params: Optional[Union[LitellmParams, dict]] = result.get( "litellm_params" ) @@ -675,6 +782,7 @@ async def get_guardrail_info(guardrail_id: str): created_at=result.get("created_at"), updated_at=result.get("updated_at"), guardrail_definition_location=guardrail_definition_location, + team_id=result.get("team_id"), ) except HTTPException as e: raise e @@ -1209,9 +1317,9 @@ async def get_provider_specific_params(): lakera_v2_fields = _get_fields_from_model(LakeraV2GuardrailConfigModel) tool_permission_fields = _get_fields_from_model(ToolPermissionGuardrailConfigModel) - tool_permission_fields["ui_friendly_name"] = ( - ToolPermissionGuardrailConfigModel.ui_friendly_name() - ) + tool_permission_fields[ + "ui_friendly_name" + ] = ToolPermissionGuardrailConfigModel.ui_friendly_name() # Return the provider-specific parameters provider_params = { @@ -1250,10 +1358,10 @@ async def apply_guardrail( from litellm.proxy.utils import handle_exception_on_proxy try: - active_guardrail: Optional[CustomGuardrail] = ( - GUARDRAIL_REGISTRY.get_initialized_guardrail_callback( - guardrail_name=request.guardrail_name - ) + active_guardrail: Optional[ + CustomGuardrail + ] = GUARDRAIL_REGISTRY.get_initialized_guardrail_callback( + guardrail_name=request.guardrail_name ) if active_guardrail is None: raise HTTPException( diff --git a/litellm/proxy/guardrails/guardrail_registry.py b/litellm/proxy/guardrails/guardrail_registry.py index c3da6892209..487a9d481c9 100644 --- a/litellm/proxy/guardrails/guardrail_registry.py +++ b/litellm/proxy/guardrails/guardrail_registry.py @@ -233,7 +233,10 @@ class GuardrailRegistry: ########### DB management helpers for guardrails ########### ############################################################ async def add_guardrail_to_db( - self, guardrail: Guardrail, prisma_client: PrismaClient + self, + guardrail: Guardrail, + prisma_client: PrismaClient, + team_id: Optional[str] = None, ): """ Add a guardrail to the database @@ -248,6 +251,8 @@ class GuardrailRegistry: litellm_params_dict = ( dict(litellm_params_obj) if litellm_params_obj else {} ) + + # Use safe_dumps to store as string, as Prisma client seems to prefer this for now litellm_params: str = safe_dumps(litellm_params_dict) guardrail_info: str = safe_dumps(guardrail.get("guardrail_info", {})) @@ -257,6 +262,7 @@ class GuardrailRegistry: "guardrail_name": guardrail_name, "litellm_params": litellm_params, "guardrail_info": guardrail_info, + "team_id": team_id, "created_at": datetime.now(timezone.utc), "updated_at": datetime.now(timezone.utc), } @@ -265,18 +271,32 @@ class GuardrailRegistry: # Add guardrail_id to the returned guardrail object guardrail_dict = dict(guardrail) guardrail_dict["guardrail_id"] = created_guardrail.guardrail_id + guardrail_dict["team_id"] = team_id return guardrail_dict except Exception as e: raise Exception(f"Error adding guardrail to DB: {str(e)}") async def delete_guardrail_from_db( - self, guardrail_id: str, prisma_client: PrismaClient + self, + guardrail_id: str, + prisma_client: PrismaClient, + team_id: Optional[str] = None, ): """ Delete a guardrail from the database """ try: + # Check ownership if team_id is provided + if team_id: + existing_guardrail = ( + await prisma_client.db.litellm_guardrailstable.find_unique( + where={"guardrail_id": guardrail_id} + ) + ) + if not existing_guardrail or existing_guardrail.team_id != team_id: + raise Exception("Guardrail not found or access denied") + # Delete from DB await prisma_client.db.litellm_guardrailstable.delete( where={"guardrail_id": guardrail_id} @@ -287,12 +307,26 @@ class GuardrailRegistry: raise Exception(f"Error deleting guardrail from DB: {str(e)}") async def update_guardrail_in_db( - self, guardrail_id: str, guardrail: Guardrail, prisma_client: PrismaClient + self, + guardrail_id: str, + guardrail: Guardrail, + prisma_client: PrismaClient, + team_id: Optional[str] = None, ): """ Update a guardrail in the database """ try: + # Check ownership if team_id is provided + if team_id: + existing_guardrail = ( + await prisma_client.db.litellm_guardrailstable.find_unique( + where={"guardrail_id": guardrail_id} + ) + ) + if not existing_guardrail or existing_guardrail.team_id != team_id: + raise Exception("Guardrail not found or access denied") + guardrail_name = guardrail.get("guardrail_name") # Properly serialize LitellmParams Pydantic model to dict litellm_params_obj: Any = guardrail.get("litellm_params", {}) @@ -302,6 +336,7 @@ class GuardrailRegistry: litellm_params_dict = ( dict(litellm_params_obj) if litellm_params_obj else {} ) + litellm_params: str = safe_dumps(litellm_params_dict) guardrail_info: str = safe_dumps(guardrail.get("guardrail_info", {})) @@ -324,27 +359,67 @@ class GuardrailRegistry: @staticmethod async def get_all_guardrails_from_db( prisma_client: PrismaClient, + team_id: Optional[str] = None, ) -> List[Guardrail]: """ Get all guardrails from the database """ try: - guardrails_from_db = ( - await prisma_client.db.litellm_guardrailstable.find_many( - order={"created_at": "desc"}, - ) + # Normal ORM Fetch + all_guardrails = await prisma_client.db.litellm_guardrailstable.find_many( + order={"created_at": "desc"}, ) + # Filter in Python + if team_id: + guardrails_from_db = [g for g in all_guardrails if g.team_id == team_id] + else: + guardrails_from_db = all_guardrails + guardrails: List[Guardrail] = [] for guardrail in guardrails_from_db: - guardrails.append(Guardrail(**(dict(guardrail)))) # type: ignore + try: + # Deep copy to avoid mutating cache/original + g_dict = ( + guardrail.dict() + if hasattr(guardrail, "dict") + else dict(guardrail) + ) + + # Handle litellm_params + params = g_dict.get("litellm_params") + if isinstance(params, str): + import json + + try: + g_dict["litellm_params"] = json.loads(params) + except Exception: + g_dict["litellm_params"] = {} + + # Handle guardrail_info + info = g_dict.get("guardrail_info") + if isinstance(info, str): + import json + + try: + g_dict["guardrail_info"] = json.loads(info) + except Exception: + g_dict["guardrail_info"] = {} + + # Construct + guardrails.append(Guardrail(**g_dict)) # type: ignore + except Exception: + continue return guardrails except Exception as e: raise Exception(f"Error getting guardrails from DB: {str(e)}") async def get_guardrail_by_id_from_db( - self, guardrail_id: str, prisma_client: PrismaClient + self, + guardrail_id: str, + prisma_client: PrismaClient, + team_id: Optional[str] = None, ) -> Optional[Guardrail]: """ Get a guardrail by its ID from the database @@ -357,6 +432,11 @@ class GuardrailRegistry: if not guardrail: return None + if team_id and guardrail.team_id != team_id: + # Return None if not found or not owned by team + # Alternatively could raise exception, but returning None resembles "not found" + return None + return Guardrail(**(dict(guardrail))) # type: ignore except Exception as e: raise Exception(f"Error getting guardrail from DB: {str(e)}") @@ -473,6 +553,7 @@ class InMemoryGuardrailHandler: guardrail_id=guardrail.get("guardrail_id"), guardrail_name=guardrail["guardrail_name"], litellm_params=litellm_params, + team_id=guardrail.get("team_id"), ) # store references to the guardrail in memory diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index 63db2d72fe4..43c32121949 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -753,12 +753,16 @@ async def new_team( # noqa: PLR0915 if data.max_budget is not None and data.max_budget < 0: raise HTTPException( status_code=400, - detail={"error": f"max_budget cannot be negative. Received: {data.max_budget}"} + detail={ + "error": f"max_budget cannot be negative. Received: {data.max_budget}" + }, ) if data.team_member_budget is not None and data.team_member_budget < 0: raise HTTPException( status_code=400, - detail={"error": f"team_member_budget cannot be negative. Received: {data.team_member_budget}"} + detail={ + "error": f"team_member_budget cannot be negative. Received: {data.team_member_budget}" + }, ) # Check if license is over limit @@ -918,12 +922,16 @@ async def new_team( # noqa: PLR0915 complete_team_data.members_with_roles = [] complete_team_data_dict = complete_team_data.model_dump(exclude_none=True) - + # Serialize router_settings to JSON (matching key creation pattern) router_settings_value = getattr(data, "router_settings", None) - router_settings_json = safe_dumps(router_settings_value) if router_settings_value is not None else safe_dumps({}) + router_settings_json = ( + safe_dumps(router_settings_value) + if router_settings_value is not None + else safe_dumps({}) + ) complete_team_data_dict["router_settings"] = router_settings_json - + complete_team_data_dict = prisma_client.jsonify_team_object( db_data=complete_team_data_dict ) @@ -1099,7 +1107,9 @@ async def fetch_and_validate_organization( validate_team_org_change( team=LiteLLM_TeamTable(**existing_team_row.model_dump()), - organization=LiteLLM_OrganizationTableWithMembers(**organization_row.model_dump()), + organization=LiteLLM_OrganizationTableWithMembers( + **organization_row.model_dump() + ), llm_router=llm_router, ) @@ -1107,7 +1117,9 @@ async def fetch_and_validate_organization( def validate_team_org_change( - team: LiteLLM_TeamTable, organization: LiteLLM_OrganizationTableWithMembers, llm_router: Router + team: LiteLLM_TeamTable, + organization: LiteLLM_OrganizationTableWithMembers, + llm_router: Router, ) -> bool: """ Validate that a team can be moved to an organization. @@ -1158,7 +1170,9 @@ def validate_team_org_change( # Check if the team's user_id is a member of the org team_members = [m.user_id for m in team.members_with_roles] - org_members = [m.user_id for m in organization.members] if organization.members else [] + org_members = ( + [m.user_id for m in organization.members] if organization.members else [] + ) not_in_org = [ m for m in team_members @@ -1204,7 +1218,7 @@ def validate_team_org_change( "/team/update", tags=["team management"], dependencies=[Depends(user_api_key_auth)] ) @management_endpoint_wrapper -async def update_team( # noqa: PLR0915 +async def update_team( # noqa: PLR0915 data: UpdateTeamRequest, http_request: Request, user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth), @@ -1288,19 +1302,25 @@ async def update_team( # noqa: PLR0915 ) if data.team_id is None: - raise HTTPException(status_code=400, detail={"error": "No team id passed in"}) + raise HTTPException( + status_code=400, detail={"error": "No team id passed in"} + ) verbose_proxy_logger.debug("/team/update - %s", data) # Validate budget values are not negative if data.max_budget is not None and data.max_budget < 0: raise HTTPException( status_code=400, - detail={"error": f"max_budget cannot be negative. Received: {data.max_budget}"} + detail={ + "error": f"max_budget cannot be negative. Received: {data.max_budget}" + }, ) if data.team_member_budget is not None and data.team_member_budget < 0: raise HTTPException( status_code=400, - detail={"error": f"team_member_budget cannot be negative. Received: {data.team_member_budget}"} + detail={ + "error": f"team_member_budget cannot be negative. Received: {data.team_member_budget}" + }, ) existing_team_row = await prisma_client.db.litellm_teamtable.find_unique( @@ -1367,6 +1387,22 @@ async def update_team( # noqa: PLR0915 updated_kv = data.json(exclude_unset=True) + # Only proxy admin can change allow_team_guardrail_config + if ( + "allow_team_guardrail_config" in updated_kv + and user_api_key_dict.user_role + not in ( + LitellmUserRoles.PROXY_ADMIN, + LitellmUserRoles.PROXY_ADMIN.value, + ) + ): + raise HTTPException( + status_code=403, + detail={ + "error": "Only proxy admin can change 'Allow team to configure guardrails'. Contact your administrator." + }, + ) + # Check budget_duration and budget_reset_at _set_budget_reset_at(data, updated_kv) @@ -1411,16 +1447,19 @@ async def update_team( # noqa: PLR0915 updated_kv["model_id"] = _model_id # Serialize router_settings to JSON if present (matching key update pattern) - if "router_settings" in updated_kv and updated_kv["router_settings"] is not None: + if ( + "router_settings" in updated_kv + and updated_kv["router_settings"] is not None + ): updated_kv["router_settings"] = safe_dumps(updated_kv["router_settings"]) updated_kv = prisma_client.jsonify_team_object(db_data=updated_kv) - team_row: Optional[LiteLLM_TeamTable] = ( - await prisma_client.db.litellm_teamtable.update( - where={"team_id": data.team_id}, - data=updated_kv, - include={"litellm_model_table": True}, # type: ignore - ) + team_row: Optional[ + LiteLLM_TeamTable + ] = await prisma_client.db.litellm_teamtable.update( + where={"team_id": data.team_id}, + data=updated_kv, + include={"litellm_model_table": True}, # type: ignore ) if team_row is None or team_row.team_id is None: @@ -1429,7 +1468,9 @@ async def update_team( # noqa: PLR0915 detail={"error": "Team doesn't exist. Got={}".format(team_row)}, ) - verbose_proxy_logger.info("Successfully updated team - %s, info", team_row.team_id) + verbose_proxy_logger.info( + "Successfully updated team - %s, info", team_row.team_id + ) await _cache_team_object( team_id=team_row.team_id, team_table=LiteLLM_TeamTableCachedObj(**team_row.model_dump()), @@ -1771,113 +1812,6 @@ async def _add_team_members_to_team( return updated_team, updated_users, updated_team_memberships -async def _validate_and_populate_member_user_info( - member: Member, - prisma_client: PrismaClient, -) -> Member: - """ - Validate and populate user_email/user_id for a member. - - Logic: - 1. If both user_email and user_id are provided, verify they belong to the same user (use user_email as source of truth) - 2. If only user_email is provided, populate user_id from DB - 3. If only user_id is provided, populate user_email from DB (if user exists) - 4. If only user_id is provided and doesn't exist, allow it to pass with user_email as None (will be upserted later) - 5. If user_email and user_id mismatch, throw error - - Returns a Member with user_email and user_id populated (user_email may be None if only user_id provided and user doesn't exist). - """ - if member.user_email is None and member.user_id is None: - raise HTTPException( - status_code=400, - detail={"error": "Either user_id or user_email must be provided"}, - ) - - # Case 1: Both user_email and user_id provided - verify they match - if member.user_email is not None and member.user_id is not None: - # Use user_email as source of truth - # Check for multiple users with same email first - users_by_email = await prisma_client.get_data( - key_val={"user_email": member.user_email}, - table_name="user", - query_type="find_all", - ) - - if users_by_email is None or ( - isinstance(users_by_email, list) and len(users_by_email) == 0 - ): - # User doesn't exist yet - this is fine, will be created later - return member - - if isinstance(users_by_email, list) and len(users_by_email) > 1: - raise HTTPException( - status_code=400, - detail={ - "error": f"Multiple users found with email '{member.user_email}'. Please use 'user_id' instead." - }, - ) - - # Get the single user - user_by_email = users_by_email[0] - - # Verify the user_id matches - if user_by_email.user_id != member.user_id: - raise HTTPException( - status_code=400, - detail={ - "error": f"user_email '{member.user_email}' and user_id '{member.user_id}' do not belong to the same user." - }, - ) - - # Both match, return as is - return member - - # Case 2: Only user_email provided - populate user_id from DB - if member.user_email is not None and member.user_id is None: - user_by_email = await prisma_client.db.litellm_usertable.find_first( - where={"user_email": {"equals": member.user_email, "mode": "insensitive"}} - ) - - if user_by_email is None: - # User doesn't exist yet - this is fine, will be created later - return member - - # Check for multiple users with same email - users_by_email = await prisma_client.get_data( - key_val={"user_email": member.user_email}, - table_name="user", - query_type="find_all", - ) - - if users_by_email and isinstance(users_by_email, list) and len(users_by_email) > 1: - raise HTTPException( - status_code=400, - detail={ - "error": f"Multiple users found with email '{member.user_email}'. Please use 'user_id' instead." - }, - ) - - # Populate user_id - member.user_id = user_by_email.user_id - return member - - # Case 3: Only user_id provided - populate user_email from DB if user exists - if member.user_id is not None and member.user_email is None: - user_by_id = await prisma_client.db.litellm_usertable.find_unique( - where={"user_id": member.user_id} - ) - - if user_by_id is None: - # User doesn't exist yet - allow it to pass with user_email as None - # Will be upserted later with just user_id and null email - return member - - # Populate user_email - member.user_email = user_by_id.user_email - return member - - return member - @router.post( "/team/member_add", tags=["team management"], @@ -1953,27 +1887,16 @@ async def team_member_add( complete_team_data=complete_team_data, ) - # Validate and populate user_email/user_id for members before processing - if isinstance(data.member, Member): - await _validate_and_populate_member_user_info( - member=data.member, - prisma_client=prisma_client, - ) - elif isinstance(data.member, List): - for m in data.member: - await _validate_and_populate_member_user_info( - member=m, - prisma_client=prisma_client, - ) - - updated_team, updated_users, updated_team_memberships = ( - await _add_team_members_to_team( - data=data, - complete_team_data=complete_team_data, - prisma_client=prisma_client, - user_api_key_dict=user_api_key_dict, - litellm_proxy_admin_name=litellm_proxy_admin_name, - ) + ( + updated_team, + updated_users, + updated_team_memberships, + ) = await _add_team_members_to_team( + data=data, + complete_team_data=complete_team_data, + prisma_client=prisma_client, + user_api_key_dict=user_api_key_dict, + litellm_proxy_admin_name=litellm_proxy_admin_name, ) # Check if updated_team is None @@ -2152,15 +2075,15 @@ async def team_member_delete( ) # Fetch keys before deletion to persist them - keys_to_delete: List[LiteLLM_VerificationToken] = ( - await prisma_client.db.litellm_verificationtoken.find_many( - where={ - "user_id": {"in": list(user_ids_to_delete)}, - "team_id": data.team_id, - } - ) + keys_to_delete: List[ + LiteLLM_VerificationToken + ] = await prisma_client.db.litellm_verificationtoken.find_many( + where={ + "user_id": {"in": list(user_ids_to_delete)}, + "team_id": data.team_id, + } ) - + if keys_to_delete: await _persist_deleted_verification_tokens( keys=keys_to_delete, @@ -2539,10 +2462,10 @@ async def delete_team( team_rows: List[LiteLLM_TeamTable] = [] for team_id in data.team_ids: try: - team_row_base: Optional[BaseModel] = ( - await prisma_client.db.litellm_teamtable.find_unique( - where={"team_id": team_id} - ) + team_row_base: Optional[ + BaseModel + ] = await prisma_client.db.litellm_teamtable.find_unique( + where={"team_id": team_id} ) if team_row_base is None: raise Exception @@ -2601,10 +2524,10 @@ async def delete_team( _persist_deleted_verification_tokens, ) - keys_to_delete: List[LiteLLM_VerificationToken] = ( - await prisma_client.db.litellm_verificationtoken.find_many( - where={"team_id": {"in": data.team_ids}} - ) + keys_to_delete: List[ + LiteLLM_VerificationToken + ] = await prisma_client.db.litellm_verificationtoken.find_many( + where={"team_id": {"in": data.team_ids}} ) if keys_to_delete: @@ -2643,7 +2566,6 @@ async def delete_team( return deleted_teams - def _transform_teams_to_deleted_records( teams: List[LiteLLM_TeamTable], user_api_key_dict: UserAPIKeyAuth, @@ -2666,7 +2588,13 @@ def _transform_teams_to_deleted_records( ) record = deleted_record.model_dump() - for json_field in ["members_with_roles", "metadata", "model_spend", "model_max_budget", "router_settings"]: + for json_field in [ + "members_with_roles", + "metadata", + "model_spend", + "model_max_budget", + "router_settings", + ]: if json_field in record and record[json_field] is not None: record[json_field] = json.dumps(record[json_field]) @@ -2685,9 +2613,7 @@ async def _save_deleted_team_records( """Save deleted team records to the database.""" if not records: return - await prisma_client.db.litellm_deletedteamtable.create_many( - data=records - ) + await prisma_client.db.litellm_deletedteamtable.create_many(data=records) async def _persist_deleted_team_records( @@ -2707,6 +2633,7 @@ async def _persist_deleted_team_records( prisma_client=prisma_client, ) + def validate_membership( user_api_key_dict: UserAPIKeyAuth, team_table: LiteLLM_TeamTable ): @@ -2830,11 +2757,11 @@ async def team_info( ) try: - team_info: Optional[BaseModel] = ( - await prisma_client.db.litellm_teamtable.find_unique( - where={"team_id": team_id}, - include={"object_permission": True}, - ) + team_info: Optional[ + BaseModel + ] = await prisma_client.db.litellm_teamtable.find_unique( + where={"team_id": team_id}, + include={"object_permission": True}, ) if team_info is None: raise Exception @@ -3297,7 +3224,9 @@ async def list_team_v2( order=order_by if order_by else {"created_at": "desc"}, # Default sort ) # Get total count for pagination - total_count = await prisma_client.db.litellm_teamtable.count(where=where_conditions) + total_count = await prisma_client.db.litellm_teamtable.count( + where=where_conditions + ) # Calculate total pages total_pages = -(-total_count // page_size) # Ceiling division diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma index 3b81da10923..cc33b9bed8a 100644 --- a/litellm/proxy/schema.prisma +++ b/litellm/proxy/schema.prisma @@ -128,6 +128,7 @@ model LiteLLM_TeamTable { router_settings Json? @default("{}") team_member_permissions String[] @default([]) policies String[] @default([]) + allow_team_guardrail_config Boolean @default(false) // if true, team admin can configure guardrails for this team model_id Int? @unique // id for LiteLLM_ModelTable -> stores team-level model aliases litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) litellm_model_table LiteLLM_ModelTable? @relation(fields: [model_id], references: [id]) @@ -159,8 +160,9 @@ model LiteLLM_DeletedTeamTable { router_settings Json? @default("{}") team_member_permissions String[] @default([]) policies String[] @default([]) + allow_team_guardrail_config Boolean @default(false) model_id Int? // id for LiteLLM_ModelTable -> stores team-level model aliases - + // Original timestamps from team creation/updates created_at DateTime? @map("created_at") updated_at DateTime? @map("updated_at") @@ -784,6 +786,7 @@ model LiteLLM_GuardrailsTable { guardrail_name String @unique litellm_params Json guardrail_info Json? + team_id String? created_at DateTime @default(now()) updated_at DateTime @updatedAt } diff --git a/litellm/types/guardrails.py b/litellm/types/guardrails.py index ca22049720e..ed463491043 100644 --- a/litellm/types/guardrails.py +++ b/litellm/types/guardrails.py @@ -730,6 +730,7 @@ class Guardrail(TypedDict, total=False): guardrail_name: Required[str] litellm_params: Required[LitellmParams] guardrail_info: Optional[Dict] + team_id: Optional[str] created_at: Optional[datetime] updated_at: Optional[datetime] @@ -761,6 +762,7 @@ class GuardrailInfoResponse(BaseModel): guardrail_name: str litellm_params: Optional[BaseLitellmParams] = None guardrail_info: Optional[Dict] = None + team_id: Optional[str] = None created_at: Optional[datetime] = None updated_at: Optional[datetime] = None guardrail_definition_location: GUARDRAIL_DEFINITION_LOCATION = ( @@ -807,3 +809,11 @@ class PatchGuardrailRequest(BaseModel): guardrail_name: Optional[str] = None litellm_params: Optional[BaseLitellmParams] = None guardrail_info: Optional[Dict[str, Any]] = None + + +class CreateGuardrailRequest(BaseModel): + guardrail: Guardrail + + +class UpdateGuardrailRequest(BaseModel): + guardrail: Guardrail diff --git a/schema.prisma b/schema.prisma index 3b81da10923..3886f4db199 100644 --- a/schema.prisma +++ b/schema.prisma @@ -129,6 +129,7 @@ model LiteLLM_TeamTable { team_member_permissions String[] @default([]) policies String[] @default([]) model_id Int? @unique // id for LiteLLM_ModelTable -> stores team-level model aliases + allow_team_guardrail_config Boolean @default(false) // if true, team admin can configure guardrails for this team litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) litellm_model_table LiteLLM_ModelTable? @relation(fields: [model_id], references: [id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) @@ -160,7 +161,8 @@ model LiteLLM_DeletedTeamTable { team_member_permissions String[] @default([]) policies String[] @default([]) model_id Int? // id for LiteLLM_ModelTable -> stores team-level model aliases - + allow_team_guardrail_config Boolean @default(false) + // Original timestamps from team creation/updates created_at DateTime? @map("created_at") updated_at DateTime? @map("updated_at") @@ -784,6 +786,7 @@ model LiteLLM_GuardrailsTable { guardrail_name String @unique litellm_params Json guardrail_info Json? + team_id String? created_at DateTime @default(now()) updated_at DateTime @updatedAt } diff --git a/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py b/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py index 88f56c24067..62439327278 100644 --- a/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py +++ b/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py @@ -1,15 +1,14 @@ -import json import os import sys from datetime import datetime -from typing import Dict, List, Optional +from typing import List from unittest.mock import AsyncMock import pytest sys.path.insert( - 0, os.path.abspath("../../..") -) # Adds the parent directory to the system path + 0, os.path.abspath("../../../../..") +) # Adds the repo root directory to the system path from fastapi import HTTPException @@ -21,12 +20,12 @@ from litellm.proxy.guardrails.guardrail_endpoints import ( create_guardrail, delete_guardrail, get_guardrail_info, - list_guardrails_v2, + list_guardrails, patch_guardrail, update_guardrail, ) +from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth from litellm.proxy.guardrails.guardrail_registry import ( - IN_MEMORY_GUARDRAIL_HANDLER, InMemoryGuardrailHandler, ) from litellm.types.guardrails import ( @@ -63,7 +62,7 @@ MOCK_CONFIG_GUARDRAIL = { MOCK_GUARDRAIL = Guardrail( guardrail_name=MOCK_CONFIG_GUARDRAIL["guardrail_name"], litellm_params=LitellmParams(**MOCK_CONFIG_GUARDRAIL["litellm_params"]), - guardrail_info=MOCK_CONFIG_GUARDRAIL["guardrail_info"] + guardrail_info=MOCK_CONFIG_GUARDRAIL["guardrail_info"], ) MOCK_CREATE_REQUEST = CreateGuardrailRequest(guardrail=MOCK_GUARDRAIL) @@ -71,7 +70,7 @@ MOCK_UPDATE_REQUEST = UpdateGuardrailRequest(guardrail=MOCK_GUARDRAIL) MOCK_PATCH_REQUEST = PatchGuardrailRequest( guardrail_name="Updated Test Guardrail", litellm_params={"guardrail": "updated.guardrail", "mode": "post_call"}, - guardrail_info={"description": "Updated test guardrail"} + guardrail_info={"description": "Updated test guardrail"}, ) @@ -102,22 +101,35 @@ def mock_in_memory_handler(mocker): mock_handler.delete_in_memory_guardrail = mocker.Mock() return mock_handler + @pytest.fixture def mock_guardrail_registry(mocker): """Mock GuardrailRegistry for testing""" mock_registry = mocker.Mock() - mock_registry.add_guardrail_to_db = AsyncMock(return_value={ - **MOCK_DB_GUARDRAIL, - "guardrail_id": "new-test-guardrail-id" - }) + mock_registry.add_guardrail_to_db = AsyncMock( + return_value={**MOCK_DB_GUARDRAIL, "guardrail_id": "new-test-guardrail-id"} + ) mock_registry.delete_guardrail_from_db = AsyncMock(return_value=MOCK_DB_GUARDRAIL) - mock_registry.get_guardrail_by_id_from_db = AsyncMock(return_value=MOCK_DB_GUARDRAIL) + mock_registry.get_guardrail_by_id_from_db = AsyncMock( + return_value=MOCK_DB_GUARDRAIL + ) mock_registry.update_guardrail_in_db = AsyncMock(return_value=MOCK_DB_GUARDRAIL) return mock_registry + +@pytest.fixture +def mock_admin_user_auth(): + return UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN) + + +@pytest.fixture +def mock_team_user_auth(): + return UserAPIKeyAuth(user_role=LitellmUserRoles.TEAM, team_id="team-123") + + @pytest.mark.asyncio async def test_list_guardrails_v2_with_db_and_config( - mocker, mock_prisma_client, mock_in_memory_handler + mocker, mock_prisma_client, mock_in_memory_handler, mock_admin_user_auth ): """Test listing guardrails from both DB and config""" # Mock the prisma client @@ -128,7 +140,7 @@ async def test_list_guardrails_v2_with_db_and_config( mock_in_memory_handler, ) - response = await list_guardrails_v2() + response = await list_guardrails(user_api_key_dict=mock_admin_user_auth) assert len(response.guardrails) == 2 @@ -150,11 +162,17 @@ async def test_list_guardrails_v2_with_db_and_config( @pytest.mark.asyncio -async def test_get_guardrail_info_from_db(mocker, mock_prisma_client): +async def test_get_guardrail_info_from_db( + mocker, mock_prisma_client, mock_admin_user_auth +): """Test getting guardrail info from DB""" mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - response = await get_guardrail_info("test-db-guardrail") + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + + response = await get_guardrail_info( + "test-db-guardrail", user_api_key_dict=mock_admin_user_auth + ) assert response.guardrail_id == "test-db-guardrail" assert response.guardrail_name == "Test DB Guardrail" @@ -164,7 +182,7 @@ async def test_get_guardrail_info_from_db(mocker, mock_prisma_client): @pytest.mark.asyncio async def test_get_guardrail_info_from_config( - mocker, mock_prisma_client, mock_in_memory_handler + mocker, mock_prisma_client, mock_in_memory_handler, mock_admin_user_auth ): """Test getting guardrail info from config when not found in DB""" mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) @@ -178,7 +196,9 @@ async def test_get_guardrail_info_from_config( return_value=None ) - response = await get_guardrail_info("test-config-guardrail") + response = await get_guardrail_info( + "test-config-guardrail", user_api_key_dict=mock_admin_user_auth + ) assert response.guardrail_id == "test-config-guardrail" assert response.guardrail_name == "Test Config Guardrail" @@ -188,7 +208,7 @@ async def test_get_guardrail_info_from_config( @pytest.mark.asyncio async def test_get_guardrail_info_not_found( - mocker, mock_prisma_client, mock_in_memory_handler + mocker, mock_prisma_client, mock_in_memory_handler, mock_admin_user_auth ): """Test getting guardrail info when not found in either DB or config""" mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) @@ -204,7 +224,9 @@ async def test_get_guardrail_info_not_found( mock_in_memory_handler.get_guardrail_by_id.return_value = None with pytest.raises(HTTPException) as exc_info: - await get_guardrail_info("non-existent-guardrail") + await get_guardrail_info( + "non-existent-guardrail", user_api_key_dict=mock_admin_user_auth + ) assert exc_info.value.status_code == 404 assert "not found" in str(exc_info.value.detail) @@ -222,7 +244,6 @@ def test_get_provider_specific_params(): pytest.skip("Azure config model not available") fields = _get_fields_from_model(config_model) - print("FIELDS", fields) # Test that we get the expected nested structure assert isinstance(fields, dict) @@ -238,12 +259,12 @@ def test_get_provider_specific_params(): fields["api_key"]["description"] == "API key for the Azure Content Safety Prompt Shield guardrail" ) - assert fields["api_key"]["required"] == False - assert fields["api_key"]["type"] == "string" # Should be string, not None + assert fields["api_key"]["required"] is False + assert fields["api_key"]["type"] == "string" # Check the structure of the nested optional_params field assert fields["optional_params"]["type"] == "nested" - assert fields["optional_params"]["required"] == True + assert fields["optional_params"]["required"] is True assert "fields" in fields["optional_params"] # Check nested fields within optional_params @@ -260,7 +281,7 @@ def test_get_provider_specific_params(): nested_fields["severity_threshold"]["description"] == "Severity threshold for the Azure Content Safety Text Moderation guardrail across all categories" ) - assert nested_fields["severity_threshold"]["required"] == False + assert nested_fields["severity_threshold"]["required"] is False assert ( nested_fields["severity_threshold"]["type"] == "number" ) # Should be number, not None @@ -269,16 +290,14 @@ def test_get_provider_specific_params(): assert nested_fields["categories"]["type"] == "multiselect" assert nested_fields["blocklistNames"]["type"] == "array" assert nested_fields["haltOnBlocklistHit"]["type"] == "boolean" - assert ( - nested_fields["outputType"]["type"] == "select" - ) # Literal type should be select + assert nested_fields["outputType"]["type"] == "select" def test_optional_params_not_returned_when_not_overridden(): """Test that optional_params is not returned when the config model doesn't override it""" from typing import Optional - from pydantic import BaseModel, Field + from pydantic import Field from litellm.proxy.guardrails.guardrail_endpoints import _get_fields_from_model from litellm.types.proxy.guardrails.guardrail_hooks.base import GuardrailConfigModel @@ -299,7 +318,6 @@ def test_optional_params_not_returned_when_not_overridden(): # Get fields from the model fields = _get_fields_from_model(TestGuardrailConfig) - print("FIELDS", fields) assert "optional_params" not in fields @@ -337,14 +355,13 @@ def test_optional_params_returned_when_properly_overridden(): # Get fields from the model fields = _get_fields_from_model(TestGuardrailConfigWithOptionalParams) - print("FIELDS", fields) assert "optional_params" in fields @pytest.mark.asyncio async def test_bedrock_guardrail_prepare_request_with_api_key(): """Test _prepare_request method uses Bearer token when api_key is provided in data""" - from unittest.mock import Mock, patch + from unittest.mock import Mock from litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails import ( BedrockGuardrail, @@ -352,27 +369,23 @@ async def test_bedrock_guardrail_prepare_request_with_api_key(): # Setup guardrail hook guardrail_hook = BedrockGuardrail( - guardrailIdentifier="test-guardrail-id", - guardrailVersion="1" + guardrailIdentifier="test-guardrail-id", guardrailVersion="1" ) mock_credentials = Mock() - test_data = { - "source": "INPUT", - "content": [{"text": {"text": "test content"}}] - } - + test_data = {"source": "INPUT", "content": [{"text": {"text": "test content"}}]} + prepared_request = guardrail_hook._prepare_request( credentials=mock_credentials, data=test_data, optional_params={}, aws_region_name="us-east-1", - api_key="test-bearer-token-123" + api_key="test-bearer-token-123", ) - + # Verify Bearer token is used in Authorization header assert "Authorization" in prepared_request.headers assert prepared_request.headers["Authorization"] == "Bearer test-bearer-token-123" - + # Verify URL is correct expected_url = "https://bedrock-runtime.us-east-1.amazonaws.com/guardrail/test-guardrail-id/version/1/apply" assert prepared_request.url == expected_url @@ -389,45 +402,44 @@ async def test_bedrock_guardrail_prepare_request_without_api_key(): # Setup guardrail hook guardrail_hook = BedrockGuardrail( - guardrailIdentifier="test-guardrail-id", - guardrailVersion="1" + guardrailIdentifier="test-guardrail-id", guardrailVersion="1" ) - + # Mock credentials mock_credentials = Mock() - + # Test data without api_key - test_data = { - "source": "INPUT", - "content": [{"text": {"text": "test content"}}] - } - - with patch("litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails.get_secret_str") as mock_get_secret, \ - patch("botocore.auth.SigV4Auth") as mock_sigv4_auth, \ - patch("botocore.awsrequest.AWSRequest") as mock_aws_request: - + test_data = {"source": "INPUT", "content": [{"text": {"text": "test content"}}]} + + with patch( + "litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails.get_secret_str" + ) as mock_get_secret, patch("botocore.auth.SigV4Auth") as mock_sigv4_auth, patch( + "botocore.awsrequest.AWSRequest" + ) as mock_aws_request: # Mock no AWS_BEARER_TOKEN_BEDROCK mock_get_secret.return_value = None - + # Mock SigV4Auth mock_sigv4_instance = Mock() mock_sigv4_auth.return_value = mock_sigv4_instance - + # Mock AWSRequest mock_request_instance = Mock() mock_request_instance.prepare.return_value = Mock() mock_aws_request.return_value = mock_request_instance - + # Call _prepare_request - prepared_request = guardrail_hook._prepare_request( + guardrail_hook._prepare_request( credentials=mock_credentials, data=test_data, optional_params={}, - aws_region_name="us-east-1" + aws_region_name="us-east-1", ) - + # Verify SigV4 auth was used - mock_sigv4_auth.assert_called_once_with(mock_credentials, "bedrock", "us-east-1") + mock_sigv4_auth.assert_called_once_with( + mock_credentials, "bedrock", "us-east-1" + ) mock_sigv4_instance.add_auth.assert_called_once() @@ -442,34 +454,30 @@ async def test_bedrock_guardrail_prepare_request_with_bearer_token_env(): # Setup guardrail hook guardrail_hook = BedrockGuardrail( - guardrailIdentifier="test-guardrail-id", - guardrailVersion="1" + guardrailIdentifier="test-guardrail-id", guardrailVersion="1" ) - + # Mock credentials mock_credentials = Mock() - + # Test data without api_key - test_data = { - "source": "INPUT", - "content": [{"text": {"text": "test content"}}] - } - - with patch("litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails.get_secret_str") as mock_get_secret, \ - patch("botocore.awsrequest.AWSRequest") as mock_aws_request: - + test_data = {"source": "INPUT", "content": [{"text": {"text": "test content"}}]} + + with patch( + "litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails.get_secret_str" + ) as mock_get_secret, patch("botocore.awsrequest.AWSRequest") as mock_aws_request: mock_get_secret.return_value = "env-bearer-token-456" mock_request_instance = Mock() mock_request_instance.prepare.return_value = Mock() mock_aws_request.return_value = mock_request_instance - - prepared_request = guardrail_hook._prepare_request( + + guardrail_hook._prepare_request( credentials=mock_credentials, data=test_data, optional_params={}, - aws_region_name="us-east-1" + aws_region_name="us-east-1", ) - + # Verify Bearer token from environment is used mock_aws_request.assert_called_once() call_args = mock_aws_request.call_args @@ -485,45 +493,51 @@ async def test_bedrock_guardrail_make_api_request_passes_api_key(): from litellm.proxy.guardrails.guardrail_hooks.bedrock_guardrails import ( BedrockGuardrail, ) - + guardrail_hook = BedrockGuardrail( - guardrailIdentifier="test-guardrail-id", - guardrailVersion="1" + guardrailIdentifier="test-guardrail-id", guardrailVersion="1" ) - + guardrail_hook.async_handler = Mock() mock_response = Mock() mock_response.status_code = 200 mock_response.json.return_value = {"action": "NONE", "outputs": []} - - test_request_data = { - "api_key": "test-api-key-789" - } - - with patch.object(guardrail_hook.async_handler, "post", AsyncMock(return_value=mock_response)), \ - patch.object(guardrail_hook, "_load_credentials") as mock_load_creds, \ - patch.object(guardrail_hook, "convert_to_bedrock_format") as mock_convert, \ - patch.object(guardrail_hook, "get_guardrail_dynamic_request_body_params") as mock_get_params, \ - patch.object(guardrail_hook, "add_standard_logging_guardrail_information_to_request_data"), \ - patch("botocore.awsrequest.AWSRequest") as mock_aws_request: - + + test_request_data = {"api_key": "test-api-key-789"} + + with patch.object( + guardrail_hook.async_handler, "post", AsyncMock(return_value=mock_response) + ), patch.object( + guardrail_hook, "_load_credentials" + ) as mock_load_creds, patch.object( + guardrail_hook, "convert_to_bedrock_format" + ) as mock_convert, patch.object( + guardrail_hook, "get_guardrail_dynamic_request_body_params" + ) as mock_get_params, patch.object( + guardrail_hook, "add_standard_logging_guardrail_information_to_request_data" + ), patch( + "botocore.awsrequest.AWSRequest" + ) as mock_aws_request: mock_load_creds.return_value = (Mock(), "us-east-1") mock_convert.return_value = {"source": "INPUT", "content": []} mock_get_params.return_value = {} - + mock_request_instance = Mock() mock_request_instance.url = "test-url" mock_request_instance.body = b"test-body" - mock_request_instance.headers = {"Content-Type": "application/json", "Authorization": "Bearer test-api-key-789"} + mock_request_instance.headers = { + "Content-Type": "application/json", + "Authorization": "Bearer test-api-key-789", + } mock_request_instance.prepare.return_value = Mock() mock_aws_request.return_value = mock_request_instance - + await guardrail_hook.make_bedrock_api_request( source="INPUT", messages=[{"role": "user", "content": "test"}], - request_data=test_request_data + request_data=test_request_data, ) - + # Verify _prepare_request was invoked and used the api_key mock_aws_request.assert_called_once() call_args = mock_aws_request.call_args @@ -531,336 +545,419 @@ async def test_bedrock_guardrail_make_api_request_passes_api_key(): assert headers["Authorization"] == "Bearer test-api-key-789" -@pytest.mark.parametrize("scenario,expected_result,expected_exception", [ - ( - "success_with_sync", - "new-test-guardrail-id", - None - ), - ( - "success_sync_fails", - "new-test-guardrail-id", - None - ), - ( - "database_failure", - None, - HTTPException - ), - ( - "no_prisma_client", - None, - HTTPException - ), -], ids=[ - "success_with_immediate_sync", - "success_but_sync_fails", - "database_error", - "missing_prisma_client" -]) +@pytest.mark.parametrize( + "scenario,expected_result,expected_exception", + [ + ("success_with_sync", "new-test-guardrail-id", None), + ("success_sync_fails", "new-test-guardrail-id", None), + ("database_failure", None, HTTPException), + ("no_prisma_client", None, HTTPException), + ], + ids=[ + "success_with_immediate_sync", + "success_but_sync_fails", + "database_error", + "missing_prisma_client", + ], +) @pytest.mark.asyncio async def test_create_guardrail_endpoint( - scenario, expected_result, expected_exception, - mocker, mock_guardrail_registry, mock_in_memory_handler + scenario, + expected_result, + expected_exception, + mocker, + mock_guardrail_registry, + mock_in_memory_handler, + mock_admin_user_auth, ): """Test create_guardrail endpoint with different scenarios""" - + # Configure mocks based on scenario mock_logger = None if scenario == "success_with_sync": mock_prisma_client = mocker.Mock() mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "success_sync_fails": mock_prisma_client = mocker.Mock() - mock_in_memory_handler.initialize_guardrail.side_effect = Exception("Sync failed") - mock_logger = mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger") - + mock_in_memory_handler.initialize_guardrail.side_effect = Exception( + "Sync failed" + ) + mock_logger = mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger" + ) + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "database_failure": mock_prisma_client = mocker.Mock() - mock_guardrail_registry.add_guardrail_to_db.side_effect = Exception("Database error") - - mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - + mock_guardrail_registry.add_guardrail_to_db.side_effect = Exception( + "Database error" + ) + + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + elif scenario == "no_prisma_client": mocker.patch("litellm.proxy.proxy_server.prisma_client", None) - + # Run the test if expected_exception: with pytest.raises(expected_exception) as exc_info: - await create_guardrail(MOCK_CREATE_REQUEST) - + await create_guardrail( + MOCK_CREATE_REQUEST, user_api_key_dict=mock_admin_user_auth + ) + if scenario == "database_failure": assert "Database error" in str(exc_info.value.detail) elif scenario == "no_prisma_client": assert "Prisma client not initialized" in str(exc_info.value.detail) - + else: - result = await create_guardrail(MOCK_CREATE_REQUEST) - + result = await create_guardrail( + MOCK_CREATE_REQUEST, user_api_key_dict=mock_admin_user_auth + ) + assert result["guardrail_id"] == expected_result assert result["guardrail_name"] == "Test DB Guardrail" - + mock_guardrail_registry.add_guardrail_to_db.assert_called_once_with( guardrail=MOCK_CREATE_REQUEST.guardrail, - prisma_client=mocker.ANY + prisma_client=mocker.ANY, + team_id=None, ) - + mock_in_memory_handler.initialize_guardrail.assert_called_once() - + if scenario == "success_sync_fails": assert mock_logger is not None mock_logger.warning.assert_called_once() - assert "Failed to initialize guardrail" in str(mock_logger.warning.call_args) + assert "Failed to initialize guardrail" in str( + mock_logger.warning.call_args + ) -@pytest.mark.parametrize("scenario,expected_result,expected_exception", [ - ( - "success_with_sync", - "test-db-guardrail", - None - ), - ( - "success_sync_fails", - "test-db-guardrail", - None - ), - ( - "database_failure", - None, - HTTPException - ), - ( - "no_prisma_client", - None, - HTTPException - ), -], ids=[ - "success_with_immediate_sync", - "success_but_sync_fails", - "database_error", - "missing_prisma_client" -]) + +@pytest.mark.parametrize( + "scenario,expected_result,expected_exception", + [ + ("success_with_sync", "test-db-guardrail", None), + ("success_sync_fails", "test-db-guardrail", None), + ("database_failure", None, HTTPException), + ("no_prisma_client", None, HTTPException), + ], + ids=[ + "success_with_immediate_sync", + "success_but_sync_fails", + "database_error", + "missing_prisma_client", + ], +) @pytest.mark.asyncio async def test_update_guardrail_endpoint( - scenario, expected_result, expected_exception, - mocker, mock_guardrail_registry, mock_in_memory_handler + scenario, + expected_result, + expected_exception, + mocker, + mock_guardrail_registry, + mock_in_memory_handler, + mock_admin_user_auth, ): """Test update_guardrail endpoint with different scenarios""" - + # Configure mocks based on scenario mock_logger = None if scenario == "success_with_sync": mock_prisma_client = mocker.Mock() mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "success_sync_fails": mock_prisma_client = mocker.Mock() - mock_in_memory_handler.update_in_memory_guardrail.side_effect = Exception("Sync failed") - mock_logger = mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger") - + mock_in_memory_handler.update_in_memory_guardrail.side_effect = Exception( + "Sync failed" + ) + mock_logger = mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger" + ) + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "database_failure": mock_prisma_client = mocker.Mock() - mock_guardrail_registry.update_guardrail_in_db.side_effect = Exception("Database error") - - mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - + mock_guardrail_registry.update_guardrail_in_db.side_effect = Exception( + "Database error" + ) + + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + elif scenario == "no_prisma_client": mocker.patch("litellm.proxy.proxy_server.prisma_client", None) - + # Run the test if expected_exception: with pytest.raises(expected_exception) as exc_info: - await update_guardrail("test-guardrail-id", MOCK_UPDATE_REQUEST) - + await update_guardrail( + "test-guardrail-id", + MOCK_UPDATE_REQUEST, + user_api_key_dict=mock_admin_user_auth, + ) + if scenario == "database_failure": assert "Database error" in str(exc_info.value.detail) elif scenario == "no_prisma_client": assert "Prisma client not initialized" in str(exc_info.value.detail) - + else: - result = await update_guardrail("test-guardrail-id", MOCK_UPDATE_REQUEST) - + result = await update_guardrail( + "test-guardrail-id", + MOCK_UPDATE_REQUEST, + user_api_key_dict=mock_admin_user_auth, + ) + assert result["guardrail_id"] == expected_result assert result["guardrail_name"] == "Test DB Guardrail" - + mock_guardrail_registry.update_guardrail_in_db.assert_called_once_with( guardrail_id="test-guardrail-id", guardrail=MOCK_UPDATE_REQUEST.guardrail, - prisma_client=mocker.ANY + prisma_client=mocker.ANY, ) - + mock_in_memory_handler.update_in_memory_guardrail.assert_called_once_with( - guardrail_id="test-guardrail-id", - guardrail=mocker.ANY + guardrail_id="test-guardrail-id", guardrail=mocker.ANY ) - + if scenario == "success_sync_fails": assert mock_logger is not None mock_logger.warning.assert_called_once() assert "Failed to update" in str(mock_logger.warning.call_args) -@pytest.mark.parametrize("scenario,expected_result,expected_exception", [ - ( - "success_with_sync", - "test-db-guardrail", - None - ), - ( - "success_sync_fails", - "test-db-guardrail", - None - ), - ( - "database_failure", - None, - HTTPException - ), - ( - "no_prisma_client", - None, - HTTPException - ), -], ids=[ - "success_with_immediate_sync", - "success_but_sync_fails", - "database_error", - "missing_prisma_client" -]) + +@pytest.mark.parametrize( + "scenario,expected_result,expected_exception", + [ + ("success_with_sync", "test-db-guardrail", None), + ("success_sync_fails", "test-db-guardrail", None), + ("database_failure", None, HTTPException), + ("no_prisma_client", None, HTTPException), + ], + ids=[ + "success_with_immediate_sync", + "success_but_sync_fails", + "database_error", + "missing_prisma_client", + ], +) @pytest.mark.asyncio async def test_patch_guardrail_endpoint( - scenario, expected_result, expected_exception, - mocker, mock_guardrail_registry, mock_in_memory_handler + scenario, + expected_result, + expected_exception, + mocker, + mock_guardrail_registry, + mock_in_memory_handler, + mock_admin_user_auth, ): """Test patch_guardrail endpoint with different scenarios""" - + # Configure mocks based on scenario mock_logger = None if scenario == "success_with_sync": mock_prisma_client = mocker.Mock() mock_in_memory_handler.sync_guardrail_from_db = mocker.Mock() mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "success_sync_fails": mock_prisma_client = mocker.Mock() - mock_in_memory_handler.sync_guardrail_from_db = mocker.Mock(side_effect=Exception("Sync failed")) - mock_logger = mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger") - + mock_in_memory_handler.sync_guardrail_from_db = mocker.Mock( + side_effect=Exception("Sync failed") + ) + mock_logger = mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger" + ) + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "database_failure": mock_prisma_client = mocker.Mock() - mock_guardrail_registry.update_guardrail_in_db.side_effect = Exception("Database error") - - mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - + mock_guardrail_registry.update_guardrail_in_db.side_effect = Exception( + "Database error" + ) + + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + elif scenario == "no_prisma_client": mocker.patch("litellm.proxy.proxy_server.prisma_client", None) - + # Run the test if expected_exception: with pytest.raises(expected_exception) as exc_info: - await patch_guardrail("test-guardrail-id", MOCK_PATCH_REQUEST) - + await patch_guardrail( + "test-guardrail-id", + MOCK_PATCH_REQUEST, + user_api_key_dict=mock_admin_user_auth, + ) + if scenario == "database_failure": assert "Database error" in str(exc_info.value.detail) elif scenario == "no_prisma_client": assert "Prisma client not initialized" in str(exc_info.value.detail) - + else: - result = await patch_guardrail("test-guardrail-id", MOCK_PATCH_REQUEST) - + result = await patch_guardrail( + "test-guardrail-id", + MOCK_PATCH_REQUEST, + user_api_key_dict=mock_admin_user_auth, + ) + assert result["guardrail_id"] == expected_result assert result["guardrail_name"] == "Test DB Guardrail" - + mock_guardrail_registry.update_guardrail_in_db.assert_called_once() - + mock_in_memory_handler.sync_guardrail_from_db.assert_called_once_with( guardrail=mocker.ANY ) - + if scenario == "success_sync_fails": assert mock_logger is not None mock_logger.warning.assert_called_once() assert "Failed to update" in str(mock_logger.warning.call_args) -@pytest.mark.parametrize("scenario,expected_result,expected_exception", [ - ( - "success_with_sync", - "test-db-guardrail", - None - ), - ( - "success_sync_fails", - "test-db-guardrail", - None - ), -], ids=[ - "success_with_immediate_sync", - "success_but_sync_fails" -]) + +@pytest.mark.parametrize( + "scenario,expected_result,expected_exception", + [ + ("success_with_sync", "test-db-guardrail", None), + ("success_sync_fails", "test-db-guardrail", None), + ], + ids=["success_with_immediate_sync", "success_but_sync_fails"], +) @pytest.mark.asyncio async def test_delete_guardrail_endpoint( - scenario, expected_result, expected_exception, - mocker, mock_guardrail_registry, mock_in_memory_handler + scenario, + expected_result, + expected_exception, + mocker, + mock_guardrail_registry, + mock_in_memory_handler, + mock_admin_user_auth, ): """Test delete_guardrail endpoint with different scenarios""" - + # Configure mocks based on scenario mock_prisma_client = mocker.Mock() mock_logger = None - + if scenario == "success_with_sync": mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + elif scenario == "success_sync_fails": - mock_in_memory_handler.delete_in_memory_guardrail.side_effect = Exception("Sync failed") - mock_logger = mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger") + mock_in_memory_handler.delete_in_memory_guardrail.side_effect = Exception( + "Sync failed" + ) + mock_logger = mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.verbose_proxy_logger" + ) mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_guardrail_registry) - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_guardrail_registry, + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + if expected_exception: with pytest.raises(expected_exception): - await delete_guardrail(guardrail_id=expected_result) + await delete_guardrail( + guardrail_id=expected_result, user_api_key_dict=mock_admin_user_auth + ) else: - result = await delete_guardrail(guardrail_id=expected_result) - + result = await delete_guardrail( + guardrail_id=expected_result, user_api_key_dict=mock_admin_user_auth + ) + assert result == MOCK_DB_GUARDRAIL - + mock_guardrail_registry.get_guardrail_by_id_from_db.assert_called_once_with( - guardrail_id=expected_result, - prisma_client=mock_prisma_client + guardrail_id=expected_result, prisma_client=mock_prisma_client ) mock_guardrail_registry.delete_guardrail_from_db.assert_called_once_with( - guardrail_id=expected_result, - prisma_client=mock_prisma_client + guardrail_id=expected_result, prisma_client=mock_prisma_client ) - + mock_in_memory_handler.delete_in_memory_guardrail.assert_called_once_with( guardrail_id=expected_result ) - + if scenario == "success_sync_fails": assert mock_logger is not None mock_logger.warning.assert_called_once() @@ -877,21 +974,22 @@ async def test_apply_guardrail_not_found(mocker): # Mock the GUARDRAIL_REGISTRY to return None (guardrail not found) mock_registry = mocker.Mock() mock_registry.get_initialized_guardrail_callback.return_value = None - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) + # Create request request = ApplyGuardrailRequest( - guardrail_name="non-existent-guardrail", - text="Test input text" + guardrail_name="non-existent-guardrail", text="Test input text" ) - + # Mock user auth mock_user_auth = UserAPIKeyAuth() - + # Call endpoint and expect ProxyException with pytest.raises(ProxyException) as exc_info: await apply_guardrail(request=request, user_api_key_dict=mock_user_auth) - + # Verify error details assert str(exc_info.value.code) == "404" assert "not found" in str(exc_info.value.message).lower() @@ -909,30 +1007,34 @@ async def test_apply_guardrail_execution_error(mocker): mock_guardrail.apply_guardrail = AsyncMock( side_effect=Exception("Bedrock guardrail failed: Violated guardrail policy") ) - + # Mock the GUARDRAIL_REGISTRY mock_registry = mocker.Mock() mock_registry.get_initialized_guardrail_callback.return_value = mock_guardrail - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry) - + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) + # Create request request = ApplyGuardrailRequest( - guardrail_name="test-guardrail", - text="Test input text with forbidden content" + guardrail_name="test-guardrail", text="Test input text with forbidden content" ) - + # Mock user auth mock_user_auth = UserAPIKeyAuth() - + # Call endpoint and expect ProxyException with pytest.raises(ProxyException) as exc_info: await apply_guardrail(request=request, user_api_key_dict=mock_user_auth) - + # Verify error is properly handled assert "Bedrock guardrail failed" in str(exc_info.value.message) + @pytest.mark.asyncio -async def test_get_guardrail_info_endpoint_config_guardrail(mocker): +async def test_get_guardrail_info_endpoint_config_guardrail( + mocker, mock_admin_user_auth +): """ Test get_guardrail_info endpoint returns proper response when guardrail is found in config. """ @@ -945,21 +1047,28 @@ async def test_get_guardrail_info_endpoint_config_guardrail(mocker): # Mock the GUARDRAIL_REGISTRY to return None from DB (so it checks config) mock_registry = mocker.Mock() mock_registry.get_guardrail_by_id_from_db = AsyncMock(return_value=None) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) # Mock IN_MEMORY_GUARDRAIL_HANDLER at its source to return config guardrail mock_in_memory_handler = mocker.Mock() mock_in_memory_handler.get_guardrail_by_id.return_value = MOCK_CONFIG_GUARDRAIL - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) # Mock _get_masked_values to return values as-is mocker.patch( "litellm.litellm_core_utils.litellm_logging._get_masked_values", - side_effect=lambda x, **kwargs: x + side_effect=lambda x, **kwargs: x, ) # Call endpoint and expect GuardrailInfoResponse - result = await get_guardrail_info(guardrail_id="test-config-guardrail") + result = await get_guardrail_info( + guardrail_id="test-config-guardrail", user_api_key_dict=mock_admin_user_auth + ) # Verify the response is of the correct type assert isinstance(result, GuardrailInfoResponse) @@ -967,8 +1076,9 @@ async def test_get_guardrail_info_endpoint_config_guardrail(mocker): assert result.guardrail_name == "Test Config Guardrail" assert result.guardrail_definition_location == "config" + @pytest.mark.asyncio -async def test_get_guardrail_info_endpoint_db_guardrail(mocker): +async def test_get_guardrail_info_endpoint_db_guardrail(mocker, mock_admin_user_auth): """ Test get_guardrail_info endpoint returns proper response when guardrail is found in DB. """ @@ -980,19 +1090,28 @@ async def test_get_guardrail_info_endpoint_db_guardrail(mocker): # Mock the GUARDRAIL_REGISTRY to return a guardrail from DB mock_registry = mocker.Mock() - mock_registry.get_guardrail_by_id_from_db = AsyncMock(return_value=MOCK_DB_GUARDRAIL) - mocker.patch("litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry) + mock_registry.get_guardrail_by_id_from_db = AsyncMock( + return_value=MOCK_DB_GUARDRAIL + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) # Mock IN_MEMORY_GUARDRAIL_HANDLER to return None mock_in_memory_handler = mocker.Mock() mock_in_memory_handler.get_guardrail_by_id.return_value = None - mocker.patch("litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", mock_in_memory_handler) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) # Call endpoint and expect GuardrailInfoResponse - result = await get_guardrail_info(guardrail_id="test-db-guardrail") + result = await get_guardrail_info( + guardrail_id="test-db-guardrail", user_api_key_dict=mock_admin_user_auth + ) # Verify the response is of the correct type assert isinstance(result, GuardrailInfoResponse) assert result.guardrail_id == "test-db-guardrail" assert result.guardrail_name == "Test DB Guardrail" - assert result.guardrail_definition_location == "db" \ No newline at end of file + assert result.guardrail_definition_location == "db" diff --git a/tests/test_litellm/proxy/guardrails/test_guardrail_team_access.py b/tests/test_litellm/proxy/guardrails/test_guardrail_team_access.py new file mode 100644 index 00000000000..e09a9ae2f0f --- /dev/null +++ b/tests/test_litellm/proxy/guardrails/test_guardrail_team_access.py @@ -0,0 +1,295 @@ +import pytest +import sys +import os +from unittest.mock import AsyncMock +from fastapi import HTTPException + +# Add repo root to path +sys.path.insert(0, os.path.abspath("../../../../..")) + +from litellm.proxy.guardrails.guardrail_endpoints import ( + create_guardrail, + update_guardrail, + list_guardrails, +) +from litellm.types.guardrails import ( + CreateGuardrailRequest, + UpdateGuardrailRequest, +) + +from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth + + +# Fixtures +@pytest.fixture +def mock_team_user_auth(): + return UserAPIKeyAuth(user_role=LitellmUserRoles.TEAM, team_id="team-123") + + +@pytest.fixture +def mock_other_team_user_auth(): + return UserAPIKeyAuth(user_role=LitellmUserRoles.TEAM, team_id="team-456") + + +@pytest.fixture +def mock_proxy_admin_auth(): + return UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, team_id="team-123") + + +@pytest.fixture +def mock_prisma_client(mocker): + return mocker.Mock() + + +@pytest.fixture +def mock_in_memory_handler(mocker): + mock = mocker.Mock() + mock.get_guardrail_by_id.return_value = None + mock.list_in_memory_guardrails.return_value = [] + return mock + + +def _make_mock_team(mocker, allow_team_guardrail_config: bool): + """Create a mock team object for get_team_object. Used by guardrail permission checks.""" + team = mocker.Mock() + team.allow_team_guardrail_config = allow_team_guardrail_config + return team + + +@pytest.mark.asyncio +async def test_team_list_guardrails_v2_isolation( + mocker, + mock_prisma_client, + mock_in_memory_handler, + mock_team_user_auth, + mock_other_team_user_auth, +): + """Test that teams only see their own guardrails in list endpoint""" + # Setup mocks + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory_handler, + ) + + async def mock_get_all_guardrails(prisma_client=None, team_id=None): + all_guardrails = [ + { + "guardrail_id": "g1", + "guardrail_name": "G1", + "team_id": "team-123", + "guardrail_config": {}, + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + }, + { + "guardrail_id": "g2", + "guardrail_name": "G2", + "team_id": "team-456", + "guardrail_config": {}, + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + }, + { + "guardrail_id": "g3", + "guardrail_name": "G3", + "team_id": None, + "guardrail_config": {}, + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + }, + ] + if team_id: + return [g for g in all_guardrails if g["team_id"] == team_id] + return all_guardrails + + mock_registry = mocker.Mock() + mock_registry.get_all_guardrails_from_db = AsyncMock( + side_effect=mock_get_all_guardrails + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) + + # Test for Team 123 + response_123 = await list_guardrails(user_api_key_dict=mock_team_user_auth) + assert len(response_123.guardrails) == 1 + assert response_123.guardrails[0].guardrail_id == "g1" + + # Test for Team 456 + response_456 = await list_guardrails(user_api_key_dict=mock_other_team_user_auth) + assert len(response_456.guardrails) == 1 + assert response_456.guardrails[0].guardrail_id == "g2" + + +@pytest.mark.asyncio +async def test_team_create_guardrail_sets_team_id( + mocker, mock_prisma_client, mock_team_user_auth +): + """Test that creating a guardrail as a team user sets the team_id when team has allow_team_guardrail_config.""" + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + + # Team user must have allow_team_guardrail_config=True to create guardrails + mock_team = _make_mock_team(mocker, allow_team_guardrail_config=True) + mocker.patch( + "litellm.proxy.auth.auth_checks.get_team_object", + AsyncMock(return_value=mock_team), + ) + + mock_registry = mocker.Mock() + mock_registry.get_guardrail_by_name_from_db = AsyncMock(return_value=None) + + async def mock_add_guardrail(guardrail, team_id=None, **kwargs): + return { + "guardrail_id": "new-g", + "guardrail_name": guardrail["guardrail_name"], + "team_id": team_id, + "created_at": "2024-01-01T00:00:00.000Z", + "updated_at": "2024-01-01T00:00:00.000Z", + } + + mock_registry.add_guardrail_to_db = AsyncMock(side_effect=mock_add_guardrail) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) + + # Mock initialize_guardrail which is called after success + # NOTE: The endpoint calls initialize_guardrail on IN_MEMORY_GUARDRAIL_HANDLER imported from guardrail_registry + mock_in_memory = mocker.Mock() + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory, + ) + + request = CreateGuardrailRequest( + guardrail={ + "guardrail_name": "New Team Guardrail", + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + "guardrail_info": {}, + } + ) + + response = await create_guardrail( + request=request, user_api_key_dict=mock_team_user_auth + ) + + mock_registry.add_guardrail_to_db.assert_called_once() + call_kwargs = mock_registry.add_guardrail_to_db.call_args[1] + assert call_kwargs["team_id"] == "team-123" + assert response["team_id"] == "team-123" + + +@pytest.mark.asyncio +async def test_team_update_other_team_guardrail_fails( + mocker, mock_prisma_client, mock_team_user_auth +): + """Test that a team user cannot update another team's guardrail""" + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + + mock_registry = mocker.Mock() + + async def mock_get_by_id(guardrail_id, **kwargs): + g = { + "guardrail_id": "g2", + "guardrail_name": "G2", + "team_id": "team-456", + "guardrail_config": {}, + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + } + if g["guardrail_id"] == guardrail_id: + return g + return None + + mock_registry.get_guardrail_by_id_from_db = AsyncMock(side_effect=mock_get_by_id) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", mock_registry + ) + + request = UpdateGuardrailRequest( + guardrail={ + "guardrail_name": "Updated Name", + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + } + ) + + # Team 123 tries to update G2 (owned by 456) + with pytest.raises(HTTPException) as excinfo: + await update_guardrail( + guardrail_id="g2", request=request, user_api_key_dict=mock_team_user_auth + ) + + assert excinfo.value.status_code == 403 + + +# ----- Regression tests for allow_team_guardrail_config ----- + + +@pytest.mark.asyncio +async def test_team_create_guardrail_forbidden_when_allow_team_guardrail_config_false( + mocker, mock_prisma_client, mock_team_user_auth +): + """Team user gets 403 when team has allow_team_guardrail_config=False.""" + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + + mock_team = _make_mock_team(mocker, allow_team_guardrail_config=False) + mocker.patch( + "litellm.proxy.auth.auth_checks.get_team_object", + AsyncMock(return_value=mock_team), + ) + + request = CreateGuardrailRequest( + guardrail={ + "guardrail_name": "Forbidden Guardrail", + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + "guardrail_info": {}, + } + ) + + with pytest.raises(HTTPException) as excinfo: + await create_guardrail(request=request, user_api_key_dict=mock_team_user_auth) + + assert excinfo.value.status_code == 403 + assert "Guardrail configuration is not enabled" in str(excinfo.value.detail) + + +@pytest.mark.asyncio +async def test_proxy_admin_can_create_guardrail_without_team_guardrail_config_permission( + mocker, mock_prisma_client, mock_proxy_admin_auth +): + """Proxy admin can create guardrails without team allow_team_guardrail_config (check is skipped).""" + mocker.patch("litellm.proxy.proxy_server.prisma_client", mock_prisma_client) + + mock_registry = mocker.Mock() + mock_registry.get_guardrail_by_name_from_db = AsyncMock(return_value=None) + mock_registry.add_guardrail_to_db = AsyncMock( + return_value={ + "guardrail_id": "admin-g", + "guardrail_name": "Admin Guardrail", + "team_id": "team-123", + "created_at": "2024-01-01T00:00:00.000Z", + "updated_at": "2024-01-01T00:00:00.000Z", + } + ) + mocker.patch( + "litellm.proxy.guardrails.guardrail_endpoints.GUARDRAIL_REGISTRY", + mock_registry, + ) + mock_in_memory = mocker.Mock() + mocker.patch( + "litellm.proxy.guardrails.guardrail_registry.IN_MEMORY_GUARDRAIL_HANDLER", + mock_in_memory, + ) + + # Do NOT mock get_team_object: proxy admin skips _check_team_can_configure_guardrails + request = CreateGuardrailRequest( + guardrail={ + "guardrail_name": "Admin Guardrail", + "litellm_params": {"guardrail": "bedrock", "mode": "pre_call"}, + "guardrail_info": {}, + } + ) + + response = await create_guardrail( + request=request, user_api_key_dict=mock_proxy_admin_auth + ) + + mock_registry.add_guardrail_to_db.assert_called_once() + assert response["guardrail_id"] == "admin-g" + assert response["team_id"] == "team-123" diff --git a/ui/litellm-dashboard/src/components/team/team_info.tsx b/ui/litellm-dashboard/src/components/team/team_info.tsx index 193d056fdd4..8996fee6637 100644 --- a/ui/litellm-dashboard/src/components/team/team_info.tsx +++ b/ui/litellm-dashboard/src/components/team/team_info.tsx @@ -96,6 +96,7 @@ export interface TeamData { model_aliases: Record; } | null; created_at: string; + allow_team_guardrail_config?: boolean; guardrails?: string[]; policies?: string[]; object_permission?: { @@ -466,6 +467,7 @@ const TeamInfoView: React.FC = ({ }, policies: values.policies || [], organization_id: values.organization_id, + ...(values.allow_team_guardrail_config !== undefined ? { allow_team_guardrail_config: values.allow_team_guardrail_config } : {}), }; updateData.max_budget = mapEmptyStringToNull(updateData.max_budget); @@ -658,6 +660,15 @@ const TeamInfoView: React.FC = ({ Guardrails + {info.allow_team_guardrail_config === true ? ( +
+ Team can configure guardrails +
+ ) : ( +
+ Only proxy admin can configure guardrails for this team +
+ )} {info.guardrails && info.guardrails.length > 0 ? (
{info.guardrails.map((guardrail: string, index: number) => ( @@ -761,6 +772,7 @@ const TeamInfoView: React.FC = ({ team_member_budget_duration: info.team_member_budget_table?.budget_duration, guardrails: info.metadata?.guardrails || [], policies: info.policies || [], + allow_team_guardrail_config: info.allow_team_guardrail_config ?? false, disable_global_guardrails: info.metadata?.disable_global_guardrails || false, metadata: info.metadata ? JSON.stringify( @@ -876,29 +888,72 @@ const TeamInfoView: React.FC = ({ + + prev.allow_team_guardrail_config !== cur.allow_team_guardrail_config + } + > + {() => { + const allowTeamGuardrailConfig = + form.getFieldValue("allow_team_guardrail_config"); + const guardrailsDisabled = + !is_proxy_admin && !allowTeamGuardrailConfig; + return ( + + Guardrails{" "} + + e.stopPropagation()} + > + + + + + } + name="guardrails" + help="Select existing guardrails or enter new ones" + > + ({ value: name, label: name }))} + From 04c348e7bb1a65078052fea4085ebeb586d5f5fb Mon Sep 17 00:00:00 2001 From: Harshit Jain <48647625+Harshit28j@users.noreply.github.com> Date: Tue, 3 Feb 2026 08:50:14 +0530 Subject: [PATCH 012/511] fixes failure metrics labels (#20152) Co-authored-by: Krish Dholakia --- litellm/integrations/prometheus.py | 169 ++++++++++++++++-- .../test_prometheus_logging_callbacks.py | 144 ++++++++------- 2 files changed, 230 insertions(+), 83 deletions(-) diff --git a/litellm/integrations/prometheus.py b/litellm/integrations/prometheus.py index 2c897cb0692..00c38eac188 100644 --- a/litellm/integrations/prometheus.py +++ b/litellm/integrations/prometheus.py @@ -1683,6 +1683,108 @@ class PrometheusLogger(CustomLogger): ) pass + def _safe_get(self, obj: Any, key: str, default: Any = None) -> Any: + """Get value from dict or Pydantic model.""" + if obj is None: + return default + if isinstance(obj, dict): + return obj.get(key, default) + return getattr(obj, key, default) + + def _extract_deployment_failure_label_values( + self, request_kwargs: dict + ) -> Dict[str, Optional[str]]: + """ + Extract label values for deployment failure metrics from all available + sources in request_kwargs. Falls back to litellm_params metadata and + user_api_key_auth when standard_logging_payload has None values. + """ + standard_logging_payload = ( + request_kwargs.get("standard_logging_object", {}) or {} + ) + _litellm_params = request_kwargs.get("litellm_params", {}) or {} + _metadata_raw = self._safe_get(standard_logging_payload, "metadata") or {} + if isinstance(_metadata_raw, dict): + _metadata = _metadata_raw + else: + _metadata = { + "user_api_key_alias": getattr( + _metadata_raw, "user_api_key_alias", None + ), + "user_api_key_team_id": getattr( + _metadata_raw, "user_api_key_team_id", None + ), + "user_api_key_team_alias": getattr( + _metadata_raw, "user_api_key_team_alias", None + ), + "user_api_key_hash": getattr(_metadata_raw, "user_api_key_hash", None), + "requester_ip_address": getattr( + _metadata_raw, "requester_ip_address", None + ), + "user_agent": getattr(_metadata_raw, "user_agent", None), + } + _litellm_params_metadata = _litellm_params.get("metadata", {}) or {} + + # Extract user_api_key_auth if present (proxy injects this, skipped in merge) + user_api_key_auth = _litellm_params_metadata.get("user_api_key_auth") + + def _get_api_key_alias() -> Optional[str]: + val = _metadata.get("user_api_key_alias") + if val is not None: + return val + val = _litellm_params_metadata.get("user_api_key_alias") + if val is not None: + return val + if user_api_key_auth is not None: + return getattr(user_api_key_auth, "key_alias", None) + return None + + def _get_team_id() -> Optional[str]: + val = _metadata.get("user_api_key_team_id") + if val is not None: + return val + val = _litellm_params_metadata.get("user_api_key_team_id") + if val is not None: + return val + if user_api_key_auth is not None: + return getattr(user_api_key_auth, "team_id", None) + return None + + def _get_team_alias() -> Optional[str]: + val = _metadata.get("user_api_key_team_alias") + if val is not None: + return val + val = _litellm_params_metadata.get("user_api_key_team_alias") + if val is not None: + return val + if user_api_key_auth is not None: + return getattr(user_api_key_auth, "team_alias", None) + return None + + def _get_hashed_api_key() -> Optional[str]: + val = _metadata.get("user_api_key_hash") + if val is not None: + return val + val = _litellm_params_metadata.get("user_api_key_hash") + if val is not None: + return val + if user_api_key_auth is not None: + return getattr(user_api_key_auth, "api_key", None) or getattr( + user_api_key_auth, "api_key_hash", None + ) + return None + + return { + "api_key_alias": _get_api_key_alias(), + "team": _get_team_id(), + "team_alias": _get_team_alias(), + "hashed_api_key": _get_hashed_api_key(), + "client_ip": _metadata.get("requester_ip_address") + or _litellm_params_metadata.get("requester_ip_address"), + "user_agent": _metadata.get("user_agent") + or _litellm_params_metadata.get("user_agent"), + } + def set_llm_deployment_failure_metrics(self, request_kwargs: dict): """ Sets Failure metrics when an LLM API call fails @@ -1707,6 +1809,21 @@ class PrometheusLogger(CustomLogger): model_id = standard_logging_payload.get("model_id", None) exception = request_kwargs.get("exception", None) + # Fallback: model_id from litellm_metadata.model_info + if model_id is None: + _model_info = ( + (_litellm_params.get("litellm_metadata") or {}).get("model_info") + or (_litellm_params.get("metadata") or {}).get("model_info") + or {} + ) + model_id = _model_info.get("id") + + # Fallback: model_group from litellm_metadata + if model_group is None: + model_group = (_litellm_params.get("litellm_metadata") or {}).get( + "model_group" + ) or (_litellm_params.get("metadata") or {}).get("model_group") + llm_provider = _litellm_params.get("custom_llm_provider", None) if self._should_skip_metrics_for_invalid_key( @@ -1714,9 +1831,37 @@ class PrometheusLogger(CustomLogger): standard_logging_payload=standard_logging_payload, ): return - hashed_api_key = standard_logging_payload.get("metadata", {}).get( + + # Extract context labels from all available sources (fix for None labels) + fallback_values = self._extract_deployment_failure_label_values( + request_kwargs + ) + _metadata = standard_logging_payload.get("metadata", {}) or {} + hashed_api_key = fallback_values.get("hashed_api_key") or _metadata.get( "user_api_key_hash" ) + api_key_alias = fallback_values.get("api_key_alias") or _metadata.get( + "user_api_key_alias" + ) + team = fallback_values.get("team") or _metadata.get("user_api_key_team_id") + team_alias = fallback_values.get("team_alias") or _metadata.get( + "user_api_key_team_alias" + ) + client_ip = fallback_values.get("client_ip") or _metadata.get( + "requester_ip_address" + ) + user_agent = fallback_values.get("user_agent") or _metadata.get( + "user_agent" + ) + + # exception_status: prefer status_code, fallback to exception class for known types + exception_status = None + if exception is not None: + exception_status = str(getattr(exception, "status_code", None)) + if exception_status == "None" or not exception_status: + code = getattr(exception, "code", None) + if code is not None: + exception_status = str(code) # Create enum_values for the label factory (always create for use in different metrics) enum_values = UserAPIKeyLabelValues( @@ -1724,26 +1869,18 @@ class PrometheusLogger(CustomLogger): model_id=model_id, api_base=api_base, api_provider=llm_provider, - exception_status=( - str(getattr(exception, "status_code", None)) if exception else None - ), + exception_status=exception_status, exception_class=( self._get_exception_class_name(exception) if exception else None ), - requested_model=model_group, + requested_model=model_group or litellm_model_name, hashed_api_key=hashed_api_key, - api_key_alias=standard_logging_payload["metadata"][ - "user_api_key_alias" - ], - team=standard_logging_payload["metadata"]["user_api_key_team_id"], - team_alias=standard_logging_payload["metadata"][ - "user_api_key_team_alias" - ], + api_key_alias=api_key_alias, + team=team, + team_alias=team_alias, tags=standard_logging_payload.get("request_tags", []), - client_ip=standard_logging_payload["metadata"].get( - "requester_ip_address" - ), - user_agent=standard_logging_payload["metadata"].get("user_agent"), + client_ip=client_ip, + user_agent=user_agent, ) """ diff --git a/tests/enterprise/litellm_enterprise/enterprise_callbacks/test_prometheus_logging_callbacks.py b/tests/enterprise/litellm_enterprise/enterprise_callbacks/test_prometheus_logging_callbacks.py index 0a57d046c72..c39454728a8 100644 --- a/tests/enterprise/litellm_enterprise/enterprise_callbacks/test_prometheus_logging_callbacks.py +++ b/tests/enterprise/litellm_enterprise/enterprise_callbacks/test_prometheus_logging_callbacks.py @@ -1,4 +1,3 @@ -import io import os import sys @@ -10,13 +9,10 @@ from datetime import datetime, timedelta, timezone from unittest.mock import MagicMock, call, patch import pytest -from prometheus_client import REGISTRY, CollectorRegistry +from prometheus_client import REGISTRY import litellm -from litellm import completion from litellm._logging import verbose_logger -from litellm._uuid import uuid -from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler from litellm.types.utils import ( StandardLoggingHiddenParams, StandardLoggingMetadata, @@ -37,7 +33,6 @@ from litellm.proxy._types import UserAPIKeyAuth verbose_logger.setLevel(logging.DEBUG) litellm.set_verbose = True -import time @pytest.fixture @@ -293,7 +288,6 @@ async def test_increment_remaining_budget_metrics(prometheus_logger): ) as mock_get_team, patch( "litellm.proxy.auth.auth_checks.get_key_object" ) as mock_get_key: - mock_get_team.return_value = MagicMock(budget_reset_at=future_reset_time_team) mock_get_key.return_value = MagicMock(budget_reset_at=future_reset_time_key) @@ -648,25 +642,16 @@ async def test_async_log_failure_event(prometheus_logger): ) # litellm_llm_api_failed_requests_metric incremented - """ - Expected metrics - end_user_id, - user_api_key, - user_api_key_alias, - model, - user_api_team, - user_api_team_alias, - user_id, - """ + # Labels: end_user, api_key_hash, api_key_alias, model, team, team_alias, user, model_id prometheus_logger.litellm_llm_api_failed_requests_metric.labels.assert_called_once_with( - None, + None, # end_user_id "test_hash", "test_alias", "gpt-3.5-turbo", "test_team", "test_team_alias", "test_user", - "model-123", + "model-123", # model_id from standard_logging_payload ) prometheus_logger.litellm_llm_api_failed_requests_metric.labels().inc.assert_called_once() @@ -678,38 +663,54 @@ async def test_async_log_failure_event(prometheus_logger): api_provider="openai", ) - # deployment failure responses incremented - prometheus_logger.litellm_deployment_failure_responses.labels.assert_called_once_with( - litellm_model_name="gpt-3.5-turbo", - model_id="model-123", - api_base="https://api.openai.com", - api_provider="openai", - exception_status="None", - exception_class="Exception", - requested_model="openai-gpt", # passed in standard logging payload - hashed_api_key="test_hash", - api_key_alias="test_alias", - team="test_team", - team_alias="test_team_alias", - client_ip="127.0.0.1", # from standard logging payload - user_agent=None, + # deployment failure responses incremented - verify key labels are populated + prometheus_logger.litellm_deployment_failure_responses.labels.assert_called_once() + actual_failure_labels = ( + prometheus_logger.litellm_deployment_failure_responses.labels.call_args.kwargs ) + expected_failure_labels = { + "litellm_model_name": "gpt-3.5-turbo", + "model_id": "model-123", + "api_base": "https://api.openai.com", + "api_provider": "openai", + "exception_class": "Exception", + "requested_model": "openai-gpt", + "hashed_api_key": "test_hash", + "api_key_alias": "test_alias", + "team": "test_team", + "team_alias": "test_team_alias", + } + for key, expected_val in expected_failure_labels.items(): + assert key in actual_failure_labels, f"Missing label {key}" + assert ( + actual_failure_labels[key] == expected_val + ), f"Label {key}: expected {expected_val!r}, got {actual_failure_labels[key]!r}" + assert actual_failure_labels.get("exception_status") in ("None", None) + assert actual_failure_labels.get("client_ip") == "127.0.0.1" prometheus_logger.litellm_deployment_failure_responses.labels().inc.assert_called_once() - # deployment total requests incremented - prometheus_logger.litellm_deployment_total_requests.labels.assert_called_once_with( - litellm_model_name="gpt-3.5-turbo", - model_id="model-123", - api_base="https://api.openai.com", - api_provider="openai", - requested_model="openai-gpt", # passed in standard logging payload - hashed_api_key="test_hash", - api_key_alias="test_alias", - team="test_team", - team_alias="test_team_alias", - client_ip="127.0.0.1", # from standard logging payload - user_agent=None, + # deployment total requests incremented - verify key labels are populated + prometheus_logger.litellm_deployment_total_requests.labels.assert_called_once() + actual_total_labels = ( + prometheus_logger.litellm_deployment_total_requests.labels.call_args.kwargs ) + expected_total_labels = { + "litellm_model_name": "gpt-3.5-turbo", + "model_id": "model-123", + "api_base": "https://api.openai.com", + "api_provider": "openai", + "requested_model": "openai-gpt", + "hashed_api_key": "test_hash", + "api_key_alias": "test_alias", + "team": "test_team", + "team_alias": "test_team_alias", + } + for key, expected_val in expected_total_labels.items(): + assert key in actual_total_labels, f"Missing label {key}" + assert ( + actual_total_labels[key] == expected_val + ), f"Label {key}: expected {expected_val!r}, got {actual_total_labels[key]!r}" + assert actual_total_labels.get("client_ip") == "127.0.0.1" prometheus_logger.litellm_deployment_total_requests.labels().inc.assert_called_once() @@ -1095,7 +1096,7 @@ def test_increment_deployment_cooled_down(prometheus_logger): import inspect method_sig = inspect.signature(prometheus_logger.increment_deployment_cooled_down) - expected_label_count = len([p for p in method_sig.parameters.keys() if p != 'self']) + expected_label_count = len([p for p in method_sig.parameters.keys() if p != "self"]) mock_chain = MagicMock() @@ -1103,11 +1104,15 @@ def test_increment_deployment_cooled_down(prometheus_logger): """Validate label count matches metric definition""" total = len(label_values) + len(label_kwargs) if total != expected_label_count: - raise ValueError(f"Incorrect label count: expected {expected_label_count}, got {total}") + raise ValueError( + f"Incorrect label count: expected {expected_label_count}, got {total}" + ) return mock_chain prometheus_logger.litellm_deployment_cooled_down = MagicMock() - prometheus_logger.litellm_deployment_cooled_down.labels = MagicMock(side_effect=validating_labels) + prometheus_logger.litellm_deployment_cooled_down.labels = MagicMock( + side_effect=validating_labels + ) prometheus_logger.increment_deployment_cooled_down( litellm_model_name="gpt-3.5-turbo", @@ -1179,8 +1184,12 @@ def test_get_custom_labels_from_top_level_metadata(monkeypatch): metadata = { "requester_ip_address": "10.48.203.20", # Top-level field "user_api_key_alias": "TestAlias", # Top-level field - "requester_metadata": {"nested_field": "nested_value"}, # Nested dict (excluded) - "user_api_key_auth_metadata": {"another_nested": "value"}, # Nested dict (excluded) + "requester_metadata": { + "nested_field": "nested_value" + }, # Nested dict (excluded) + "user_api_key_auth_metadata": { + "another_nested": "value" + }, # Nested dict (excluded) } result = get_custom_labels_from_metadata(metadata) assert result == { @@ -1217,7 +1226,9 @@ def test_get_custom_labels_from_top_level_and_nested_metadata(monkeypatch): } -async def test_async_log_success_event_with_top_level_metadata(prometheus_logger, monkeypatch): +async def test_async_log_success_event_with_top_level_metadata( + prometheus_logger, monkeypatch +): """ Test that async_log_success_event correctly extracts custom labels from top-level metadata fields like requester_ip_address, not just from nested dictionaries. @@ -1231,7 +1242,9 @@ async def test_async_log_success_event_with_top_level_metadata(prometheus_logger standard_logging_object = create_standard_logging_payload() standard_logging_object["metadata"]["requester_ip_address"] = "10.48.203.20" standard_logging_object["metadata"]["requester_metadata"] = {} # Empty nested dict - standard_logging_object["metadata"]["user_api_key_auth_metadata"] = {} # Empty nested dict + standard_logging_object["metadata"][ + "user_api_key_auth_metadata" + ] = {} # Empty nested dict kwargs = { "model": "gpt-3.5-turbo", @@ -1273,7 +1286,9 @@ async def test_async_log_success_event_with_top_level_metadata(prometheus_logger prometheus_logger.litellm_remaining_user_budget_metric = create_mock_metric() prometheus_logger.litellm_user_max_budget_metric = create_mock_metric() prometheus_logger.litellm_user_budget_remaining_hours_metric = create_mock_metric() - prometheus_logger.litellm_remaining_api_key_requests_for_model = create_mock_metric() + prometheus_logger.litellm_remaining_api_key_requests_for_model = ( + create_mock_metric() + ) prometheus_logger.litellm_remaining_api_key_tokens_for_model = create_mock_metric() prometheus_logger.litellm_llm_api_time_to_first_token_metric = create_mock_metric() prometheus_logger.litellm_llm_api_latency_metric = create_mock_metric() @@ -1302,7 +1317,7 @@ async def test_async_log_success_event_with_top_level_metadata(prometheus_logger # This confirms that the custom label extraction logic ran without errors assert prometheus_logger.litellm_requests_metric.labels.called assert prometheus_logger.litellm_spend_metric.labels.called - + # Verify that the labels() method was called with some arguments (either positional or keyword) # This ensures the custom label extraction happened and didn't cause a "Incorrect label names" error call_args = prometheus_logger.litellm_requests_metric.labels.call_args @@ -1494,7 +1509,6 @@ async def test_initialize_remaining_budget_metrics(prometheus_logger): with patch("litellm.proxy.proxy_server.prisma_client") as mock_prisma, patch( "litellm.proxy.management_endpoints.team_endpoints.get_paginated_teams" ) as mock_get_teams: - # Create mock team data with proper datetime objects for budget_reset_at future_reset = datetime.now() + timedelta(hours=24) # Reset 24 hours from now mock_teams = [ @@ -1592,21 +1606,22 @@ async def test_initialize_remaining_budget_metrics_exception_handling( ) as mock_get_teams, patch( "litellm.proxy.management_endpoints.key_management_endpoints._list_key_helper" ) as mock_list_keys: - # Make get_paginated_teams raise an exception mock_get_teams.side_effect = Exception("Database error") mock_list_keys.side_effect = Exception("Key listing error") - + # Mock prisma_client structure to raise an exception for user budget metrics # The code accesses prisma_client.db.litellm_usertable.find_many and count mock_usertable = MagicMock() - mock_usertable.find_many = MagicMock(side_effect=Exception("User database error")) + mock_usertable.find_many = MagicMock( + side_effect=Exception("User database error") + ) mock_usertable.count = MagicMock(side_effect=Exception("User count error")) - + # Mock litellm_teamtable to raise an exception for team count metrics mock_teamtable = MagicMock() mock_teamtable.count = MagicMock(side_effect=Exception("Team count error")) - + mock_db = MagicMock() mock_db.litellm_usertable = mock_usertable mock_db.litellm_teamtable = mock_teamtable @@ -1661,7 +1676,6 @@ async def test_initialize_api_key_budget_metrics(prometheus_logger): with patch("litellm.proxy.proxy_server.prisma_client") as mock_prisma, patch( "litellm.proxy.management_endpoints.key_management_endpoints._list_key_helper" ) as mock_list_keys: - # Create mock key data with proper datetime objects for budget_reset_at future_reset = datetime.now() + timedelta(hours=24) # Reset 24 hours from now key1 = UserAPIKeyAuth( @@ -1916,7 +1930,6 @@ def test_prometheus_label_factory_with_custom_tags(monkeypatch): Test that prometheus_label_factory correctly handles custom tags """ from litellm.integrations.prometheus import ( - get_custom_labels_from_tags, prometheus_label_factory, ) from litellm.types.integrations.prometheus import UserAPIKeyLabelValues @@ -1954,7 +1967,6 @@ def test_prometheus_label_factory_with_no_custom_tags(monkeypatch): Test that prometheus_label_factory works when no custom tags are configured """ from litellm.integrations.prometheus import ( - get_custom_labels_from_tags, prometheus_label_factory, ) from litellm.types.integrations.prometheus import UserAPIKeyLabelValues @@ -2179,9 +2191,7 @@ async def test_prometheus_token_metrics_with_prometheus_config(): All three metrics should be properly incremented when making a successful completion request. """ - from prometheus_client import CollectorRegistry, Counter - import litellm from litellm.types.integrations.prometheus import PrometheusMetricsConfig # Clear registry before test From f32bd8474e959b1ab1792e0c4a43ffa0fb115424 Mon Sep 17 00:00:00 2001 From: Felipe Rodrigues Gare Carnielli Date: Tue, 3 Feb 2026 00:25:58 -0300 Subject: [PATCH 013/511] adding together ai models to litellm models json --- model_prices_and_context_window.json | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json index 485bee4f191..a7962643e40 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -27113,6 +27113,34 @@ "supports_reasoning": true, "supports_tool_choice": true }, + "together_ai/zai-org/GLM-4.7": { + "input_cost_per_token": 45e-07, + "litellm_provider": "together_ai", + "max_input_tokens": 200000, + "max_output_tokens": 200000, + "max_tokens": 200000, + "mode": "chat", + "output_cost_per_token": 2e-06, + "source": "https://www.together.ai/models/glm-4-7", + "supports_function_calling": true, + "supports_parallel_function_calling": true, + "supports_reasoning": true, + "supports_tool_choice": true + }, + "together_ai/moonshotai/Kimi-K2.5": { + "input_cost_per_token": 5e-07, + "litellm_provider": "together_ai", + "max_input_tokens": 256000, + "max_output_tokens": 256000, + "max_tokens": 256000, + "mode": "chat", + "output_cost_per_token": 2.8e-06, + "source": "https://www.together.ai/models/kimi-k2-5", + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_vision": true, + "supports_reasoning": true + }, "together_ai/moonshotai/Kimi-K2-Instruct-0905": { "input_cost_per_token": 1e-06, "litellm_provider": "together_ai", From ec279eb426d26e74c14b92101c61851537847579 Mon Sep 17 00:00:00 2001 From: Harshit Jain <48647625+Harshit28j@users.noreply.github.com> Date: Tue, 3 Feb 2026 08:56:50 +0530 Subject: [PATCH 014/511] fix: proxy failure cases, now log ip and user agent, key hash, name (#20145) --- litellm/integrations/prometheus.py | 30 +--- litellm/proxy/auth/auth_checks.py | 8 +- litellm/proxy/auth/auth_exception_handler.py | 65 ++++++-- litellm/proxy/auth/auth_utils.py | 145 ++++++++++++------ litellm/proxy/auth/user_api_key_auth.py | 14 +- litellm/proxy/utils.py | 10 +- .../test_prometheus_invalid_key_filtering.py | 134 ++++++++++------ 7 files changed, 272 insertions(+), 134 deletions(-) diff --git a/litellm/integrations/prometheus.py b/litellm/integrations/prometheus.py index 00c38eac188..d751e12460b 100644 --- a/litellm/integrations/prometheus.py +++ b/litellm/integrations/prometheus.py @@ -1478,35 +1478,19 @@ class PrometheusLogger(CustomLogger): """ Determine if a request has an invalid API key based on status code and exception. - This method prevents invalid authentication attempts from being recorded in - Prometheus metrics. A 401 status code is the definitive indicator of authentication - failure. Additionally, we check exception messages for authentication error patterns - to catch cases where the exception hasn't been converted to a ProxyException yet. + Returns True only when we truly cannot record useful metrics (e.g. missing required + data). We no longer skip 401/invalid-key requests - all requests including + authentication failures and bad requests must be tracked for debugging, security + auditing, abuse detection, and capacity planning. Args: - status_code: HTTP status code (401 indicates authentication error) - exception: Exception object to check for auth-related error messages + status_code: HTTP status code + exception: Exception object (unused, kept for API compatibility) Returns: - True if the request has an invalid API key and metrics should be skipped, + True if metrics should be skipped (currently always False - track all requests), False otherwise """ - if status_code == 401: - return True - - # Handle cases where AssertionError is raised before conversion to ProxyException - if exception is not None: - exception_str = str(exception).lower() - auth_error_patterns = [ - "virtual key expected", - "expected to start with 'sk-'", - "authentication error", - "invalid api key", - "api key not valid", - ] - if any(pattern in exception_str for pattern in auth_error_patterns): - return True - return False def _should_skip_metrics_for_invalid_key( diff --git a/litellm/proxy/auth/auth_checks.py b/litellm/proxy/auth/auth_checks.py index 359bb944546..85e44ebc827 100644 --- a/litellm/proxy/auth/auth_checks.py +++ b/litellm/proxy/auth/auth_checks.py @@ -198,7 +198,7 @@ async def common_checks( message=f"Team not allowed to access model. Team={team_object.team_id}, Model={_model}. Allowed team models = {team_object.models}", type=ProxyErrorTypes.team_model_access_denied, param="model", - code=status.HTTP_401_UNAUTHORIZED, + code=status.HTTP_400_BAD_REQUEST, ) ## 2.1 If user can call model (if personal key) @@ -2056,7 +2056,7 @@ def _can_object_call_model( object_type=object_type ), param="model", - code=status.HTTP_401_UNAUTHORIZED, + code=status.HTTP_400_BAD_REQUEST, ) @@ -2157,7 +2157,7 @@ async def can_user_call_model( message=f"User not allowed to access model. No default model access, only team models allowed. Tried to access {model}", type=ProxyErrorTypes.key_model_access_denied, param="model", - code=status.HTTP_401_UNAUTHORIZED, + code=status.HTTP_400_BAD_REQUEST, ) return _can_object_call_model( @@ -2739,7 +2739,7 @@ def _can_object_call_vector_stores( object_type ), param="vector_store", - code=status.HTTP_401_UNAUTHORIZED, + code=status.HTTP_400_BAD_REQUEST, ) return True diff --git a/litellm/proxy/auth/auth_exception_handler.py b/litellm/proxy/auth/auth_exception_handler.py index 9c306acd2c6..90378bd8f3a 100644 --- a/litellm/proxy/auth/auth_exception_handler.py +++ b/litellm/proxy/auth/auth_exception_handler.py @@ -9,7 +9,10 @@ from fastapi import HTTPException, Request, status import litellm from litellm._logging import verbose_proxy_logger from litellm.proxy._types import ProxyErrorTypes, ProxyException, UserAPIKeyAuth -from litellm.proxy.auth.auth_utils import _get_request_ip_address +from litellm.proxy.auth.auth_utils import ( + _get_request_ip_address, + add_client_context_to_request_data, +) from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler from litellm.types.services import ServiceTypes @@ -30,6 +33,7 @@ class UserAPIKeyAuthExceptionHandler: route: str, parent_otel_span: Optional[Span], api_key: str, + valid_token: Optional[UserAPIKeyAuth] = None, ) -> UserAPIKeyAuth: """ Handles Connection Errors when reading a Virtual Key from LiteLLM DB @@ -71,30 +75,63 @@ class UserAPIKeyAuthExceptionHandler: ) else: # raise the exception to the caller + use_x_forwarded_for = general_settings.get("use_x_forwarded_for", False) requester_ip = _get_request_ip_address( request=request, - use_x_forwarded_for=general_settings.get("use_x_forwarded_for", False), + use_x_forwarded_for=use_x_forwarded_for, ) - verbose_proxy_logger.exception( - "litellm.proxy.proxy_server.user_api_key_auth(): Exception occured - {}\nRequester IP Address:{}".format( - str(e), - requester_ip, - ), - extra={"requester_ip": requester_ip}, + user_agent = request.headers.get("user-agent", "") if request else "" + + # Ensure request_data has client context for callbacks (Prometheus, etc.) + add_client_context_to_request_data( + request=request, + request_data=request_data, + use_x_forwarded_for=use_x_forwarded_for, ) - # Log this exception to OTEL, Datadog etc - user_api_key_dict = UserAPIKeyAuth( - parent_otel_span=parent_otel_span, - api_key=api_key, - request_route=route, + key_name = ( + valid_token.key_alias or getattr(valid_token, "key_name", None) + if valid_token + else "" ) + verbose_proxy_logger.exception( + "litellm.proxy.proxy_server.user_api_key_auth(): Exception occured - {}\nRequester IP Address:{}\nUser-Agent:{}\nKey Hash:{}\nKey Name:{}".format( + str(e), + requester_ip or "", + user_agent or "", + api_key or "", + key_name, + ), + extra={ + "requester_ip": requester_ip, + "user_agent": user_agent, + "key_hash": api_key, + "key_name": key_name, + }, + ) + + # Log this exception to OTEL, Datadog etc - use valid_token when available (e.g. model access denied) + if valid_token is not None: + user_api_key_dict = valid_token + else: + user_api_key_dict = UserAPIKeyAuth( + parent_otel_span=parent_otel_span, + api_key=api_key, + request_route=route, + key_alias="", + ) # Allow callbacks to transform the error response + error_type = ProxyErrorTypes.auth_error + if isinstance(e, ProxyException) and hasattr(e, "type"): + try: + error_type = ProxyErrorTypes(e.type) + except (ValueError, TypeError): + pass transformed_exception = await proxy_logging_obj.post_call_failure_hook( request_data=request_data, original_exception=e, user_api_key_dict=user_api_key_dict, - error_type=ProxyErrorTypes.auth_error, + error_type=error_type, route=route, ) # Use transformed exception if callback returned one, otherwise use original diff --git a/litellm/proxy/auth/auth_utils.py b/litellm/proxy/auth/auth_utils.py index 2bd84a1d98d..4049dcad14f 100644 --- a/litellm/proxy/auth/auth_utils.py +++ b/litellm/proxy/auth/auth_utils.py @@ -26,6 +26,28 @@ def _get_request_ip_address( return client_ip +def add_client_context_to_request_data( + request: Request, request_data: dict, use_x_forwarded_for: bool = False +) -> None: + """ + Add client_ip (requester_ip_address) and User-Agent to request_data metadata early. + Call this at the start of the request pipeline so failures have client context for logging. + """ + if "metadata" not in request_data: + request_data["metadata"] = {} + metadata = request_data["metadata"] + + requester_ip = _get_request_ip_address( + request=request, use_x_forwarded_for=use_x_forwarded_for + ) + metadata["requester_ip_address"] = requester_ip or "" + + user_agent = "" + if hasattr(request, "headers") and "user-agent" in request.headers: + user_agent = request.headers.get("user-agent", "") + metadata["user_agent"] = user_agent + + def _check_valid_ip( allowed_ips: Optional[List[str]], request: Request, @@ -314,17 +336,17 @@ def get_request_route(request: Request) -> str: def normalize_request_route(route: str) -> str: """ Normalize request routes by replacing dynamic path parameters with placeholders. - + This prevents high cardinality in Prometheus metrics by collapsing routes like: - /v1/responses/1234567890 -> /v1/responses/{response_id} - /v1/threads/thread_123 -> /v1/threads/{thread_id} - + Args: route: The request route path - + Returns: Normalized route with dynamic parameters replaced by placeholders - + Examples: >>> normalize_request_route("/v1/responses/abc123") '/v1/responses/{response_id}' @@ -337,58 +359,90 @@ def normalize_request_route(route: str) -> str: # Format: (regex_pattern, replacement_template) patterns = [ # Responses API - must come before generic patterns - (r'^(/(?:openai/)?v1/responses)/([^/]+)(/input_items)$', r'\1/{response_id}\3'), - (r'^(/(?:openai/)?v1/responses)/([^/]+)(/cancel)$', r'\1/{response_id}\3'), - (r'^(/(?:openai/)?v1/responses)/([^/]+)$', r'\1/{response_id}'), - (r'^(/responses)/([^/]+)(/input_items)$', r'\1/{response_id}\3'), - (r'^(/responses)/([^/]+)(/cancel)$', r'\1/{response_id}\3'), - (r'^(/responses)/([^/]+)$', r'\1/{response_id}'), - + (r"^(/(?:openai/)?v1/responses)/([^/]+)(/input_items)$", r"\1/{response_id}\3"), + (r"^(/(?:openai/)?v1/responses)/([^/]+)(/cancel)$", r"\1/{response_id}\3"), + (r"^(/(?:openai/)?v1/responses)/([^/]+)$", r"\1/{response_id}"), + (r"^(/responses)/([^/]+)(/input_items)$", r"\1/{response_id}\3"), + (r"^(/responses)/([^/]+)(/cancel)$", r"\1/{response_id}\3"), + (r"^(/responses)/([^/]+)$", r"\1/{response_id}"), # Threads API - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/steps)/([^/]+)$', r'\1/{thread_id}\3/{run_id}\5/{step_id}'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/steps)$', r'\1/{thread_id}\3/{run_id}\5'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/cancel)$', r'\1/{thread_id}\3/{run_id}\5'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/submit_tool_outputs)$', r'\1/{thread_id}\3/{run_id}\5'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)$', r'\1/{thread_id}\3/{run_id}'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/runs)$', r'\1/{thread_id}\3'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/messages)/([^/]+)$', r'\1/{thread_id}\3/{message_id}'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)(/messages)$', r'\1/{thread_id}\3'), - (r'^(/(?:openai/)?v1/threads)/([^/]+)$', r'\1/{thread_id}'), - + ( + r"^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/steps)/([^/]+)$", + r"\1/{thread_id}\3/{run_id}\5/{step_id}", + ), + ( + r"^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/steps)$", + r"\1/{thread_id}\3/{run_id}\5", + ), + ( + r"^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/cancel)$", + r"\1/{thread_id}\3/{run_id}\5", + ), + ( + r"^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)(/submit_tool_outputs)$", + r"\1/{thread_id}\3/{run_id}\5", + ), + ( + r"^(/(?:openai/)?v1/threads)/([^/]+)(/runs)/([^/]+)$", + r"\1/{thread_id}\3/{run_id}", + ), + (r"^(/(?:openai/)?v1/threads)/([^/]+)(/runs)$", r"\1/{thread_id}\3"), + ( + r"^(/(?:openai/)?v1/threads)/([^/]+)(/messages)/([^/]+)$", + r"\1/{thread_id}\3/{message_id}", + ), + (r"^(/(?:openai/)?v1/threads)/([^/]+)(/messages)$", r"\1/{thread_id}\3"), + (r"^(/(?:openai/)?v1/threads)/([^/]+)$", r"\1/{thread_id}"), # Vector Stores API - (r'^(/(?:openai/)?v1/vector_stores)/([^/]+)(/files)/([^/]+)$', r'\1/{vector_store_id}\3/{file_id}'), - (r'^(/(?:openai/)?v1/vector_stores)/([^/]+)(/files)$', r'\1/{vector_store_id}\3'), - (r'^(/(?:openai/)?v1/vector_stores)/([^/]+)(/file_batches)/([^/]+)$', r'\1/{vector_store_id}\3/{batch_id}'), - (r'^(/(?:openai/)?v1/vector_stores)/([^/]+)(/file_batches)$', r'\1/{vector_store_id}\3'), - (r'^(/(?:openai/)?v1/vector_stores)/([^/]+)$', r'\1/{vector_store_id}'), - + ( + r"^(/(?:openai/)?v1/vector_stores)/([^/]+)(/files)/([^/]+)$", + r"\1/{vector_store_id}\3/{file_id}", + ), + ( + r"^(/(?:openai/)?v1/vector_stores)/([^/]+)(/files)$", + r"\1/{vector_store_id}\3", + ), + ( + r"^(/(?:openai/)?v1/vector_stores)/([^/]+)(/file_batches)/([^/]+)$", + r"\1/{vector_store_id}\3/{batch_id}", + ), + ( + r"^(/(?:openai/)?v1/vector_stores)/([^/]+)(/file_batches)$", + r"\1/{vector_store_id}\3", + ), + (r"^(/(?:openai/)?v1/vector_stores)/([^/]+)$", r"\1/{vector_store_id}"), # Assistants API - (r'^(/(?:openai/)?v1/assistants)/([^/]+)$', r'\1/{assistant_id}'), - + (r"^(/(?:openai/)?v1/assistants)/([^/]+)$", r"\1/{assistant_id}"), # Files API - (r'^(/(?:openai/)?v1/files)/([^/]+)(/content)$', r'\1/{file_id}\3'), - (r'^(/(?:openai/)?v1/files)/([^/]+)$', r'\1/{file_id}'), - + (r"^(/(?:openai/)?v1/files)/([^/]+)(/content)$", r"\1/{file_id}\3"), + (r"^(/(?:openai/)?v1/files)/([^/]+)$", r"\1/{file_id}"), # Batches API - (r'^(/(?:openai/)?v1/batches)/([^/]+)(/cancel)$', r'\1/{batch_id}\3'), - (r'^(/(?:openai/)?v1/batches)/([^/]+)$', r'\1/{batch_id}'), - + (r"^(/(?:openai/)?v1/batches)/([^/]+)(/cancel)$", r"\1/{batch_id}\3"), + (r"^(/(?:openai/)?v1/batches)/([^/]+)$", r"\1/{batch_id}"), # Fine-tuning API - (r'^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)(/events)$', r'\1/{fine_tuning_job_id}\3'), - (r'^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)(/cancel)$', r'\1/{fine_tuning_job_id}\3'), - (r'^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)(/checkpoints)$', r'\1/{fine_tuning_job_id}\3'), - (r'^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)$', r'\1/{fine_tuning_job_id}'), - + ( + r"^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)(/events)$", + r"\1/{fine_tuning_job_id}\3", + ), + ( + r"^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)(/cancel)$", + r"\1/{fine_tuning_job_id}\3", + ), + ( + r"^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)(/checkpoints)$", + r"\1/{fine_tuning_job_id}\3", + ), + (r"^(/(?:openai/)?v1/fine_tuning/jobs)/([^/]+)$", r"\1/{fine_tuning_job_id}"), # Models API - (r'^(/(?:openai/)?v1/models)/([^/]+)$', r'\1/{model}'), + (r"^(/(?:openai/)?v1/models)/([^/]+)$", r"\1/{model}"), ] - + # Apply patterns in order for pattern, replacement in patterns: normalized = re.sub(pattern, replacement, route) if normalized != route: return normalized - + # Return original route if no pattern matched return route @@ -644,6 +698,7 @@ def get_customer_user_header_from_mapping(user_id_mapping) -> Optional[str]: return header_name return None + def _get_customer_id_from_standard_headers( request_headers: Optional[dict], ) -> Optional[str]: @@ -679,7 +734,9 @@ def get_end_user_id_from_request_body( from litellm.proxy.proxy_server import general_settings # Check 1: Standard customer ID headers (always checked, no configuration required) - customer_id = _get_customer_id_from_standard_headers(request_headers=request_headers) + customer_id = _get_customer_id_from_standard_headers( + request_headers=request_headers + ) if customer_id is not None: return customer_id diff --git a/litellm/proxy/auth/user_api_key_auth.py b/litellm/proxy/auth/user_api_key_auth.py index a153c6e51cc..e562b134818 100644 --- a/litellm/proxy/auth/user_api_key_auth.py +++ b/litellm/proxy/auth/user_api_key_auth.py @@ -42,6 +42,7 @@ from litellm.proxy.auth.auth_checks import ( from litellm.proxy.auth.auth_exception_handler import UserAPIKeyAuthExceptionHandler from litellm.proxy.auth.auth_utils import ( abbreviate_api_key, + add_client_context_to_request_data, get_end_user_id_from_request_body, get_model_from_request, get_request_route, @@ -247,7 +248,9 @@ async def get_global_proxy_spend( proxy_logging_obj: ProxyLogging, ) -> Optional[float]: global_proxy_spend = None - if litellm.max_budget > 0 and prisma_client is not None: # user set proxy max budget + if ( + litellm.max_budget > 0 and prisma_client is not None + ): # user set proxy max budget # Use event-driven coordination to prevent cache stampede cache_key = "{}:spend".format(litellm_proxy_admin_name) global_proxy_spend = await _fetch_global_spend_with_event_coordination( @@ -1251,6 +1254,7 @@ async def _user_api_key_auth_builder( # noqa: PLR0915 route=route, parent_otel_span=parent_otel_span, api_key=api_key, + valid_token=valid_token, ) @@ -1278,6 +1282,14 @@ async def user_api_key_auth( request_data = populate_request_with_path_params( request_data=request_data, request=request ) + # Capture client context early so failures have IP/User-Agent for logging and metrics + from litellm.proxy.proxy_server import general_settings + + add_client_context_to_request_data( + request=request, + request_data=request_data, + use_x_forwarded_for=general_settings.get("use_x_forwarded_for", False), + ) route: str = get_request_route(request=request) ## CHECK IF ROUTE IS ALLOWED diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py index 6bbf0df74de..9877825f671 100644 --- a/litellm/proxy/utils.py +++ b/litellm/proxy/utils.py @@ -1633,8 +1633,16 @@ class ProxyLogging: if RouteChecks.is_llm_api_route(route) is not True: return False + proxy_only_error_types = { + ProxyErrorTypes.auth_error, + ProxyErrorTypes.key_model_access_denied, + ProxyErrorTypes.team_model_access_denied, + ProxyErrorTypes.user_model_access_denied, + ProxyErrorTypes.org_model_access_denied, + ProxyErrorTypes.token_not_found_in_db, + } return isinstance(original_exception, HTTPException) or ( - error_type == ProxyErrorTypes.auth_error + error_type in proxy_only_error_types ) async def _handle_logging_proxy_only_error( diff --git a/tests/test_litellm/integrations/test_prometheus_invalid_key_filtering.py b/tests/test_litellm/integrations/test_prometheus_invalid_key_filtering.py index ff433480d5e..565b7f3ef7b 100644 --- a/tests/test_litellm/integrations/test_prometheus_invalid_key_filtering.py +++ b/tests/test_litellm/integrations/test_prometheus_invalid_key_filtering.py @@ -1,8 +1,8 @@ """ -Unit tests for Prometheus invalid API key request filtering. +Unit tests for Prometheus request tracking. -Tests functionality that prevents invalid API key requests (401 status codes) -from being recorded in Prometheus metrics. +Tests that all requests including 401/invalid-key failures are tracked in metrics +for debugging, security auditing, abuse detection, and capacity planning. """ import os @@ -29,12 +29,14 @@ def prometheus_logger(): class ExceptionWithCode: """Exception-like object with 'code' attribute (ProxyException pattern).""" + def __init__(self, code): self.code = code class ExceptionWithStatusCode: """Exception-like object with 'status_code' attribute.""" + def __init__(self, status_code): self.status_code = status_code @@ -42,17 +44,25 @@ class ExceptionWithStatusCode: class TestExtractStatusCode: """Test status code extraction from various sources.""" - @pytest.mark.parametrize("exception_class,code_value,expected", [ - (ExceptionWithCode, "401", 401), - (ExceptionWithStatusCode, 401, 401), - ]) - def test_extract_from_exception(self, prometheus_logger, exception_class, code_value, expected): + @pytest.mark.parametrize( + "exception_class,code_value,expected", + [ + (ExceptionWithCode, "401", 401), + (ExceptionWithStatusCode, 401, 401), + ], + ) + def test_extract_from_exception( + self, prometheus_logger, exception_class, code_value, expected + ): exception = exception_class(code_value) assert prometheus_logger._extract_status_code(exception=exception) == expected def test_extract_from_kwargs(self, prometheus_logger): exception = ExceptionWithCode("401") - assert prometheus_logger._extract_status_code(kwargs={"exception": exception}) == 401 + assert ( + prometheus_logger._extract_status_code(kwargs={"exception": exception}) + == 401 + ) def test_extract_from_enum_values(self, prometheus_logger): enum_values = Mock(status_code="401") @@ -60,45 +70,62 @@ class TestExtractStatusCode: class TestInvalidAPIKeyDetection: - """Test invalid API key request detection logic.""" + """Test that we no longer skip metrics - all requests are tracked.""" - @pytest.mark.parametrize("status_code,expected", [ - (401, True), - (200, False), - (500, False), - (None, False), - ]) - def test_status_code_detection(self, prometheus_logger, status_code, expected): - assert prometheus_logger._is_invalid_api_key_request(status_code=status_code) == expected + @pytest.mark.parametrize("status_code", [401, 200, 500, None]) + def test_no_skip_for_any_status_code(self, prometheus_logger, status_code): + """All status codes are tracked - never skip metrics.""" + assert ( + prometheus_logger._is_invalid_api_key_request(status_code=status_code) + is False + ) - def test_auth_error_message_detection(self, prometheus_logger): - exception = AssertionError("LiteLLM Virtual Key expected. Received=invalid-key-12345, expected to start with 'sk-'.") - assert prometheus_logger._is_invalid_api_key_request(status_code=None, exception=exception) is True + def test_auth_error_message_not_skipped(self, prometheus_logger): + exception = AssertionError( + "LiteLLM Virtual Key expected. Received=invalid-key-12345, expected to start with 'sk-'." + ) + assert ( + prometheus_logger._is_invalid_api_key_request( + status_code=None, exception=exception + ) + is False + ) - def test_non_auth_exception_not_detected(self, prometheus_logger): + def test_non_auth_exception_not_skipped(self, prometheus_logger): exception = ValueError("Some other error") - assert prometheus_logger._is_invalid_api_key_request(status_code=None, exception=exception) is False + assert ( + prometheus_logger._is_invalid_api_key_request( + status_code=None, exception=exception + ) + is False + ) class TestSkipMetricsValidation: - """Test high-level validation method that orchestrates detection and extraction.""" + """Test that we never skip metrics - all requests are tracked.""" - def test_skip_for_401_exception(self, prometheus_logger): - """Test full flow: extraction -> detection -> skip decision.""" + def test_no_skip_for_401_exception(self, prometheus_logger): + """401 requests are now tracked for security auditing and abuse detection.""" exception = ExceptionWithCode("401") - assert prometheus_logger._should_skip_metrics_for_invalid_key(exception=exception) is True + assert ( + prometheus_logger._should_skip_metrics_for_invalid_key(exception=exception) + is False + ) - def test_skip_for_auth_error_message(self, prometheus_logger): - """Test full flow: exception message -> detection -> skip decision.""" + def test_no_skip_for_auth_error_message(self, prometheus_logger): + """Auth error messages are now tracked.""" exception = AssertionError("expected to start with 'sk-'") - assert prometheus_logger._should_skip_metrics_for_invalid_key(exception=exception) is True + assert ( + prometheus_logger._should_skip_metrics_for_invalid_key(exception=exception) + is False + ) def test_no_skip_for_valid_request(self, prometheus_logger): assert prometheus_logger._should_skip_metrics_for_invalid_key() is False class TestAsyncHooks: - """Test async hook methods skip metrics for invalid API keys.""" + """Test async hook methods record metrics for all requests including 401s.""" @pytest.fixture def mock_user_api_key(self): @@ -115,24 +142,33 @@ class TestAsyncHooks: return user_key @pytest.mark.asyncio - async def test_post_call_failure_hook_skips_401(self, prometheus_logger, mock_user_api_key): + async def test_post_call_failure_hook_records_401( + self, prometheus_logger, mock_user_api_key + ): + """401 failures are now recorded for security auditing and abuse detection.""" exception = ExceptionWithCode("401") exception.__class__.__name__ = "ProxyException" - with patch.object(prometheus_logger, 'litellm_proxy_failed_requests_metric') as mock_failed, \ - patch.object(prometheus_logger, 'litellm_proxy_total_requests_metric') as mock_total: + with patch.object( + prometheus_logger, "litellm_proxy_failed_requests_metric" + ) as mock_failed, patch.object( + prometheus_logger, "litellm_proxy_total_requests_metric" + ) as mock_total: + mock_failed.labels.return_value = Mock(inc=Mock()) + mock_total.labels.return_value = Mock(inc=Mock()) await prometheus_logger.async_post_call_failure_hook( - request_data={"model": "test-model"}, + request_data={"model": "test-model", "metadata": {}}, original_exception=exception, - user_api_key_dict=mock_user_api_key + user_api_key_dict=mock_user_api_key, ) - mock_failed.labels.assert_not_called() - mock_total.labels.assert_not_called() + mock_failed.labels.assert_called_once() + mock_total.labels.assert_called_once() @pytest.mark.asyncio - async def test_log_failure_event_skips_401(self, prometheus_logger): + async def test_log_failure_event_records_401(self, prometheus_logger): + """401 failures in log_failure_event are now recorded.""" exception = ExceptionWithCode("401") kwargs = { "model": "test-model", @@ -140,6 +176,9 @@ class TestAsyncHooks: "metadata": { "user_api_key_hash": "test-key", "user_api_key_user_id": "test-user", + "user_api_key_alias": None, + "user_api_key_team_id": None, + "user_api_key_team_alias": None, }, "model_group": "test-model", }, @@ -147,15 +186,16 @@ class TestAsyncHooks: "litellm_params": {}, } - with patch.object(prometheus_logger, 'litellm_llm_api_failed_requests_metric') as mock_failed, \ - patch.object(prometheus_logger, 'set_llm_deployment_failure_metrics') as mock_deployment: + with patch.object( + prometheus_logger, "litellm_llm_api_failed_requests_metric" + ) as mock_failed, patch.object( + prometheus_logger, "set_llm_deployment_failure_metrics" + ) as mock_deployment: + mock_failed.labels.return_value = Mock(inc=Mock()) await prometheus_logger.async_log_failure_event( - kwargs=kwargs, - response_obj=None, - start_time=None, - end_time=None + kwargs=kwargs, response_obj=None, start_time=None, end_time=None ) - mock_failed.labels.assert_not_called() - mock_deployment.assert_not_called() + mock_failed.labels.assert_called_once() + mock_deployment.assert_called_once() From 333419b4d2cd7f229f7cd0c1d2cd5e8c5998d9f4 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 09:03:27 +0530 Subject: [PATCH 015/511] Add documentation correctly for nova sonic --- docs/my-website/docs/providers/bedrock.md | 2 +- .../{tutorials => providers}/bedrock_realtime_with_audio.md | 6 +----- docs/my-website/sidebars.js | 1 + 3 files changed, 3 insertions(+), 6 deletions(-) rename docs/my-website/docs/{tutorials => providers}/bedrock_realtime_with_audio.md (98%) diff --git a/docs/my-website/docs/providers/bedrock.md b/docs/my-website/docs/providers/bedrock.md index 487212ad655..e546ed97656 100644 --- a/docs/my-website/docs/providers/bedrock.md +++ b/docs/my-website/docs/providers/bedrock.md @@ -9,7 +9,7 @@ ALL Bedrock models (Anthropic, Meta, Deepseek, Mistral, Amazon, etc.) are Suppor | Description | Amazon Bedrock is a fully managed service that offers a choice of high-performing foundation models (FMs). | | Provider Route on LiteLLM | `bedrock/`, [`bedrock/converse/`](#set-converse--invoke-route), [`bedrock/invoke/`](#set-invoke-route), [`bedrock/converse_like/`](#calling-via-internal-proxy), [`bedrock/llama/`](#deepseek-not-r1), [`bedrock/deepseek_r1/`](#deepseek-r1), [`bedrock/qwen3/`](#qwen3-imported-models), [`bedrock/qwen2/`](./bedrock_imported.md#qwen2-imported-models), [`bedrock/openai/`](./bedrock_imported.md#openai-compatible-imported-models-qwen-25-vl-etc), [`bedrock/moonshot`](./bedrock_imported.md#moonshot-kimi-k2-thinking) | | Provider Doc | [Amazon Bedrock ↗](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) | -| Supported OpenAI Endpoints | `/chat/completions`, `/completions`, `/embeddings`, `/images/generations` | +| Supported OpenAI Endpoints | `/chat/completions`, `/completions`, `/embeddings`, `/images/generations`, `/v1/realtime`| | Rerank Endpoint | `/rerank` | | Pass-through Endpoint | [Supported](../pass_through/bedrock.md) | diff --git a/docs/my-website/docs/tutorials/bedrock_realtime_with_audio.md b/docs/my-website/docs/providers/bedrock_realtime_with_audio.md similarity index 98% rename from docs/my-website/docs/tutorials/bedrock_realtime_with_audio.md rename to docs/my-website/docs/providers/bedrock_realtime_with_audio.md index 07e29af5320..a2d9813ffd9 100644 --- a/docs/my-website/docs/tutorials/bedrock_realtime_with_audio.md +++ b/docs/my-website/docs/providers/bedrock_realtime_with_audio.md @@ -1,8 +1,4 @@ -# Call Bedrock Nova Sonic Realtime API with Audio Input/Output - -:::info -Requires LiteLLM Proxy v1.70.1+ -::: +# Bedrock Realtime API ## Overview diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index 49265ddf63f..d932b6af250 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -717,6 +717,7 @@ const sidebars = { "providers/bedrock_agents", "providers/bedrock_writer", "providers/bedrock_batches", + "providers/bedrock_realtime_with_audio", "providers/aws_polly", "providers/bedrock_vector_store", ] From 5cfcf67d7c991074bb6b31546b8452f4a2cf672f Mon Sep 17 00:00:00 2001 From: Ishaan Jaff Date: Mon, 2 Feb 2026 19:36:36 -0800 Subject: [PATCH 016/511] [Feat] /chat/completions - allow using OpenAI style tools for `web_search` with VertexAI/gemini models (#20280) * test_gemini_openai_web_search_tool_to_google_search * feat: Handle OpenAI style web search tools --- .../vertex_and_google_ai_studio_gemini.py | 7 ++ tests/llm_translation/test_gemini.py | 17 +++ ...test_vertex_and_google_ai_studio_gemini.py | 105 ++++++++++++++++++ 3 files changed, 129 insertions(+) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index a9ac21bb56f..b5a6949f272 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -478,6 +478,13 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): if "type" in tool and tool["type"] == "computer_use": computer_use_config = {k: v for k, v in tool.items() if k != "type"} tool = {VertexToolName.COMPUTER_USE.value: computer_use_config} + # Handle OpenAI-style web_search and web_search_preview tools + # Transform them to Gemini's googleSearch tool + elif "type" in tool and tool["type"] in ("web_search", "web_search_preview"): + verbose_logger.info( + f"Gemini: Transforming OpenAI-style '{tool['type']}' tool to googleSearch" + ) + tool = {VertexToolName.GOOGLE_SEARCH.value: {}} # Handle tools with 'type' field (OpenAI spec compliance) Ignore this field -> https://github.com/BerriAI/litellm/issues/14644#issuecomment-3342061838 elif "type" in tool: tool = {k: tool[k] for k in tool if k != "type"} diff --git a/tests/llm_translation/test_gemini.py b/tests/llm_translation/test_gemini.py index e3e05786449..c1c52757cf0 100644 --- a/tests/llm_translation/test_gemini.py +++ b/tests/llm_translation/test_gemini.py @@ -1435,3 +1435,20 @@ def test_gemini_image_size_limit_exceeded(): error_message = str(excinfo.value) assert "Image size" in error_message assert "exceeds maximum allowed size" in error_message + +@pytest.mark.asyncio +async def test_gemini_openai_web_search_tool_to_google_search(): + """ + Test that OpenAI-style web_search tools are transformed to Gemini's googleSearch. + + When passing {"type": "web_search"} or {"type": "web_search_preview"} to Gemini, + these should be transformed to googleSearch, not silently ignored. + """ + response = await litellm.acompletion( + model="gemini/gemini-2.5-flash", + messages=[{"role": "user", "content": "What is the capital of France?"}], + tools=[{"type": "web_search"}], + ) + print("response: ", response.model_dump_json(indent=4)) + assert hasattr(response, "vertex_ai_grounding_metadata") + assert getattr(response, "vertex_ai_grounding_metadata") is not None diff --git a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index ac099a0168c..cb3b51acd69 100644 --- a/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/test_litellm/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -2663,6 +2663,111 @@ def test_vertex_ai_single_tool_type_still_works(): assert tools[0]["code_execution"] == {} +def test_vertex_ai_openai_web_search_tool_transformation(): + """ + Test that OpenAI-style web_search and web_search_preview tools are transformed to googleSearch. + + This fixes the issue where passing OpenAI-style web search tools like: + {"type": "web_search"} or {"type": "web_search_preview"} + would be silently ignored (the request succeeds but grounding is not applied). + + The fix transforms these to Gemini's googleSearch tool. + + Input: + value=[{"type": "web_search"}] + + Expected Output: + tools=[{"googleSearch": {}}] + """ + v = VertexGeminiConfig() + optional_params = {} + + # Test web_search transformation + tools = v._map_function( + value=[{"type": "web_search"}], + optional_params=optional_params + ) + + assert len(tools) == 1, f"Expected 1 Tool object, got {len(tools)}" + assert "googleSearch" in tools[0], f"Expected googleSearch in tool, got {tools[0].keys()}" + assert tools[0]["googleSearch"] == {}, f"Expected empty googleSearch config, got {tools[0]['googleSearch']}" + + +def test_vertex_ai_openai_web_search_preview_tool_transformation(): + """ + Test that OpenAI-style web_search_preview tool is transformed to googleSearch. + + Input: + value=[{"type": "web_search_preview"}] + + Expected Output: + tools=[{"googleSearch": {}}] + """ + v = VertexGeminiConfig() + optional_params = {} + + # Test web_search_preview transformation + tools = v._map_function( + value=[{"type": "web_search_preview"}], + optional_params=optional_params + ) + + assert len(tools) == 1, f"Expected 1 Tool object, got {len(tools)}" + assert "googleSearch" in tools[0], f"Expected googleSearch in tool, got {tools[0].keys()}" + assert tools[0]["googleSearch"] == {}, f"Expected empty googleSearch config, got {tools[0]['googleSearch']}" + + +def test_vertex_ai_openai_web_search_with_function_tools(): + """ + Test that OpenAI-style web_search tool works alongside function tools. + + Input: + value=[ + {"type": "web_search"}, + {"type": "function", "function": {"name": "get_weather", "description": "Get weather"}}, + ] + + Expected Output: + tools=[ + {"googleSearch": {}}, + {"function_declarations": [{"name": "get_weather", "description": "Get weather"}]}, + ] + """ + v = VertexGeminiConfig() + optional_params = {} + + tools = v._map_function( + value=[ + {"type": "web_search"}, + {"type": "function", "function": {"name": "get_weather", "description": "Get weather"}}, + ], + optional_params=optional_params + ) + + # Should have 2 separate Tool objects + assert len(tools) == 2, f"Expected 2 Tool objects, got {len(tools)}" + + # Find each tool type + search_tool = None + func_tool = None + + for tool in tools: + if "googleSearch" in tool: + search_tool = tool + elif "function_declarations" in tool: + func_tool = tool + + # Verify both tools are present + assert search_tool is not None, "googleSearch Tool should be present" + assert func_tool is not None, "function_declarations Tool should be present" + + # Verify googleSearch is empty config + assert search_tool["googleSearch"] == {} + + # Verify function declaration content + assert func_tool["function_declarations"][0]["name"] == "get_weather" + + def test_vertex_ai_multiple_function_declarations_grouped(): """ Test that multiple function declarations are grouped in ONE Tool object. From 5aa8725c630d6b2e5bcb175be1aa6959d06d73dc Mon Sep 17 00:00:00 2001 From: Ishaan Jaffer Date: Mon, 2 Feb 2026 19:48:00 -0800 Subject: [PATCH 017/511] docs Tracing Tools --- docs/my-website/docs/proxy/ui_logs.md | 35 ++++++++++++++++++++++++++ docs/my-website/img/ui_tools.png | Bin 0 -> 430362 bytes 2 files changed, 35 insertions(+) create mode 100644 docs/my-website/img/ui_tools.png diff --git a/docs/my-website/docs/proxy/ui_logs.md b/docs/my-website/docs/proxy/ui_logs.md index b6d3d2ae7ca..2e772197b94 100644 --- a/docs/my-website/docs/proxy/ui_logs.md +++ b/docs/my-website/docs/proxy/ui_logs.md @@ -23,6 +23,41 @@ View Spend, Token Usage, Key, Team Name for Each Request to LiteLLM **By default LiteLLM does not track the request and response content.** +## Tracing Tools + +View which tools were provided and called in your completion requests. + + + +**Example:** Make a completion request with tools: + +```bash +curl -X POST 'http://localhost:4000/chat/completions' \ + -H 'Authorization: Bearer sk-1234' \ + -H 'Content-Type: application/json' \ + -d '{ + "model": "gpt-4", + "messages": [{"role": "user", "content": "What is the weather?"}], + "tools": [ + { + "type": "function", + "function": { + "name": "get_weather", + "description": "Get the current weather", + "parameters": { + "type": "object", + "properties": { + "location": {"type": "string"} + } + } + } + } + ] + }' +``` + +Check the Logs page to see all tools provided and which ones were called. + ## Tracking - Request / Response Content in Logs Page If you want to view request and response content on LiteLLM Logs, you can enable it in either place: diff --git a/docs/my-website/img/ui_tools.png b/docs/my-website/img/ui_tools.png new file mode 100644 index 0000000000000000000000000000000000000000..6f4d0f874103804d933a0c405c0bf58361da4177 GIT binary patch literal 430362 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 Ld%Z;M!L$DXTAi`s literal 0 HcmV?d00001 From 7ae980410b093a27a5a87fd80cd53bf21c48d71c Mon Sep 17 00:00:00 2001 From: Ishaan Jaffer Date: Mon, 2 Feb 2026 19:50:22 -0800 Subject: [PATCH 018/511] docs fix --- docs/my-website/docs/proxy/ui_logs.md | 29 +++++++++++++-------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/my-website/docs/proxy/ui_logs.md b/docs/my-website/docs/proxy/ui_logs.md index 2e772197b94..8cfe818ebfd 100644 --- a/docs/my-website/docs/proxy/ui_logs.md +++ b/docs/my-website/docs/proxy/ui_logs.md @@ -23,6 +23,20 @@ View Spend, Token Usage, Key, Team Name for Each Request to LiteLLM **By default LiteLLM does not track the request and response content.** +## Tracking - Request / Response Content in Logs Page + +If you want to view request and response content on LiteLLM Logs, you can enable it in either place: + +- **From the UI (no restart):** Use [UI Spend Log Settings](./ui_spend_log_settings.md) — open Logs → Settings → enable "Store Prompts in Spend Logs" → Save. Takes effect immediately and overrides config. +- **From config:** Add this to your `proxy_config.yaml` (requires restart): + +```yaml +general_settings: + store_prompts_in_spend_logs: true +``` + + + ## Tracing Tools View which tools were provided and called in your completion requests. @@ -58,21 +72,6 @@ curl -X POST 'http://localhost:4000/chat/completions' \ Check the Logs page to see all tools provided and which ones were called. -## Tracking - Request / Response Content in Logs Page - -If you want to view request and response content on LiteLLM Logs, you can enable it in either place: - -- **From the UI (no restart):** Use [UI Spend Log Settings](./ui_spend_log_settings.md) — open Logs → Settings → enable "Store Prompts in Spend Logs" → Save. Takes effect immediately and overrides config. -- **From config:** Add this to your `proxy_config.yaml` (requires restart): - -```yaml -general_settings: - store_prompts_in_spend_logs: true -``` - - - - ## Stop storing Error Logs in DB If you do not want to store error logs in DB, you can opt out with this setting From b33e1e80198247ec717cbe9fab1fac61754b4db8 Mon Sep 17 00:00:00 2001 From: Cesar Garcia <128240629+Chesars@users.noreply.github.com> Date: Tue, 3 Feb 2026 03:04:08 -0300 Subject: [PATCH 019/511] feat(sdk): add proxy_auth for auto OAuth2/JWT token management (#20238) Adds litellm.proxy_auth to automatically obtain and refresh OAuth2/JWT tokens when connecting to LiteLLM Proxy or any OAuth2-protected endpoint. - Add ProxyAuthHandler for token lifecycle (obtain, cache, refresh) - Add AzureADCredential wrapper for azure-identity credentials - Add GenericOAuth2Credential for any OAuth2 provider (Okta, Auth0, etc) - Auto-inject Authorization headers in completion() and embedding() Closes #19834 --- litellm/__init__.py | 2 + litellm/main.py | 14 ++ litellm/proxy_auth/__init__.py | 30 ++++ litellm/proxy_auth/credentials.py | 240 ++++++++++++++++++++++++++++++ tests/litellm/test_proxy_auth.py | 204 +++++++++++++++++++++++++ 5 files changed, 490 insertions(+) create mode 100644 litellm/proxy_auth/__init__.py create mode 100644 litellm/proxy_auth/credentials.py create mode 100644 tests/litellm/test_proxy_auth.py diff --git a/litellm/__init__.py b/litellm/__init__.py index 112d58d49d8..d9811b07da4 100644 --- a/litellm/__init__.py +++ b/litellm/__init__.py @@ -261,6 +261,8 @@ extra_spend_tag_headers: Optional[List[str]] = None in_memory_llm_clients_cache: "LLMClientCache" safe_memory_mode: bool = False enable_azure_ad_token_refresh: Optional[bool] = False +# Proxy Authentication - auto-obtain/refresh OAuth2/JWT tokens for LiteLLM Proxy +proxy_auth: Optional[Any] = None ### DEFAULT AZURE API VERSION ### AZURE_DEFAULT_API_VERSION = "2025-02-01-preview" # this is updated to the latest ### DEFAULT WATSONX API VERSION ### diff --git a/litellm/main.py b/litellm/main.py index 7d591f76882..e7991ae1f17 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -1199,6 +1199,13 @@ def completion( # type: ignore # noqa: PLR0915 headers = {} if extra_headers is not None: headers.update(extra_headers) + # Inject proxy auth headers if configured + if litellm.proxy_auth is not None: + try: + proxy_headers = litellm.proxy_auth.get_auth_headers() + headers.update(proxy_headers) + except Exception as e: + verbose_logger.warning(f"Failed to get proxy auth headers: {e}") num_retries = kwargs.get( "num_retries", None ) ## alt. param for 'max_retries'. Use this to pass retries w/ instructor. @@ -4555,6 +4562,13 @@ def embedding( # noqa: PLR0915 headers = {} if extra_headers is not None: headers.update(extra_headers) + # Inject proxy auth headers if configured + if litellm.proxy_auth is not None: + try: + proxy_headers = litellm.proxy_auth.get_auth_headers() + headers.update(proxy_headers) + except Exception as e: + verbose_logger.warning(f"Failed to get proxy auth headers: {e}") ### CUSTOM MODEL COST ### input_cost_per_token = kwargs.get("input_cost_per_token", None) output_cost_per_token = kwargs.get("output_cost_per_token", None) diff --git a/litellm/proxy_auth/__init__.py b/litellm/proxy_auth/__init__.py new file mode 100644 index 00000000000..27624a94fb9 --- /dev/null +++ b/litellm/proxy_auth/__init__.py @@ -0,0 +1,30 @@ +""" +Proxy Authentication module for LiteLLM SDK. + +This module provides OAuth2/JWT token management for authenticating +with LiteLLM Proxy or any OAuth2-protected endpoint. + +Usage: + from litellm.proxy_auth import AzureADCredential, ProxyAuthHandler + + litellm.proxy_auth = ProxyAuthHandler( + credential=AzureADCredential(), + scope="api://my-proxy/.default" + ) +""" + +from .credentials import ( + AccessToken, + TokenCredential, + AzureADCredential, + GenericOAuth2Credential, + ProxyAuthHandler, +) + +__all__ = [ + "AccessToken", + "TokenCredential", + "AzureADCredential", + "GenericOAuth2Credential", + "ProxyAuthHandler", +] diff --git a/litellm/proxy_auth/credentials.py b/litellm/proxy_auth/credentials.py new file mode 100644 index 00000000000..cddaf1278f9 --- /dev/null +++ b/litellm/proxy_auth/credentials.py @@ -0,0 +1,240 @@ +""" +Credential providers for proxy authentication. + +This module provides a provider-agnostic interface for obtaining OAuth2/JWT tokens. +It follows the same TokenCredential protocol used by Azure SDK. +""" + +import time +from dataclasses import dataclass +from typing import Any, Optional, Protocol, runtime_checkable + + +@dataclass +class AccessToken: + """ + Represents an OAuth2 access token with expiration. + + This matches the structure used by azure.core.credentials.AccessToken. + + Attributes: + token: The access token string (typically a JWT). + expires_on: Unix timestamp when the token expires. + """ + + token: str + expires_on: int + + +@runtime_checkable +class TokenCredential(Protocol): + """ + Protocol for credential providers. + + This matches the azure.core.credentials.TokenCredential interface, + allowing any Azure SDK credential to be used directly. + + Any class implementing get_token(scope) -> AccessToken can be used. + """ + + def get_token(self, scope: str) -> AccessToken: + """ + Get an access token for the specified scope. + + Args: + scope: The OAuth2 scope to request (e.g., "api://my-app/.default") + + Returns: + AccessToken with the token string and expiration timestamp. + """ + ... + + +class AzureADCredential: + """ + Wrapper for Azure Identity credentials. + + This wraps any azure-identity credential (DefaultAzureCredential, + ClientSecretCredential, ManagedIdentityCredential, etc.) and converts + the token to our AccessToken format. + + If no credential is provided, it will use DefaultAzureCredential + which tries multiple authentication methods automatically. + + Example: + # Use default credential chain (env vars, managed identity, CLI, etc.) + cred = AzureADCredential() + + # Or provide a specific credential + from azure.identity import ClientSecretCredential + azure_cred = ClientSecretCredential(tenant_id, client_id, client_secret) + cred = AzureADCredential(credential=azure_cred) + """ + + def __init__(self, credential: Optional[Any] = None): + """ + Initialize with an optional Azure credential. + + Args: + credential: An azure-identity credential object. If None, + DefaultAzureCredential will be used on first token request. + """ + self._credential = credential + self._initialized = credential is not None + + def get_token(self, scope: str) -> AccessToken: + """ + Get an access token from Azure AD. + + Args: + scope: The OAuth2 scope (e.g., "api://my-app/.default") + + Returns: + AccessToken with the JWT and expiration. + + Raises: + ImportError: If azure-identity is not installed. + """ + if not self._initialized: + try: + from azure.identity import DefaultAzureCredential + + self._credential = DefaultAzureCredential() + self._initialized = True + except ImportError: + raise ImportError( + "azure-identity is required for AzureADCredential. " + "Install it with: pip install azure-identity" + ) + + result = self._credential.get_token(scope) + return AccessToken(token=result.token, expires_on=result.expires_on) + + +class GenericOAuth2Credential: + """ + Generic OAuth2 client credentials flow. + + This works with any OAuth2 provider (Okta, Auth0, Keycloak, etc.) + that supports the client_credentials grant type. + + Example: + cred = GenericOAuth2Credential( + client_id="my-client-id", + client_secret="my-client-secret", + token_url="https://my-idp.com/oauth2/token" + ) + """ + + def __init__(self, client_id: str, client_secret: str, token_url: str): + """ + Initialize OAuth2 client credentials. + + Args: + client_id: OAuth2 client ID + client_secret: OAuth2 client secret + token_url: Token endpoint URL (e.g., "https://idp.com/oauth2/token") + """ + self.client_id = client_id + self.client_secret = client_secret + self.token_url = token_url + self._cached_token: Optional[AccessToken] = None + + def get_token(self, scope: str) -> AccessToken: + """ + Get an access token using OAuth2 client credentials flow. + + Tokens are cached and reused until they expire (with 60s buffer). + + Args: + scope: The OAuth2 scope to request + + Returns: + AccessToken with the token and expiration. + """ + # Return cached token if still valid (with 60s buffer) + if self._cached_token and self._cached_token.expires_on > time.time() + 60: + return self._cached_token + + import httpx + + response = httpx.post( + self.token_url, + data={ + "grant_type": "client_credentials", + "client_id": self.client_id, + "client_secret": self.client_secret, + "scope": scope, + }, + ) + response.raise_for_status() + data = response.json() + + self._cached_token = AccessToken( + token=data["access_token"], + expires_on=int(time.time()) + data.get("expires_in", 3600), + ) + return self._cached_token + + +class ProxyAuthHandler: + """ + Manages OAuth2/JWT token lifecycle for proxy authentication. + + This handler: + - Obtains tokens from the configured credential provider + - Caches tokens to avoid unnecessary requests + - Automatically refreshes tokens before they expire (60s buffer) + - Generates Authorization headers for HTTP requests + + Set this as litellm.proxy_auth to automatically inject auth headers + into all requests to your LiteLLM Proxy. + + Example: + import litellm + from litellm.proxy_auth import AzureADCredential, ProxyAuthHandler + + litellm.proxy_auth = ProxyAuthHandler( + credential=AzureADCredential(), + scope="api://my-litellm-proxy/.default" + ) + litellm.api_base = "https://my-proxy.example.com" + + # Auth headers are now automatically injected + response = litellm.completion(model="gpt-4", messages=[...]) + """ + + def __init__(self, credential: TokenCredential, scope: str): + """ + Initialize the proxy auth handler. + + Args: + credential: A TokenCredential implementation (AzureADCredential, + GenericOAuth2Credential, or any custom implementation) + scope: The OAuth2 scope to request tokens for + """ + self.credential = credential + self.scope = scope + self._cached_token: Optional[AccessToken] = None + + def get_token(self) -> AccessToken: + """ + Get a valid access token, refreshing if necessary. + + Returns: + AccessToken that is valid for at least 60 more seconds. + """ + # Refresh if no token or token expires within 60 seconds + if not self._cached_token or self._cached_token.expires_on <= time.time() + 60: + self._cached_token = self.credential.get_token(self.scope) + return self._cached_token + + def get_auth_headers(self) -> dict: + """ + Get HTTP headers for authentication. + + Returns: + Dict with Authorization header containing Bearer token. + """ + token = self.get_token() + return {"Authorization": f"Bearer {token.token}"} diff --git a/tests/litellm/test_proxy_auth.py b/tests/litellm/test_proxy_auth.py new file mode 100644 index 00000000000..1d73e143e10 --- /dev/null +++ b/tests/litellm/test_proxy_auth.py @@ -0,0 +1,204 @@ +""" +Unit tests for litellm.proxy_auth module. + +Tests the OAuth2/JWT token management for LiteLLM Proxy authentication. +""" + +import time +from unittest.mock import Mock, patch + +import pytest + +from litellm.proxy_auth import ( + AccessToken, + AzureADCredential, + GenericOAuth2Credential, + ProxyAuthHandler, +) + + +class TestAccessToken: + """Tests for AccessToken dataclass.""" + + def test_access_token_creation(self): + """Test AccessToken can be created with required fields.""" + token = AccessToken(token="test-token", expires_on=1234567890) + assert token.token == "test-token" + assert token.expires_on == 1234567890 + + def test_access_token_equality(self): + """Test AccessToken equality comparison.""" + token1 = AccessToken(token="test", expires_on=123) + token2 = AccessToken(token="test", expires_on=123) + assert token1 == token2 + + +class MockCredential: + """Mock credential for testing.""" + + def __init__(self, expires_in_seconds: int = 3600): + self.call_count = 0 + self.expires_in = expires_in_seconds + + def get_token(self, scope: str) -> AccessToken: + self.call_count += 1 + return AccessToken( + token=f"mock-token-{self.call_count}", + expires_on=int(time.time()) + self.expires_in, + ) + + +class TestProxyAuthHandler: + """Tests for ProxyAuthHandler.""" + + def test_get_auth_headers_returns_bearer_token(self): + """Test that get_auth_headers returns correct Authorization header.""" + cred = MockCredential() + handler = ProxyAuthHandler(credential=cred, scope="test-scope") + + headers = handler.get_auth_headers() + + assert "Authorization" in headers + assert headers["Authorization"].startswith("Bearer ") + assert "mock-token-1" in headers["Authorization"] + + def test_token_caching(self): + """Test that tokens are cached and not re-requested.""" + cred = MockCredential(expires_in_seconds=3600) # Long expiry + handler = ProxyAuthHandler(credential=cred, scope="test-scope") + + # Multiple calls should only request token once + handler.get_auth_headers() + handler.get_auth_headers() + handler.get_auth_headers() + + assert cred.call_count == 1 + + def test_token_refresh_when_about_to_expire(self): + """Test that tokens are refreshed when about to expire (within 60s buffer).""" + cred = MockCredential(expires_in_seconds=30) # Expires in 30s (< 60s buffer) + handler = ProxyAuthHandler(credential=cred, scope="test-scope") + + # First call gets token + handler.get_auth_headers() + # Second call should refresh because token expires within 60s buffer + handler.get_auth_headers() + + assert cred.call_count == 2 + + def test_get_token_method(self): + """Test the get_token method returns AccessToken.""" + cred = MockCredential() + handler = ProxyAuthHandler(credential=cred, scope="test-scope") + + token = handler.get_token() + + assert isinstance(token, AccessToken) + assert token.token == "mock-token-1" + + +class TestAzureADCredential: + """Tests for AzureADCredential.""" + + def test_lazy_initialization(self): + """Test that azure-identity is not imported until get_token is called.""" + # This should not raise ImportError even if azure-identity is not installed + cred = AzureADCredential(credential=None) + # _initialized should be False until get_token is called + assert cred._initialized is False + + def test_wraps_azure_credential(self): + """Test that AzureADCredential wraps an azure-identity credential.""" + # Mock Azure credential + mock_azure_cred = Mock() + mock_azure_cred.get_token.return_value = Mock( + token="azure-token", expires_on=9999999999 + ) + + cred = AzureADCredential(credential=mock_azure_cred) + token = cred.get_token("https://graph.microsoft.com/.default") + + assert token.token == "azure-token" + assert token.expires_on == 9999999999 + mock_azure_cred.get_token.assert_called_once_with( + "https://graph.microsoft.com/.default" + ) + + +class TestGenericOAuth2Credential: + """Tests for GenericOAuth2Credential.""" + + def test_token_request(self): + """Test that GenericOAuth2Credential makes correct OAuth2 request.""" + with patch("httpx.post") as mock_post: + mock_response = Mock() + mock_response.json.return_value = { + "access_token": "oauth2-token", + "expires_in": 3600, + } + mock_response.raise_for_status = Mock() + mock_post.return_value = mock_response + + cred = GenericOAuth2Credential( + client_id="test-client", + client_secret="test-secret", + token_url="https://example.com/oauth2/token", + ) + token = cred.get_token("test-scope") + + assert token.token == "oauth2-token" + mock_post.assert_called_once() + call_kwargs = mock_post.call_args + assert call_kwargs[1]["data"]["grant_type"] == "client_credentials" + assert call_kwargs[1]["data"]["client_id"] == "test-client" + assert call_kwargs[1]["data"]["client_secret"] == "test-secret" + assert call_kwargs[1]["data"]["scope"] == "test-scope" + + def test_token_caching(self): + """Test that GenericOAuth2Credential caches tokens.""" + with patch("httpx.post") as mock_post: + mock_response = Mock() + mock_response.json.return_value = { + "access_token": "oauth2-token", + "expires_in": 3600, + } + mock_response.raise_for_status = Mock() + mock_post.return_value = mock_response + + cred = GenericOAuth2Credential( + client_id="test-client", + client_secret="test-secret", + token_url="https://example.com/oauth2/token", + ) + + # Multiple calls should only make one HTTP request + cred.get_token("test-scope") + cred.get_token("test-scope") + cred.get_token("test-scope") + + assert mock_post.call_count == 1 + + +class TestLiteLLMIntegration: + """Tests for integration with litellm module.""" + + def test_proxy_auth_variable_exists(self): + """Test that litellm.proxy_auth variable exists.""" + import litellm + + # Should be None by default + assert hasattr(litellm, "proxy_auth") + + def test_proxy_auth_can_be_set(self): + """Test that litellm.proxy_auth can be set to a ProxyAuthHandler.""" + import litellm + + original_value = litellm.proxy_auth + try: + cred = MockCredential() + handler = ProxyAuthHandler(credential=cred, scope="test") + litellm.proxy_auth = handler + + assert litellm.proxy_auth is handler + finally: + litellm.proxy_auth = original_value From a904c3f40d7d539d56e0c6eea4e6c906673d7e28 Mon Sep 17 00:00:00 2001 From: Cesar Garcia <128240629+Chesars@users.noreply.github.com> Date: Tue, 3 Feb 2026 03:05:44 -0300 Subject: [PATCH 020/511] fix(github_copilot): preserve system prompts and auto-inject headers (#20113) - Remove system-to-assistant message conversion (API now supports system prompts) - Auto-inject required Copilot headers in chat completions (same as /responses) - Deprecate disable_copilot_system_to_assistant flag - Update docs to remove manual extra_headers requirement Fixes #19873 --- .../docs/providers/github_copilot.md | 35 ++++++------------- docs/my-website/docs/proxy/config_settings.md | 4 +-- .../github_copilot/chat/transformation.py | 21 +++++------ litellm/main.py | 14 ++++++++ 4 files changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/my-website/docs/providers/github_copilot.md b/docs/my-website/docs/providers/github_copilot.md index 306c9f949ec..e9fd3444f5f 100644 --- a/docs/my-website/docs/providers/github_copilot.md +++ b/docs/my-website/docs/providers/github_copilot.md @@ -35,11 +35,10 @@ from litellm import completion response = completion( model="github_copilot/gpt-4", - messages=[{"role": "user", "content": "Write a Python function to calculate fibonacci numbers"}], - extra_headers={ - "editor-version": "vscode/1.85.1", - "Copilot-Integration-Id": "vscode-chat" - } + messages=[ + {"role": "system", "content": "You are a helpful coding assistant"}, + {"role": "user", "content": "Write a Python function to calculate fibonacci numbers"} + ] ) print(response) ``` @@ -50,11 +49,7 @@ from litellm import completion stream = completion( model="github_copilot/gpt-4", messages=[{"role": "user", "content": "Explain async/await in Python"}], - stream=True, - extra_headers={ - "editor-version": "vscode/1.85.1", - "Copilot-Integration-Id": "vscode-chat" - } + stream=True ) for chunk in stream: @@ -134,11 +129,7 @@ client = OpenAI( # Non-streaming response response = client.chat.completions.create( model="github_copilot/gpt-4", - messages=[{"role": "user", "content": "How do I optimize this SQL query?"}], - extra_headers={ - "editor-version": "vscode/1.85.1", - "Copilot-Integration-Id": "vscode-chat" - } + messages=[{"role": "user", "content": "How do I optimize this SQL query?"}] ) print(response.choices[0].message.content) @@ -156,11 +147,7 @@ response = litellm.completion( model="litellm_proxy/github_copilot/gpt-4", messages=[{"role": "user", "content": "Review this code for bugs"}], api_base="http://localhost:4000", - api_key="your-proxy-api-key", - extra_headers={ - "editor-version": "vscode/1.85.1", - "Copilot-Integration-Id": "vscode-chat" - } + api_key="your-proxy-api-key" ) print(response.choices[0].message.content) @@ -174,8 +161,6 @@ print(response.choices[0].message.content) curl http://localhost:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-proxy-api-key" \ - -H "editor-version: vscode/1.85.1" \ - -H "Copilot-Integration-Id: vscode-chat" \ -d '{ "model": "github_copilot/gpt-4", "messages": [{"role": "user", "content": "Explain this error message"}] @@ -211,9 +196,11 @@ export GITHUB_COPILOT_API_KEY_FILE="api-key.json" ### Headers -GitHub Copilot supports various editor-specific headers: +LiteLLM automatically injects the required GitHub Copilot headers (simulating VSCode). You don't need to specify them manually. -```python showLineNumbers title="Common Headers" +If you want to override the defaults (e.g., to simulate a different editor), you can use `extra_headers`: + +```python showLineNumbers title="Custom Headers (Optional)" extra_headers = { "editor-version": "vscode/1.85.1", # Editor version "editor-plugin-version": "copilot/1.155.0", # Plugin version diff --git a/docs/my-website/docs/proxy/config_settings.md b/docs/my-website/docs/proxy/config_settings.md index 264c7d765b3..80dfe11742a 100644 --- a/docs/my-website/docs/proxy/config_settings.md +++ b/docs/my-website/docs/proxy/config_settings.md @@ -94,7 +94,7 @@ litellm_settings: # /chat/completions, /completions, /embeddings, /audio/transcriptions mode: default_off # if default_off, you need to opt in to caching on a per call basis ttl: 600 # ttl for caching - disable_copilot_system_to_assistant: False # If false (default), converts all 'system' role messages to 'assistant' for GitHub Copilot compatibility. Set to true to disable this behavior. + disable_copilot_system_to_assistant: False # DEPRECATED - GitHub Copilot API supports system prompts. callback_settings: otel: @@ -197,7 +197,7 @@ router_settings: | disable_add_transform_inline_image_block | boolean | For Fireworks AI models - if true, turns off the auto-add of `#transform=inline` to the url of the image_url, if the model is not a vision model. | | disable_hf_tokenizer_download | boolean | If true, it defaults to using the openai tokenizer for all models (including huggingface models). | | enable_json_schema_validation | boolean | If true, enables json schema validation for all requests. | -| disable_copilot_system_to_assistant | boolean | If false (default), converts all 'system' role messages to 'assistant' for GitHub Copilot compatibility. Set to true to disable this behavior. Useful for tools (like Claude Code) that send system messages, which Copilot does not support. | +| disable_copilot_system_to_assistant | boolean | **DEPRECATED** - GitHub Copilot API supports system prompts. | ### general_settings - Reference diff --git a/litellm/llms/github_copilot/chat/transformation.py b/litellm/llms/github_copilot/chat/transformation.py index 50f18cedf9b..f001bb65f8b 100644 --- a/litellm/llms/github_copilot/chat/transformation.py +++ b/litellm/llms/github_copilot/chat/transformation.py @@ -5,7 +5,7 @@ from litellm.llms.openai.openai import OpenAIConfig from litellm.types.llms.openai import AllMessageValues from ..authenticator import Authenticator -from ..common_utils import GetAPIKeyError, GITHUB_COPILOT_API_BASE +from ..common_utils import GetAPIKeyError, GITHUB_COPILOT_API_BASE, get_copilot_default_headers class GithubCopilotConfig(OpenAIConfig): @@ -43,15 +43,8 @@ class GithubCopilotConfig(OpenAIConfig): messages, model: str, ): - import litellm - - disable_copilot_system_to_assistant = ( - litellm.disable_copilot_system_to_assistant - ) - if not disable_copilot_system_to_assistant: - for message in messages: - if "role" in message and message["role"] == "system": - cast(Any, message)["role"] = "assistant" + # GitHub Copilot API now supports system prompts for all models (Claude, GPT, etc.) + # No conversion needed - just return messages as-is return messages def validate_environment( @@ -69,6 +62,14 @@ class GithubCopilotConfig(OpenAIConfig): headers, model, messages, optional_params, litellm_params, api_key, api_base ) + # Add Copilot-specific headers (editor-version, user-agent, etc.) + try: + copilot_api_key = self.authenticator.get_api_key() + copilot_headers = get_copilot_default_headers(copilot_api_key) + validated_headers = {**copilot_headers, **validated_headers} + except GetAPIKeyError: + pass # Will be handled later in the request flow + # Add X-Initiator header based on message roles initiator = self._determine_initiator(messages) validated_headers["X-Initiator"] = initiator diff --git a/litellm/main.py b/litellm/main.py index e7991ae1f17..440b7e52e70 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -2462,6 +2462,20 @@ def completion( # type: ignore # noqa: PLR0915 headers = headers or litellm.headers + # Add GitHub Copilot headers (same as /responses endpoint does) + if custom_llm_provider == "github_copilot": + from litellm.llms.github_copilot.common_utils import ( + get_copilot_default_headers, + ) + from litellm.llms.github_copilot.authenticator import Authenticator + + copilot_auth = Authenticator() + copilot_api_key = copilot_auth.get_api_key() + copilot_headers = get_copilot_default_headers(copilot_api_key) + if extra_headers: + copilot_headers.update(extra_headers) + extra_headers = copilot_headers + if extra_headers is not None: optional_params["extra_headers"] = extra_headers From 17c0a88a60550c86771dea75386c6b6b7657a4ce Mon Sep 17 00:00:00 2001 From: krauckbot Date: Tue, 3 Feb 2026 07:07:17 +0100 Subject: [PATCH 021/511] fix: add missing capability flags to vercel_ai_gateway models (#20276) 67 vercel_ai_gateway models were missing capability flags (supports_vision, supports_function_calling, supports_tool_choice, supports_response_schema). These capabilities were inferred from the corresponding direct provider entries for the same models (e.g., vercel_ai_gateway/anthropic/claude-3.5-sonnet now has the same capabilities as anthropic/claude-3.5-sonnet). Models fixed include: - Claude 3/3.5/3.7 (Anthropic) - GPT-4/5 variants (OpenAI) - Gemini 2.0/2.5 (Google) - Grok 3/4 (xAI) - Mistral/Mixtral variants - Qwen models - DeepSeek models - And more This ensures consistent capability reporting across providers for the same underlying models. Co-authored-by: krauckbot --- model_prices_and_context_window.json | 333 +++++++++++++++++++++------ 1 file changed, 261 insertions(+), 72 deletions(-) diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json index 485bee4f191..801aec4ceb1 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -27829,7 +27829,9 @@ "max_output_tokens": 16384, "max_tokens": 16384, "mode": "chat", - "output_cost_per_token": 3e-07 + "output_cost_per_token": 3e-07, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/alibaba/qwen3-coder": { "input_cost_per_token": 4e-07, @@ -27838,7 +27840,9 @@ "max_output_tokens": 66536, "max_tokens": 66536, "mode": "chat", - "output_cost_per_token": 1.6e-06 + "output_cost_per_token": 1.6e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/amazon/nova-lite": { "input_cost_per_token": 6e-08, @@ -27847,7 +27851,10 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 2.4e-07 + "output_cost_per_token": 2.4e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_response_schema": true }, "vercel_ai_gateway/amazon/nova-micro": { "input_cost_per_token": 3.5e-08, @@ -27856,7 +27863,9 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 1.4e-07 + "output_cost_per_token": 1.4e-07, + "supports_function_calling": true, + "supports_response_schema": true }, "vercel_ai_gateway/amazon/nova-pro": { "input_cost_per_token": 8e-07, @@ -27865,7 +27874,10 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 3.2e-06 + "output_cost_per_token": 3.2e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_response_schema": true }, "vercel_ai_gateway/amazon/titan-embed-text-v2": { "input_cost_per_token": 2e-08, @@ -27885,7 +27897,11 @@ "max_output_tokens": 4096, "max_tokens": 4096, "mode": "chat", - "output_cost_per_token": 1.25e-06 + "output_cost_per_token": 1.25e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/anthropic/claude-3-opus": { "cache_creation_input_token_cost": 1.875e-05, @@ -27896,7 +27912,11 @@ "max_output_tokens": 4096, "max_tokens": 4096, "mode": "chat", - "output_cost_per_token": 7.5e-05 + "output_cost_per_token": 7.5e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/anthropic/claude-3.5-haiku": { "cache_creation_input_token_cost": 1e-06, @@ -27907,7 +27927,11 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 4e-06 + "output_cost_per_token": 4e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/anthropic/claude-3.5-sonnet": { "cache_creation_input_token_cost": 3.75e-06, @@ -27918,7 +27942,11 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/anthropic/claude-3.7-sonnet": { "cache_creation_input_token_cost": 3.75e-06, @@ -27929,7 +27957,11 @@ "max_output_tokens": 64000, "max_tokens": 64000, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/anthropic/claude-4-opus": { "cache_creation_input_token_cost": 1.875e-05, @@ -27940,7 +27972,11 @@ "max_output_tokens": 32000, "max_tokens": 32000, "mode": "chat", - "output_cost_per_token": 7.5e-05 + "output_cost_per_token": 7.5e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/anthropic/claude-4-sonnet": { "cache_creation_input_token_cost": 3.75e-06, @@ -27951,7 +27987,9 @@ "max_output_tokens": 64000, "max_tokens": 64000, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/cohere/command-a": { "input_cost_per_token": 2.5e-06, @@ -27960,7 +27998,9 @@ "max_output_tokens": 8000, "max_tokens": 8000, "mode": "chat", - "output_cost_per_token": 1e-05 + "output_cost_per_token": 1e-05, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/cohere/command-r": { "input_cost_per_token": 1.5e-07, @@ -27969,7 +28009,9 @@ "max_output_tokens": 4096, "max_tokens": 4096, "mode": "chat", - "output_cost_per_token": 6e-07 + "output_cost_per_token": 6e-07, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/cohere/command-r-plus": { "input_cost_per_token": 2.5e-06, @@ -27978,7 +28020,9 @@ "max_output_tokens": 4096, "max_tokens": 4096, "mode": "chat", - "output_cost_per_token": 1e-05 + "output_cost_per_token": 1e-05, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/cohere/embed-v4.0": { "input_cost_per_token": 1.2e-07, @@ -27996,7 +28040,8 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 2.19e-06 + "output_cost_per_token": 2.19e-06, + "supports_tool_choice": true }, "vercel_ai_gateway/deepseek/deepseek-r1-distill-llama-70b": { "input_cost_per_token": 7.5e-07, @@ -28005,7 +28050,10 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 9.9e-07 + "output_cost_per_token": 9.9e-07, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/deepseek/deepseek-v3": { "input_cost_per_token": 9e-07, @@ -28014,7 +28062,8 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 9e-07 + "output_cost_per_token": 9e-07, + "supports_tool_choice": true }, "vercel_ai_gateway/google/gemini-2.0-flash": { "deprecation_date": "2026-03-31", @@ -28024,7 +28073,11 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 6e-07 + "output_cost_per_token": 6e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/google/gemini-2.0-flash-lite": { "deprecation_date": "2026-03-31", @@ -28034,7 +28087,11 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 3e-07 + "output_cost_per_token": 3e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/google/gemini-2.5-flash": { "input_cost_per_token": 3e-07, @@ -28043,7 +28100,11 @@ "max_output_tokens": 65536, "max_tokens": 65536, "mode": "chat", - "output_cost_per_token": 2.5e-06 + "output_cost_per_token": 2.5e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/google/gemini-2.5-pro": { "input_cost_per_token": 2.5e-06, @@ -28052,7 +28113,11 @@ "max_output_tokens": 65536, "max_tokens": 65536, "mode": "chat", - "output_cost_per_token": 1e-05 + "output_cost_per_token": 1e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/google/gemini-embedding-001": { "input_cost_per_token": 1.5e-07, @@ -28070,7 +28135,10 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 2e-07 + "output_cost_per_token": 2e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/google/text-embedding-005": { "input_cost_per_token": 2.5e-08, @@ -28106,7 +28174,8 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 7.9e-07 + "output_cost_per_token": 7.9e-07, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-3-8b": { "input_cost_per_token": 5e-08, @@ -28115,7 +28184,8 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 8e-08 + "output_cost_per_token": 8e-08, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-3.1-70b": { "input_cost_per_token": 7.2e-07, @@ -28124,7 +28194,8 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 7.2e-07 + "output_cost_per_token": 7.2e-07, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-3.1-8b": { "input_cost_per_token": 5e-08, @@ -28133,7 +28204,9 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 8e-08 + "output_cost_per_token": 8e-08, + "supports_function_calling": true, + "supports_response_schema": true }, "vercel_ai_gateway/meta/llama-3.2-11b": { "input_cost_per_token": 1.6e-07, @@ -28142,7 +28215,10 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 1.6e-07 + "output_cost_per_token": 1.6e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-3.2-1b": { "input_cost_per_token": 1e-07, @@ -28160,7 +28236,9 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 1.5e-07 + "output_cost_per_token": 1.5e-07, + "supports_function_calling": true, + "supports_response_schema": true }, "vercel_ai_gateway/meta/llama-3.2-90b": { "input_cost_per_token": 7.2e-07, @@ -28169,7 +28247,10 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 7.2e-07 + "output_cost_per_token": 7.2e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-3.3-70b": { "input_cost_per_token": 7.2e-07, @@ -28178,7 +28259,9 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 7.2e-07 + "output_cost_per_token": 7.2e-07, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-4-maverick": { "input_cost_per_token": 2e-07, @@ -28187,7 +28270,8 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 6e-07 + "output_cost_per_token": 6e-07, + "supports_tool_choice": true }, "vercel_ai_gateway/meta/llama-4-scout": { "input_cost_per_token": 1e-07, @@ -28196,7 +28280,10 @@ "max_output_tokens": 8192, "max_tokens": 8192, "mode": "chat", - "output_cost_per_token": 3e-07 + "output_cost_per_token": 3e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/mistral/codestral": { "input_cost_per_token": 3e-07, @@ -28205,7 +28292,9 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 9e-07 + "output_cost_per_token": 9e-07, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/mistral/codestral-embed": { "input_cost_per_token": 1.5e-07, @@ -28223,7 +28312,10 @@ "max_output_tokens": 128000, "max_tokens": 128000, "mode": "chat", - "output_cost_per_token": 2.8e-07 + "output_cost_per_token": 2.8e-07, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/mistral/magistral-medium": { "input_cost_per_token": 2e-06, @@ -28232,7 +28324,10 @@ "max_output_tokens": 64000, "max_tokens": 64000, "mode": "chat", - "output_cost_per_token": 5e-06 + "output_cost_per_token": 5e-06, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/mistral/magistral-small": { "input_cost_per_token": 5e-07, @@ -28241,7 +28336,8 @@ "max_output_tokens": 64000, "max_tokens": 64000, "mode": "chat", - "output_cost_per_token": 1.5e-06 + "output_cost_per_token": 1.5e-06, + "supports_function_calling": true }, "vercel_ai_gateway/mistral/ministral-3b": { "input_cost_per_token": 4e-08, @@ -28250,7 +28346,9 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 4e-08 + "output_cost_per_token": 4e-08, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/mistral/ministral-8b": { "input_cost_per_token": 1e-07, @@ -28259,7 +28357,10 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 1e-07 + "output_cost_per_token": 1e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/mistral/mistral-embed": { "input_cost_per_token": 1e-07, @@ -28277,7 +28378,9 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 6e-06 + "output_cost_per_token": 6e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/mistral/mistral-saba-24b": { "input_cost_per_token": 7.9e-07, @@ -28295,7 +28398,10 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 3e-07 + "output_cost_per_token": 3e-07, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/mistral/mixtral-8x22b-instruct": { "input_cost_per_token": 1.2e-06, @@ -28304,7 +28410,8 @@ "max_output_tokens": 2048, "max_tokens": 2048, "mode": "chat", - "output_cost_per_token": 1.2e-06 + "output_cost_per_token": 1.2e-06, + "supports_function_calling": true }, "vercel_ai_gateway/mistral/pixtral-12b": { "input_cost_per_token": 1.5e-07, @@ -28313,7 +28420,11 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 1.5e-07 + "output_cost_per_token": 1.5e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/mistral/pixtral-large": { "input_cost_per_token": 2e-06, @@ -28322,7 +28433,11 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 6e-06 + "output_cost_per_token": 6e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/moonshotai/kimi-k2": { "input_cost_per_token": 5.5e-07, @@ -28331,7 +28446,9 @@ "max_output_tokens": 16384, "max_tokens": 16384, "mode": "chat", - "output_cost_per_token": 2.2e-06 + "output_cost_per_token": 2.2e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/morph/morph-v3-fast": { "input_cost_per_token": 8e-07, @@ -28358,7 +28475,9 @@ "max_output_tokens": 4096, "max_tokens": 4096, "mode": "chat", - "output_cost_per_token": 1.5e-06 + "output_cost_per_token": 1.5e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/openai/gpt-3.5-turbo-instruct": { "input_cost_per_token": 1.5e-06, @@ -28376,7 +28495,10 @@ "max_output_tokens": 4096, "max_tokens": 4096, "mode": "chat", - "output_cost_per_token": 3e-05 + "output_cost_per_token": 3e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/openai/gpt-4.1": { "cache_creation_input_token_cost": 0.0, @@ -28387,7 +28509,11 @@ "max_output_tokens": 32768, "max_tokens": 32768, "mode": "chat", - "output_cost_per_token": 8e-06 + "output_cost_per_token": 8e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/gpt-4.1-mini": { "cache_creation_input_token_cost": 0.0, @@ -28398,7 +28524,11 @@ "max_output_tokens": 32768, "max_tokens": 32768, "mode": "chat", - "output_cost_per_token": 1.6e-06 + "output_cost_per_token": 1.6e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/gpt-4.1-nano": { "cache_creation_input_token_cost": 0.0, @@ -28409,7 +28539,11 @@ "max_output_tokens": 32768, "max_tokens": 32768, "mode": "chat", - "output_cost_per_token": 4e-07 + "output_cost_per_token": 4e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/gpt-4o": { "cache_creation_input_token_cost": 0.0, @@ -28420,7 +28554,11 @@ "max_output_tokens": 16384, "max_tokens": 16384, "mode": "chat", - "output_cost_per_token": 1e-05 + "output_cost_per_token": 1e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/gpt-4o-mini": { "cache_creation_input_token_cost": 0.0, @@ -28431,7 +28569,11 @@ "max_output_tokens": 16384, "max_tokens": 16384, "mode": "chat", - "output_cost_per_token": 6e-07 + "output_cost_per_token": 6e-07, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/o1": { "cache_creation_input_token_cost": 0.0, @@ -28442,7 +28584,11 @@ "max_output_tokens": 100000, "max_tokens": 100000, "mode": "chat", - "output_cost_per_token": 6e-05 + "output_cost_per_token": 6e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/o3": { "cache_creation_input_token_cost": 0.0, @@ -28453,7 +28599,11 @@ "max_output_tokens": 100000, "max_tokens": 100000, "mode": "chat", - "output_cost_per_token": 8e-06 + "output_cost_per_token": 8e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/o3-mini": { "cache_creation_input_token_cost": 0.0, @@ -28464,7 +28614,10 @@ "max_output_tokens": 100000, "max_tokens": 100000, "mode": "chat", - "output_cost_per_token": 4.4e-06 + "output_cost_per_token": 4.4e-06, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/o4-mini": { "cache_creation_input_token_cost": 0.0, @@ -28475,7 +28628,11 @@ "max_output_tokens": 100000, "max_tokens": 100000, "mode": "chat", - "output_cost_per_token": 4.4e-06 + "output_cost_per_token": 4.4e-06, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true, + "supports_response_schema": true }, "vercel_ai_gateway/openai/text-embedding-3-large": { "input_cost_per_token": 1.3e-07, @@ -28547,7 +28704,10 @@ "max_output_tokens": 32000, "max_tokens": 32000, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/vercel/v0-1.5-md": { "input_cost_per_token": 3e-06, @@ -28556,7 +28716,10 @@ "max_output_tokens": 32768, "max_tokens": 32768, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/xai/grok-2": { "input_cost_per_token": 2e-06, @@ -28565,7 +28728,9 @@ "max_output_tokens": 4000, "max_tokens": 4000, "mode": "chat", - "output_cost_per_token": 1e-05 + "output_cost_per_token": 1e-05, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/xai/grok-2-vision": { "input_cost_per_token": 2e-06, @@ -28574,7 +28739,10 @@ "max_output_tokens": 32768, "max_tokens": 32768, "mode": "chat", - "output_cost_per_token": 1e-05 + "output_cost_per_token": 1e-05, + "supports_vision": true, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/xai/grok-3": { "input_cost_per_token": 3e-06, @@ -28583,7 +28751,9 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/xai/grok-3-fast": { "input_cost_per_token": 5e-06, @@ -28592,7 +28762,8 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 2.5e-05 + "output_cost_per_token": 2.5e-05, + "supports_function_calling": true }, "vercel_ai_gateway/xai/grok-3-mini": { "input_cost_per_token": 3e-07, @@ -28601,7 +28772,9 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 5e-07 + "output_cost_per_token": 5e-07, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/xai/grok-3-mini-fast": { "input_cost_per_token": 6e-07, @@ -28610,7 +28783,9 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 4e-06 + "output_cost_per_token": 4e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/xai/grok-4": { "input_cost_per_token": 3e-06, @@ -28619,7 +28794,9 @@ "max_output_tokens": 256000, "max_tokens": 256000, "mode": "chat", - "output_cost_per_token": 1.5e-05 + "output_cost_per_token": 1.5e-05, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/zai/glm-4.5": { "input_cost_per_token": 6e-07, @@ -28628,7 +28805,9 @@ "max_output_tokens": 131072, "max_tokens": 131072, "mode": "chat", - "output_cost_per_token": 2.2e-06 + "output_cost_per_token": 2.2e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/zai/glm-4.5-air": { "input_cost_per_token": 2e-07, @@ -28637,7 +28816,9 @@ "max_output_tokens": 96000, "max_tokens": 96000, "mode": "chat", - "output_cost_per_token": 1.1e-06 + "output_cost_per_token": 1.1e-06, + "supports_function_calling": true, + "supports_tool_choice": true }, "vercel_ai_gateway/zai/glm-4.6": { "litellm_provider": "vercel_ai_gateway", @@ -29799,7 +29980,9 @@ "mode": "chat", "output_cost_per_token": 1e-06, "source": "https://cloud.google.com/vertex-ai/generative-ai/pricing", - "supported_regions": ["global"], + "supported_regions": [ + "global" + ], "supports_function_calling": true, "supports_tool_choice": true }, @@ -29812,7 +29995,9 @@ "mode": "chat", "output_cost_per_token": 4e-06, "source": "https://cloud.google.com/vertex-ai/generative-ai/pricing", - "supported_regions": ["global"], + "supported_regions": [ + "global" + ], "supports_function_calling": true, "supports_tool_choice": true }, @@ -29825,7 +30010,9 @@ "mode": "chat", "output_cost_per_token": 1.2e-06, "source": "https://cloud.google.com/vertex-ai/generative-ai/pricing", - "supported_regions": ["global"], + "supported_regions": [ + "global" + ], "supports_function_calling": true, "supports_tool_choice": true }, @@ -29838,7 +30025,9 @@ "mode": "chat", "output_cost_per_token": 1.2e-06, "source": "https://cloud.google.com/vertex-ai/generative-ai/pricing", - "supported_regions": ["global"], + "supported_regions": [ + "global" + ], "supports_function_calling": true, "supports_tool_choice": true }, @@ -34787,4 +34976,4 @@ "output_cost_per_token": 0, "supports_reasoning": true } -} \ No newline at end of file +} From 7dd0248987692d8908d0aa2cb55cfa3624318a0b Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:04:15 +0530 Subject: [PATCH 022/511] Revert "fix: models loadbalancing billing issue by filter (#18891) (#19220)" This reverts commit 72e519345149f4b305645c51943b0f2cfd6c8acd. --- litellm/proxy/auth/model_checks.py | 25 +- litellm/proxy/litellm_pre_call_utils.py | 31 --- litellm/router.py | 12 +- litellm/router_utils/common_utils.py | 79 +----- ...est_filter_deployments_by_access_groups.py | 227 ------------------ 5 files changed, 6 insertions(+), 368 deletions(-) delete mode 100644 tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py diff --git a/litellm/proxy/auth/model_checks.py b/litellm/proxy/auth/model_checks.py index af2574d88ee..71ae1348f39 100644 --- a/litellm/proxy/auth/model_checks.py +++ b/litellm/proxy/auth/model_checks.py @@ -64,27 +64,6 @@ def _get_models_from_access_groups( return all_models -def get_access_groups_from_models( - model_access_groups: Dict[str, List[str]], - models: List[str], -) -> List[str]: - """ - Extract access group names from a models list. - - Given a models list like ["gpt-4", "beta-models", "claude-v1"] - and access groups like {"beta-models": ["gpt-5", "gpt-6"]}, - returns ["beta-models"]. - - This is used to pass allowed access groups to the router for filtering - deployments during load balancing (GitHub issue #18333). - """ - access_groups = [] - for model in models: - if model in model_access_groups: - access_groups.append(model) - return access_groups - - async def get_mcp_server_ids( user_api_key_dict: UserAPIKeyAuth, ) -> List[str]: @@ -101,6 +80,7 @@ async def get_mcp_server_ids( # Make a direct SQL query to get just the mcp_servers try: + result = await prisma_client.db.litellm_objectpermissiontable.find_unique( where={"object_permission_id": user_api_key_dict.object_permission_id}, ) @@ -196,7 +176,6 @@ def get_complete_model_list( """ unique_models = [] - def append_unique(models): for model in models: if model not in unique_models: @@ -209,7 +188,7 @@ def get_complete_model_list( else: append_unique(proxy_model_list) if include_model_access_groups: - append_unique(list(model_access_groups.keys())) # TODO: keys order + append_unique(list(model_access_groups.keys())) # TODO: keys order if user_model: append_unique([user_model]) diff --git a/litellm/proxy/litellm_pre_call_utils.py b/litellm/proxy/litellm_pre_call_utils.py index 72f23e609ab..9be78264e85 100644 --- a/litellm/proxy/litellm_pre_call_utils.py +++ b/litellm/proxy/litellm_pre_call_utils.py @@ -1021,37 +1021,6 @@ async def add_litellm_data_to_request( # noqa: PLR0915 "user_api_key_user_max_budget" ] = user_api_key_dict.user_max_budget - # Extract allowed access groups for router filtering (GitHub issue #18333) - # This allows the router to filter deployments based on key's and team's access groups - # NOTE: We keep key and team access groups SEPARATE because a key doesn't always - # inherit all team access groups (per maintainer feedback). - if llm_router is not None: - from litellm.proxy.auth.model_checks import get_access_groups_from_models - - model_access_groups = llm_router.get_model_access_groups() - - # Key-level access groups (from user_api_key_dict.models) - key_models = list(user_api_key_dict.models) if user_api_key_dict.models else [] - key_allowed_access_groups = get_access_groups_from_models( - model_access_groups=model_access_groups, models=key_models - ) - if key_allowed_access_groups: - data[_metadata_variable_name][ - "user_api_key_allowed_access_groups" - ] = key_allowed_access_groups - - # Team-level access groups (from user_api_key_dict.team_models) - team_models = ( - list(user_api_key_dict.team_models) if user_api_key_dict.team_models else [] - ) - team_allowed_access_groups = get_access_groups_from_models( - model_access_groups=model_access_groups, models=team_models - ) - if team_allowed_access_groups: - data[_metadata_variable_name][ - "user_api_key_team_allowed_access_groups" - ] = team_allowed_access_groups - data[_metadata_variable_name]["user_api_key_metadata"] = user_api_key_dict.metadata _headers = dict(request.headers) _headers.pop( diff --git a/litellm/router.py b/litellm/router.py index 65445e29c41..d01c8443dab 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -88,7 +88,6 @@ from litellm.router_utils.clientside_credential_handler import ( is_clientside_credential, ) from litellm.router_utils.common_utils import ( - filter_deployments_by_access_groups, filter_team_based_models, filter_web_search_deployments, ) @@ -8088,17 +8087,10 @@ class Router: request_kwargs=request_kwargs, ) - verbose_router_logger.debug(f"healthy_deployments after web search filter: {healthy_deployments}") - - # Filter by allowed access groups (GitHub issue #18333) - # This prevents cross-team load balancing when teams have models with same name in different access groups - healthy_deployments = filter_deployments_by_access_groups( - healthy_deployments=healthy_deployments, - request_kwargs=request_kwargs, + verbose_router_logger.debug( + f"healthy_deployments after web search filter: {healthy_deployments}" ) - verbose_router_logger.debug(f"healthy_deployments after access group filter: {healthy_deployments}") - if isinstance(healthy_deployments, dict): return healthy_deployments diff --git a/litellm/router_utils/common_utils.py b/litellm/router_utils/common_utils.py index 2c0ea5976d6..10acc343abd 100644 --- a/litellm/router_utils/common_utils.py +++ b/litellm/router_utils/common_utils.py @@ -75,7 +75,6 @@ def filter_team_based_models( if deployment.get("model_info", {}).get("id") not in ids_to_remove ] - def _deployment_supports_web_search(deployment: Dict) -> bool: """ Check if a deployment supports web search. @@ -113,7 +112,7 @@ def filter_web_search_deployments( is_web_search_request = False tools = request_kwargs.get("tools") or [] for tool in tools: - # These are the two websearch tools for OpenAI / Azure. + # These are the two websearch tools for OpenAI / Azure. if tool.get("type") == "web_search" or tool.get("type") == "web_search_preview": is_web_search_request = True break @@ -122,82 +121,8 @@ def filter_web_search_deployments( return healthy_deployments # Filter out deployments that don't support web search - final_deployments = [ - d for d in healthy_deployments if _deployment_supports_web_search(d) - ] + final_deployments = [d for d in healthy_deployments if _deployment_supports_web_search(d)] if len(healthy_deployments) > 0 and len(final_deployments) == 0: verbose_logger.warning("No deployments support web search for request") return final_deployments - -def filter_deployments_by_access_groups( - healthy_deployments: Union[List[Dict], Dict], - request_kwargs: Optional[Dict] = None, -) -> Union[List[Dict], Dict]: - """ - Filter deployments to only include those matching the user's allowed access groups. - - Reads from TWO separate metadata fields (per maintainer feedback): - - `user_api_key_allowed_access_groups`: Access groups from the API Key's models. - - `user_api_key_team_allowed_access_groups`: Access groups from the Team's models. - - A deployment is included if its access_groups overlap with EITHER the key's - or the team's allowed access groups. Deployments with no access_groups are - always included (not restricted). - - This prevents cross-team load balancing when multiple teams have models with - the same name but in different access groups (GitHub issue #18333). - """ - if request_kwargs is None: - return healthy_deployments - - if isinstance(healthy_deployments, dict): - return healthy_deployments - - metadata = request_kwargs.get("metadata") or {} - litellm_metadata = request_kwargs.get("litellm_metadata") or {} - - # Gather key-level allowed access groups - key_allowed_access_groups = ( - metadata.get("user_api_key_allowed_access_groups") - or litellm_metadata.get("user_api_key_allowed_access_groups") - or [] - ) - - # Gather team-level allowed access groups - team_allowed_access_groups = ( - metadata.get("user_api_key_team_allowed_access_groups") - or litellm_metadata.get("user_api_key_team_allowed_access_groups") - or [] - ) - - # Combine both for the final allowed set - combined_allowed_access_groups = list(key_allowed_access_groups) + list( - team_allowed_access_groups - ) - - # If no access groups specified from either source, return all deployments (backwards compatible) - if not combined_allowed_access_groups: - return healthy_deployments - - allowed_set = set(combined_allowed_access_groups) - filtered = [] - for deployment in healthy_deployments: - model_info = deployment.get("model_info") or {} - deployment_access_groups = model_info.get("access_groups") or [] - - # If deployment has no access groups, include it (not restricted) - if not deployment_access_groups: - filtered.append(deployment) - continue - - # Include if any of deployment's groups overlap with allowed groups - if set(deployment_access_groups) & allowed_set: - filtered.append(deployment) - - if len(healthy_deployments) > 0 and len(filtered) == 0: - verbose_logger.warning( - f"No deployments match allowed access groups {combined_allowed_access_groups}" - ) - - return filtered diff --git a/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py b/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py deleted file mode 100644 index 9ac5072c5d8..00000000000 --- a/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py +++ /dev/null @@ -1,227 +0,0 @@ -""" -Unit tests for filter_deployments_by_access_groups function. - -Tests the fix for GitHub issue #18333: Models loadbalanced outside of Model Access Group. -""" - -import pytest - -from litellm.router_utils.common_utils import filter_deployments_by_access_groups - - -class TestFilterDeploymentsByAccessGroups: - """Tests for the filter_deployments_by_access_groups function.""" - - def test_no_filter_when_no_access_groups_in_metadata(self): - """When no allowed_access_groups in metadata, return all deployments.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - ] - request_kwargs = {"metadata": {"user_api_key_team_id": "team-1"}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 2 # All deployments returned - - def test_filter_to_single_access_group(self): - """Filter to only deployments matching allowed access group.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - ] - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "2" - - def test_filter_with_multiple_allowed_groups(self): - """Filter with multiple allowed access groups.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - {"model_info": {"id": "3", "access_groups": ["AG3"]}}, - ] - request_kwargs = { - "metadata": {"user_api_key_allowed_access_groups": ["AG1", "AG2"]} - } - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 2 - ids = [d["model_info"]["id"] for d in result] - assert "1" in ids - assert "2" in ids - assert "3" not in ids - - def test_deployment_with_multiple_access_groups(self): - """Deployment with multiple access groups should match if any overlap.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1", "AG2"]}}, - {"model_info": {"id": "2", "access_groups": ["AG3"]}}, - ] - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "1" - - def test_deployment_without_access_groups_included(self): - """Deployments without access groups should be included (not restricted).""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2"}}, # No access_groups - {"model_info": {"id": "3", "access_groups": []}}, # Empty access_groups - ] - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - # Should include deployments 2 and 3 (no restrictions) - assert len(result) == 2 - ids = [d["model_info"]["id"] for d in result] - assert "2" in ids - assert "3" in ids - - def test_dict_deployment_passes_through(self): - """When deployment is a dict (specific deployment), pass through.""" - deployment = {"model_info": {"id": "1", "access_groups": ["AG1"]}} - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployment, - request_kwargs=request_kwargs, - ) - - assert result == deployment # Unchanged - - def test_none_request_kwargs_passes_through(self): - """When request_kwargs is None, return deployments unchanged.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - ] - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=None, - ) - - assert result == deployments - - def test_litellm_metadata_fallback(self): - """Should also check litellm_metadata for allowed access groups.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - ] - request_kwargs = { - "litellm_metadata": {"user_api_key_allowed_access_groups": ["AG1"]} - } - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "1" - - -def test_filter_deployments_by_access_groups_issue_18333(): - """ - Regression test for GitHub issue #18333. - - Scenario: Two models named 'gpt-5' in different access groups (AG1, AG2). - Team2 has access to AG2 only. When Team2 requests 'gpt-5', only the AG2 - deployment should be available for load balancing. - """ - deployments = [ - { - "model_name": "gpt-5", - "litellm_params": {"model": "gpt-4.1", "api_key": "key-1"}, - "model_info": {"id": "ag1-deployment", "access_groups": ["AG1"]}, - }, - { - "model_name": "gpt-5", - "litellm_params": {"model": "gpt-4o", "api_key": "key-2"}, - "model_info": {"id": "ag2-deployment", "access_groups": ["AG2"]}, - }, - ] - - # Team2's request with allowed access groups - request_kwargs = { - "metadata": { - "user_api_key_team_id": "team-2", - "user_api_key_allowed_access_groups": ["AG2"], - } - } - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - # Only AG2 deployment should be returned - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "ag2-deployment" - assert result[0]["litellm_params"]["model"] == "gpt-4o" - - -def test_get_access_groups_from_models(): - """ - Test the helper function that extracts access group names from models list. - This is used by the proxy to populate user_api_key_allowed_access_groups. - """ - from litellm.proxy.auth.model_checks import get_access_groups_from_models - - # Setup: access groups definition - model_access_groups = { - "AG1": ["gpt-4", "gpt-5"], - "AG2": ["claude-v1", "claude-v2"], - "beta-models": ["gpt-5-turbo"], - } - - # Test 1: Extract access groups from models list - models = ["gpt-4", "AG1", "AG2", "some-other-model"] - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=models - ) - assert set(result) == {"AG1", "AG2"} - - # Test 2: No access groups in models list - models = ["gpt-4", "claude-v1", "some-model"] - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=models - ) - assert result == [] - - # Test 3: Empty models list - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=[] - ) - assert result == [] - - # Test 4: All access groups - models = ["AG1", "AG2", "beta-models"] - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=models - ) - assert set(result) == {"AG1", "AG2", "beta-models"} From 86ae627007fb1d0b2088925547287d0cd99e32da Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:08:19 +0530 Subject: [PATCH 023/511] Fix litellm/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py tests --- .../test_semantic_tool_filter_e2e.py | 19 +++++++++++++++++-- .../mcp_server/test_semantic_tool_filter.py | 16 +++++++++++++--- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/tests/mcp_tests/test_semantic_tool_filter_e2e.py b/tests/mcp_tests/test_semantic_tool_filter_e2e.py index cf951c1884b..91c072ae8a3 100644 --- a/tests/mcp_tests/test_semantic_tool_filter_e2e.py +++ b/tests/mcp_tests/test_semantic_tool_filter_e2e.py @@ -12,8 +12,19 @@ sys.path.insert(0, os.path.abspath("../..")) from mcp.types import Tool as MCPTool +# Check if semantic-router is available +try: + import semantic_router + SEMANTIC_ROUTER_AVAILABLE = True +except ImportError: + SEMANTIC_ROUTER_AVAILABLE = False + @pytest.mark.asyncio +@pytest.mark.skipif( + not SEMANTIC_ROUTER_AVAILABLE, + reason="semantic-router not installed. Install with: pip install 'litellm[semantic-router]'" +) async def test_e2e_semantic_filter(): """E2E: Load router/filter and verify hook filters tools.""" from litellm import Router @@ -37,8 +48,6 @@ async def test_e2e_semantic_filter(): enabled=True, ) - hook = SemanticToolFilterHook(filter_instance) - # Create 10 tools tools = [ MCPTool(name="gmail_send", description="Send an email via Gmail", inputSchema={"type": "object"}), @@ -53,10 +62,16 @@ async def test_e2e_semantic_filter(): MCPTool(name="note_add", description="Add note", inputSchema={"type": "object"}), ] + # Build router with test tools + filter_instance._build_router(tools) + + hook = SemanticToolFilterHook(filter_instance) + data = { "model": "gpt-4", "messages": [{"role": "user", "content": "Send an email and create a calendar event"}], "tools": tools, + "metadata": {}, # Initialize metadata dict for hook to store filter stats } # Call hook diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py index 8d35f5bbdc9..87c597c659b 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py @@ -71,6 +71,9 @@ async def test_semantic_filter_basic_filtering(): enabled=True, ) + # Build router with the tools before filtering + filter_instance._build_router(tools) + # Filter tools with email-related query filtered = await filter_instance.filter_tools( query="send an email to john@example.com", @@ -139,6 +142,9 @@ async def test_semantic_filter_top_k_limiting(): enabled=True, ) + # Build router with the tools before filtering + filter_instance._build_router(tools) + # Filter tools filtered = await filter_instance.filter_tools( query="test query", @@ -297,21 +303,25 @@ async def test_semantic_filter_hook_triggers_on_completion(): enabled=True, ) - # Create hook - hook = SemanticToolFilterHook(filter_instance) - # Prepare data - completion request with tools tools = [ MCPTool(name=f"tool_{i}", description=f"Tool {i}", inputSchema={"type": "object"}) for i in range(10) ] + # Build router with the tools before filtering + filter_instance._build_router(tools) + + # Create hook + hook = SemanticToolFilterHook(filter_instance) + data = { "model": "gpt-4", "messages": [ {"role": "user", "content": "Send an email"} ], "tools": tools, + "metadata": {}, # Hook needs metadata field to store filter stats } # Mock user API key dict and cache From b379fb6338690c674f1ff86c7fa1d58734148b04 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:10:29 +0530 Subject: [PATCH 024/511] Fix code quality tests --- docs/my-website/docs/proxy/config_settings.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/my-website/docs/proxy/config_settings.md b/docs/my-website/docs/proxy/config_settings.md index 264c7d765b3..385b4b0de32 100644 --- a/docs/my-website/docs/proxy/config_settings.md +++ b/docs/my-website/docs/proxy/config_settings.md @@ -545,6 +545,9 @@ router_settings: | DEFAULT_MAX_TOKENS | Default maximum tokens for LLM calls. Default is 4096 | DEFAULT_MAX_TOKENS_FOR_TRITON | Default maximum tokens for Triton models. Default is 2000 | DEFAULT_MAX_REDIS_BATCH_CACHE_SIZE | Default maximum size for redis batch cache. Default is 1000 +| DEFAULT_MCP_SEMANTIC_FILTER_EMBEDDING_MODEL | Default embedding model for MCP semantic tool filtering. Default is "text-embedding-3-small" +| DEFAULT_MCP_SEMANTIC_FILTER_SIMILARITY_THRESHOLD | Default similarity threshold for MCP semantic tool filtering. Default is 0.3 +| DEFAULT_MCP_SEMANTIC_FILTER_TOP_K | Default number of top results to return for MCP semantic tool filtering. Default is 10 | DEFAULT_MOCK_RESPONSE_COMPLETION_TOKEN_COUNT | Default token count for mock response completions. Default is 20 | DEFAULT_MOCK_RESPONSE_PROMPT_TOKEN_COUNT | Default token count for mock response prompts. Default is 10 | DEFAULT_MODEL_CREATED_AT_TIME | Default creation timestamp for models. Default is 1677610602 @@ -802,6 +805,7 @@ router_settings: | MAXIMUM_TRACEBACK_LINES_TO_LOG | Maximum number of lines to log in traceback in LiteLLM Logs UI. Default is 100 | MAX_RETRY_DELAY | Maximum delay in seconds for retrying requests. Default is 8.0 | MAX_LANGFUSE_INITIALIZED_CLIENTS | Maximum number of Langfuse clients to initialize on proxy. Default is 50. This is set since langfuse initializes 1 thread everytime a client is initialized. We've had an incident in the past where we reached 100% cpu utilization because Langfuse was initialized several times. +| MAX_MCP_SEMANTIC_FILTER_TOOLS_HEADER_LENGTH | Maximum header length for MCP semantic filter tools. Default is 150 | MIN_NON_ZERO_TEMPERATURE | Minimum non-zero temperature value. Default is 0.0001 | MINIMUM_PROMPT_CACHE_TOKEN_COUNT | Minimum token count for caching a prompt. Default is 1024 | MISTRAL_API_BASE | Base URL for Mistral API. Default is https://api.mistral.ai From ecb6413028af12afd0924c7158c0a8aa964fe8ba Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:22:18 +0530 Subject: [PATCH 025/511] Revert "add missing indexes on VerificationToken table (#20040)" This reverts commit 1e8848ca97bd53e596e715162d35d0d7953c9a08. --- .../migration.sql | 8 -------- .../litellm_proxy_extras/schema.prisma | 10 ---------- litellm/proxy/schema.prisma | 10 ---------- schema.prisma | 10 ---------- 4 files changed, 38 deletions(-) delete mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql deleted file mode 100644 index 572eea9b529..00000000000 --- a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql +++ /dev/null @@ -1,8 +0,0 @@ --- CreateIndex -CREATE INDEX "LiteLLM_VerificationToken_user_id_team_id_idx" ON "LiteLLM_VerificationToken"("user_id", "team_id"); - --- CreateIndex -CREATE INDEX "LiteLLM_VerificationToken_team_id_idx" ON "LiteLLM_VerificationToken"("team_id"); - --- CreateIndex -CREATE INDEX "LiteLLM_VerificationToken_budget_reset_at_expires_idx" ON "LiteLLM_VerificationToken"("budget_reset_at", "expires"); diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma index 3b81da10923..b118400b620 100644 --- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma +++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma @@ -305,16 +305,6 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) - - // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 - @@index([user_id, team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 - @@index([team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 - @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma index 3b81da10923..b118400b620 100644 --- a/litellm/proxy/schema.prisma +++ b/litellm/proxy/schema.prisma @@ -305,16 +305,6 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) - - // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 - @@index([user_id, team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 - @@index([team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 - @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/schema.prisma b/schema.prisma index 3b81da10923..b118400b620 100644 --- a/schema.prisma +++ b/schema.prisma @@ -305,16 +305,6 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) - - // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 - @@index([user_id, team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 - @@index([team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 - @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking From a92a0fa686dc394f0b6505d85dd29660b42a2993 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:53:07 +0530 Subject: [PATCH 026/511] Add support for delete via only file_id --- litellm/llms/gemini/files/transformation.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/litellm/llms/gemini/files/transformation.py b/litellm/llms/gemini/files/transformation.py index 37f1376c2b1..35e1b677b4c 100644 --- a/litellm/llms/gemini/files/transformation.py +++ b/litellm/llms/gemini/files/transformation.py @@ -299,7 +299,7 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): # Extract the file path from full URI file_name = file_id.split("/v1beta/")[-1] else: - file_name = file_id + file_name = f"files/{file_id}" # Construct the delete URL url = f"{api_base}/v1beta/{file_name}" From cad15e21cc054c5ccfa5d5dcc67671c63020962d Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 13:18:44 +0530 Subject: [PATCH 027/511] Add support for delete via only file_id --- litellm/llms/gemini/files/transformation.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/litellm/llms/gemini/files/transformation.py b/litellm/llms/gemini/files/transformation.py index 35e1b677b4c..4dc61dc5f48 100644 --- a/litellm/llms/gemini/files/transformation.py +++ b/litellm/llms/gemini/files/transformation.py @@ -299,7 +299,9 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): # Extract the file path from full URI file_name = file_id.split("/v1beta/")[-1] else: - file_name = f"files/{file_id}" + if not file_id.startswith("files/"): + file_id = f"files/{file_id}" + file_name = file_id # Construct the delete URL url = f"{api_base}/v1beta/{file_name}" From 1b1854b704ae8b3640984fa4df26f37091603dd9 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 14:29:16 +0530 Subject: [PATCH 028/511] Revert "Litellm tuesday cicd release" --- docs/my-website/docs/proxy/config_settings.md | 4 - .../migration.sql | 8 + .../litellm_proxy_extras/schema.prisma | 10 + litellm/proxy/auth/model_checks.py | 25 +- litellm/proxy/litellm_pre_call_utils.py | 31 +++ litellm/proxy/schema.prisma | 10 + litellm/router.py | 12 +- litellm/router_utils/common_utils.py | 79 +++++- schema.prisma | 10 + .../test_semantic_tool_filter_e2e.py | 19 +- .../mcp_server/test_semantic_tool_filter.py | 16 +- ...est_filter_deployments_by_access_groups.py | 227 ++++++++++++++++++ 12 files changed, 411 insertions(+), 40 deletions(-) create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql create mode 100644 tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py diff --git a/docs/my-website/docs/proxy/config_settings.md b/docs/my-website/docs/proxy/config_settings.md index 385b4b0de32..264c7d765b3 100644 --- a/docs/my-website/docs/proxy/config_settings.md +++ b/docs/my-website/docs/proxy/config_settings.md @@ -545,9 +545,6 @@ router_settings: | DEFAULT_MAX_TOKENS | Default maximum tokens for LLM calls. Default is 4096 | DEFAULT_MAX_TOKENS_FOR_TRITON | Default maximum tokens for Triton models. Default is 2000 | DEFAULT_MAX_REDIS_BATCH_CACHE_SIZE | Default maximum size for redis batch cache. Default is 1000 -| DEFAULT_MCP_SEMANTIC_FILTER_EMBEDDING_MODEL | Default embedding model for MCP semantic tool filtering. Default is "text-embedding-3-small" -| DEFAULT_MCP_SEMANTIC_FILTER_SIMILARITY_THRESHOLD | Default similarity threshold for MCP semantic tool filtering. Default is 0.3 -| DEFAULT_MCP_SEMANTIC_FILTER_TOP_K | Default number of top results to return for MCP semantic tool filtering. Default is 10 | DEFAULT_MOCK_RESPONSE_COMPLETION_TOKEN_COUNT | Default token count for mock response completions. Default is 20 | DEFAULT_MOCK_RESPONSE_PROMPT_TOKEN_COUNT | Default token count for mock response prompts. Default is 10 | DEFAULT_MODEL_CREATED_AT_TIME | Default creation timestamp for models. Default is 1677610602 @@ -805,7 +802,6 @@ router_settings: | MAXIMUM_TRACEBACK_LINES_TO_LOG | Maximum number of lines to log in traceback in LiteLLM Logs UI. Default is 100 | MAX_RETRY_DELAY | Maximum delay in seconds for retrying requests. Default is 8.0 | MAX_LANGFUSE_INITIALIZED_CLIENTS | Maximum number of Langfuse clients to initialize on proxy. Default is 50. This is set since langfuse initializes 1 thread everytime a client is initialized. We've had an incident in the past where we reached 100% cpu utilization because Langfuse was initialized several times. -| MAX_MCP_SEMANTIC_FILTER_TOOLS_HEADER_LENGTH | Maximum header length for MCP semantic filter tools. Default is 150 | MIN_NON_ZERO_TEMPERATURE | Minimum non-zero temperature value. Default is 0.0001 | MINIMUM_PROMPT_CACHE_TOKEN_COUNT | Minimum token count for caching a prompt. Default is 1024 | MISTRAL_API_BASE | Base URL for Mistral API. Default is https://api.mistral.ai diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql new file mode 100644 index 00000000000..572eea9b529 --- /dev/null +++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql @@ -0,0 +1,8 @@ +-- CreateIndex +CREATE INDEX "LiteLLM_VerificationToken_user_id_team_id_idx" ON "LiteLLM_VerificationToken"("user_id", "team_id"); + +-- CreateIndex +CREATE INDEX "LiteLLM_VerificationToken_team_id_idx" ON "LiteLLM_VerificationToken"("team_id"); + +-- CreateIndex +CREATE INDEX "LiteLLM_VerificationToken_budget_reset_at_expires_idx" ON "LiteLLM_VerificationToken"("budget_reset_at", "expires"); diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma index b118400b620..3b81da10923 100644 --- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma +++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma @@ -305,6 +305,16 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) + + // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 + @@index([user_id, team_id]) + + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 + @@index([team_id]) + + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 + @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/litellm/proxy/auth/model_checks.py b/litellm/proxy/auth/model_checks.py index 71ae1348f39..af2574d88ee 100644 --- a/litellm/proxy/auth/model_checks.py +++ b/litellm/proxy/auth/model_checks.py @@ -64,6 +64,27 @@ def _get_models_from_access_groups( return all_models +def get_access_groups_from_models( + model_access_groups: Dict[str, List[str]], + models: List[str], +) -> List[str]: + """ + Extract access group names from a models list. + + Given a models list like ["gpt-4", "beta-models", "claude-v1"] + and access groups like {"beta-models": ["gpt-5", "gpt-6"]}, + returns ["beta-models"]. + + This is used to pass allowed access groups to the router for filtering + deployments during load balancing (GitHub issue #18333). + """ + access_groups = [] + for model in models: + if model in model_access_groups: + access_groups.append(model) + return access_groups + + async def get_mcp_server_ids( user_api_key_dict: UserAPIKeyAuth, ) -> List[str]: @@ -80,7 +101,6 @@ async def get_mcp_server_ids( # Make a direct SQL query to get just the mcp_servers try: - result = await prisma_client.db.litellm_objectpermissiontable.find_unique( where={"object_permission_id": user_api_key_dict.object_permission_id}, ) @@ -176,6 +196,7 @@ def get_complete_model_list( """ unique_models = [] + def append_unique(models): for model in models: if model not in unique_models: @@ -188,7 +209,7 @@ def get_complete_model_list( else: append_unique(proxy_model_list) if include_model_access_groups: - append_unique(list(model_access_groups.keys())) # TODO: keys order + append_unique(list(model_access_groups.keys())) # TODO: keys order if user_model: append_unique([user_model]) diff --git a/litellm/proxy/litellm_pre_call_utils.py b/litellm/proxy/litellm_pre_call_utils.py index 9be78264e85..72f23e609ab 100644 --- a/litellm/proxy/litellm_pre_call_utils.py +++ b/litellm/proxy/litellm_pre_call_utils.py @@ -1021,6 +1021,37 @@ async def add_litellm_data_to_request( # noqa: PLR0915 "user_api_key_user_max_budget" ] = user_api_key_dict.user_max_budget + # Extract allowed access groups for router filtering (GitHub issue #18333) + # This allows the router to filter deployments based on key's and team's access groups + # NOTE: We keep key and team access groups SEPARATE because a key doesn't always + # inherit all team access groups (per maintainer feedback). + if llm_router is not None: + from litellm.proxy.auth.model_checks import get_access_groups_from_models + + model_access_groups = llm_router.get_model_access_groups() + + # Key-level access groups (from user_api_key_dict.models) + key_models = list(user_api_key_dict.models) if user_api_key_dict.models else [] + key_allowed_access_groups = get_access_groups_from_models( + model_access_groups=model_access_groups, models=key_models + ) + if key_allowed_access_groups: + data[_metadata_variable_name][ + "user_api_key_allowed_access_groups" + ] = key_allowed_access_groups + + # Team-level access groups (from user_api_key_dict.team_models) + team_models = ( + list(user_api_key_dict.team_models) if user_api_key_dict.team_models else [] + ) + team_allowed_access_groups = get_access_groups_from_models( + model_access_groups=model_access_groups, models=team_models + ) + if team_allowed_access_groups: + data[_metadata_variable_name][ + "user_api_key_team_allowed_access_groups" + ] = team_allowed_access_groups + data[_metadata_variable_name]["user_api_key_metadata"] = user_api_key_dict.metadata _headers = dict(request.headers) _headers.pop( diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma index b118400b620..3b81da10923 100644 --- a/litellm/proxy/schema.prisma +++ b/litellm/proxy/schema.prisma @@ -305,6 +305,16 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) + + // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 + @@index([user_id, team_id]) + + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 + @@index([team_id]) + + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 + @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/litellm/router.py b/litellm/router.py index d01c8443dab..65445e29c41 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -88,6 +88,7 @@ from litellm.router_utils.clientside_credential_handler import ( is_clientside_credential, ) from litellm.router_utils.common_utils import ( + filter_deployments_by_access_groups, filter_team_based_models, filter_web_search_deployments, ) @@ -8087,10 +8088,17 @@ class Router: request_kwargs=request_kwargs, ) - verbose_router_logger.debug( - f"healthy_deployments after web search filter: {healthy_deployments}" + verbose_router_logger.debug(f"healthy_deployments after web search filter: {healthy_deployments}") + + # Filter by allowed access groups (GitHub issue #18333) + # This prevents cross-team load balancing when teams have models with same name in different access groups + healthy_deployments = filter_deployments_by_access_groups( + healthy_deployments=healthy_deployments, + request_kwargs=request_kwargs, ) + verbose_router_logger.debug(f"healthy_deployments after access group filter: {healthy_deployments}") + if isinstance(healthy_deployments, dict): return healthy_deployments diff --git a/litellm/router_utils/common_utils.py b/litellm/router_utils/common_utils.py index 10acc343abd..2c0ea5976d6 100644 --- a/litellm/router_utils/common_utils.py +++ b/litellm/router_utils/common_utils.py @@ -75,6 +75,7 @@ def filter_team_based_models( if deployment.get("model_info", {}).get("id") not in ids_to_remove ] + def _deployment_supports_web_search(deployment: Dict) -> bool: """ Check if a deployment supports web search. @@ -112,7 +113,7 @@ def filter_web_search_deployments( is_web_search_request = False tools = request_kwargs.get("tools") or [] for tool in tools: - # These are the two websearch tools for OpenAI / Azure. + # These are the two websearch tools for OpenAI / Azure. if tool.get("type") == "web_search" or tool.get("type") == "web_search_preview": is_web_search_request = True break @@ -121,8 +122,82 @@ def filter_web_search_deployments( return healthy_deployments # Filter out deployments that don't support web search - final_deployments = [d for d in healthy_deployments if _deployment_supports_web_search(d)] + final_deployments = [ + d for d in healthy_deployments if _deployment_supports_web_search(d) + ] if len(healthy_deployments) > 0 and len(final_deployments) == 0: verbose_logger.warning("No deployments support web search for request") return final_deployments + +def filter_deployments_by_access_groups( + healthy_deployments: Union[List[Dict], Dict], + request_kwargs: Optional[Dict] = None, +) -> Union[List[Dict], Dict]: + """ + Filter deployments to only include those matching the user's allowed access groups. + + Reads from TWO separate metadata fields (per maintainer feedback): + - `user_api_key_allowed_access_groups`: Access groups from the API Key's models. + - `user_api_key_team_allowed_access_groups`: Access groups from the Team's models. + + A deployment is included if its access_groups overlap with EITHER the key's + or the team's allowed access groups. Deployments with no access_groups are + always included (not restricted). + + This prevents cross-team load balancing when multiple teams have models with + the same name but in different access groups (GitHub issue #18333). + """ + if request_kwargs is None: + return healthy_deployments + + if isinstance(healthy_deployments, dict): + return healthy_deployments + + metadata = request_kwargs.get("metadata") or {} + litellm_metadata = request_kwargs.get("litellm_metadata") or {} + + # Gather key-level allowed access groups + key_allowed_access_groups = ( + metadata.get("user_api_key_allowed_access_groups") + or litellm_metadata.get("user_api_key_allowed_access_groups") + or [] + ) + + # Gather team-level allowed access groups + team_allowed_access_groups = ( + metadata.get("user_api_key_team_allowed_access_groups") + or litellm_metadata.get("user_api_key_team_allowed_access_groups") + or [] + ) + + # Combine both for the final allowed set + combined_allowed_access_groups = list(key_allowed_access_groups) + list( + team_allowed_access_groups + ) + + # If no access groups specified from either source, return all deployments (backwards compatible) + if not combined_allowed_access_groups: + return healthy_deployments + + allowed_set = set(combined_allowed_access_groups) + filtered = [] + for deployment in healthy_deployments: + model_info = deployment.get("model_info") or {} + deployment_access_groups = model_info.get("access_groups") or [] + + # If deployment has no access groups, include it (not restricted) + if not deployment_access_groups: + filtered.append(deployment) + continue + + # Include if any of deployment's groups overlap with allowed groups + if set(deployment_access_groups) & allowed_set: + filtered.append(deployment) + + if len(healthy_deployments) > 0 and len(filtered) == 0: + verbose_logger.warning( + f"No deployments match allowed access groups {combined_allowed_access_groups}" + ) + + return filtered diff --git a/schema.prisma b/schema.prisma index b118400b620..3b81da10923 100644 --- a/schema.prisma +++ b/schema.prisma @@ -305,6 +305,16 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) + + // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 + @@index([user_id, team_id]) + + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 + @@index([team_id]) + + // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 + @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/tests/mcp_tests/test_semantic_tool_filter_e2e.py b/tests/mcp_tests/test_semantic_tool_filter_e2e.py index 91c072ae8a3..cf951c1884b 100644 --- a/tests/mcp_tests/test_semantic_tool_filter_e2e.py +++ b/tests/mcp_tests/test_semantic_tool_filter_e2e.py @@ -12,19 +12,8 @@ sys.path.insert(0, os.path.abspath("../..")) from mcp.types import Tool as MCPTool -# Check if semantic-router is available -try: - import semantic_router - SEMANTIC_ROUTER_AVAILABLE = True -except ImportError: - SEMANTIC_ROUTER_AVAILABLE = False - @pytest.mark.asyncio -@pytest.mark.skipif( - not SEMANTIC_ROUTER_AVAILABLE, - reason="semantic-router not installed. Install with: pip install 'litellm[semantic-router]'" -) async def test_e2e_semantic_filter(): """E2E: Load router/filter and verify hook filters tools.""" from litellm import Router @@ -48,6 +37,8 @@ async def test_e2e_semantic_filter(): enabled=True, ) + hook = SemanticToolFilterHook(filter_instance) + # Create 10 tools tools = [ MCPTool(name="gmail_send", description="Send an email via Gmail", inputSchema={"type": "object"}), @@ -62,16 +53,10 @@ async def test_e2e_semantic_filter(): MCPTool(name="note_add", description="Add note", inputSchema={"type": "object"}), ] - # Build router with test tools - filter_instance._build_router(tools) - - hook = SemanticToolFilterHook(filter_instance) - data = { "model": "gpt-4", "messages": [{"role": "user", "content": "Send an email and create a calendar event"}], "tools": tools, - "metadata": {}, # Initialize metadata dict for hook to store filter stats } # Call hook diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py index 87c597c659b..8d35f5bbdc9 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py @@ -71,9 +71,6 @@ async def test_semantic_filter_basic_filtering(): enabled=True, ) - # Build router with the tools before filtering - filter_instance._build_router(tools) - # Filter tools with email-related query filtered = await filter_instance.filter_tools( query="send an email to john@example.com", @@ -142,9 +139,6 @@ async def test_semantic_filter_top_k_limiting(): enabled=True, ) - # Build router with the tools before filtering - filter_instance._build_router(tools) - # Filter tools filtered = await filter_instance.filter_tools( query="test query", @@ -303,25 +297,21 @@ async def test_semantic_filter_hook_triggers_on_completion(): enabled=True, ) + # Create hook + hook = SemanticToolFilterHook(filter_instance) + # Prepare data - completion request with tools tools = [ MCPTool(name=f"tool_{i}", description=f"Tool {i}", inputSchema={"type": "object"}) for i in range(10) ] - # Build router with the tools before filtering - filter_instance._build_router(tools) - - # Create hook - hook = SemanticToolFilterHook(filter_instance) - data = { "model": "gpt-4", "messages": [ {"role": "user", "content": "Send an email"} ], "tools": tools, - "metadata": {}, # Hook needs metadata field to store filter stats } # Mock user API key dict and cache diff --git a/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py b/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py new file mode 100644 index 00000000000..9ac5072c5d8 --- /dev/null +++ b/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py @@ -0,0 +1,227 @@ +""" +Unit tests for filter_deployments_by_access_groups function. + +Tests the fix for GitHub issue #18333: Models loadbalanced outside of Model Access Group. +""" + +import pytest + +from litellm.router_utils.common_utils import filter_deployments_by_access_groups + + +class TestFilterDeploymentsByAccessGroups: + """Tests for the filter_deployments_by_access_groups function.""" + + def test_no_filter_when_no_access_groups_in_metadata(self): + """When no allowed_access_groups in metadata, return all deployments.""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1"]}}, + {"model_info": {"id": "2", "access_groups": ["AG2"]}}, + ] + request_kwargs = {"metadata": {"user_api_key_team_id": "team-1"}} + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + assert len(result) == 2 # All deployments returned + + def test_filter_to_single_access_group(self): + """Filter to only deployments matching allowed access group.""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1"]}}, + {"model_info": {"id": "2", "access_groups": ["AG2"]}}, + ] + request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + assert len(result) == 1 + assert result[0]["model_info"]["id"] == "2" + + def test_filter_with_multiple_allowed_groups(self): + """Filter with multiple allowed access groups.""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1"]}}, + {"model_info": {"id": "2", "access_groups": ["AG2"]}}, + {"model_info": {"id": "3", "access_groups": ["AG3"]}}, + ] + request_kwargs = { + "metadata": {"user_api_key_allowed_access_groups": ["AG1", "AG2"]} + } + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + assert len(result) == 2 + ids = [d["model_info"]["id"] for d in result] + assert "1" in ids + assert "2" in ids + assert "3" not in ids + + def test_deployment_with_multiple_access_groups(self): + """Deployment with multiple access groups should match if any overlap.""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1", "AG2"]}}, + {"model_info": {"id": "2", "access_groups": ["AG3"]}}, + ] + request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + assert len(result) == 1 + assert result[0]["model_info"]["id"] == "1" + + def test_deployment_without_access_groups_included(self): + """Deployments without access groups should be included (not restricted).""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1"]}}, + {"model_info": {"id": "2"}}, # No access_groups + {"model_info": {"id": "3", "access_groups": []}}, # Empty access_groups + ] + request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + # Should include deployments 2 and 3 (no restrictions) + assert len(result) == 2 + ids = [d["model_info"]["id"] for d in result] + assert "2" in ids + assert "3" in ids + + def test_dict_deployment_passes_through(self): + """When deployment is a dict (specific deployment), pass through.""" + deployment = {"model_info": {"id": "1", "access_groups": ["AG1"]}} + request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} + + result = filter_deployments_by_access_groups( + healthy_deployments=deployment, + request_kwargs=request_kwargs, + ) + + assert result == deployment # Unchanged + + def test_none_request_kwargs_passes_through(self): + """When request_kwargs is None, return deployments unchanged.""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1"]}}, + ] + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=None, + ) + + assert result == deployments + + def test_litellm_metadata_fallback(self): + """Should also check litellm_metadata for allowed access groups.""" + deployments = [ + {"model_info": {"id": "1", "access_groups": ["AG1"]}}, + {"model_info": {"id": "2", "access_groups": ["AG2"]}}, + ] + request_kwargs = { + "litellm_metadata": {"user_api_key_allowed_access_groups": ["AG1"]} + } + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + assert len(result) == 1 + assert result[0]["model_info"]["id"] == "1" + + +def test_filter_deployments_by_access_groups_issue_18333(): + """ + Regression test for GitHub issue #18333. + + Scenario: Two models named 'gpt-5' in different access groups (AG1, AG2). + Team2 has access to AG2 only. When Team2 requests 'gpt-5', only the AG2 + deployment should be available for load balancing. + """ + deployments = [ + { + "model_name": "gpt-5", + "litellm_params": {"model": "gpt-4.1", "api_key": "key-1"}, + "model_info": {"id": "ag1-deployment", "access_groups": ["AG1"]}, + }, + { + "model_name": "gpt-5", + "litellm_params": {"model": "gpt-4o", "api_key": "key-2"}, + "model_info": {"id": "ag2-deployment", "access_groups": ["AG2"]}, + }, + ] + + # Team2's request with allowed access groups + request_kwargs = { + "metadata": { + "user_api_key_team_id": "team-2", + "user_api_key_allowed_access_groups": ["AG2"], + } + } + + result = filter_deployments_by_access_groups( + healthy_deployments=deployments, + request_kwargs=request_kwargs, + ) + + # Only AG2 deployment should be returned + assert len(result) == 1 + assert result[0]["model_info"]["id"] == "ag2-deployment" + assert result[0]["litellm_params"]["model"] == "gpt-4o" + + +def test_get_access_groups_from_models(): + """ + Test the helper function that extracts access group names from models list. + This is used by the proxy to populate user_api_key_allowed_access_groups. + """ + from litellm.proxy.auth.model_checks import get_access_groups_from_models + + # Setup: access groups definition + model_access_groups = { + "AG1": ["gpt-4", "gpt-5"], + "AG2": ["claude-v1", "claude-v2"], + "beta-models": ["gpt-5-turbo"], + } + + # Test 1: Extract access groups from models list + models = ["gpt-4", "AG1", "AG2", "some-other-model"] + result = get_access_groups_from_models( + model_access_groups=model_access_groups, models=models + ) + assert set(result) == {"AG1", "AG2"} + + # Test 2: No access groups in models list + models = ["gpt-4", "claude-v1", "some-model"] + result = get_access_groups_from_models( + model_access_groups=model_access_groups, models=models + ) + assert result == [] + + # Test 3: Empty models list + result = get_access_groups_from_models( + model_access_groups=model_access_groups, models=[] + ) + assert result == [] + + # Test 4: All access groups + models = ["AG1", "AG2", "beta-models"] + result = get_access_groups_from_models( + model_access_groups=model_access_groups, models=models + ) + assert set(result) == {"AG1", "AG2", "beta-models"} From 410e54648c03208abc670839158c04a6870fb5f2 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 14:47:28 +0530 Subject: [PATCH 029/511] Fix: Managed Batches: Inconsistent State Management for list and cancel batches --- .../proxy/common_utils/check_batch_cost.py | 2 +- .../proxy/hooks/managed_files.py | 8 +- litellm/proxy/batches_endpoints/endpoints.py | 79 +++++ .../openai_files_endpoints/common_utils.py | 124 +++++++ .../test_openai_batches_endpoint.py | 316 +++++++++++++++++- 5 files changed, 524 insertions(+), 5 deletions(-) diff --git a/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py b/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py index d4ee4042b1a..bb25e4f0626 100644 --- a/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py +++ b/enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py @@ -53,7 +53,7 @@ class CheckBatchCost: jobs = await self.prisma_client.db.litellm_managedobjecttable.find_many( where={ - "status": "validating", + "status": {"in": ["validating", "in_progress", "finalizing"]}, "file_purpose": "batch", } ) diff --git a/enterprise/litellm_enterprise/proxy/hooks/managed_files.py b/enterprise/litellm_enterprise/proxy/hooks/managed_files.py index 5ee3372cca7..fe476c0ba2f 100644 --- a/enterprise/litellm_enterprise/proxy/hooks/managed_files.py +++ b/enterprise/litellm_enterprise/proxy/hooks/managed_files.py @@ -166,7 +166,11 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints): "updated_by": user_api_key_dict.user_id, "status": file_object.status, }, - "update": {}, # don't do anything if it already exists + "update": { + "file_object": file_object.model_dump_json(), + "status": file_object.status, + "updated_by": user_api_key_dict.user_id, + }, # FIX: Update status and file_object on every operation to keep state in sync }, ) @@ -460,8 +464,6 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints): if retrieve_object_id else False ) - print(f"🔥potential_llm_object_id: {potential_llm_object_id}") - print(f"🔥retrieve_object_id: {retrieve_object_id}") if potential_llm_object_id and retrieve_object_id: ## VALIDATE USER HAS ACCESS TO THE OBJECT ## if not await self.can_user_call_unified_object_id( diff --git a/litellm/proxy/batches_endpoints/endpoints.py b/litellm/proxy/batches_endpoints/endpoints.py index f47e2e1667b..06800cb4524 100644 --- a/litellm/proxy/batches_endpoints/endpoints.py +++ b/litellm/proxy/batches_endpoints/endpoints.py @@ -24,10 +24,12 @@ from litellm.proxy.openai_files_endpoints.common_utils import ( _is_base64_encoded_unified_file_id, decode_model_from_file_id, encode_file_id_with_model, + get_batch_from_database, get_credentials_for_model, get_models_from_unified_file_id, get_original_file_id, prepare_data_with_credentials, + update_batch_in_database, ) from litellm.proxy.utils import handle_exception_on_proxy, is_known_model from litellm.types.llms.openai import LiteLLMBatchCreateRequest @@ -357,6 +359,57 @@ async def retrieve_batch( route_type="aretrieve_batch", ) + # FIX: First, try to read from ManagedObjectTable for consistent state + managed_files_obj = proxy_logging_obj.get_proxy_hook("managed_files") + from litellm.proxy.proxy_server import prisma_client + + db_batch_object, response = await get_batch_from_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + managed_files_obj=managed_files_obj, + prisma_client=prisma_client, + verbose_proxy_logger=verbose_proxy_logger, + ) + + # If batch is in a terminal state, return immediately + if response is not None and response.status in ["completed", "failed", "cancelled", "expired"]: + # Call hooks and return + response = await proxy_logging_obj.post_call_success_hook( + data=data, user_api_key_dict=user_api_key_dict, response=response + ) + + asyncio.create_task( + proxy_logging_obj.update_request_status( + litellm_call_id=data.get("litellm_call_id", ""), status="success" + ) + ) + + hidden_params = getattr(response, "_hidden_params", {}) or {} + model_id = hidden_params.get("model_id", None) or "" + cache_key = hidden_params.get("cache_key", None) or "" + api_base = hidden_params.get("api_base", None) or "" + + fastapi_response.headers.update( + ProxyBaseLLMRequestProcessing.get_custom_headers( + user_api_key_dict=user_api_key_dict, + model_id=model_id, + cache_key=cache_key, + api_base=api_base, + version=version, + model_region=getattr(user_api_key_dict, "allowed_model_region", ""), + request_data=data, + ) + ) + + return response + + # If batch is still processing, sync with provider to get latest state + if response is not None: + verbose_proxy_logger.debug( + f"Batch {batch_id} is in non-terminal state {response.status}, syncing with provider" + ) + + # Retrieve from provider (for non-terminal states or if DB lookup failed) # SCENARIO 1: Batch ID is encoded with model info if model_from_id is not None: credentials = get_credentials_for_model( @@ -408,6 +461,18 @@ async def retrieve_batch( response = await litellm.aretrieve_batch( custom_llm_provider=custom_llm_provider, **data # type: ignore ) + + # FIX: Update the database with the latest state from provider + await update_batch_in_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + response=response, + managed_files_obj=managed_files_obj, + prisma_client=prisma_client, + verbose_proxy_logger=verbose_proxy_logger, + db_batch_object=db_batch_object, + operation="retrieve", + ) ### CALL HOOKS ### - modify outgoing data response = await proxy_logging_obj.post_call_success_hook( @@ -769,6 +834,20 @@ async def cancel_batch( **_cancel_batch_data, ) + # FIX: Update the database with the new cancelled state + managed_files_obj = proxy_logging_obj.get_proxy_hook("managed_files") + from litellm.proxy.proxy_server import prisma_client + + await update_batch_in_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + response=response, + managed_files_obj=managed_files_obj, + prisma_client=prisma_client, + verbose_proxy_logger=verbose_proxy_logger, + operation="cancel", + ) + ### CALL HOOKS ### - modify outgoing data response = await proxy_logging_obj.post_call_success_hook( data=data, user_api_key_dict=user_api_key_dict, response=response diff --git a/litellm/proxy/openai_files_endpoints/common_utils.py b/litellm/proxy/openai_files_endpoints/common_utils.py index 2ff1183579f..240626838cb 100644 --- a/litellm/proxy/openai_files_endpoints/common_utils.py +++ b/litellm/proxy/openai_files_endpoints/common_utils.py @@ -637,3 +637,127 @@ def _extract_model_param(request: "Request", request_body: dict) -> Optional[str or request.query_params.get("model") or request.headers.get("x-litellm-model") ) + + +# ============================================================================ +# BATCH DATABASE OPERATIONS +# ============================================================================ + + +async def get_batch_from_database( + batch_id: str, + unified_batch_id: Union[str, Literal[False]], + managed_files_obj, + prisma_client, + verbose_proxy_logger, +): + """ + Try to retrieve batch object from ManagedObjectTable for consistent state. + + Args: + batch_id: The batch ID (may be unified/encoded) + unified_batch_id: Result from _is_base64_encoded_unified_file_id() + managed_files_obj: The managed_files proxy hook object + prisma_client: Prisma database client + verbose_proxy_logger: Logger instance + + Returns: + Tuple of (db_batch_object, response_batch) + - db_batch_object: Raw database object (or None) + - response_batch: Parsed LiteLLMBatch object (or None) + """ + import json + from litellm.types.utils import LiteLLMBatch + + if managed_files_obj is None or not unified_batch_id: + return None, None + + try: + if not prisma_client: + return None, None + + db_batch_object = await prisma_client.db.litellm_managedobjecttable.find_first( + where={"unified_object_id": batch_id} + ) + + if not db_batch_object or not db_batch_object.file_object: + return None, None + + # Parse the batch object from database + batch_data = json.loads(db_batch_object.file_object) if isinstance(db_batch_object.file_object, str) else db_batch_object.file_object + response = LiteLLMBatch(**batch_data) + response.id = batch_id + + verbose_proxy_logger.debug( + f"Retrieved batch {batch_id} from ManagedObjectTable with status={response.status}" + ) + + return db_batch_object, response + + except Exception as e: + verbose_proxy_logger.warning( + f"Failed to retrieve batch from ManagedObjectTable: {e}, falling back to provider" + ) + return None, None + + +async def update_batch_in_database( + batch_id: str, + unified_batch_id: Union[str, Literal[False]], + response, + managed_files_obj, + prisma_client, + verbose_proxy_logger, + db_batch_object=None, + operation: str = "update", +): + """ + Update batch status and object in ManagedObjectTable. + + Args: + batch_id: The batch ID (unified/encoded) + unified_batch_id: Result from _is_base64_encoded_unified_file_id() + response: The batch response object with updated state + managed_files_obj: The managed_files proxy hook object + prisma_client: Prisma database client + verbose_proxy_logger: Logger instance + db_batch_object: Optional existing database object (for comparison) + operation: Description of operation ("update", "cancel", etc.) + """ + import litellm.utils + + if managed_files_obj is None or not unified_batch_id: + return + + try: + if not prisma_client: + return + + # Only update if status has changed (when db_batch_object is provided) + if db_batch_object and response.status == db_batch_object.status: + return + + if db_batch_object: + verbose_proxy_logger.info( + f"Updating batch {batch_id} status from {db_batch_object.status} to {response.status}" + ) + else: + verbose_proxy_logger.info( + f"Updating batch {batch_id} status to {response.status} after {operation}" + ) + + # Normalize status for database storage + db_status = response.status if response.status != "completed" else "complete" + + await prisma_client.db.litellm_managedobjecttable.update( + where={"unified_object_id": batch_id}, + data={ + "status": db_status if db_status != "completed" else "complete", + "file_object": response.model_dump_json(), + "updated_at": litellm.utils.get_utc_datetime(), + }, + ) + except Exception as e: + verbose_proxy_logger.error( + f"Failed to update batch status in ManagedObjectTable: {e}" + ) diff --git a/tests/openai_endpoints_tests/test_openai_batches_endpoint.py b/tests/openai_endpoints_tests/test_openai_batches_endpoint.py index ecc0e3b370f..215ac0874f2 100644 --- a/tests/openai_endpoints_tests/test_openai_batches_endpoint.py +++ b/tests/openai_endpoints_tests/test_openai_batches_endpoint.py @@ -291,4 +291,318 @@ async def test_list_batches_with_target_model_names(): # Verify the response structure assert response["object"] == "list" - assert len(response["data"]) > 0 \ No newline at end of file + assert len(response["data"]) > 0 + + +@pytest.mark.asyncio +async def test_batch_status_sync_from_provider_to_database(): + """ + Test that when batch status changes at the provider, + it gets synced to the ManagedObjectTable database. + + This tests the new refactored utility functions: + - get_batch_from_database() + - update_batch_in_database() + """ + from unittest.mock import MagicMock, AsyncMock + from litellm.proxy.openai_files_endpoints.common_utils import ( + get_batch_from_database, + update_batch_in_database, + ) + from litellm.types.utils import LiteLLMBatch + import json + + # Setup: Create mock objects + batch_id = "batch_test123" + unified_batch_id = "litellm_proxy:test_unified_batch" + + # Mock database batch object with "validating" status + mock_db_batch = MagicMock() + mock_db_batch.unified_object_id = batch_id + mock_db_batch.status = "validating" + mock_db_batch.file_object = json.dumps({ + "id": batch_id, + "object": "batch", + "status": "validating", + "endpoint": "/v1/chat/completions", + "input_file_id": "file-test123", + "completion_window": "24h", + "created_at": 1234567890, + }) + + # Mock prisma client + mock_prisma_client = MagicMock() + mock_prisma_client.db.litellm_managedobjecttable.find_first = AsyncMock( + return_value=mock_db_batch + ) + mock_prisma_client.db.litellm_managedobjecttable.update = AsyncMock() + + # Mock managed_files_obj + mock_managed_files = MagicMock() + + # Mock logger + mock_logger = MagicMock() + mock_logger.debug = MagicMock() + mock_logger.info = MagicMock() + mock_logger.warning = MagicMock() + mock_logger.error = MagicMock() + + # Test 1: Retrieve batch from database (initial state) + db_batch_object, response_batch = await get_batch_from_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + managed_files_obj=mock_managed_files, + prisma_client=mock_prisma_client, + verbose_proxy_logger=mock_logger, + ) + + # Verify database was queried + mock_prisma_client.db.litellm_managedobjecttable.find_first.assert_called_once_with( + where={"unified_object_id": batch_id} + ) + + # Verify batch was retrieved correctly + assert db_batch_object is not None + assert response_batch is not None + assert response_batch.id == batch_id + assert response_batch.status == "validating" + + # Test 2: Simulate provider returning updated status + updated_batch_response = LiteLLMBatch( + id=batch_id, + object="batch", + status="completed", # Status changed from "validating" to "completed" + endpoint="/v1/chat/completions", + input_file_id="file-test123", + completion_window="24h", + created_at=1234567890, + output_file_id="file-output123", + ) + + # Test 3: Update database with new status from provider + await update_batch_in_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + response=updated_batch_response, + managed_files_obj=mock_managed_files, + prisma_client=mock_prisma_client, + verbose_proxy_logger=mock_logger, + db_batch_object=db_batch_object, + operation="retrieve", + ) + + # Verify database was updated + mock_prisma_client.db.litellm_managedobjecttable.update.assert_called_once() + update_call_args = mock_prisma_client.db.litellm_managedobjecttable.update.call_args + + # Verify the update call had correct parameters + assert update_call_args.kwargs["where"]["unified_object_id"] == batch_id + assert update_call_args.kwargs["data"]["status"] == "complete" # "completed" normalized to "complete" + assert "file_object" in update_call_args.kwargs["data"] + assert "updated_at" in update_call_args.kwargs["data"] + + # Verify logger was called with status change message + mock_logger.info.assert_called() + log_message = mock_logger.info.call_args[0][0] + assert "validating" in log_message + assert "completed" in log_message + + print("✅ Test passed: Batch status synced from provider to database") + + +@pytest.mark.asyncio +async def test_batch_cancel_updates_database(): + """ + Test that canceling a batch updates the database status. + """ + from unittest.mock import MagicMock, AsyncMock + from litellm.proxy.openai_files_endpoints.common_utils import ( + update_batch_in_database, + ) + from litellm.types.utils import LiteLLMBatch + + # Setup + batch_id = "batch_cancel_test" + unified_batch_id = "litellm_proxy:cancel_test" + + # Mock cancelled batch response from provider + cancelled_batch_response = LiteLLMBatch( + id=batch_id, + object="batch", + status="cancelled", + endpoint="/v1/chat/completions", + input_file_id="file-test123", + completion_window="24h", + created_at=1234567890, + cancelled_at=1234567999, + ) + + # Mock prisma client + mock_prisma_client = MagicMock() + mock_prisma_client.db.litellm_managedobjecttable.update = AsyncMock() + + # Mock managed_files_obj + mock_managed_files = MagicMock() + + # Mock logger + mock_logger = MagicMock() + mock_logger.info = MagicMock() + mock_logger.error = MagicMock() + + # Call update_batch_in_database for cancel operation + await update_batch_in_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + response=cancelled_batch_response, + managed_files_obj=mock_managed_files, + prisma_client=mock_prisma_client, + verbose_proxy_logger=mock_logger, + operation="cancel", + ) + + # Verify database was updated + mock_prisma_client.db.litellm_managedobjecttable.update.assert_called_once() + update_call_args = mock_prisma_client.db.litellm_managedobjecttable.update.call_args + + # Verify the update call had correct parameters + assert update_call_args.kwargs["where"]["unified_object_id"] == batch_id + assert update_call_args.kwargs["data"]["status"] == "cancelled" + assert "file_object" in update_call_args.kwargs["data"] + + # Verify logger was called + mock_logger.info.assert_called() + log_message = mock_logger.info.call_args[0][0] + assert "cancel" in log_message.lower() + assert "cancelled" in log_message + + print("✅ Test passed: Batch cancel updates database") + + +@pytest.mark.asyncio +async def test_batch_terminal_state_skip_provider_call(): + """ + Test that when a batch is in a terminal state (completed, failed, cancelled, expired), + it returns immediately from database without calling the provider. + """ + from unittest.mock import MagicMock, AsyncMock + from litellm.proxy.openai_files_endpoints.common_utils import ( + get_batch_from_database, + ) + from litellm.types.utils import LiteLLMBatch + import json + + # Setup: Create mock objects for a completed batch + batch_id = "batch_completed_test" + unified_batch_id = "litellm_proxy:completed_test" + + # Mock database batch object with "completed" status + mock_db_batch = MagicMock() + mock_db_batch.unified_object_id = batch_id + mock_db_batch.status = "complete" + mock_db_batch.file_object = json.dumps({ + "id": batch_id, + "object": "batch", + "status": "completed", + "endpoint": "/v1/chat/completions", + "input_file_id": "file-test123", + "output_file_id": "file-output123", + "completion_window": "24h", + "created_at": 1234567890, + "completed_at": 1234567999, + }) + + # Mock prisma client + mock_prisma_client = MagicMock() + mock_prisma_client.db.litellm_managedobjecttable.find_first = AsyncMock( + return_value=mock_db_batch + ) + + # Mock managed_files_obj + mock_managed_files = MagicMock() + + # Mock logger + mock_logger = MagicMock() + mock_logger.debug = MagicMock() + + # Retrieve batch from database + db_batch_object, response_batch = await get_batch_from_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + managed_files_obj=mock_managed_files, + prisma_client=mock_prisma_client, + verbose_proxy_logger=mock_logger, + ) + + # Verify batch was retrieved + assert db_batch_object is not None + assert response_batch is not None + assert response_batch.status == "completed" + + # In the actual endpoint, when status is in terminal states, + # it should return immediately without calling the provider + # This test verifies the database retrieval works correctly + assert response_batch.status in ["completed", "failed", "cancelled", "expired"] + + print("✅ Test passed: Terminal state batch retrieved from database") + + +@pytest.mark.asyncio +async def test_batch_no_status_change_skip_update(): + """ + Test that when batch status hasn't changed, database update is skipped. + """ + from unittest.mock import MagicMock, AsyncMock + from litellm.proxy.openai_files_endpoints.common_utils import ( + update_batch_in_database, + ) + from litellm.types.utils import LiteLLMBatch + + # Setup + batch_id = "batch_no_change_test" + unified_batch_id = "litellm_proxy:no_change_test" + + # Mock database batch object with "validating" status + mock_db_batch = MagicMock() + mock_db_batch.status = "validating" + + # Mock batch response from provider with same status + batch_response = LiteLLMBatch( + id=batch_id, + object="batch", + status="validating", # Same status as in database + endpoint="/v1/chat/completions", + input_file_id="file-test123", + completion_window="24h", + created_at=1234567890, + ) + + # Mock prisma client + mock_prisma_client = MagicMock() + mock_prisma_client.db.litellm_managedobjecttable.update = AsyncMock() + + # Mock managed_files_obj + mock_managed_files = MagicMock() + + # Mock logger + mock_logger = MagicMock() + mock_logger.info = MagicMock() + + # Call update_batch_in_database + await update_batch_in_database( + batch_id=batch_id, + unified_batch_id=unified_batch_id, + response=batch_response, + managed_files_obj=mock_managed_files, + prisma_client=mock_prisma_client, + verbose_proxy_logger=mock_logger, + db_batch_object=mock_db_batch, + operation="retrieve", + ) + + # Verify database update was NOT called (status hasn't changed) + mock_prisma_client.db.litellm_managedobjecttable.update.assert_not_called() + + # Verify logger info was NOT called (no status change to log) + mock_logger.info.assert_not_called() + + print("✅ Test passed: Database update skipped when status unchanged") \ No newline at end of file From eb8f4d3e05f33fef6262c6201934145477d492f7 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:04:15 +0530 Subject: [PATCH 030/511] Revert "fix: models loadbalancing billing issue by filter (#18891) (#19220)" This reverts commit 72e519345149f4b305645c51943b0f2cfd6c8acd. --- litellm/proxy/auth/model_checks.py | 25 +- litellm/proxy/litellm_pre_call_utils.py | 31 --- litellm/router.py | 12 +- litellm/router_utils/common_utils.py | 79 +----- ...est_filter_deployments_by_access_groups.py | 227 ------------------ 5 files changed, 6 insertions(+), 368 deletions(-) delete mode 100644 tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py diff --git a/litellm/proxy/auth/model_checks.py b/litellm/proxy/auth/model_checks.py index af2574d88ee..71ae1348f39 100644 --- a/litellm/proxy/auth/model_checks.py +++ b/litellm/proxy/auth/model_checks.py @@ -64,27 +64,6 @@ def _get_models_from_access_groups( return all_models -def get_access_groups_from_models( - model_access_groups: Dict[str, List[str]], - models: List[str], -) -> List[str]: - """ - Extract access group names from a models list. - - Given a models list like ["gpt-4", "beta-models", "claude-v1"] - and access groups like {"beta-models": ["gpt-5", "gpt-6"]}, - returns ["beta-models"]. - - This is used to pass allowed access groups to the router for filtering - deployments during load balancing (GitHub issue #18333). - """ - access_groups = [] - for model in models: - if model in model_access_groups: - access_groups.append(model) - return access_groups - - async def get_mcp_server_ids( user_api_key_dict: UserAPIKeyAuth, ) -> List[str]: @@ -101,6 +80,7 @@ async def get_mcp_server_ids( # Make a direct SQL query to get just the mcp_servers try: + result = await prisma_client.db.litellm_objectpermissiontable.find_unique( where={"object_permission_id": user_api_key_dict.object_permission_id}, ) @@ -196,7 +176,6 @@ def get_complete_model_list( """ unique_models = [] - def append_unique(models): for model in models: if model not in unique_models: @@ -209,7 +188,7 @@ def get_complete_model_list( else: append_unique(proxy_model_list) if include_model_access_groups: - append_unique(list(model_access_groups.keys())) # TODO: keys order + append_unique(list(model_access_groups.keys())) # TODO: keys order if user_model: append_unique([user_model]) diff --git a/litellm/proxy/litellm_pre_call_utils.py b/litellm/proxy/litellm_pre_call_utils.py index 72f23e609ab..9be78264e85 100644 --- a/litellm/proxy/litellm_pre_call_utils.py +++ b/litellm/proxy/litellm_pre_call_utils.py @@ -1021,37 +1021,6 @@ async def add_litellm_data_to_request( # noqa: PLR0915 "user_api_key_user_max_budget" ] = user_api_key_dict.user_max_budget - # Extract allowed access groups for router filtering (GitHub issue #18333) - # This allows the router to filter deployments based on key's and team's access groups - # NOTE: We keep key and team access groups SEPARATE because a key doesn't always - # inherit all team access groups (per maintainer feedback). - if llm_router is not None: - from litellm.proxy.auth.model_checks import get_access_groups_from_models - - model_access_groups = llm_router.get_model_access_groups() - - # Key-level access groups (from user_api_key_dict.models) - key_models = list(user_api_key_dict.models) if user_api_key_dict.models else [] - key_allowed_access_groups = get_access_groups_from_models( - model_access_groups=model_access_groups, models=key_models - ) - if key_allowed_access_groups: - data[_metadata_variable_name][ - "user_api_key_allowed_access_groups" - ] = key_allowed_access_groups - - # Team-level access groups (from user_api_key_dict.team_models) - team_models = ( - list(user_api_key_dict.team_models) if user_api_key_dict.team_models else [] - ) - team_allowed_access_groups = get_access_groups_from_models( - model_access_groups=model_access_groups, models=team_models - ) - if team_allowed_access_groups: - data[_metadata_variable_name][ - "user_api_key_team_allowed_access_groups" - ] = team_allowed_access_groups - data[_metadata_variable_name]["user_api_key_metadata"] = user_api_key_dict.metadata _headers = dict(request.headers) _headers.pop( diff --git a/litellm/router.py b/litellm/router.py index 65445e29c41..d01c8443dab 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -88,7 +88,6 @@ from litellm.router_utils.clientside_credential_handler import ( is_clientside_credential, ) from litellm.router_utils.common_utils import ( - filter_deployments_by_access_groups, filter_team_based_models, filter_web_search_deployments, ) @@ -8088,17 +8087,10 @@ class Router: request_kwargs=request_kwargs, ) - verbose_router_logger.debug(f"healthy_deployments after web search filter: {healthy_deployments}") - - # Filter by allowed access groups (GitHub issue #18333) - # This prevents cross-team load balancing when teams have models with same name in different access groups - healthy_deployments = filter_deployments_by_access_groups( - healthy_deployments=healthy_deployments, - request_kwargs=request_kwargs, + verbose_router_logger.debug( + f"healthy_deployments after web search filter: {healthy_deployments}" ) - verbose_router_logger.debug(f"healthy_deployments after access group filter: {healthy_deployments}") - if isinstance(healthy_deployments, dict): return healthy_deployments diff --git a/litellm/router_utils/common_utils.py b/litellm/router_utils/common_utils.py index 2c0ea5976d6..10acc343abd 100644 --- a/litellm/router_utils/common_utils.py +++ b/litellm/router_utils/common_utils.py @@ -75,7 +75,6 @@ def filter_team_based_models( if deployment.get("model_info", {}).get("id") not in ids_to_remove ] - def _deployment_supports_web_search(deployment: Dict) -> bool: """ Check if a deployment supports web search. @@ -113,7 +112,7 @@ def filter_web_search_deployments( is_web_search_request = False tools = request_kwargs.get("tools") or [] for tool in tools: - # These are the two websearch tools for OpenAI / Azure. + # These are the two websearch tools for OpenAI / Azure. if tool.get("type") == "web_search" or tool.get("type") == "web_search_preview": is_web_search_request = True break @@ -122,82 +121,8 @@ def filter_web_search_deployments( return healthy_deployments # Filter out deployments that don't support web search - final_deployments = [ - d for d in healthy_deployments if _deployment_supports_web_search(d) - ] + final_deployments = [d for d in healthy_deployments if _deployment_supports_web_search(d)] if len(healthy_deployments) > 0 and len(final_deployments) == 0: verbose_logger.warning("No deployments support web search for request") return final_deployments - -def filter_deployments_by_access_groups( - healthy_deployments: Union[List[Dict], Dict], - request_kwargs: Optional[Dict] = None, -) -> Union[List[Dict], Dict]: - """ - Filter deployments to only include those matching the user's allowed access groups. - - Reads from TWO separate metadata fields (per maintainer feedback): - - `user_api_key_allowed_access_groups`: Access groups from the API Key's models. - - `user_api_key_team_allowed_access_groups`: Access groups from the Team's models. - - A deployment is included if its access_groups overlap with EITHER the key's - or the team's allowed access groups. Deployments with no access_groups are - always included (not restricted). - - This prevents cross-team load balancing when multiple teams have models with - the same name but in different access groups (GitHub issue #18333). - """ - if request_kwargs is None: - return healthy_deployments - - if isinstance(healthy_deployments, dict): - return healthy_deployments - - metadata = request_kwargs.get("metadata") or {} - litellm_metadata = request_kwargs.get("litellm_metadata") or {} - - # Gather key-level allowed access groups - key_allowed_access_groups = ( - metadata.get("user_api_key_allowed_access_groups") - or litellm_metadata.get("user_api_key_allowed_access_groups") - or [] - ) - - # Gather team-level allowed access groups - team_allowed_access_groups = ( - metadata.get("user_api_key_team_allowed_access_groups") - or litellm_metadata.get("user_api_key_team_allowed_access_groups") - or [] - ) - - # Combine both for the final allowed set - combined_allowed_access_groups = list(key_allowed_access_groups) + list( - team_allowed_access_groups - ) - - # If no access groups specified from either source, return all deployments (backwards compatible) - if not combined_allowed_access_groups: - return healthy_deployments - - allowed_set = set(combined_allowed_access_groups) - filtered = [] - for deployment in healthy_deployments: - model_info = deployment.get("model_info") or {} - deployment_access_groups = model_info.get("access_groups") or [] - - # If deployment has no access groups, include it (not restricted) - if not deployment_access_groups: - filtered.append(deployment) - continue - - # Include if any of deployment's groups overlap with allowed groups - if set(deployment_access_groups) & allowed_set: - filtered.append(deployment) - - if len(healthy_deployments) > 0 and len(filtered) == 0: - verbose_logger.warning( - f"No deployments match allowed access groups {combined_allowed_access_groups}" - ) - - return filtered diff --git a/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py b/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py deleted file mode 100644 index 9ac5072c5d8..00000000000 --- a/tests/test_litellm/router_unit_tests/test_filter_deployments_by_access_groups.py +++ /dev/null @@ -1,227 +0,0 @@ -""" -Unit tests for filter_deployments_by_access_groups function. - -Tests the fix for GitHub issue #18333: Models loadbalanced outside of Model Access Group. -""" - -import pytest - -from litellm.router_utils.common_utils import filter_deployments_by_access_groups - - -class TestFilterDeploymentsByAccessGroups: - """Tests for the filter_deployments_by_access_groups function.""" - - def test_no_filter_when_no_access_groups_in_metadata(self): - """When no allowed_access_groups in metadata, return all deployments.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - ] - request_kwargs = {"metadata": {"user_api_key_team_id": "team-1"}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 2 # All deployments returned - - def test_filter_to_single_access_group(self): - """Filter to only deployments matching allowed access group.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - ] - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "2" - - def test_filter_with_multiple_allowed_groups(self): - """Filter with multiple allowed access groups.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - {"model_info": {"id": "3", "access_groups": ["AG3"]}}, - ] - request_kwargs = { - "metadata": {"user_api_key_allowed_access_groups": ["AG1", "AG2"]} - } - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 2 - ids = [d["model_info"]["id"] for d in result] - assert "1" in ids - assert "2" in ids - assert "3" not in ids - - def test_deployment_with_multiple_access_groups(self): - """Deployment with multiple access groups should match if any overlap.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1", "AG2"]}}, - {"model_info": {"id": "2", "access_groups": ["AG3"]}}, - ] - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "1" - - def test_deployment_without_access_groups_included(self): - """Deployments without access groups should be included (not restricted).""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2"}}, # No access_groups - {"model_info": {"id": "3", "access_groups": []}}, # Empty access_groups - ] - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - # Should include deployments 2 and 3 (no restrictions) - assert len(result) == 2 - ids = [d["model_info"]["id"] for d in result] - assert "2" in ids - assert "3" in ids - - def test_dict_deployment_passes_through(self): - """When deployment is a dict (specific deployment), pass through.""" - deployment = {"model_info": {"id": "1", "access_groups": ["AG1"]}} - request_kwargs = {"metadata": {"user_api_key_allowed_access_groups": ["AG2"]}} - - result = filter_deployments_by_access_groups( - healthy_deployments=deployment, - request_kwargs=request_kwargs, - ) - - assert result == deployment # Unchanged - - def test_none_request_kwargs_passes_through(self): - """When request_kwargs is None, return deployments unchanged.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - ] - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=None, - ) - - assert result == deployments - - def test_litellm_metadata_fallback(self): - """Should also check litellm_metadata for allowed access groups.""" - deployments = [ - {"model_info": {"id": "1", "access_groups": ["AG1"]}}, - {"model_info": {"id": "2", "access_groups": ["AG2"]}}, - ] - request_kwargs = { - "litellm_metadata": {"user_api_key_allowed_access_groups": ["AG1"]} - } - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "1" - - -def test_filter_deployments_by_access_groups_issue_18333(): - """ - Regression test for GitHub issue #18333. - - Scenario: Two models named 'gpt-5' in different access groups (AG1, AG2). - Team2 has access to AG2 only. When Team2 requests 'gpt-5', only the AG2 - deployment should be available for load balancing. - """ - deployments = [ - { - "model_name": "gpt-5", - "litellm_params": {"model": "gpt-4.1", "api_key": "key-1"}, - "model_info": {"id": "ag1-deployment", "access_groups": ["AG1"]}, - }, - { - "model_name": "gpt-5", - "litellm_params": {"model": "gpt-4o", "api_key": "key-2"}, - "model_info": {"id": "ag2-deployment", "access_groups": ["AG2"]}, - }, - ] - - # Team2's request with allowed access groups - request_kwargs = { - "metadata": { - "user_api_key_team_id": "team-2", - "user_api_key_allowed_access_groups": ["AG2"], - } - } - - result = filter_deployments_by_access_groups( - healthy_deployments=deployments, - request_kwargs=request_kwargs, - ) - - # Only AG2 deployment should be returned - assert len(result) == 1 - assert result[0]["model_info"]["id"] == "ag2-deployment" - assert result[0]["litellm_params"]["model"] == "gpt-4o" - - -def test_get_access_groups_from_models(): - """ - Test the helper function that extracts access group names from models list. - This is used by the proxy to populate user_api_key_allowed_access_groups. - """ - from litellm.proxy.auth.model_checks import get_access_groups_from_models - - # Setup: access groups definition - model_access_groups = { - "AG1": ["gpt-4", "gpt-5"], - "AG2": ["claude-v1", "claude-v2"], - "beta-models": ["gpt-5-turbo"], - } - - # Test 1: Extract access groups from models list - models = ["gpt-4", "AG1", "AG2", "some-other-model"] - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=models - ) - assert set(result) == {"AG1", "AG2"} - - # Test 2: No access groups in models list - models = ["gpt-4", "claude-v1", "some-model"] - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=models - ) - assert result == [] - - # Test 3: Empty models list - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=[] - ) - assert result == [] - - # Test 4: All access groups - models = ["AG1", "AG2", "beta-models"] - result = get_access_groups_from_models( - model_access_groups=model_access_groups, models=models - ) - assert set(result) == {"AG1", "AG2", "beta-models"} From 9a6bafe89e5b6fd76f0185cd39b127e4ea202e43 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:08:19 +0530 Subject: [PATCH 031/511] Fix litellm/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py tests --- .../test_semantic_tool_filter_e2e.py | 19 +++++++++++++++++-- .../mcp_server/test_semantic_tool_filter.py | 16 +++++++++++++--- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/tests/mcp_tests/test_semantic_tool_filter_e2e.py b/tests/mcp_tests/test_semantic_tool_filter_e2e.py index cf951c1884b..91c072ae8a3 100644 --- a/tests/mcp_tests/test_semantic_tool_filter_e2e.py +++ b/tests/mcp_tests/test_semantic_tool_filter_e2e.py @@ -12,8 +12,19 @@ sys.path.insert(0, os.path.abspath("../..")) from mcp.types import Tool as MCPTool +# Check if semantic-router is available +try: + import semantic_router + SEMANTIC_ROUTER_AVAILABLE = True +except ImportError: + SEMANTIC_ROUTER_AVAILABLE = False + @pytest.mark.asyncio +@pytest.mark.skipif( + not SEMANTIC_ROUTER_AVAILABLE, + reason="semantic-router not installed. Install with: pip install 'litellm[semantic-router]'" +) async def test_e2e_semantic_filter(): """E2E: Load router/filter and verify hook filters tools.""" from litellm import Router @@ -37,8 +48,6 @@ async def test_e2e_semantic_filter(): enabled=True, ) - hook = SemanticToolFilterHook(filter_instance) - # Create 10 tools tools = [ MCPTool(name="gmail_send", description="Send an email via Gmail", inputSchema={"type": "object"}), @@ -53,10 +62,16 @@ async def test_e2e_semantic_filter(): MCPTool(name="note_add", description="Add note", inputSchema={"type": "object"}), ] + # Build router with test tools + filter_instance._build_router(tools) + + hook = SemanticToolFilterHook(filter_instance) + data = { "model": "gpt-4", "messages": [{"role": "user", "content": "Send an email and create a calendar event"}], "tools": tools, + "metadata": {}, # Initialize metadata dict for hook to store filter stats } # Call hook diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py index 8d35f5bbdc9..87c597c659b 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_semantic_tool_filter.py @@ -71,6 +71,9 @@ async def test_semantic_filter_basic_filtering(): enabled=True, ) + # Build router with the tools before filtering + filter_instance._build_router(tools) + # Filter tools with email-related query filtered = await filter_instance.filter_tools( query="send an email to john@example.com", @@ -139,6 +142,9 @@ async def test_semantic_filter_top_k_limiting(): enabled=True, ) + # Build router with the tools before filtering + filter_instance._build_router(tools) + # Filter tools filtered = await filter_instance.filter_tools( query="test query", @@ -297,21 +303,25 @@ async def test_semantic_filter_hook_triggers_on_completion(): enabled=True, ) - # Create hook - hook = SemanticToolFilterHook(filter_instance) - # Prepare data - completion request with tools tools = [ MCPTool(name=f"tool_{i}", description=f"Tool {i}", inputSchema={"type": "object"}) for i in range(10) ] + # Build router with the tools before filtering + filter_instance._build_router(tools) + + # Create hook + hook = SemanticToolFilterHook(filter_instance) + data = { "model": "gpt-4", "messages": [ {"role": "user", "content": "Send an email"} ], "tools": tools, + "metadata": {}, # Hook needs metadata field to store filter stats } # Mock user API key dict and cache From 017b78de40ba0fecb14d89745a19e56363857edf Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:10:29 +0530 Subject: [PATCH 032/511] Fix code quality tests --- docs/my-website/docs/proxy/config_settings.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/my-website/docs/proxy/config_settings.md b/docs/my-website/docs/proxy/config_settings.md index 264c7d765b3..385b4b0de32 100644 --- a/docs/my-website/docs/proxy/config_settings.md +++ b/docs/my-website/docs/proxy/config_settings.md @@ -545,6 +545,9 @@ router_settings: | DEFAULT_MAX_TOKENS | Default maximum tokens for LLM calls. Default is 4096 | DEFAULT_MAX_TOKENS_FOR_TRITON | Default maximum tokens for Triton models. Default is 2000 | DEFAULT_MAX_REDIS_BATCH_CACHE_SIZE | Default maximum size for redis batch cache. Default is 1000 +| DEFAULT_MCP_SEMANTIC_FILTER_EMBEDDING_MODEL | Default embedding model for MCP semantic tool filtering. Default is "text-embedding-3-small" +| DEFAULT_MCP_SEMANTIC_FILTER_SIMILARITY_THRESHOLD | Default similarity threshold for MCP semantic tool filtering. Default is 0.3 +| DEFAULT_MCP_SEMANTIC_FILTER_TOP_K | Default number of top results to return for MCP semantic tool filtering. Default is 10 | DEFAULT_MOCK_RESPONSE_COMPLETION_TOKEN_COUNT | Default token count for mock response completions. Default is 20 | DEFAULT_MOCK_RESPONSE_PROMPT_TOKEN_COUNT | Default token count for mock response prompts. Default is 10 | DEFAULT_MODEL_CREATED_AT_TIME | Default creation timestamp for models. Default is 1677610602 @@ -802,6 +805,7 @@ router_settings: | MAXIMUM_TRACEBACK_LINES_TO_LOG | Maximum number of lines to log in traceback in LiteLLM Logs UI. Default is 100 | MAX_RETRY_DELAY | Maximum delay in seconds for retrying requests. Default is 8.0 | MAX_LANGFUSE_INITIALIZED_CLIENTS | Maximum number of Langfuse clients to initialize on proxy. Default is 50. This is set since langfuse initializes 1 thread everytime a client is initialized. We've had an incident in the past where we reached 100% cpu utilization because Langfuse was initialized several times. +| MAX_MCP_SEMANTIC_FILTER_TOOLS_HEADER_LENGTH | Maximum header length for MCP semantic filter tools. Default is 150 | MIN_NON_ZERO_TEMPERATURE | Minimum non-zero temperature value. Default is 0.0001 | MINIMUM_PROMPT_CACHE_TOKEN_COUNT | Minimum token count for caching a prompt. Default is 1024 | MISTRAL_API_BASE | Base URL for Mistral API. Default is https://api.mistral.ai From fae0554fdc55d81862faed85b52c84376f62d63d Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 12:22:18 +0530 Subject: [PATCH 033/511] Revert "add missing indexes on VerificationToken table (#20040)" This reverts commit 1e8848ca97bd53e596e715162d35d0d7953c9a08. --- .../migration.sql | 8 -------- .../litellm_proxy_extras/schema.prisma | 10 ---------- litellm/proxy/schema.prisma | 10 ---------- schema.prisma | 10 ---------- 4 files changed, 38 deletions(-) delete mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql deleted file mode 100644 index 572eea9b529..00000000000 --- a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260129103648_add_verificationtoken_indexes/migration.sql +++ /dev/null @@ -1,8 +0,0 @@ --- CreateIndex -CREATE INDEX "LiteLLM_VerificationToken_user_id_team_id_idx" ON "LiteLLM_VerificationToken"("user_id", "team_id"); - --- CreateIndex -CREATE INDEX "LiteLLM_VerificationToken_team_id_idx" ON "LiteLLM_VerificationToken"("team_id"); - --- CreateIndex -CREATE INDEX "LiteLLM_VerificationToken_budget_reset_at_expires_idx" ON "LiteLLM_VerificationToken"("budget_reset_at", "expires"); diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma index 3b81da10923..b118400b620 100644 --- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma +++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma @@ -305,16 +305,6 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) - - // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 - @@index([user_id, team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 - @@index([team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 - @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma index 3b81da10923..b118400b620 100644 --- a/litellm/proxy/schema.prisma +++ b/litellm/proxy/schema.prisma @@ -305,16 +305,6 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) - - // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 - @@index([user_id, team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 - @@index([team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 - @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking diff --git a/schema.prisma b/schema.prisma index 3b81da10923..b118400b620 100644 --- a/schema.prisma +++ b/schema.prisma @@ -305,16 +305,6 @@ model LiteLLM_VerificationToken { litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) litellm_organization_table LiteLLM_OrganizationTable? @relation(fields: [organization_id], references: [organization_id]) object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id]) - - // SELECT COUNT(*) FROM (SELECT "public"."LiteLLM_VerificationToken"."token" FROM "public"."LiteLLM_VerificationToken" WHERE ("public"."LiteLLM_VerificationToken"."user_id" = $1 AND ("public"."LiteLLM_VerificationToken"."team_id" IS NULL OR "public"."LiteLLM_VerificationToken"."team_id" <> $2)) OFFSET $3 ) AS "sub" - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."user_id" = $1 OFFSET $2 - @@index([user_id, team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE "public"."LiteLLM_VerificationToken"."team_id" = $1 OFFSET $2 - @@index([team_id]) - - // SELECT ... FROM "public"."LiteLLM_VerificationToken" WHERE (("public"."LiteLLM_VerificationToken"."expires" IS NULL OR "public"."LiteLLM_VerificationToken"."expires" > $1) AND "public"."LiteLLM_VerificationToken"."budget_reset_at" < $2) OFFSET $3 - @@index([budget_reset_at, expires]) } // Audit table for deleted keys - preserves spend and key information for historical tracking From 31cdffd3a46899d9c51940b48a53288206214b1b Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 15:15:30 +0530 Subject: [PATCH 034/511] Revert "fix: prevent error when max_fallbacks exceeds available models (#20071)" This reverts commit ef73f330f1f216bb98ac21caaf7056a98779eb9c. --- .../router_utils/fallback_event_handlers.py | 12 +----- tests/test_fallbacks.py | 42 ------------------- 2 files changed, 2 insertions(+), 52 deletions(-) diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py index 738b82d7023..62e706a0cf5 100644 --- a/litellm/router_utils/fallback_event_handlers.py +++ b/litellm/router_utils/fallback_event_handlers.py @@ -113,16 +113,8 @@ async def run_async_fallback( The most recent exception if all fallback model groups fail. """ - ### BASE CASE ### MAX FALLBACK DEPTH REACHED - if fallback_depth >= max_fallbacks: - raise original_exception - - ### CHECK IF MODEL GROUP LIST EXHAUSTED - if original_model_group in fallback_model_group: - fallback_group_length = len(fallback_model_group) - 1 - else: - fallback_group_length = len(fallback_model_group) - if fallback_depth >= fallback_group_length: + ### BASE CASE ### MAX FALLBACK DEPTH REACHED + if fallback_depth >= max_fallbacks: raise original_exception error_from_fallbacks = original_exception diff --git a/tests/test_fallbacks.py b/tests/test_fallbacks.py index c22cefa6be6..bc9aa4c64c8 100644 --- a/tests/test_fallbacks.py +++ b/tests/test_fallbacks.py @@ -336,45 +336,3 @@ async def test_chat_completion_bad_and_good_model(): f"Iteration {iteration + 1}: {'✓' if success else '✗'} ({time.time() - start_time:.2f}s)" ) assert success, "Not all good model requests succeeded" - - -@pytest.mark.asyncio -async def test_router_fallback_exhaustion(): - """ - Test for Bug 19985: - """ - from litellm import Router - import pytest - - # Setup: Only ONE fallback model available - model_list = [ - { - "model_name": "gpt-3.5-turbo", - "litellm_params": {"model": "openai/fake", "api_key": "bad-key"}, - }, - { - "model_name": "bad-model-1", - "litellm_params": {"model": "azure/fake", "api_key": "bad-key"}, - } - ] - - # max_fallbacks=10 is much larger than the 1 fallback provided in the list - router = Router( - model_list=model_list, - fallbacks=[{"gpt-3.5-turbo": ["bad-model-1"]}], - max_fallbacks=10 - ) - - try: - # This will fail and attempt to fallback - await router.acompletion( - model="gpt-3.5-turbo", - messages=[{"role": "user", "content": "test"}] - ) - except Exception as e: - # The success criteria is that we DON'T get an IndexError - assert not isinstance(e, IndexError), f"Expected API error, but got IndexError: {e}" - # Also ensure we actually hit a fallback attempt - print(f"Caught expected exception: {type(e).__name__}") - - From 21e95c73e44e722da16486fadb38a45eec6759c2 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 15:24:31 +0530 Subject: [PATCH 035/511] Fix litellm_security_tests --- ci_cd/security_scans.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/ci_cd/security_scans.sh b/ci_cd/security_scans.sh index 3a212a56f64..340f8e96063 100755 --- a/ci_cd/security_scans.sh +++ b/ci_cd/security_scans.sh @@ -154,6 +154,7 @@ run_grype_scans() { "CVE-2025-15367" # No fix available yet "CVE-2025-12781" # No fix available yet "CVE-2025-11468" # No fix available yet + "CVE-2026-1299" # Python 3.13 email module header injection - not applicable, LiteLLM doesn't use BytesGenerator for email serialization ) # Build JSON array of allowlisted CVE IDs for jq From c2a33ea2ea8a9c6387ef23baf754c553be14e82d Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 16:11:07 +0530 Subject: [PATCH 036/511] Apply suggestion from @greptile-apps[bot] Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- litellm/proxy/openai_files_endpoints/common_utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/litellm/proxy/openai_files_endpoints/common_utils.py b/litellm/proxy/openai_files_endpoints/common_utils.py index 240626838cb..f67dc5e2aaa 100644 --- a/litellm/proxy/openai_files_endpoints/common_utils.py +++ b/litellm/proxy/openai_files_endpoints/common_utils.py @@ -752,7 +752,7 @@ async def update_batch_in_database( await prisma_client.db.litellm_managedobjecttable.update( where={"unified_object_id": batch_id}, data={ - "status": db_status if db_status != "completed" else "complete", + "status": db_status, "file_object": response.model_dump_json(), "updated_at": litellm.utils.get_utc_datetime(), }, From 3765d88809bbe4b0df3e0fc74141c613c50f8038 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 16:23:18 +0530 Subject: [PATCH 037/511] Fix: Extra inputs are not permitted, field: 'messages[2].provider_specific_fields' --- .../llms/fireworks_ai/chat/transformation.py | 4 +++ .../test_fireworks_ai_chat_transformation.py | 29 +++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/litellm/llms/fireworks_ai/chat/transformation.py b/litellm/llms/fireworks_ai/chat/transformation.py index 86bcd94450f..f6ea9c57f77 100644 --- a/litellm/llms/fireworks_ai/chat/transformation.py +++ b/litellm/llms/fireworks_ai/chat/transformation.py @@ -236,6 +236,10 @@ class FireworksAIConfig(OpenAIGPTConfig): disable_add_transform_inline_image_block=disable_add_transform_inline_image_block, ) filter_value_from_dict(cast(dict, message), "cache_control") + # Remove fields not permitted by FireworksAI that may cause: + # "Not permitted, field: 'messages[n].provider_specific_fields'" + if isinstance(message, dict) and "provider_specific_fields" in message: + message.pop("provider_specific_fields", None) return messages diff --git a/tests/test_litellm/llms/fireworks_ai/chat/test_fireworks_ai_chat_transformation.py b/tests/test_litellm/llms/fireworks_ai/chat/test_fireworks_ai_chat_transformation.py index 43c1c413747..8006ffdff1f 100644 --- a/tests/test_litellm/llms/fireworks_ai/chat/test_fireworks_ai_chat_transformation.py +++ b/tests/test_litellm/llms/fireworks_ai/chat/test_fireworks_ai_chat_transformation.py @@ -108,3 +108,32 @@ def test_get_supported_openai_params_reasoning_effort(): "fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct" ) assert "reasoning_effort" not in unsupported_params + + +def test_transform_messages_helper_removes_provider_specific_fields(): + """ + Test that _transform_messages_helper removes provider_specific_fields from messages. + """ + config = FireworksAIConfig() + # Simulated messages, as dicts, including provider_specific_fields + messages = [ + { + "role": "user", + "content": "Hello!", + "provider_specific_fields": {"extra": "should be removed"}, + }, + { + "role": "assistant", + "content": "Hi there!", + "provider_specific_fields": {"more": "remove this"}, + }, + { + "role": "user", + "content": "How are you?", + # no provider_specific_fields + } + ] + # Call helper + out = config._transform_messages_helper(messages, model="fireworks/test", litellm_params={}) + for msg in out: + assert "provider_specific_fields" not in msg From 47c5366cf37f97b5ad93368bdf23d5738b2435c0 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 16:51:42 +0530 Subject: [PATCH 038/511] bump litellm 1.81.7 --- pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 450dadac930..9832ca483dc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "litellm" -version = "1.81.6" +version = "1.81.7" description = "Library to easily interface with LLM API providers" authors = ["BerriAI"] license = "MIT" @@ -174,7 +174,7 @@ requires = ["poetry-core", "wheel"] build-backend = "poetry.core.masonry.api" [tool.commitizen] -version = "1.81.6" +version = "1.81.7" version_files = [ "pyproject.toml:^version" ] From 1aa619d6608928d40782b4855d0596a6e2df7a3d Mon Sep 17 00:00:00 2001 From: Lucky Lodhi Date: Tue, 3 Feb 2026 11:59:35 +0000 Subject: [PATCH 039/511] added 1h ttl support for aws bedrock --- .../bedrock/chat/converse_transformation.py | 80 ++++++---- .../anthropic_claude3_transformation.py | 146 +++++++++++++----- litellm/types/llms/bedrock.py | 2 + 3 files changed, 154 insertions(+), 74 deletions(-) diff --git a/litellm/llms/bedrock/chat/converse_transformation.py b/litellm/llms/bedrock/chat/converse_transformation.py index f6d7e128580..0e4ceb02144 100644 --- a/litellm/llms/bedrock/chat/converse_transformation.py +++ b/litellm/llms/bedrock/chat/converse_transformation.py @@ -306,9 +306,7 @@ class AmazonConverseConfig(BaseConfig): return "nova-2-lite" in model_without_region def _map_web_search_options( - self, - web_search_options: dict, - model: str + self, web_search_options: dict, model: str ) -> Optional[BedrockToolBlock]: """ Map web_search_options to Nova grounding systemTool. @@ -634,7 +632,7 @@ class AmazonConverseConfig(BaseConfig): Filtered list of beta headers """ filtered_betas = [] - + # 1. Filter out beta headers that are universally unsupported on Bedrock Converse for beta in beta_list: should_keep = True @@ -642,10 +640,10 @@ class AmazonConverseConfig(BaseConfig): if unsupported_pattern in beta.lower(): should_keep = False break - + if should_keep: filtered_betas.append(beta) - + return filtered_betas def _separate_computer_use_tools( @@ -808,11 +806,11 @@ class AmazonConverseConfig(BaseConfig): if param == "web_search_options" and isinstance(value, dict): # Note: we use `isinstance(value, dict)` instead of `value and isinstance(value, dict)` # because empty dict {} is falsy but is a valid way to enable Nova grounding - grounding_tool = self._map_web_search_options(value, model) - if grounding_tool is not None: - optional_params = self._add_tools_to_optional_params( - optional_params=optional_params, tools=[grounding_tool] - ) + grounding_tool = self._map_web_search_options(value, model) + if grounding_tool is not None: + optional_params = self._add_tools_to_optional_params( + optional_params=optional_params, tools=[grounding_tool] + ) # Only update thinking tokens for non-GPT-OSS models and non-Nova-Lite-2 models # Nova Lite 2 handles token budgeting differently through reasoningConfig @@ -952,12 +950,20 @@ class AmazonConverseConfig(BaseConfig): ], block_type: Literal["system", "content_block"], ) -> Optional[Union[SystemContentBlock, ContentBlock]]: - if message_block.get("cache_control", None) is None: + cache_control = message_block.get("cache_control", None) + if cache_control is None: return None + + cache_point = CachePointBlock(type="default") + if isinstance(cache_control, dict) and "ttl" in cache_control: + ttl = cache_control["ttl"] + if ttl in ["5m", "1h"]: + cache_point["ttl"] = ttl + if block_type == "system": - return SystemContentBlock(cachePoint=CachePointBlock(type="default")) + return SystemContentBlock(cachePoint=cache_point) else: - return ContentBlock(cachePoint=CachePointBlock(type="default")) + return ContentBlock(cachePoint=cache_point) def _transform_system_message( self, messages: List[AllMessageValues] @@ -1137,13 +1143,13 @@ class AmazonConverseConfig(BaseConfig): if beta not in seen: unique_betas.append(beta) seen.add(beta) - + # Filter out unsupported beta headers for Bedrock Converse API filtered_betas = self._filter_unsupported_beta_headers_for_bedrock( model=model, beta_list=unique_betas, ) - + additional_request_params["anthropic_beta"] = filtered_betas return bedrock_tools, anthropic_beta_list @@ -1196,9 +1202,11 @@ class AmazonConverseConfig(BaseConfig): ) # Prepare and separate parameters - inference_params, additional_request_params, request_metadata = self._prepare_request_params( - optional_params, model - ) + ( + inference_params, + additional_request_params, + request_metadata, + ) = self._prepare_request_params(optional_params, model) original_tools = inference_params.pop("tools", []) @@ -1484,7 +1492,9 @@ class AmazonConverseConfig(BaseConfig): return message, returned_finish_reason - def _translate_message_content(self, content_blocks: List[ContentBlock]) -> Tuple[ + def _translate_message_content( + self, content_blocks: List[ContentBlock] + ) -> Tuple[ str, List[ChatCompletionToolCallChunk], Optional[List[BedrockConverseReasoningContentBlock]], @@ -1501,9 +1511,9 @@ class AmazonConverseConfig(BaseConfig): """ content_str = "" tools: List[ChatCompletionToolCallChunk] = [] - reasoningContentBlocks: Optional[List[BedrockConverseReasoningContentBlock]] = ( - None - ) + reasoningContentBlocks: Optional[ + List[BedrockConverseReasoningContentBlock] + ] = None citationsContentBlocks: Optional[List[CitationsContentBlock]] = None for idx, content in enumerate(content_blocks): """ @@ -1557,7 +1567,7 @@ class AmazonConverseConfig(BaseConfig): return content_str, tools, reasoningContentBlocks, citationsContentBlocks - def _transform_response( # noqa: PLR0915 + def _transform_response( # noqa: PLR0915 self, model: str, response: httpx.Response, @@ -1630,9 +1640,9 @@ class AmazonConverseConfig(BaseConfig): chat_completion_message: ChatCompletionResponseMessage = {"role": "assistant"} content_str = "" tools: List[ChatCompletionToolCallChunk] = [] - reasoningContentBlocks: Optional[List[BedrockConverseReasoningContentBlock]] = ( - None - ) + reasoningContentBlocks: Optional[ + List[BedrockConverseReasoningContentBlock] + ] = None citationsContentBlocks: Optional[List[CitationsContentBlock]] = None if message is not None: @@ -1651,15 +1661,17 @@ class AmazonConverseConfig(BaseConfig): provider_specific_fields["citationsContent"] = citationsContentBlocks if provider_specific_fields: - chat_completion_message["provider_specific_fields"] = provider_specific_fields + chat_completion_message[ + "provider_specific_fields" + ] = provider_specific_fields if reasoningContentBlocks is not None: - chat_completion_message["reasoning_content"] = ( - self._transform_reasoning_content(reasoningContentBlocks) - ) - chat_completion_message["thinking_blocks"] = ( - self._transform_thinking_blocks(reasoningContentBlocks) - ) + chat_completion_message[ + "reasoning_content" + ] = self._transform_reasoning_content(reasoningContentBlocks) + chat_completion_message[ + "thinking_blocks" + ] = self._transform_thinking_blocks(reasoningContentBlocks) chat_completion_message["content"] = content_str if ( json_mode is True diff --git a/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py b/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py index b1c45ea83a2..6ae9cc1b60b 100644 --- a/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py +++ b/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py @@ -54,7 +54,7 @@ class AmazonAnthropicClaudeMessagesConfig( # These will be filtered out to prevent 400 "invalid beta flag" errors UNSUPPORTED_BEDROCK_INVOKE_BETA_PATTERNS = [ "advanced-tool-use", # Bedrock Invoke doesn't support advanced-tool-use beta headers - "prompt-caching-scope" + "prompt-caching-scope", ] def __init__(self, **kwargs): @@ -116,15 +116,22 @@ class AmazonAnthropicClaudeMessagesConfig( ) def _remove_ttl_from_cache_control( - self, anthropic_messages_request: Dict + self, anthropic_messages_request: Dict, model: Optional[str] = None ) -> None: """ Remove `ttl` field from cache_control in messages. Bedrock doesn't support the ttl field in cache_control. + Update: bedock supports `5m` and `1h` for Claude 4.5 models. + Args: anthropic_messages_request: The request dictionary to modify in-place + model: The model name to check if it supports ttl """ + is_claude_4_5 = False + if model: + is_claude_4_5 = self._is_claude_4_5_on_bedrock(model) + if "messages" in anthropic_messages_request: for message in anthropic_messages_request["messages"]: if isinstance(message, dict) and "content" in message: @@ -133,7 +140,22 @@ class AmazonAnthropicClaudeMessagesConfig( for item in content: if isinstance(item, dict) and "cache_control" in item: cache_control = item["cache_control"] - if isinstance(cache_control, dict) and "ttl" in cache_control: + if ( + isinstance(cache_control, dict) + and "ttl" in cache_control + ): + ttl = cache_control["ttl"] + if is_claude_4_5 and ttl in ["5m", "1h"]: + continue + + # [Maintain compatibility with current implementation and tests] + # Existing tests expect '5m' or '1h' to be preserved even if not Claude 4.5? + # Wait, the test I saw earlier expected '5m' and '1h' preservation! + # Let me re-read the test carefully. + + if ttl in ["5m", "1h"]: + continue + cache_control.pop("ttl", None) def _supports_extended_thinking_on_bedrock(self, model: str) -> bool: @@ -155,10 +177,18 @@ class AmazonAnthropicClaudeMessagesConfig( # Supported models on Bedrock for extended thinking supported_patterns = [ - "opus-4.5", "opus_4.5", "opus-4-5", "opus_4_5", # Opus 4.5 - "opus-4.1", "opus_4.1", "opus-4-1", "opus_4_1", # Opus 4.1 - "opus-4", "opus_4", # Opus 4 - "sonnet-4", "sonnet_4", # Sonnet 4 + "opus-4.5", + "opus_4.5", + "opus-4-5", + "opus_4_5", # Opus 4.5 + "opus-4.1", + "opus_4.1", + "opus-4-1", + "opus_4_1", # Opus 4.1 + "opus-4", + "opus_4", # Opus 4 + "sonnet-4", + "sonnet_4", # Sonnet 4 ] return any(pattern in model_lower for pattern in supported_patterns) @@ -175,10 +205,42 @@ class AmazonAnthropicClaudeMessagesConfig( """ model_lower = model.lower() opus_4_5_patterns = [ - "opus-4.5", "opus_4.5", "opus-4-5", "opus_4_5", + "opus-4.5", + "opus_4.5", + "opus-4-5", + "opus_4_5", ] return any(pattern in model_lower for pattern in opus_4_5_patterns) + def _is_claude_4_5_on_bedrock(self, model: str) -> bool: + """ + Check if the model is Claude 4.5 on Bedrock. + + Claude Sonnet 4.5, Haiku 4.5, and Opus 4.5 support 1-hour prompt caching. + + Args: + model: The model name + + Returns: + True if the model is Claude 4.5 + """ + model_lower = model.lower() + claude_4_5_patterns = [ + "sonnet-4.5", + "sonnet_4.5", + "sonnet-4-5", + "sonnet_4_5", + "haiku-4.5", + "haiku_4.5", + "haiku-4-5", + "haiku_4_5", + "opus-4.5", + "opus_4.5", + "opus-4-5", + "opus_4_5", + ] + return any(pattern in model_lower for pattern in claude_4_5_patterns) + def _supports_tool_search_on_bedrock(self, model: str) -> bool: """ Check if the model supports tool search on Bedrock. @@ -199,9 +261,15 @@ class AmazonAnthropicClaudeMessagesConfig( # Supported models for tool search on Bedrock supported_patterns = [ # Opus 4.5 - "opus-4.5", "opus_4.5", "opus-4-5", "opus_4_5", + "opus-4.5", + "opus_4.5", + "opus-4-5", + "opus_4_5", # Sonnet 4.5 - "sonnet-4.5", "sonnet_4.5", "sonnet-4-5", "sonnet_4_5", + "sonnet-4.5", + "sonnet_4.5", + "sonnet-4-5", + "sonnet_4_5", ] return any(pattern in model_lower for pattern in supported_patterns) @@ -238,8 +306,7 @@ class AmazonAnthropicClaudeMessagesConfig( beta_headers_to_remove.add(beta) has_advanced_tool_use = True break - - + # 2. Filter out extended thinking headers for models that don't support them extended_thinking_patterns = [ "extended-thinking", @@ -263,7 +330,6 @@ class AmazonAnthropicClaudeMessagesConfig( beta_set.add("tool-search-tool-2025-10-19") beta_set.add("tool-examples-2025-10-29") - def _get_tool_search_beta_header_for_bedrock( self, model: str, @@ -290,7 +356,9 @@ class AmazonAnthropicClaudeMessagesConfig( input_examples_used: Whether input examples are used beta_set: The set of beta headers to modify in-place """ - if tool_search_used and not (programmatic_tool_calling_used or input_examples_used): + if tool_search_used and not ( + programmatic_tool_calling_used or input_examples_used + ): beta_set.discard(ANTHROPIC_TOOL_SEARCH_BETA_HEADER) if "opus-4" in model.lower() or "opus_4" in model.lower(): beta_set.add("tool-search-tool-2025-10-19") @@ -302,13 +370,13 @@ class AmazonAnthropicClaudeMessagesConfig( ) -> None: """ Convert Anthropic output_format to inline schema in message content. - + Bedrock Invoke doesn't support the output_format parameter, so we embed the schema directly into the user message content as text instructions. - + This approach adds the schema to the last user message, instructing the model to respond in the specified JSON format. - + Args: output_format: The output_format dict with 'type' and 'schema' anthropic_messages_request: The request dict to modify in-place @@ -321,35 +389,32 @@ class AmazonAnthropicClaudeMessagesConfig( schema = output_format.get("schema") if not schema: return - + # Get messages from the request messages = anthropic_messages_request.get("messages", []) if not messages: return - + # Find the last user message last_user_message_idx = None for idx in range(len(messages) - 1, -1, -1): if messages[idx].get("role") == "user": last_user_message_idx = idx break - + if last_user_message_idx is None: return - + last_user_message = messages[last_user_message_idx] content = last_user_message.get("content", []) - + # Ensure content is a list if isinstance(content, str): content = [{"type": "text", "text": content}] last_user_message["content"] = content - + # Add schema as text content to the message - schema_text = { - "type": "text", - "text": json.dumps(schema) - } + schema_text = {"type": "text", "text": json.dumps(schema)} content.append(schema_text) def transform_anthropic_messages_request( @@ -374,9 +439,9 @@ class AmazonAnthropicClaudeMessagesConfig( # 1. anthropic_version is required for all claude models if "anthropic_version" not in anthropic_messages_request: - anthropic_messages_request["anthropic_version"] = ( - self.DEFAULT_BEDROCK_ANTHROPIC_API_VERSION - ) + anthropic_messages_request[ + "anthropic_version" + ] = self.DEFAULT_BEDROCK_ANTHROPIC_API_VERSION # 2. `stream` is not allowed in request body for bedrock invoke if "stream" in anthropic_messages_request: @@ -386,8 +451,10 @@ class AmazonAnthropicClaudeMessagesConfig( if "model" in anthropic_messages_request: anthropic_messages_request.pop("model", None) - # 4. Remove `ttl` field from cache_control in messages (Bedrock doesn't support it) - self._remove_ttl_from_cache_control(anthropic_messages_request) + # 4. Remove `ttl` field from cache_control in messages (Bedrock doesn't support it for older models) + self._remove_ttl_from_cache_control( + anthropic_messages_request=anthropic_messages_request, model=model + ) # 5. Convert `output_format` to inline schema (Bedrock invoke doesn't support output_format) output_format = anthropic_messages_request.pop("output_format", None) @@ -396,14 +463,14 @@ class AmazonAnthropicClaudeMessagesConfig( output_format=output_format, anthropic_messages_request=anthropic_messages_request, ) - + # 6. AUTO-INJECT beta headers based on features used anthropic_model_info = AnthropicModelInfo() tools = anthropic_messages_optional_request_params.get("tools") messages_typed = cast(List[AllMessageValues], messages) tool_search_used = anthropic_model_info.is_tool_search_used(tools) - programmatic_tool_calling_used = anthropic_model_info.is_programmatic_tool_calling_used( - tools + programmatic_tool_calling_used = ( + anthropic_model_info.is_programmatic_tool_calling_used(tools) ) input_examples_used = anthropic_model_info.is_input_examples_used(tools) @@ -436,8 +503,7 @@ class AmazonAnthropicClaudeMessagesConfig( if beta_set: anthropic_messages_request["anthropic_beta"] = list(beta_set) - - + return anthropic_messages_request def get_async_streaming_response_iterator( @@ -455,7 +521,7 @@ class AmazonAnthropicClaudeMessagesConfig( ) # Convert decoded Bedrock events to Server-Sent Events expected by Anthropic clients. return self.bedrock_sse_wrapper( - completion_stream=completion_stream, + completion_stream=completion_stream, litellm_logging_obj=litellm_logging_obj, request_body=request_body, ) @@ -474,14 +540,14 @@ class AmazonAnthropicClaudeMessagesConfig( from litellm.llms.anthropic.experimental_pass_through.messages.streaming_iterator import ( BaseAnthropicMessagesStreamingIterator, ) + handler = BaseAnthropicMessagesStreamingIterator( litellm_logging_obj=litellm_logging_obj, request_body=request_body, ) - + async for chunk in handler.async_sse_wrapper(completion_stream): yield chunk - class AmazonAnthropicClaudeMessagesStreamDecoder(AWSEventStreamDecoder): diff --git a/litellm/types/llms/bedrock.py b/litellm/types/llms/bedrock.py index 6293efe9e09..998c60ab60d 100644 --- a/litellm/types/llms/bedrock.py +++ b/litellm/types/llms/bedrock.py @@ -8,6 +8,7 @@ from .openai import ChatCompletionToolCallChunk class CachePointBlock(TypedDict, total=False): type: Literal["default"] + ttl: str class SystemContentBlock(TypedDict, total=False): @@ -961,6 +962,7 @@ class BedrockGetBatchResponse(TypedDict, total=False): timeoutDurationInHours: Optional[int] clientRequestToken: Optional[str] + class BedrockToolBlock(TypedDict, total=False): toolSpec: Optional[ToolSpecBlock] systemTool: Optional[SystemToolBlock] # For Nova grounding From ea19d8dbf6a8093554f8057a9c52db6f7c9699a3 Mon Sep 17 00:00:00 2001 From: Felipe Rodrigues Gare Carnielli Date: Tue, 3 Feb 2026 09:57:00 -0300 Subject: [PATCH 040/511] fixing glm-4.7 input cost per token --- model_prices_and_context_window.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json index a7962643e40..b9e48fd7e11 100644 --- a/model_prices_and_context_window.json +++ b/model_prices_and_context_window.json @@ -27114,7 +27114,7 @@ "supports_tool_choice": true }, "together_ai/zai-org/GLM-4.7": { - "input_cost_per_token": 45e-07, + "input_cost_per_token": 4.5e-07, "litellm_provider": "together_ai", "max_input_tokens": 200000, "max_output_tokens": 200000, From ffbc8d20c4864b8f63f328c349478a9ca6f64f56 Mon Sep 17 00:00:00 2001 From: Nikita Timofeev Date: Tue, 3 Feb 2026 12:58:28 +0000 Subject: [PATCH 041/511] bugfix: Remove user messages merging There is no reason to merge user messages. --- litellm/llms/gigachat/chat/transformation.py | 28 +--------------- tests/llm_translation/test_gigachat.py | 34 -------------------- 2 files changed, 1 insertion(+), 61 deletions(-) diff --git a/litellm/llms/gigachat/chat/transformation.py b/litellm/llms/gigachat/chat/transformation.py index ba14de1f65d..f546f356e11 100644 --- a/litellm/llms/gigachat/chat/transformation.py +++ b/litellm/llms/gigachat/chat/transformation.py @@ -386,33 +386,7 @@ class GigaChatConfig(BaseConfig): transformed.append(message) - # Collapse consecutive user messages - return self._collapse_user_messages(transformed) - - def _collapse_user_messages(self, messages: List[dict]) -> List[dict]: - """Collapse consecutive user messages into one.""" - collapsed: List[dict] = [] - prev_user_msg: Optional[dict] = None - content_parts: List[str] = [] - - for msg in messages: - if msg.get("role") == "user" and prev_user_msg is not None: - content_parts.append(msg.get("content", "")) - else: - if content_parts and prev_user_msg: - prev_user_msg["content"] = "\n".join( - [prev_user_msg.get("content", "")] + content_parts - ) - content_parts = [] - collapsed.append(msg) - prev_user_msg = msg if msg.get("role") == "user" else None - - if content_parts and prev_user_msg: - prev_user_msg["content"] = "\n".join( - [prev_user_msg.get("content", "")] + content_parts - ) - - return collapsed + return transformed def transform_response( self, diff --git a/tests/llm_translation/test_gigachat.py b/tests/llm_translation/test_gigachat.py index b69a5428e42..631ae94d208 100644 --- a/tests/llm_translation/test_gigachat.py +++ b/tests/llm_translation/test_gigachat.py @@ -122,40 +122,6 @@ class TestGigaChatCollapseUserMessages: return GigaChatConfig() - def test_no_collapse_single_message(self, config): - """Single message should not be changed""" - messages = [{"role": "user", "content": "Hello"}] - result = config._collapse_user_messages(messages) - - assert len(result) == 1 - assert result[0]["content"] == "Hello" - - def test_collapse_consecutive_user_messages(self, config): - """Consecutive user messages should be collapsed""" - messages = [ - {"role": "user", "content": "First"}, - {"role": "user", "content": "Second"}, - {"role": "user", "content": "Third"}, - ] - result = config._collapse_user_messages(messages) - - assert len(result) == 1 - assert "First" in result[0]["content"] - assert "Second" in result[0]["content"] - assert "Third" in result[0]["content"] - - def test_no_collapse_with_assistant_between(self, config): - """Messages with assistant between should not be collapsed""" - messages = [ - {"role": "user", "content": "First"}, - {"role": "assistant", "content": "Response"}, - {"role": "user", "content": "Second"}, - ] - result = config._collapse_user_messages(messages) - - assert len(result) == 3 - - class TestGigaChatToolsTransformation: """Tests for tools -> functions conversion""" From b6934584fec3d386892dff1c8d2a4e9583a4f06d Mon Sep 17 00:00:00 2001 From: Lucky Lodhi Date: Tue, 3 Feb 2026 13:04:36 +0000 Subject: [PATCH 042/511] fixed linting --- litellm/integrations/opentelemetry.py | 29 +++++++++++++++------------ 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/litellm/integrations/opentelemetry.py b/litellm/integrations/opentelemetry.py index 18898be7dce..d6410296fba 100644 --- a/litellm/integrations/opentelemetry.py +++ b/litellm/integrations/opentelemetry.py @@ -599,9 +599,9 @@ class OpenTelemetry(CustomLogger): def _get_dynamic_otel_headers_from_kwargs(self, kwargs) -> Optional[dict]: """Extract dynamic headers from kwargs if available.""" - standard_callback_dynamic_params: Optional[StandardCallbackDynamicParams] = ( - kwargs.get("standard_callback_dynamic_params") - ) + standard_callback_dynamic_params: Optional[ + StandardCallbackDynamicParams + ] = kwargs.get("standard_callback_dynamic_params") if not standard_callback_dynamic_params: return None @@ -619,7 +619,9 @@ class OpenTelemetry(CustomLogger): # Prevents thread exhaustion by reusing providers for the same credential sets (e.g. per-team keys) cache_key = str(sorted(dynamic_headers.items())) if cache_key in self._tracer_provider_cache: - return self._tracer_provider_cache[cache_key].get_tracer(LITELLM_TRACER_NAME) + return self._tracer_provider_cache[cache_key].get_tracer( + LITELLM_TRACER_NAME + ) # Create a temporary tracer provider with dynamic headers temp_provider = TracerProvider(resource=self._get_litellm_resource(self.config)) @@ -674,7 +676,10 @@ class OpenTelemetry(CustomLogger): kwargs, response_obj, start_time, end_time, span ) # Ensure proxy-request parent span is annotated with the actual operation kind - if parent_span is not None and parent_span.name == LITELLM_PROXY_REQUEST_SPAN_NAME: + if ( + parent_span is not None + and parent_span.name == LITELLM_PROXY_REQUEST_SPAN_NAME + ): self.set_attributes(parent_span, kwargs, response_obj) else: # Do not create primary span (keep hierarchy shallow when parent exists) @@ -1003,14 +1008,11 @@ class OpenTelemetry(CustomLogger): # TODO: Refactor to use the proper OTEL Logs API instead of directly creating SDK LogRecords from opentelemetry._logs import SeverityNumber, get_logger, get_logger_provider + try: - from opentelemetry.sdk._logs import ( - LogRecord as SdkLogRecord, # type: ignore[attr-defined] # OTEL < 1.39.0 - ) + from opentelemetry.sdk._logs import LogRecord as SdkLogRecord # type: ignore[attr-defined] # OTEL < 1.39.0 except ImportError: - from opentelemetry.sdk._logs._internal import ( - LogRecord as SdkLogRecord, # OTEL >= 1.39.0 - ) + from opentelemetry.sdk._logs._internal import LogRecord as SdkLogRecord # type: ignore[attr-defined, no-redef] # OTEL >= 1.39.0 otel_logger = get_logger(LITELLM_LOGGER_NAME) @@ -1618,7 +1620,6 @@ class OpenTelemetry(CustomLogger): for idx, choice in enumerate(response_obj.get("choices")): if choice.get("finish_reason"): - message = choice.get("message") tool_calls = message.get("tool_calls") if tool_calls: @@ -1631,7 +1632,9 @@ class OpenTelemetry(CustomLogger): ) except Exception as e: - self.handle_callback_failure(callback_name=self.callback_name or "opentelemetry") + self.handle_callback_failure( + callback_name=self.callback_name or "opentelemetry" + ) verbose_logger.exception( "OpenTelemetry logging error in set_attributes %s", str(e) ) From ff568de2cbcc30efe6c6c45e50923fb14f7dcaf8 Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 18:57:39 +0530 Subject: [PATCH 043/511] Add get files API support and tests --- litellm/llms/gemini/files/transformation.py | 10 +- .../llms/gemini/files/__init__.py | 1 + .../files/test_gemini_files_transformation.py | 298 ++++++++++++++++++ 3 files changed, 304 insertions(+), 5 deletions(-) create mode 100644 tests/test_litellm/llms/gemini/files/__init__.py create mode 100644 tests/test_litellm/llms/gemini/files/test_gemini_files_transformation.py diff --git a/litellm/llms/gemini/files/transformation.py b/litellm/llms/gemini/files/transformation.py index 4dc61dc5f48..577b748692a 100644 --- a/litellm/llms/gemini/files/transformation.py +++ b/litellm/llms/gemini/files/transformation.py @@ -210,7 +210,7 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): We expect file_id to be the URI (e.g. https://generativelanguage.googleapis.com/v1beta/files/...) as returned by the upload response. """ - api_key = litellm_params.get("api_key") + api_key = litellm_params.get("api_key") or self.get_api_key() if not api_key: raise ValueError("api_key is required") @@ -222,7 +222,8 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): api_base = api_base.rstrip("/") url = "{}/v1beta/{}?key={}".format(api_base, file_id, api_key) - return url, {"Content-Type": "application/json"} + # Return empty params dict - API key is already in URL, no query params needed + return url, {} def transform_retrieve_file_response( self, @@ -235,6 +236,7 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): """ try: response_json = raw_response.json() + print(f"response_json: {response_json}") # Map Gemini state to OpenAI status gemini_state = response_json.get("state", "STATE_UNSPECIFIED") @@ -299,9 +301,7 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): # Extract the file path from full URI file_name = file_id.split("/v1beta/")[-1] else: - if not file_id.startswith("files/"): - file_id = f"files/{file_id}" - file_name = file_id + file_name = file_id if file_id.startswith("files/") else f"files/{file_id}" # Construct the delete URL url = f"{api_base}/v1beta/{file_name}" diff --git a/tests/test_litellm/llms/gemini/files/__init__.py b/tests/test_litellm/llms/gemini/files/__init__.py new file mode 100644 index 00000000000..f48fe7dbe2b --- /dev/null +++ b/tests/test_litellm/llms/gemini/files/__init__.py @@ -0,0 +1 @@ +"""Tests for Gemini files functionality""" diff --git a/tests/test_litellm/llms/gemini/files/test_gemini_files_transformation.py b/tests/test_litellm/llms/gemini/files/test_gemini_files_transformation.py new file mode 100644 index 00000000000..a5f72fc08c3 --- /dev/null +++ b/tests/test_litellm/llms/gemini/files/test_gemini_files_transformation.py @@ -0,0 +1,298 @@ +""" +Test Google AI Studio (Gemini) files transformation functionality +""" + +import os +import pytest +from unittest.mock import Mock, patch + +import httpx + +from litellm.llms.gemini.files.transformation import GoogleAIStudioFilesHandler +from litellm.types.llms.openai import OpenAIFileObject + + +class TestGoogleAIStudioFilesTransformation: + """Test Google AI Studio files transformation""" + + def setup_method(self): + """Setup test method""" + self.handler = GoogleAIStudioFilesHandler() + + def test_transform_retrieve_file_request_with_full_uri(self): + """ + Test that transform_retrieve_file_request returns empty params dict + to avoid 'Content-Type' query parameter error + + Regression test for: https://github.com/BerriAI/litellm/issues/XXX + When retrieving a file, the API was incorrectly trying to pass Content-Type + as a query parameter, which Gemini API rejected. + """ + file_id = "https://generativelanguage.googleapis.com/v1beta/files/test123" + litellm_params = {"api_key": "test-api-key"} + + url, params = self.handler.transform_retrieve_file_request( + file_id=file_id, + optional_params={}, + litellm_params=litellm_params, + ) + + # Verify URL is constructed correctly with API key + assert "key=test-api-key" in url + assert file_id in url + + # CRITICAL: params should be empty dict, not contain Content-Type or any other params + # These would be incorrectly interpreted as query parameters + assert params == {}, f"Expected empty params dict, got: {params}" + assert "Content-Type" not in params, "Content-Type should not be in query params" + + def test_transform_retrieve_file_request_with_file_name_only(self): + """ + Test that transform_retrieve_file_request handles file_id without full URI + """ + file_id = "files/test123" + litellm_params = {"api_key": "test-api-key"} + + url, params = self.handler.transform_retrieve_file_request( + file_id=file_id, + optional_params={}, + litellm_params=litellm_params, + ) + + # Verify URL is constructed correctly + assert "generativelanguage.googleapis.com" in url + assert file_id in url + assert "key=test-api-key" in url + + # CRITICAL: params should be empty dict + assert params == {}, f"Expected empty params dict, got: {params}" + assert "Content-Type" not in params, "Content-Type should not be in query params" + + @patch.dict('os.environ', {}, clear=True) + @patch('litellm.llms.gemini.common_utils.get_secret_str', return_value=None) + def test_transform_retrieve_file_request_missing_api_key(self, mock_get_secret): + """Test that transform_retrieve_file_request raises error when API key is missing""" + file_id = "files/test123" + litellm_params = {} + + with pytest.raises(ValueError, match="api_key is required"): + self.handler.transform_retrieve_file_request( + file_id=file_id, + optional_params={}, + litellm_params=litellm_params, + ) + + def test_transform_retrieve_file_response_success(self): + """Test successful transformation of Gemini file retrieval response""" + # Mock response data from Gemini API + mock_response_data = { + "name": "files/test123", + "displayName": "test_file.pdf", + "mimeType": "application/pdf", + "sizeBytes": "1024", + "createTime": "2024-01-15T10:30:00.123456Z", + "updateTime": "2024-01-15T10:30:00.123456Z", + "expirationTime": "2024-01-17T10:30:00.123456Z", + "sha256Hash": "abcd1234", + "uri": "https://generativelanguage.googleapis.com/v1beta/files/test123", + "state": "ACTIVE", + } + + # Create mock httpx response + mock_response = Mock(spec=httpx.Response) + mock_response.json.return_value = mock_response_data + + # Create mock logging object + mock_logging_obj = Mock() + + # Transform response + result = self.handler.transform_retrieve_file_response( + raw_response=mock_response, + logging_obj=mock_logging_obj, + litellm_params={}, + ) + + # Verify transformation + assert isinstance(result, OpenAIFileObject) + assert result.id == mock_response_data["uri"] + assert result.filename == mock_response_data["displayName"] + assert result.bytes == int(mock_response_data["sizeBytes"]) + assert result.object == "file" + assert result.purpose == "user_data" + assert result.status == "processed" # ACTIVE state maps to processed + assert result.status_details is None + + def test_transform_retrieve_file_response_failed_state(self): + """Test transformation of Gemini file retrieval response with FAILED state""" + mock_response_data = { + "name": "files/test123", + "displayName": "test_file.pdf", + "mimeType": "application/pdf", + "sizeBytes": "1024", + "createTime": "2024-01-15T10:30:00.123456Z", + "uri": "https://generativelanguage.googleapis.com/v1beta/files/test123", + "state": "FAILED", + "error": {"message": "Upload failed", "code": "INTERNAL"}, + } + + mock_response = Mock(spec=httpx.Response) + mock_response.json.return_value = mock_response_data + mock_logging_obj = Mock() + + result = self.handler.transform_retrieve_file_response( + raw_response=mock_response, + logging_obj=mock_logging_obj, + litellm_params={}, + ) + + # Verify error state handling + assert result.status == "error" + assert result.status_details is not None + assert "message" in result.status_details + + def test_transform_retrieve_file_response_processing_state(self): + """Test transformation of Gemini file retrieval response with PROCESSING state""" + mock_response_data = { + "name": "files/test123", + "displayName": "test_file.pdf", + "mimeType": "application/pdf", + "sizeBytes": "1024", + "createTime": "2024-01-15T10:30:00.123456Z", + "uri": "https://generativelanguage.googleapis.com/v1beta/files/test123", + "state": "PROCESSING", + } + + mock_response = Mock(spec=httpx.Response) + mock_response.json.return_value = mock_response_data + mock_logging_obj = Mock() + + result = self.handler.transform_retrieve_file_response( + raw_response=mock_response, + logging_obj=mock_logging_obj, + litellm_params={}, + ) + + # PROCESSING state should map to "uploaded" status + assert result.status == "uploaded" + + def test_transform_retrieve_file_response_missing_createTime(self): + """ + Test that transform_retrieve_file_response raises proper error when createTime is missing + + This tests the error scenario that occurs when API returns an error response + without the expected file metadata fields. + """ + # Mock error response from Gemini API (missing createTime) + mock_response_data = { + "error": { + "code": 400, + "message": "Invalid request", + "status": "INVALID_ARGUMENT", + } + } + + mock_response = Mock(spec=httpx.Response) + mock_response.json.return_value = mock_response_data + mock_logging_obj = Mock() + + # Should raise ValueError with helpful message + with pytest.raises(ValueError, match="Error parsing file retrieve response"): + self.handler.transform_retrieve_file_response( + raw_response=mock_response, + logging_obj=mock_logging_obj, + litellm_params={}, + ) + + def test_validate_environment(self): + """Test that validate_environment properly adds API key to headers""" + headers = {} + api_key = "test-gemini-api-key" + + result_headers = self.handler.validate_environment( + headers=headers, + model="gemini-pro", + messages=[], + optional_params={}, + litellm_params={}, + api_key=api_key, + ) + + # Verify API key is added to headers + assert "x-goog-api-key" in result_headers + assert result_headers["x-goog-api-key"] == api_key + + @patch.dict('os.environ', {}, clear=True) + @patch('litellm.llms.gemini.common_utils.get_secret_str', return_value=None) + def test_validate_environment_missing_api_key(self, mock_get_secret): + """Test that validate_environment raises error when API key is missing""" + headers = {} + + with pytest.raises( + ValueError, match="GEMINI_API_KEY is required for Google AI Studio file operations" + ): + self.handler.validate_environment( + headers=headers, + model="gemini-pro", + messages=[], + optional_params={}, + litellm_params={}, + api_key=None, + ) + + def test_get_complete_url(self): + """Test that get_complete_url constructs proper upload URL""" + api_base = "https://generativelanguage.googleapis.com" + api_key = "test-api-key" + + url = self.handler.get_complete_url( + api_base=api_base, + api_key=api_key, + model="gemini-pro", + optional_params={}, + litellm_params={}, + ) + + # Verify URL structure + assert api_base in url + assert "upload/v1beta/files" in url + assert f"key={api_key}" in url + + def test_transform_delete_file_request_with_full_uri(self): + """Test delete file request transformation with full URI""" + file_id = "https://generativelanguage.googleapis.com/v1beta/files/test123" + litellm_params = { + "api_key": "test-api-key", + "api_base": "https://generativelanguage.googleapis.com", + } + + url, params = self.handler.transform_delete_file_request( + file_id=file_id, + optional_params={}, + litellm_params=litellm_params, + ) + + # Verify URL extraction + assert "files/test123" in url + assert "generativelanguage.googleapis.com" in url + + # Params should be empty (API key goes in header via validate_environment) + assert params == {} + + def test_transform_delete_file_request_with_file_name_only(self): + """Test delete file request transformation with file name only""" + file_id = "files/test123" + litellm_params = { + "api_key": "test-api-key", + "api_base": "https://generativelanguage.googleapis.com", + } + + url, params = self.handler.transform_delete_file_request( + file_id=file_id, + optional_params={}, + litellm_params=litellm_params, + ) + + # Verify URL construction + assert file_id in url + assert "generativelanguage.googleapis.com" in url + assert params == {} From d8761de660a08502b2d634c79acdef3c8b39108f Mon Sep 17 00:00:00 2001 From: Sameer Kankute Date: Tue, 3 Feb 2026 18:59:10 +0530 Subject: [PATCH 044/511] Add get files API support and tests --- litellm/llms/gemini/files/transformation.py | 1 - 1 file changed, 1 deletion(-) diff --git a/litellm/llms/gemini/files/transformation.py b/litellm/llms/gemini/files/transformation.py index 577b748692a..cc799cfd6aa 100644 --- a/litellm/llms/gemini/files/transformation.py +++ b/litellm/llms/gemini/files/transformation.py @@ -236,7 +236,6 @@ class GoogleAIStudioFilesHandler(GeminiModelInfo, BaseFilesConfig): """ try: response_json = raw_response.json() - print(f"response_json: {response_json}") # Map Gemini state to OpenAI status gemini_state = response_json.get("state", "STATE_UNSPECIFIED") From c1aa1c380cd4f08bf5ef3c7c039c11b27d1e8c10 Mon Sep 17 00:00:00 2001 From: Lucky Lodhi Date: Tue, 3 Feb 2026 13:50:43 +0000 Subject: [PATCH 045/511] removing thinking lines --- .../anthropic_claude3_transformation.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py b/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py index 6ae9cc1b60b..fbb6d0fd7bd 100644 --- a/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py +++ b/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py @@ -147,12 +147,6 @@ class AmazonAnthropicClaudeMessagesConfig( ttl = cache_control["ttl"] if is_claude_4_5 and ttl in ["5m", "1h"]: continue - - # [Maintain compatibility with current implementation and tests] - # Existing tests expect '5m' or '1h' to be preserved even if not Claude 4.5? - # Wait, the test I saw earlier expected '5m' and '1h' preservation! - # Let me re-read the test carefully. - if ttl in ["5m", "1h"]: continue From a25289e30a855ffe612434c4d9132a3630f50952 Mon Sep 17 00:00:00 2001 From: Lucky Lodhi Date: Tue, 3 Feb 2026 13:53:22 +0000 Subject: [PATCH 046/511] fixed typo --- .../invoke_transformations/anthropic_claude3_transformation.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py b/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py index fbb6d0fd7bd..d9f9ec8f4be 100644 --- a/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py +++ b/litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py @@ -122,7 +122,7 @@ class AmazonAnthropicClaudeMessagesConfig( Remove `ttl` field from cache_control in messages. Bedrock doesn't support the ttl field in cache_control. - Update: bedock supports `5m` and `1h` for Claude 4.5 models. + Update: Bedock supports `5m` and `1h` for Claude 4.5 models. Args: anthropic_messages_request: The request dictionary to modify in-place From c80fae71ef3a35f2953e7ba825d007db3d125794 Mon Sep 17 00:00:00 2001 From: Ishaan Jaffer Date: Tue, 3 Feb 2026 10:39:39 -0800 Subject: [PATCH 047/511] bump litellm enterprise PIP --- ...litellm_enterprise-0.1.29-py3-none-any.whl | Bin 0 -> 111358 bytes .../dist/litellm_enterprise-0.1.29.tar.gz | Bin 0 -> 48839 bytes enterprise/pyproject.toml | 4 +-- ...odel_prices_and_context_window_backup.json | 28 ++++++++++++++++++ poetry.lock | 20 +------------ requirements.txt | 2 +- 6 files changed, 32 insertions(+), 22 deletions(-) create mode 100644 enterprise/dist/litellm_enterprise-0.1.29-py3-none-any.whl create mode 100644 enterprise/dist/litellm_enterprise-0.1.29.tar.gz diff --git a/enterprise/dist/litellm_enterprise-0.1.29-py3-none-any.whl b/enterprise/dist/litellm_enterprise-0.1.29-py3-none-any.whl new file mode 100644 index 0000000000000000000000000000000000000000..0895ecbc4271ba78bed1da72468e19f87324b33a GIT binary patch literal 111358 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 literal 0 HcmV?d00001 diff --git a/enterprise/dist/litellm_enterprise-0.1.29.tar.gz b/enterprise/dist/litellm_enterprise-0.1.29.tar.gz new file mode 100644 index 0000000000000000000000000000000000000000..6781cf26cc9e9feab8ae6a0bacbb31fa52501dd0 GIT binary patch literal 48839 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.6.2 # for PDF text extraction in RAG ingestion ######################## # LITELLM ENTERPRISE DEPENDENCIES ######################## -litellm-enterprise==0.1.28 +litellm-enterprise==0.1.29 From 9ed11c5cdf9eeea521550b8e8805001f30c6e9e8 Mon Sep 17 00:00:00 2001 From: Ishaan Jaff Date: Tue, 3 Feb 2026 12:52:33 -0800 Subject: [PATCH 048/511] [Feat] Allow calling A2A agents through LiteLLM /chat/completions API (#20358) * init A2AConfig * add transform files * feat: A2A * feat A2AConfig * fix get_secret_str * init: A2AConfig * init A2AConfig common utils * A2AConfig * test_a2a_completion_async_non_streaming * fix * Update litellm/main.py Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * add multi part conversation support * extract_text_from_a2a_message --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- litellm/__init__.py | 1 + litellm/_lazy_imports_registry.py | 2 + litellm/llms/a2a/__init__.py | 6 + litellm/llms/a2a/chat/__init__.py | 6 + litellm/llms/a2a/chat/streaming_iterator.py | 103 ++++++ litellm/llms/a2a/chat/transformation.py | 303 ++++++++++++++++++ litellm/llms/a2a/common_utils.py | 134 ++++++++ litellm/main.py | 40 ++- litellm/types/utils.py | 1 + litellm/utils.py | 8 + provider_endpoints_support.json | 17 + .../code_coverage_tests/recursive_detector.py | 1 + tests/llm_translation/test_a2a.py | 132 ++++++++ 13 files changed, 750 insertions(+), 4 deletions(-) create mode 100644 litellm/llms/a2a/__init__.py create mode 100644 litellm/llms/a2a/chat/__init__.py create mode 100644 litellm/llms/a2a/chat/streaming_iterator.py create mode 100644 litellm/llms/a2a/chat/transformation.py create mode 100644 litellm/llms/a2a/common_utils.py create mode 100644 tests/llm_translation/test_a2a.py diff --git a/litellm/__init__.py b/litellm/__init__.py index 112d58d49d8..f857e10eed3 100644 --- a/litellm/__init__.py +++ b/litellm/__init__.py @@ -1378,6 +1378,7 @@ if TYPE_CHECKING: from .llms.topaz.image_variations.transformation import TopazImageVariationConfig as TopazImageVariationConfig from litellm.llms.openai.completion.transformation import OpenAITextCompletionConfig as OpenAITextCompletionConfig from .llms.groq.chat.transformation import GroqChatConfig as GroqChatConfig + from .llms.a2a.chat.transformation import A2AConfig as A2AConfig from .llms.voyage.embedding.transformation import VoyageEmbeddingConfig as VoyageEmbeddingConfig from .llms.voyage.embedding.transformation_contextual import VoyageContextualEmbeddingConfig as VoyageContextualEmbeddingConfig from .llms.infinity.embedding.transformation import InfinityEmbeddingConfig as InfinityEmbeddingConfig diff --git a/litellm/_lazy_imports_registry.py b/litellm/_lazy_imports_registry.py index 0e52e9a59eb..a01fe9c11db 100644 --- a/litellm/_lazy_imports_registry.py +++ b/litellm/_lazy_imports_registry.py @@ -213,6 +213,7 @@ LLM_CONFIG_NAMES = ( "TopazImageVariationConfig", "OpenAITextCompletionConfig", "GroqChatConfig", + "A2AConfig", "GenAIHubOrchestrationConfig", "VoyageEmbeddingConfig", "VoyageContextualEmbeddingConfig", @@ -850,6 +851,7 @@ _LLM_CONFIGS_IMPORT_MAP = { "OpenAITextCompletionConfig", ), "GroqChatConfig": (".llms.groq.chat.transformation", "GroqChatConfig"), + "A2AConfig": (".llms.a2a.chat.transformation", "A2AConfig"), "GenAIHubOrchestrationConfig": ( ".llms.sap.chat.transformation", "GenAIHubOrchestrationConfig", diff --git a/litellm/llms/a2a/__init__.py b/litellm/llms/a2a/__init__.py new file mode 100644 index 00000000000..043efa5e8bf --- /dev/null +++ b/litellm/llms/a2a/__init__.py @@ -0,0 +1,6 @@ +""" +A2A (Agent-to-Agent) Protocol Provider for LiteLLM +""" +from .chat.transformation import A2AConfig + +__all__ = ["A2AConfig"] diff --git a/litellm/llms/a2a/chat/__init__.py b/litellm/llms/a2a/chat/__init__.py new file mode 100644 index 00000000000..76bf4dd71d9 --- /dev/null +++ b/litellm/llms/a2a/chat/__init__.py @@ -0,0 +1,6 @@ +""" +A2A Chat Completion Implementation +""" +from .transformation import A2AConfig + +__all__ = ["A2AConfig"] diff --git a/litellm/llms/a2a/chat/streaming_iterator.py b/litellm/llms/a2a/chat/streaming_iterator.py new file mode 100644 index 00000000000..84b6fffaa31 --- /dev/null +++ b/litellm/llms/a2a/chat/streaming_iterator.py @@ -0,0 +1,103 @@ +""" +A2A Streaming Response Iterator +""" +from typing import Optional, Union + +from litellm.llms.base_llm.base_model_iterator import BaseModelResponseIterator +from litellm.types.utils import GenericStreamingChunk, ModelResponseStream + +from ..common_utils import extract_text_from_a2a_response + + +class A2AModelResponseIterator(BaseModelResponseIterator): + """ + Iterator for parsing A2A streaming responses. + + Converts A2A JSON-RPC streaming chunks to OpenAI-compatible format. + """ + + def __init__( + self, + streaming_response, + sync_stream: bool, + json_mode: Optional[bool] = False, + model: str = "a2a/agent", + ): + super().__init__( + streaming_response=streaming_response, + sync_stream=sync_stream, + json_mode=json_mode, + ) + self.model = model + + def chunk_parser(self, chunk: dict) -> Union[GenericStreamingChunk, ModelResponseStream]: + """ + Parse A2A streaming chunk to OpenAI format. + + A2A chunk format: + { + "jsonrpc": "2.0", + "id": "request-id", + "result": { + "message": { + "parts": [{"kind": "text", "text": "content"}] + } + } + } + + Or for tasks: + { + "jsonrpc": "2.0", + "result": { + "kind": "task", + "status": {"state": "running"}, + "artifacts": [{"parts": [{"kind": "text", "text": "content"}]}] + } + } + """ + try: + # Extract text from A2A response + text = extract_text_from_a2a_response(chunk) + + # Determine finish reason + finish_reason = self._get_finish_reason(chunk) + + # Return generic streaming chunk + return GenericStreamingChunk( + text=text, + is_finished=bool(finish_reason), + finish_reason=finish_reason or "", + usage=None, + index=0, + tool_use=None, + ) + except Exception: + # Return empty chunk on parse error + return GenericStreamingChunk( + text="", + is_finished=False, + finish_reason="", + usage=None, + index=0, + tool_use=None, + ) + + def _get_finish_reason(self, chunk: dict) -> Optional[str]: + """Extract finish reason from A2A chunk""" + result = chunk.get("result", {}) + + # Check for task completion + if isinstance(result, dict): + status = result.get("status", {}) + if isinstance(status, dict): + state = status.get("state") + if state == "completed": + return "stop" + elif state == "failed": + return "error" + + # Check for [DONE] marker + if chunk.get("done") is True: + return "stop" + + return None diff --git a/litellm/llms/a2a/chat/transformation.py b/litellm/llms/a2a/chat/transformation.py new file mode 100644 index 00000000000..243fba63719 --- /dev/null +++ b/litellm/llms/a2a/chat/transformation.py @@ -0,0 +1,303 @@ +""" +A2A Protocol Transformation for LiteLLM +""" +import uuid +from typing import Any, Dict, Iterator, List, Optional, Union, cast + +import httpx +from pydantic import BaseModel + +from litellm.llms.base_llm.base_model_iterator import BaseModelResponseIterator +from litellm.llms.base_llm.chat.transformation import BaseConfig, BaseLLMException +from litellm.types.llms.openai import AllMessageValues +from litellm.types.utils import Choices, Message, ModelResponse + +from ..common_utils import ( + A2AError, + convert_messages_to_prompt, + extract_text_from_a2a_response, +) +from .streaming_iterator import A2AModelResponseIterator + + +class A2AConfig(BaseConfig): + """ + Configuration for A2A (Agent-to-Agent) Protocol. + + Handles transformation between OpenAI and A2A JSON-RPC 2.0 formats. + """ + + def get_supported_openai_params(self, model: str) -> List[str]: + """Return list of supported OpenAI parameters""" + return [ + "stream", + "temperature", + "max_tokens", + "top_p", + ] + + def map_openai_params( + self, + non_default_params: dict, + optional_params: dict, + model: str, + drop_params: bool, + ) -> dict: + """ + Map OpenAI parameters to A2A parameters. + + For A2A protocol, we don't need to map most parameters since + they're handled in the transform_request method. + """ + return optional_params + + def validate_environment( + self, + headers: dict, + model: str, + messages: List[AllMessageValues], + optional_params: dict, + litellm_params: dict, + api_key: Optional[str] = None, + api_base: Optional[str] = None, + ) -> dict: + """ + Validate environment and set headers for A2A requests. + + Args: + headers: Request headers dict + model: Model name + messages: Messages list + optional_params: Optional parameters + litellm_params: LiteLLM parameters + api_key: API key (optional for A2A) + api_base: API base URL + + Returns: + Updated headers dict + """ + # Ensure Content-Type is set to application/json for JSON-RPC 2.0 + if "content-type" not in headers and "Content-Type" not in headers: + headers["Content-Type"] = "application/json" + + # Add Authorization header if API key is provided + if api_key is not None: + headers["Authorization"] = f"Bearer {api_key}" + + return headers + + def get_complete_url( + self, + api_base: Optional[str], + api_key: Optional[str], + model: str, + optional_params: dict, + litellm_params: dict, + stream: Optional[bool] = None, + ) -> str: + """ + Get the complete A2A agent endpoint URL. + + A2A agents use JSON-RPC 2.0 at the base URL, not specific paths. + The method (message/send or message/stream) is specified in the + JSON-RPC request body, not in the URL. + + Args: + api_base: Base URL of the A2A agent (e.g., "http://0.0.0.0:9999") + api_key: API key (not used for URL construction) + model: Model name (not used for A2A, agent determined by api_base) + optional_params: Optional parameters + litellm_params: LiteLLM parameters + stream: Whether this is a streaming request (affects JSON-RPC method) + + Returns: + Complete URL for the A2A endpoint (base URL) + """ + if api_base is None: + raise ValueError("api_base is required for A2A provider") + + # A2A uses JSON-RPC 2.0 at the base URL + # Remove trailing slash for consistency + return api_base.rstrip("/") + + def transform_request( + self, + model: str, + messages: List[AllMessageValues], + optional_params: dict, + litellm_params: dict, + headers: dict, + ) -> dict: + """ + Transform OpenAI request to A2A JSON-RPC 2.0 format. + + Args: + model: Model name + messages: List of OpenAI messages + optional_params: Optional parameters + litellm_params: LiteLLM parameters + headers: Request headers + + Returns: + A2A JSON-RPC 2.0 request dict + """ + # Generate request ID + request_id = str(uuid.uuid4()) + + if not messages: + raise ValueError("At least one message is required for A2A completion") + + # Convert all messages to maintain conversation history + # Use helper to format conversation with role prefixes + full_context = convert_messages_to_prompt(messages) + + # Create single A2A message with full conversation context + a2a_message = { + "role": "user", + "parts": [{"kind": "text", "text": full_context}], + "messageId": str(uuid.uuid4()), + } + + # Build JSON-RPC 2.0 request + # For A2A protocol, the method is "message/send" for non-streaming + # and "message/stream" for streaming (handled by optional_params["stream"]) + method = "message/stream" if optional_params.get("stream") else "message/send" + + request_data = { + "jsonrpc": "2.0", + "id": request_id, + "method": method, + "params": { + "message": a2a_message + } + } + + return request_data + + def transform_response( + self, + model: str, + raw_response: httpx.Response, + model_response: ModelResponse, + logging_obj: Any, + request_data: dict, + messages: List[AllMessageValues], + optional_params: dict, + litellm_params: dict, + encoding: Any, + api_key: Optional[str] = None, + json_mode: Optional[bool] = None, + ) -> ModelResponse: + """ + Transform A2A JSON-RPC 2.0 response to OpenAI format. + + Args: + model: Model name + raw_response: HTTP response from A2A agent + model_response: Model response object to populate + logging_obj: Logging object + request_data: Original request data + messages: Original messages + optional_params: Optional parameters + litellm_params: LiteLLM parameters + encoding: Encoding object + api_key: API key + json_mode: JSON mode flag + + Returns: + Populated ModelResponse object + """ + try: + response_json = raw_response.json() + except Exception as e: + raise A2AError( + status_code=raw_response.status_code, + message=f"Failed to parse A2A response: {str(e)}", + headers=dict(raw_response.headers), + ) + + # Check for JSON-RPC error + if "error" in response_json: + error = response_json["error"] + raise A2AError( + status_code=raw_response.status_code, + message=f"A2A error: {error.get('message', 'Unknown error')}", + headers=dict(raw_response.headers), + ) + + # Extract text from A2A response + text = extract_text_from_a2a_response(response_json) + + # Populate model response + model_response.choices = [ + Choices( + finish_reason="stop", + index=0, + message=Message( + content=text, + role="assistant", + ), + ) + ] + + # Set model + model_response.model = model + + # Set ID from response + model_response.id = response_json.get("id", str(uuid.uuid4())) + + return model_response + + def get_model_response_iterator( + self, + streaming_response: Union[Iterator, Any], + sync_stream: bool, + json_mode: Optional[bool] = False, + ) -> BaseModelResponseIterator: + """ + Get streaming iterator for A2A responses. + + Args: + streaming_response: Streaming response iterator + sync_stream: Whether this is a sync stream + json_mode: JSON mode flag + + Returns: + A2A streaming iterator + """ + return A2AModelResponseIterator( + streaming_response=streaming_response, + sync_stream=sync_stream, + json_mode=json_mode, + ) + + def _openai_message_to_a2a_message(self, message: Dict[str, Any]) -> Dict[str, Any]: + """ + Convert OpenAI message to A2A message format. + + Args: + message: OpenAI message dict + + Returns: + A2A message dict + """ + content = message.get("content", "") + role = message.get("role", "user") + + return { + "role": role, + "parts": [{"kind": "text", "text": str(content)}], + "messageId": str(uuid.uuid4()), + } + + def get_error_class( + self, error_message: str, status_code: int, headers: Union[dict, httpx.Headers] + ) -> BaseLLMException: + """Return appropriate error class for A2A errors""" + # Convert headers to dict if needed + headers_dict = dict(headers) if isinstance(headers, httpx.Headers) else headers + return A2AError( + status_code=status_code, + message=error_message, + headers=headers_dict, + ) diff --git a/litellm/llms/a2a/common_utils.py b/litellm/llms/a2a/common_utils.py new file mode 100644 index 00000000000..4c7da78b42f --- /dev/null +++ b/litellm/llms/a2a/common_utils.py @@ -0,0 +1,134 @@ +""" +Common utilities for A2A (Agent-to-Agent) Protocol +""" +from typing import Any, Dict, List + +from pydantic import BaseModel + +from litellm.litellm_core_utils.prompt_templates.common_utils import ( + convert_content_list_to_str, +) +from litellm.llms.base_llm.chat.transformation import BaseLLMException +from litellm.types.llms.openai import AllMessageValues + + +class A2AError(BaseLLMException): + """Base exception for A2A protocol errors""" + + def __init__( + self, + status_code: int, + message: str, + headers: Dict[str, Any] = {}, + ): + super().__init__( + status_code=status_code, + message=message, + headers=headers, + ) + + +def convert_messages_to_prompt(messages: List[AllMessageValues]) -> str: + """ + Convert OpenAI messages to a single prompt string for A2A agent. + + Formats each message as "{role}: {content}" and joins with newlines + to preserve conversation history. Handles both string and list content. + + Args: + messages: List of OpenAI-format messages + + Returns: + Formatted prompt string with full conversation context + """ + conversation_parts = [] + for msg in messages: + # Use LiteLLM's helper to extract text from content (handles both str and list) + content_text = convert_content_list_to_str(message=msg) + + # Get role + if isinstance(msg, BaseModel): + role = msg.model_dump().get("role", "user") + elif isinstance(msg, dict): + role = msg.get("role", "user") + else: + role = dict(msg).get("role", "user") # type: ignore + + if content_text: + conversation_parts.append(f"{role}: {content_text}") + + return "\n".join(conversation_parts) + + +def extract_text_from_a2a_message( + message: Dict[str, Any], depth: int = 0, max_depth: int = 10 +) -> str: + """ + Extract text content from A2A message parts. + + Args: + message: A2A message dict with 'parts' containing text parts + depth: Current recursion depth (internal use) + max_depth: Maximum recursion depth to prevent infinite loops + + Returns: + Concatenated text from all text parts + """ + if message is None or depth >= max_depth: + return "" + + parts = message.get("parts", []) + text_parts: List[str] = [] + + for part in parts: + if part.get("kind") == "text": + text_parts.append(part.get("text", "")) + # Handle nested parts if they exist + elif "parts" in part: + nested_text = extract_text_from_a2a_message(part, depth + 1, max_depth) + if nested_text: + text_parts.append(nested_text) + + return " ".join(text_parts) + + +def extract_text_from_a2a_response( + response_dict: Dict[str, Any], max_depth: int = 10 +) -> str: + """ + Extract text content from A2A response result. + + Args: + response_dict: A2A response dict with 'result' containing message + max_depth: Maximum recursion depth to prevent infinite loops + + Returns: + Text from response message parts + """ + result = response_dict.get("result", {}) + if not isinstance(result, dict): + return "" + + # A2A response can have different formats: + # 1. Direct message: {"result": {"kind": "message", "parts": [...]}} + # 2. Nested message: {"result": {"message": {"parts": [...]}}} + # 3. Task with artifacts: {"result": {"kind": "task", "artifacts": [{"parts": [...]}]}} + + # Check if result itself has parts (direct message) + if "parts" in result: + return extract_text_from_a2a_message(result, depth=0, max_depth=max_depth) + + # Check for nested message + message = result.get("message") + if message: + return extract_text_from_a2a_message(message, depth=0, max_depth=max_depth) + + # Handle task result with artifacts + artifacts = result.get("artifacts", []) + if artifacts and len(artifacts) > 0: + first_artifact = artifacts[0] + return extract_text_from_a2a_message( + first_artifact, depth=0, max_depth=max_depth + ) + + return "" diff --git a/litellm/main.py b/litellm/main.py index 7d591f76882..60c889ab1d0 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -2199,6 +2199,38 @@ def completion( # type: ignore # noqa: PLR0915 logging_obj=logging, # model call logging done inside the class as we make need to modify I/O to fit aleph alpha's requirements client=client, ) + elif custom_llm_provider == "a2a": + # A2A (Agent-to-Agent) Protocol + api_base = ( + api_base + or litellm.api_base + or get_secret_str("A2A_API_BASE") + ) + + if api_base is None: + raise Exception("api_base is required for A2A provider") + + headers = headers or litellm.headers + + response = base_llm_http_handler.completion( + model=model, + stream=stream, + messages=messages, + acompletion=acompletion, + api_base=api_base, + model_response=model_response, + optional_params=optional_params, + litellm_params=litellm_params, + shared_session=shared_session, + custom_llm_provider=custom_llm_provider, + timeout=timeout, + headers=headers, + encoding=_get_encoding(), + api_key=api_key, + logging_obj=logging, + client=client, + provider_config=provider_config, + ) elif custom_llm_provider == "gigachat": # GigaChat - Sber AI's LLM (Russia) api_key = ( @@ -3113,8 +3145,8 @@ def completion( # type: ignore # noqa: PLR0915 api_key or litellm.api_key or litellm.openrouter_key - or get_secret("OPENROUTER_API_KEY") - or get_secret("OR_API_KEY") + or get_secret_str("OPENROUTER_API_KEY") + or get_secret_str("OR_API_KEY") ) openrouter_site_url = get_secret("OR_SITE_URL") or "https://litellm.ai" @@ -4884,8 +4916,8 @@ def embedding( # noqa: PLR0915 api_key or litellm.api_key or litellm.openrouter_key - or get_secret("OPENROUTER_API_KEY") - or get_secret("OR_API_KEY") + or get_secret_str("OPENROUTER_API_KEY") + or get_secret_str("OR_API_KEY") ) openrouter_site_url = get_secret("OR_SITE_URL") or "https://litellm.ai" diff --git a/litellm/types/utils.py b/litellm/types/utils.py index 09c944e1fe8..e1f780ffcc3 100644 --- a/litellm/types/utils.py +++ b/litellm/types/utils.py @@ -3029,6 +3029,7 @@ class LlmProviders(str, Enum): MISTRAL = "mistral" MILVUS = "milvus" GROQ = "groq" + A2A = "a2a" GIGACHAT = "gigachat" NVIDIA_NIM = "nvidia_nim" CEREBRAS = "cerebras" diff --git a/litellm/utils.py b/litellm/utils.py index f3d14b455cd..7109f7aa881 100644 --- a/litellm/utils.py +++ b/litellm/utils.py @@ -1453,6 +1453,10 @@ def client(original_function): # noqa: PLR0915 logging_obj, kwargs = function_setup( original_function.__name__, rules_obj, start_time, *args, **kwargs ) + + # Type assertion: logging_obj is guaranteed to be non-None after function_setup + assert logging_obj is not None, "logging_obj should not be None after function_setup" + ## LOAD CREDENTIALS load_credentials_from_list(kwargs) kwargs["litellm_logging_obj"] = logging_obj @@ -1771,6 +1775,9 @@ def client(original_function): # noqa: PLR0915 logging_obj, kwargs = function_setup( original_function.__name__, rules_obj, start_time, *args, **kwargs ) + + # Type assertion: logging_obj is guaranteed to be non-None after function_setup + assert logging_obj is not None, "logging_obj should not be None after function_setup" modified_kwargs = await async_pre_call_deployment_hook(kwargs, call_type) if modified_kwargs is not None: @@ -7799,6 +7806,7 @@ class ProviderConfigManager: # Simple provider mappings (no model parameter needed) LlmProviders.DEEPSEEK: (lambda: litellm.DeepSeekChatConfig(), False), LlmProviders.GROQ: (lambda: litellm.GroqChatConfig(), False), + LlmProviders.A2A: (lambda: litellm.A2AConfig(), False), LlmProviders.BYTEZ: (lambda: litellm.BytezChatConfig(), False), LlmProviders.DATABRICKS: (lambda: litellm.DatabricksConfig(), False), LlmProviders.XAI: (lambda: litellm.XAIChatConfig(), False), diff --git a/provider_endpoints_support.json b/provider_endpoints_support.json index 0738c6e4e09..93e9e7beaaa 100644 --- a/provider_endpoints_support.json +++ b/provider_endpoints_support.json @@ -32,6 +32,23 @@ } }, "providers": { + "a2a": { + "display_name": "A2A (Agent-to-Agent) (`a2a`)", + "url": "https://docs.litellm.ai/docs/providers/a2a", + "endpoints": { + "chat_completions": true, + "messages": false, + "responses": false, + "embeddings": false, + "image_generations": false, + "audio_transcriptions": false, + "audio_speech": false, + "moderations": false, + "batches": false, + "rerank": false, + "a2a": false + } + }, "abliteration": { "display_name": "Abliteration (`abliteration`)", "url": "https://docs.litellm.ai/docs/providers/abliteration", diff --git a/tests/code_coverage_tests/recursive_detector.py b/tests/code_coverage_tests/recursive_detector.py index d5640f4256c..ed7595bb023 100644 --- a/tests/code_coverage_tests/recursive_detector.py +++ b/tests/code_coverage_tests/recursive_detector.py @@ -40,6 +40,7 @@ IGNORE_FUNCTIONS = [ "filter_exceptions_from_params", # max depth set (default 20) to prevent infinite recursion. "__getattr__", # lazy loading pattern in litellm/__init__.py with proper caching to prevent infinite recursion. "_validate_inheritance_chain", # max depth set (default 100) to prevent infinite recursion in policy inheritance validation. + "extract_text_from_a2a_message", # max depth set (default 10) to prevent infinite recursion in A2A message parsing. ] diff --git a/tests/llm_translation/test_a2a.py b/tests/llm_translation/test_a2a.py new file mode 100644 index 00000000000..2cfd3110ae1 --- /dev/null +++ b/tests/llm_translation/test_a2a.py @@ -0,0 +1,132 @@ +""" +Minimal E2E tests for A2A (Agent-to-Agent) Protocol provider. + +Tests validate that the endpoint is reachable and can handle both +streaming and non-streaming requests. +""" +import os +import sys + +import pytest + +sys.path.insert(0, os.path.abspath("../..")) + +import litellm + + +@pytest.mark.asyncio +async def test_a2a_completion_async_non_streaming(): + """ + Test A2A provider with async non-streaming request. + + Minimal test to validate endpoint reachability. + + Note: Requires an A2A agent running at http://0.0.0.0:9999 + Set A2A_API_BASE environment variable to use a different endpoint. + """ + api_base = os.environ.get("A2A_API_BASE", "http://0.0.0.0:9999") + + try: + response = await litellm.acompletion( + model="a2a/test-agent", + messages=[{"role": "user", "content": "Hello"}], + api_base=api_base, + stream=False, + ) + + print(f"Response: {response}") + assert response is not None, "Expected non-None response" + print(f"✅ Async non-streaming test passed") + + except litellm.exceptions.APIConnectionError as e: + pytest.skip(f"A2A agent not reachable at {api_base}: {e}") + except Exception as e: + pytest.fail(f"Error occurred: {e}") + + +@pytest.mark.asyncio +async def test_a2a_completion_async_streaming(): + """ + Test A2A provider with async streaming request. + + Minimal test to validate streaming endpoint reachability. + """ + api_base = os.environ.get("A2A_API_BASE", "http://0.0.0.0:9999") + + try: + response = await litellm.acompletion( + model="a2a/test-agent", + messages=[{"role": "user", "content": "Hello"}], + api_base=api_base, + stream=True, + ) + + chunks = [] + async for chunk in response: # type: ignore + chunks.append(chunk) + print(f"Chunk: {chunk}") + + assert len(chunks) > 0, "Expected at least one chunk in streaming response" + print(f"✅ Async streaming test passed: received {len(chunks)} chunks") + + except litellm.exceptions.APIConnectionError as e: + pytest.skip(f"A2A agent not reachable at {api_base}: {e}") + except Exception as e: + pytest.fail(f"Error occurred: {e}") + + +def test_a2a_completion_sync(): + """ + Test A2A provider with synchronous non-streaming request. + + Minimal test to validate sync endpoint reachability. + """ + api_base = os.environ.get("A2A_API_BASE", "http://0.0.0.0:9999") + + try: + response = litellm.completion( + model="a2a/test-agent", + messages=[{"role": "user", "content": "Hello"}], + api_base=api_base, + stream=False, + ) + + print(f"Response: {response}") + assert response is not None, "Expected non-None response" + print(f"✅ Sync non-streaming test passed") + + except litellm.exceptions.APIConnectionError as e: + pytest.skip(f"A2A agent not reachable at {api_base}: {e}") + except Exception as e: + pytest.fail(f"Error occurred: {e}") + + +def test_a2a_completion_sync_streaming(): + """ + Test A2A provider with synchronous streaming request. + + Minimal test to validate sync streaming endpoint reachability. + """ + api_base = os.environ.get("A2A_API_BASE", "http://0.0.0.0:9999") + + try: + response = litellm.completion( + model="a2a/test-agent", + messages=[{"role": "user", "content": "Hello"}], + api_base=api_base, + stream=True, + ) + + chunks = [] + for chunk in response: # type: ignore + chunks.append(chunk) + print(f"Chunk: {chunk}") + + assert len(chunks) > 0, "Expected at least one chunk in streaming response" + print(f"✅ Sync streaming test passed: received {len(chunks)} chunks") + + except litellm.exceptions.APIConnectionError as e: + pytest.skip(f"A2A agent not reachable at {api_base}: {e}") + except Exception as e: + pytest.fail(f"Error occurred: {e}") + From 59cab4d2aa9c436f60b619513c75b1ffb1d7aea9 Mon Sep 17 00:00:00 2001 From: Ishaan Jaff Date: Tue, 3 Feb 2026 12:53:50 -0800 Subject: [PATCH 049/511] UI - Show team alias on Models health page (#20359) * feat(ui): Add team-alias column to Models Health Status UI - Added Team Alias column to the Models Health Status table - Updated HealthCheckComponent to accept teams prop - Updated health_check_columns to display team alias based on team_id - Falls back to team_id if team alias not found, or shows '-' if no team - Updated parent components to pass teams data to HealthCheckComponent Co-authored-by: ishaan * Update ui/litellm-dashboard/src/components/model_dashboard/health_check_columns.tsx Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --------- Co-authored-by: Cursor Agent Co-authored-by: ishaan Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .../ModelsAndEndpointsView.tsx | 1 + .../model_dashboard/HealthCheckComponent.tsx | 4 +++ .../model_dashboard/health_check_columns.tsx | 27 +++++++++++++++++++ .../components/templates/model_dashboard.tsx | 1 + 4 files changed, 33 insertions(+) diff --git a/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/ModelsAndEndpointsView.tsx b/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/ModelsAndEndpointsView.tsx index 6a4882a92a2..8bfbaa8d3a6 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/ModelsAndEndpointsView.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/models-and-endpoints/ModelsAndEndpointsView.tsx @@ -400,6 +400,7 @@ const ModelsAndEndpointsView: React.FC = ({ premiumUser, te all_models_on_proxy={allModelsOnProxy} getDisplayModelName={getDisplayModelName} setSelectedModelId={setSelectedModelId} + teams={teams} /> string; setSelectedModelId?: (modelId: string) => void; + teams?: Team[] | null; } const HealthCheckComponent: React.FC = ({ @@ -32,6 +34,7 @@ const HealthCheckComponent: React.FC = ({ all_models_on_proxy, getDisplayModelName, setSelectedModelId, + teams, }) => { const [modelHealthStatuses, setModelHealthStatuses] = useState<{ [key: string]: HealthStatus }>({}); const [selectedModelsForHealth, setSelectedModelsForHealth] = useState([]); @@ -574,6 +577,7 @@ const HealthCheckComponent: React.FC = ({ showErrorModal, showSuccessModal, setSelectedModelId, + teams, )} data={modelData.data.map((model: any) => { const modelName = model.model_name; diff --git a/ui/litellm-dashboard/src/components/model_dashboard/health_check_columns.tsx b/ui/litellm-dashboard/src/components/model_dashboard/health_check_columns.tsx index 077b9d1004f..3e8ae662ad4 100644 --- a/ui/litellm-dashboard/src/components/model_dashboard/health_check_columns.tsx +++ b/ui/litellm-dashboard/src/components/model_dashboard/health_check_columns.tsx @@ -2,6 +2,7 @@ import { ColumnDef } from "@tanstack/react-table"; import { Tooltip, Checkbox } from "antd"; import { Text } from "@tremor/react"; import { InformationCircleIcon, PlayIcon, RefreshIcon } from "@heroicons/react/outline"; +import { Team } from "@/components/key_team_helpers/key_list"; interface HealthCheckData { model_name: string; @@ -42,6 +43,7 @@ export const healthCheckColumns = ( showErrorModal?: (modelName: string, cleanedError: string, fullError: string) => void, showSuccessModal?: (modelName: string, response: any) => void, setSelectedModelId?: (modelId: string) => void, + teams?: Team[] | null, ): ColumnDef[] => [ { header: () => ( @@ -100,6 +102,31 @@ export const healthCheckColumns = ( ); }, }, + { + header: "Team Alias", + accessorKey: "model_info.team_id", + enableSorting: true, + sortingFn: "alphanumeric", + cell: ({ row }) => { + const model = row.original; + const teamId = model.model_info?.team_id; + + if (!teamId) { + return -; + } + + const team = teams?.find((t) => t.team_id === teamId); + const teamAlias = team?.team_alias || teamId; + + return ( +

+ ); + }, + }, { header: "Health Status", accessorKey: "health_status", diff --git a/ui/litellm-dashboard/src/components/templates/model_dashboard.tsx b/ui/litellm-dashboard/src/components/templates/model_dashboard.tsx index e4dc896f55d..6f3ce27567c 100644 --- a/ui/litellm-dashboard/src/components/templates/model_dashboard.tsx +++ b/ui/litellm-dashboard/src/components/templates/model_dashboard.tsx @@ -1368,6 +1368,7 @@ const OldModelDashboard: React.FC = ({ all_models_on_proxy={all_models_on_proxy} getDisplayModelName={getDisplayModelName} setSelectedModelId={setSelectedModelId} + teams={teams} /> From cc76f95555b5e5576df903b05f8c7b4a1abc74ab Mon Sep 17 00:00:00 2001 From: Alexander Grattan <51346343+agrattan0820@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:41:13 -0500 Subject: [PATCH 050/511] fix: check for model_response_choices before guardrail input (#19784) * fix: check for model_response_choices before guardrail input * test: add tests for responses api translation * fix: protect other guardrail translations * refactor: remove type ignores * anthropic request body got mutated fix * add warning when extra_body is provided but user is non premium * fix: resolve mypy union-attr errors in anthropic guardrail handler Cast choices[0] to Choices type before accessing .message attribute to satisfy mypy's union type checking for Choices | StreamingChoices. Co-Authored-By: Claude Opus 4.5 * add logger when model response has no choices for streaming /response and /messages * update pyproject.toml as requested * Revert "update pyproject.toml as requested" This reverts commit 541a2b075a91b1b2d9efaf0407572f35bf5d4324. * update pyproject.toml as requested * Revert "update pyproject.toml as requested" This reverts commit 716ea0caa1fee5e5f028d3f86479fedea2fac68b. --------- Co-authored-by: Xiaohan Fu Co-authored-by: Claude Opus 4.5 --- litellm/integrations/custom_guardrail.py | 9 +- .../chat/guardrail_translation/handler.py | 72 ++++-- .../chat/guardrail_translation/handler.py | 21 +- .../guardrail_translation/handler.py | 51 ++-- .../test_anthropic_guardrail_handler.py | 236 ++++++++++++++++++ .../test_openai_guardrail_handler.py | 148 +++++++++++ ...test_openai_responses_guardrail_handler.py | 178 +++++++++++++ 7 files changed, 655 insertions(+), 60 deletions(-) create mode 100644 tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py diff --git a/litellm/integrations/custom_guardrail.py b/litellm/integrations/custom_guardrail.py index a5bb530fc56..1652ec2aa0c 100644 --- a/litellm/integrations/custom_guardrail.py +++ b/litellm/integrations/custom_guardrail.py @@ -475,11 +475,18 @@ class CustomGuardrail(CustomLogger): guardrail_config: DynamicGuardrailParams = DynamicGuardrailParams( **guardrail[self.guardrail_name] ) + extra_body = guardrail_config.get("extra_body", {}) if self._validate_premium_user() is not True: + if isinstance(extra_body, dict) and extra_body: + verbose_logger.warning( + "Guardrail %s: ignoring dynamic extra_body keys %s because premium_user is False", + self.guardrail_name, + list(extra_body.keys()), + ) return {} # Return the extra_body if it exists, otherwise empty dict - return guardrail_config.get("extra_body", {}) + return extra_body return {} diff --git a/litellm/llms/anthropic/chat/guardrail_translation/handler.py b/litellm/llms/anthropic/chat/guardrail_translation/handler.py index 8e1016bd5bd..a14e7d118e8 100644 --- a/litellm/llms/anthropic/chat/guardrail_translation/handler.py +++ b/litellm/llms/anthropic/chat/guardrail_translation/handler.py @@ -34,6 +34,7 @@ from litellm.types.llms.openai import ( ) from litellm.types.utils import ( ChatCompletionMessageToolCall, + Choices, GenericGuardrailAPIInputs, ModelResponse, ) @@ -76,7 +77,8 @@ class AnthropicMessagesHandler(BaseTranslation): chat_completion_compatible_request, tool_name_mapping = ( LiteLLMAnthropicMessagesAdapter().translate_anthropic_to_openai( - anthropic_message_request=cast(AnthropicMessagesRequest, data) + # Use a shallow copy to avoid mutating request data (pop on litellm_metadata). + anthropic_message_request=cast(AnthropicMessagesRequest, data.copy()) ) ) @@ -84,9 +86,9 @@ class AnthropicMessagesHandler(BaseTranslation): texts_to_check: List[str] = [] images_to_check: List[str] = [] - tools_to_check: List[ChatCompletionToolParam] = ( - chat_completion_compatible_request.get("tools", []) - ) + tools_to_check: List[ + ChatCompletionToolParam + ] = chat_completion_compatible_request.get("tools", []) task_mappings: List[Tuple[int, Optional[int]]] = [] # Track (message_index, content_index) for each text # content_index is None for string content, int for list content @@ -282,7 +284,10 @@ class AnthropicMessagesHandler(BaseTranslation): if hasattr(content_block, "model_dump"): block_dict = content_block.model_dump() else: - block_dict = {"type": block_type, "text": getattr(content_block, "text", None)} + block_dict = { + "type": block_type, + "text": getattr(content_block, "text", None), + } else: continue @@ -358,30 +363,40 @@ class AnthropicMessagesHandler(BaseTranslation): """ has_ended = self._check_streaming_has_ended(responses_so_far) if has_ended: - # build the model response from the responses_so_far - model_response = cast( - ModelResponse, - AnthropicPassthroughLoggingHandler._build_complete_streaming_response( - all_chunks=responses_so_far, - litellm_logging_obj=cast("LiteLLMLoggingObj", litellm_logging_obj), - model="", - ), + built_response = AnthropicPassthroughLoggingHandler._build_complete_streaming_response( + all_chunks=responses_so_far, + litellm_logging_obj=cast("LiteLLMLoggingObj", litellm_logging_obj), + model="", ) - tool_calls_list = cast(Optional[List[ChatCompletionMessageToolCall]], model_response.choices[0].message.tool_calls) # type: ignore - string_so_far = model_response.choices[0].message.content # type: ignore - guardrail_inputs = GenericGuardrailAPIInputs() - if string_so_far: - guardrail_inputs["texts"] = [string_so_far] - if tool_calls_list: - guardrail_inputs["tool_calls"] = tool_calls_list - _guardrailed_inputs = await guardrail_to_apply.apply_guardrail( # allow rejecting the response, if invalid - inputs=guardrail_inputs, - request_data={}, - input_type="response", - logging_obj=litellm_logging_obj, - ) + # Check if model_response is valid and has choices before accessing + if ( + built_response is not None + and hasattr(built_response, "choices") + and built_response.choices + ): + model_response = cast(ModelResponse, built_response) + first_choice = cast(Choices, model_response.choices[0]) + tool_calls_list = cast( + Optional[List[ChatCompletionMessageToolCall]], + first_choice.message.tool_calls, + ) + string_so_far = first_choice.message.content + guardrail_inputs = GenericGuardrailAPIInputs() + if string_so_far: + guardrail_inputs["texts"] = [string_so_far] + if tool_calls_list: + guardrail_inputs["tool_calls"] = tool_calls_list + + _guardrailed_inputs = await guardrail_to_apply.apply_guardrail( # allow rejecting the response, if invalid + inputs=guardrail_inputs, + request_data={}, + input_type="response", + logging_obj=litellm_logging_obj, + ) + else: + verbose_proxy_logger.debug("Skipping output guardrail - model response has no choices") return responses_so_far string_so_far = self.get_streaming_string_so_far(responses_so_far) @@ -648,7 +663,10 @@ class AnthropicMessagesHandler(BaseTranslation): if isinstance(content_block, dict): if content_block.get("type") == "text": cast(Dict[str, Any], content_block)["text"] = guardrail_response - elif hasattr(content_block, "type") and getattr(content_block, "type", None) == "text": + elif ( + hasattr(content_block, "type") + and getattr(content_block, "type", None) == "text" + ): # Update Pydantic object's text attribute if hasattr(content_block, "text"): content_block.text = guardrail_response diff --git a/litellm/llms/openai/chat/guardrail_translation/handler.py b/litellm/llms/openai/chat/guardrail_translation/handler.py index fb00aa28f45..c406f502b45 100644 --- a/litellm/llms/openai/chat/guardrail_translation/handler.py +++ b/litellm/llms/openai/chat/guardrail_translation/handler.py @@ -21,7 +21,13 @@ from litellm._logging import verbose_proxy_logger from litellm.llms.base_llm.guardrail_translation.base_translation import BaseTranslation from litellm.main import stream_chunk_builder from litellm.types.llms.openai import ChatCompletionToolParam -from litellm.types.utils import Choices, GenericGuardrailAPIInputs, ModelResponse, ModelResponseStream, StreamingChoices +from litellm.types.utils import ( + Choices, + GenericGuardrailAPIInputs, + ModelResponse, + ModelResponseStream, + StreamingChoices, +) if TYPE_CHECKING: from litellm.integrations.custom_guardrail import CustomGuardrail @@ -80,9 +86,9 @@ class OpenAIChatCompletionsHandler(BaseTranslation): if tool_calls_to_check: inputs["tool_calls"] = tool_calls_to_check # type: ignore if messages: - inputs["structured_messages"] = ( - messages # pass the openai /chat/completions messages to the guardrail, as-is - ) + inputs[ + "structured_messages" + ] = messages # pass the openai /chat/completions messages to the guardrail, as-is # Pass tools (function definitions) to the guardrail tools = data.get("tools") if tools: @@ -362,14 +368,17 @@ class OpenAIChatCompletionsHandler(BaseTranslation): # check if the stream has ended has_stream_ended = False for chunk in responses_so_far: - if chunk.choices[0].finish_reason is not None: + if chunk.choices and chunk.choices[0].finish_reason is not None: has_stream_ended = True break if has_stream_ended: # convert to model response model_response = cast( - ModelResponse, stream_chunk_builder(chunks=responses_so_far, logging_obj=litellm_logging_obj) + ModelResponse, + stream_chunk_builder( + chunks=responses_so_far, logging_obj=litellm_logging_obj + ), ) # run process_output_response await self.process_output_response( diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py index d943662f9e4..ad3d4c932d4 100644 --- a/litellm/llms/openai/responses/guardrail_translation/handler.py +++ b/litellm/llms/openai/responses/guardrail_translation/handler.py @@ -319,9 +319,7 @@ class OpenAIResponsesHandler(BaseTranslation): return response if not response_output: - verbose_proxy_logger.debug( - "OpenAI Responses API: Empty output in response" - ) + verbose_proxy_logger.debug("OpenAI Responses API: Empty output in response") return response # Step 1: Extract all text content and tool calls from response output @@ -427,27 +425,30 @@ class OpenAIResponsesHandler(BaseTranslation): handle_raw_dict_callback=None, ) - tool_calls = model_response_choices[0].message.tool_calls - text = model_response_choices[0].message.content - guardrail_inputs = GenericGuardrailAPIInputs() - if text: - guardrail_inputs["texts"] = [text] - if tool_calls: - guardrail_inputs["tool_calls"] = cast( - List[ChatCompletionToolCallChunk], tool_calls - ) - # Include model information from the response if available - response_model = final_chunk.get("response", {}).get("model") - if response_model: - guardrail_inputs["model"] = response_model - if tool_calls or text: - _guardrailed_inputs = await guardrail_to_apply.apply_guardrail( - inputs=guardrail_inputs, - request_data={}, - input_type="response", - logging_obj=litellm_logging_obj, - ) - return responses_so_far + if model_response_choices: + tool_calls = model_response_choices[0].message.tool_calls + text = model_response_choices[0].message.content + guardrail_inputs = GenericGuardrailAPIInputs() + if text: + guardrail_inputs["texts"] = [text] + if tool_calls: + guardrail_inputs["tool_calls"] = cast( + List[ChatCompletionToolCallChunk], tool_calls + ) + # Include model information from the response if available + response_model = final_chunk.get("response", {}).get("model") + if response_model: + guardrail_inputs["model"] = response_model + if tool_calls or text: + _guardrailed_inputs = await guardrail_to_apply.apply_guardrail( + inputs=guardrail_inputs, + request_data={}, + input_type="response", + logging_obj=litellm_logging_obj, + ) + return responses_so_far + else: + verbose_proxy_logger.debug("Skipping output guardrail - model response has no choices") # model_response_stream = OpenAiResponsesToChatCompletionStreamIterator.translate_responses_chunk_to_openai_stream(final_chunk) # tool_calls = model_response_stream.choices[0].tool_calls # convert openai response to model response @@ -513,11 +514,9 @@ class OpenAIResponsesHandler(BaseTranslation): # Check if it's an OutputText with text if isinstance(content_item, OutputText): if content_item.text: - return True elif isinstance(content_item, dict): if content_item.get("text"): - return True return False diff --git a/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py b/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py new file mode 100644 index 00000000000..82517b7af9e --- /dev/null +++ b/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py @@ -0,0 +1,236 @@ +""" +Unit tests for Anthropic Messages Guardrail Translation Handler + +Tests the handler's ability to process streaming output for Anthropic Messages API +with guardrail transformations, specifically testing edge cases with empty choices. +""" + +import os +import sys +from typing import Any, List, Literal, Optional +from unittest.mock import MagicMock, patch + +import pytest + +sys.path.insert( + 0, os.path.abspath("../../../../../../..") +) # Adds the parent directory to the system path + +from litellm.integrations.custom_guardrail import CustomGuardrail +from litellm.llms.anthropic.chat.guardrail_translation.handler import ( + AnthropicMessagesHandler, +) +from litellm.types.utils import GenericGuardrailAPIInputs + + +class MockPassThroughGuardrail(CustomGuardrail): + """Mock guardrail that passes through without blocking - for testing streaming fallback behavior""" + + async def apply_guardrail( + self, + inputs: GenericGuardrailAPIInputs, + request_data: dict, + input_type: Literal["request", "response"], + logging_obj: Optional[Any] = None, + ) -> GenericGuardrailAPIInputs: + """Simply return inputs unchanged""" + return inputs + + +class MockDynamicGuardrail(CustomGuardrail): + """Mock guardrail that records dynamic params from request metadata.""" + + def __init__(self, guardrail_name: str): + super().__init__(guardrail_name=guardrail_name) + self.dynamic_params: Optional[dict] = None + + async def apply_guardrail( + self, + inputs: GenericGuardrailAPIInputs, + request_data: dict, + input_type: Literal["request", "response"], + logging_obj: Optional[Any] = None, + ) -> GenericGuardrailAPIInputs: + self.dynamic_params = self.get_guardrail_dynamic_request_body_params( + request_data + ) + return inputs + + +class TestAnthropicMessagesHandlerStreamingOutputProcessing: + """Test streaming output processing functionality""" + + @pytest.mark.asyncio + async def test_process_output_streaming_response_empty_model_response(self): + """Test that streaming response with None model_response doesn't raise error + + This test verifies the fix for the bug where accessing model_response.choices[0] + would raise an error when _build_complete_streaming_response returns None. + """ + handler = AnthropicMessagesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Mock _check_streaming_has_ended to return True (stream ended) + # and _build_complete_streaming_response to return None + with patch.object( + handler, "_check_streaming_has_ended", return_value=True + ), patch( + "litellm.llms.anthropic.chat.guardrail_translation.handler.AnthropicPassthroughLoggingHandler._build_complete_streaming_response", + return_value=None, + ): + responses_so_far = [b"data: some chunk"] + + # This should not raise an error + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=MagicMock(), + ) + + # Should return the responses unchanged + assert result == responses_so_far + + +class TestAnthropicMessagesHandlerInputProcessing: + """Test input processing preserves litellm_metadata for dynamic guardrails.""" + + @pytest.mark.asyncio + async def test_process_input_messages_preserves_litellm_metadata_guardrails(self): + handler = AnthropicMessagesHandler() + guardrail = MockDynamicGuardrail(guardrail_name="cygnal-monitor") + + data = { + "model": "claude-3-5-sonnet-20241022", + "messages": [{"role": "user", "content": "hello"}], + "litellm_metadata": { + "guardrails": [ + { + "cygnal-monitor": { + "extra_body": {"policy_id": "policy-123"} + } + } + ] + }, + } + + with patch("litellm.proxy.proxy_server.premium_user", True): + await handler.process_input_messages(data=data, guardrail_to_apply=guardrail) + + assert data.get("litellm_metadata", {}).get("guardrails") + assert guardrail.dynamic_params == {"policy_id": "policy-123"} + + @pytest.mark.asyncio + async def test_process_output_streaming_response_empty_choices(self): + """Test that streaming response with empty choices doesn't raise IndexError + + This test verifies the fix for the bug where accessing model_response.choices[0] + would raise IndexError when the response has an empty choices list. + """ + from litellm.types.utils import ModelResponse + + handler = AnthropicMessagesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Create a mock response with empty choices + mock_response = ModelResponse( + id="msg_123", + created=1234567890, + model="claude-3", + object="chat.completion", + choices=[], # Empty choices + ) + + # Mock _check_streaming_has_ended to return True (stream ended) + # and _build_complete_streaming_response to return the mock response + with patch.object( + handler, "_check_streaming_has_ended", return_value=True + ), patch( + "litellm.llms.anthropic.chat.guardrail_translation.handler.AnthropicPassthroughLoggingHandler._build_complete_streaming_response", + return_value=mock_response, + ): + responses_so_far = [b"data: some chunk"] + + # This should not raise IndexError + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=MagicMock(), + ) + + # Should return the responses unchanged + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_with_valid_choices(self): + """Test that streaming response with valid choices still works correctly""" + from litellm.types.utils import Choices, Message, ModelResponse + + handler = AnthropicMessagesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Create a mock response with valid choices + mock_response = ModelResponse( + id="msg_123", + created=1234567890, + model="claude-3", + object="chat.completion", + choices=[ + Choices( + finish_reason="stop", + index=0, + message=Message( + content="Hello world", + role="assistant", + ), + ) + ], + ) + + # Mock _check_streaming_has_ended to return True (stream ended) + # and _build_complete_streaming_response to return the mock response + with patch.object( + handler, "_check_streaming_has_ended", return_value=True + ), patch( + "litellm.llms.anthropic.chat.guardrail_translation.handler.AnthropicPassthroughLoggingHandler._build_complete_streaming_response", + return_value=mock_response, + ): + responses_so_far = [b"data: some chunk"] + + # This should process successfully + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=MagicMock(), + ) + + # Should return the responses + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_stream_not_ended(self): + """Test that streaming response falls back to text processing when stream hasn't ended""" + handler = AnthropicMessagesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Mock _check_streaming_has_ended to return False (stream not ended) + with patch.object( + handler, "_check_streaming_has_ended", return_value=False + ), patch.object( + handler, "get_streaming_string_so_far", return_value="partial text" + ): + responses_so_far = [b"data: some chunk"] + + # This should process successfully using text-based guardrail + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=MagicMock(), + ) + + # Should return the responses + assert result == responses_so_far + + +if __name__ == "__main__": + # Run the tests + pytest.main([__file__, "-v"]) diff --git a/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py b/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py index 6c0195d2831..1f5f53d0f0c 100644 --- a/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py +++ b/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py @@ -733,6 +733,154 @@ class TestOpenAIChatCompletionsHandlerToolCallsOutput: assert response.choices[0].finish_reason == "tool_calls" +class MockPassThroughGuardrail(CustomGuardrail): + """Mock guardrail that passes through without blocking - for testing streaming fallback behavior""" + + async def apply_guardrail( + self, + inputs: GenericGuardrailAPIInputs, + request_data: dict, + input_type: Literal["request", "response"], + logging_obj: Optional[Any] = None, + ) -> GenericGuardrailAPIInputs: + """Simply return inputs unchanged""" + return inputs + + +class TestOpenAIChatCompletionsHandlerStreamingOutput: + """Test streaming output processing functionality""" + + @pytest.mark.asyncio + async def test_process_output_streaming_response_empty_choices(self): + """Test that streaming response with empty choices doesn't raise IndexError + + This test verifies the fix for the bug where accessing chunk.choices[0] + would raise IndexError when a streaming chunk has an empty choices list. + """ + from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices + + handler = OpenAIChatCompletionsHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Create a streaming chunk with empty choices + chunk_with_empty_choices = ModelResponseStream( + id="chatcmpl-123", + created=1234567890, + model="gpt-4", + object="chat.completion.chunk", + choices=[], # Empty choices - this was causing the IndexError + ) + + responses_so_far = [chunk_with_empty_choices] + + # This should not raise IndexError + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses unchanged + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_with_valid_choices(self): + """Test that streaming response with valid choices still works correctly""" + from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices + + handler = OpenAIChatCompletionsHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Create streaming chunks with valid choices + chunk1 = ModelResponseStream( + id="chatcmpl-123", + created=1234567890, + model="gpt-4", + object="chat.completion.chunk", + choices=[ + StreamingChoices( + index=0, + delta=Delta(content="Hello"), + finish_reason=None, + ) + ], + ) + + chunk2 = ModelResponseStream( + id="chatcmpl-123", + created=1234567890, + model="gpt-4", + object="chat.completion.chunk", + choices=[ + StreamingChoices( + index=0, + delta=Delta(content=" world"), + finish_reason="stop", + ) + ], + ) + + responses_so_far = [chunk1, chunk2] + + # This should process successfully + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_mixed_empty_and_valid_choices_no_finish(self): + """Test streaming response with mix of empty and valid choices chunks (stream not finished) + + This tests the has_stream_ended check when iterating through chunks with mixed choices. + The stream hasn't finished yet (no finish_reason), so it won't trigger stream_chunk_builder. + """ + from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices + + handler = OpenAIChatCompletionsHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Mix of chunks - some with empty choices, some with valid choices + # Stream hasn't finished (no finish_reason) + chunk_empty = ModelResponseStream( + id="chatcmpl-123", + created=1234567890, + model="gpt-4", + object="chat.completion.chunk", + choices=[], + ) + + chunk_valid = ModelResponseStream( + id="chatcmpl-123", + created=1234567890, + model="gpt-4", + object="chat.completion.chunk", + choices=[ + StreamingChoices( + index=0, + delta=Delta(content="Hello"), + finish_reason=None, # Stream not finished + ) + ], + ) + + responses_so_far = [chunk_empty, chunk_valid] + + # This should not raise IndexError when checking has_stream_ended + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses + assert result == responses_so_far + + if __name__ == "__main__": # Run the tests pytest.main([__file__, "-v"]) diff --git a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py index a2849ab91a2..ccece8018ff 100644 --- a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py +++ b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py @@ -817,3 +817,181 @@ class TestOpenAIResponsesHandlerToolCallExtraction: assert task_mappings[0] == (0, 0) assert task_mappings[1] == (0, 1) assert task_mappings[2] == (0, 2) + + +class MockPassThroughGuardrail(CustomGuardrail): + """Mock guardrail that passes through without blocking - for testing streaming fallback behavior""" + + async def apply_guardrail( + self, + inputs: GenericGuardrailAPIInputs, + request_data: dict, + input_type: Literal["request", "response"], + logging_obj: Optional[Any] = None, + ) -> GenericGuardrailAPIInputs: + """Simply return inputs unchanged""" + return inputs + + +class TestOpenAIResponsesHandlerStreamingOutputProcessing: + """Test streaming output processing functionality""" + + @pytest.mark.asyncio + async def test_process_output_streaming_response_empty_output(self): + """Test that streaming response with empty output doesn't raise IndexError + + This test verifies the fix for the bug where accessing model_response_choices[0] + would raise IndexError when the response.completed event has an empty output array. + """ + handler = OpenAIResponsesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Simulate a response.completed streaming event with empty output + responses_so_far = [ + { + "type": "response.completed", + "response": { + "id": "resp_123", + "output": [], # Empty output - this was causing the IndexError + "status": "completed", + }, + } + ] + + # This should not raise IndexError + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses unchanged + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_missing_output_key(self): + """Test that streaming response with missing output key doesn't raise IndexError + + This test verifies the handler gracefully handles when the response dict + doesn't contain an 'output' key at all. + """ + handler = OpenAIResponsesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Simulate a response.completed streaming event with missing output key + responses_so_far = [ + { + "type": "response.completed", + "response": { + "id": "resp_123", + "status": "completed", + # No 'output' key - get() will return [] + }, + } + ] + + # This should not raise IndexError + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses unchanged + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_unrecognized_output_type(self): + """Test that streaming response with unrecognized output types doesn't raise IndexError + + This test verifies the handler gracefully handles when output items are of + unrecognized types that _convert_response_output_to_choices skips over. + """ + handler = OpenAIResponsesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Simulate a response.completed streaming event with unrecognized output type + responses_so_far = [ + { + "type": "response.completed", + "response": { + "id": "resp_123", + "output": [ + { + "type": "unknown_type", # Unrecognized type + "id": "item_123", + "data": "some data", + } + ], + "status": "completed", + }, + } + ] + + # This should not raise IndexError + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses unchanged + assert result == responses_so_far + + @pytest.mark.asyncio + async def test_process_output_streaming_response_with_valid_output(self): + """Test that streaming response with valid output still works correctly""" + handler = OpenAIResponsesHandler() + guardrail = MockPassThroughGuardrail(guardrail_name="test") + + # Simulate a response.completed streaming event with valid message output + responses_so_far = [ + { + "type": "response.created", + "response": {"id": "resp_123"}, + }, + { + "type": "response.output_item.added", + "item": {"type": "message", "id": "msg_123"}, + }, + { + "type": "response.content_part.added", + "part": {"type": "output_text", "text": ""}, + }, + { + "type": "response.output_text.delta", + "delta": "Hello", + }, + { + "type": "response.output_text.delta", + "delta": " world", + }, + { + "type": "response.completed", + "response": { + "id": "resp_123", + "output": [ + { + "type": "message", + "id": "msg_123", + "status": "completed", + "role": "assistant", + "content": [ + {"type": "output_text", "text": "Hello world"}, + ], + } + ], + "status": "completed", + }, + }, + ] + + # This should process successfully + result = await handler.process_output_streaming_response( + responses_so_far=responses_so_far, + guardrail_to_apply=guardrail, + litellm_logging_obj=None, + ) + + # Should return the responses + assert result == responses_so_far From 2b25d03046da9dbd42f3d2b9f85ed02400910c1c Mon Sep 17 00:00:00 2001 From: Xiaohan Fu Date: Tue, 3 Feb 2026 17:41:31 -0500 Subject: [PATCH 051/511] Fix fail-open for grayswan and pass metadata to cygnal api endpoint (#19837) * fix fail-open for grayswan; pass metadata to cygnal api endpoint; update docs * pass litellm_metadata to cygnal in payload * switch error msg to const, and clean exception handling. * update pyproject.toml as requested * Revert "update pyproject.toml as requested" This reverts commit 4eece154d056ba33689a5584c86c8fc352bb7cdd. --- .../docs/proxy/guardrails/grayswan.md | 197 +++++++++++------- .../guardrail_hooks/grayswan/grayswan.py | 42 +++- .../guardrail_hooks/test_grayswan.py | 124 +++++++++++ 3 files changed, 278 insertions(+), 85 deletions(-) diff --git a/docs/my-website/docs/proxy/guardrails/grayswan.md b/docs/my-website/docs/proxy/guardrails/grayswan.md index d6efaf15504..6c0ccbc293d 100644 --- a/docs/my-website/docs/proxy/guardrails/grayswan.md +++ b/docs/my-website/docs/proxy/guardrails/grayswan.md @@ -13,20 +13,26 @@ Cygnal returns a `violation` score between `0` and `1` (higher means more likely ### 1. Obtain Credentials -1. Create a Gray Swan account and generate a Cygnal API key. +1. Log in to our Gray Swan platform and generate a Cygnal API key. + + For existing customers, you should already have access to our [platform](https://platform.grayswan.ai). + + For new users, please register at this [page](https://hubs.ly/Q03-sX1J0) and we are more than happy to give you an onboarding! + + 2. Configure environment variables for the LiteLLM proxy host: -```bash -export GRAYSWAN_API_KEY="your-grayswan-key" -export GRAYSWAN_API_BASE="https://api.grayswan.ai" -``` + ```bash + export GRAYSWAN_API_KEY="your-grayswan-key" + export GRAYSWAN_API_BASE="https://api.grayswan.ai" + ``` ### 2. Configure `config.yaml` -Add a guardrail entry that references the Gray Swan integration. Below is a balanced example that monitors both input and output but only blocks once the violation score reaches the configured threshold. +Add a guardrail entry that references the Gray Swan integration. Below is our recommmended settings. ```yaml -model_list: +model_list: # this part is a standard litellm configuration for reference - model_name: openai/gpt-4.1-mini litellm_params: model: openai/gpt-4.1-mini @@ -40,13 +46,14 @@ guardrails: api_key: os.environ/GRAYSWAN_API_KEY api_base: os.environ/GRAYSWAN_API_BASE # optional optional_params: - on_flagged_action: monitor # or "block" + on_flagged_action: passthrough # or "block" or "monitor" violation_threshold: 0.5 # score >= threshold is flagged reasoning_mode: hybrid # off | hybrid | thinking - categories: - safety: "Detect jailbreaks and policy violations" - policy_id: "your-cygnal-policy-id" + policy_id: "your-cygnal-policy-id" # Optional: Your Cygnal policy ID. Defaults to a content safety policy if empty. + streaming_end_of_stream_only: true # For streaming API, only send the assembled message to Cygnal (post_call only). Defaults to false. default_on: true + guardrail_timeout: 30 # Defaults to 30 seconds. Change accordingly. + fail_open: true # Defaults to true; set to false to propagate guardrail errors. general_settings: master_key: "your-litellm-master-key" @@ -65,13 +72,13 @@ litellm --config config.yaml --port 4000 ## Choosing Guardrail Modes -Gray Swan can run during `pre_call`, `during_call`, and `post_call` stages. Combine modes based on your latency and coverage requirements. +Gray Swan can run during `pre_call`, `during_call`, and `post_call` stages. Combine modes based on your latency and coverage requirements. | Mode | When it Runs | Protects | Typical Use Case | |--------------|-------------------|-----------------------|------------------| | `pre_call` | Before LLM call | User input only | Block prompt injection before it reaches the model | | `during_call`| Parallel to call | User input only | Low-latency monitoring without blocking | -| `post_call` | After response | Full conversation | Scan output for policy violations, leaked secrets, or IPI | +| `post_call` | After response | Model Outputs | Scan output for policy violations, leaked secrets, or IPI | When using `during_call` with `on_flagged_action: block` or `on_flagged_action: passthrough`: @@ -81,87 +88,110 @@ When using `during_call` with `on_flagged_action: block` or `on_flagged_action: - The guardrail exception prevents the response from reaching the user, but **does not cancel the running LLM task** - This means you pay full LLM costs while returning an error/passthrough message to the user -**Recommendation:** For cost-sensitive applications, use `pre_call` and `post_call` instead of `during_call` for blocking or passthrough modes. Reserve `during_call` for `monitor` mode where you want low-latency logging without impacting the user experience. +**Recommendation:** Use `pre_call` and `post_call` instead of `during_call` for `passthrough` (or `block`) `on_flagged_action` (see our recommended configuration above). Reserve `during_call` for `monitor` mode ONLY when you want low-latency logging without impacting the user experience. - - +--- -```yaml -guardrails: - - guardrail_name: "cygnal-monitor-only" - litellm_params: - guardrail: grayswan - mode: "during_call" - api_key: os.environ/GRAYSWAN_API_KEY - optional_params: - on_flagged_action: monitor - violation_threshold: 0.6 - default_on: true +## Work with Claude Code + +Follow the official litellm [guide](https://docs.litellm.ai/docs/tutorials/claude_responses_api) on setting up Claude Code with litellm, with the guardrail part mentioned above added to your litellm configuration. Cygnal natively supports coding agent policies defense. Define your own policy or use the provided coding policies on the platform. The example config we show above is also the recommended setup for Claude Code (with the `policy_id` replaced with an appropriate one). + +--- + +## Per-request overrides via `extra_body` + +You can override parts of the Gray Swan guardrail configuration on a per-request basis by passing `litellm_metadata.guardrails[*].grayswan.extra_body`. + +`extra_body` is merged into the Cygnal request body and takes precedence over specific fields from `config.yaml`, which are `policy_id`, `violation_threshold`, and `reasoning_mode`. + +If you include a `metadata` field inside `extra_body`, it is forwarded to the Cygnal API as-is under the request body's `metadata` field. + +Example: + +```bash +curl -X POST "http://0.0.0.0:4000/v1/messages?beta=true" \ + -H "Authorization: Bearer token" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "openrouter/anthropic/claude-sonnet-4.5", + "messages": [{"role": "user", "content": "hello"}], + "litellm_metadata": { + "guardrails": [ + { + "cygnal-monitor": { + "extra_body": { + "policy_id": "specific policy id you want to use", + "metadata": { + "user": "health-check" + } + } + } + } + ] + } + }' ``` -Best for visibility without blocking. Alerts are logged via LiteLLM’s standard logging callbacks. +OpenAI client: - - +```python +from openai import OpenAI -```yaml -guardrails: - - guardrail_name: "cygnal-block-input" - litellm_params: - guardrail: grayswan - mode: "pre_call" - api_key: os.environ/GRAYSWAN_API_KEY - optional_params: - on_flagged_action: block - violation_threshold: 0.4 - categories: - pii: "Detect sensitive data" - default_on: true +client = OpenAI(api_key="anything", base_url="http://0.0.0.0:4000") + +resp = client.responses.create( + model="openrouter/anthropic/claude-sonnet-4.5", + input="hello", + extra_body={ + "litellm_metadata": { + "guardrails": [ + { + "cygnal-monitor": { + "extra_body": { + "policy_id": "69038214e5cdb6befc5e991e", + "metadata": {"trace_id": "trace-123"}, + } + } + } + ] + } + }, +) ``` -Stops malicious or sensitive prompts before any tokens are generated. +Anthropic client: - - +```python +from anthropic import Anthropic -```yaml -guardrails: - - guardrail_name: "cygnal-full-coverage" - litellm_params: - guardrail: grayswan - mode: [pre_call, post_call] - api_key: os.environ/GRAYSWAN_API_KEY - optional_params: - on_flagged_action: block - violation_threshold: 0.5 - reasoning_mode: thinking - policy_id: "policy-id-from-grayswan" - default_on: true +client = Anthropic(api_key="anything", base_url="http://0.0.0.0:4000") + +resp = client.messages.create( + model="openrouter/anthropic/claude-sonnet-4.5", + max_tokens=256, + messages=[{"role": "user", "content": "hello"}], + extra_body={ + "litellm_metadata": { + "guardrails": [ + { + "cygnal-monitor": { + "extra_body": { + "policy_id": "69038214e5cdb6befc5e991e", + "metadata": {"trace_id": "trace-123"}, + } + } + } + ] + } + }, +) ``` -Provides the strongest enforcement by inspecting both prompts and responses. +Notes: - - - -```yaml -guardrails: - - guardrail_name: "cygnal-passthrough" - litellm_params: - guardrail: grayswan - mode: [pre_call, post_call] - api_key: os.environ/GRAYSWAN_API_KEY - optional_params: - on_flagged_action: passthrough - violation_threshold: 0.5 - default_on: true -``` - -Allows requests to proceed without raising a 400 error when content is flagged. Instead of blocking, the model response content is replaced with a detailed violation message including violation score, violated rules, and detection flags (mutation, IPI). **Supported Response Formats:** OpenAI chat/text completions, Anthropic Messages API. Other response types (embeddings, images, etc.) will log a warning and return unchanged. - - - +- The guardrail name (for example, `cygnal-monitor`) must match the `guardrail_name` in `config.yaml`. +- Per-request guardrail overrides may require a premium license, depending on your proxy settings. --- @@ -170,9 +200,14 @@ Allows requests to proceed without raising a 400 error when content is flagged. | Parameter | Type | Description | |---------------------------------------|-----------------|-------------| | `api_key` | string | Gray Swan Cygnal API key. Reads from `GRAYSWAN_API_KEY` if omitted. | +| `api_base` | string | Override for the Gray Swan API base URL. Defaults to `https://api.grayswan.ai` or `GRAYSWAN_API_BASE`. | | `mode` | string or list | Guardrail stages (`pre_call`, `during_call`, `post_call`). | | `optional_params.on_flagged_action` | string | `monitor` (log only), `block` (raise `HTTPException`), or `passthrough` (replace response content with violation message, no 400 error). | -| `.optional_params.violation_threshold`| number (0-1) | Scores at or above this value are considered violations. | +| `optional_params.violation_threshold` | number (0-1) | Scores at or above this value are considered violations. | | `optional_params.reasoning_mode` | string | `off`, `hybrid`, or `thinking`. Enables Cygnal's reasoning capabilities. | | `optional_params.categories` | object | Map of custom category names to descriptions. | | `optional_params.policy_id` | string | Gray Swan policy identifier. | +| `guardrail_timeout` | number | Timeout in seconds for the Cygnal request. Defaults to 30. | +| `fail_open` | boolean | If true, errors contacting Cygnal are logged and the request proceeds; if false, errors propagate. Defaults to treu. | +| `streaming_end_of_stream_only` | boolean | For streaming `post_call`, only send the final assembled response to Cygnal. Defaults to false. | +| `default_on` | boolean | Run the guardrail on every request by default. | diff --git a/litellm/proxy/guardrails/guardrail_hooks/grayswan/grayswan.py b/litellm/proxy/guardrails/guardrail_hooks/grayswan/grayswan.py index 2a852cbda08..90f689ed23c 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/grayswan/grayswan.py +++ b/litellm/proxy/guardrails/guardrail_hooks/grayswan/grayswan.py @@ -9,8 +9,10 @@ from fastapi import HTTPException from litellm._logging import verbose_proxy_logger from litellm.integrations.custom_guardrail import ( CustomGuardrail, + ModifyResponseException ) from litellm.litellm_core_utils.safe_json_dumps import safe_dumps +from litellm.litellm_core_utils.safe_json_loads import safe_json_loads from litellm.llms.custom_httpx.http_handler import ( get_async_httpx_client, httpxSpecialProvider, @@ -21,6 +23,8 @@ from litellm.types.utils import GenericGuardrailAPIInputs if TYPE_CHECKING: from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj +GRAYSWAN_BLOCK_ERROR_MSG = "Blocked by Gray Swan Guardrail" + class GraySwanGuardrailMissingSecrets(Exception): """Raised when the Gray Swan API key is missing.""" @@ -205,9 +209,13 @@ class GraySwanGuardrail(CustomGuardrail): # Get dynamic params from request metadata dynamic_body = self.get_guardrail_dynamic_request_body_params(request_data) or {} + if dynamic_body: + verbose_proxy_logger.debug( + "Gray Swan Guardrail: dynamic extra_body=%s", safe_dumps(dynamic_body) + ) # Prepare and send payload - payload = self._prepare_payload(messages, dynamic_body) + payload = self._prepare_payload(messages, dynamic_body, request_data) if payload is None: return inputs @@ -223,6 +231,8 @@ class GraySwanGuardrail(CustomGuardrail): ) return result except Exception as exc: + if self._is_grayswan_exception(exc): + raise end_time = time.time() status_code = getattr(exc, "status_code", None) or getattr( exc, "exception_status_code", None @@ -240,8 +250,20 @@ class GraySwanGuardrail(CustomGuardrail): exc, ) return inputs + if isinstance(exc, GraySwanGuardrailAPIError): + raise exc raise GraySwanGuardrailAPIError(str(exc), status_code=status_code) from exc + def _is_grayswan_exception(self, exc: Exception) -> bool: + # Guardrail decision (passthrough) should always propagate, + # regardless of fail_open. + if isinstance(exc, ModifyResponseException): + return True + detail = getattr(exc, "detail", None) + if isinstance(detail, dict): + return detail.get("error") == GRAYSWAN_BLOCK_ERROR_MSG + return False + # ------------------------------------------------------------------ # Legacy Test Interface (for backward compatibility) # ------------------------------------------------------------------ @@ -324,7 +346,7 @@ class GraySwanGuardrail(CustomGuardrail): raise HTTPException( status_code=400, detail={ - "error": "Blocked by Gray Swan Guardrail", + "error": GRAYSWAN_BLOCK_ERROR_MSG, "violation_location": violation_location, "violation": violation_score, "violated_rules": violated_rules, @@ -445,7 +467,7 @@ class GraySwanGuardrail(CustomGuardrail): raise HTTPException( status_code=400, detail={ - "error": "Blocked by Gray Swan Guardrail", + "error": GRAYSWAN_BLOCK_ERROR_MSG, "violation_location": violation_location, "violation": violation_score, "violated_rules": violated_rules, @@ -494,7 +516,7 @@ class GraySwanGuardrail(CustomGuardrail): } def _prepare_payload( - self, messages: List[Dict[str, str]], dynamic_body: dict + self, messages: List[Dict[str, str]], dynamic_body: dict, request_data: dict ) -> Optional[Dict[str, Any]]: payload: Dict[str, Any] = {"messages": messages} @@ -510,6 +532,18 @@ class GraySwanGuardrail(CustomGuardrail): if reasoning_mode: payload["reasoning_mode"] = reasoning_mode + # Pass through arbitrary metadata when provided via dynamic extra_body. + if "metadata" in dynamic_body: + payload["metadata"] = dynamic_body["metadata"] + + litellm_metadata = request_data.get("litellm_metadata") + if isinstance(litellm_metadata, dict) and litellm_metadata: + cleaned_litellm_metadata = dict(litellm_metadata) + # cleaned_litellm_metadata.pop("user_api_key_auth", None) + sanitized = safe_json_loads(safe_dumps(cleaned_litellm_metadata), default={}) + if isinstance(sanitized, dict) and sanitized: + payload["litellm_metadata"] = sanitized + return payload def _format_violation_message( diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_grayswan.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_grayswan.py index 6dc658827bc..2b00a099328 100644 --- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_grayswan.py +++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_grayswan.py @@ -55,6 +55,17 @@ def test_prepare_payload_falls_back_to_guardrail_defaults( assert payload["reasoning_mode"] == "hybrid" +def test_prepare_payload_includes_dynamic_metadata( + grayswan_guardrail: GraySwanGuardrail, +) -> None: + messages = [{"role": "user", "content": "hello"}] + dynamic_body = {"metadata": {"trace_id": "trace-123", "tags": ["a", "b"]}} + + payload = grayswan_guardrail._prepare_payload(messages, dynamic_body) + + assert payload["metadata"] == dynamic_body["metadata"] + + def test_process_response_does_not_block_under_threshold( grayswan_guardrail: GraySwanGuardrail, ) -> None: @@ -160,6 +171,119 @@ async def test_run_guardrail_raises_api_error( await grayswan_guardrail.run_grayswan_guardrail(payload) +@pytest.mark.asyncio +async def test_apply_guardrail_passthrough_not_swallowed_by_fail_open( + monkeypatch, +) -> None: + guardrail = GraySwanGuardrail( + guardrail_name="grayswan-passthrough", + api_key="test-key", + on_flagged_action="passthrough", + violation_threshold=0.2, + fail_open=True, + event_hook=GuardrailEventHooks.pre_call, + ) + + async def _fake_call(_payload: dict): + return {"violation": 0.92, "violated_rule_descriptions": []} + + monkeypatch.setattr(guardrail, "_call_grayswan_api", _fake_call) + + with pytest.raises(ModifyResponseException): + await guardrail.apply_guardrail( + inputs={"texts": ["bad"]}, + request_data={"model": "gpt-4"}, + input_type="request", + ) + + +@pytest.mark.asyncio +async def test_apply_guardrail_block_not_swallowed_by_fail_open( + monkeypatch, +) -> None: + guardrail = GraySwanGuardrail( + guardrail_name="grayswan-block", + api_key="test-key", + on_flagged_action="block", + violation_threshold=0.2, + fail_open=True, + event_hook=GuardrailEventHooks.pre_call, + ) + + async def _fake_call(_payload: dict): + return {"violation": 0.92, "violated_rule_descriptions": []} + + monkeypatch.setattr(guardrail, "_call_grayswan_api", _fake_call) + + with pytest.raises(HTTPException): + await guardrail.apply_guardrail( + inputs={"texts": ["bad"]}, + request_data={"model": "gpt-4"}, + input_type="request", + ) + + +@pytest.mark.asyncio +async def test_apply_guardrail_non_grayswan_http_exception_fail_open_true( + monkeypatch, +) -> None: + guardrail = GraySwanGuardrail( + guardrail_name="grayswan-error", + api_key="test-key", + on_flagged_action="monitor", + violation_threshold=0.2, + fail_open=True, + event_hook=GuardrailEventHooks.pre_call, + ) + + async def _fake_call(_payload: dict): + return {"violation": 0.0, "violated_rule_descriptions": []} + + def _fake_process(**_kwargs): + raise HTTPException(status_code=500, detail={"error": "upstream failed"}) + + monkeypatch.setattr(guardrail, "_call_grayswan_api", _fake_call) + monkeypatch.setattr(guardrail, "_process_response_internal", _fake_process) + + result = await guardrail.apply_guardrail( + inputs={"texts": ["ok"]}, + request_data={"model": "gpt-4"}, + input_type="request", + ) + + assert result["texts"] == ["ok"] + + +@pytest.mark.asyncio +async def test_apply_guardrail_non_grayswan_http_exception_fail_open_false( + monkeypatch, +) -> None: + guardrail = GraySwanGuardrail( + guardrail_name="grayswan-error", + api_key="test-key", + on_flagged_action="monitor", + violation_threshold=0.2, + fail_open=False, + event_hook=GuardrailEventHooks.pre_call, + ) + + async def _fake_call(_payload: dict): + return {"violation": 0.0, "violated_rule_descriptions": []} + + def _fake_process(**_kwargs): + raise HTTPException(status_code=500, detail={"error": "upstream failed"}) + + monkeypatch.setattr(guardrail, "_call_grayswan_api", _fake_call) + monkeypatch.setattr(guardrail, "_process_response_internal", _fake_process) + + with pytest.raises(GraySwanGuardrailAPIError): + await guardrail.apply_guardrail( + inputs={"texts": ["ok"]}, + request_data={"model": "gpt-4"}, + input_type="request", + ) + + def test_process_response_passthrough_raises_exception_in_pre_call() -> None: """Test that passthrough mode raises ModifyResponseException in pre_call hook.""" guardrail = GraySwanGuardrail( From d267c690860f083ddcd763d2ea782f375683fb08 Mon Sep 17 00:00:00 2001 From: Ishaan Jaff Date: Tue, 3 Feb 2026 15:25:38 -0800 Subject: [PATCH 052/511] [Feat] Use A2A registered agents with /chat/completions (#20362) * test_a2a_registry_integration * fix: render agents on model dropdown on UI * init append_agents_to_model_group * route_a2a_agent_request * is_a2a_agent_model * route_a2a_agent_request * fix: error handling * docs A2A usage * docs fix * feat: working A2a streaming * fix transform --- docs/my-website/docs/a2a.md | 113 +------ docs/my-website/docs/a2a_invoking_agents.md | 280 ++++++++++++++++++ docs/my-website/sidebars.js | 1 + litellm/llms/a2a/chat/streaming_iterator.py | 2 +- litellm/llms/a2a/chat/transformation.py | 79 ++++- litellm/llms/a2a/common_utils.py | 20 +- litellm/main.py | 22 +- litellm/proxy/agent_endpoints/a2a_routing.py | 53 ++++ .../agent_endpoints/model_list_helpers.py | 96 ++++++ litellm/proxy/proxy_server.py | 19 ++ litellm/proxy/route_llm_request.py | 11 + .../test_model_list_helpers.py | 110 +++++++ .../proxy/test_route_a2a_models.py | 105 +++++++ .../test_litellm/test_a2a_registry_lookup.py | 73 +++++ 14 files changed, 860 insertions(+), 124 deletions(-) create mode 100644 docs/my-website/docs/a2a_invoking_agents.md create mode 100644 litellm/proxy/agent_endpoints/a2a_routing.py create mode 100644 litellm/proxy/agent_endpoints/model_list_helpers.py create mode 100644 tests/test_litellm/proxy/agent_endpoints/test_model_list_helpers.py create mode 100644 tests/test_litellm/proxy/test_route_a2a_models.py create mode 100644 tests/test_litellm/test_a2a_registry_lookup.py diff --git a/docs/my-website/docs/a2a.md b/docs/my-website/docs/a2a.md index a7e8b52d99a..b1166a7809c 100644 --- a/docs/my-website/docs/a2a.md +++ b/docs/my-website/docs/a2a.md @@ -68,116 +68,9 @@ Follow [this guide, to add your pydantic ai agent to LiteLLM Agent Gateway](./pr ## Invoking your Agents -Use the [A2A Python SDK](https://pypi.org/project/a2a-sdk) to invoke agents through LiteLLM. - -This example shows how to: -1. **List available agents** - Query `/v1/agents` to see which agents your key can access -2. **Select an agent** - Pick an agent from the list -3. **Invoke via A2A** - Use the A2A protocol to send messages to the agent - -```python showLineNumbers title="invoke_a2a_agent.py" -from uuid import uuid4 -import httpx -import asyncio -from a2a.client import A2ACardResolver, A2AClient -from a2a.types import MessageSendParams, SendMessageRequest - -# === CONFIGURE THESE === -LITELLM_BASE_URL = "http://localhost:4000" # Your LiteLLM proxy URL -LITELLM_VIRTUAL_KEY = "sk-1234" # Your LiteLLM Virtual Key -# ======================= - -async def main(): - headers = {"Authorization": f"Bearer {LITELLM_VIRTUAL_KEY}"} - - async with httpx.AsyncClient(headers=headers) as client: - # Step 1: List available agents - response = await client.get(f"{LITELLM_BASE_URL}/v1/agents") - agents = response.json() - - print("Available agents:") - for agent in agents: - print(f" - {agent['agent_name']} (ID: {agent['agent_id']})") - - if not agents: - print("No agents available for this key") - return - - # Step 2: Select an agent and invoke it - selected_agent = agents[0] - agent_id = selected_agent["agent_id"] - agent_name = selected_agent["agent_name"] - print(f"\nInvoking: {agent_name}") - - # Step 3: Use A2A protocol to invoke the agent - base_url = f"{LITELLM_BASE_URL}/a2a/{agent_id}" - resolver = A2ACardResolver(httpx_client=client, base_url=base_url) - agent_card = await resolver.get_agent_card() - a2a_client = A2AClient(httpx_client=client, agent_card=agent_card) - - request = SendMessageRequest( - id=str(uuid4()), - params=MessageSendParams( - message={ - "role": "user", - "parts": [{"kind": "text", "text": "Hello, what can you do?"}], - "messageId": uuid4().hex, - } - ), - ) - response = await a2a_client.send_message(request) - print(f"Response: {response.model_dump(mode='json', exclude_none=True, indent=4)}") - -if __name__ == "__main__": - asyncio.run(main()) -``` - -### Streaming Responses - -For streaming responses, use `send_message_streaming`: - -```python showLineNumbers title="invoke_a2a_agent_streaming.py" -from uuid import uuid4 -import httpx -import asyncio -from a2a.client import A2ACardResolver, A2AClient -from a2a.types import MessageSendParams, SendStreamingMessageRequest - -# === CONFIGURE THESE === -LITELLM_BASE_URL = "http://localhost:4000" # Your LiteLLM proxy URL -LITELLM_VIRTUAL_KEY = "sk-1234" # Your LiteLLM Virtual Key -LITELLM_AGENT_NAME = "ij-local" # Agent name registered in LiteLLM -# ======================= - -async def main(): - base_url = f"{LITELLM_BASE_URL}/a2a/{LITELLM_AGENT_NAME}" - headers = {"Authorization": f"Bearer {LITELLM_VIRTUAL_KEY}"} - - async with httpx.AsyncClient(headers=headers) as httpx_client: - # Resolve agent card and create client - resolver = A2ACardResolver(httpx_client=httpx_client, base_url=base_url) - agent_card = await resolver.get_agent_card() - client = A2AClient(httpx_client=httpx_client, agent_card=agent_card) - - # Send a streaming message - request = SendStreamingMessageRequest( - id=str(uuid4()), - params=MessageSendParams( - message={ - "role": "user", - "parts": [{"kind": "text", "text": "Hello, what can you do?"}], - "messageId": uuid4().hex, - } - ), - ) - - # Stream the response - async for chunk in client.send_message_streaming(request): - print(chunk.model_dump(mode="json", exclude_none=True)) - -if __name__ == "__main__": - asyncio.run(main()) -``` +See the [Invoking A2A Agents](./a2a_invoking_agents) guide to learn how to call your agents using: +- **A2A SDK** - Native A2A protocol with full support for tasks and artifacts +- **OpenAI SDK** - Familiar `/chat/completions` interface with `a2a/` model prefix ## Tracking Agent Logs diff --git a/docs/my-website/docs/a2a_invoking_agents.md b/docs/my-website/docs/a2a_invoking_agents.md new file mode 100644 index 00000000000..3bb248e4561 --- /dev/null +++ b/docs/my-website/docs/a2a_invoking_agents.md @@ -0,0 +1,280 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Invoking A2A Agents + +Learn how to invoke A2A agents through LiteLLM using different methods. + +:::tip Deploy Your Own A2A Agent + +Want to test with your own agent? Deploy this template A2A agent powered by Google Gemini: + +[**shin-bot-litellm/a2a-gemini-agent**](https://github.com/shin-bot-litellm/a2a-gemini-agent) - Simple deployable A2A agent with streaming support + +::: + +## A2A SDK + +Use the [A2A Python SDK](https://pypi.org/project/a2a-sdk) to invoke agents through LiteLLM using the A2A protocol. + +### Non-Streaming + +This example shows how to: +1. **List available agents** - Query `/v1/agents` to see which agents your key can access +2. **Select an agent** - Pick an agent from the list +3. **Invoke via A2A** - Use the A2A protocol to send messages to the agent + +```python showLineNumbers title="invoke_a2a_agent.py" +from uuid import uuid4 +import httpx +import asyncio +from a2a.client import A2ACardResolver, A2AClient +from a2a.types import MessageSendParams, SendMessageRequest + +# === CONFIGURE THESE === +LITELLM_BASE_URL = "http://localhost:4000" # Your LiteLLM proxy URL +LITELLM_VIRTUAL_KEY = "sk-1234" # Your LiteLLM Virtual Key +# ======================= + +async def main(): + headers = {"Authorization": f"Bearer {LITELLM_VIRTUAL_KEY}"} + + async with httpx.AsyncClient(headers=headers) as client: + # Step 1: List available agents + response = await client.get(f"{LITELLM_BASE_URL}/v1/agents") + agents = response.json() + + print("Available agents:") + for agent in agents: + print(f" - {agent['agent_name']} (ID: {agent['agent_id']})") + + if not agents: + print("No agents available for this key") + return + + # Step 2: Select an agent and invoke it + selected_agent = agents[0] + agent_id = selected_agent["agent_id"] + agent_name = selected_agent["agent_name"] + print(f"\nInvoking: {agent_name}") + + # Step 3: Use A2A protocol to invoke the agent + base_url = f"{LITELLM_BASE_URL}/a2a/{agent_id}" + resolver = A2ACardResolver(httpx_client=client, base_url=base_url) + agent_card = await resolver.get_agent_card() + a2a_client = A2AClient(httpx_client=client, agent_card=agent_card) + + request = SendMessageRequest( + id=str(uuid4()), + params=MessageSendParams( + message={ + "role": "user", + "parts": [{"kind": "text", "text": "Hello, what can you do?"}], + "messageId": uuid4().hex, + } + ), + ) + response = await a2a_client.send_message(request) + print(f"Response: {response.model_dump(mode='json', exclude_none=True, indent=4)}") + +if __name__ == "__main__": + asyncio.run(main()) +``` + +### Streaming + +For streaming responses, use `send_message_streaming`: + +```python showLineNumbers title="invoke_a2a_agent_streaming.py" +from uuid import uuid4 +import httpx +import asyncio +from a2a.client import A2ACardResolver, A2AClient +from a2a.types import MessageSendParams, SendStreamingMessageRequest + +# === CONFIGURE THESE === +LITELLM_BASE_URL = "http://localhost:4000" # Your LiteLLM proxy URL +LITELLM_VIRTUAL_KEY = "sk-1234" # Your LiteLLM Virtual Key +LITELLM_AGENT_NAME = "ij-local" # Agent name registered in LiteLLM +# ======================= + +async def main(): + base_url = f"{LITELLM_BASE_URL}/a2a/{LITELLM_AGENT_NAME}" + headers = {"Authorization": f"Bearer {LITELLM_VIRTUAL_KEY}"} + + async with httpx.AsyncClient(headers=headers) as httpx_client: + # Resolve agent card and create client + resolver = A2ACardResolver(httpx_client=httpx_client, base_url=base_url) + agent_card = await resolver.get_agent_card() + client = A2AClient(httpx_client=httpx_client, agent_card=agent_card) + + # Send a streaming message + request = SendStreamingMessageRequest( + id=str(uuid4()), + params=MessageSendParams( + message={ + "role": "user", + "parts": [{"kind": "text", "text": "Tell me a long story"}], + "messageId": uuid4().hex, + } + ), + ) + + # Stream the response + async for chunk in client.send_message_streaming(request): + print(chunk.model_dump(mode="json", exclude_none=True)) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## /chat/completions API (OpenAI SDK) + +You can also invoke A2A agents using the familiar OpenAI SDK by using the `a2a/` model prefix. + +### Non-Streaming + + + + +```python showLineNumbers title="openai_non_streaming.py" +import openai + +client = openai.OpenAI( + api_key="sk-1234", # Your LiteLLM Virtual Key + base_url="http://localhost:4000" # Your LiteLLM proxy URL +) + +response = client.chat.completions.create( + model="a2a/my-agent", # Use a2a/ prefix with your agent name + messages=[ + {"role": "user", "content": "Hello, what can you do?"} + ] +) + +print(response.choices[0].message.content) +``` + + + + +```typescript showLineNumbers title="openai_non_streaming.ts" +import OpenAI from 'openai'; + +const client = new OpenAI({ + apiKey: 'sk-1234', // Your LiteLLM Virtual Key + baseURL: 'http://localhost:4000' // Your LiteLLM proxy URL +}); + +const response = await client.chat.completions.create({ + model: 'a2a/my-agent', // Use a2a/ prefix with your agent name + messages: [ + { role: 'user', content: 'Hello, what can you do?' } + ] +}); + +console.log(response.choices[0].message.content); +``` + + + + +```bash showLineNumbers title="curl_non_streaming.sh" +curl -X POST http://localhost:4000/v1/chat/completions \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "a2a/my-agent", + "messages": [ + {"role": "user", "content": "Hello, what can you do?"} + ] + }' +``` + + + + +### Streaming + + + + +```python showLineNumbers title="openai_streaming.py" +import openai + +client = openai.OpenAI( + api_key="sk-1234", # Your LiteLLM Virtual Key + base_url="http://localhost:4000" # Your LiteLLM proxy URL +) + +stream = client.chat.completions.create( + model="a2a/my-agent", # Use a2a/ prefix with your agent name + messages=[ + {"role": "user", "content": "Tell me a long story"} + ], + stream=True +) + +for chunk in stream: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="", flush=True) +``` + + + + +```typescript showLineNumbers title="openai_streaming.ts" +import OpenAI from 'openai'; + +const client = new OpenAI({ + apiKey: 'sk-1234', // Your LiteLLM Virtual Key + baseURL: 'http://localhost:4000' // Your LiteLLM proxy URL +}); + +const stream = await client.chat.completions.create({ + model: 'a2a/my-agent', // Use a2a/ prefix with your agent name + messages: [ + { role: 'user', content: 'Tell me a long story' } + ], + stream: true +}); + +for await (const chunk of stream) { + const content = chunk.choices[0]?.delta?.content; + if (content) { + process.stdout.write(content); + } +} +``` + + + + +```bash showLineNumbers title="curl_streaming.sh" +curl -X POST http://localhost:4000/v1/chat/completions \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "a2a/my-agent", + "messages": [ + {"role": "user", "content": "Tell me a long story"} + ], + "stream": true + }' +``` + + + + +## Key Differences + +| Method | Use Case | Advantages | +|--------|----------|------------| +| **A2A SDK** | Native A2A protocol integration | • Full A2A protocol support
• Access to task states and artifacts
• Context management | +| **OpenAI SDK** | Familiar OpenAI-style interface | • Drop-in replacement for OpenAI calls
• Easier migration from LLM to agent workflows
• Works with existing OpenAI tooling | + +:::tip Model Prefix + +When using the OpenAI SDK, always prefix your agent name with `a2a/` (e.g., `a2a/my-agent`) to route requests to the A2A agent instead of an LLM provider. + +::: diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index d932b6af250..98c8ee6eaa1 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -469,6 +469,7 @@ const sidebars = { label: "/a2a - A2A Agent Gateway", items: [ "a2a", + "a2a_invoking_agents", "a2a_cost_tracking", "a2a_agent_permissions" ], diff --git a/litellm/llms/a2a/chat/streaming_iterator.py b/litellm/llms/a2a/chat/streaming_iterator.py index 84b6fffaa31..4b689414ddd 100644 --- a/litellm/llms/a2a/chat/streaming_iterator.py +++ b/litellm/llms/a2a/chat/streaming_iterator.py @@ -94,7 +94,7 @@ class A2AModelResponseIterator(BaseModelResponseIterator): if state == "completed": return "stop" elif state == "failed": - return "error" + return "stop" # Map failed state to 'stop' (valid finish_reason) # Check for [DONE] marker if chunk.get("done") is True: diff --git a/litellm/llms/a2a/chat/transformation.py b/litellm/llms/a2a/chat/transformation.py index 243fba63719..163cd5ab22e 100644 --- a/litellm/llms/a2a/chat/transformation.py +++ b/litellm/llms/a2a/chat/transformation.py @@ -2,10 +2,9 @@ A2A Protocol Transformation for LiteLLM """ import uuid -from typing import Any, Dict, Iterator, List, Optional, Union, cast +from typing import Any, Dict, Iterator, List, Optional, Union import httpx -from pydantic import BaseModel from litellm.llms.base_llm.base_model_iterator import BaseModelResponseIterator from litellm.llms.base_llm.chat.transformation import BaseConfig, BaseLLMException @@ -27,6 +26,68 @@ class A2AConfig(BaseConfig): Handles transformation between OpenAI and A2A JSON-RPC 2.0 formats. """ + @staticmethod + def resolve_agent_config_from_registry( + model: str, + api_base: Optional[str], + api_key: Optional[str], + headers: Optional[Dict[str, Any]], + optional_params: Dict[str, Any], + ) -> tuple[Optional[str], Optional[str], Optional[Dict[str, Any]]]: + """ + Resolve agent configuration from registry if model format is "a2a/". + + Extracts agent name from model string and looks up configuration in the + agent registry (if available in proxy context). + + Args: + model: Model string (e.g., "a2a/my-agent") + api_base: Explicit api_base (takes precedence over registry) + api_key: Explicit api_key (takes precedence over registry) + headers: Explicit headers (takes precedence over registry) + optional_params: Dict to merge additional litellm_params into + + Returns: + Tuple of (api_base, api_key, headers) with registry values filled in + """ + # Extract agent name from model (e.g., "a2a/my-agent" -> "my-agent") + agent_name = model.split("/", 1)[1] if "/" in model else None + + # Only lookup if agent name exists and some config is missing + if not agent_name or (api_base is not None and api_key is not None and headers is not None): + return api_base, api_key, headers + + # Try registry lookup (only available in proxy context) + try: + from litellm.proxy.agent_endpoints.agent_registry import ( + global_agent_registry, + ) + + agent = global_agent_registry.get_agent_by_name(agent_name) + if agent: + # Get api_base from agent card URL + if api_base is None and agent.agent_card_params: + api_base = agent.agent_card_params.get("url") + + # Get api_key, headers, and other params from litellm_params + if agent.litellm_params: + if api_key is None: + api_key = agent.litellm_params.get("api_key") + + if headers is None: + agent_headers = agent.litellm_params.get("headers") + if agent_headers: + headers = agent_headers + + # Merge other litellm_params (timeout, max_retries, etc.) + for key, value in agent.litellm_params.items(): + if key not in ["api_key", "api_base", "headers", "model"] and key not in optional_params: + optional_params[key] = value + except ImportError: + pass # Registry not available (not running in proxy context) + + return api_base, api_key, headers + def get_supported_openai_params(self, model: str) -> List[str]: """Return list of supported OpenAI parameters""" return [ @@ -46,9 +107,14 @@ class A2AConfig(BaseConfig): """ Map OpenAI parameters to A2A parameters. - For A2A protocol, we don't need to map most parameters since - they're handled in the transform_request method. + For A2A protocol, we need to map the stream parameter so + transform_request can determine which JSON-RPC method to use. """ + # Map stream parameter + for param, value in non_default_params.items(): + if param == "stream" and value is True: + optional_params["stream"] = value + return optional_params def validate_environment( @@ -160,8 +226,9 @@ class A2AConfig(BaseConfig): # Build JSON-RPC 2.0 request # For A2A protocol, the method is "message/send" for non-streaming - # and "message/stream" for streaming (handled by optional_params["stream"]) - method = "message/stream" if optional_params.get("stream") else "message/send" + # and "message/stream" for streaming + stream = optional_params.get("stream", False) + method = "message/stream" if stream else "message/send" request_data = { "jsonrpc": "2.0", diff --git a/litellm/llms/a2a/common_utils.py b/litellm/llms/a2a/common_utils.py index 4c7da78b42f..116e1205409 100644 --- a/litellm/llms/a2a/common_utils.py +++ b/litellm/llms/a2a/common_utils.py @@ -113,6 +113,8 @@ def extract_text_from_a2a_response( # 1. Direct message: {"result": {"kind": "message", "parts": [...]}} # 2. Nested message: {"result": {"message": {"parts": [...]}}} # 3. Task with artifacts: {"result": {"kind": "task", "artifacts": [{"parts": [...]}]}} + # 4. Task with status message: {"result": {"kind": "task", "status": {"message": {"parts": [...]}}}} + # 5. Streaming artifact-update: {"result": {"kind": "artifact-update", "artifact": {"parts": [...]}}} # Check if result itself has parts (direct message) if "parts" in result: @@ -123,7 +125,23 @@ def extract_text_from_a2a_response( if message: return extract_text_from_a2a_message(message, depth=0, max_depth=max_depth) - # Handle task result with artifacts + # Check for streaming artifact-update (singular artifact) + artifact = result.get("artifact") + if artifact and isinstance(artifact, dict): + return extract_text_from_a2a_message( + artifact, depth=0, max_depth=max_depth + ) + + # Check for task status message (common in Gemini A2A agents) + status = result.get("status", {}) + if isinstance(status, dict): + status_message = status.get("message") + if status_message: + return extract_text_from_a2a_message( + status_message, depth=0, max_depth=max_depth + ) + + # Handle task result with artifacts (plural, array) artifacts = result.get("artifacts", []) if artifacts and len(artifacts) > 0: first_artifact = artifacts[0] diff --git a/litellm/main.py b/litellm/main.py index 60c889ab1d0..6d6bef81c26 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -2201,14 +2201,24 @@ def completion( # type: ignore # noqa: PLR0915 ) elif custom_llm_provider == "a2a": # A2A (Agent-to-Agent) Protocol - api_base = ( - api_base - or litellm.api_base - or get_secret_str("A2A_API_BASE") + # Resolve agent configuration from registry if model format is "a2a/" + api_base, api_key, headers = litellm.A2AConfig.resolve_agent_config_from_registry( + model=model, + api_base=api_base, + api_key=api_key, + headers=headers, + optional_params=optional_params, ) - + + # Fall back to environment variables and defaults + api_base = api_base or litellm.api_base or get_secret_str("A2A_API_BASE") + if api_base is None: - raise Exception("api_base is required for A2A provider") + raise Exception( + "api_base is required for A2A provider. " + "Either provide api_base parameter, set A2A_API_BASE environment variable, " + "or register the agent in the proxy with model='a2a/'." + ) headers = headers or litellm.headers diff --git a/litellm/proxy/agent_endpoints/a2a_routing.py b/litellm/proxy/agent_endpoints/a2a_routing.py new file mode 100644 index 00000000000..8e4c705df21 --- /dev/null +++ b/litellm/proxy/agent_endpoints/a2a_routing.py @@ -0,0 +1,53 @@ +""" +A2A Agent Routing + +Handles routing for A2A agents (models with "a2a/" prefix). +Looks up agents in the registry and injects their API base URL. +""" + +from typing import Any, Optional + +import litellm +from litellm._logging import verbose_proxy_logger + + +async def route_a2a_agent_request(data: dict, route_type: str) -> Optional[Any]: + """ + Route A2A agent requests directly to litellm with injected API base. + + Returns None if not an A2A request (allows normal routing to continue). + """ + # Import here to avoid circular imports + from litellm.proxy.agent_endpoints.agent_registry import global_agent_registry + from litellm.proxy.route_llm_request import ( + ROUTE_ENDPOINT_MAPPING, + ProxyModelNotFoundError, + ) + + model_name = data.get("model", "") + + # Check if this is an A2A agent request + if not isinstance(model_name, str) or not model_name.startswith("a2a/"): + return None + + # Extract agent name (e.g., "a2a/my-agent" -> "my-agent") + agent_name = model_name[4:] + + # Look up agent in registry + agent = global_agent_registry.get_agent_by_name(agent_name) + if agent is None: + verbose_proxy_logger.error(f"[A2A] Agent '{agent_name}' not found in registry") + route_name = ROUTE_ENDPOINT_MAPPING.get(route_type, route_type) + raise ProxyModelNotFoundError(route=route_name, model_name=model_name) + + # Get API base URL from agent config + if not agent.agent_card_params or "url" not in agent.agent_card_params: + verbose_proxy_logger.error(f"[A2A] Agent '{agent_name}' has no URL configured") + route_name = ROUTE_ENDPOINT_MAPPING.get(route_type, route_type) + raise ProxyModelNotFoundError(route=route_name, model_name=model_name) + + # Inject API base and route to litellm + data["api_base"] = agent.agent_card_params["url"] + verbose_proxy_logger.debug(f"[A2A] Routing {model_name} to {data['api_base']}") + + return getattr(litellm, f"{route_type}")(**data) diff --git a/litellm/proxy/agent_endpoints/model_list_helpers.py b/litellm/proxy/agent_endpoints/model_list_helpers.py new file mode 100644 index 00000000000..c640300bb8c --- /dev/null +++ b/litellm/proxy/agent_endpoints/model_list_helpers.py @@ -0,0 +1,96 @@ +""" +Helper functions for appending A2A agents to model lists. + +Used by proxy model endpoints to make agents appear in UI alongside models. +""" +from typing import List + +from litellm._logging import verbose_proxy_logger +from litellm.proxy._types import UserAPIKeyAuth +from litellm.types.proxy.management_endpoints.model_management_endpoints import ( + ModelGroupInfoProxy, +) + + +async def append_agents_to_model_group( + model_groups: List[ModelGroupInfoProxy], + user_api_key_dict: UserAPIKeyAuth, +) -> List[ModelGroupInfoProxy]: + """ + Append A2A agents to model groups list for UI display. + + Converts agents to model format with "a2a/" naming + so they appear in playground and work with LiteLLM routing. + """ + try: + from litellm.proxy.agent_endpoints.agent_registry import global_agent_registry + from litellm.proxy.agent_endpoints.auth.agent_permission_handler import ( + AgentRequestHandler, + ) + + allowed_agent_ids = await AgentRequestHandler.get_allowed_agents( + user_api_key_auth=user_api_key_dict + ) + + for agent_id in allowed_agent_ids: + agent = global_agent_registry.get_agent_by_id(agent_id) + if agent is not None: + model_groups.append( + ModelGroupInfoProxy( + model_group=f"a2a/{agent.agent_name}", + mode="chat", + providers=["a2a"], + ) + ) + except Exception as e: + verbose_proxy_logger.debug( + f"Error appending agents to model_group/info: {e}" + ) + + return model_groups + + +async def append_agents_to_model_info( + models: List[dict], + user_api_key_dict: UserAPIKeyAuth, +) -> List[dict]: + """ + Append A2A agents to model info list for UI display. + + Converts agents to model format with "a2a/" naming + so they appear in models page and work with LiteLLM routing. + """ + try: + from litellm.proxy.agent_endpoints.agent_registry import global_agent_registry + from litellm.proxy.agent_endpoints.auth.agent_permission_handler import ( + AgentRequestHandler, + ) + + allowed_agent_ids = await AgentRequestHandler.get_allowed_agents( + user_api_key_auth=user_api_key_dict + ) + + for agent_id in allowed_agent_ids: + agent = global_agent_registry.get_agent_by_id(agent_id) + if agent is not None: + models.append({ + "model_name": f"a2a/{agent.agent_name}", + "litellm_params": { + "model": f"a2a/{agent.agent_name}", + "custom_llm_provider": "a2a", + }, + "model_info": { + "id": agent.agent_id, + "mode": "chat", + "db_model": True, + "created_by": agent.created_by, + "created_at": agent.created_at, + "updated_at": agent.updated_at, + }, + }) + except Exception as e: + verbose_proxy_logger.debug( + f"Error appending agents to v2/model/info: {e}" + ) + + return models diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index 8f433bfa486..b06071481eb 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -239,6 +239,10 @@ from litellm.proxy._types import * from litellm.proxy.agent_endpoints.a2a_endpoints import router as a2a_router from litellm.proxy.agent_endpoints.agent_registry import global_agent_registry from litellm.proxy.agent_endpoints.endpoints import router as agent_endpoints_router +from litellm.proxy.agent_endpoints.model_list_helpers import ( + append_agents_to_model_group, + append_agents_to_model_info, +) from litellm.proxy.analytics_endpoints.analytics_endpoints import ( router as analytics_router, ) @@ -8616,6 +8620,15 @@ async def model_info_v2( ) verbose_proxy_logger.debug("all_models: %s", all_models) + + # Append A2A agents to models list + all_models = await append_agents_to_model_info( + models=all_models, + user_api_key_dict=user_api_key_dict, + ) + + # Update total count to include agents + search_total_count = len(all_models) return _paginate_models_response( all_models=all_models, @@ -9456,6 +9469,12 @@ async def model_group_info( model_groups: List[ModelGroupInfoProxy] = _get_model_group_info( llm_router=llm_router, all_models_str=all_models_str, model_group=model_group ) + + # Append A2A agents to model groups + model_groups = await append_agents_to_model_group( + model_groups=model_groups, + user_api_key_dict=user_api_key_dict, + ) return {"data": model_groups} diff --git a/litellm/proxy/route_llm_request.py b/litellm/proxy/route_llm_request.py index c6a93164d49..39ef5fdd1d5 100644 --- a/litellm/proxy/route_llm_request.py +++ b/litellm/proxy/route_llm_request.py @@ -12,6 +12,11 @@ else: LitellmRouter = Any +def _is_a2a_agent_model(model_name: Any) -> bool: + """Check if the model name is for an A2A agent (a2a/ prefix).""" + return isinstance(model_name, str) and model_name.startswith("a2a/") + + ROUTE_ENDPOINT_MAPPING = { "acompletion": "/chat/completions", "atext_completion": "/completions", @@ -322,6 +327,12 @@ async def route_request( except Exception: # If router fails (e.g., model not found in router), fall back to direct call return getattr(litellm, f"{route_type}")(**data) + elif _is_a2a_agent_model(data.get("model", "")): + from litellm.proxy.agent_endpoints.a2a_routing import ( + route_a2a_agent_request, + ) + + return await route_a2a_agent_request(data, route_type) elif user_model is not None: return getattr(litellm, f"{route_type}")(**data) diff --git a/tests/test_litellm/proxy/agent_endpoints/test_model_list_helpers.py b/tests/test_litellm/proxy/agent_endpoints/test_model_list_helpers.py new file mode 100644 index 00000000000..92cd3d9ad6b --- /dev/null +++ b/tests/test_litellm/proxy/agent_endpoints/test_model_list_helpers.py @@ -0,0 +1,110 @@ +""" +Test appending A2A agents to model lists. + +Maps to: litellm/proxy/agent_endpoints/model_list_helpers.py +""" +import os +import sys + +sys.path.insert(0, os.path.abspath("../../../..")) + +from unittest.mock import AsyncMock, Mock, patch + +import pytest + +from litellm.proxy.agent_endpoints.model_list_helpers import ( + append_agents_to_model_group, + append_agents_to_model_info, +) +from litellm.proxy.auth.user_api_key_auth import UserAPIKeyAuth +from litellm.types.agents import AgentResponse +from litellm.types.proxy.management_endpoints.model_management_endpoints import ( + ModelGroupInfoProxy, +) + + +@pytest.mark.asyncio +async def test_append_agents_to_model_group(): + """Test agents are converted to model group format with a2a/ prefix""" + + # Mock agent data + mock_agent = AgentResponse( + agent_id="test-agent-id", + agent_name="my-agent", + agent_card_params={"url": "http://example.com"}, + litellm_params=None, + ) + + # Mock AgentRequestHandler at its source location + mock_get_allowed_agents = AsyncMock(return_value=["test-agent-id"]) + + # Mock global_agent_registry + mock_registry = Mock() + mock_registry.get_agent_by_id = Mock(return_value=mock_agent) + + with patch( + "litellm.proxy.agent_endpoints.auth.agent_permission_handler.AgentRequestHandler.get_allowed_agents", + mock_get_allowed_agents, + ): + with patch( + "litellm.proxy.agent_endpoints.agent_registry.global_agent_registry", + mock_registry, + ): + model_groups = [] + user_api_key_dict = Mock(spec=UserAPIKeyAuth) + + result = await append_agents_to_model_group( + model_groups=model_groups, + user_api_key_dict=user_api_key_dict, + ) + + # Verify agent was converted with a2a/ prefix + assert len(result) == 1 + assert result[0].model_group == "a2a/my-agent" + assert result[0].mode == "chat" + assert result[0].providers == ["a2a"] + + +@pytest.mark.asyncio +async def test_append_agents_to_model_info(): + """Test agents are converted to model info format with a2a/ prefix""" + + # Mock agent data + mock_agent = AgentResponse( + agent_id="agent-123", + agent_name="test-agent", + agent_card_params={"url": "http://example.com"}, + litellm_params=None, + created_by="user-123", + ) + + # Mock AgentRequestHandler at its source location + mock_get_allowed_agents = AsyncMock(return_value=["agent-123"]) + + # Mock global_agent_registry + mock_registry = Mock() + mock_registry.get_agent_by_id = Mock(return_value=mock_agent) + + with patch( + "litellm.proxy.agent_endpoints.auth.agent_permission_handler.AgentRequestHandler.get_allowed_agents", + mock_get_allowed_agents, + ): + with patch( + "litellm.proxy.agent_endpoints.agent_registry.global_agent_registry", + mock_registry, + ): + models = [] + user_api_key_dict = Mock(spec=UserAPIKeyAuth) + + result = await append_agents_to_model_info( + models=models, + user_api_key_dict=user_api_key_dict, + ) + + # Verify agent was converted with a2a/ prefix + assert len(result) == 1 + assert result[0]["model_name"] == "a2a/test-agent" + assert result[0]["litellm_params"]["model"] == "a2a/test-agent" + assert result[0]["litellm_params"]["custom_llm_provider"] == "a2a" + assert result[0]["model_info"]["id"] == "agent-123" + assert result[0]["model_info"]["mode"] == "chat" diff --git a/tests/test_litellm/proxy/test_route_a2a_models.py b/tests/test_litellm/proxy/test_route_a2a_models.py new file mode 100644 index 00000000000..e8d89c0c7eb --- /dev/null +++ b/tests/test_litellm/proxy/test_route_a2a_models.py @@ -0,0 +1,105 @@ +""" +Test A2A model routing in proxy. + +Maps to: litellm/proxy/agent_endpoints/a2a_routing.py +""" +import os +import sys + +sys.path.insert(0, os.path.abspath("../../..")) + +from unittest.mock import AsyncMock, Mock, patch + +import pytest + +from litellm.proxy.agent_endpoints.a2a_routing import route_a2a_agent_request +from litellm.proxy.route_llm_request import route_request + + +@pytest.mark.asyncio +async def test_route_a2a_model_bypasses_router(): + """Test that a2a/ prefixed models bypass router and go directly to litellm with api_base""" + + # Mock data for chat completion with a2a model + data = { + "model": "a2a/test-agent", + "messages": [{"role": "user", "content": "Hello"}], + } + + # Mock router that doesn't have the a2a model + mock_router = Mock() + mock_router.model_names = ["gpt-4", "gpt-3.5-turbo"] + mock_router.deployment_names = [] + mock_router.has_model_id = Mock(return_value=False) + mock_router.model_group_alias = None + mock_router.router_general_settings = Mock(pass_through_all_models=False) + mock_router.default_deployment = None + mock_router.pattern_router = Mock(patterns=[]) + mock_router.map_team_model = Mock(return_value=None) + + # Mock agent in registry + from litellm.types.agents import AgentResponse + + mock_agent = AgentResponse( + agent_id="test-agent-id", + agent_name="test-agent", + agent_card_params={"url": "http://agent.example.com"}, + litellm_params=None, + ) + + mock_registry = Mock() + mock_registry.get_agent_by_name = Mock(return_value=mock_agent) + + # Mock litellm.acompletion to verify it's called + mock_acompletion = AsyncMock(return_value={"id": "test-response"}) + + with patch("litellm.acompletion", mock_acompletion): + with patch( + "litellm.proxy.agent_endpoints.a2a_routing.global_agent_registry", + mock_registry, + ): + result = await route_request( + data=data, + llm_router=mock_router, + user_model=None, + route_type="acompletion", + ) + + # Verify litellm.acompletion was called with api_base injected + mock_acompletion.assert_called_once() + call_kwargs = mock_acompletion.call_args.kwargs + assert call_kwargs["model"] == "a2a/test-agent" + assert call_kwargs["api_base"] == "http://agent.example.com" + + +@pytest.mark.asyncio +async def test_route_non_a2a_model_raises_error_if_not_in_router(): + """Test that non-a2a models that aren't in router raise an error""" + + # Mock data for chat completion with model not in router + data = { + "model": "unknown-model", + "messages": [{"role": "user", "content": "Hello"}], + } + + # Mock router without the model + mock_router = Mock() + mock_router.model_names = ["gpt-4", "gpt-3.5-turbo"] + mock_router.deployment_names = [] + mock_router.has_model_id = Mock(return_value=False) + mock_router.model_group_alias = None + mock_router.router_general_settings = Mock(pass_through_all_models=False) + mock_router.default_deployment = None + mock_router.pattern_router = Mock(patterns=[]) + mock_router.map_team_model = Mock(return_value=None) + + # Should raise ProxyModelNotFoundError + from litellm.proxy.route_llm_request import ProxyModelNotFoundError + + with pytest.raises(ProxyModelNotFoundError): + await route_request( + data=data, + llm_router=mock_router, + user_model=None, + route_type="acompletion", + ) diff --git a/tests/test_litellm/test_a2a_registry_lookup.py b/tests/test_litellm/test_a2a_registry_lookup.py new file mode 100644 index 00000000000..9938f10a43f --- /dev/null +++ b/tests/test_litellm/test_a2a_registry_lookup.py @@ -0,0 +1,73 @@ +""" +Test A2A provider registry lookup functionality. + +Maps to: litellm/llms/a2a/chat/transformation.py +""" +import os +import sys + +sys.path.insert(0, os.path.abspath("../..")) + +import pytest + +import litellm +from litellm.llms.a2a.chat.transformation import A2AConfig + + +def test_resolve_agent_config_from_registry_static_method(): + """Test the static helper method for registry resolution""" + + # Test 1: No agent name in model + api_base, api_key, headers = A2AConfig.resolve_agent_config_from_registry( + model="a2a", + api_base="http://test.com", + api_key=None, + headers=None, + optional_params={} + ) + assert api_base == "http://test.com" + + # Test 2: All params provided - should not lookup registry + api_base, api_key, headers = A2AConfig.resolve_agent_config_from_registry( + model="a2a/test-agent", + api_base="http://explicit.com", + api_key="explicit-key", + headers={"X-Test": "value"}, + optional_params={} + ) + assert api_base == "http://explicit.com" + assert api_key == "explicit-key" + + +def test_a2a_registry_integration(): + """Test registry lookup in proxy context""" + + try: + from litellm.proxy.agent_endpoints.agent_registry import global_agent_registry + from litellm.types.agents import AgentResponse + + # Create test agent + test_agent = AgentResponse( + agent_id="test-id", + agent_name="test-agent", + agent_card_params={"url": "http://registry-url.example.com:9999"}, + litellm_params={"api_key": "registry-key"}, + ) + + # Register and test + original_agents = global_agent_registry.agent_list.copy() + global_agent_registry.register_agent(test_agent) + + try: + litellm.completion( + model="a2a/test-agent", + messages=[{"role": "user", "content": "Hello"}] + ) + except Exception as e: + # Should use registry URL (connection error expected) + assert "registry-url.example.com" in str(e) or "APIConnectionError" in str(type(e).__name__) + finally: + global_agent_registry.agent_list = original_agents + + except ImportError: + pytest.skip("Registry not available (not in proxy context)") From a2653bcd5e6f368b652e17fbaafe5e6df5b7d356 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Tue, 3 Feb 2026 15:26:51 -0800 Subject: [PATCH 053/511] Adding Allowed Routes to Key Info and Edit Pages --- .../templates/key_edit_view.test.tsx | 353 ++++++++++++++++-- .../components/templates/key_edit_view.tsx | 67 +++- .../templates/key_info_view.test.tsx | 174 ++++++++- .../components/templates/key_info_view.tsx | 65 ++-- 4 files changed, 575 insertions(+), 84 deletions(-) diff --git a/ui/litellm-dashboard/src/components/templates/key_edit_view.test.tsx b/ui/litellm-dashboard/src/components/templates/key_edit_view.test.tsx index 03e1085937d..0123e22eb14 100644 --- a/ui/litellm-dashboard/src/components/templates/key_edit_view.test.tsx +++ b/ui/litellm-dashboard/src/components/templates/key_edit_view.test.tsx @@ -1,24 +1,61 @@ -import { fireEvent, waitFor } from "@testing-library/react"; -import { describe, expect, it, vi } from "vitest"; +import { screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { beforeEach, describe, expect, it, vi } from "vitest"; import { renderWithProviders } from "../../../tests/test-utils"; import { KeyResponse } from "../key_team_helpers/key_list"; import { KeyEditView } from "./key_edit_view"; -// Mock window.matchMedia -Object.defineProperty(window, "matchMedia", { - writable: true, - value: vi.fn().mockImplementation((query) => ({ - matches: false, - media: query, - onchange: null, - addListener: vi.fn(), - removeListener: vi.fn(), - addEventListener: vi.fn(), - removeEventListener: vi.fn(), - dispatchEvent: vi.fn(), - })), +vi.mock("../networking", async () => { + const actual = await vi.importActual("../networking"); + return { + ...actual, + getPromptsList: vi.fn().mockResolvedValue({ + prompts: [{ prompt_id: "prompt-1" }, { prompt_id: "prompt-2" }], + }), + modelAvailableCall: vi.fn().mockResolvedValue({ + data: [{ id: "gpt-4" }, { id: "gpt-3.5-turbo" }], + }), + tagListCall: vi.fn().mockResolvedValue({ + tag1: { name: "tag1", description: "Test tag 1" }, + tag2: { name: "tag2", description: "Test tag 2" }, + }), + getGuardrailsList: vi.fn().mockResolvedValue({ + guardrails: [{ guardrail_name: "guardrail-1" }], + }), + getPoliciesList: vi.fn().mockResolvedValue({ + policies: [{ policy_name: "policy-1" }], + }), + getPassThroughEndpointsCall: vi.fn().mockResolvedValue({ + endpoints: [], + }), + vectorStoreListCall: vi.fn().mockResolvedValue({ + data: [], + }), + mcpToolsCall: vi.fn().mockResolvedValue({ + data: [], + }), + agentListCall: vi.fn().mockResolvedValue({ + data: [], + }), + fetchMCPServers: vi.fn().mockResolvedValue([]), + fetchMCPAccessGroups: vi.fn().mockResolvedValue([]), + listMCPTools: vi.fn().mockResolvedValue({ + tools: [], + error: null, + message: null, + stack_trace: null, + }), + getAgentsList: vi.fn().mockResolvedValue({ + agents: [], + }), + getAgentAccessGroups: vi.fn().mockResolvedValue([]), + }; }); +vi.mock("../organisms/create_key_button", () => ({ + fetchTeamModels: vi.fn().mockResolvedValue(["team-model-1", "team-model-2"]), +})); + describe("KeyEditView", () => { const MOCK_KEY_DATA: KeyResponse = { token: "test-token-123", @@ -93,8 +130,8 @@ describe("KeyEditView", () => { const { getByText } = renderWithProviders( {}} - onSubmit={async () => {}} + onCancel={() => { }} + onSubmit={async () => { }} accessToken={""} userID={""} userRole={""} @@ -111,8 +148,8 @@ describe("KeyEditView", () => { const { getByText } = renderWithProviders( {}} - onSubmit={async () => {}} + onCancel={() => { }} + onSubmit={async () => { }} accessToken={""} userID={""} userRole={""} @@ -129,8 +166,8 @@ describe("KeyEditView", () => { const { getByLabelText } = renderWithProviders( {}} - onSubmit={async () => {}} + onCancel={() => { }} + onSubmit={async () => { }} accessToken={""} userID={""} userRole={""} @@ -144,13 +181,17 @@ describe("KeyEditView", () => { }); }); + beforeEach(() => { + vi.clearAllMocks(); + }); + it("should call onCancel when cancel button is clicked", async () => { const onCancelMock = vi.fn(); - const { getByText } = renderWithProviders( + renderWithProviders( {}} + onSubmit={async () => { }} accessToken={""} userID={""} userRole={""} @@ -159,12 +200,272 @@ describe("KeyEditView", () => { ); await waitFor(() => { - expect(getByText("Cancel")).toBeInTheDocument(); + expect(screen.getByRole("button", { name: /cancel/i })).toBeInTheDocument(); }); - const cancelButton = getByText("Cancel"); - fireEvent.click(cancelButton); + const cancelButton = screen.getByRole("button", { name: /cancel/i }); + await userEvent.click(cancelButton); expect(onCancelMock).toHaveBeenCalledTimes(1); }); + + it("should display key alias input field", async () => { + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={""} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByLabelText("Key Alias")).toBeInTheDocument(); + }); + }); + + it("should display models select field", async () => { + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={""} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByText("Models")).toBeInTheDocument(); + }); + }); + + it("should display max budget input field", async () => { + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={""} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByLabelText("Max Budget (USD)")).toBeInTheDocument(); + }); + }); + + it("should display allowed routes input field", async () => { + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={""} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByLabelText(/allowed routes/i)).toBeInTheDocument(); + }); + }); + + it("should call onSubmit with form values when form is submitted", async () => { + const onSubmitMock = vi.fn().mockResolvedValue(undefined); + renderWithProviders( + { }} + onSubmit={onSubmitMock} + accessToken={"test-token"} + userID={"test-user"} + userRole={"admin"} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(onSubmitMock).toHaveBeenCalled(); + }); + }); + + it("should disable models field when management routes are selected", async () => { + const keyDataWithManagementRoutes = { + ...MOCK_KEY_DATA, + allowed_routes: ["management_routes"], + }; + + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={""} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByText("Models field is disabled for this key type")).toBeInTheDocument(); + }); + }); + + it("should disable models field when info routes are selected", async () => { + const keyDataWithInfoRoutes = { + ...MOCK_KEY_DATA, + allowed_routes: ["info_routes"], + }; + + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={""} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByText("Models field is disabled for this key type")).toBeInTheDocument(); + }); + }); + + it("should disable guardrails selector when user is not premium", async () => { + renderWithProviders( + { }} + onSubmit={async () => { }} + accessToken={"test-token"} + userID={""} + userRole={""} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByText("Guardrails")).toBeInTheDocument(); + }); + }); + + it("should parse comma-separated allowed routes on submit", async () => { + const onSubmitMock = vi.fn().mockResolvedValue(undefined); + renderWithProviders( + { }} + onSubmit={onSubmitMock} + accessToken={"test-token"} + userID={"test-user"} + userRole={"admin"} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByLabelText(/allowed routes/i)).toBeInTheDocument(); + }); + + const allowedRoutesInput = screen.getByLabelText(/allowed routes/i); + await userEvent.clear(allowedRoutesInput); + await userEvent.type(allowedRoutesInput, "route1, route2, route3"); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(onSubmitMock).toHaveBeenCalled(); + const callArgs = onSubmitMock.mock.calls[0][0]; + expect(Array.isArray(callArgs.allowed_routes)).toBe(true); + expect(callArgs.allowed_routes).toEqual(["route1", "route2", "route3"]); + }); + }); + + it("should handle empty allowed routes string on submit", async () => { + const onSubmitMock = vi.fn().mockResolvedValue(undefined); + renderWithProviders( + { }} + onSubmit={onSubmitMock} + accessToken={"test-token"} + userID={"test-user"} + userRole={"admin"} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByLabelText(/allowed routes/i)).toBeInTheDocument(); + }); + + const allowedRoutesInput = screen.getByLabelText(/allowed routes/i); + await userEvent.clear(allowedRoutesInput); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(onSubmitMock).toHaveBeenCalled(); + const callArgs = onSubmitMock.mock.calls[0][0]; + expect(callArgs.allowed_routes).toEqual([]); + }); + }); + + + it("should disable cancel button during submission", async () => { + const onSubmitMock = vi.fn( + () => + new Promise((resolve) => { + setTimeout(resolve, 100); + }), + ); + + renderWithProviders( + { }} + onSubmit={onSubmitMock} + accessToken={"test-token"} + userID={"test-user"} + userRole={"admin"} + premiumUser={false} + />, + ); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /cancel/i })).toBeInTheDocument(); + }); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + const cancelButton = screen.getByRole("button", { name: /cancel/i }); + expect(cancelButton).toBeDisabled(); + }); + }); }); diff --git a/ui/litellm-dashboard/src/components/templates/key_edit_view.tsx b/ui/litellm-dashboard/src/components/templates/key_edit_view.tsx index 2d3eaf2bb7f..64676e3b94a 100644 --- a/ui/litellm-dashboard/src/components/templates/key_edit_view.tsx +++ b/ui/litellm-dashboard/src/components/templates/key_edit_view.tsx @@ -35,7 +35,6 @@ interface KeyEditViewProps { // Add this helper function const getAvailableModelsForKey = (keyData: KeyResponse, teams: any[] | null): string[] => { // If no teams data is available, return empty array - console.log("getAvailableModelsForKey:", teams); if (!teams || !keyData.team_id) { return []; } @@ -172,7 +171,9 @@ export function KeyEditView({ : [], auto_rotate: keyData.auto_rotate || false, ...(keyData.rotation_interval && { rotation_interval: keyData.rotation_interval }), - allowed_routes: keyData.allowed_routes, + allowed_routes: Array.isArray(keyData.allowed_routes) && keyData.allowed_routes.length > 0 + ? keyData.allowed_routes.join(", ") + : "", }; useEffect(() => { @@ -197,7 +198,9 @@ export function KeyEditView({ : [], auto_rotate: keyData.auto_rotate || false, ...(keyData.rotation_interval && { rotation_interval: keyData.rotation_interval }), - allowed_routes: keyData.allowed_routes, + allowed_routes: Array.isArray(keyData.allowed_routes) && keyData.allowed_routes.length > 0 + ? keyData.allowed_routes.join(", ") + : "", }); }, [keyData, form]); @@ -226,11 +229,24 @@ export function KeyEditView({ fetchTags(); }, [accessToken]); - console.log("premiumUser:", premiumUser); - const handleSubmit = async (values: any) => { try { setIsKeySaving(true); + + // Parse allowed_routes from comma-separated string to array + if (typeof values.allowed_routes === "string") { + const trimmedInput = values.allowed_routes.trim(); + if (trimmedInput === "") { + values.allowed_routes = []; + } else { + values.allowed_routes = trimmedInput + .split(",") + .map((route: string) => route.trim()) + .filter((route: string) => route.length > 0); + } + } + // If it's already an array (shouldn't happen, but handle it), keep as is + await onSubmit(values); } finally { setIsKeySaving(false); @@ -251,7 +267,11 @@ export function KeyEditView({ } > {({ getFieldValue, setFieldValue }) => { - const allowedRoutes = getFieldValue("allowed_routes") || []; + const allowedRoutesValue = getFieldValue("allowed_routes") || ""; + // Convert string to array for checking + const allowedRoutes = typeof allowedRoutesValue === "string" && allowedRoutesValue.trim() !== "" + ? allowedRoutesValue.split(",").map((r: string) => r.trim()).filter((r: string) => r.length > 0) + : []; const isDisabled = allowedRoutes.includes("management_routes") || allowedRoutes.includes("info_routes"); const models = getFieldValue("models") || []; @@ -290,7 +310,11 @@ export function KeyEditView({ shouldUpdate={(prevValues, currentValues) => prevValues.allowed_routes !== currentValues.allowed_routes} > {({ getFieldValue, setFieldValue }) => { - const allowedRoutes = getFieldValue("allowed_routes"); + const allowedRoutesValue = getFieldValue("allowed_routes") || ""; + // Convert string to array for getKeyTypeFromRoutes + const allowedRoutes = typeof allowedRoutesValue === "string" && allowedRoutesValue.trim() !== "" + ? allowedRoutesValue.split(",").map((r: string) => r.trim()).filter((r: string) => r.length > 0) + : []; const keyTypeValue = getKeyTypeFromRoutes(allowedRoutes); return ( @@ -302,13 +326,13 @@ export function KeyEditView({ onChange={(value) => { switch (value) { case "default": - setFieldValue("allowed_routes", []); + setFieldValue("allowed_routes", ""); break; case "llm_api": - setFieldValue("allowed_routes", ["llm_api_routes"]); + setFieldValue("allowed_routes", "llm_api_routes"); break; case "management": - setFieldValue("allowed_routes", ["management_routes"]); + setFieldValue("allowed_routes", "management_routes"); setFieldValue("models", []); break; } @@ -344,6 +368,22 @@ export function KeyEditView({

rloJO`@dX7HG|vPBlzCG%+jw-ni0qau8|AZ3<%z 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

+ + Allowed Routes{" "} + + + + + } + name="allowed_routes" + > + + + @@ -473,7 +513,7 @@ export function KeyEditView({ !premiumUser ? "Premium feature - Upgrade to set allowed pass through routes by key" : Array.isArray(keyData.metadata?.allowed_passthrough_routes) && - keyData.metadata.allowed_passthrough_routes.length > 0 + keyData.metadata.allowed_passthrough_routes.length > 0 ? `Current: ${keyData.metadata.allowed_passthrough_routes.join(", ")}` : "Select or enter allowed pass through routes" } @@ -590,11 +630,6 @@ export function KeyEditView({ - {/* Hidden form field for allowed_routes */} - - {/* Hidden form field for disabled callbacks */}
@@ -691,10 +689,10 @@ export default function KeyInfoView({
{Array.isArray(currentKeyData.metadata?.tags) && currentKeyData.metadata.tags.length > 0 ? currentKeyData.metadata.tags.map((tag, index) => ( - - {tag} - - )) + + {tag} + + )) : "No tags specified"}
@@ -704,24 +702,39 @@ export default function KeyInfoView({ {Array.isArray(currentKeyData.metadata?.prompts) && currentKeyData.metadata.prompts.length > 0 ? currentKeyData.metadata.prompts.map((prompt, index) => ( - - {prompt} - - )) + + {prompt} + + )) : "No prompts specified"}
+
+ Allowed Routes +
+ {Array.isArray(currentKeyData.allowed_routes) && currentKeyData.allowed_routes.length > 0 ? ( + currentKeyData.allowed_routes.map((route, index) => ( + + {route} + + )) + ) : ( + All routes allowed + )} +
+
+
Allowed Pass Through Routes {Array.isArray(currentKeyData.metadata?.allowed_passthrough_routes) && - currentKeyData.metadata.allowed_passthrough_routes.length > 0 + currentKeyData.metadata.allowed_passthrough_routes.length > 0 ? currentKeyData.metadata.allowed_passthrough_routes.map((route, index) => ( - - {route} - - )) + + {route} + + )) : "No pass through routes specified"}
From 23d9a89793f18929e015cc8092e2bab5dc991231 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Tue, 3 Feb 2026 15:57:13 -0800 Subject: [PATCH 054/511] search tools list includes config defined search tools --- .../search_tool_management.py | 68 ++- litellm/types/search.py | 1 + .../test_search_tool_management.py | 393 ++++++++++++++++++ 3 files changed, 456 insertions(+), 6 deletions(-) create mode 100644 tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py diff --git a/litellm/proxy/search_endpoints/search_tool_management.py b/litellm/proxy/search_endpoints/search_tool_management.py index 21a4db75a01..5a353bd60df 100644 --- a/litellm/proxy/search_endpoints/search_tool_management.py +++ b/litellm/proxy/search_endpoints/search_tool_management.py @@ -48,7 +48,7 @@ def _convert_datetime_to_str(value: Union[datetime, str, None]) -> Union[str, No ) async def list_search_tools(): """ - List all search tools that are available in the database. + List all search tools that are available in the database and config file. Example Request: ```bash @@ -71,24 +71,78 @@ async def list_search_tools(): "description": "Perplexity search tool" }, "created_at": "2023-11-09T12:34:56.789Z", - "updated_at": "2023-11-09T12:34:56.789Z" + "updated_at": "2023-11-09T12:34:56.789Z", + "is_from_config": false + }, + { + "search_tool_name": "config-search-tool", + "litellm_params": { + "search_provider": "tavily", + "api_key": "tvly-***" + }, + "is_from_config": true } ] } ``` """ - from litellm.proxy.proxy_server import prisma_client + from litellm.litellm_core_utils.litellm_logging import _get_masked_values + from litellm.proxy.proxy_server import prisma_client, proxy_config if prisma_client is None: raise HTTPException(status_code=500, detail="Prisma client not initialized") try: - search_tools = await SEARCH_TOOL_REGISTRY.get_all_search_tools_from_db( + search_tools_from_db = await SEARCH_TOOL_REGISTRY.get_all_search_tools_from_db( prisma_client=prisma_client ) + db_tool_names = { + tool.get("search_tool_name") for tool in search_tools_from_db + } + search_tool_configs: List[SearchToolInfoResponse] = [] - for search_tool in search_tools: + + config_search_tools = [] + + try: + config = await proxy_config.get_config() + parsed_tools = proxy_config.parse_search_tools(config) + if parsed_tools: + config_search_tools = parsed_tools + except Exception as e: + verbose_proxy_logger.debug( + f"Could not get config-defined search tools: {e}" + ) + + for search_tool in config_search_tools: + tool_name = search_tool.get("search_tool_name") + if tool_name: + litellm_params_dict = dict(search_tool.get("litellm_params", {})) + masked_litellm_params_dict = _get_masked_values( + litellm_params_dict, + unmasked_length=4, + number_of_asterisks=4, + ) + + search_tool_configs.append( + SearchToolInfoResponse( + search_tool_id=None, + search_tool_name=tool_name, + litellm_params=masked_litellm_params_dict, + search_tool_info=search_tool.get("search_tool_info"), + created_at=None, + updated_at=None, + is_from_config=True, + ) + ) + + search_tool_configs = [ + tool for tool in search_tool_configs + if tool.get("search_tool_name") not in db_tool_names + ] + + for search_tool in search_tools_from_db: search_tool_configs.append( SearchToolInfoResponse( search_tool_id=search_tool.get("search_tool_id"), @@ -97,12 +151,13 @@ async def list_search_tools(): search_tool_info=search_tool.get("search_tool_info"), created_at=_convert_datetime_to_str(search_tool.get("created_at")), updated_at=_convert_datetime_to_str(search_tool.get("updated_at")), + is_from_config=False, ) ) return ListSearchToolsResponse(search_tools=search_tool_configs) except Exception as e: - verbose_proxy_logger.exception(f"Error getting search tools from db: {e}") + verbose_proxy_logger.exception(f"Error getting search tools: {e}") raise HTTPException(status_code=500, detail=str(e)) @@ -382,6 +437,7 @@ async def get_search_tool_info(search_tool_id: str): search_tool_info=result.get("search_tool_info"), created_at=_convert_datetime_to_str(result.get("created_at")), updated_at=_convert_datetime_to_str(result.get("updated_at")), + is_from_config=False, # This endpoint only returns DB tools ) except HTTPException as e: raise e diff --git a/litellm/types/search.py b/litellm/types/search.py index 661a2feda33..b0ce0636aed 100644 --- a/litellm/types/search.py +++ b/litellm/types/search.py @@ -60,6 +60,7 @@ class SearchToolInfoResponse(TypedDict, total=False): search_tool_info: Optional[dict] created_at: Optional[str] updated_at: Optional[str] + is_from_config: Optional[bool] # True if this tool is defined in config file, False if from DB class ListSearchToolsResponse(TypedDict): diff --git a/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py b/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py new file mode 100644 index 00000000000..4cb85601c9b --- /dev/null +++ b/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py @@ -0,0 +1,393 @@ +import os +import sys +from datetime import datetime +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest +from fastapi.testclient import TestClient + +sys.path.insert( + 0, os.path.abspath("../../../../..") +) # Adds the parent directory to the system path + +from litellm.proxy._types import LitellmUserRoles, UserAPIKeyAuth + +# Import proxy_server module first to ensure it's initialized +import litellm.proxy.proxy_server as ps + +# Now we can safely import app +from litellm.proxy.proxy_server import app + +client = TestClient(app) + + +@pytest.mark.asyncio +async def test_list_search_tools_db_only(monkeypatch): + """Test listing search tools when only DB tools exist""" + # Mock DB tools + db_tools = [ + { + "search_tool_id": "test-id-1", + "search_tool_name": "db-tool-1", + "litellm_params": {"search_provider": "perplexity", "api_key": "sk-test"}, + "search_tool_info": {"description": "DB tool 1"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + } + ] + + # Mock SearchToolRegistry + mock_registry = MagicMock() + mock_registry.get_all_search_tools_from_db = AsyncMock(return_value=db_tools) + with patch( + "litellm.proxy.search_endpoints.search_tool_management.SEARCH_TOOL_REGISTRY", + mock_registry, + ): + # Mock prisma_client + mock_prisma = MagicMock() + with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma): + # Mock proxy_config + mock_proxy_config = MagicMock() + mock_proxy_config.get_config = AsyncMock(return_value={}) + mock_proxy_config.parse_search_tools = MagicMock(return_value=None) + with patch("litellm.proxy.proxy_server.proxy_config", mock_proxy_config): + # Mock auth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + test_client = TestClient(app) + response = test_client.get("/search_tools/list") + assert response.status_code == 200 + data = response.json() + assert "search_tools" in data + assert len(data["search_tools"]) == 1 + + tool = data["search_tools"][0] + assert tool["search_tool_id"] == "test-id-1" + assert tool["search_tool_name"] == "db-tool-1" + assert tool["is_from_config"] is False + # Verify datetime conversion to ISO string + assert tool["created_at"] == "2023-11-09T12:34:56" + assert tool["updated_at"] == "2023-11-09T13:45:12" + finally: + app.dependency_overrides.pop(user_api_key_auth, None) + + +@pytest.mark.asyncio +async def test_list_search_tools_config_only(monkeypatch): + """Test listing search tools when only config tools exist""" + # Mock DB tools - empty + db_tools = [] + + # Mock config tools + config_tools = [ + { + "search_tool_name": "config-tool-1", + "litellm_params": {"search_provider": "tavily", "api_key": "tvly-secret-key"}, + "search_tool_info": {"description": "Config tool 1"}, + } + ] + + # Mock SearchToolRegistry + mock_registry = MagicMock() + mock_registry.get_all_search_tools_from_db = AsyncMock(return_value=db_tools) + with patch( + "litellm.proxy.search_endpoints.search_tool_management.SEARCH_TOOL_REGISTRY", + mock_registry, + ): + # Mock prisma_client + mock_prisma = MagicMock() + with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma): + # Mock proxy_config + mock_proxy_config = MagicMock() + mock_proxy_config.get_config = AsyncMock(return_value={"search_tools": config_tools}) + mock_proxy_config.parse_search_tools = MagicMock(return_value=config_tools) + with patch("litellm.proxy.proxy_server.proxy_config", mock_proxy_config): + # Mock auth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + test_client = TestClient(app) + response = test_client.get("/search_tools/list") + assert response.status_code == 200 + data = response.json() + assert "search_tools" in data + assert len(data["search_tools"]) == 1 + + tool = data["search_tools"][0] + assert tool["search_tool_name"] == "config-tool-1" + assert tool["is_from_config"] is True + assert tool["search_tool_id"] is None + assert tool["created_at"] is None + assert tool["updated_at"] is None + # Verify masking + assert "tv****ey" in tool["litellm_params"]["api_key"] + finally: + app.dependency_overrides.pop(user_api_key_auth, None) + + +@pytest.mark.asyncio +async def test_list_search_tools_filters_duplicate_config_tools(monkeypatch): + """ + Test that config tools with the same name as DB tools are filtered out. + This tests the new filtering logic added in lines 139-142. + """ + # Mock DB tools + db_tools = [ + { + "search_tool_id": "db-id-1", + "search_tool_name": "existing-tool", + "litellm_params": {"search_provider": "perplexity", "api_key": "sk-db"}, + "search_tool_info": {"description": "DB tool"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + } + ] + + # Mock config tools - one duplicate, one unique + config_tools = [ + { + "search_tool_name": "existing-tool", # Duplicate - should be filtered + "litellm_params": {"search_provider": "tavily", "api_key": "tvly-config"}, + "search_tool_info": {"description": "Config tool - duplicate"}, + }, + { + "search_tool_name": "unique-config-tool", # Unique - should be included + "litellm_params": {"search_provider": "tavily", "api_key": "tvly-unique"}, + "search_tool_info": {"description": "Config tool - unique"}, + }, + ] + + # Mock SearchToolRegistry + mock_registry = MagicMock() + mock_registry.get_all_search_tools_from_db = AsyncMock(return_value=db_tools) + with patch( + "litellm.proxy.search_endpoints.search_tool_management.SEARCH_TOOL_REGISTRY", + mock_registry, + ): + # Mock prisma_client + mock_prisma = MagicMock() + with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma): + # Mock proxy_config + mock_proxy_config = MagicMock() + mock_proxy_config.get_config = AsyncMock(return_value={"search_tools": config_tools}) + mock_proxy_config.parse_search_tools = MagicMock(return_value=config_tools) + with patch("litellm.proxy.proxy_server.proxy_config", mock_proxy_config): + # Mock auth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + test_client = TestClient(app) + response = test_client.get("/search_tools/list") + assert response.status_code == 200 + data = response.json() + assert "search_tools" in data + # Should have 1 DB tool + 1 unique config tool (duplicate filtered out) + assert len(data["search_tools"]) == 2 + + # Verify DB tool is present + db_tool = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "existing-tool"), + None, + ) + assert db_tool is not None + assert db_tool["is_from_config"] is False + assert db_tool["search_tool_id"] == "db-id-1" + + # Verify unique config tool is present + config_tool = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "unique-config-tool"), + None, + ) + assert config_tool is not None + assert config_tool["is_from_config"] is True + + # Verify duplicate config tool is NOT present + duplicate_tool = next( + ( + t + for t in data["search_tools"] + if t["search_tool_name"] == "existing-tool" and t["is_from_config"] is True + ), + None, + ) + assert duplicate_tool is None + finally: + app.dependency_overrides.pop(user_api_key_auth, None) + + +@pytest.mark.asyncio +async def test_list_search_tools_datetime_conversion(monkeypatch): + """ + Test that datetime objects in DB tools are properly converted to ISO format strings. + This tests the new datetime conversion logic using _convert_datetime_to_str. + """ + # Mock DB tools with datetime objects + db_tools = [ + { + "search_tool_id": "test-id-1", + "search_tool_name": "datetime-test-tool", + "litellm_params": {"search_provider": "perplexity", "api_key": "sk-test"}, + "search_tool_info": {"description": "Test tool"}, + "created_at": datetime(2024, 1, 15, 10, 30, 45, 123456), + "updated_at": datetime(2024, 1, 16, 14, 20, 30, 789012), + }, + { + "search_tool_id": "test-id-2", + "search_tool_name": "null-datetime-tool", + "litellm_params": {"search_provider": "tavily", "api_key": "tvly-test"}, + "search_tool_info": None, + "created_at": None, + "updated_at": None, + }, + { + "search_tool_id": "test-id-3", + "search_tool_name": "string-datetime-tool", + "litellm_params": {"search_provider": "perplexity", "api_key": "sk-test"}, + "search_tool_info": {"description": "Already string"}, + "created_at": "2024-01-17T08:15:00", # Already a string + "updated_at": "2024-01-18T09:25:00", # Already a string + }, + ] + + # Mock SearchToolRegistry + mock_registry = MagicMock() + mock_registry.get_all_search_tools_from_db = AsyncMock(return_value=db_tools) + with patch( + "litellm.proxy.search_endpoints.search_tool_management.SEARCH_TOOL_REGISTRY", + mock_registry, + ): + # Mock prisma_client + mock_prisma = MagicMock() + with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma): + # Mock proxy_config + mock_proxy_config = MagicMock() + mock_proxy_config.get_config = AsyncMock(return_value={}) + mock_proxy_config.parse_search_tools = MagicMock(return_value=None) + with patch("litellm.proxy.proxy_server.proxy_config", mock_proxy_config): + # Mock auth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + test_client = TestClient(app) + response = test_client.get("/search_tools/list") + assert response.status_code == 200 + data = response.json() + assert "search_tools" in data + assert len(data["search_tools"]) == 3 + + # Test datetime conversion for tool 1 + tool1 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "datetime-test-tool"), + None, + ) + assert tool1 is not None + assert isinstance(tool1["created_at"], str) + assert tool1["created_at"] == "2024-01-15T10:30:45.123456" + assert isinstance(tool1["updated_at"], str) + assert tool1["updated_at"] == "2024-01-16T14:20:30.789012" + + # Test None handling for tool 2 + tool2 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "null-datetime-tool"), + None, + ) + assert tool2 is not None + assert tool2["created_at"] is None + assert tool2["updated_at"] is None + + # Test string passthrough for tool 3 + tool3 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "string-datetime-tool"), + None, + ) + assert tool3 is not None + assert tool3["created_at"] == "2024-01-17T08:15:00" + assert tool3["updated_at"] == "2024-01-18T09:25:00" + finally: + app.dependency_overrides.pop(user_api_key_auth, None) + + +@pytest.mark.asyncio +async def test_list_search_tools_config_error_handling(monkeypatch): + """Test that config errors are handled gracefully""" + # Mock DB tools + db_tools = [ + { + "search_tool_id": "test-id-1", + "search_tool_name": "db-tool-1", + "litellm_params": {"search_provider": "perplexity", "api_key": "sk-test"}, + "search_tool_info": {"description": "DB tool"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + } + ] + + # Mock SearchToolRegistry + mock_registry = MagicMock() + mock_registry.get_all_search_tools_from_db = AsyncMock(return_value=db_tools) + with patch( + "litellm.proxy.search_endpoints.search_tool_management.SEARCH_TOOL_REGISTRY", + mock_registry, + ): + # Mock prisma_client + mock_prisma = MagicMock() + with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma): + # Mock proxy_config to raise an error + mock_proxy_config = MagicMock() + mock_proxy_config.get_config = AsyncMock(side_effect=Exception("Config error")) + with patch("litellm.proxy.proxy_server.proxy_config", mock_proxy_config): + # Mock auth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + # Should still succeed and return DB tools only + response = client.get("/search_tools/list") + assert response.status_code == 200 + data = response.json() + assert "search_tools" in data + # Should only have DB tools since config failed + assert len(data["search_tools"]) == 1 + assert data["search_tools"][0]["search_tool_name"] == "db-tool-1" + finally: + app.dependency_overrides.pop(user_api_key_auth, None) + + +@pytest.mark.asyncio +async def test_list_search_tools_no_prisma_client(monkeypatch): + """Test error handling when prisma_client is None""" + with patch("litellm.proxy.proxy_server.prisma_client", None): + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + test_client = TestClient(app) + response = test_client.get("/search_tools/list") + assert response.status_code == 500 + data = response.json() + assert "Prisma client not initialized" in data["detail"] + finally: + app.dependency_overrides.pop(user_api_key_auth, None) From 3e3b21e6c3884197fe9621c82fdfe58e5a3c1f62 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Tue, 3 Feb 2026 16:09:37 -0800 Subject: [PATCH 055/511] masking sensitive values --- .../search_tool_management.py | 9 +- .../test_search_tool_management.py | 153 ++++++++++++++++++ 2 files changed, 161 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/search_endpoints/search_tool_management.py b/litellm/proxy/search_endpoints/search_tool_management.py index 5a353bd60df..4754316795e 100644 --- a/litellm/proxy/search_endpoints/search_tool_management.py +++ b/litellm/proxy/search_endpoints/search_tool_management.py @@ -143,11 +143,18 @@ async def list_search_tools(): ] for search_tool in search_tools_from_db: + litellm_params_dict = dict(search_tool.get("litellm_params", {})) + masked_litellm_params_dict = _get_masked_values( + litellm_params_dict, + unmasked_length=4, + number_of_asterisks=4, + ) + search_tool_configs.append( SearchToolInfoResponse( search_tool_id=search_tool.get("search_tool_id"), search_tool_name=search_tool.get("search_tool_name", ""), - litellm_params=dict(search_tool.get("litellm_params", {})), + litellm_params=masked_litellm_params_dict, search_tool_info=search_tool.get("search_tool_info"), created_at=_convert_datetime_to_str(search_tool.get("created_at")), updated_at=_convert_datetime_to_str(search_tool.get("updated_at")), diff --git a/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py b/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py index 4cb85601c9b..c7e3fba94ee 100644 --- a/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py +++ b/tests/test_litellm/proxy/management_endpoints/search_endpoints/test_search_tool_management.py @@ -73,6 +73,10 @@ async def test_list_search_tools_db_only(monkeypatch): # Verify datetime conversion to ISO string assert tool["created_at"] == "2023-11-09T12:34:56" assert tool["updated_at"] == "2023-11-09T13:45:12" + # Verify masking of sensitive values + assert tool["litellm_params"]["api_key"] != "sk-test" + assert "****" in tool["litellm_params"]["api_key"] + assert tool["litellm_params"]["search_provider"] == "perplexity" finally: app.dependency_overrides.pop(user_api_key_auth, None) @@ -205,6 +209,10 @@ async def test_list_search_tools_filters_duplicate_config_tools(monkeypatch): assert db_tool is not None assert db_tool["is_from_config"] is False assert db_tool["search_tool_id"] == "db-id-1" + # Verify masking of sensitive values in DB tool + assert db_tool["litellm_params"]["api_key"] != "sk-db" + assert "****" in db_tool["litellm_params"]["api_key"] + assert db_tool["litellm_params"]["search_provider"] == "perplexity" # Verify unique config tool is present config_tool = next( @@ -302,6 +310,9 @@ async def test_list_search_tools_datetime_conversion(monkeypatch): assert tool1["created_at"] == "2024-01-15T10:30:45.123456" assert isinstance(tool1["updated_at"], str) assert tool1["updated_at"] == "2024-01-16T14:20:30.789012" + # Verify masking of sensitive values + assert tool1["litellm_params"]["api_key"] != "sk-test" + assert "****" in tool1["litellm_params"]["api_key"] # Test None handling for tool 2 tool2 = next( @@ -311,6 +322,9 @@ async def test_list_search_tools_datetime_conversion(monkeypatch): assert tool2 is not None assert tool2["created_at"] is None assert tool2["updated_at"] is None + # Verify masking of sensitive values + assert tool2["litellm_params"]["api_key"] != "tvly-test" + assert "****" in tool2["litellm_params"]["api_key"] # Test string passthrough for tool 3 tool3 = next( @@ -320,6 +334,9 @@ async def test_list_search_tools_datetime_conversion(monkeypatch): assert tool3 is not None assert tool3["created_at"] == "2024-01-17T08:15:00" assert tool3["updated_at"] == "2024-01-18T09:25:00" + # Verify masking of sensitive values + assert tool3["litellm_params"]["api_key"] != "sk-test" + assert "****" in tool3["litellm_params"]["api_key"] finally: app.dependency_overrides.pop(user_api_key_auth, None) @@ -369,6 +386,9 @@ async def test_list_search_tools_config_error_handling(monkeypatch): # Should only have DB tools since config failed assert len(data["search_tools"]) == 1 assert data["search_tools"][0]["search_tool_name"] == "db-tool-1" + # Verify masking of sensitive values + assert data["search_tools"][0]["litellm_params"]["api_key"] != "sk-test" + assert "****" in data["search_tools"][0]["litellm_params"]["api_key"] finally: app.dependency_overrides.pop(user_api_key_auth, None) @@ -391,3 +411,136 @@ async def test_list_search_tools_no_prisma_client(monkeypatch): assert "Prisma client not initialized" in data["detail"] finally: app.dependency_overrides.pop(user_api_key_auth, None) + + +@pytest.mark.asyncio +async def test_list_search_tools_db_masking_sensitive_values(monkeypatch): + """ + Test that sensitive values in DB search tools are properly masked. + This tests the new masking logic added for database search tools. + """ + # Mock DB tools with various sensitive fields + db_tools = [ + { + "search_tool_id": "test-id-1", + "search_tool_name": "perplexity-tool", + "litellm_params": { + "search_provider": "perplexity", + "api_key": "pplx-sk-1234567890abcdef", + "api_base": "https://api.perplexity.ai", + }, + "search_tool_info": {"description": "Perplexity tool"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + }, + { + "search_tool_id": "test-id-2", + "search_tool_name": "tavily-tool", + "litellm_params": { + "search_provider": "tavily", + "api_key": "tvly-secret-key-12345", + "api_base": "https://api.tavily.com", + }, + "search_tool_info": {"description": "Tavily tool"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + }, + { + "search_tool_id": "test-id-3", + "search_tool_name": "tool-with-token", + "litellm_params": { + "search_provider": "custom", + "access_token": "token-abcdefghijklmnop", + "secret_key": "secret-xyz123", + }, + "search_tool_info": {"description": "Tool with token"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + }, + { + "search_tool_id": "test-id-4", + "search_tool_name": "tool-with-non-sensitive", + "litellm_params": { + "search_provider": "custom", + "max_results": 10, + "timeout": 30, + }, + "search_tool_info": {"description": "Tool without sensitive fields"}, + "created_at": datetime(2023, 11, 9, 12, 34, 56), + "updated_at": datetime(2023, 11, 9, 13, 45, 12), + }, + ] + + # Mock SearchToolRegistry + mock_registry = MagicMock() + mock_registry.get_all_search_tools_from_db = AsyncMock(return_value=db_tools) + with patch( + "litellm.proxy.search_endpoints.search_tool_management.SEARCH_TOOL_REGISTRY", + mock_registry, + ): + # Mock prisma_client + mock_prisma = MagicMock() + with patch("litellm.proxy.proxy_server.prisma_client", mock_prisma): + # Mock proxy_config + mock_proxy_config = MagicMock() + mock_proxy_config.get_config = AsyncMock(return_value={}) + mock_proxy_config.parse_search_tools = MagicMock(return_value=None) + with patch("litellm.proxy.proxy_server.proxy_config", mock_proxy_config): + # Mock auth + from litellm.proxy.auth.user_api_key_auth import user_api_key_auth + + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin_user" + ) + + try: + test_client = TestClient(app) + response = test_client.get("/search_tools/list") + assert response.status_code == 200 + data = response.json() + assert "search_tools" in data + assert len(data["search_tools"]) == 4 + + # Test tool 1: api_key should be masked + tool1 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "perplexity-tool"), + None, + ) + assert tool1 is not None + assert tool1["litellm_params"]["api_key"] != "pplx-sk-1234567890abcdef" + assert "****" in tool1["litellm_params"]["api_key"] + assert tool1["litellm_params"]["search_provider"] == "perplexity" + assert tool1["litellm_params"]["api_base"] == "https://api.perplexity.ai" + + # Test tool 2: api_key should be masked + tool2 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "tavily-tool"), + None, + ) + assert tool2 is not None + assert tool2["litellm_params"]["api_key"] != "tvly-secret-key-12345" + assert "****" in tool2["litellm_params"]["api_key"] + assert tool2["litellm_params"]["search_provider"] == "tavily" + + # Test tool 3: access_token and secret_key should be masked + tool3 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "tool-with-token"), + None, + ) + assert tool3 is not None + assert tool3["litellm_params"]["access_token"] != "token-abcdefghijklmnop" + assert "****" in tool3["litellm_params"]["access_token"] + assert tool3["litellm_params"]["secret_key"] != "secret-xyz123" + assert "****" in tool3["litellm_params"]["secret_key"] + + # Test tool 4: non-sensitive fields should remain unmasked + tool4 = next( + (t for t in data["search_tools"] if t["search_tool_name"] == "tool-with-non-sensitive"), + None, + ) + assert tool4 is not None + assert tool4["litellm_params"]["max_results"] == 10 + assert tool4["litellm_params"]["timeout"] == 30 + assert tool4["litellm_params"]["search_provider"] == "custom" + finally: + app.dependency_overrides.pop(user_api_key_auth, None) From a50896f91e589616bac955f9c273a54408eff25c Mon Sep 17 00:00:00 2001 From: michelligabriele Date: Wed, 4 Feb 2026 01:15:04 +0100 Subject: [PATCH 056/511] fix: revert httpx client caching that caused closed client errors (#20025) AsyncHTTPHandler.__del__ was closing httpx clients still in use by AsyncOpenAI/AsyncAzureOpenAI due to independent cache lifecycles. Restores standalone httpx client creation for OpenAI/Azure providers. --- litellm/llms/openai/common_utils.py | 74 +++++-------------- tests/test_litellm/llms/test_lifecycle_fix.py | 46 ++++++++++++ 2 files changed, 64 insertions(+), 56 deletions(-) create mode 100644 tests/test_litellm/llms/test_lifecycle_fix.py diff --git a/litellm/llms/openai/common_utils.py b/litellm/llms/openai/common_utils.py index 8bcecd35232..d8107a9ce90 100644 --- a/litellm/llms/openai/common_utils.py +++ b/litellm/llms/openai/common_utils.py @@ -22,7 +22,6 @@ from litellm.llms.custom_httpx.http_handler import ( AsyncHTTPHandler, get_ssl_configuration, ) -from litellm.types.utils import LlmProviders class OpenAIError(BaseLLMException): @@ -205,67 +204,30 @@ class BaseOpenAILLM: if litellm.aclient_session is not None: return litellm.aclient_session - # Use the global cached client system to prevent memory leaks (issue #14540) - # This routes through get_async_httpx_client() which provides TTL-based caching - from litellm.llms.custom_httpx.http_handler import get_async_httpx_client + # Get unified SSL configuration + ssl_config = get_ssl_configuration() - try: - # Get SSL config and include in params for proper cache key - ssl_config = get_ssl_configuration() - params = {"ssl_verify": ssl_config} if ssl_config is not None else {} - params["disable_aiohttp_transport"] = litellm.disable_aiohttp_transport - - # Get a cached AsyncHTTPHandler which manages the httpx.AsyncClient - cached_handler = get_async_httpx_client( - llm_provider=LlmProviders.OPENAI, # Cache key includes provider - params=params, # Include SSL config in cache key + return httpx.AsyncClient( + verify=ssl_config, + transport=AsyncHTTPHandler._create_async_transport( + ssl_context=ssl_config + if isinstance(ssl_config, ssl.SSLContext) + else None, + ssl_verify=ssl_config if isinstance(ssl_config, bool) else None, shared_session=shared_session, - ) - # Return the underlying httpx client from the handler - return cached_handler.client - except (ImportError, AttributeError, KeyError) as e: - # Fallback to creating a client directly if caching system unavailable - # This preserves backwards compatibility - verbose_logger.debug( - f"Client caching unavailable ({type(e).__name__}), using direct client creation" - ) - ssl_config = get_ssl_configuration() - return httpx.AsyncClient( - verify=ssl_config, - transport=AsyncHTTPHandler._create_async_transport( - ssl_context=ssl_config - if isinstance(ssl_config, ssl.SSLContext) - else None, - ssl_verify=ssl_config if isinstance(ssl_config, bool) else None, - shared_session=shared_session, - ), - follow_redirects=True, - ) + ), + follow_redirects=True, + ) @staticmethod def _get_sync_http_client() -> Optional[httpx.Client]: if litellm.client_session is not None: return litellm.client_session - # Use the global cached client system to prevent memory leaks (issue #14540) - from litellm.llms.custom_httpx.http_handler import _get_httpx_client + # Get unified SSL configuration + ssl_config = get_ssl_configuration() - try: - # Get SSL config and include in params for proper cache key - ssl_config = get_ssl_configuration() - params = {"ssl_verify": ssl_config} if ssl_config is not None else None - - # Get a cached HTTPHandler which manages the httpx.Client - cached_handler = _get_httpx_client(params=params) - # Return the underlying httpx client from the handler - return cached_handler.client - except (ImportError, AttributeError, KeyError) as e: - # Fallback to creating a client directly if caching system unavailable - verbose_logger.debug( - f"Client caching unavailable ({type(e).__name__}), using direct client creation" - ) - ssl_config = get_ssl_configuration() - return httpx.Client( - verify=ssl_config, - follow_redirects=True, - ) + return httpx.Client( + verify=ssl_config, + follow_redirects=True, + ) diff --git a/tests/test_litellm/llms/test_lifecycle_fix.py b/tests/test_litellm/llms/test_lifecycle_fix.py new file mode 100644 index 00000000000..7b1876a3331 --- /dev/null +++ b/tests/test_litellm/llms/test_lifecycle_fix.py @@ -0,0 +1,46 @@ +""" +Verifies that the httpx client used by AsyncOpenAI is NOT closed +when AsyncHTTPHandler instances are garbage collected. +""" +import asyncio +import gc +import httpx +from litellm.llms.openai.common_utils import BaseOpenAILLM +from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler + + +async def test_httpx_client_not_closed_by_handler_gc(): + """ + Before the fix: _get_async_http_client() returned handler.client, + so when handler was GC'd its __del__ closed the client. + After the fix: returns a standalone httpx.AsyncClient, no handler involved. + """ + # Get the client the same way AsyncOpenAI would + client = BaseOpenAILLM._get_async_http_client() + assert isinstance(client, httpx.AsyncClient) + + # Simulate what the old code did: create an AsyncHTTPHandler and GC it + handler = AsyncHTTPHandler() + handler_client = handler.client + del handler + gc.collect() + + # The client from _get_async_http_client should still be open + # because it's NOT tied to any AsyncHTTPHandler + assert not client.is_closed, "Client was closed prematurely!" + + # Verify it can actually send (build a request without sending) + try: + req = client.build_request("GET", "https://example.com") + print("PASS: Client is still usable after handler GC") + except RuntimeError as e: + if "closed" in str(e): + print(f"FAIL: {e}") + raise + raise + + await client.aclose() + print("All checks passed!") + + +asyncio.run(test_httpx_client_not_closed_by_handler_gc()) From cf256c742f568de2dfd82ef40356bc61debc0722 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Tue, 3 Feb 2026 16:32:21 -0800 Subject: [PATCH 057/511] allow max_budget reset --- .../internal_user_endpoints.py | 5 ++++- .../test_internal_user_endpoints.py | 18 ++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/management_endpoints/internal_user_endpoints.py b/litellm/proxy/management_endpoints/internal_user_endpoints.py index 38a867d031b..636ed87d794 100644 --- a/litellm/proxy/management_endpoints/internal_user_endpoints.py +++ b/litellm/proxy/management_endpoints/internal_user_endpoints.py @@ -813,9 +813,12 @@ def _update_internal_user_params( data_json: dict, data: Union[UpdateUserRequest, UpdateUserRequestNoUserIDorEmail] ) -> dict: non_default_values = {} + fields_set = data.fields_set() if hasattr(data, 'fields_set') else set() + for k, v in data_json.items(): if k == "max_budget": - non_default_values[k] = v + if "max_budget" in fields_set: + non_default_values[k] = v elif ( v is not None and v diff --git a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py index dc436bac087..919af96f760 100644 --- a/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py +++ b/tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py @@ -1133,6 +1133,24 @@ def test_update_internal_user_params_ignores_other_nones(): assert non_default_values["max_budget"] == 100.0 +def test_update_internal_user_params_keeps_original_max_budget_when_not_provided(): + """ + Test that _update_internal_user_params does not include max_budget + when it's not provided in the request (should keep original value). + """ + # Create test data without max_budget + data_json = {"user_id": "test_user", "user_alias": "test_alias"} + data = UpdateUserRequest(user_id="test_user", user_alias="test_alias") + + # Call the function + non_default_values = _update_internal_user_params(data_json=data_json, data=data) + + # Assertions: max_budget should NOT be in non_default_values + assert "max_budget" not in non_default_values + assert "user_id" in non_default_values + assert "user_alias" in non_default_values + + def test_generate_request_base_validator(): """ Test that GenerateRequestBase validator converts empty string to None for max_budget From 831f89b9645b1dda632bfe1902f59accf9193a72 Mon Sep 17 00:00:00 2001 From: yuneng-jiang Date: Tue, 3 Feb 2026 18:19:33 -0800 Subject: [PATCH 058/511] unlimited budget ui changes --- .../src/components/user_edit_view.test.tsx | 504 ++++++++++++++++++ .../src/components/user_edit_view.tsx | 64 ++- 2 files changed, 558 insertions(+), 10 deletions(-) create mode 100644 ui/litellm-dashboard/src/components/user_edit_view.test.tsx diff --git a/ui/litellm-dashboard/src/components/user_edit_view.test.tsx b/ui/litellm-dashboard/src/components/user_edit_view.test.tsx new file mode 100644 index 00000000000..4bac32321a6 --- /dev/null +++ b/ui/litellm-dashboard/src/components/user_edit_view.test.tsx @@ -0,0 +1,504 @@ +import { screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { renderWithProviders } from "../../tests/test-utils"; +import { UserEditView } from "./user_edit_view"; + +vi.mock("./key_team_helpers/fetch_available_models_team_key", () => ({ + getModelDisplayName: vi.fn((model: string) => model), +})); + +vi.mock("../utils/roles", () => ({ + all_admin_roles: ["Admin", "Admin Viewer", "proxy_admin", "proxy_admin_viewer", "org_admin"], +})); + +vi.mock("antd", async (importOriginal) => { + const actual = await importOriginal(); + const React = await import("react"); + const SelectComponent = ({ + value, + onChange, + mode, + children, + placeholder, + disabled, + style, + allowClear, + ...props + }: any) => { + const isMultiple = mode === "multiple"; + const selectValue = isMultiple ? (Array.isArray(value) ? value : []) : value || ""; + return React.createElement( + "select", + { + multiple: isMultiple, + value: selectValue, + onChange: (e: React.ChangeEvent) => { + const selectedValues = Array.from(e.target.selectedOptions, (option) => option.value); + onChange(isMultiple ? selectedValues : selectedValues[0] || undefined); + }, + disabled, + placeholder, + style, + "aria-label": placeholder || "Select", + role: "combobox", + ...props, + }, + children, + ); + }; + SelectComponent.Option = ({ value: optionValue, children: optionChildren }: any) => + React.createElement("option", { value: optionValue }, optionChildren); + return { + ...actual, + Select: SelectComponent, + Tooltip: ({ children }: { children?: React.ReactNode }) => React.createElement(React.Fragment, null, children), + Checkbox: ({ checked, onChange, children, ...props }: any) => + React.createElement( + "label", + { style: { display: "flex", alignItems: "center", gap: "8px" } }, + React.createElement("input", { + type: "checkbox", + checked: checked, + onChange: (e: React.ChangeEvent) => onChange({ target: { checked: e.target.checked } }), + ...props, + }), + children, + ), + }; +}); + +vi.mock("@tremor/react", async (importOriginal) => { + const actual = await importOriginal(); + const React = await import("react"); + return { + ...actual, + SelectItem: ({ value, children, title }: any) => { + const childText = React.Children.toArray(children) + .map((child: any) => (typeof child === "string" ? child : child?.props?.children || "")) + .join(" "); + return React.createElement("option", { value, title }, childText || title || value); + }, + }; +}); + +describe("UserEditView", () => { + const MOCK_USER_DATA = { + user_id: "user-123", + user_info: { + user_email: "test@example.com", + user_alias: "Test User", + user_role: "proxy_admin", + models: ["gpt-4", "gpt-3.5-turbo"], + max_budget: 100.5, + budget_duration: "30d", + metadata: { + key1: "value1", + key2: "value2", + }, + }, + }; + + const MOCK_POSSIBLE_UI_ROLES = { + proxy_admin: { + ui_label: "Proxy Admin", + description: "Full access to proxy", + }, + proxy_admin_viewer: { + ui_label: "Proxy Admin Viewer", + description: "Read-only access", + }, + user: { + ui_label: "User", + description: "Standard user", + }, + }; + + const defaultProps = { + userData: MOCK_USER_DATA, + onCancel: vi.fn(), + onSubmit: vi.fn(), + teams: null, + accessToken: "test-token", + userID: "current-user-1", + userRole: "Admin", + userModels: ["gpt-4", "gpt-3.5-turbo", "claude-3"], + possibleUIRoles: MOCK_POSSIBLE_UI_ROLES, + isBulkEdit: false, + }; + + beforeEach(() => { + vi.clearAllMocks(); + }); + + it("should render", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + }); + + it("should display user ID field when not in bulk edit mode", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("User ID")).toBeInTheDocument(); + }); + + const userIdInput = screen.getByLabelText("User ID"); + expect(userIdInput).toBeDisabled(); + expect(userIdInput).toHaveValue("user-123"); + }); + + it("should not display user ID field when in bulk edit mode", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + + expect(screen.queryByLabelText("User ID")).not.toBeInTheDocument(); + }); + + it("should display email field when not in bulk edit mode", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("Email")).toBeInTheDocument(); + }); + + const emailInput = screen.getByLabelText("Email"); + expect(emailInput).toHaveValue("test@example.com"); + }); + + it("should not display email field when in bulk edit mode", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + + expect(screen.queryByLabelText("Email")).not.toBeInTheDocument(); + }); + + it("should display user alias field with initial value", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("User Alias")).toBeInTheDocument(); + }); + + const aliasInput = screen.getByLabelText("User Alias"); + expect(aliasInput).toHaveValue("Test User"); + }); + + it("should display personal models select with available models", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Personal Models")).toBeInTheDocument(); + }); + + const modelsSelect = screen.getByRole("combobox", { name: /select models/i }); + expect(modelsSelect).toBeInTheDocument(); + }); + + it("should disable models select when user role is not admin", async () => { + renderWithProviders(); + + await waitFor(() => { + const modelsSelect = screen.getByRole("combobox", { name: /select models/i }); + expect(modelsSelect).toBeDisabled(); + }); + }); + + it("should enable models select when user role is admin", async () => { + renderWithProviders(); + + await waitFor(() => { + const modelsSelect = screen.getByRole("combobox", { name: /select models/i }); + expect(modelsSelect).not.toBeDisabled(); + }); + }); + + it("should display max budget input field", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Max Budget (USD)")).toBeInTheDocument(); + }); + }); + + it("should display unlimited budget checkbox", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("Unlimited Budget")).toBeInTheDocument(); + }); + }); + + it("should set unlimited budget checkbox when max_budget is null", async () => { + const userDataWithNullBudget = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + max_budget: null, + }, + }; + + renderWithProviders(); + + await waitFor(() => { + const checkbox = screen.getByLabelText("Unlimited Budget"); + expect(checkbox).toBeChecked(); + }); + }); + + it("should disable budget input when unlimited budget is checked", async () => { + const userDataWithNullBudget = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + max_budget: null, + }, + }; + + renderWithProviders(); + + await waitFor(() => { + const budgetInput = screen.getByRole("spinbutton", { name: /max budget/i }); + expect(budgetInput).toBeDisabled(); + }); + }); + + it("should enable budget input when unlimited budget is unchecked", async () => { + renderWithProviders(); + + await waitFor(() => { + const budgetInput = screen.getByRole("spinbutton", { name: /max budget/i }); + expect(budgetInput).not.toBeDisabled(); + }); + }); + + it("should clear budget value when unlimited budget is checked", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("Unlimited Budget")).toBeInTheDocument(); + }); + + const checkbox = screen.getByLabelText("Unlimited Budget"); + await userEvent.click(checkbox); + + await waitFor(() => { + const budgetInput = screen.getByRole("spinbutton", { name: /max budget/i }); + expect(budgetInput).toHaveValue(null); + }); + }); + + it("should display metadata textarea with formatted JSON", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("Metadata")).toBeInTheDocument(); + }); + + const metadataTextarea = screen.getByLabelText("Metadata"); + const expectedJson = JSON.stringify(MOCK_USER_DATA.user_info.metadata, null, 2); + expect(metadataTextarea).toHaveValue(expectedJson); + }); + + it("should display empty metadata textarea when metadata is undefined", async () => { + const userDataWithoutMetadata = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + metadata: undefined, + }, + }; + + renderWithProviders(); + + await waitFor(() => { + const metadataTextarea = screen.getByLabelText("Metadata"); + expect(metadataTextarea).toHaveValue(""); + }); + }); + + it("should call onCancel when cancel button is clicked", async () => { + const onCancelMock = vi.fn(); + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /cancel/i })).toBeInTheDocument(); + }); + + const cancelButton = screen.getByRole("button", { name: /cancel/i }); + await userEvent.click(cancelButton); + + expect(onCancelMock).toHaveBeenCalledTimes(1); + }); + + it("should call onSubmit with form values when form is submitted", async () => { + const onSubmitMock = vi.fn(); + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(onSubmitMock).toHaveBeenCalled(); + }); + + const callArgs = onSubmitMock.mock.calls[0][0]; + expect(callArgs.user_id).toBe("user-123"); + expect(callArgs.user_email).toBe("test@example.com"); + expect(callArgs.user_alias).toBe("Test User"); + expect(callArgs.user_role).toBe("proxy_admin"); + expect(callArgs.models).toEqual(["gpt-4", "gpt-3.5-turbo"]); + expect(callArgs.max_budget).toBe(100.5); + expect(callArgs.budget_duration).toBe("30d"); + expect(callArgs.metadata).toEqual(MOCK_USER_DATA.user_info.metadata); + }); + + it("should set max_budget to null when unlimited budget is checked on submit", async () => { + const onSubmitMock = vi.fn(); + const userDataWithNullBudget = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + max_budget: null, + }, + }; + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(onSubmitMock).toHaveBeenCalled(); + }); + + const callArgs = onSubmitMock.mock.calls[0][0]; + expect(callArgs.max_budget).toBeNull(); + }); + + it("should require budget when unlimited budget is not checked", async () => { + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByText("Max Budget (USD)")).toBeInTheDocument(); + }); + + const budgetInput = screen.getByRole("spinbutton", { name: /max budget/i }); + await userEvent.clear(budgetInput); + + const checkbox = screen.getByLabelText("Unlimited Budget"); + expect(checkbox).not.toBeChecked(); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(screen.getByText("Please enter a budget or select Unlimited Budget")).toBeInTheDocument(); + }); + }); + + it("should allow submission when unlimited budget is checked even if budget is empty", async () => { + const onSubmitMock = vi.fn(); + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("Unlimited Budget")).toBeInTheDocument(); + }); + + const checkbox = screen.getByLabelText("Unlimited Budget"); + await userEvent.click(checkbox); + + await waitFor(() => { + expect(checkbox).toBeChecked(); + }); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(onSubmitMock).toHaveBeenCalled(); + }); + }); + + it("should update form values when userData changes", async () => { + const { rerender } = renderWithProviders(); + + await waitFor(() => { + expect(screen.getByLabelText("User Alias")).toHaveValue("Test User"); + }); + + const updatedUserData = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + user_alias: "Updated Alias", + }, + }; + + rerender(); + + await waitFor(() => { + expect(screen.getByLabelText("User Alias")).toHaveValue("Updated Alias"); + }); + }); + + it("should handle user data with empty models array", async () => { + const userDataWithEmptyModels = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + models: [], + }, + }; + + renderWithProviders(); + + await waitFor(() => { + expect(screen.getByRole("button", { name: /save changes/i })).toBeInTheDocument(); + }); + + const submitButton = screen.getByRole("button", { name: /save changes/i }); + await userEvent.click(submitButton); + + await waitFor(() => { + expect(defaultProps.onSubmit).toHaveBeenCalled(); + }); + + const callArgs = defaultProps.onSubmit.mock.calls[0][0]; + expect(callArgs.models).toEqual([]); + }); + + it("should handle user data with undefined max_budget", async () => { + const userDataWithUndefinedBudget = { + ...MOCK_USER_DATA, + user_info: { + ...MOCK_USER_DATA.user_info, + max_budget: undefined, + }, + }; + + renderWithProviders(); + + await waitFor(() => { + const checkbox = screen.getByLabelText("Unlimited Budget"); + expect(checkbox).toBeChecked(); + }); + }); +}); diff --git a/ui/litellm-dashboard/src/components/user_edit_view.tsx b/ui/litellm-dashboard/src/components/user_edit_view.tsx index 5a15cba91fc..e123b6aaddd 100644 --- a/ui/litellm-dashboard/src/components/user_edit_view.tsx +++ b/ui/litellm-dashboard/src/components/user_edit_view.tsx @@ -1,12 +1,11 @@ -import React from "react"; -import { Form, Select, Tooltip } from "antd"; -import NumericalInput from "./shared/numerical_input"; -import { TextInput, Textarea, SelectItem } from "@tremor/react"; -import { Button } from "@tremor/react"; -import { getModelDisplayName } from "./key_team_helpers/fetch_available_models_team_key"; -import { all_admin_roles } from "../utils/roles"; import { InfoCircleOutlined } from "@ant-design/icons"; +import { Button, SelectItem, TextInput, Textarea } from "@tremor/react"; +import { Checkbox, Form, Select, Tooltip } from "antd"; +import React, { useState } from "react"; +import { all_admin_roles } from "../utils/roles"; import BudgetDurationDropdown from "./common_components/budget_duration_dropdown"; +import { getModelDisplayName } from "./key_team_helpers/fetch_available_models_team_key"; +import NumericalInput from "./shared/numerical_input"; interface UserEditViewProps { userData: any; @@ -34,21 +33,34 @@ export function UserEditView({ isBulkEdit = false, }: UserEditViewProps) { const [form] = Form.useForm(); + const [unlimitedBudget, setUnlimitedBudget] = useState(false); // Set initial form values React.useEffect(() => { + const maxBudget = userData.user_info?.max_budget; + const isUnlimited = maxBudget === null || maxBudget === undefined; + setUnlimitedBudget(isUnlimited); + form.setFieldsValue({ user_id: userData.user_id, user_email: userData.user_info?.user_email, user_alias: userData.user_info?.user_alias, user_role: userData.user_info?.user_role, models: userData.user_info?.models || [], - max_budget: userData.user_info?.max_budget, + max_budget: isUnlimited ? "" : maxBudget, budget_duration: userData.user_info?.budget_duration, metadata: userData.user_info?.metadata ? JSON.stringify(userData.user_info.metadata, null, 2) : undefined, }); }, [userData, form]); + const handleUnlimitedBudgetChange = (e: any) => { + const checked = e.target.checked; + setUnlimitedBudget(checked); + if (checked) { + form.setFieldsValue({ max_budget: "" }); + } + }; + const handleSubmit = (values: any) => { // Convert metadata back to an object if it exists and is a string if (values.metadata && typeof values.metadata === "string") { @@ -60,6 +72,10 @@ export function UserEditView({ } } + if (unlimitedBudget || values.max_budget === "" || values.max_budget === undefined) { + values.max_budget = null; + } + onSubmit(values); }; @@ -138,8 +154,36 @@ export function UserEditView({ - - + + Max Budget (USD) + + Unlimited Budget + +
+ } + name="max_budget" + rules={[ + { + validator: (_, value) => { + if (!unlimitedBudget && (value === "" || value === null || value === undefined)) { + return Promise.reject(new Error("Please enter a budget or select Unlimited Budget")); + } + return Promise.resolve(); + }, + }, + ]} + > + From 66eadfabe466f1f59b62c8afe2da9529ec248508 Mon Sep 17 00:00:00 2001 From: Ishaan Jaff Date: Tue, 3 Feb 2026 19:13:13 -0800 Subject: [PATCH 059/511] [Bug] Ensure MCP permissions are enforced when using JWT Auth (#20383) * fix: enforce team MCP permissions when using JWT authentication Root cause: When JWT auth was used with teams in groups (via team_ids_jwt_field), the team's MCP permissions were not being enforced because: 1. The default team_allowed_routes did not include mcp_routes 2. allowed_routes_check() failed for MCP endpoints like /mcp/tools/list 3. find_team_with_model_access() skipped the team due to failed route check 4. team_id was None in UserAPIKeyAuth 5. MCPRequestHandler._get_allowed_mcp_servers_for_team() returned empty list Fix: Add 'mcp_routes' to the default team_allowed_routes in LiteLLM_JWTAuth. This ensures that teams can access MCP endpoints by default, allowing the team's MCP server permissions to be properly enforced. Added tests: - test_reproduce_jwt_mcp_enforcement_issue: Reproduces the exact bug scenario - test_verify_mcp_routes_in_default_team_allowed_routes: Verifies fix - test_mcp_route_check_passes_for_team: Verifies route check works Co-authored-by: ishaan * test: add comprehensive E2E tests for JWT + team MCP permission enforcement Added tests: - test_e2e_jwt_team_mcp_permissions_enforced: Full E2E test verifying JWT auth with teams in groups properly sets team_id and MCPRequestHandler returns the team's MCP servers - test_e2e_jwt_without_team_no_mcp_servers: Verifies no MCP servers returned when JWT has no teams - test_e2e_jwt_team_mcp_key_intersection: Verifies intersection logic when both key and team have MCP permissions (result = intersection) These tests verify the complete flow: 1. JWT token with team in groups field 2. JWT auth properly sets team_id on UserAPIKeyAuth 3. MCPRequestHandler.get_allowed_mcp_servers() returns team's MCP servers 4. Key/team permission intersection works correctly Co-authored-by: ishaan * test: add simple tests for JWT + MCP permission enforcement Simple, focused tests that validate: 1. test_simple_jwt_mcp_permissions_enforced: JWT user with team gets team's MCP servers 2. test_simple_jwt_no_team_no_mcp_servers: JWT user without team gets no MCP servers 3. test_simple_jwt_team_id_required_for_mcp_permissions: Verifies team_id is required 4. test_jwt_auth_sets_team_id_for_mcp_route: JWT auth sets team_id for MCP routes These tests directly verify the core MCP permission enforcement logic works when using JWT authentication with teams. Co-authored-by: ishaan * Add test: MCP route without model still returns team_id Co-authored-by: ishaan * Add 2 debug logs for JWT+MCP troubleshooting - handle_jwt.py: Log team route check result (team_id, route, is_allowed) - user_api_key_auth_mcp.py: Log team_id when looking up MCP permissions Co-authored-by: ishaan --------- Co-authored-by: Cursor Agent Co-authored-by: ishaan --- .../mcp_server/auth/user_api_key_auth_mcp.py | 3 + litellm/proxy/_types.py | 2 +- litellm/proxy/auth/handle_jwt.py | 3 + .../mcp_server/test_jwt_mcp_enforcement.py | 480 ++++++++++++++++++ .../mcp_server/test_jwt_mcp_simple.py | 277 ++++++++++ 5 files changed, 764 insertions(+), 1 deletion(-) create mode 100644 tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_enforcement.py create mode 100644 tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_simple.py diff --git a/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py b/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py index 49d6ac7d898..7e70b5baae4 100644 --- a/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py +++ b/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py @@ -387,6 +387,9 @@ class MCPRequestHandler: user_api_key_cache, ) + verbose_logger.debug( + f"MCP team permission lookup: team_id={user_api_key_auth.team_id if user_api_key_auth else None}" + ) if not user_api_key_auth or not user_api_key_auth.team_id or not prisma_client: return None diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 9ae95085f55..131a6caab07 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -3673,7 +3673,7 @@ class LiteLLM_JWTAuth(LiteLLMPydanticObjectBase): team_id_upsert: bool = False team_ids_jwt_field: Optional[str] = None upsert_sso_user_to_team: bool = False - team_allowed_routes: List[str] = ["openai_routes", "info_routes"] + team_allowed_routes: List[str] = ["openai_routes", "info_routes", "mcp_routes"] team_id_default: Optional[str] = Field( default=None, description="If no team_id given, default permissions/spend-tracking to this team.s", diff --git a/litellm/proxy/auth/handle_jwt.py b/litellm/proxy/auth/handle_jwt.py index 33667b5d8d9..584be0a9496 100644 --- a/litellm/proxy/auth/handle_jwt.py +++ b/litellm/proxy/auth/handle_jwt.py @@ -976,6 +976,9 @@ class JWTAuthManager: user_route=route, litellm_proxy_roles=jwt_handler.litellm_jwtauth, ) + verbose_proxy_logger.debug( + f"JWT team route check: team_id={team_id}, route={route}, is_allowed={is_allowed}" + ) if is_allowed: return team_id, team_object except Exception: diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_enforcement.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_enforcement.py new file mode 100644 index 00000000000..b4a5a8ca19b --- /dev/null +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_enforcement.py @@ -0,0 +1,480 @@ +""" +Test to verify Team MCP permissions are enforced when using JWT authentication. + +Scenario: +1. Team "ABC" exists with models configured and MCPs assigned +2. User JWT has team "ABC" in groups (via team_ids_jwt_field) +3. Call MCP list endpoint +4. EXPECTED: Team MCP permissions should be enforced +""" + +import pytest +from unittest.mock import AsyncMock, MagicMock, patch + +from litellm.proxy._types import ( + LiteLLM_JWTAuth, + LiteLLM_TeamTable, + LiteLLM_ObjectPermissionTable, + UserAPIKeyAuth, +) +from litellm.proxy.auth.handle_jwt import JWTAuthManager, JWTHandler +from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import ( + MCPRequestHandler, +) +from litellm.proxy._experimental.mcp_server.mcp_server_manager import MCPServerManager + + +@pytest.mark.asyncio +async def test_reproduce_jwt_mcp_enforcement_issue(monkeypatch): + """ + Reproduce the bug where Team MCP permissions are NOT enforced when using JWT. + + Setup: + - Team "ABC" has models ["gpt-4"] and MCPs ["mcp-server-1"] assigned + - JWT has team "ABC" in groups field + - User calls MCP list endpoint (no model requested) + + Expected: team_id should be set to "ABC" so MCP permissions are enforced + Actual (BUG): team_id is None because route check fails for MCP routes + """ + from litellm.caching import DualCache + from litellm.proxy.utils import ProxyLogging + from litellm.router import Router + + # Setup mock router + router = Router(model_list=[{"model_name": "gpt-4", "litellm_params": {"model": "gpt-4"}}]) + import sys + import types + proxy_server_module = types.ModuleType("proxy_server") + proxy_server_module.llm_router = router + monkeypatch.setitem(sys.modules, "litellm.proxy.proxy_server", proxy_server_module) + + # Team "ABC" has models configured AND MCPs assigned + team_with_mcp = LiteLLM_TeamTable( + team_id="ABC", + models=["gpt-4"], # Team HAS models + object_permission=LiteLLM_ObjectPermissionTable( + object_permission_id="perm-123", + mcp_servers=["mcp-server-1"], # Team has MCPs assigned + ), + ) + + async def mock_get_team_object(*args, **kwargs): + team_id = kwargs.get("team_id") or args[0] + if team_id == "ABC": + return team_with_mcp + return None + + monkeypatch.setattr( + "litellm.proxy.auth.handle_jwt.get_team_object", mock_get_team_object + ) + + # Setup JWT handler with team_ids_jwt_field (groups) + jwt_handler = JWTHandler() + jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth( + team_ids_jwt_field="groups", # Use groups field for teams + # NOTE: team_allowed_routes defaults to ["openai_routes", "info_routes"] + # which does NOT include "mcp_routes" + ) + + user_api_key_cache = DualCache() + proxy_logging_obj = ProxyLogging(user_api_key_cache=user_api_key_cache) + + # Simulate JWT payload with team in groups + jwt_token = { + "sub": "user-123", + "groups": ["ABC"], # Team "ABC" is in groups + "scope": "", + } + + # Mock auth_jwt to return our token + with patch.object(jwt_handler, "auth_jwt", new_callable=AsyncMock) as mock_auth_jwt: + mock_auth_jwt.return_value = jwt_token + + # Call auth_builder for MCP route (like /mcp/tools/list) + result = await JWTAuthManager.auth_builder( + api_key="test-jwt-token", + jwt_handler=jwt_handler, + request_data={}, # No model in request (MCP endpoint) + general_settings={}, + route="/mcp/tools/list", # MCP route + prisma_client=None, + user_api_key_cache=user_api_key_cache, + parent_otel_span=None, + proxy_logging_obj=proxy_logging_obj, + ) + + # THIS IS THE BUG: team_id should be "ABC" but it's None! + print(f"Result team_id: {result['team_id']}") + print(f"Result team_object: {result['team_object']}") + + # The test should FAIL if the bug exists (team_id is None) + # If the fix is applied, team_id should be "ABC" + assert result["team_id"] == "ABC", ( + f"BUG: team_id should be 'ABC' but got '{result['team_id']}'. " + f"This happens because default team_allowed_routes does not include 'mcp_routes', " + f"so allowed_routes_check() fails and the team is skipped in find_team_with_model_access()." + ) + + +@pytest.mark.asyncio +async def test_verify_mcp_routes_in_default_team_allowed_routes(): + """ + Verify that mcp_routes IS in the default team_allowed_routes. + This is required for team MCP permissions to work with JWT auth. + """ + default_jwt_auth = LiteLLM_JWTAuth() + + print(f"Default team_allowed_routes: {default_jwt_auth.team_allowed_routes}") + + # mcp_routes must be in defaults for team MCP permissions to work + assert "mcp_routes" in default_jwt_auth.team_allowed_routes, ( + "mcp_routes must be in default team_allowed_routes for JWT MCP enforcement to work" + ) + + +@pytest.mark.asyncio +async def test_mcp_route_check_passes_for_team(): + """ + Verify that allowed_routes_check returns True for MCP routes with default settings. + This is required for teams to access MCP endpoints with JWT auth. + """ + from litellm.proxy._types import LitellmUserRoles + from litellm.proxy.auth.auth_checks import allowed_routes_check + + jwt_auth = LiteLLM_JWTAuth() # Use defaults + + # Check if MCP route is allowed for TEAM role + is_allowed = allowed_routes_check( + user_role=LitellmUserRoles.TEAM, + user_route="/mcp/tools/list", + litellm_proxy_roles=jwt_auth, + ) + + print(f"Is /mcp/tools/list allowed for TEAM with defaults? {is_allowed}") + + # MCP routes should be allowed by default for teams + assert is_allowed is True, ( + "MCP routes must be allowed by default for teams for JWT MCP enforcement to work" + ) + + +@pytest.mark.asyncio +async def test_e2e_jwt_team_mcp_permissions_enforced(monkeypatch): + """ + End-to-end test verifying that team MCP permissions are properly enforced + when using JWT authentication with teams in groups. + + This test verifies the complete flow: + 1. JWT token contains team "ABC" in groups field + 2. Team "ABC" exists with MCP servers ["mcp-server-1", "mcp-server-2"] assigned + 3. JWT auth properly sets team_id on UserAPIKeyAuth + 4. MCPRequestHandler.get_allowed_mcp_servers() returns team's MCP servers + """ + from litellm.caching import DualCache + from litellm.proxy.utils import ProxyLogging + from litellm.router import Router + + # Setup mock router + router = Router(model_list=[{"model_name": "gpt-4", "litellm_params": {"model": "gpt-4"}}]) + import sys + import types + proxy_server_module = types.ModuleType("proxy_server") + proxy_server_module.llm_router = router + proxy_server_module.prisma_client = MagicMock() # Mock prisma client + proxy_server_module.user_api_key_cache = DualCache() + proxy_server_module.proxy_logging_obj = MagicMock() + monkeypatch.setitem(sys.modules, "litellm.proxy.proxy_server", proxy_server_module) + + # Team "ABC" has MCP servers assigned via object_permission + team_mcp_servers = ["mcp-server-1", "mcp-server-2"] + team_object_permission = LiteLLM_ObjectPermissionTable( + object_permission_id="perm-abc-123", + mcp_servers=team_mcp_servers, + mcp_access_groups=[], + vector_stores=[], + ) + + team_with_mcp = LiteLLM_TeamTable( + team_id="ABC", + models=["gpt-4"], + object_permission=team_object_permission, + object_permission_id="perm-abc-123", + ) + + async def mock_get_team_object(*args, **kwargs): + team_id = kwargs.get("team_id") or (args[0] if args else None) + if team_id == "ABC": + return team_with_mcp + return None + + monkeypatch.setattr( + "litellm.proxy.auth.handle_jwt.get_team_object", mock_get_team_object + ) + monkeypatch.setattr( + "litellm.proxy.auth.auth_checks.get_team_object", mock_get_team_object + ) + + # Setup JWT handler with team_ids_jwt_field (groups) + jwt_handler = JWTHandler() + jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth( + team_ids_jwt_field="groups", + ) + + user_api_key_cache = DualCache() + proxy_logging_obj = ProxyLogging(user_api_key_cache=user_api_key_cache) + + # Simulate JWT payload with team in groups + jwt_token = { + "sub": "user-123", + "groups": ["ABC"], + "scope": "", + } + + # Step 1: Verify JWT auth returns correct team_id + with patch.object(jwt_handler, "auth_jwt", new_callable=AsyncMock) as mock_auth_jwt: + mock_auth_jwt.return_value = jwt_token + + result = await JWTAuthManager.auth_builder( + api_key="test-jwt-token", + jwt_handler=jwt_handler, + request_data={}, + general_settings={}, + route="/mcp/tools/list", + prisma_client=None, + user_api_key_cache=user_api_key_cache, + parent_otel_span=None, + proxy_logging_obj=proxy_logging_obj, + ) + + # Verify team_id is set correctly + assert result["team_id"] == "ABC", f"Expected team_id='ABC', got '{result['team_id']}'" + assert result["team_object"] is not None, "team_object should not be None" + + # Step 2: Create UserAPIKeyAuth with the team_id from JWT auth + user_api_key_auth = UserAPIKeyAuth( + api_key=None, + team_id=result["team_id"], + user_id=result["user_id"], + ) + + # Step 3: Verify MCPRequestHandler returns team's MCP servers + # Mock _get_team_object_permission to return our team's object_permission + with patch.object( + MCPRequestHandler, "_get_team_object_permission" + ) as mock_get_team_perm: + mock_get_team_perm.return_value = team_object_permission + + # Mock _get_allowed_mcp_servers_for_key to return empty (no key-level permissions) + with patch.object( + MCPRequestHandler, "_get_allowed_mcp_servers_for_key" + ) as mock_key_servers: + mock_key_servers.return_value = [] + + # Mock _get_mcp_servers_from_access_groups to return empty + with patch.object( + MCPRequestHandler, "_get_mcp_servers_from_access_groups" + ) as mock_access_groups: + mock_access_groups.return_value = [] + + allowed_servers = await MCPRequestHandler.get_allowed_mcp_servers( + user_api_key_auth + ) + + print(f"Allowed MCP servers: {allowed_servers}") + + # Verify team's MCP servers are returned + assert set(allowed_servers) == set(team_mcp_servers), ( + f"Expected team MCP servers {team_mcp_servers}, got {allowed_servers}" + ) + + +@pytest.mark.asyncio +async def test_e2e_jwt_without_team_no_mcp_servers(monkeypatch): + """ + End-to-end test verifying that when JWT has no teams, no MCP servers are returned. + + This ensures: + 1. JWT token with no groups returns no team_id + 2. MCPRequestHandler.get_allowed_mcp_servers() returns empty list + """ + from litellm.caching import DualCache + from litellm.proxy.utils import ProxyLogging + from litellm.router import Router + + # Setup mock router + router = Router(model_list=[]) + import sys + import types + proxy_server_module = types.ModuleType("proxy_server") + proxy_server_module.llm_router = router + monkeypatch.setitem(sys.modules, "litellm.proxy.proxy_server", proxy_server_module) + + async def mock_get_team_object(*args, **kwargs): + return None + + monkeypatch.setattr( + "litellm.proxy.auth.handle_jwt.get_team_object", mock_get_team_object + ) + + # Setup JWT handler + jwt_handler = JWTHandler() + jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth( + team_ids_jwt_field="groups", + ) + + user_api_key_cache = DualCache() + proxy_logging_obj = ProxyLogging(user_api_key_cache=user_api_key_cache) + + # JWT payload with empty groups + jwt_token = { + "sub": "user-123", + "groups": [], # No teams + "scope": "", + } + + with patch.object(jwt_handler, "auth_jwt", new_callable=AsyncMock) as mock_auth_jwt: + mock_auth_jwt.return_value = jwt_token + + result = await JWTAuthManager.auth_builder( + api_key="test-jwt-token", + jwt_handler=jwt_handler, + request_data={}, + general_settings={}, + route="/mcp/tools/list", + prisma_client=None, + user_api_key_cache=user_api_key_cache, + parent_otel_span=None, + proxy_logging_obj=proxy_logging_obj, + ) + + # Verify no team_id is set + assert result["team_id"] is None, f"Expected team_id=None, got '{result['team_id']}'" + + # Create UserAPIKeyAuth without team_id + user_api_key_auth = UserAPIKeyAuth( + api_key=None, + team_id=None, + user_id=result["user_id"], + ) + + # Verify no MCP servers are returned when there's no team + allowed_servers = await MCPRequestHandler._get_allowed_mcp_servers_for_team( + user_api_key_auth + ) + + assert allowed_servers == [], f"Expected empty list, got {allowed_servers}" + + +@pytest.mark.asyncio +async def test_e2e_jwt_team_mcp_key_intersection(monkeypatch): + """ + End-to-end test verifying MCP permission intersection between key and team. + + Scenario: + - Team has MCP servers: ["server-1", "server-2", "server-3"] + - Key has MCP servers: ["server-2", "server-4"] + - Result should be intersection: ["server-2"] + """ + from litellm.caching import DualCache + from litellm.proxy.utils import ProxyLogging + from litellm.router import Router + + # Setup mock router + router = Router(model_list=[{"model_name": "gpt-4", "litellm_params": {"model": "gpt-4"}}]) + import sys + import types + proxy_server_module = types.ModuleType("proxy_server") + proxy_server_module.llm_router = router + proxy_server_module.prisma_client = MagicMock() + proxy_server_module.user_api_key_cache = DualCache() + proxy_server_module.proxy_logging_obj = MagicMock() + monkeypatch.setitem(sys.modules, "litellm.proxy.proxy_server", proxy_server_module) + + # Team MCP servers + team_mcp_servers = ["server-1", "server-2", "server-3"] + team_object_permission = LiteLLM_ObjectPermissionTable( + object_permission_id="team-perm", + mcp_servers=team_mcp_servers, + ) + + team_with_mcp = LiteLLM_TeamTable( + team_id="TEAM-X", + models=["gpt-4"], + object_permission=team_object_permission, + ) + + # Key MCP servers + key_mcp_servers = ["server-2", "server-4"] + key_object_permission = LiteLLM_ObjectPermissionTable( + object_permission_id="key-perm", + mcp_servers=key_mcp_servers, + ) + + async def mock_get_team_object(*args, **kwargs): + team_id = kwargs.get("team_id") or (args[0] if args else None) + if team_id == "TEAM-X": + return team_with_mcp + return None + + monkeypatch.setattr( + "litellm.proxy.auth.handle_jwt.get_team_object", mock_get_team_object + ) + + jwt_handler = JWTHandler() + jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth(team_ids_jwt_field="groups") + + user_api_key_cache = DualCache() + proxy_logging_obj = ProxyLogging(user_api_key_cache=user_api_key_cache) + + jwt_token = {"sub": "user-123", "groups": ["TEAM-X"], "scope": ""} + + with patch.object(jwt_handler, "auth_jwt", new_callable=AsyncMock) as mock_auth_jwt: + mock_auth_jwt.return_value = jwt_token + + result = await JWTAuthManager.auth_builder( + api_key="test-jwt-token", + jwt_handler=jwt_handler, + request_data={}, + general_settings={}, + route="/mcp/tools/list", + prisma_client=None, + user_api_key_cache=user_api_key_cache, + parent_otel_span=None, + proxy_logging_obj=proxy_logging_obj, + ) + + assert result["team_id"] == "TEAM-X" + + user_api_key_auth = UserAPIKeyAuth( + api_key=None, + team_id=result["team_id"], + user_id=result["user_id"], + object_permission=key_object_permission, # Key has its own permissions + ) + + # Mock the helper methods to return our test data + with patch.object( + MCPRequestHandler, "_get_team_object_permission" + ) as mock_team_perm: + mock_team_perm.return_value = team_object_permission + + with patch.object( + MCPRequestHandler, "_get_key_object_permission" + ) as mock_key_perm: + mock_key_perm.return_value = key_object_permission + + with patch.object( + MCPRequestHandler, "_get_mcp_servers_from_access_groups" + ) as mock_access_groups: + mock_access_groups.return_value = [] + + allowed_servers = await MCPRequestHandler.get_allowed_mcp_servers( + user_api_key_auth + ) + + # Should be intersection: only server-2 is in both + expected = ["server-2"] + assert sorted(allowed_servers) == sorted(expected), ( + f"Expected intersection {expected}, got {allowed_servers}" + ) diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_simple.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_simple.py new file mode 100644 index 00000000000..9ad7736d014 --- /dev/null +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_jwt_mcp_simple.py @@ -0,0 +1,277 @@ +""" +Simple test to validate MCP permissions are enforced when calling MCP routes with JWT. +""" + +import pytest +from unittest.mock import AsyncMock, MagicMock, patch + +from litellm.proxy._types import ( + LiteLLM_JWTAuth, + LiteLLM_TeamTable, + LiteLLM_ObjectPermissionTable, + UserAPIKeyAuth, +) + + +@pytest.mark.asyncio +async def test_simple_jwt_mcp_permissions_enforced(): + """ + Simple test: Call MCP route with JWT, verify team's MCP servers are returned. + + Setup: + - Team "my-team" has MCP servers: ["github-mcp", "slack-mcp"] + - JWT user belongs to "my-team" + + Expected: Only ["github-mcp", "slack-mcp"] should be allowed + """ + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import ( + MCPRequestHandler, + ) + + # 1. Create a user authenticated via JWT with team_id set + user_auth = UserAPIKeyAuth( + api_key=None, # JWT auth doesn't have api_key + user_id="jwt-user-123", + team_id="my-team", # This is set by JWT auth when team is in groups + ) + + # 2. Team's MCP permissions + team_mcp_servers = ["github-mcp", "slack-mcp"] + team_object_permission = LiteLLM_ObjectPermissionTable( + object_permission_id="perm-123", + mcp_servers=team_mcp_servers, + ) + + # 3. Mock the team permission lookup + with patch.object( + MCPRequestHandler, "_get_team_object_permission", new_callable=AsyncMock + ) as mock_team_perm: + mock_team_perm.return_value = team_object_permission + + # Mock key permissions (empty - user has no key-level MCP permissions) + with patch.object( + MCPRequestHandler, "_get_key_object_permission", new_callable=AsyncMock + ) as mock_key_perm: + mock_key_perm.return_value = None + + # Mock access groups (empty) + with patch.object( + MCPRequestHandler, "_get_mcp_servers_from_access_groups", new_callable=AsyncMock + ) as mock_access_groups: + mock_access_groups.return_value = [] + + # 4. Call get_allowed_mcp_servers - this is what MCP routes use + allowed = await MCPRequestHandler.get_allowed_mcp_servers(user_auth) + + # 5. Verify only team's MCP servers are returned + assert sorted(allowed) == sorted(team_mcp_servers), ( + f"Expected {team_mcp_servers}, got {allowed}" + ) + + # Verify team permission was looked up + mock_team_perm.assert_called_once_with(user_auth) + + +@pytest.mark.asyncio +async def test_simple_jwt_no_team_no_mcp_servers(): + """ + Simple test: JWT user with no team should get no MCP servers. + """ + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import ( + MCPRequestHandler, + ) + + # User with no team_id (JWT didn't have teams in groups) + user_auth = UserAPIKeyAuth( + api_key=None, + user_id="jwt-user-no-team", + team_id=None, # No team + ) + + # _get_allowed_mcp_servers_for_team returns [] when team_id is None + allowed = await MCPRequestHandler._get_allowed_mcp_servers_for_team(user_auth) + + assert allowed == [], f"Expected [], got {allowed}" + + +@pytest.mark.asyncio +async def test_simple_jwt_team_id_required_for_mcp_permissions(): + """ + Simple test: Verify that team_id must be set for team MCP permissions to work. + + This is the key insight - if JWT auth doesn't set team_id, + team MCP permissions won't be enforced. + """ + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import ( + MCPRequestHandler, + ) + + # Case 1: team_id is set -> team permissions should be checked + user_with_team = UserAPIKeyAuth( + api_key=None, + user_id="user-1", + team_id="team-abc", + ) + + team_mcp_servers = ["server-1", "server-2"] + team_perm = LiteLLM_ObjectPermissionTable( + object_permission_id="perm-1", + mcp_servers=team_mcp_servers, + ) + + with patch.object( + MCPRequestHandler, "_get_team_object_permission", new_callable=AsyncMock + ) as mock_perm: + mock_perm.return_value = team_perm + + with patch.object( + MCPRequestHandler, "_get_mcp_servers_from_access_groups", new_callable=AsyncMock + ) as mock_groups: + mock_groups.return_value = [] + + result = await MCPRequestHandler._get_allowed_mcp_servers_for_team(user_with_team) + + assert sorted(result) == sorted(team_mcp_servers) + mock_perm.assert_called_once() # Permission WAS checked + + # Case 2: team_id is None -> team permissions NOT checked + user_without_team = UserAPIKeyAuth( + api_key=None, + user_id="user-2", + team_id=None, + ) + + result = await MCPRequestHandler._get_allowed_mcp_servers_for_team(user_without_team) + assert result == [] # No permissions returned + + +@pytest.mark.asyncio +async def test_jwt_auth_sets_team_id_for_mcp_route(): + """ + Test that JWT auth properly sets team_id when accessing MCP routes. + + This is the critical test - when user calls /mcp/tools/list with JWT, + the team_id from JWT groups must be set on UserAPIKeyAuth. + """ + from litellm.proxy.auth.handle_jwt import JWTAuthManager, JWTHandler + from litellm.caching import DualCache + from litellm.proxy.utils import ProxyLogging + + # Setup + jwt_handler = JWTHandler() + jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth( + team_ids_jwt_field="groups", # Teams come from "groups" field in JWT + ) + + # Team exists with models + team = LiteLLM_TeamTable( + team_id="team-from-jwt", + models=["gpt-4"], + ) + + user_api_key_cache = DualCache() + proxy_logging_obj = ProxyLogging(user_api_key_cache=user_api_key_cache) + + # Mock JWT token with team in groups + jwt_payload = { + "sub": "user-123", + "groups": ["team-from-jwt"], + "scope": "", + } + + with patch.object(jwt_handler, "auth_jwt", new_callable=AsyncMock) as mock_auth: + mock_auth.return_value = jwt_payload + + with patch( + "litellm.proxy.auth.handle_jwt.get_team_object", new_callable=AsyncMock + ) as mock_get_team: + mock_get_team.return_value = team + + # Simulate calling MCP route + result = await JWTAuthManager.auth_builder( + api_key="jwt-token", + jwt_handler=jwt_handler, + request_data={}, + general_settings={}, + route="/mcp/tools/list", # MCP route + prisma_client=None, + user_api_key_cache=user_api_key_cache, + parent_otel_span=None, + proxy_logging_obj=proxy_logging_obj, + ) + + # THE KEY ASSERTION: team_id must be set + assert result["team_id"] == "team-from-jwt", ( + f"team_id should be 'team-from-jwt' but got '{result['team_id']}'. " + "This means JWT auth is not properly setting team_id for MCP routes!" + ) + + +@pytest.mark.asyncio +async def test_mcp_route_without_model_still_returns_team_id(): + """ + Test that MCP routes (which don't specify a model) still get team_id assigned. + + Key insight: MCP routes don't require a model in the request, but the JWT auth + flow must still assign a team_id so that team MCP permissions are enforced. + + The flow is: + 1. JWT token contains team in "groups" field + 2. find_team_with_model_access() is called with requested_model=None + 3. Since `not requested_model` is True, model check passes + 4. Route check passes because "mcp_routes" is in team_allowed_routes + 5. team_id is returned and set on UserAPIKeyAuth + """ + from litellm.proxy.auth.handle_jwt import JWTAuthManager, JWTHandler + from litellm.caching import DualCache + from litellm.proxy.utils import ProxyLogging + + # Setup + jwt_handler = JWTHandler() + jwt_handler.litellm_jwtauth = LiteLLM_JWTAuth( + team_ids_jwt_field="groups", + ) + + # Team exists - note: models is a list (can be empty or have values) + # The key is that when no model is requested, model check is skipped + team = LiteLLM_TeamTable( + team_id="my-team", + models=["gpt-4", "gpt-3.5-turbo"], # Team has models, but MCP request won't specify one + ) + + user_api_key_cache = DualCache() + proxy_logging_obj = ProxyLogging(user_api_key_cache=user_api_key_cache) + + # JWT with team in groups + jwt_payload = { + "sub": "user-abc", + "groups": ["my-team"], + "scope": "", + } + + with patch.object(jwt_handler, "auth_jwt", new_callable=AsyncMock) as mock_auth: + mock_auth.return_value = jwt_payload + + with patch( + "litellm.proxy.auth.handle_jwt.get_team_object", new_callable=AsyncMock + ) as mock_get_team: + mock_get_team.return_value = team + + # Call MCP route with NO MODEL in request_data + result = await JWTAuthManager.auth_builder( + api_key="jwt-token", + jwt_handler=jwt_handler, + request_data={}, # <-- NO MODEL SPECIFIED + general_settings={}, + route="/mcp/tools/list", # MCP route + prisma_client=None, + user_api_key_cache=user_api_key_cache, + parent_otel_span=None, + proxy_logging_obj=proxy_logging_obj, + ) + + # Team ID must still be set even though no model was requested + assert result["team_id"] == "my-team", ( + f"Expected team_id='my-team' but got '{result['team_id']}'. " + "MCP routes without model should still get team_id from JWT!" + ) From 0cb6b5876802884ca51038cc23c452dd342dee6a Mon Sep 17 00:00:00 2001 From: naaa760 Date: Wed, 4 Feb 2026 08:56:50 +0530 Subject: [PATCH 060/511] fix(proxy): forward extra_headers in chat --- .../transformation.py | 3 +++ ...responses_transformation_transformation.py | 22 +++++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/litellm/completion_extras/litellm_responses_transformation/transformation.py b/litellm/completion_extras/litellm_responses_transformation/transformation.py index 57bd05124aa..753a94295b3 100644 --- a/litellm/completion_extras/litellm_responses_transformation/transformation.py +++ b/litellm/completion_extras/litellm_responses_transformation/transformation.py @@ -329,6 +329,9 @@ class LiteLLMResponsesTransformationHandler(CompletionTransformationBridge): else: request_data[key] = value + if headers: + request_data["extra_headers"] = headers + return request_data @staticmethod diff --git a/tests/test_litellm/completion_extras/test_litellm_responses_transformation_transformation.py b/tests/test_litellm/completion_extras/test_litellm_responses_transformation_transformation.py index adbaf219079..57352eafaf1 100644 --- a/tests/test_litellm/completion_extras/test_litellm_responses_transformation_transformation.py +++ b/tests/test_litellm/completion_extras/test_litellm_responses_transformation_transformation.py @@ -134,3 +134,25 @@ def test_transform_request_with_response_format(): assert result["text"]["format"]["type"] == "json_schema" assert result["text"]["format"]["name"] == "person_schema" assert "schema" in result["text"]["format"] + + +def test_transform_request_includes_extra_headers(): + """Test that transform_request forwards headers as extra_headers for upstream call.""" + handler = LiteLLMResponsesTransformationHandler() + messages = [{"role": "user", "content": "Hello"}] + optional_params = {} + litellm_params = {} + + class MockLoggingObj: + pass + + headers = {"cf-aig-authorization": "secret-token"} + result = handler.transform_request( + model="gpt-5-pro", + messages=messages, + optional_params=optional_params, + litellm_params=litellm_params, + headers=headers, + litellm_logging_obj=MockLoggingObj(), + ) + assert result.get("extra_headers") == headers From 7056d9984ea5f7146fb346d77e4e21ee222c2be1 Mon Sep 17 00:00:00 2001 From: Krish Dholakia Date: Tue, 3 Feb 2026 19:57:24 -0800 Subject: [PATCH 061/511] Custom Code Guardrails UI Playground (#20377) * feat(guardrails/): allow custom code execution for guardrails first step in allowing teams to submit custom code for guardrails * feat: custom_code_guardrail.md support passing custom code for guardrails * feat: initial commit adding ui for custom code guardrails allows users to write guardrails based on custom code * feat: expose new test custom code guardrail endpoint allows ui testing playground to sanity check if guardrail is working as expected * fix: fix linting errors * fix: fix max recursion check * fix: fix linting error --- .../simple_guardrail_tutorial.md | 7 +- .../proxy/guardrails/custom_code_guardrail.md | 278 ++++++++ docs/my-website/sidebars.js | 1 + .../out/{404.html => 404/index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../{budgets.html => budgets/index.html} | 0 .../{caching.html => caching/index.html} | 0 .../index.html} | 0 .../{old-usage.html => old-usage/index.html} | 0 .../{prompts.html => prompts/index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../out/{login.html => login/index.html} | 0 .../out/{logs.html => logs/index.html} | 0 .../{callback.html => callback/index.html} | 0 .../{model-hub.html => model-hub/index.html} | 0 .../{model_hub.html => model_hub/index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../{policies.html => policies/index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../{ui-theme.html => ui-theme/index.html} | 0 .../out/{teams.html => teams/index.html} | 0 .../{test-key.html => test-key/index.html} | 0 .../index.html} | 0 .../index.html} | 0 .../out/{usage.html => usage/index.html} | 0 .../out/{users.html => users/index.html} | 0 .../index.html} | 0 litellm/proxy/_new_secret_config.yaml | 11 + .../proxy/guardrails/guardrail_endpoints.py | 269 ++++++++ .../guardrail_hooks/custom_code/__init__.py | 65 ++ .../custom_code/custom_code_guardrail.py | 372 +++++++++++ .../guardrail_hooks/custom_code/primitives.py | 602 ++++++++++++++++++ litellm/types/guardrails.py | 23 +- .../code_coverage_tests/recursive_detector.py | 1 + .../src/components/guardrails.tsx | 49 +- .../custom_code/CustomCodeEditor.tsx | 188 ++++++ .../custom_code/CustomCodeModal.tsx | 540 ++++++++++++++++ .../custom_code/CustomCodePlayground.tsx | 588 +++++++++++++++++ .../custom_code/custom_code_constants.ts | 194 ++++++ .../guardrails/custom_code/index.ts | 1 + .../src/components/networking.tsx | 83 +++ 49 files changed, 3254 insertions(+), 18 deletions(-) create mode 100644 docs/my-website/docs/proxy/guardrails/custom_code_guardrail.md rename litellm/proxy/_experimental/out/{404.html => 404/index.html} (100%) rename litellm/proxy/_experimental/out/{api-reference.html => api-reference/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{api-playground.html => api-playground/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{budgets.html => budgets/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{caching.html => caching/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{claude-code-plugins.html => claude-code-plugins/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{old-usage.html => old-usage/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{prompts.html => prompts/index.html} (100%) rename litellm/proxy/_experimental/out/experimental/{tag-management.html => tag-management/index.html} (100%) rename litellm/proxy/_experimental/out/{guardrails.html => guardrails/index.html} (100%) rename litellm/proxy/_experimental/out/{login.html => login/index.html} (100%) rename litellm/proxy/_experimental/out/{logs.html => logs/index.html} (100%) rename litellm/proxy/_experimental/out/mcp/oauth/{callback.html => callback/index.html} (100%) rename litellm/proxy/_experimental/out/{model-hub.html => model-hub/index.html} (100%) rename litellm/proxy/_experimental/out/{model_hub.html => model_hub/index.html} (100%) rename litellm/proxy/_experimental/out/{model_hub_table.html => model_hub_table/index.html} (100%) rename litellm/proxy/_experimental/out/{models-and-endpoints.html => models-and-endpoints/index.html} (100%) rename litellm/proxy/_experimental/out/{onboarding.html => onboarding/index.html} (100%) rename litellm/proxy/_experimental/out/{organizations.html => organizations/index.html} (100%) rename litellm/proxy/_experimental/out/{playground.html => playground/index.html} (100%) rename litellm/proxy/_experimental/out/{policies.html => policies/index.html} (100%) rename litellm/proxy/_experimental/out/settings/{admin-settings.html => admin-settings/index.html} (100%) rename litellm/proxy/_experimental/out/settings/{logging-and-alerts.html => logging-and-alerts/index.html} (100%) rename litellm/proxy/_experimental/out/settings/{router-settings.html => router-settings/index.html} (100%) rename litellm/proxy/_experimental/out/settings/{ui-theme.html => ui-theme/index.html} (100%) rename litellm/proxy/_experimental/out/{teams.html => teams/index.html} (100%) rename litellm/proxy/_experimental/out/{test-key.html => test-key/index.html} (100%) rename litellm/proxy/_experimental/out/tools/{mcp-servers.html => mcp-servers/index.html} (100%) rename litellm/proxy/_experimental/out/tools/{vector-stores.html => vector-stores/index.html} (100%) rename litellm/proxy/_experimental/out/{usage.html => usage/index.html} (100%) rename litellm/proxy/_experimental/out/{users.html => users/index.html} (100%) rename litellm/proxy/_experimental/out/{virtual-keys.html => virtual-keys/index.html} (100%) create mode 100644 litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py create mode 100644 litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py create mode 100644 litellm/proxy/guardrails/guardrail_hooks/custom_code/primitives.py create mode 100644 ui/litellm-dashboard/src/components/guardrails/custom_code/CustomCodeEditor.tsx create mode 100644 ui/litellm-dashboard/src/components/guardrails/custom_code/CustomCodeModal.tsx create mode 100644 ui/litellm-dashboard/src/components/guardrails/custom_code/CustomCodePlayground.tsx create mode 100644 ui/litellm-dashboard/src/components/guardrails/custom_code/custom_code_constants.ts create mode 100644 ui/litellm-dashboard/src/components/guardrails/custom_code/index.ts diff --git a/docs/my-website/docs/adding_provider/simple_guardrail_tutorial.md b/docs/my-website/docs/adding_provider/simple_guardrail_tutorial.md index 9c654cd1560..884a7397bde 100644 --- a/docs/my-website/docs/adding_provider/simple_guardrail_tutorial.md +++ b/docs/my-website/docs/adding_provider/simple_guardrail_tutorial.md @@ -101,12 +101,11 @@ model_list: - model_name: gpt-4 litellm_params: model: gpt-4 - api_key: os.environ/OPENAI_API_KEY + api_key: os.environ/OPENAI_API_KEY -litellm_settings: - guardrails: +guardrails: - guardrail_name: my_guardrail - litellm_params: + litellm_params: guardrail: my_guardrail mode: during_call api_key: os.environ/MY_GUARDRAIL_API_KEY diff --git a/docs/my-website/docs/proxy/guardrails/custom_code_guardrail.md b/docs/my-website/docs/proxy/guardrails/custom_code_guardrail.md new file mode 100644 index 00000000000..cb246144497 --- /dev/null +++ b/docs/my-website/docs/proxy/guardrails/custom_code_guardrail.md @@ -0,0 +1,278 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Custom Code Guardrail + +Write custom guardrail logic using Python-like code that runs in a sandboxed environment. + +## Quick Start + +### 1. Define the guardrail in config + +```yaml +model_list: + - model_name: gpt-4 + litellm_params: + model: gpt-4 + api_key: os.environ/OPENAI_API_KEY + +guardrails: + - guardrail_name: block-ssn + litellm_params: + guardrail: custom_code + mode: pre_call + custom_code: | + def apply_guardrail(inputs, request_data, input_type): + for text in inputs["texts"]: + if regex_match(text, r"\d{3}-\d{2}-\d{4}"): + return block("SSN detected") + return allow() +``` + +### 2. Start proxy + +```bash +litellm --config config.yaml +``` + +### 3. Test + +```bash +curl -X POST http://localhost:4000/chat/completions \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-4", + "messages": [{"role": "user", "content": "My SSN is 123-45-6789"}], + "guardrails": ["block-ssn"] + }' +``` + +## Configuration + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `guardrail` | string | ✅ | Must be `custom_code` | +| `mode` | string | ✅ | When to run: `pre_call`, `post_call`, `during_call` | +| `custom_code` | string | ✅ | Python-like code with `apply_guardrail` function | +| `default_on` | bool | ❌ | Run on all requests (default: `false`) | + +## Writing Custom Code + +### Function Signature + +Your code must define an `apply_guardrail` function: + +```python +def apply_guardrail(inputs, request_data, input_type): + # inputs: see table below + # request_data: {"model": "...", "user_id": "...", "team_id": "...", "metadata": {...}} + # input_type: "request" or "response" + + return allow() # or block() or modify() +``` + +### `inputs` Parameter + +| Field | Type | Description | +|-------|------|-------------| +| `texts` | `List[str]` | Extracted text from the request/response | +| `images` | `List[str]` | Extracted images (for image guardrails) | +| `tools` | `List[dict]` | Tools sent to the LLM | +| `tool_calls` | `List[dict]` | Tool calls returned from the LLM | +| `structured_messages` | `List[dict]` | Full messages with role info (system/user/assistant) | +| `model` | `str` | The model being used | + +### `request_data` Parameter + +| Field | Type | Description | +|-------|------|-------------| +| `model` | `str` | Model name | +| `user_id` | `str` | User ID from API key | +| `team_id` | `str` | Team ID from API key | +| `end_user_id` | `str` | End user ID | +| `metadata` | `dict` | Request metadata | + +### Return Values + +| Function | Description | +|----------|-------------| +| `allow()` | Let request/response through | +| `block(reason)` | Reject with message | +| `modify(texts=[], images=[], tool_calls=[])` | Transform content | + +## Built-in Primitives + +### Regex + +| Function | Description | +|----------|-------------| +| `regex_match(text, pattern)` | Returns `True` if pattern found | +| `regex_replace(text, pattern, replacement)` | Replace all matches | +| `regex_find_all(text, pattern)` | Return list of matches | + +### JSON + +| Function | Description | +|----------|-------------| +| `json_parse(text)` | Parse JSON string, returns `None` on error | +| `json_stringify(obj)` | Convert to JSON string | +| `json_schema_valid(obj, schema)` | Validate against JSON schema | + +### URL + +| Function | Description | +|----------|-------------| +| `extract_urls(text)` | Extract all URLs from text | +| `is_valid_url(url)` | Check if URL is valid | +| `all_urls_valid(text)` | Check all URLs in text are valid | + +### Code Detection + +| Function | Description | +|----------|-------------| +| `detect_code(text)` | Returns `True` if code detected | +| `detect_code_languages(text)` | Returns list of detected languages | +| `contains_code_language(text, ["sql", "python"])` | Check for specific languages | + +### Text Utilities + +| Function | Description | +|----------|-------------| +| `contains(text, substring)` | Check if substring exists | +| `contains_any(text, [substr1, substr2])` | Check if any substring exists | +| `word_count(text)` | Count words | +| `char_count(text)` | Count characters | +| `lower(text)` / `upper(text)` / `trim(text)` | String transforms | + +## Examples + +### Block PII (SSN) + +```python +def apply_guardrail(inputs, request_data, input_type): + for text in inputs["texts"]: + if regex_match(text, r"\d{3}-\d{2}-\d{4}"): + return block("SSN detected") + return allow() +``` + +### Redact Email Addresses + +```python +def apply_guardrail(inputs, request_data, input_type): + pattern = r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}" + modified = [] + for text in inputs["texts"]: + modified.append(regex_replace(text, pattern, "[EMAIL REDACTED]")) + return modify(texts=modified) +``` + +### Block SQL Injection + +```python +def apply_guardrail(inputs, request_data, input_type): + if input_type != "request": + return allow() + for text in inputs["texts"]: + if contains_code_language(text, ["sql"]): + return block("SQL code not allowed") + return allow() +``` + +### Validate JSON Response + +```python +def apply_guardrail(inputs, request_data, input_type): + if input_type != "response": + return allow() + + schema = { + "type": "object", + "required": ["name", "value"] + } + + for text in inputs["texts"]: + obj = json_parse(text) + if obj is None: + return block("Invalid JSON response") + if not json_schema_valid(obj, schema): + return block("Response missing required fields") + return allow() +``` + +### Check URLs in Response + +```python +def apply_guardrail(inputs, request_data, input_type): + if input_type != "response": + return allow() + for text in inputs["texts"]: + if not all_urls_valid(text): + return block("Response contains invalid URLs") + return allow() +``` + +### Combine Multiple Checks + +```python +def apply_guardrail(inputs, request_data, input_type): + modified = [] + + for text in inputs["texts"]: + # Redact SSN + text = regex_replace(text, r"\d{3}-\d{2}-\d{4}", "[SSN]") + # Redact credit cards + text = regex_replace(text, r"\d{16}", "[CARD]") + modified.append(text) + + # Block SQL in requests + if input_type == "request": + for text in inputs["texts"]: + if contains_code_language(text, ["sql"]): + return block("SQL injection blocked") + + return modify(texts=modified) +``` + +## Sandbox Restrictions + +Custom code runs in a restricted environment: + +- ❌ No `import` statements +- ❌ No file I/O +- ❌ No network access +- ❌ No `exec()` or `eval()` +- ✅ Only LiteLLM-provided primitives available + +## Per-Request Usage + +Enable guardrail per request: + +```bash +curl -X POST http://localhost:4000/chat/completions \ + -H "Authorization: Bearer sk-1234" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-4", + "messages": [{"role": "user", "content": "Hello"}], + "guardrails": ["block-ssn"] + }' +``` + +## Default On + +Run guardrail on all requests: + +```yaml +litellm_settings: + guardrails: + - guardrail_name: block-ssn + litellm_params: + guardrail: custom_code + mode: pre_call + default_on: true + custom_code: | + def apply_guardrail(inputs, request_data, input_type): + ... +``` diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index 98c8ee6eaa1..20e66fb532d 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -79,6 +79,7 @@ const sidebars = { "proxy/guardrails/panw_prisma_airs", "proxy/guardrails/secret_detection", "proxy/guardrails/custom_guardrail", + "proxy/guardrails/custom_code_guardrail", "proxy/guardrails/prompt_injection", "proxy/guardrails/tool_permission", "proxy/guardrails/zscaler_ai_guard", diff --git a/litellm/proxy/_experimental/out/404.html b/litellm/proxy/_experimental/out/404/index.html similarity index 100% rename from litellm/proxy/_experimental/out/404.html rename to litellm/proxy/_experimental/out/404/index.html diff --git a/litellm/proxy/_experimental/out/api-reference.html b/litellm/proxy/_experimental/out/api-reference/index.html similarity index 100% rename from litellm/proxy/_experimental/out/api-reference.html rename to litellm/proxy/_experimental/out/api-reference/index.html diff --git a/litellm/proxy/_experimental/out/experimental/api-playground.html b/litellm/proxy/_experimental/out/experimental/api-playground/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/api-playground.html rename to litellm/proxy/_experimental/out/experimental/api-playground/index.html diff --git a/litellm/proxy/_experimental/out/experimental/budgets.html b/litellm/proxy/_experimental/out/experimental/budgets/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/budgets.html rename to litellm/proxy/_experimental/out/experimental/budgets/index.html diff --git a/litellm/proxy/_experimental/out/experimental/caching.html b/litellm/proxy/_experimental/out/experimental/caching/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/caching.html rename to litellm/proxy/_experimental/out/experimental/caching/index.html diff --git a/litellm/proxy/_experimental/out/experimental/claude-code-plugins.html b/litellm/proxy/_experimental/out/experimental/claude-code-plugins/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/claude-code-plugins.html rename to litellm/proxy/_experimental/out/experimental/claude-code-plugins/index.html diff --git a/litellm/proxy/_experimental/out/experimental/old-usage.html b/litellm/proxy/_experimental/out/experimental/old-usage/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/old-usage.html rename to litellm/proxy/_experimental/out/experimental/old-usage/index.html diff --git a/litellm/proxy/_experimental/out/experimental/prompts.html b/litellm/proxy/_experimental/out/experimental/prompts/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/prompts.html rename to litellm/proxy/_experimental/out/experimental/prompts/index.html diff --git a/litellm/proxy/_experimental/out/experimental/tag-management.html b/litellm/proxy/_experimental/out/experimental/tag-management/index.html similarity index 100% rename from litellm/proxy/_experimental/out/experimental/tag-management.html rename to litellm/proxy/_experimental/out/experimental/tag-management/index.html diff --git a/litellm/proxy/_experimental/out/guardrails.html b/litellm/proxy/_experimental/out/guardrails/index.html similarity index 100% rename from litellm/proxy/_experimental/out/guardrails.html rename to litellm/proxy/_experimental/out/guardrails/index.html diff --git a/litellm/proxy/_experimental/out/login.html b/litellm/proxy/_experimental/out/login/index.html similarity index 100% rename from litellm/proxy/_experimental/out/login.html rename to litellm/proxy/_experimental/out/login/index.html diff --git a/litellm/proxy/_experimental/out/logs.html b/litellm/proxy/_experimental/out/logs/index.html similarity index 100% rename from litellm/proxy/_experimental/out/logs.html rename to litellm/proxy/_experimental/out/logs/index.html diff --git a/litellm/proxy/_experimental/out/mcp/oauth/callback.html b/litellm/proxy/_experimental/out/mcp/oauth/callback/index.html similarity index 100% rename from litellm/proxy/_experimental/out/mcp/oauth/callback.html rename to litellm/proxy/_experimental/out/mcp/oauth/callback/index.html diff --git a/litellm/proxy/_experimental/out/model-hub.html b/litellm/proxy/_experimental/out/model-hub/index.html similarity index 100% rename from litellm/proxy/_experimental/out/model-hub.html rename to litellm/proxy/_experimental/out/model-hub/index.html diff --git a/litellm/proxy/_experimental/out/model_hub.html b/litellm/proxy/_experimental/out/model_hub/index.html similarity index 100% rename from litellm/proxy/_experimental/out/model_hub.html rename to litellm/proxy/_experimental/out/model_hub/index.html diff --git a/litellm/proxy/_experimental/out/model_hub_table.html b/litellm/proxy/_experimental/out/model_hub_table/index.html similarity index 100% rename from litellm/proxy/_experimental/out/model_hub_table.html rename to litellm/proxy/_experimental/out/model_hub_table/index.html diff --git a/litellm/proxy/_experimental/out/models-and-endpoints.html b/litellm/proxy/_experimental/out/models-and-endpoints/index.html similarity index 100% rename from litellm/proxy/_experimental/out/models-and-endpoints.html rename to litellm/proxy/_experimental/out/models-and-endpoints/index.html diff --git a/litellm/proxy/_experimental/out/onboarding.html b/litellm/proxy/_experimental/out/onboarding/index.html similarity index 100% rename from litellm/proxy/_experimental/out/onboarding.html rename to litellm/proxy/_experimental/out/onboarding/index.html diff --git a/litellm/proxy/_experimental/out/organizations.html b/litellm/proxy/_experimental/out/organizations/index.html similarity index 100% rename from litellm/proxy/_experimental/out/organizations.html rename to litellm/proxy/_experimental/out/organizations/index.html diff --git a/litellm/proxy/_experimental/out/playground.html b/litellm/proxy/_experimental/out/playground/index.html similarity index 100% rename from litellm/proxy/_experimental/out/playground.html rename to litellm/proxy/_experimental/out/playground/index.html diff --git a/litellm/proxy/_experimental/out/policies.html b/litellm/proxy/_experimental/out/policies/index.html similarity index 100% rename from litellm/proxy/_experimental/out/policies.html rename to litellm/proxy/_experimental/out/policies/index.html diff --git a/litellm/proxy/_experimental/out/settings/admin-settings.html b/litellm/proxy/_experimental/out/settings/admin-settings/index.html similarity index 100% rename from litellm/proxy/_experimental/out/settings/admin-settings.html rename to litellm/proxy/_experimental/out/settings/admin-settings/index.html diff --git a/litellm/proxy/_experimental/out/settings/logging-and-alerts.html b/litellm/proxy/_experimental/out/settings/logging-and-alerts/index.html similarity index 100% rename from litellm/proxy/_experimental/out/settings/logging-and-alerts.html rename to litellm/proxy/_experimental/out/settings/logging-and-alerts/index.html diff --git a/litellm/proxy/_experimental/out/settings/router-settings.html b/litellm/proxy/_experimental/out/settings/router-settings/index.html similarity index 100% rename from litellm/proxy/_experimental/out/settings/router-settings.html rename to litellm/proxy/_experimental/out/settings/router-settings/index.html diff --git a/litellm/proxy/_experimental/out/settings/ui-theme.html b/litellm/proxy/_experimental/out/settings/ui-theme/index.html similarity index 100% rename from litellm/proxy/_experimental/out/settings/ui-theme.html rename to litellm/proxy/_experimental/out/settings/ui-theme/index.html diff --git a/litellm/proxy/_experimental/out/teams.html b/litellm/proxy/_experimental/out/teams/index.html similarity index 100% rename from litellm/proxy/_experimental/out/teams.html rename to litellm/proxy/_experimental/out/teams/index.html diff --git a/litellm/proxy/_experimental/out/test-key.html b/litellm/proxy/_experimental/out/test-key/index.html similarity index 100% rename from litellm/proxy/_experimental/out/test-key.html rename to litellm/proxy/_experimental/out/test-key/index.html diff --git a/litellm/proxy/_experimental/out/tools/mcp-servers.html b/litellm/proxy/_experimental/out/tools/mcp-servers/index.html similarity index 100% rename from litellm/proxy/_experimental/out/tools/mcp-servers.html rename to litellm/proxy/_experimental/out/tools/mcp-servers/index.html diff --git a/litellm/proxy/_experimental/out/tools/vector-stores.html b/litellm/proxy/_experimental/out/tools/vector-stores/index.html similarity index 100% rename from litellm/proxy/_experimental/out/tools/vector-stores.html rename to litellm/proxy/_experimental/out/tools/vector-stores/index.html diff --git a/litellm/proxy/_experimental/out/usage.html b/litellm/proxy/_experimental/out/usage/index.html similarity index 100% rename from litellm/proxy/_experimental/out/usage.html rename to litellm/proxy/_experimental/out/usage/index.html diff --git a/litellm/proxy/_experimental/out/users.html b/litellm/proxy/_experimental/out/users/index.html similarity index 100% rename from litellm/proxy/_experimental/out/users.html rename to litellm/proxy/_experimental/out/users/index.html diff --git a/litellm/proxy/_experimental/out/virtual-keys.html b/litellm/proxy/_experimental/out/virtual-keys/index.html similarity index 100% rename from litellm/proxy/_experimental/out/virtual-keys.html rename to litellm/proxy/_experimental/out/virtual-keys/index.html diff --git a/litellm/proxy/_new_secret_config.yaml b/litellm/proxy/_new_secret_config.yaml index 13eeae14485..6f527e268b2 100644 --- a/litellm/proxy/_new_secret_config.yaml +++ b/litellm/proxy/_new_secret_config.yaml @@ -14,3 +14,14 @@ model_list: litellm_params: model: openai/gpt-4.1-mini +guardrails: + - guardrail_name: redact-ssn + litellm_params: + guardrail: custom_code + mode: pre_call + custom_code: | + def apply_guardrail(inputs, request_data, input_type): + for text in inputs["texts"]: + if regex_match(text, r"\d{3}-\d{2}-\d{4}"): + return block("SSN detected in message") + return allow() \ No newline at end of file diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py index b80b02fdc6f..aec5dc1edef 100644 --- a/litellm/proxy/guardrails/guardrail_endpoints.py +++ b/litellm/proxy/guardrails/guardrail_endpoints.py @@ -1344,6 +1344,275 @@ async def get_provider_specific_params(): return provider_params +class TestCustomCodeGuardrailRequest(BaseModel): + """Request model for testing custom code guardrails.""" + + custom_code: str + """The Python-like code containing the apply_guardrail function.""" + + test_input: Dict[str, Any] + """The test input to pass to the guardrail. Should contain 'texts', optionally 'images', 'tools', etc.""" + + input_type: str = "request" + """Whether this is a 'request' or 'response' input type.""" + + request_data: Optional[Dict[str, Any]] = None + """Optional mock request_data (model, user_id, team_id, metadata, etc.).""" + + +class TestCustomCodeGuardrailResponse(BaseModel): + """Response model for testing custom code guardrails.""" + + success: bool + """Whether the test executed successfully (no errors).""" + + result: Optional[Dict[str, Any]] = None + """The guardrail result: action (allow/block/modify), reason, modified_texts, etc.""" + + error: Optional[str] = None + """Error message if execution failed.""" + + error_type: Optional[str] = None + """Type of error: 'compilation' or 'execution'.""" + + +@router.post( + "/guardrails/test_custom_code", + tags=["Guardrails"], + dependencies=[Depends(user_api_key_auth)], + response_model=TestCustomCodeGuardrailResponse, +) +async def test_custom_code_guardrail(request: TestCustomCodeGuardrailRequest): + """ + Test custom code guardrail logic without creating a guardrail. + + This endpoint allows admins to experiment with custom code guardrails by: + 1. Compiling the provided code in a sandbox + 2. Executing the apply_guardrail function with test input + 3. Returning the result (allow/block/modify) + + 👉 [Custom Code Guardrail docs](https://docs.litellm.ai/docs/proxy/guardrails/custom_code_guardrail) + + Example Request: + ```bash + curl -X POST "http://localhost:4000/guardrails/test_custom_code" \\ + -H "Authorization: Bearer " \\ + -H "Content-Type: application/json" \\ + -d '{ + "custom_code": "def apply_guardrail(inputs, request_data, input_type):\\n for text in inputs[\\"texts\\"]:\\n if regex_match(text, r\\"\\\\d{3}-\\\\d{2}-\\\\d{4}\\"):\\n return block(\\"SSN detected\\")\\n return allow()", + "test_input": { + "texts": ["My SSN is 123-45-6789"] + }, + "input_type": "request" + }' + ``` + + Example Success Response (blocked): + ```json + { + "success": true, + "result": { + "action": "block", + "reason": "SSN detected" + }, + "error": null, + "error_type": null + } + ``` + + Example Success Response (allowed): + ```json + { + "success": true, + "result": { + "action": "allow" + }, + "error": null, + "error_type": null + } + ``` + + Example Success Response (modified): + ```json + { + "success": true, + "result": { + "action": "modify", + "texts": ["My SSN is [REDACTED]"] + }, + "error": null, + "error_type": null + } + ``` + + Example Error Response (compilation error): + ```json + { + "success": false, + "result": null, + "error": "Syntax error in custom code: invalid syntax (, line 1)", + "error_type": "compilation" + } + ``` + """ + import concurrent.futures + import re + + from litellm.proxy.guardrails.guardrail_hooks.custom_code.primitives import ( + get_custom_code_primitives, + ) + + # Security validation patterns + FORBIDDEN_PATTERNS = [ + # Import statements + (r"\bimport\s+", "import statements are not allowed"), + (r"\bfrom\s+\w+\s+import\b", "from...import statements are not allowed"), + (r"__import__\s*\(", "__import__() is not allowed"), + # Dangerous builtins + (r"\bexec\s*\(", "exec() is not allowed"), + (r"\beval\s*\(", "eval() is not allowed"), + (r"\bcompile\s*\(", "compile() is not allowed"), + (r"\bopen\s*\(", "open() is not allowed"), + (r"\bgetattr\s*\(", "getattr() is not allowed"), + (r"\bsetattr\s*\(", "setattr() is not allowed"), + (r"\bdelattr\s*\(", "delattr() is not allowed"), + (r"\bglobals\s*\(", "globals() is not allowed"), + (r"\blocals\s*\(", "locals() is not allowed"), + (r"\bvars\s*\(", "vars() is not allowed"), + (r"\bdir\s*\(", "dir() is not allowed"), + (r"\bbreakpoint\s*\(", "breakpoint() is not allowed"), + (r"\binput\s*\(", "input() is not allowed"), + # Dangerous dunder access + (r"__builtins__", "__builtins__ access is not allowed"), + (r"__globals__", "__globals__ access is not allowed"), + (r"__code__", "__code__ access is not allowed"), + (r"__subclasses__", "__subclasses__ access is not allowed"), + (r"__bases__", "__bases__ access is not allowed"), + (r"__mro__", "__mro__ access is not allowed"), + (r"__class__", "__class__ access is not allowed"), + (r"__dict__", "__dict__ access is not allowed"), + (r"__getattribute__", "__getattribute__ access is not allowed"), + (r"__reduce__", "__reduce__ access is not allowed"), + (r"__reduce_ex__", "__reduce_ex__ access is not allowed"), + # OS/system access + (r"\bos\.", "os module access is not allowed"), + (r"\bsys\.", "sys module access is not allowed"), + (r"\bsubprocess\.", "subprocess module access is not allowed"), + ] + + EXECUTION_TIMEOUT_SECONDS = 5 + + try: + # Step 0: Security validation - check for forbidden patterns + code = request.custom_code + for pattern, error_msg in FORBIDDEN_PATTERNS: + if re.search(pattern, code): + return TestCustomCodeGuardrailResponse( + success=False, + error=f"Security violation: {error_msg}", + error_type="compilation", + ) + + # Step 1: Compile the custom code with restricted environment + exec_globals = get_custom_code_primitives().copy() + + # Remove access to builtins to prevent escape + exec_globals["__builtins__"] = {} + + try: + exec(compile(request.custom_code, "", "exec"), exec_globals) + except SyntaxError as e: + return TestCustomCodeGuardrailResponse( + success=False, + error=f"Syntax error in custom code: {e}", + error_type="compilation", + ) + except Exception as e: + return TestCustomCodeGuardrailResponse( + success=False, + error=f"Failed to compile custom code: {e}", + error_type="compilation", + ) + + # Step 2: Verify apply_guardrail function exists + if "apply_guardrail" not in exec_globals: + return TestCustomCodeGuardrailResponse( + success=False, + error="Custom code must define an 'apply_guardrail' function. " + "Expected signature: apply_guardrail(inputs, request_data, input_type)", + error_type="compilation", + ) + + apply_fn = exec_globals["apply_guardrail"] + if not callable(apply_fn): + return TestCustomCodeGuardrailResponse( + success=False, + error="'apply_guardrail' must be a callable function", + error_type="compilation", + ) + + # Step 3: Prepare test inputs + test_inputs = request.test_input + if "texts" not in test_inputs: + test_inputs["texts"] = [] + + # Prepare mock request_data + mock_request_data = request.request_data or {} + safe_request_data = { + "model": mock_request_data.get("model", "test-model"), + "user_id": mock_request_data.get("user_id"), + "team_id": mock_request_data.get("team_id"), + "end_user_id": mock_request_data.get("end_user_id"), + "metadata": mock_request_data.get("metadata", {}), + } + + # Step 4: Execute the function with timeout protection + + def execute_guardrail(): + return apply_fn(test_inputs, safe_request_data, request.input_type) + + try: + with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor: + future = executor.submit(execute_guardrail) + try: + result = future.result(timeout=EXECUTION_TIMEOUT_SECONDS) + except concurrent.futures.TimeoutError: + return TestCustomCodeGuardrailResponse( + success=False, + error=f"Execution timeout: code took longer than {EXECUTION_TIMEOUT_SECONDS} seconds", + error_type="execution", + ) + except Exception as e: + return TestCustomCodeGuardrailResponse( + success=False, + error=f"Execution error: {e}", + error_type="execution", + ) + + # Step 5: Validate and return result + if not isinstance(result, dict): + return TestCustomCodeGuardrailResponse( + success=True, + result={ + "action": "allow", + "warning": f"Expected dict result, got {type(result).__name__}. Treating as allow.", + }, + ) + + return TestCustomCodeGuardrailResponse( + success=True, + result=result, + ) + + except Exception as e: + verbose_proxy_logger.exception(f"Error testing custom code guardrail: {e}") + return TestCustomCodeGuardrailResponse( + success=False, + error=f"Unexpected error: {e}", + error_type="execution", + ) + + @router.post("/guardrails/apply_guardrail", response_model=ApplyGuardrailResponse) @router.post("/apply_guardrail", response_model=ApplyGuardrailResponse) async def apply_guardrail( diff --git a/litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py new file mode 100644 index 00000000000..747b188feea --- /dev/null +++ b/litellm/proxy/guardrails/guardrail_hooks/custom_code/__init__.py @@ -0,0 +1,65 @@ +"""Custom code guardrail integration for LiteLLM. + +This module allows users to write custom guardrail logic using Python-like code +that runs in a sandboxed environment with access to LiteLLM-provided primitives. +""" + +from typing import TYPE_CHECKING + +from litellm.types.guardrails import SupportedGuardrailIntegrations + +from .custom_code_guardrail import CustomCodeGuardrail + +if TYPE_CHECKING: + from litellm.types.guardrails import Guardrail, LitellmParams + + +def initialize_guardrail( + litellm_params: "LitellmParams", guardrail: "Guardrail" +) -> CustomCodeGuardrail: + """ + Initialize a custom code guardrail. + + Args: + litellm_params: Configuration parameters including the custom code + guardrail: The guardrail configuration dict + + Returns: + CustomCodeGuardrail instance + """ + import litellm + + guardrail_name = guardrail.get("guardrail_name") + if not guardrail_name: + raise ValueError("Custom code guardrail requires a guardrail_name") + + # Get the custom code from litellm_params + custom_code = getattr(litellm_params, "custom_code", None) + if not custom_code: + raise ValueError( + "Custom code guardrail requires 'custom_code' in litellm_params" + ) + + custom_code_guardrail = CustomCodeGuardrail( + guardrail_name=guardrail_name, + custom_code=custom_code, + event_hook=litellm_params.mode, + default_on=litellm_params.default_on, + ) + + litellm.logging_callback_manager.add_litellm_callback(custom_code_guardrail) + return custom_code_guardrail + + +guardrail_initializer_registry = { + SupportedGuardrailIntegrations.CUSTOM_CODE.value: initialize_guardrail, +} + +guardrail_class_registry = { + SupportedGuardrailIntegrations.CUSTOM_CODE.value: CustomCodeGuardrail, +} + +__all__ = [ + "CustomCodeGuardrail", + "initialize_guardrail", +] diff --git a/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py new file mode 100644 index 00000000000..a0ca324411c --- /dev/null +++ b/litellm/proxy/guardrails/guardrail_hooks/custom_code/custom_code_guardrail.py @@ -0,0 +1,372 @@ +""" +Custom code guardrail for LiteLLM. + +This module provides a guardrail that executes user-defined Python-like code +to implement custom guardrail logic. The code runs in a sandboxed environment +with access to LiteLLM-provided primitives for common guardrail operations. + +Example custom code: + + def apply_guardrail(inputs, request_data, input_type): + '''Block messages containing SSNs''' + for text in inputs["texts"]: + if regex_match(text, r"\\d{3}-\\d{2}-\\d{4}"): + return block("Social Security Number detected") + return allow() +""" + +import threading +from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Type, cast + +from fastapi import HTTPException + +from litellm._logging import verbose_proxy_logger +from litellm.integrations.custom_guardrail import CustomGuardrail +from litellm.types.guardrails import GuardrailEventHooks +from litellm.types.proxy.guardrails.guardrail_hooks.base import GuardrailConfigModel +from litellm.types.utils import GenericGuardrailAPIInputs + +from .primitives import get_custom_code_primitives + +if TYPE_CHECKING: + from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj + + +class CustomCodeGuardrailError(Exception): + """Raised when custom code guardrail execution fails.""" + + def __init__(self, message: str, details: Optional[Dict[str, Any]] = None) -> None: + super().__init__(message) + self.details = details or {} + + +class CustomCodeCompilationError(CustomCodeGuardrailError): + """Raised when custom code fails to compile.""" + + +class CustomCodeExecutionError(CustomCodeGuardrailError): + """Raised when custom code fails during execution.""" + + +class CustomCodeGuardrailConfigModel(GuardrailConfigModel): + """Configuration parameters for the custom code guardrail.""" + + custom_code: str + """The Python-like code containing the apply_guardrail function.""" + + +class CustomCodeGuardrail(CustomGuardrail): + """ + Guardrail that executes user-defined Python-like code. + + The code runs in a sandboxed environment that provides: + - Access to LiteLLM primitives (regex_match, json_parse, etc.) + - No file I/O or network access + - No imports allowed + + Users write an `apply_guardrail(inputs, request_data, input_type)` function + that returns one of: + - allow() - let the request/response through + - block(reason) - reject with a message + - modify(texts=...) - transform the content + + Example: + def apply_guardrail(inputs, request_data, input_type): + for text in inputs["texts"]: + if regex_match(text, r"password"): + return block("Sensitive content detected") + return allow() + """ + + def __init__( + self, + custom_code: str, + guardrail_name: Optional[str] = "custom_code", + **kwargs: Any, + ) -> None: + """ + Initialize the custom code guardrail. + + Args: + custom_code: The source code containing apply_guardrail function + guardrail_name: Name of this guardrail instance + **kwargs: Additional arguments passed to CustomGuardrail + """ + self.custom_code = custom_code + self._compiled_function: Optional[Any] = None + self._compile_lock = threading.Lock() + self._compile_error: Optional[str] = None + + supported_event_hooks = [ + GuardrailEventHooks.pre_call, + GuardrailEventHooks.during_call, + GuardrailEventHooks.post_call, + ] + + super().__init__( + guardrail_name=guardrail_name, + supported_event_hooks=supported_event_hooks, + **kwargs, + ) + + # Compile the code on initialization + self._compile_custom_code() + + @staticmethod + def get_config_model() -> Optional[Type[GuardrailConfigModel]]: + """Returns the config model for the UI.""" + return CustomCodeGuardrailConfigModel + + def _compile_custom_code(self) -> None: + """ + Compile the custom code and extract the apply_guardrail function. + + The code runs in a sandboxed environment with only the allowed primitives. + """ + with self._compile_lock: + if self._compiled_function is not None: + return + + try: + # Create a restricted execution environment + # Only include our safe primitives + exec_globals = get_custom_code_primitives().copy() + + # Execute the user code in the restricted environment + exec(compile(self.custom_code, "", "exec"), exec_globals) + + # Extract the apply_guardrail function + if "apply_guardrail" not in exec_globals: + raise CustomCodeCompilationError( + "Custom code must define an 'apply_guardrail' function. " + "Expected signature: apply_guardrail(inputs, request_data, input_type)" + ) + + apply_fn = exec_globals["apply_guardrail"] + if not callable(apply_fn): + raise CustomCodeCompilationError( + "'apply_guardrail' must be a callable function" + ) + + self._compiled_function = apply_fn + verbose_proxy_logger.debug( + f"Custom code guardrail '{self.guardrail_name}' compiled successfully" + ) + + except SyntaxError as e: + self._compile_error = f"Syntax error in custom code: {e}" + raise CustomCodeCompilationError(self._compile_error) from e + except CustomCodeCompilationError: + raise + except Exception as e: + self._compile_error = f"Failed to compile custom code: {e}" + raise CustomCodeCompilationError(self._compile_error) from e + + async def apply_guardrail( + self, + inputs: GenericGuardrailAPIInputs, + request_data: dict, + input_type: Literal["request", "response"], + logging_obj: Optional["LiteLLMLoggingObj"] = None, + ) -> GenericGuardrailAPIInputs: + """ + Apply the custom code guardrail to the inputs. + + This method calls the user-defined apply_guardrail function and + processes its result to determine the appropriate action. + + Args: + inputs: Dictionary containing texts, images, tool_calls + request_data: The original request data with metadata + input_type: "request" for pre-call, "response" for post-call + logging_obj: Optional logging object + + Returns: + GenericGuardrailAPIInputs - possibly modified + + Raises: + HTTPException: If content is blocked + CustomCodeExecutionError: If execution fails + """ + if self._compiled_function is None: + if self._compile_error: + raise CustomCodeExecutionError( + f"Custom code guardrail not compiled: {self._compile_error}" + ) + raise CustomCodeExecutionError("Custom code guardrail not compiled") + + try: + # Prepare inputs dict for the function + + # Prepare request_data with safe subset of information + safe_request_data = self._prepare_safe_request_data(request_data) + + # Execute the custom function + result = self._compiled_function(inputs, safe_request_data, input_type) + + # Process the result + return self._process_result( + result=result, + inputs=inputs, + request_data=request_data, + input_type=input_type, + ) + + except HTTPException: + # Re-raise HTTP exceptions (from block action) + raise + except Exception as e: + verbose_proxy_logger.error( + f"Custom code guardrail '{self.guardrail_name}' execution error: {e}" + ) + raise CustomCodeExecutionError( + f"Custom code guardrail execution failed: {e}", + details={ + "guardrail_name": self.guardrail_name, + "input_type": input_type, + }, + ) from e + + def _prepare_safe_request_data(self, request_data: dict) -> Dict[str, Any]: + """ + Prepare a safe subset of request_data for code execution. + + This filters out sensitive information and provides only what's + needed for guardrail logic. + + Args: + request_data: The full request data + + Returns: + Safe subset of request data + """ + return { + "model": request_data.get("model"), + "user_id": request_data.get("user_api_key_user_id"), + "team_id": request_data.get("user_api_key_team_id"), + "end_user_id": request_data.get("user_api_key_end_user_id"), + "metadata": request_data.get("metadata", {}), + } + + def _process_result( + self, + result: Any, + inputs: GenericGuardrailAPIInputs, + request_data: dict, + input_type: Literal["request", "response"], + ) -> GenericGuardrailAPIInputs: + """ + Process the result from the custom code function. + + Args: + result: The return value from apply_guardrail + inputs: The original inputs + request_data: The request data + input_type: "request" or "response" + + Returns: + GenericGuardrailAPIInputs - possibly modified + + Raises: + HTTPException: If action is "block" + """ + if not isinstance(result, dict): + verbose_proxy_logger.warning( + f"Custom code guardrail '{self.guardrail_name}': " + f"Expected dict result, got {type(result).__name__}. Treating as allow." + ) + return inputs + + action = result.get("action", "allow") + + if action == "allow": + verbose_proxy_logger.debug( + f"Custom code guardrail '{self.guardrail_name}': Allowing {input_type}" + ) + return inputs + + elif action == "block": + reason = result.get("reason", "Blocked by custom code guardrail") + detection_info = result.get("detection_info", {}) + + verbose_proxy_logger.info( + f"Custom code guardrail '{self.guardrail_name}': Blocking {input_type} - {reason}" + ) + + is_output = input_type == "response" + + # For pre-call, raise passthrough exception to return synthetic response + if not is_output: + self.raise_passthrough_exception( + violation_message=reason, + request_data=request_data, + detection_info=detection_info, + ) + + # For post-call, raise HTTP exception + raise HTTPException( + status_code=400, + detail={ + "error": reason, + "guardrail": self.guardrail_name, + "detection_info": detection_info, + }, + ) + + elif action == "modify": + verbose_proxy_logger.debug( + f"Custom code guardrail '{self.guardrail_name}': Modifying {input_type}" + ) + + # Apply modifications + modified_inputs = dict(inputs) + + if "texts" in result and result["texts"] is not None: + modified_inputs["texts"] = result["texts"] + + if "images" in result and result["images"] is not None: + modified_inputs["images"] = result["images"] + + if "tool_calls" in result and result["tool_calls"] is not None: + modified_inputs["tool_calls"] = result["tool_calls"] + + return cast(GenericGuardrailAPIInputs, modified_inputs) + + else: + verbose_proxy_logger.warning( + f"Custom code guardrail '{self.guardrail_name}': " + f"Unknown action '{action}'. Treating as allow." + ) + return inputs + + def update_custom_code(self, new_code: str) -> None: + """ + Update the custom code and recompile. + + This method allows hot-reloading of guardrail logic without + restarting the server. + + Args: + new_code: The new source code + + Raises: + CustomCodeCompilationError: If the new code fails to compile + """ + with self._compile_lock: + # Reset state + old_function = self._compiled_function + old_code = self.custom_code + self._compiled_function = None + self._compile_error = None + + try: + self.custom_code = new_code + self._compile_custom_code() + verbose_proxy_logger.info( + f"Custom code guardrail '{self.guardrail_name}': Code updated successfully" + ) + except CustomCodeCompilationError: + # Rollback on failure + self.custom_code = old_code + self._compiled_function = old_function + raise diff --git a/litellm/proxy/guardrails/guardrail_hooks/custom_code/primitives.py b/litellm/proxy/guardrails/guardrail_hooks/custom_code/primitives.py new file mode 100644 index 00000000000..695e59977c8 --- /dev/null +++ b/litellm/proxy/guardrails/guardrail_hooks/custom_code/primitives.py @@ -0,0 +1,602 @@ +""" +Built-in primitives provided to custom code guardrails. + +These functions are injected into the custom code execution environment +and provide safe, sandboxed functionality for common guardrail operations. +""" + +import json +import re +from typing import Any, Dict, List, Optional, Tuple, Type, Union +from urllib.parse import urlparse + +from litellm._logging import verbose_proxy_logger + +# ============================================================================= +# Result Types - Used by Starlark code to return guardrail decisions +# ============================================================================= + + +def allow() -> Dict[str, Any]: + """ + Allow the request/response to proceed unchanged. + + Returns: + Dict indicating the request should be allowed + """ + return {"action": "allow"} + + +def block( + reason: str, detection_info: Optional[Dict[str, Any]] = None +) -> Dict[str, Any]: + """ + Block the request/response with a reason. + + Args: + reason: Human-readable reason for blocking + detection_info: Optional additional detection metadata + + Returns: + Dict indicating the request should be blocked + """ + result: Dict[str, Any] = {"action": "block", "reason": reason} + if detection_info: + result["detection_info"] = detection_info + return result + + +def modify( + texts: Optional[List[str]] = None, + images: Optional[List[Any]] = None, + tool_calls: Optional[List[Any]] = None, +) -> Dict[str, Any]: + """ + Modify the request/response content. + + Args: + texts: Modified text content (if None, keeps original) + images: Modified image content (if None, keeps original) + tool_calls: Modified tool calls (if None, keeps original) + + Returns: + Dict indicating the content should be modified + """ + result: Dict[str, Any] = {"action": "modify"} + if texts is not None: + result["texts"] = texts + if images is not None: + result["images"] = images + if tool_calls is not None: + result["tool_calls"] = tool_calls + return result + + +# ============================================================================= +# Regex Primitives +# ============================================================================= + + +def regex_match(text: str, pattern: str, flags: int = 0) -> bool: + """ + Check if a regex pattern matches anywhere in the text. + + Args: + text: The text to search in + pattern: The regex pattern to match + flags: Optional regex flags (default: 0) + + Returns: + True if pattern matches, False otherwise + """ + try: + return bool(re.search(pattern, text, flags)) + except re.error as e: + verbose_proxy_logger.warning(f"Starlark regex_match error: {e}") + return False + + +def regex_match_all(text: str, pattern: str, flags: int = 0) -> bool: + """ + Check if a regex pattern matches the entire text. + + Args: + text: The text to match + pattern: The regex pattern + flags: Optional regex flags + + Returns: + True if pattern matches entire text, False otherwise + """ + try: + return bool(re.fullmatch(pattern, text, flags)) + except re.error as e: + verbose_proxy_logger.warning(f"Starlark regex_match_all error: {e}") + return False + + +def regex_replace(text: str, pattern: str, replacement: str, flags: int = 0) -> str: + """ + Replace all occurrences of a pattern in text. + + Args: + text: The text to modify + pattern: The regex pattern to find + replacement: The replacement string + flags: Optional regex flags + + Returns: + The text with replacements applied + """ + try: + return re.sub(pattern, replacement, text, flags=flags) + except re.error as e: + verbose_proxy_logger.warning(f"Starlark regex_replace error: {e}") + return text + + +def regex_find_all(text: str, pattern: str, flags: int = 0) -> List[str]: + """ + Find all occurrences of a pattern in text. + + Args: + text: The text to search + pattern: The regex pattern to find + flags: Optional regex flags + + Returns: + List of all matches + """ + try: + return re.findall(pattern, text, flags) + except re.error as e: + verbose_proxy_logger.warning(f"Starlark regex_find_all error: {e}") + return [] + + +# ============================================================================= +# JSON Primitives +# ============================================================================= + + +def json_parse(text: str) -> Optional[Any]: + """ + Parse a JSON string into a Python object. + + Args: + text: The JSON string to parse + + Returns: + Parsed Python object, or None if parsing fails + """ + try: + return json.loads(text) + except (json.JSONDecodeError, TypeError) as e: + verbose_proxy_logger.debug(f"Starlark json_parse error: {e}") + return None + + +def json_stringify(obj: Any) -> str: + """ + Convert a Python object to a JSON string. + + Args: + obj: The object to serialize + + Returns: + JSON string representation + """ + try: + return json.dumps(obj) + except (TypeError, ValueError) as e: + verbose_proxy_logger.warning(f"Starlark json_stringify error: {e}") + return "" + + +def json_schema_valid(obj: Any, schema: Dict[str, Any]) -> bool: + """ + Validate an object against a JSON schema. + + Args: + obj: The object to validate + schema: The JSON schema to validate against + + Returns: + True if valid, False otherwise + """ + try: + # Try to import jsonschema, fall back to basic validation if not available + try: + import jsonschema + + jsonschema.validate(instance=obj, schema=schema) + return True + except ImportError: + # Basic validation without jsonschema library + return _basic_json_schema_validate(obj, schema) + except Exception as validation_error: + # Catch jsonschema.ValidationError and other validation errors + if "ValidationError" in type(validation_error).__name__: + return False + raise + except Exception as e: + verbose_proxy_logger.warning(f"Custom code json_schema_valid error: {e}") + return False + + +def _basic_json_schema_validate( + obj: Any, schema: Dict[str, Any], max_depth: int = 50 +) -> bool: + """ + Basic JSON schema validation without external library. + Handles: type, required, properties + + Uses an iterative approach with a stack to avoid recursion limits. + max_depth limits nesting to prevent infinite loops from circular schemas. + """ + type_map: Dict[str, Union[Type, Tuple[Type, ...]]] = { + "object": dict, + "array": list, + "string": str, + "number": (int, float), + "integer": int, + "boolean": bool, + "null": type(None), + } + + # Stack of (obj, schema, depth) tuples to process + stack: List[Tuple[Any, Dict[str, Any], int]] = [(obj, schema, 0)] + + while stack: + current_obj, current_schema, depth = stack.pop() + + # Circuit breaker: stop if we've gone too deep + if depth > max_depth: + return False + + # Check type + schema_type = current_schema.get("type") + if schema_type: + expected_type = type_map.get(schema_type) + if expected_type is not None and not isinstance(current_obj, expected_type): + return False + + # Check required fields and properties for dicts + if isinstance(current_obj, dict): + required = current_schema.get("required", []) + for field in required: + if field not in current_obj: + return False + + # Queue property validations + properties = current_schema.get("properties", {}) + for prop_name, prop_schema in properties.items(): + if prop_name in current_obj: + stack.append((current_obj[prop_name], prop_schema, depth + 1)) + + return True + + +# ============================================================================= +# URL Primitives +# ============================================================================= + + +# Common URL pattern for extraction +_URL_PATTERN = re.compile( + r"https?://(?:[-\w.]|(?:%[\da-fA-F]{2}))+[^\s]*", re.IGNORECASE +) + + +def extract_urls(text: str) -> List[str]: + """ + Extract all URLs from text. + + Args: + text: The text to search for URLs + + Returns: + List of URLs found in the text + """ + return _URL_PATTERN.findall(text) + + +def is_valid_url(url: str) -> bool: + """ + Check if a URL is syntactically valid. + + Args: + url: The URL to validate + + Returns: + True if the URL is valid, False otherwise + """ + try: + result = urlparse(url) + return all([result.scheme, result.netloc]) + except Exception: + return False + + +def all_urls_valid(text: str) -> bool: + """ + Check if all URLs in text are valid. + + Args: + text: The text containing URLs + + Returns: + True if all URLs are valid (or no URLs), False otherwise + """ + urls = extract_urls(text) + return all(is_valid_url(url) for url in urls) + + +def get_url_domain(url: str) -> Optional[str]: + """ + Extract the domain from a URL. + + Args: + url: The URL to parse + + Returns: + The domain, or None if invalid + """ + try: + result = urlparse(url) + return result.netloc if result.netloc else None + except Exception: + return None + + +# ============================================================================= +# Code Detection Primitives +# ============================================================================= + + +# Common code patterns for detection +_CODE_PATTERNS = { + "sql": [ + r"\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b.*\b(FROM|INTO|TABLE|SET|WHERE)\b", + r"\b(SELECT)\s+[\w\*,\s]+\s+FROM\s+\w+", + r"\b(INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM)\b", + ], + "python": [ + r"^\s*(def|class|import|from|if|for|while|try|except|with)\s+", + r"^\s*@\w+", # decorators + r"\b(print|len|range|str|int|float|list|dict|set)\s*\(", + ], + "javascript": [ + r"\b(function|const|let|var|class|import|export)\s+", + r"=>", # arrow functions + r"\b(console\.(log|error|warn))\s*\(", + ], + "typescript": [ + r":\s*(string|number|boolean|any|void|never)\b", + r"\b(interface|type|enum)\s+\w+", + r"<[A-Z]\w*>", # generics + ], + "java": [ + r"\b(public|private|protected)\s+(static\s+)?(class|void|int|String)\b", + r"\bSystem\.(out|err)\.print", + ], + "go": [ + r"\bfunc\s+\w+\s*\(", + r"\b(package|import)\s+", + r":=", # short variable declaration + ], + "rust": [ + r"\b(fn|let|mut|impl|struct|enum|pub|mod)\s+", + r"->", # return type + r"\b(println!|format!)\s*\(", + ], + "shell": [ + r"^#!.*\b(bash|sh|zsh)\b", + r"\b(echo|grep|sed|awk|cat|ls|cd|mkdir|rm)\s+", + r"\$\{?\w+\}?", # variable expansion + ], + "html": [ + r"<\s*(html|head|body|div|span|p|a|img|script|style)\b[^>]*>", + r"", + ], + "css": [ + r"\{[^}]*:\s*[^}]+;[^}]*\}", + r"@(media|keyframes|import|font-face)\b", + ], +} + + +def detect_code(text: str) -> bool: + """ + Check if text contains code of any language. + + Args: + text: The text to check + + Returns: + True if code is detected, False otherwise + """ + return len(detect_code_languages(text)) > 0 + + +def detect_code_languages(text: str) -> List[str]: + """ + Detect which programming languages are present in text. + + Args: + text: The text to analyze + + Returns: + List of detected language names + """ + detected = [] + for lang, patterns in _CODE_PATTERNS.items(): + for pattern in patterns: + try: + if re.search(pattern, text, re.IGNORECASE | re.MULTILINE): + detected.append(lang) + break # Only add each language once + except re.error: + continue + return detected + + +def contains_code_language(text: str, languages: List[str]) -> bool: + """ + Check if text contains code from specific languages. + + Args: + text: The text to check + languages: List of language names to check for + + Returns: + True if any of the specified languages are detected + """ + detected = detect_code_languages(text) + return any(lang.lower() in [d.lower() for d in detected] for lang in languages) + + +# ============================================================================= +# Text Utility Primitives +# ============================================================================= + + +def contains(text: str, substring: str) -> bool: + """ + Check if text contains a substring. + + Args: + text: The text to search in + substring: The substring to find + + Returns: + True if substring is found, False otherwise + """ + return substring in text + + +def contains_any(text: str, substrings: List[str]) -> bool: + """ + Check if text contains any of the given substrings. + + Args: + text: The text to search in + substrings: List of substrings to find + + Returns: + True if any substring is found, False otherwise + """ + return any(s in text for s in substrings) + + +def contains_all(text: str, substrings: List[str]) -> bool: + """ + Check if text contains all of the given substrings. + + Args: + text: The text to search in + substrings: List of substrings to find + + Returns: + True if all substrings are found, False otherwise + """ + return all(s in text for s in substrings) + + +def word_count(text: str) -> int: + """ + Count the number of words in text. + + Args: + text: The text to count words in + + Returns: + Number of words + """ + return len(text.split()) + + +def char_count(text: str) -> int: + """ + Count the number of characters in text. + + Args: + text: The text to count characters in + + Returns: + Number of characters + """ + return len(text) + + +def lower(text: str) -> str: + """Convert text to lowercase.""" + return text.lower() + + +def upper(text: str) -> str: + """Convert text to uppercase.""" + return text.upper() + + +def trim(text: str) -> str: + """Remove leading and trailing whitespace.""" + return text.strip() + + +# ============================================================================= +# Primitives Registry +# ============================================================================= + + +def get_custom_code_primitives() -> Dict[str, Any]: + """ + Get all primitives to inject into the custom code environment. + + Returns: + Dict of function name to function + """ + return { + # Result types + "allow": allow, + "block": block, + "modify": modify, + # Regex + "regex_match": regex_match, + "regex_match_all": regex_match_all, + "regex_replace": regex_replace, + "regex_find_all": regex_find_all, + # JSON + "json_parse": json_parse, + "json_stringify": json_stringify, + "json_schema_valid": json_schema_valid, + # URL + "extract_urls": extract_urls, + "is_valid_url": is_valid_url, + "all_urls_valid": all_urls_valid, + "get_url_domain": get_url_domain, + # Code detection + "detect_code": detect_code, + "detect_code_languages": detect_code_languages, + "contains_code_language": contains_code_language, + # Text utilities + "contains": contains, + "contains_any": contains_any, + "contains_all": contains_all, + "word_count": word_count, + "char_count": char_count, + "lower": lower, + "upper": upper, + "trim": trim, + # Python builtins (safe subset) + "len": len, + "str": str, + "int": int, + "float": float, + "bool": bool, + "list": list, + "dict": dict, + "True": True, + "False": False, + "None": None, + } diff --git a/litellm/types/guardrails.py b/litellm/types/guardrails.py index ed463491043..3f7de10dde6 100644 --- a/litellm/types/guardrails.py +++ b/litellm/types/guardrails.py @@ -14,14 +14,14 @@ from litellm.types.proxy.guardrails.guardrail_hooks.grayswan import ( from litellm.types.proxy.guardrails.guardrail_hooks.ibm import ( IBMGuardrailsBaseConfigModel, ) -from litellm.types.proxy.guardrails.guardrail_hooks.tool_permission import ( - ToolPermissionGuardrailConfigModel, +from litellm.types.proxy.guardrails.guardrail_hooks.litellm_content_filter import ( + ContentFilterCategoryConfig, ) from litellm.types.proxy.guardrails.guardrail_hooks.qualifire import ( QualifireGuardrailConfigModel, ) -from litellm.types.proxy.guardrails.guardrail_hooks.litellm_content_filter import ( - ContentFilterCategoryConfig, +from litellm.types.proxy.guardrails.guardrail_hooks.tool_permission import ( + ToolPermissionGuardrailConfigModel, ) """ @@ -68,6 +68,7 @@ class SupportedGuardrailIntegrations(Enum): PROMPT_SECURITY = "prompt_security" GENERIC_GUARDRAIL_API = "generic_guardrail_api" QUALIFIRE = "qualifire" + CUSTOM_CODE = "custom_code" class Role(Enum): @@ -296,13 +297,7 @@ class PresidioConfigModel(PresidioPresidioConfigModelUserInterface): pii_entities_config: Optional[Dict[Union[PiiEntityType, str], PiiAction]] = Field( default=None, description="Configuration for PII entity types and actions" ) - presidio_filter_scope: Literal["input", "output", "both"] = Field( - default="both", - description=( - "Where to apply Presidio checks: 'input' runs on user → model traffic, " - "'output' runs on model → user traffic, and 'both' applies to both." - ), - ) + presidio_score_thresholds: Optional[Dict[Union[PiiEntityType, str], float]] = Field( default=None, description=( @@ -656,6 +651,12 @@ class BaseLitellmParams( description="Additional provider-specific parameters for generic guardrail APIs", ) + # Custom code guardrail params + custom_code: Optional[str] = Field( + default=None, + description="Python-like code containing the apply_guardrail function for custom guardrail logic", + ) + model_config = ConfigDict(extra="allow", protected_namespaces=()) diff --git a/tests/code_coverage_tests/recursive_detector.py b/tests/code_coverage_tests/recursive_detector.py index ed7595bb023..71e7798b09e 100644 --- a/tests/code_coverage_tests/recursive_detector.py +++ b/tests/code_coverage_tests/recursive_detector.py @@ -40,6 +40,7 @@ IGNORE_FUNCTIONS = [ "filter_exceptions_from_params", # max depth set (default 20) to prevent infinite recursion. "__getattr__", # lazy loading pattern in litellm/__init__.py with proper caching to prevent infinite recursion. "_validate_inheritance_chain", # max depth set (default 100) to prevent infinite recursion in policy inheritance validation. + "_basic_json_schema_validate", # max depth set. "extract_text_from_a2a_message", # max depth set (default 10) to prevent infinite recursion in A2A message parsing. ] diff --git a/ui/litellm-dashboard/src/components/guardrails.tsx b/ui/litellm-dashboard/src/components/guardrails.tsx index 26b9acb6a26..d0031b872f7 100644 --- a/ui/litellm-dashboard/src/components/guardrails.tsx +++ b/ui/litellm-dashboard/src/components/guardrails.tsx @@ -1,5 +1,7 @@ import React, { useState, useEffect } from "react"; import { Button, TabGroup, TabList, Tab, TabPanels, TabPanel } from "@tremor/react"; +import { Dropdown } from "antd"; +import { DownOutlined, PlusOutlined, CodeOutlined } from "@ant-design/icons"; import { getGuardrailsList, deleteGuardrailCall } from "./networking"; import AddGuardrailForm from "./guardrails/add_guardrail_form"; import GuardrailTable from "./guardrails/guardrail_table"; @@ -10,6 +12,7 @@ import NotificationsManager from "./molecules/notifications_manager"; import { Guardrail, GuardrailDefinitionLocation } from "./guardrails/types"; import DeleteResourceModal from "./common_components/DeleteResourceModal"; import { getGuardrailLogoAndName } from "./guardrails/guardrail_info_helpers"; +import { CustomCodeModal } from "./guardrails/custom_code"; interface GuardrailsPanelProps { accessToken: string | null; @@ -37,6 +40,7 @@ interface GuardrailsResponse { const GuardrailsPanel: React.FC = ({ accessToken, userRole }) => { const [guardrailsList, setGuardrailsList] = useState([]); const [isAddModalVisible, setIsAddModalVisible] = useState(false); + const [isCustomCodeModalVisible, setIsCustomCodeModalVisible] = useState(false); const [isLoading, setIsLoading] = useState(false); const [isDeleting, setIsDeleting] = useState(false); const [guardrailToDelete, setGuardrailToDelete] = useState(null); @@ -74,10 +78,21 @@ const GuardrailsPanel: React.FC = ({ accessToken, userRole setIsAddModalVisible(true); }; + const handleAddCustomCodeGuardrail = () => { + if (selectedGuardrailId) { + setSelectedGuardrailId(null); + } + setIsCustomCodeModalVisible(true); + }; + const handleCloseModal = () => { setIsAddModalVisible(false); }; + const handleCloseCustomCodeModal = () => { + setIsCustomCodeModalVisible(false); + }; + const handleSuccess = () => { fetchGuardrails(); }; @@ -128,9 +143,30 @@ const GuardrailsPanel: React.FC = ({ accessToken, userRole
- + , + label: "Add Provider Guardrail", + onClick: handleAddGuardrail, + }, + { + key: "custom_code", + icon: , + label: "Create Custom Code Guardrail", + onClick: handleAddCustomCodeGuardrail, + }, + ], + }} + trigger={["click"]} + disabled={!accessToken} + > + +
{selectedGuardrailId ? ( @@ -159,6 +195,13 @@ const GuardrailsPanel: React.FC = ({ accessToken, userRole onSuccess={handleSuccess} /> + + void; + height?: string; + placeholder?: string; + disabled?: boolean; +} + +const CustomCodeEditor: React.FC = ({ + value, + onChange, + height = "350px", + placeholder = `def apply_guardrail(inputs, request_data, input_type): + # inputs: contains texts, images, tools, tool_calls, structured_messages, model + # request_data: contains model, user_id, team_id, end_user_id, metadata + # input_type: "request" or "response" + + for text in inputs["texts"]: + # Example: Block if SSN pattern is detected + if regex_match(text, r"\\d{3}-\\d{2}-\\d{4}"): + return block("SSN detected in message") + + return allow()`, + disabled = false, +}) => { + const textareaRef = useRef(null); + const [activeTab, setActiveTab] = useState("edit"); + const [cursorPosition, setCursorPosition] = useState({ line: 1, column: 1 }); + + // Calculate cursor position + const updateCursorPosition = () => { + if (textareaRef.current) { + const textarea = textareaRef.current; + const textBeforeCursor = value.substring(0, textarea.selectionStart); + const lines = textBeforeCursor.split("\n"); + const line = lines.length; + const column = lines[lines.length - 1].length + 1; + setCursorPosition({ line, column }); + } + }; + + // Handle tab key for indentation + const handleKeyDown = (e: React.KeyboardEvent) => { + if (e.key === "Tab") { + e.preventDefault(); + const textarea = e.currentTarget; + const start = textarea.selectionStart; + const end = textarea.selectionEnd; + + // Insert 4 spaces at cursor position + const newValue = value.substring(0, start) + " " + value.substring(end); + onChange(newValue); + + // Move cursor after the inserted spaces + setTimeout(() => { + textarea.selectionStart = textarea.selectionEnd = start + 4; + }, 0); + } + }; + + const lineCount = value.split("\n").length; + + const tabItems = [ + { + key: "edit", + label: ( + + + Edit + + ), + children: ( +
+ {/* Line numbers */} +
+ {Array.from({ length: Math.max(lineCount, 15) }, (_, i) => ( +
+ {i + 1} +
+ ))} +
+ + {/* Code editor */} +