chore(typing): clear 1.4k basedpyright Any errors across 21 hotspot files

[mateo-berri]

TLDR

Problem this solves:

• Backend Any counts keep drifting toward their basedpyright ceilings
• 21 hotspot files carried 2,479 reportAny/reportExplicitAny errors, concentrated in the management endpoints, guardrails, streaming internals, and MCP surfaces

How it solves it:

• Real types at each Any source; zero casts, ignores, or suppressions
• Typed Prisma seams, TypedDicts, and precise parameter and return annotations replace Any-typed dicts and untyped kwargs plumbing
• Ratchets budgets down: basedpyright -1,663, ruff-strict -86, type-discipline -110

User Flow

Before: on litellm_internal_staging, admins manage keys, teams, models, and guardrails while developers stream completions and call the responses, messages, and MCP surfaces

1. An admin creates a key with POST /key/generate, a team with POST /team/new, updates a model with POST /model/update, and lists guardrails with GET /guardrails/list, getting the usual JSON responses
2. A developer streams a chat completion through POST /v1/chat/completions with stream: true and receives assembled chunks plus the final usage block
3. A client calls POST /v1/responses, an Anthropic-shape POST /v1/messages, or an MCP tool over /mcp, and an admin signs in through /sso/key/generate

After: on this branch, every step behaves identically because the diff only changes type annotations and typed seams, no runtime code path

1. The same requests hit the same routes and return the same payloads, byte for byte

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

Whole-tree basedpyright before and after this branch, measured with the same command the CI gate runs (uv run basedpyright --outputjson | python scripts/type_check_gate.py), counting severity=error diagnostics in-tree:

rule                 before   after   delta
reportAny            18,563  17,452  -1,111
reportExplicitAny     6,185   5,889    -296
all rules combined  148,648 146,984  -1,664

No basedpyright rule increased repo-wide and no file regressed on any rule versus its baseline count. make lint-budget-update output confirming the fixes are real and the ceilings now hold them:

Ratcheted strict-rule limits down by 86 violations this branch fixed
Ratcheted LIT-rule limits down by 110 violations this branch fixed
Ratcheted basedpyright limits down by 1663 errors this branch fixed across 48 rules

make pre-commit is green on the staged diff

Type

🧹 Refactoring

Changes

Typing-only changes across the 21 files with the highest reportAny/reportExplicitAny density among self-contained modules: the key, team, model, SSO, and proxy-settings management endpoints, the guardrail endpoints plus the unified and Cisco AI Defense guardrail hooks, the streaming internals (chunk builder, responses streaming iterator, realtime streaming), the responses-to-completion and pydantic_ai transformations, Azure assistants, the Anthropic adapters handler, websearch interception, litellm_skills, the MCP server and its REST endpoints, enterprise managed files, and vector store management. No runtime behavior changes: annotations, TYPE_CHECKING imports, TypedDicts, and typed helper seams that pay the Any-to-typed crossing once per boundary

Forbidden constructs were not used anywhere in the diff: no cast(), no # type: ignore, no # noqa, no suppression comments, no new Any annotations. Diagnostics that could not be fixed without one of those were left in place rather than hidden, which is why roughly 1,070 target errors remain in the touched files, mostly the irreducible one-flag-per-seam residue where upstream sources like PrismaWrapper.__getattr__ still return Any

Budget files are ratcheted by make lint-budget-update so the cleared headroom cannot silently grow back. The existing mapped suites for every touched module pass (about 4,800 tests, 0 failures caused by this diff; the only local reds fail identically on pristine litellm_internal_staging: one SSO test needing an unset GOOGLE_CLIENT_ID, the semantic tool filter file needing the optional semantic_router package, and two order-dependent MCP env var tests that only fail in a full-directory run)

QA runbook

1. make pre-commit green on this branch
2. git diff litellm_internal_staging --stat shows only typing edits plus the three budget JSONs, and no test changes
3. Boot the proxy (python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml) and confirm clean startup, then exercise a touched surface end to end, e.g. curl http://localhost:4000/guardrails/list -H "Authorization: Bearer sk-1234" and a streamed curl http://localhost:4000/v1/chat/completions -H "Authorization: Bearer sk-1234" -d '{"model": "gpt-5.2", "stream": true, "messages": [{"role": "user", "content": "hi"}]}'; responses are identical to litellm_internal_staging because no runtime code path changed

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
Changes are annotations and typed seams only; no intentional runtime behavior changes, though reviewers should watch for accidental logic edits mixed with formatting in large files like managed files and MCP server.

Overview
This PR is typing-only: it lowers basedpyright error ceilings in basedpyright-code-budget.json (notably reportAny / reportExplicitAny) and replaces loose Any / untyped dict plumbing with Protocols, TypedDicts, and narrower Mapping / Sequence annotations across several high-traffic modules.

Enterprise managed files routes Prisma access through _managed_file_table / _managed_object_table and _ManagedFileTableActions / _ManagedObjectTableActions protocols so DB calls are typed at the boundary instead of flowing as Any.

Streaming and adapters gain structured types in streaming_chunk_builder_utils (chunk/usage TypedDicts, Logging in TYPE_CHECKING), realtime_streaming (client WebSocket protocol, guardrail hook typing), Pydantic AI transformation (TypeAdapter validation + dump protocols), Anthropic messages adapter handler (message/system type aliases, clearer proxy metadata tuple), websearch interception (AgenticLoopParams, tool sequences), and Azure assistants (OpenAIMessage.model_validate / typed run-stream kwargs).

MCP proxy surfaces tighten tool-call/logging signatures (CallToolResult, dict[str, object]), add transport/registry protocols for stateful sessions, and type ASGI header sequences more precisely.

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

[greptile-apps]

Greptile Summary

This PR replaces broad Any usage with protocols, TypedDicts, narrower annotations, and validated boundary types across management, streaming, guardrail, MCP, provider, and managed-resource code. It also lowers the repository’s static-analysis budgets to retain the resulting improvements

• Adds typed Prisma and repository interfaces around management and managed-resource operations
• Tightens streaming, Responses API, A2A, Anthropic, Azure, guardrail, MCP, and SSO boundaries
• Ratchets basedpyright, Ruff strict, and type-discipline budgets downward

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code failure identified

The reviewed changes preserve current request, persistence, authorization, and streaming behavior while narrowing static types and validating previously untyped boundaries

Important Files Changed

Filename	Overview
litellm/a2a_protocol/providers/pydantic_ai_agents/transformation.py	Adds structural protocols and Pydantic boundary validation while preserving the plain-dictionary request and response shapes used by current callers
litellm/responses/litellm_completion_transformation/transformation.py	Tightens tool-call, image, and response transformation types without an established behavioral regression
litellm/litellm_core_utils/streaming_chunk_builder_utils.py	Replaces broad streaming usage and delta types with precise wrappers and TypedDicts while preserving assembly logic
litellm/proxy/management_endpoints/model_management_endpoints.py	Refactors model persistence typing; existing model parameters and metadata remain merged and serialized as before
litellm/proxy/management_endpoints/ui_sso.py	Adds typed SSO and repository seams without changing session, redirect, or authentication behavior
litellm/proxy/_experimental/mcp_server/server.py	Introduces typed MCP session and server-state accessors that preserve existing runtime operations
litellm/proxy/guardrails/guardrail_endpoints.py	Narrows guardrail endpoint and logging types through identity helpers and protocols without changing CRUD behavior
enterprise/litellm_enterprise/proxy/hooks/managed_files.py	Adds typed Prisma table protocols and narrower managed-file interfaces while retaining the same database calls and access checks
basedpyright-code-budget.json	Lowers static-analysis ceilings to match the reduced diagnostic counts

_{Reviews (1): Last reviewed commit: "chore(typing): clear 1.4k basedpyright A..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 81.62084% with 127 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...col/providers/pydantic_ai_agents/transformation.py	0.00%	59 Missing ⚠️
...itellm_completion_transformation/transformation.py	77.41%	14 Missing ⚠️
litellm/llms/azure/assistants.py	45.45%	12 Missing ⚠️
litellm/proxy/hooks/litellm_skills/main.py	47.05%	9 Missing ⚠️
...y/management_endpoints/key_management_endpoints.py	75.00%	8 Missing ⚠️
...tellm/proxy/management_endpoints/team_endpoints.py	91.25%	7 Missing ⚠️
litellm/proxy/management_endpoints/ui_sso.py	90.00%	5 Missing ⚠️
litellm/responses/streaming_iterator.py	70.58%	5 Missing ⚠️
...opic/experimental_pass_through/adapters/handler.py	85.71%	2 Missing ⚠️
...proxy/ui_crud_endpoints/proxy_setting_endpoints.py	94.87%	2 Missing ⚠️
... and 4 more

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_decrease_anys_fable3 (20eb7bb) with litellm_internal_staging (c28cbb8)¹}

Footnotes

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

[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 20eb7bb. Configure here.}