chore(lint): remove litellm/types from the ruff lint exclusion

[mateo-berri]

TLDR

Problem this solves:

• ruff.toml has excluded litellm/types/* from linting since 2024
• new types code silently skipped pyupgrade, F401, and every other rule
• typed-dict params kept landing with legacy Optional[X]/Dict[X] spellings
• several rules also sat above their lint budgets, forcing slow gate runs

How it solves it:

• removes the litellm/types/* entry from lint.exclude in ruff.toml
• auto-fixes the mechanical violations, hand-fixes the pyupgrade residue
• modernizes star-import consumers that leaked typing names from types hubs
• teaches runtime Union introspection about types.UnionType, with tests
• clears every rule sitting above its lint budget, then ratchets ceilings down

Relevant issues

Linear ticket

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

This is a lint-config and mechanical-modernization change, so the proof is that the linters which previously skipped litellm/types now scan it clean, all three budget gates pass with every rule at or under its limit, and runtime imports are intact. All output below captured at 6c76f5f

$ ruff check litellm --config ruff.toml
All checks passed!

$ python scripts/ruff_strict_gate.py --base origin/litellm_internal_staging
OK: every strict rule is within its codebase ceiling (base origin/litellm_internal_staging)

$ python scripts/type_discipline_gate.py --base origin/litellm_internal_staging
OK: every LIT rule is within its codebase ceiling (base origin/litellm_internal_staging)

$ python scripts/type_check_gate.py --base origin/litellm_internal_staging
OK: every rule is within its basedpyright limit (149351 errors total)

$ pytest tests/test_litellm/types tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py tests/test_litellm/llms/volcengine -q
230 passed, 1 skipped

$ pytest tests/test_litellm/litellm_core_utils/test_streaming_handler.py tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py tests/test_litellm/proxy/batches_endpoints/test_endpoints.py -q
572 passed, 2 xfailed

$ pytest tests/test_litellm/proxy/management_endpoints/test_internal_user_endpoints.py -q
92 passed

$ pytest tests/test_litellm/proxy/guardrails/guardrail_hooks/test_xecguard.py tests/test_litellm/integrations/test_prometheus_labels.py tests/test_litellm/integrations/test_prometheus_user_team_metrics.py -q
191 passed

The broader unit sweep over bedrock chat, openai, custom_httpx, caching, and guardrails (4098 passed, 1 skipped, 1 xfailed, captured at d59135b) is exercised by CI at this head rather than re-run locally

An importlib walk over every litellm submodule (pkgutil.walk_packages plus import_module) reports a single environment-only failure, the optional mangum dependency, confirming no re-export or star-import leak broke at runtime

Type

🧹 Refactoring

Changes

ruff.toml carried litellm/types/* in lint.exclude, so none of the lint rules, regular or strict, ever ran on the types tree. That is how typed-dict params could land with pre-PEP-604 spellings unchecked. This PR removes the exclusion and brings the tree up to standard

The bulk of the diff is ruff --fix plus ruff format over litellm/types: PEP 604 unions and builtin generics (UP006/UP007/UP035/UP045), import hygiene, and formatting. On top of that, hand fixes cover what autofix cannot: module-level implicit type aliases (X = Union[...]) converted to | chains, RootModel[Union[...]] bases in interactions/generated.py, a stray print in types/utils.py replaced with verbose_logger.debug, and duplicate imports in types/llms/openai.py. One B006 autofix in types/guardrails.py rewrote a mutable = {} default to = None without widening the parameter, so the annotation is corrected to dict[str, dict] | None

Preview-mode F401 deletes import X as X re-exports, which are load-bearing API surface in the types tree. Consumed re-exports in types/utils.py are restored verbatim, and the six star-imported hub modules (caching, slack_alerting, custom_http, llms/openai, scim_v2, responses/main) get F401 per-file-ignores since their imports are deliberate re-export surface

Several non-types files star-import those hubs and silently relied on typing names (Union, List, Dict, Tuple) leaking through them; ruff cannot flag those usages because the star import hides them. The affected consumers (bedrock invoke_handler, llms/openai/openai.py, assistants, fine_tuning, guardrail_helpers, openai responses transformation) are modernized to builtin generics and | unions so the leak is gone

Two spots introspect annotations at runtime and only recognized typing.Union, so PEP 604 unions fell through: the guardrail UI field-schema generator started reporting number fields as strings, and the volcengine response fill stopped unwrapping optional nested models. Both now handle types.UnionType the same way proxy_server.py already does, and both have regression tests that fail without the fix

ruff-strict-budget.json limits for the eleven rules the types tree now trips (ANN001/002/003/206/401, BLE001, C901, PLC0414, PLW0127, RUF012, TID251) are raised to the exact measured totals with no slack, so any net-new violation still fails the gate. The pyupgrade rules stay at 0. The dashboard schema.d.ts regeneration is the deterministic output of gen:api at this head

The final commit clears the lint drift that sat above budget limits across the wider package, since the gates measure all of litellm and any rule over its limit forces the slow base-comparison path. FURB188, RUF022, SIM118, UP007, UP032, and UP037 drop to zero via PEP 604 rewrites of runtime type aliases and sorted __all__ blocks, while LIT001 and LIT006 come back under their ceilings through two MappingProxyType constants and three removed casts. Consumers that leaked Union through from litellm.proxy._types import * move to | spellings so the leaked import could go, and make lint-budget-update then ratchets the ruff-strict, type-discipline, and basedpyright budgets down to the new totals

One caveat: litellm/types/interactions/generated.py is code-generated; its generator should be updated to emit the modern spellings or its next regeneration will reintroduce violations

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

---

Note

Low Risk
Refactoring-only typing and style changes with small behavioral fixes for UnionType introspection; no auth, billing, or core request-path logic redesign.

Overview
Brings the wider litellm package in line with PEP 604 and builtin generics after litellm/types is no longer excluded from ruff: Union/Optional/List/Dict/Tuple become | unions and list/dict/tuple across caching, integrations, proxy, router, and LLM provider code.

Runtime annotation introspection now treats types.UnionType (PEP 604 unions) like typing.Union in the guardrail UI field-type helper and Volcengine responses fill logic, so optional/nested model handling does not break when annotations use X | Y.

Mechanical cleanups include iterating mappings without .keys(), alphabetized __all__ exports, str.removeprefix for NLP Cloud streaming chunk trimming, and tightened ruff-strict / basedpyright budget ceilings in basedpyright-code-budget.json to match the new totals.

^{Reviewed by Cursor Bugbot for commit 6c76f5f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 99.28367% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/fine_tuning_endpoints/endpoints.py	0.00%	3 Missing ⚠️
litellm/router.py	75.00%	3 Missing ⚠️
...tellm/llms/bedrock/vector_stores/transformation.py	0.00%	2 Missing ⚠️
litellm/llms/openai/openai.py	50.00%	2 Missing ⚠️
litellm/proxy/hooks/litellm_skills/main.py	0.00%	2 Missing ⚠️
litellm/types/services.py	75.00%	2 Missing ⚠️
litellm/assistants/utils.py	50.00%	1 Missing ⚠️
litellm/integrations/langtrace.py	0.00%	1 Missing ⚠️
litellm/litellm_core_utils/litellm_logging.py	66.66%	1 Missing ⚠️
litellm/litellm_core_utils/streaming_handler.py	66.66%	1 Missing ⚠️
... and 7 more

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_remove_types_ruff_exclusion (6c76f5f) with litellm_internal_staging (2792887)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (6c76f5f) during the generation of this report, so 2792887 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[mateo-berri]

@greptile-apps please review despite the file count, the diff is almost entirely mechanical ruff autofix and format over litellm/types

[greptile-apps]

Greptile Summary

This PR enables Ruff linting for litellm/types and modernizes annotations, imports, exports, and lint budgets while preserving runtime annotation handling.

• Converts legacy typing syntax to PEP 604 unions and builtin generics.
• Preserves deliberate type-hub re-exports and updates consumers that relied on leaked typing names.
• Extends runtime union introspection for guardrail schemas and Volcengine response models.
• Ratchets Ruff, type-discipline, and basedpyright budgets to the resulting totals.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains in the eligible follow-up review scope.

Important Files Changed

Filename	Overview
ruff.toml	Removes the types-tree exclusion so Ruff rules now cover litellm/types.
litellm/proxy/guardrails/guardrail_endpoints.py	Extends annotation inspection to recognize PEP 604 unions while retaining legacy typing.Union handling.
litellm/llms/volcengine/responses/transformation.py	Updates default-value and nested-model selection logic to unwrap both forms of union annotations.
litellm/types/guardrails.py	Modernizes guardrail type annotations and corrects the nullable annotation for a default changed to None.
tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py	Adds coverage for field-schema generation from modern union annotations.
tests/test_litellm/llms/volcengine/responses/test_volcengine_responses_transformation.py	Adds regression coverage for filling nested response models declared with PEP 604 optionals.
ruff-strict-budget.json	Updates strict-rule ceilings to account for newly linted type modules while retaining measured limits.
basedpyright-code-budget.json	Ratchets several type-checking error ceilings downward to the new measured totals.

_{Reviews (2): Last reviewed commit: "chore(lint): clear grandfathered over-li..." | Re-trigger Greptile}

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 66373eb. Configure here.}

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 6c76f5f. Configure here.}