From b4f9e14a44789b408c3ceab56d01671f33a7b3d0 Mon Sep 17 00:00:00 2001 From: milan Date: Tue, 28 Jul 2026 14:14:53 +0000 Subject: [PATCH 01/13] feat(dd_span_tagger): emit litellm_user_email span tag for JWT-authenticated requests Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- litellm/proxy/dd_span_tagger.py | 8 +++++- .../proxy/test_common_request_processing.py | 27 ++++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/litellm/proxy/dd_span_tagger.py b/litellm/proxy/dd_span_tagger.py index 08b7d928d0e..1fda0c638d4 100644 --- a/litellm/proxy/dd_span_tagger.py +++ b/litellm/proxy/dd_span_tagger.py @@ -38,11 +38,15 @@ class DDSpanTagger: - ``litellm.key_alias`` — human-readable alias for the API key - ``litellm.key_hash`` — hashed API key (safe to log; never the raw secret) - ``litellm.requested_model``— model name as sent by the client + - ``litellm_user_email`` — email of the authenticated user Use cases: - Trace all requests from a specific user/key: filter by ``litellm.key_alias`` or ``litellm.key_hash``. - Trace all requests for a specific model: filter by ``litellm.requested_model``. + - Trace all requests from a specific person under JWT auth, where there is no key_alias: + filter by ``@litellm_user_email:"user@example.com"``. The value comes from the JWT claim + mapped by ``litellm_jwtauth.user_email_jwt_field``, or from the user row for virtual keys. Note: key_alias / key_hash are not available for unauthenticated (e.g. 401) requests. """ @@ -53,8 +57,10 @@ class DDSpanTagger: set_active_span_tag("litellm.key_hash", str(user_api_key_dict.token)) if requested_model: set_active_span_tag("litellm.requested_model", str(requested_model)) + if user_api_key_dict.user_email: + set_active_span_tag("litellm_user_email", str(user_api_key_dict.user_email)) except Exception: verbose_proxy_logger.debug( - "Failed to tag active ddtrace span with key/model tags", + "Failed to tag active ddtrace span with key/model/user tags", exc_info=True, ) diff --git a/tests/test_litellm/proxy/test_common_request_processing.py b/tests/test_litellm/proxy/test_common_request_processing.py index 58f81cdad35..287e6f2f80c 100644 --- a/tests/test_litellm/proxy/test_common_request_processing.py +++ b/tests/test_litellm/proxy/test_common_request_processing.py @@ -2318,12 +2318,13 @@ class TestStreamingOverheadHeader: class TestDDSpanTaggerTagRequest: """Tests for DDSpanTagger.tag_request - key/model DD span tagging.""" - def _make_user_api_key_dict(self, key_alias=None, token=None): + def _make_user_api_key_dict(self, key_alias=None, token=None, user_email=None): from litellm.proxy._types import UserAPIKeyAuth d = UserAPIKeyAuth() d.key_alias = key_alias d.token = token + d.user_email = user_email return d def test_tags_key_alias_and_model(self): @@ -2364,6 +2365,30 @@ class TestDDSpanTaggerTagRequest: mock_set_tag.assert_called_once_with("litellm.requested_model", "claude-3-5-sonnet") + def test_tags_user_email(self): + """user_email is tagged so JWT-authenticated requests are traceable per person.""" + user_key = self._make_user_api_key_dict(user_email="user@example.com") + + with patch("litellm.proxy.dd_span_tagger.set_active_span_tag") as mock_set_tag: + DDSpanTagger.tag_request( + user_api_key_dict=user_key, + requested_model=None, + ) + + mock_set_tag.assert_called_once_with("litellm_user_email", "user@example.com") + + def test_no_user_email_tag_when_absent(self): + """No user email tag when the authenticated identity has no email.""" + user_key = self._make_user_api_key_dict(key_alias="my-prod-key", user_email=None) + + with patch("litellm.proxy.dd_span_tagger.set_active_span_tag") as mock_set_tag: + DDSpanTagger.tag_request( + user_api_key_dict=user_key, + requested_model="gpt-4o", + ) + + assert all(call.args[0] != "litellm_user_email" for call in mock_set_tag.call_args_list) + class TestHasAttributeErrorInChain: """Tests for _has_attribute_error_in_chain helper.""" From 819faa01c336d825619b3592ed1c1d763a4156d4 Mon Sep 17 00:00:00 2001 From: milan Date: Tue, 28 Jul 2026 14:40:04 +0000 Subject: [PATCH 02/13] refactor(dd_span_tagger): use dotted litellm.user_email tag for consistency Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- litellm/proxy/dd_span_tagger.py | 6 +++--- tests/test_litellm/proxy/test_common_request_processing.py | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/litellm/proxy/dd_span_tagger.py b/litellm/proxy/dd_span_tagger.py index 1fda0c638d4..cafae9bb2a3 100644 --- a/litellm/proxy/dd_span_tagger.py +++ b/litellm/proxy/dd_span_tagger.py @@ -38,14 +38,14 @@ class DDSpanTagger: - ``litellm.key_alias`` — human-readable alias for the API key - ``litellm.key_hash`` — hashed API key (safe to log; never the raw secret) - ``litellm.requested_model``— model name as sent by the client - - ``litellm_user_email`` — email of the authenticated user + - ``litellm.user_email`` — email of the authenticated user Use cases: - Trace all requests from a specific user/key: filter by ``litellm.key_alias`` or ``litellm.key_hash``. - Trace all requests for a specific model: filter by ``litellm.requested_model``. - Trace all requests from a specific person under JWT auth, where there is no key_alias: - filter by ``@litellm_user_email:"user@example.com"``. The value comes from the JWT claim + filter by ``@litellm.user_email:"user@example.com"``. The value comes from the JWT claim mapped by ``litellm_jwtauth.user_email_jwt_field``, or from the user row for virtual keys. Note: key_alias / key_hash are not available for unauthenticated (e.g. 401) requests. @@ -58,7 +58,7 @@ class DDSpanTagger: if requested_model: set_active_span_tag("litellm.requested_model", str(requested_model)) if user_api_key_dict.user_email: - set_active_span_tag("litellm_user_email", str(user_api_key_dict.user_email)) + set_active_span_tag("litellm.user_email", str(user_api_key_dict.user_email)) except Exception: verbose_proxy_logger.debug( "Failed to tag active ddtrace span with key/model/user tags", diff --git a/tests/test_litellm/proxy/test_common_request_processing.py b/tests/test_litellm/proxy/test_common_request_processing.py index 287e6f2f80c..312c3d2a884 100644 --- a/tests/test_litellm/proxy/test_common_request_processing.py +++ b/tests/test_litellm/proxy/test_common_request_processing.py @@ -2375,7 +2375,7 @@ class TestDDSpanTaggerTagRequest: requested_model=None, ) - mock_set_tag.assert_called_once_with("litellm_user_email", "user@example.com") + mock_set_tag.assert_called_once_with("litellm.user_email", "user@example.com") def test_no_user_email_tag_when_absent(self): """No user email tag when the authenticated identity has no email.""" @@ -2387,7 +2387,7 @@ class TestDDSpanTaggerTagRequest: requested_model="gpt-4o", ) - assert all(call.args[0] != "litellm_user_email" for call in mock_set_tag.call_args_list) + assert all(call.args[0] != "litellm.user_email" for call in mock_set_tag.call_args_list) class TestHasAttributeErrorInChain: From b224b15b9d24c15590a81c3c4bb5399d40b7d9e0 Mon Sep 17 00:00:00 2001 From: milan Date: Fri, 21 Aug 2026 02:41:55 +0000 Subject: [PATCH 03/13] feat(model_hub): surface model_info.description in model group info and Model Hub UI Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- litellm/router.py | 6 +++++ litellm/types/router.py | 1 + tests/test_litellm/test_router.py | 25 +++++++++++++++++++ .../src/components/AIHub/ModelHubTable.tsx | 6 +++++ .../components/AIHub/ModelHubTableColumns.tsx | 1 + .../components/PublicModelHubTableColumns.tsx | 1 + .../src/components/public_model_hub.tsx | 6 +++++ ui/litellm-dashboard/src/lib/http/schema.d.ts | 2 ++ 8 files changed, 48 insertions(+) diff --git a/litellm/router.py b/litellm/router.py index e9eeab53934..90968800460 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -9334,6 +9334,9 @@ class Router: model_litellm_params = model.get("litellm_params", {}) model_info_dict = model.get("model_info", {}) + _raw_description = model_info_dict.get("description") + _deployment_description: str | None = _raw_description if isinstance(_raw_description, str) else None + # get model tpm _deployment_tpm: int | None = None if _deployment_tpm is None: @@ -9415,6 +9418,7 @@ class Router: **{ "model_group": user_facing_model_group_name, "providers": [llm_provider], + "description": _deployment_description, **model_info, } ) @@ -9428,6 +9432,8 @@ class Router: # supports_function_calling == True if llm_provider not in model_group_info.providers: model_group_info.providers.append(llm_provider) + if model_group_info.description is None and _deployment_description is not None: + model_group_info.description = _deployment_description if ( model_info.get("max_input_tokens", None) is not None and model_info["max_input_tokens"] is not None diff --git a/litellm/types/router.py b/litellm/types/router.py index 99a4603ae49..b33e387c508 100644 --- a/litellm/types/router.py +++ b/litellm/types/router.py @@ -637,6 +637,7 @@ class ModelGroupInfo(BaseModel): supports_function_calling: bool = Field(default=False) supported_openai_params: list[str] | None = Field(default=[]) configurable_clientside_auth_params: CONFIGURABLE_CLIENTSIDE_AUTH_PARAMS = None + description: str | None = None def __init__(self, **data) -> None: for field_name, field_type in get_type_hints(self.__class__).items(): diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py index 9894fcef163..765e479e378 100644 --- a/tests/test_litellm/test_router.py +++ b/tests/test_litellm/test_router.py @@ -1626,6 +1626,31 @@ def test_model_group_info_cost_none_when_db_model_info_has_no_cost(): assert result.output_cost_per_token is None +def test_model_group_info_description_from_model_info(): + """ + model_info.description set in the config should surface on ModelGroupInfo, + including when only a later deployment in the group carries it. + """ + router = litellm.Router( + model_list=[ + { + "model_name": "gpt-4", + "litellm_params": {"model": "gpt-4", "api_key": "fake"}, + "model_info": {}, + }, + { + "model_name": "gpt-4", + "litellm_params": {"model": "gpt-4", "api_key": "fake2"}, + "model_info": {"description": "State-of-the-art language model."}, + }, + ] + ) + + result = router.get_model_group_info("gpt-4") + assert result is not None + assert result.description == "State-of-the-art language model." + + @pytest.mark.parametrize( "value,expected", [ diff --git a/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx b/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx index 299104b271b..5fadbe3300d 100644 --- a/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx +++ b/ui/litellm-dashboard/src/components/AIHub/ModelHubTable.tsx @@ -647,6 +647,12 @@ const ModelHubTable: React.FC = ({ accessToken, publicPage, ))} + {selectedModel.description && ( +
+

Description:

+

{selectedModel.description}

+
+ )} diff --git a/ui/litellm-dashboard/src/components/AIHub/ModelHubTableColumns.tsx b/ui/litellm-dashboard/src/components/AIHub/ModelHubTableColumns.tsx index 9f74771f3b1..b025bcf62aa 100644 --- a/ui/litellm-dashboard/src/components/AIHub/ModelHubTableColumns.tsx +++ b/ui/litellm-dashboard/src/components/AIHub/ModelHubTableColumns.tsx @@ -31,6 +31,7 @@ export interface ModelHubData { supports_function_calling: boolean; supported_openai_params?: string[]; is_public_model_group: boolean; + description?: string; [key: string]: any; } diff --git a/ui/litellm-dashboard/src/components/PublicModelHubTableColumns.tsx b/ui/litellm-dashboard/src/components/PublicModelHubTableColumns.tsx index ab0ed976149..f3673df8025 100644 --- a/ui/litellm-dashboard/src/components/PublicModelHubTableColumns.tsx +++ b/ui/litellm-dashboard/src/components/PublicModelHubTableColumns.tsx @@ -24,6 +24,7 @@ export interface ModelGroupInfo { health_status?: string; health_response_time?: number; health_checked_at?: string; + description?: string; [key: string]: any; } diff --git a/ui/litellm-dashboard/src/components/public_model_hub.tsx b/ui/litellm-dashboard/src/components/public_model_hub.tsx index 171b7992325..cd10068b9e6 100644 --- a/ui/litellm-dashboard/src/components/public_model_hub.tsx +++ b/ui/litellm-dashboard/src/components/public_model_hub.tsx @@ -918,6 +918,12 @@ const PublicModelHub: React.FC = ({ accessToken, isEmbedded })} + {selectedModel.description && ( +
+

Description:

+

{selectedModel.description}

+
+ )} {/* Wildcard Routing Note */} diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts index fff48e14ecf..39b3255efb3 100644 --- a/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -29481,6 +29481,8 @@ export interface components { ModelGroupInfoProxy: { /** Configurable Clientside Auth Params */ configurable_clientside_auth_params?: (string | components["schemas"]["ConfigurableClientsideParamsCustomAuth-Output"])[] | null; + /** Description */ + description?: string | null; /** Health Checked At */ health_checked_at?: string | null; /** Health Response Time */ From 342b93fe0a92f32b8c2fb4ccf61441cb0a2cf3b1 Mon Sep 17 00:00:00 2001 From: milan Date: Fri, 21 Aug 2026 03:27:35 +0000 Subject: [PATCH 04/13] refactor(router): aggregate model group description without in-place mutation Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- litellm/router.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/litellm/router.py b/litellm/router.py index 90968800460..d65c13d57b2 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -9313,6 +9313,10 @@ class Router: model_list: Final = self.get_model_list(model_name=model_group) if model_list is None: return None + model_group_description: Final[str | None] = next( + (d for d in (m.get("model_info", {}).get("description") for m in model_list) if isinstance(d, str)), + None, + ) for model in model_list: is_match = False if ( @@ -9334,9 +9338,6 @@ class Router: model_litellm_params = model.get("litellm_params", {}) model_info_dict = model.get("model_info", {}) - _raw_description = model_info_dict.get("description") - _deployment_description: str | None = _raw_description if isinstance(_raw_description, str) else None - # get model tpm _deployment_tpm: int | None = None if _deployment_tpm is None: @@ -9418,7 +9419,7 @@ class Router: **{ "model_group": user_facing_model_group_name, "providers": [llm_provider], - "description": _deployment_description, + "description": model_group_description, **model_info, } ) @@ -9432,8 +9433,6 @@ class Router: # supports_function_calling == True if llm_provider not in model_group_info.providers: model_group_info.providers.append(llm_provider) - if model_group_info.description is None and _deployment_description is not None: - model_group_info.description = _deployment_description if ( model_info.get("max_input_tokens", None) is not None and model_info["max_input_tokens"] is not None From 6d2c4899b0f9fa36c59c793657234f75b6a83704 Mon Sep 17 00:00:00 2001 From: yassin Date: Sun, 13 Sep 2026 09:44:22 +0000 Subject: [PATCH 05/13] fix(health): skip background health check DB writes when the latest-row read fails Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- litellm/proxy/db/health_check_latest.py | 8 ++++-- .../health_endpoints/_health_endpoints.py | 7 +++-- .../proxy/db/test_health_check_latest.py | 10 +++++++ .../proxy/test_health_check_functions.py | 27 +++++++++++++++---- 4 files changed, 43 insertions(+), 9 deletions(-) diff --git a/litellm/proxy/db/health_check_latest.py b/litellm/proxy/db/health_check_latest.py index 35bc838379c..21438f095bb 100644 --- a/litellm/proxy/db/health_check_latest.py +++ b/litellm/proxy/db/health_check_latest.py @@ -74,10 +74,14 @@ class LatestHealthCheckRow(BaseModel): _ROWS_ADAPTER: Final = TypeAdapter(tuple[LatestHealthCheckRow, ...]) +async def query_latest_health_checks(prisma_client: PrismaClient) -> tuple[LatestHealthCheckRow, ...]: + rows: Final = await prisma_client.db.query_raw(LATEST_HEALTH_CHECKS_SQL) + return _ROWS_ADAPTER.validate_python(rows) + + async def fetch_latest_health_checks(prisma_client: PrismaClient) -> tuple[LatestHealthCheckRow, ...]: try: - rows: Final = await prisma_client.db.query_raw(LATEST_HEALTH_CHECKS_SQL) - return _ROWS_ADAPTER.validate_python(rows) + return await query_latest_health_checks(prisma_client) except Exception as query_err: # noqa: BLE001 # health decorates other reads; a driver error must not fail them verbose_proxy_logger.error("Error getting all latest health checks: %s", query_err) return () diff --git a/litellm/proxy/health_endpoints/_health_endpoints.py b/litellm/proxy/health_endpoints/_health_endpoints.py index db6ec754c6e..64fd59bbe44 100644 --- a/litellm/proxy/health_endpoints/_health_endpoints.py +++ b/litellm/proxy/health_endpoints/_health_endpoints.py @@ -45,7 +45,10 @@ from litellm.proxy.auth.auth_utils import ( from litellm.proxy.auth.model_checks import get_key_models from litellm.proxy.auth.user_api_key_auth import user_api_key_auth from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler -from litellm.proxy.db.health_check_latest import LatestHealthCheckRow +from litellm.proxy.db.health_check_latest import ( + LatestHealthCheckRow, + query_latest_health_checks, +) from litellm.proxy.db.proxy_worker_heartbeat import count_live_proxy_workers from litellm.proxy.health_check import ( ADMIN_ONLY_HEALTH_DISPLAY_PARAMS, @@ -876,7 +879,7 @@ async def _save_background_health_checks_to_db( ) # Step 3: Get latest health checks for all models in one query to compare status - latest_checks: Final = await prisma_client.get_all_latest_health_checks() + latest_checks: Final = await query_latest_health_checks(prisma_client) latest_checks_map: Final = {} for check in latest_checks: # Use model_id as primary key, fallback to model_name diff --git a/tests/test_litellm/proxy/db/test_health_check_latest.py b/tests/test_litellm/proxy/db/test_health_check_latest.py index 529e4d8f2e9..6322891ae9e 100644 --- a/tests/test_litellm/proxy/db/test_health_check_latest.py +++ b/tests/test_litellm/proxy/db/test_health_check_latest.py @@ -8,6 +8,7 @@ from litellm.proxy.db.health_check_latest import ( LATEST_HEALTH_CHECKS_SQL, fetch_latest_health_checks, fetch_latest_health_checks_for_models, + query_latest_health_checks, ) @@ -83,6 +84,15 @@ async def test_fetch_all_degrades_to_no_rows_when_the_query_fails(): assert await fetch_latest_health_checks(prisma) == () +@pytest.mark.asyncio +async def test_query_all_raises_when_the_query_fails_instead_of_reading_as_an_empty_table(): + """The background save decides what to write from this read; a failure has to be told apart from no rows.""" + prisma = _prisma([]) + prisma.db.query_raw.side_effect = RuntimeError("db down") + with pytest.raises(RuntimeError, match="db down"): + await query_latest_health_checks(prisma) + + @pytest.mark.asyncio async def test_fetch_all_degrades_to_no_rows_for_a_malformed_row(): assert await fetch_latest_health_checks(_prisma([{"unexpected": "shape"}])) == () diff --git a/tests/test_litellm/proxy/test_health_check_functions.py b/tests/test_litellm/proxy/test_health_check_functions.py index c0c853ae2c5..7d6c5d3cebe 100644 --- a/tests/test_litellm/proxy/test_health_check_functions.py +++ b/tests/test_litellm/proxy/test_health_check_functions.py @@ -374,7 +374,7 @@ async def test_save_background_health_checks_to_db(): """Test the main background health check save function""" mock_prisma = MagicMock() mock_prisma.save_health_check_result = AsyncMock() - mock_prisma.get_all_latest_health_checks = AsyncMock(return_value=[]) + mock_prisma.db.query_raw = AsyncMock(return_value=[]) model_list = [ { @@ -398,9 +398,9 @@ async def test_save_background_health_checks_to_db(): "background_health_check", ) - # Should call get_all_latest_health_checks and save_health_check_result, and report completion + # Should read the latest rows and save_health_check_result, and report completion assert persisted is True - mock_prisma.get_all_latest_health_checks.assert_called_once() + mock_prisma.db.query_raw.assert_awaited_once() mock_prisma.save_health_check_result.assert_called_once() call_kwargs = mock_prisma.save_health_check_result.call_args[1] @@ -493,7 +493,7 @@ def _one_model_setup(): @pytest.mark.asyncio async def test_save_background_health_checks_to_db_returns_false_when_a_write_fails(): mock_prisma = MagicMock() - mock_prisma.get_all_latest_health_checks = AsyncMock(return_value=[]) + mock_prisma.db.query_raw = AsyncMock(return_value=[]) mock_prisma.save_health_check_result = AsyncMock(return_value=None) model_list, healthy_endpoints, unhealthy_endpoints = _one_model_setup() @@ -504,6 +504,23 @@ async def test_save_background_health_checks_to_db_returns_false_when_a_write_fa assert (persisted, mock_prisma.save_health_check_result.await_count) == (False, 1) +@pytest.mark.asyncio +async def test_save_background_health_checks_to_db_writes_nothing_when_the_latest_row_read_fails(mock_prisma): + """ + A failed dedup read must not read as an empty table. Treated that way, every model was written on every + cycle by every pod while the read kept failing, which is what filled the table in production. + """ + mock_prisma.db.query_raw = AsyncMock(side_effect=RuntimeError("db down")) + mock_prisma.save_health_check_result = AsyncMock(return_value={"id": "row"}) + model_list, healthy_endpoints, unhealthy_endpoints = _one_model_setup() + + persisted = await _save_background_health_checks_to_db( + mock_prisma, model_list, healthy_endpoints, unhealthy_endpoints, 1234567890.0, "background_health_check" + ) + + assert (persisted, mock_prisma.save_health_check_result.await_count) == (False, 0) + + @pytest.mark.asyncio async def test_save_background_health_checks_to_db_no_prisma(): """Test graceful handling when no prisma client""" @@ -515,7 +532,7 @@ async def test_save_background_health_checks_to_db_no_prisma(): async def test_save_background_health_checks_to_db_exception_handling(): """Test exception handling in background health check save""" mock_prisma = MagicMock() - mock_prisma.get_all_latest_health_checks = AsyncMock(side_effect=Exception("DB Error")) + mock_prisma.db.query_raw = AsyncMock(side_effect=Exception("DB Error")) model_list = [ { From 4cf791176ba294c3a3990d81a312bd1cc6390f18 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 3 Sep 2026 02:09:39 +0000 Subject: [PATCH 06/13] fix(proxy): stop treating empty budget_duration as a daily reset Empty or unparseable budget_duration values were falling through get_next_standardized_reset_time to next-midnight. Treat blank as unset and raise on garbage so spend is not wiped every 24 hours Fixes #39368 Co-authored-by: Zsanz3 --- litellm/litellm_core_utils/duration_parser.py | 20 ++------- litellm/proxy/_types.py | 21 ++++++++++ .../management_endpoints/team_endpoints.py | 24 ++++++++--- .../test_duration_parser.py | 13 +++--- .../test_team_endpoints.py | 42 +++++++++++++++++++ tests/test_litellm/proxy/test__types.py | 11 +++++ 6 files changed, 101 insertions(+), 30 deletions(-) diff --git a/litellm/litellm_core_utils/duration_parser.py b/litellm/litellm_core_utils/duration_parser.py index 7ac2299b7d8..414369e35c6 100644 --- a/litellm/litellm_core_utils/duration_parser.py +++ b/litellm/litellm_core_utils/duration_parser.py @@ -12,8 +12,6 @@ from datetime import datetime, time, timedelta, timezone, tzinfo from typing import Final from zoneinfo import ZoneInfo -from litellm._logging import verbose_logger - _BUDGET_DURATION_WORD_ALIASES: Final[dict[str, str]] = { "hourly": "1h", "daily": "24h", @@ -135,20 +133,14 @@ def get_next_standardized_reset_time( # Set up timezone and normalize current time current_time, _ = _setup_timezone(current_time, timezone_str) - # Parse duration value, unit = _parse_duration(_normalize_duration(duration)) - if value is None: - verbose_logger.warning( - "Unrecognized budget_duration %r; falling back to a next-midnight reset. " - "Use the format (e.g. '1h', '7d', '30d', '1mo').", - duration, + if value is None or unit not in {"s", "m", "h", "d", "w", "mo"}: + raise ValueError( + f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." ) - return current_time.replace(hour=0, minute=0, second=0, microsecond=0) + timedelta(days=1) - # Midnight of the current day in the specified timezone base_midnight: Final = current_time.replace(hour=0, minute=0, second=0, microsecond=0) - # Handle different time units if unit == "d": return _handle_day_reset(current_time, base_midnight, value, reset_time_of_day) elif unit == "w": @@ -159,11 +151,7 @@ def get_next_standardized_reset_time( return _handle_minute_reset(current_time, base_midnight, value) elif unit == "s": return _handle_second_reset(current_time, base_midnight, value) - elif unit == "mo": - return _handle_month_reset(current_time, base_midnight, value, reset_time_of_day) - else: - # Unrecognized unit, default to next midnight - return base_midnight + timedelta(days=1) + return _handle_month_reset(current_time, base_midnight, value, reset_time_of_day) def _setup_timezone(current_time: datetime, timezone_str: str = "UTC") -> tuple[datetime, tzinfo]: diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index fc05796db5a..ffcb0026f7a 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -1145,6 +1145,12 @@ from litellm.types.object_permission import ( # noqa: E402 ) +def _blank_duration_as_unset(v: object) -> object: + if isinstance(v, str) and v.strip() == "": + return None + return v + + class GenerateRequestBase(LiteLLMPydanticObjectBase): """ Overlapping schema between key and user generate/update requests @@ -1190,6 +1196,11 @@ class GenerateRequestBase(LiteLLMPydanticObjectBase): return None return v + @field_validator("budget_duration", mode="before") + @classmethod + def empty_budget_duration_is_unset(cls, v: object) -> object: + return _blank_duration_as_unset(v) + class AllowedVectorStoreIndexItem(LiteLLMPydanticObjectBase): index_name: str @@ -2044,6 +2055,11 @@ class NewTeamRequest(TeamBase): return None return v + @field_validator("budget_duration", "team_member_budget_duration", mode="before") + @classmethod + def empty_budget_duration_is_unset(cls, v: object) -> object: + return _blank_duration_as_unset(v) + class GlobalEndUsersSpend(LiteLLMPydanticObjectBase): api_key: str | None = None @@ -2107,6 +2123,11 @@ class UpdateTeamRequest(LiteLLMPydanticObjectBase): budget_limits: list[BudgetLimitEntry] | None = None # multiple concurrent budget windows default_team_member_models: list[str] | None = None # default allowed_models seeded onto new team members + @field_validator("budget_duration", "team_member_budget_duration", mode="before") + @classmethod + def empty_budget_duration_is_unset(cls, v: object) -> object: + return _blank_duration_as_unset(v) + class PatchTeamRequest(UpdateTeamRequest): """ diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index 0b7f69bbb7f..c68789ce12d 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -1527,12 +1527,14 @@ async def new_team( value=getattr(data, field), ) - # If budget_duration is set, set `budget_reset_at` - if complete_team_data.budget_duration is not None: + usable_budget_duration: Final = _usable_budget_duration(complete_team_data.budget_duration) + if usable_budget_duration is None: + complete_team_data.budget_duration = None + else: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time complete_team_data.budget_reset_at = get_budget_reset_time( - budget_duration=complete_team_data.budget_duration, + budget_duration=usable_budget_duration, ) # If budget_limits is set, initialize reset_at for each window @@ -2442,14 +2444,24 @@ async def patch_team( raise handle_exception_on_proxy(e) +def _usable_budget_duration(duration: str | None) -> str | None: + if duration is None or duration.strip() == "": + return None + return duration + + def _set_budget_reset_at(data: UpdateTeamRequest, updated_kv: dict) -> None: """Set budget_reset_at in updated_kv if budget_duration is provided.""" - if data.budget_duration is not None: + usable_budget_duration: Final = _usable_budget_duration(data.budget_duration) + if usable_budget_duration is not None: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time - reset_at: Final = get_budget_reset_time(budget_duration=data.budget_duration) + reset_at: Final = get_budget_reset_time(budget_duration=usable_budget_duration) updated_kv["budget_reset_at"] = reset_at - elif "budget_duration" in updated_kv and updated_kv["budget_duration"] is None: + elif data.budget_duration is not None or ( + "budget_duration" in updated_kv and updated_kv["budget_duration"] is None + ): + updated_kv["budget_duration"] = None updated_kv["budget_reset_at"] = None if data.budget_limits is not None and len(data.budget_limits) > 0: diff --git a/tests/test_litellm/litellm_core_utils/test_duration_parser.py b/tests/test_litellm/litellm_core_utils/test_duration_parser.py index cb9f273a0a7..94c429530ee 100644 --- a/tests/test_litellm/litellm_core_utils/test_duration_parser.py +++ b/tests/test_litellm/litellm_core_utils/test_duration_parser.py @@ -1,9 +1,7 @@ import unittest from datetime import datetime, time, timezone -from unittest.mock import patch from zoneinfo import ZoneInfo -import litellm.litellm_core_utils.duration_parser as duration_parser from litellm.litellm_core_utils.duration_parser import ( duration_in_seconds, get_next_standardized_reset_time, @@ -376,13 +374,12 @@ class TestWordFormBudgetDurations(unittest.TestCase): self.assertEqual(duration_in_seconds("weekly"), 604800) self.assertEqual(duration_in_seconds("monthly"), 2592000) - def test_invalid_duration_logs_warning_and_falls_back(self): + def test_unparseable_duration_raises_instead_of_midnight_fallback(self): base_time = datetime(2023, 5, 15, 15, 0, 0, tzinfo=timezone.utc) - with patch.object(duration_parser.verbose_logger, "warning") as mock_warning: - result = get_next_standardized_reset_time("garbage", base_time, "UTC") - self.assertEqual(result, datetime(2023, 5, 16, 0, 0, 0, tzinfo=timezone.utc)) - mock_warning.assert_called_once() - self.assertIn("garbage", mock_warning.call_args.args) + for duration in ("", " ", "garbage", "1x"): + with self.assertRaises(ValueError) as ctx: + get_next_standardized_reset_time(duration, base_time, "UTC") + self.assertIn("Invalid budget_duration", str(ctx.exception)) if __name__ == "__main__": diff --git a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py index 0e1831614ac..f5032bc17ed 100644 --- a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py +++ b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py @@ -541,6 +541,19 @@ async def test_update_team_rejects_a_duration_that_never_advances( mock_find_unique.assert_not_awaited() +@pytest.mark.parametrize("blank", ["", " "]) +def test_set_budget_reset_at_treats_a_blank_duration_as_unset(blank): + from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at + + data = UpdateTeamRequest.model_construct(team_id="team-1", budget_duration=blank) + updated_kv = {"budget_duration": blank} + + _set_budget_reset_at(data, updated_kv) + + assert updated_kv["budget_duration"] is None + assert updated_kv["budget_reset_at"] is None + + @pytest.mark.asyncio async def test_new_team_with_object_permission(mock_db_client, mock_admin_auth): """ @@ -13172,6 +13185,35 @@ async def test_new_team_explicit_null_budget_duration_beats_configured_default( assert team_data.get("budget_reset_at") is None +@pytest.mark.asyncio +@pytest.mark.parametrize("blank", ["", " "]) +async def test_new_team_blank_budget_duration_is_lifetime_not_a_daily_reset( + mock_db_client, mock_admin_auth, monkeypatch, blank +): + """A form-posted empty budget_duration used to stamp budget_reset_at at + next midnight. It must persist as unset, the same as an explicit null. + """ + from fastapi import Request + + import litellm + from litellm.proxy._types import NewTeamRequest + from litellm.proxy.management_endpoints.team_endpoints import new_team + + monkeypatch.setattr(litellm, "default_team_settings", None) + monkeypatch.setattr(litellm, "default_team_params", {"budget_duration": "30d"}) + mock_team_create = _wire_new_team_prisma(mock_db_client) + + await new_team( + data=NewTeamRequest(team_alias="blank-duration-team", budget_duration=blank), + http_request=MagicMock(spec=Request), + user_api_key_dict=mock_admin_auth, + ) + + team_data = mock_team_create.call_args.kwargs["data"] + assert team_data.get("budget_duration") is None + assert team_data.get("budget_reset_at") is None + + @pytest.mark.asyncio async def test_new_team_omitted_budget_duration_still_takes_configured_default( mock_db_client, mock_admin_auth, monkeypatch diff --git a/tests/test_litellm/proxy/test__types.py b/tests/test_litellm/proxy/test__types.py index 4ea30c7bf87..706a226c80d 100644 --- a/tests/test_litellm/proxy/test__types.py +++ b/tests/test_litellm/proxy/test__types.py @@ -11,10 +11,12 @@ from litellm.proxy._types import ( LiteLLM_AuditLogs, LiteLLM_TeamMembership, LitellmUserRoles, + NewTeamRequest, NewUserRequest, OrganizationMemberUpdateRequest, ResetSpendRequest, UpdateKeyRequest, + UpdateTeamRequest, UpdateUserRequest, UserAPIKeyAuth, ) @@ -190,6 +192,15 @@ def test_an_empty_max_budget_from_a_form_post_reads_as_no_budget_not_as_zero(): assert GenerateKeyRequest(max_budget="").max_budget is None +@pytest.mark.parametrize("blank", ("", " ")) +def test_an_empty_budget_duration_from_a_form_post_reads_as_unset(blank): + assert GenerateKeyRequest(budget_duration=blank).budget_duration is None + assert NewTeamRequest(team_alias="my-team", budget_duration=blank).budget_duration is None + assert NewTeamRequest(team_alias="my-team", team_member_budget_duration=blank).team_member_budget_duration is None + assert UpdateTeamRequest(team_id="team-1", budget_duration=blank).budget_duration is None + assert UpdateTeamRequest(team_id="team-1", team_member_budget_duration=blank).team_member_budget_duration is None + + @pytest.mark.parametrize("sent", (0, 0.0, 25.5)) def test_a_max_budget_that_was_actually_sent_is_kept(sent): assert GenerateKeyRequest(max_budget=sent).max_budget == sent From 84fe67045a24af639646e309f8842c253ae3e5de Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 3 Sep 2026 14:00:28 +0000 Subject: [PATCH 07/13] fix(proxy): clear LIT002/LIT011 on empty budget_duration paths Replace the unit membership set with a match so the parser does not build a mutable collection. Stop writing budget_duration on updated_kv when the duration is blank Co-authored-by: Zsanz3 --- litellm/litellm_core_utils/duration_parser.py | 30 +++++++++++-------- .../management_endpoints/team_endpoints.py | 1 - .../test_team_endpoints.py | 1 - 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/litellm/litellm_core_utils/duration_parser.py b/litellm/litellm_core_utils/duration_parser.py index 414369e35c6..89786086dbf 100644 --- a/litellm/litellm_core_utils/duration_parser.py +++ b/litellm/litellm_core_utils/duration_parser.py @@ -134,24 +134,30 @@ def get_next_standardized_reset_time( current_time, _ = _setup_timezone(current_time, timezone_str) value, unit = _parse_duration(_normalize_duration(duration)) - if value is None or unit not in {"s", "m", "h", "d", "w", "mo"}: + if value is None: raise ValueError( f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." ) base_midnight: Final = current_time.replace(hour=0, minute=0, second=0, microsecond=0) - if unit == "d": - return _handle_day_reset(current_time, base_midnight, value, reset_time_of_day) - elif unit == "w": - return _handle_day_reset(current_time, base_midnight, value * 7, reset_time_of_day) - elif unit == "h": - return _handle_hour_reset(current_time, base_midnight, value) - elif unit == "m": - return _handle_minute_reset(current_time, base_midnight, value) - elif unit == "s": - return _handle_second_reset(current_time, base_midnight, value) - return _handle_month_reset(current_time, base_midnight, value, reset_time_of_day) + match unit: + case "d": + return _handle_day_reset(current_time, base_midnight, value, reset_time_of_day) + case "w": + return _handle_day_reset(current_time, base_midnight, value * 7, reset_time_of_day) + case "h": + return _handle_hour_reset(current_time, base_midnight, value) + case "m": + return _handle_minute_reset(current_time, base_midnight, value) + case "s": + return _handle_second_reset(current_time, base_midnight, value) + case "mo": + return _handle_month_reset(current_time, base_midnight, value, reset_time_of_day) + case _: + raise ValueError( + f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." + ) def _setup_timezone(current_time: datetime, timezone_str: str = "UTC") -> tuple[datetime, tzinfo]: diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index c68789ce12d..df83a9328eb 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -2461,7 +2461,6 @@ def _set_budget_reset_at(data: UpdateTeamRequest, updated_kv: dict) -> None: elif data.budget_duration is not None or ( "budget_duration" in updated_kv and updated_kv["budget_duration"] is None ): - updated_kv["budget_duration"] = None updated_kv["budget_reset_at"] = None if data.budget_limits is not None and len(data.budget_limits) > 0: diff --git a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py index f5032bc17ed..f1831d13905 100644 --- a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py +++ b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py @@ -550,7 +550,6 @@ def test_set_budget_reset_at_treats_a_blank_duration_as_unset(blank): _set_budget_reset_at(data, updated_kv) - assert updated_kv["budget_duration"] is None assert updated_kv["budget_reset_at"] is None From 15d98540993b4a586925cca371eb253157029351 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 07:37:28 +0000 Subject: [PATCH 08/13] fix(proxy): persist normalized budget_duration without mutating callers Build a persistence copy for blank/null duration instead of writing back onto complete_team_data or the update payload. Empty budget_duration still stores as unset, not a daily reset. Co-authored-by: Zsanz3 --- .../management_endpoints/team_endpoints.py | 58 +++++++++++------ .../test_team_endpoints.py | 62 +++++++++++++++---- 2 files changed, 88 insertions(+), 32 deletions(-) diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index df83a9328eb..6b22b3cb56c 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -1528,9 +1528,7 @@ async def new_team( ) usable_budget_duration: Final = _usable_budget_duration(complete_team_data.budget_duration) - if usable_budget_duration is None: - complete_team_data.budget_duration = None - else: + if usable_budget_duration is not None: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time complete_team_data.budget_reset_at = get_budget_reset_time( @@ -1554,7 +1552,11 @@ async def new_team( members_with_roles = complete_team_data.members_with_roles complete_team_data.members_with_roles = [] - complete_team_data_dict = complete_team_data.model_dump(exclude_none=True) + dumped_team_data: Final = complete_team_data.model_dump(exclude_none=True) + complete_team_data_dict = _persistence_values_for_budget_duration( + dumped_team_data, + complete_team_data.budget_duration, + ) # Serialize router_settings to JSON (matching key creation pattern) router_settings_value: Final = getattr(data, "router_settings", None) @@ -2215,7 +2217,7 @@ async def update_team( ) # Check budget_duration and budget_reset_at - _set_budget_reset_at(data, updated_kv) + updated_kv = _set_budget_reset_at(data, updated_kv) _team_member_fields_in_request: Final = { field @@ -2450,28 +2452,46 @@ def _usable_budget_duration(duration: str | None) -> str | None: return duration -def _set_budget_reset_at(data: UpdateTeamRequest, updated_kv: dict) -> None: - """Set budget_reset_at in updated_kv if budget_duration is provided.""" +def _persistence_values_for_budget_duration( + persistence_values: Mapping[str, object], + duration: str | None, +) -> dict[str, object]: + if _usable_budget_duration(duration) is not None: + return {**persistence_values} + return {key: value for key, value in persistence_values.items() if key != "budget_duration"} + + +def _budget_reset_persistence_fields( + data: UpdateTeamRequest, updated_kv: Mapping[str, object] +) -> Mapping[str, object]: usable_budget_duration: Final = _usable_budget_duration(data.budget_duration) if usable_budget_duration is not None: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time - reset_at: Final = get_budget_reset_time(budget_duration=usable_budget_duration) - updated_kv["budget_reset_at"] = reset_at - elif data.budget_duration is not None or ( + return MappingProxyType( + {"budget_reset_at": get_budget_reset_time(budget_duration=usable_budget_duration)} + ) + if data.budget_duration is not None or ( "budget_duration" in updated_kv and updated_kv["budget_duration"] is None ): - updated_kv["budget_reset_at"] = None + return MappingProxyType({"budget_duration": None, "budget_reset_at": None}) + return MappingProxyType({}) - if data.budget_limits is not None and len(data.budget_limits) > 0: - from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time - initialized_windows: Final = [] - for window in data.budget_limits: - w = window if isinstance(window, dict) else window.model_dump() - w["reset_at"] = get_budget_reset_time(budget_duration=w["budget_duration"]).isoformat() - initialized_windows.append(w) - updated_kv["budget_limits"] = json.dumps(initialized_windows) +def _set_budget_reset_at(data: UpdateTeamRequest, updated_kv: Mapping[str, object]) -> dict[str, object]: + """Return a persistence copy with budget_reset_at. Does not mutate `updated_kv`.""" + budget_fields: Final = _budget_reset_persistence_fields(data, updated_kv) + if data.budget_limits is None or len(data.budget_limits) == 0: + return {**updated_kv, **budget_fields} + + from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time + + initialized_windows: Final = [] + for window in data.budget_limits: + w = window if isinstance(window, dict) else window.model_dump() + w["reset_at"] = get_budget_reset_time(budget_duration=w["budget_duration"]).isoformat() + initialized_windows.append(w) + return {**updated_kv, **budget_fields, "budget_limits": json.dumps(initialized_windows)} async def handle_update_object_permission(data_json: dict, existing_team_row: _ObjectPermissionRow) -> dict: diff --git a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py index f1831d13905..9d4079513fc 100644 --- a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py +++ b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py @@ -548,9 +548,41 @@ def test_set_budget_reset_at_treats_a_blank_duration_as_unset(blank): data = UpdateTeamRequest.model_construct(team_id="team-1", budget_duration=blank) updated_kv = {"budget_duration": blank} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert updated_kv["budget_reset_at"] is None + assert persisted["budget_duration"] is None + assert persisted["budget_reset_at"] is None + assert updated_kv == {"budget_duration": blank} + assert data.budget_duration == blank + + +@pytest.mark.parametrize("blank", ["", " "]) +def test_create_persistence_drops_blank_budget_duration_without_mutating_input(blank): + from litellm.proxy.management_endpoints.team_endpoints import ( + _persistence_values_for_budget_duration, + ) + + dumped = {"team_alias": "blank-duration-team", "budget_duration": blank, "max_budget": 10} + + persisted = _persistence_values_for_budget_duration(dumped, blank) + + assert "budget_duration" not in persisted + assert persisted["team_alias"] == "blank-duration-team" + assert dumped == {"team_alias": "blank-duration-team", "budget_duration": blank, "max_budget": 10} + + +def test_create_persistence_keeps_a_usable_budget_duration_without_mutating_input(): + from litellm.proxy.management_endpoints.team_endpoints import ( + _persistence_values_for_budget_duration, + ) + + dumped = {"team_alias": "daily-team", "budget_duration": "1d"} + + persisted = _persistence_values_for_budget_duration(dumped, "1d") + + assert persisted["budget_duration"] == "1d" + assert persisted is not dumped + assert dumped == {"team_alias": "daily-team", "budget_duration": "1d"} @pytest.mark.asyncio @@ -10833,7 +10865,7 @@ async def test_update_team_blocks_non_admin_passthrough_routes(mock_db_client): def test_set_budget_reset_at_clears_when_budget_duration_null(): """ When budget_duration is explicitly set to null, _set_budget_reset_at - should set budget_reset_at=None in updated_kv so Prisma clears it in the DB. + should set budget_reset_at=None in the persistence copy so Prisma clears it. """ from litellm.proxy._types import UpdateTeamRequest from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at @@ -10841,16 +10873,17 @@ def test_set_budget_reset_at_clears_when_budget_duration_null(): data = UpdateTeamRequest(team_id="test-team", budget_duration=None) updated_kv = {"team_id": "test-team", "budget_duration": None} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert "budget_reset_at" in updated_kv - assert updated_kv["budget_reset_at"] is None + assert persisted["budget_reset_at"] is None + assert persisted["budget_duration"] is None + assert updated_kv == {"team_id": "test-team", "budget_duration": None} def test_set_budget_reset_at_noop_when_budget_duration_not_sent(): """ When budget_duration is NOT sent (unset), _set_budget_reset_at should - not add budget_reset_at to updated_kv. + not add budget_reset_at to the persistence copy. """ from litellm.proxy._types import UpdateTeamRequest from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at @@ -10858,15 +10891,17 @@ def test_set_budget_reset_at_noop_when_budget_duration_not_sent(): data = UpdateTeamRequest(team_id="test-team") updated_kv = {"team_id": "test-team"} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert "budget_reset_at" not in updated_kv + assert "budget_reset_at" not in persisted + assert persisted == {"team_id": "test-team"} + assert updated_kv == {"team_id": "test-team"} def test_set_budget_reset_at_sets_value_when_budget_duration_provided(): """ When budget_duration is set to a valid string, _set_budget_reset_at - should compute and set budget_reset_at. + should compute and set budget_reset_at on the persistence copy. """ from litellm.proxy._types import UpdateTeamRequest from litellm.proxy.management_endpoints.team_endpoints import _set_budget_reset_at @@ -10874,10 +10909,11 @@ def test_set_budget_reset_at_sets_value_when_budget_duration_provided(): data = UpdateTeamRequest(team_id="test-team", budget_duration="30d") updated_kv = {"team_id": "test-team", "budget_duration": "30d"} - _set_budget_reset_at(data, updated_kv) + persisted = _set_budget_reset_at(data, updated_kv) - assert "budget_reset_at" in updated_kv - assert updated_kv["budget_reset_at"] is not None + assert persisted["budget_reset_at"] is not None + assert persisted["budget_duration"] == "30d" + assert updated_kv == {"team_id": "test-team", "budget_duration": "30d"} @pytest.mark.asyncio From 00642bed28399aca3821faeecceefb7f734c317b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 10:25:44 +0000 Subject: [PATCH 09/13] style: ruff format budget_duration changes Co-authored-by: Zsanz3 --- litellm/proxy/management_endpoints/team_endpoints.py | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index 6b22b3cb56c..80426aba34a 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -2461,19 +2461,13 @@ def _persistence_values_for_budget_duration( return {key: value for key, value in persistence_values.items() if key != "budget_duration"} -def _budget_reset_persistence_fields( - data: UpdateTeamRequest, updated_kv: Mapping[str, object] -) -> Mapping[str, object]: +def _budget_reset_persistence_fields(data: UpdateTeamRequest, updated_kv: Mapping[str, object]) -> Mapping[str, object]: usable_budget_duration: Final = _usable_budget_duration(data.budget_duration) if usable_budget_duration is not None: from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time - return MappingProxyType( - {"budget_reset_at": get_budget_reset_time(budget_duration=usable_budget_duration)} - ) - if data.budget_duration is not None or ( - "budget_duration" in updated_kv and updated_kv["budget_duration"] is None - ): + return MappingProxyType({"budget_reset_at": get_budget_reset_time(budget_duration=usable_budget_duration)}) + if data.budget_duration is not None or ("budget_duration" in updated_kv and updated_kv["budget_duration"] is None): return MappingProxyType({"budget_duration": None, "budget_reset_at": None}) return MappingProxyType({}) From c110a3ae319a2e34b03ad57d0134ed3b68fc2655 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 13:50:17 +0000 Subject: [PATCH 10/13] fix(proxy): narrow team-update metadata before dict unpack _set_budget_reset_at now returns dict[str, object], so unpacking updated_kv["metadata"] was reportGeneralTypeIssues. Bind the value first so isinstance narrows it to a mapping. Co-authored-by: Zsanz3 --- litellm/proxy/management_endpoints/team_endpoints.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py index 80426aba34a..4ffe3d28292 100644 --- a/litellm/proxy/management_endpoints/team_endpoints.py +++ b/litellm/proxy/management_endpoints/team_endpoints.py @@ -2237,12 +2237,13 @@ async def update_team( *LiteLLM_ManagementEndpoint_MetadataFields_Premium, ) ) + incoming_metadata: Final = updated_kv.get("metadata") if isinstance(existing_team_row.metadata, dict): if "metadata" not in updated_kv and (_team_member_fields_in_request or _writes_metadata_backed_field): updated_kv["metadata"] = copy.deepcopy(existing_team_row.metadata) - elif isinstance(updated_kv.get("metadata"), dict): + elif isinstance(incoming_metadata, dict): updated_kv["metadata"] = { - **updated_kv["metadata"], + **incoming_metadata, **{ key: existing_team_row.metadata[key] for key in TeamMemberBudgetHandler.SYSTEM_MANAGED_METADATA_KEYS From fc739ac14ede913a1dfca87ec3fc45fd6cc563e8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 20:18:51 +0000 Subject: [PATCH 11/13] fix(proxy): quarantine unparseable budget_duration rows in the reset job Malformed durations no longer stay due after a failed parse, so they cannot fill a reset batch and starve later tenants. Co-authored-by: Zsanz3 --- .../proxy/common_utils/reset_budget_job.py | 152 ++++++++++++++---- litellm/repositories/unit_of_work.py | 28 ++++ .../test_duration_parser.py | 2 +- .../common_utils/test_reset_budget_job.py | 116 +++++++++++++ .../repositories/test_unit_of_work.py | 31 ++++ 5 files changed, 294 insertions(+), 35 deletions(-) diff --git a/litellm/proxy/common_utils/reset_budget_job.py b/litellm/proxy/common_utils/reset_budget_job.py index 35e74418628..a9f41255772 100644 --- a/litellm/proxy/common_utils/reset_budget_job.py +++ b/litellm/proxy/common_utils/reset_budget_job.py @@ -258,6 +258,7 @@ class _BudgetCascade: budgets: tuple[LiteLLM_BudgetTableFull, ...] = () budget_ids: tuple[str, ...] = () budget_resets: tuple[tuple[str, datetime], ...] = () + budget_quarantines: tuple[str, ...] = () endusers: tuple[_EndUserRow, ...] = () counter_resets: tuple[tuple[str, float], ...] = () cache_keys: tuple[str, ...] = () @@ -299,14 +300,70 @@ def _as_utc(moment: datetime) -> datetime: def _count_advanced(reset_ats: Iterable[object], cutoff: datetime) -> int: """How many rows the write actually moved past the due cutoff. - A budget_duration of "0s" (or one the parser cannot read) resolves to the - current time, so the row is written and stays due. Counting it as progress - would re-read the same chunk until the per-run cap on every tick. + A budget_duration of "0s" resolves to the current time, so the row is written + and stays due. Counting it as progress would re-read the same chunk until + the per-run cap on every tick. """ utc_cutoff: Final = _as_utc(cutoff) return sum(1 for reset_at in reset_ats if isinstance(reset_at, datetime) and _as_utc(reset_at) > utc_cutoff) +def _try_compute_budget_reset_at(duration: object, settings: BudgetResetSettings) -> datetime | None: + if not isinstance(duration, str): + return None + try: + return compute_budget_reset_at(budget_duration=duration, settings=settings) + except ValueError: + return None + + +def _is_duration_quarantine( + item: LiteLLM_TeamTable | LiteLLM_UserTable | LiteLLM_VerificationToken, +) -> bool: + return item.budget_duration is None and item.budget_reset_at is None + + +def _count_rows_leaving_due_set( + items: Iterable[LiteLLM_TeamTable | LiteLLM_UserTable | LiteLLM_VerificationToken], + cutoff: datetime, +) -> int: + return sum( + 1 + for item in items + if _is_duration_quarantine(item) + or (isinstance(item.budget_reset_at, datetime) and _as_utc(item.budget_reset_at) > _as_utc(cutoff)) + ) + + +@dataclass(frozen=True, slots=True) +class _AdvanceWindow: + budget_id: str + reset_at: datetime + + +@dataclass(frozen=True, slots=True) +class _QuarantineWindow: + budget_id: str + + +def _plan_budget_window( + budget: LiteLLM_BudgetTableFull, settings: BudgetResetSettings +) -> _AdvanceWindow | _QuarantineWindow | None: + budget_id: Final = budget.budget_id + duration: Final = budget.budget_duration + if budget_id is None or duration is None: + return None + reset_at: Final = _try_compute_budget_reset_at(duration, settings) + if reset_at is None: + verbose_proxy_logger.warning( + "Reset budget job: clearing unparseable budget_duration %r on budget %s so it leaves the due set", + duration, + budget_id, + ) + return _QuarantineWindow(budget_id) + return _AdvanceWindow(budget_id, reset_at) + + def _phase_is_drained(outcome: _ChunkOutcome) -> bool: """A short chunk means the due rows ran out. A full chunk that advanced nothing would be re-read unchanged forever, so it ends the phase too and @@ -626,9 +683,15 @@ class ResetBudgetJob: own schedule via reset_budget_for_litellm_keys(), so sweeping them here would reset them twice. """ - budget_ids: Final = tuple(b.budget_id for b in budgets_to_reset if b.budget_id is not None) + window_plans: Final = tuple(_plan_budget_window(b, self.reset_settings) for b in budgets_to_reset) + budget_resets: Final = tuple((p.budget_id, p.reset_at) for p in window_plans if isinstance(p, _AdvanceWindow)) + budget_quarantines: Final = tuple(p.budget_id for p in window_plans if isinstance(p, _QuarantineWindow)) + quarantine_ids: Final = frozenset(budget_quarantines) + budget_ids: Final = tuple( + b.budget_id for b in budgets_to_reset if b.budget_id is not None and b.budget_id not in quarantine_ids + ) if not budget_ids: - return _EMPTY_CASCADE + return _BudgetCascade(budgets=tuple(budgets_to_reset), budget_quarantines=budget_quarantines) team_memberships: Final[tuple[_TeamMembershipRow, ...]] = await self._fetch_linked_rows( table=TeamMembershipRepository(self.prisma_client).table, @@ -659,7 +722,9 @@ class ResetBudgetJob: { # mutable-ok: MappingProxyType wraps a one-shot dict comprehension b.budget_id: cap for b in budgets_to_reset - if b.budget_id is not None and (cap := _rollover_cap(b.max_budget)) is not None + if b.budget_id is not None + and b.budget_id not in quarantine_ids + and (cap := _rollover_cap(b.max_budget)) is not None } if _rollover_enabled() else {} # mutable-ok: empty sentinel immediately frozen by MappingProxyType @@ -668,14 +733,8 @@ class ResetBudgetJob: return _BudgetCascade( budgets=tuple(budgets_to_reset), budget_ids=budget_ids, - budget_resets=tuple( - ( - b.budget_id, - compute_budget_reset_at(budget_duration=b.budget_duration, settings=self.reset_settings), - ) - for b in budgets_to_reset - if b.budget_id is not None and b.budget_duration is not None - ), + budget_resets=budget_resets, + budget_quarantines=budget_quarantines, endusers=endusers, counter_resets=( *( @@ -710,7 +769,7 @@ class ResetBudgetJob: batching both means a mid-cascade failure persists nothing and the rows stay due for the next run. """ - if not cascade.budget_ids: + if not cascade.budget_ids and not cascade.budget_quarantines: return await self._with_db_write_retry( @@ -728,6 +787,8 @@ class ResetBudgetJob: _queue_enduser_resets(uow.endusers, cascade) for budget_id, budget_reset_at in cascade.budget_resets: uow.budgets.queue_window_advance(budget_id=budget_id, budget_reset_at=budget_reset_at) + for budget_id in cascade.budget_quarantines: + uow.budgets.queue_window_quarantine(budget_id=budget_id) async def _invalidate_budget_cascade_caches(self, cascade: _BudgetCascade) -> None: for counter_key, new_spend in cascade.counter_resets: @@ -762,7 +823,8 @@ class ResetBudgetJob: advanced=_count_advanced( (reset_at for _, reset_at in cascade.budget_resets), cutoff=datetime.now(timezone.utc), - ), + ) + + len(cascade.budget_quarantines), ) async def reset_budget_for_litellm_budget_table(self) -> None: @@ -863,6 +925,9 @@ class ResetBudgetJob: for k in updated_keys: if k.token is None: continue + if _is_duration_quarantine(k): + uow.keys.queue_duration_quarantine(token=k.token) + continue uow.keys.queue_spend_reset( token=k.token, budget_reset_at=k.budget_reset_at, @@ -885,6 +950,9 @@ class ResetBudgetJob: async def _write_user_reset_updates_once(self, updated_users: list[LiteLLM_UserTable]) -> None: async with spend_reset_unit_of_work(self.prisma_client.db.batch_) as uow: for u in updated_users: + if _is_duration_quarantine(u): + uow.users.queue_duration_quarantine(user_id=u.user_id) + continue uow.users.queue_spend_reset( user_id=u.user_id, budget_reset_at=u.budget_reset_at, @@ -907,6 +975,9 @@ class ResetBudgetJob: async def _write_team_reset_updates_once(self, updated_teams: list[LiteLLM_TeamTable]) -> None: async with spend_reset_unit_of_work(self.prisma_client.db.batch_) as uow: for t in updated_teams: + if _is_duration_quarantine(t): + uow.teams.queue_duration_quarantine(team_id=t.team_id) + continue uow.teams.queue_spend_reset( team_id=t.team_id, budget_reset_at=t.budget_reset_at, @@ -985,6 +1056,8 @@ class ResetBudgetJob: if updated_keys: await self._write_key_reset_updates(updated_keys=updated_keys) for k in updated_keys: + if _is_duration_quarantine(k): + continue token = getattr(k, "token", None) if token: await self._invalidate_spend_counter(f"spend:key:{token}", new_spend=k.spend or 0.0) @@ -992,10 +1065,7 @@ class ResetBudgetJob: end_time = time.time() outcome: Final = _ChunkOutcome( fetched=len(keys_to_reset) if keys_to_reset else 0, - advanced=_count_advanced( - (k.budget_reset_at for k in updated_keys), - cutoff=datetime.now(timezone.utc), - ), + advanced=_count_rows_leaving_due_set(updated_keys, cutoff=datetime.now(timezone.utc)), ) if len(failed_keys) > 0: self._emit_phase_failure( @@ -1090,6 +1160,8 @@ class ResetBudgetJob: if updated_users: await self._write_user_reset_updates(updated_users=updated_users) for u in updated_users: + if _is_duration_quarantine(u): + continue user_id = getattr(u, "user_id", None) if user_id: await self._invalidate_spend_counter(f"spend:user:{user_id}", new_spend=u.spend or 0.0) @@ -1099,10 +1171,7 @@ class ResetBudgetJob: end_time = time.time() outcome: Final = _ChunkOutcome( fetched=len(users_to_reset) if users_to_reset else 0, - advanced=_count_advanced( - (u.budget_reset_at for u in updated_users), - cutoff=datetime.now(timezone.utc), - ), + advanced=_count_rows_leaving_due_set(updated_users, cutoff=datetime.now(timezone.utc)), ) if len(failed_users) > 0: self._emit_phase_failure( @@ -1199,6 +1268,8 @@ class ResetBudgetJob: if updated_teams: await self._write_team_reset_updates(updated_teams=updated_teams) for t in updated_teams: + if _is_duration_quarantine(t): + continue team_id = getattr(t, "team_id", None) if team_id: await self._invalidate_spend_counter(f"spend:team:{team_id}", new_spend=t.spend or 0.0) @@ -1206,10 +1277,7 @@ class ResetBudgetJob: end_time = time.time() outcome: Final = _ChunkOutcome( fetched=len(teams_to_reset) if teams_to_reset else 0, - advanced=_count_advanced( - (t.budget_reset_at for t in updated_teams), - cutoff=datetime.now(timezone.utc), - ), + advanced=_count_rows_leaving_due_set(updated_teams, cutoff=datetime.now(timezone.utc)), ) if len(failed_teams) > 0: self._emit_phase_failure( @@ -1277,6 +1345,15 @@ class ResetBudgetJob: reset_at: Final = datetime.fromisoformat(reset_at_str.replace("Z", "+00:00")).replace(tzinfo=None) if reset_at > now: return False + budget_duration: Final = window.get("budget_duration") + next_reset_at: Final = _try_compute_budget_reset_at(budget_duration, reset_settings) + if next_reset_at is None or not isinstance(budget_duration, str): + verbose_proxy_logger.warning( + "Reset budget job: clearing unparseable budget_duration %r on a window so it is not retried", + budget_duration, + ) + window["reset_at"] = None + return True new_value: Final = await ResetBudgetJob._window_carried_spend(window, counter_key, spend_counter_cache) spend_counter_cache.in_memory_cache.set_cache(key=counter_key, value=new_value) if spend_counter_cache.redis_cache is not None: @@ -1284,8 +1361,6 @@ class ResetBudgetJob: await spend_counter_cache.redis_cache.async_set_cache(key=counter_key, value=new_value) except Exception as redis_err: verbose_proxy_logger.warning("Failed to reset Redis counter %s: %s", counter_key, redis_err) - budget_duration: Final = window["budget_duration"] - next_reset_at: Final = compute_budget_reset_at(budget_duration=budget_duration, settings=reset_settings) window["reset_at"] = next_reset_at.isoformat() await ResetBudgetJob._roll_window_spend_row( prisma_client=prisma_client, @@ -1462,11 +1537,20 @@ class ResetBudgetJob: still holds the pre-reset value, admitting requests past the cap. """ try: + duration: Final = item.budget_duration + if duration is not None: + reset_at: Final = _try_compute_budget_reset_at(duration, reset_settings) + if reset_at is None: + verbose_proxy_logger.warning( + "Reset budget job: clearing unparseable budget_duration %r on %s so it leaves the due set", + duration, + item_type, + ) + item.budget_duration = None + item.budget_reset_at = None + return item + item.budget_reset_at = reset_at item.spend = _carried_spend(item.spend, _rollover_cap(item.max_budget)) if _rollover_enabled() else 0.0 - if hasattr(item, "budget_duration") and item.budget_duration is not None: - item.budget_reset_at = compute_budget_reset_at( - budget_duration=item.budget_duration, settings=reset_settings - ) return item except Exception as e: verbose_proxy_logger.exception("Error resetting budget for %s: %s. Item: %s", item_type, e, item) diff --git a/litellm/repositories/unit_of_work.py b/litellm/repositories/unit_of_work.py index a497d0580db..0abf806b170 100644 --- a/litellm/repositories/unit_of_work.py +++ b/litellm/repositories/unit_of_work.py @@ -33,6 +33,13 @@ def _spend_reset_data(budget_reset_at: datetime | None, spend_decrement: float | return {"spend": spend, "budget_reset_at": budget_reset_at} # mutable-ok: prisma update payload must be a dict +def _duration_quarantine_data() -> Mapping[str, object]: + return { + "budget_duration": None, + "budget_reset_at": None, + } # mutable-ok: prisma update payload must be a dict + + @dataclass(frozen=True, slots=True) class KeySpendResetWrites: table: BatchTable @@ -45,6 +52,12 @@ class KeySpendResetWrites: data=_spend_reset_data(budget_reset_at, spend_decrement), ) + def queue_duration_quarantine(self, token: str) -> None: + self.table.update( + where={"token": token}, # mutable-ok: prisma where filter must be a dict + data=_duration_quarantine_data(), + ) + @dataclass(frozen=True, slots=True) class UserSpendResetWrites: @@ -58,6 +71,12 @@ class UserSpendResetWrites: data=_spend_reset_data(budget_reset_at, spend_decrement), ) + def queue_duration_quarantine(self, user_id: str) -> None: + self.table.update( + where={"user_id": user_id}, # mutable-ok: prisma where filter must be a dict + data=_duration_quarantine_data(), + ) + @dataclass(frozen=True, slots=True) class TeamSpendResetWrites: @@ -71,6 +90,12 @@ class TeamSpendResetWrites: data=_spend_reset_data(budget_reset_at, spend_decrement), ) + def queue_duration_quarantine(self, team_id: str) -> None: + self.table.update( + where={"team_id": team_id}, # mutable-ok: prisma where filter must be a dict + data=_duration_quarantine_data(), + ) + @dataclass(frozen=True, slots=True) class LinkedSpendResetWrites: @@ -97,6 +122,9 @@ class BudgetWindowWrites: no-op row count instead of a P2025 that aborts the whole chunk.""" self.table.update_many(where={"budget_id": budget_id}, data={"budget_reset_at": budget_reset_at}) + def queue_window_quarantine(self, budget_id: str) -> None: + self.table.update_many(where={"budget_id": budget_id}, data=_duration_quarantine_data()) + @dataclass(frozen=True, slots=True) class SpendResetUnitOfWork: diff --git a/tests/test_litellm/litellm_core_utils/test_duration_parser.py b/tests/test_litellm/litellm_core_utils/test_duration_parser.py index 94c429530ee..19ed5bc15ad 100644 --- a/tests/test_litellm/litellm_core_utils/test_duration_parser.py +++ b/tests/test_litellm/litellm_core_utils/test_duration_parser.py @@ -376,7 +376,7 @@ class TestWordFormBudgetDurations(unittest.TestCase): def test_unparseable_duration_raises_instead_of_midnight_fallback(self): base_time = datetime(2023, 5, 15, 15, 0, 0, tzinfo=timezone.utc) - for duration in ("", " ", "garbage", "1x"): + for duration in ("", " ", "garbage", "1x", "1dinvalid"): with self.assertRaises(ValueError) as ctx: get_next_standardized_reset_time(duration, base_time, "UTC") self.assertIn("Invalid budget_duration", str(ctx.exception)) diff --git a/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py b/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py index 560953f0b51..24765ca6ed2 100644 --- a/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py +++ b/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py @@ -1158,6 +1158,36 @@ def test_reset_budget_windows_handles_string_budget_limits(monkeypatch): prisma_client.db.litellm_verificationtoken.update.assert_awaited_once() +def test_reset_budget_windows_clears_unparseable_duration_and_still_resets_later_rows(monkeypatch): + """An expired window with a duration the new parser rejects must not raise + and stall the keyset walk. Clearing reset_at persists so the next tick + skips it and later keys still reset.""" + now = datetime.utcnow() + expired = (now - timedelta(minutes=5)).isoformat() + "Z" + key_rows = [ + {"token": "sk-bad", "budget_limits": [{"budget_duration": "1dinvalid", "reset_at": expired}]}, + {"token": "sk-good", "budget_limits": [{"budget_duration": "1d", "reset_at": expired}]}, + ] + job, prisma_client, spend_counter_cache = _make_reset_budget_windows_job( + monkeypatch, key_rows=key_rows, team_rows=[] + ) + + asyncio.run(job.reset_budget_windows()) + + assert prisma_client.db.litellm_verificationtoken.update.await_count == 2 + first, second = prisma_client.db.litellm_verificationtoken.update.await_args_list + assert first.kwargs["where"] == {"token": "sk-bad"} + bad_windows = json.loads(first.kwargs["data"]["budget_limits"]) + assert bad_windows[0]["reset_at"] is None + assert second.kwargs["where"] == {"token": "sk-good"} + good_windows = json.loads(second.kwargs["data"]["budget_limits"]) + new_reset_at = datetime.fromisoformat(good_windows[0]["reset_at"].replace("Z", "+00:00")).replace(tzinfo=None) + assert new_reset_at > now + spend_counter_cache.in_memory_cache.set_cache.assert_any_call(key="spend:key:sk-good:window:1d", value=0.0) + touched_keys = [call.kwargs.get("key") for call in spend_counter_cache.in_memory_cache.set_cache.call_args_list] + assert "spend:key:sk-bad:window:1dinvalid" not in touched_keys + + def test_reset_budget_windows_skips_row_with_empty_budget_limits(monkeypatch): """A row whose `budget_limits` comes back as an empty/falsy payload (shouldn't happen given the WHERE filter, but we guard anyway) must not @@ -2179,6 +2209,92 @@ def test_budget_table_reset_stops_when_the_new_window_is_not_in_the_future(monke assert len(_batch_writes(client, "budget", op="update_many")) == 2 +_QUARANTINE_DATA = {"budget_duration": None, "budget_reset_at": None} + + +@pytest.mark.parametrize( + "phase, table_name, row_factory, id_field", + [ + ("reset_budget_for_litellm_keys", "key", _key_row, "token"), + ("reset_budget_for_litellm_users", "user", _user_row, "user_id"), + ("reset_budget_for_litellm_teams", "team", _team_row, "team_id"), + ], + ids=["keys", "users", "teams"], +) +def test_reset_quarantines_unparseable_budget_duration_and_keeps_paging( + monkeypatch, phase, table_name, row_factory, id_field +): + """A due row whose duration the new parser rejects used to raise, stay due, + and refill every batch. Clearing duration and reset_at takes it out of the + due query so later tenants can reset.""" + monkeypatch.setattr(reset_budget_job_module, "RESET_BUDGET_JOB_BATCH_SIZE", 2) + client, job = _chunked_job( + { + table_name: [ + [row_factory("bad1", budget_duration="1dinvalid"), row_factory("bad2", budget_duration="garbage")], + [row_factory("good1"), row_factory("good2")], + ] + } + ) + + asyncio.run(getattr(job, phase)()) + + assert client.fetches_by_table[table_name] == 2 + writes = _batch_writes(client, table_name, op="update") + quarantined = [w for w in writes if w["data"] == _QUARANTINE_DATA] + reset = [w for w in writes if "spend" in w["data"]] + assert [w["where"][id_field] for w in quarantined] == ["bad1", "bad2"] + assert [w["where"][id_field] for w in reset] == ["good1", "good2"] + assert all("spend" not in w["data"] for w in quarantined) + + +def test_budget_table_reset_quarantines_unparseable_durations_and_keeps_paging(monkeypatch): + """The cascade used to raise while building the next window, commit nothing, + and leave the invalid tiers at the head of every later fetch.""" + monkeypatch.setattr(reset_budget_job_module, "RESET_BUDGET_JOB_BATCH_SIZE", 2) + client, job = _chunked_job( + { + "budget": [ + [_budget_row("bad1", budget_duration="1dinvalid"), _budget_row("bad2", budget_duration="garbage")], + [_budget_row("good1"), _budget_row("good2")], + ] + } + ) + + asyncio.run(job.reset_budget_for_litellm_budget_table()) + + assert client.fetches_by_table["budget"] == 2 + writes = _batch_writes(client, "budget", op="update_many") + quarantined = [w for w in writes if w["data"] == _QUARANTINE_DATA] + advanced = [w for w in writes if w["data"] != _QUARANTINE_DATA] + assert [w["where"]["budget_id"] for w in quarantined] == ["bad1", "bad2"] + assert [w["where"]["budget_id"] for w in advanced] == ["good1", "good2"] + assert all("spend" not in w["data"] for w in quarantined) + + +def test_budget_table_reset_does_not_sweep_dependents_of_an_unparseable_tier( + reset_budget_job, mock_prisma_client, monkeypatch +): + """Quarantine is not a scheduled reset: linked spend stays put.""" + _make_counter_invalidation_job(monkeypatch) + mock_prisma_client.data["budget"] = [_budget_row(budget_id="bad-tier", budget_duration="1dinvalid")] + mock_prisma_client.db.litellm_teammembership.set_find_many_results( + [type("Membership", (), {"user_id": "alice", "team_id": "team-x", "budget_id": "bad-tier", "spend": 9.0})()] + ) + + asyncio.run(reset_budget_job.reset_budget_for_litellm_budget_table()) + + assert _batch_writes(mock_prisma_client, "team_membership") == [] + assert _batch_writes(mock_prisma_client, "budget", op="update_many") == [ + { + "table": "budget", + "op": "update_many", + "where": {"budget_id": "bad-tier"}, + "data": _QUARANTINE_DATA, + } + ] + + class PoisonRow: """A row the in-memory reset cannot write, like the DataError rows in #27730.""" diff --git a/tests/test_litellm/repositories/test_unit_of_work.py b/tests/test_litellm/repositories/test_unit_of_work.py index 1a76b537e95..c346c4c054d 100644 --- a/tests/test_litellm/repositories/test_unit_of_work.py +++ b/tests/test_litellm/repositories/test_unit_of_work.py @@ -59,6 +59,37 @@ async def test_updates_across_tables_share_one_batch_and_commit_once(): ] +async def test_duration_quarantine_clears_duration_and_reset_without_touching_spend(): + batch = FakeBatch() + + async with spend_reset_unit_of_work(lambda: batch) as uow: + uow.keys.queue_duration_quarantine(token="tok-bad") + uow.users.queue_duration_quarantine(user_id="user-bad") + uow.teams.queue_duration_quarantine(team_id="team-bad") + + cleared = {"budget_duration": None, "budget_reset_at": None} + assert batch.calls == [ + ("litellm_verificationtoken", {"token": "tok-bad"}, cleared), + ("litellm_usertable", {"user_id": "user-bad"}, cleared), + ("litellm_teamtable", {"team_id": "team-bad"}, cleared), + ] + + +async def test_budget_window_quarantine_clears_duration_and_reset_without_touching_spend(): + batch = FakeBatch() + + async with budget_cascade_unit_of_work(lambda: batch) as uow: + uow.budgets.queue_window_quarantine(budget_id="budget-bad") + + assert batch.calls == [ + ( + "litellm_budgettable.update_many", + {"budget_id": "budget-bad"}, + {"budget_duration": None, "budget_reset_at": None}, + ) + ] + + async def test_raising_inside_block_skips_commit(): batch = FakeBatch() From f53b2bbb27fccc0f56e0986a590736748f0d9932 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 20:24:58 +0000 Subject: [PATCH 12/13] test(proxy): drain the last quarantine chunk so paging assertions hold Co-authored-by: Zsanz3 --- .../proxy/common_utils/test_reset_budget_job.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py b/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py index 24765ca6ed2..30b9bcc11ba 100644 --- a/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py +++ b/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py @@ -2232,7 +2232,7 @@ def test_reset_quarantines_unparseable_budget_duration_and_keeps_paging( { table_name: [ [row_factory("bad1", budget_duration="1dinvalid"), row_factory("bad2", budget_duration="garbage")], - [row_factory("good1"), row_factory("good2")], + [row_factory("good1")], ] } ) @@ -2244,7 +2244,7 @@ def test_reset_quarantines_unparseable_budget_duration_and_keeps_paging( quarantined = [w for w in writes if w["data"] == _QUARANTINE_DATA] reset = [w for w in writes if "spend" in w["data"]] assert [w["where"][id_field] for w in quarantined] == ["bad1", "bad2"] - assert [w["where"][id_field] for w in reset] == ["good1", "good2"] + assert [w["where"][id_field] for w in reset] == ["good1"] assert all("spend" not in w["data"] for w in quarantined) @@ -2256,7 +2256,7 @@ def test_budget_table_reset_quarantines_unparseable_durations_and_keeps_paging(m { "budget": [ [_budget_row("bad1", budget_duration="1dinvalid"), _budget_row("bad2", budget_duration="garbage")], - [_budget_row("good1"), _budget_row("good2")], + [_budget_row("good1")], ] } ) @@ -2268,7 +2268,7 @@ def test_budget_table_reset_quarantines_unparseable_durations_and_keeps_paging(m quarantined = [w for w in writes if w["data"] == _QUARANTINE_DATA] advanced = [w for w in writes if w["data"] != _QUARANTINE_DATA] assert [w["where"]["budget_id"] for w in quarantined] == ["bad1", "bad2"] - assert [w["where"]["budget_id"] for w in advanced] == ["good1", "good2"] + assert [w["where"]["budget_id"] for w in advanced] == ["good1"] assert all("spend" not in w["data"] for w in quarantined) From 314b581f10925f85598cb4871562d728e09a38dc Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 26 Oct 2026 13:42:25 +0000 Subject: [PATCH 13/13] fix(proxy): quarantine only unparseable duration strings Integer durations stay a per-row failure. 1hr and fortnightly now raise instead of resetting at the next midnight. Co-authored-by: Zsanz3 --- litellm/proxy/common_utils/reset_budget_job.py | 4 +++- tests/unit/litellm_core_utils/test_duration_parser.py | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/litellm/proxy/common_utils/reset_budget_job.py b/litellm/proxy/common_utils/reset_budget_job.py index 67ecc5db5d0..2c896792f6f 100644 --- a/litellm/proxy/common_utils/reset_budget_job.py +++ b/litellm/proxy/common_utils/reset_budget_job.py @@ -368,7 +368,9 @@ def _count_advanced(reset_ats: Iterable[object], cutoff: datetime) -> int: def _try_compute_budget_reset_at(duration: object, settings: BudgetResetSettings) -> datetime | None: if not isinstance(duration, str): - return None + raise ValueError( + f"Invalid budget_duration {duration!r}. Use the format (e.g. '1h', '7d', '30d', '1mo')." + ) try: return compute_budget_reset_at(budget_duration=duration, settings=settings) except ValueError: diff --git a/tests/unit/litellm_core_utils/test_duration_parser.py b/tests/unit/litellm_core_utils/test_duration_parser.py index 5773ece15a0..5576b7db6b3 100644 --- a/tests/unit/litellm_core_utils/test_duration_parser.py +++ b/tests/unit/litellm_core_utils/test_duration_parser.py @@ -339,7 +339,7 @@ class TestWordFormBudgetDurations(unittest.TestCase): def test_unparseable_duration_raises_instead_of_midnight_fallback(self): base_time = datetime(2023, 5, 15, 15, 0, 0, tzinfo=timezone.utc) - for duration in ("", " ", "garbage", "1x", "1dinvalid"): + for duration in ("", " ", "garbage", "1x", "1dinvalid", "1hr", "fortnightly"): with self.assertRaises(ValueError) as ctx: get_next_standardized_reset_time(duration, base_time, "UTC") self.assertIn("Invalid budget_duration", str(ctx.exception)) @@ -348,7 +348,7 @@ class TestWordFormBudgetDurations(unittest.TestCase): class TestGetBudgetWindowStart(unittest.TestCase): def test_window_start_is_the_previous_reset_on_the_same_schedule(self): created_at: Final = datetime(2024, 10, 1, 0, 30, tzinfo=timezone.utc) - durations: Final = "1d 24h daily 7d weekly 2w 10d 30d monthly 1mo 4h 5h 30m 45s 1hr fortnightly".split() + durations: Final = "1d 24h daily 7d weekly 2w 10d 30d monthly 1mo 4h 5h 30m 45s".split() for duration in durations: with self.subTest(duration=duration): reset_at = get_next_standardized_reset_time(duration, created_at, "UTC")