refactor: expose core private helpers under public names

[devin-ai-integration]

TLDR

Problem this solves:

• reportPrivateUsage sits at 1,804 on main, and about 600 of those hits are core code (litellm root, router, caching, integrations, enterprise) importing or calling another module's underscore helpers
• That blocks driving the private-usage budget to zero

How it solves it:

• Rename each cross-module private helper, method and attribute in the core bucket to its public name and update every in-tree caller and test patch target
• Keep the old name working as an alias (_old = new for functions, classes and methods, a forwarding property for plain instance attributes), so enterprise, proxy-extras and user code that imports the old name is unaffected. tests/unit/test_private_usage_aliases.py asserts every alias is the identical object and every property round-trips
• Third-party private members (openai _parsing, prometheus_client _name and _names_to_collectors) get exact-rule pyright: ignore[reportPrivateUsage] with a reason
• Deliberately left private: methods on user extension points (CustomGuardrail, CustomLogger subclasses, BaseCache, secret managers) where an external override of the old name would silently stop being called, every module or class level value (for example litellm._async_success_callback, litellm._custom_providers), since assigning a new value to the old name would not reach the new one, pydantic private attributes, name collisions, and 16 helpers whose untyped signatures would have raised other rule counts
• Typing the renamed helpers lowered other rules too, no rule count goes up. reportPrivateUsage 1,804 to 1,384 on the gate's basedpyright. The budget file is untouched, the ratchet lowers it after merge
• Second of four PRs, after refactor: expose public hidden_params accessors #44668 (hidden_params). llms and proxy follow

User Flow

Before: an SDK user or enterprise callback imports a helper by its underscore name

1. from litellm.utils import _get_model_cost_key or litellm._should_retry(429)
2. It works, and requests through http://localhost:4000/v1/chat/completions behave as they do today

After: the same imports work and a public name exists

1. from litellm.utils import _get_model_cost_key still works and is the same function as get_model_cost_key
2. Requests through the proxy return the same responses, headers, cost and fallback behavior

Pre-Submission checklist

• I have added meaningful tests
• The handful of test files covering my change pass locally
• My PR passes all required CI/CD checks
• 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

Caveats

Screenshots / Proof of Fix

Live before and after video goes in the Slack thread https://berriaillm.slack.com/archives/C0B302ZJU05/p1791232426675779

Link to Devin session: https://app.devin.ai/sessions/32b275f5ec964f1f82cf6192e19a6237
Open in Devin Desktop: https://app.devin.ai/desktop/session/32b275f5ec964f1f82cf6192e19a6237?variant=devin
Requested by: @mateo-berri

---

Note

Medium Risk
Large, cross-cutting rename with alias preservation—low logic change—but it touches caching, batch cost attribution, and logging/redaction paths where a missed caller or alias could cause subtle breakage.

Overview
This PR promotes cross-module underscore helpers to public names across LiteLLM core and enterprise (logging, lazy imports, caching, batch/file utilities, cost calculator, integrations, enterprise proxy hooks) and updates in-tree callers to use the new names.

Backward compatibility is preserved by assigning each old symbol to the new one (_turn_on_debug = turn_on_debug, _PROXY_LiteLLMManagedFiles = PROXY_LiteLLMManagedFiles, lazy-import registry entries that map both _should_retry and should_retry, etc.), so existing from litellm... import _foo patterns keep working.

Alongside the renames, the diff adds typing tightening in touched paths—TypedDict/Protocol for file and Prisma helpers, cast/Final, and stricter callback Callable[..., object] types—without changing the described runtime behavior of proxy, caching, or batch cost tracking.

Enterprise-facing renames include managed files/vector store hook classes (dropping the leading underscore on the primary class name), should_block_robots, and call sites switched from private logging/tag helpers (e.g. get_request_tags, get_vector_stores_from_db).

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

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[greptile-apps]

Confidence Score: 5/5

[High risk] Renames private helper functions to public names across the codebase.

The PR appears safe to merge on the reviewed changes; no outstanding finding remains.

Summary

The PR exposes core private helpers under public names, updates in-tree callers, and retains aliases or forwarding properties for the old names.

• Adds alias-identity and property round-trip tests.
• Leaves module-level provider lists under their original private names.

_{Reviews (10) · Last reviewed commit: "Merge remote-tracking branch 'origin/mai..."}

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_private_usage_core (9ba5e40) with main (a193c67)¹}

Footnotes

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

[codecov]

Codecov Report

❌ Patch coverage is 89.34837% with 170 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/responses/main.py	37.93%	18 Missing ⚠️
litellm/utils.py	91.55%	13 Missing ⚠️
...llm/litellm_core_utils/prompt_templates/factory.py	80.35%	11 Missing ⚠️
litellm/passthrough/main.py	0.00%	9 Missing ⚠️
litellm/integrations/focus/export_engine.py	84.31%	8 Missing ⚠️
litellm/responses/mcp/chat_completions_handler.py	0.00%	8 Missing ⚠️
litellm/litellm_core_utils/litellm_logging.py	93.57%	7 Missing ⚠️
litellm/proxy/proxy_server.py	62.50%	6 Missing ⚠️
litellm/responses/utils.py	86.36%	6 Missing ⚠️
..._enterprise/proxy/common_utils/check_batch_cost.py	80.00%	5 Missing ⚠️
... and 52 more

📢 Thoughts on this report? Let us know!

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai Please review the latest pushed changes at 10003e3 and report any actionable concerns on the PR

[mateo-berri]

bugbot run Please review the latest pushed changes at 10003e3 and report any new issues on the PR

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[mateo-berri]

@greptileai the run picker and heuristic fallback findings come from main's dashboard commits merged in. This PR's diff against its merge base touches no ui/ files

[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 9ba5e40. Configure here.}

[mateo-berri]

LGTM