fix(typing): bring reportReturnType back under the basedpyright budget

[mateo-berri]

Relevant issues

The LiteLLM Linting check is red on every PR currently branched off litellm_internal_staging (for example #30446), failing the basedpyright budget gate:

FAIL: basedpyright errors exceed the per-rule ceiling:
  reportReturnType: 143 errors over cap 139

This is a staging-level regression, not a problem with any individual PR: the gate (scripts/type_check_gate.py) counts absolute codebase-wide errors against the committed ceiling, so a branch off the current staging tip inherits the red regardless of what it changes.

Root cause

The budget was last ratcheted at 1bd603d1 to baseline 126 (cap 126 + slack 13 = 139). Blaming each of the 143 current reportReturnType offenders, exactly four were introduced after that ratchet, all by #30813 ("refactor(completion): extract provider dispatch into typed helpers"):

• litellm/main.py MCP dispatch path (acompletion_with_mcp)
• the fallbacks path (completion_with_fallbacks)
• the batch path (batch_completion_models)
• the responses-bridge path (responses_api_bridge.completion)

That refactor made basedpyright able to analyze completion() for the first time and correctly added pyright: ignore[reportReturnType] to the 61 extracted helpers, but it missed these four returns that live in completion()'s own body. They take the codebase total from 139 to 143, four over the ceiling.

Fix

Suppress exactly those four sites with coded, reasoned pyright ignores. Each path returns a coroutine (MCP, responses bridge), a list (batch), or the untyped fallback runner's result, none of which match completion()'s declared Union[ModelResponse, CustomStreamWrapper]; the async/batch callers handle those shapes. Widening completion()'s return type would ripple across thousands of call sites and is out of scope. Note the repo sets enableTypeIgnoreComments=false, so the pre-existing type: ignore[return-value] on the MCP path was dead and is replaced with a working pyright: ignore.

After the fix the codebase total is back to 139, exactly at the ceiling, and the gate passes.

Type

🐛 Bug Fix

Changes

Adds four pyright: ignore[reportReturnType] suppressions, each with a reason, to the async/batch dispatch returns in completion(); no behavior change.

---

Generated by Claude Code

[mateo-berri]

Closing in favor of #31103, which carries the same commit on a litellm_-prefixed branch to follow the branch naming convention.

---

Generated by Claude Code

[mateo-berri]

Folding this into #30446 instead of shipping it as a standalone PR, since that branch is the one currently blocked by the red lint gate and the fix is a single commit that belongs alongside it. The same commit (the four pyright: ignore[reportReturnType] suppressions that bring the codebase total back to 139) is now on litellm_fix_vertex_realtime_query_params. Closing this one

---

Generated by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/main.py	50.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!