feat(lint): enforce Final on locals and freeze function parameters (LIT010, LIT011)

[mateo-berri]

TLDR

Problem this solves:

• Nothing stops silent rebinding of locals, globals, or parameters
• Mutation of function arguments is invisible to reviewers
• Never-rebound names carry no Final, so typecheckers cannot help

How it solves it:

• New LIT010: every assignment must be declared Final
• New LIT011: parameters cannot be rebound or mutated in place
• Unpacking and walrus targets are implicitly final; rebinding them trips
• # rebind-ok: <reason> bypasses either rule with an explanation
• Sweep annotated ~31k never-rebound names with Final
• Remaining rebinders grandfathered at 1.5x, the hard CI ceiling
• basedpyright's Final-reassignment bucket ratcheted to the live count, so rebinding a declared Final reddens CI

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

All runs below were captured at 258d154

The new rules firing on a demo file:

$ cat /tmp/lit_demo.py
from typing import Final

LIMIT: Final = 10
retries = 3

def send(payload: dict, attempts: int) -> None:
    attempts += 1
    payload["sent"] = True

a, b = (1, 2)
a, b = (b, a)

$ python scripts/check_type_discipline.py /tmp/lit_demo.py
/tmp/lit_demo.py:4: LIT010 `retries` is assigned without a Final declaration, leaving it open to rebinding: annotate `retries: Final = ...` (or `Final[T]`, or a bare `retries: Final[T]` declaration with a single deferred assignment); implicit type aliases must use `retries: TypeAlias = ...` instead, since a Final alias no longer resolves in type expressions; if rebinding is the point, suppress with `# rebind-ok: <reason>`
/tmp/lit_demo.py:6: LIT001 mutable `dict` in parameter `payload` of `send`: a mutable collection can be grown or rewritten by whoever holds it. Annotate a read-only view -- Mapping[...], Sequence[...], AbstractSet[...], tuple[X, ...], frozenset[X], or a frozen dataclass / NamedTuple / ReadOnly TypedDict -- and build it functionally, not by append-in-a-loop (suppress: `# mutable-ok: <reason>`)
/tmp/lit_demo.py:7: LIT011 parameter `attempts` of `send` is re-bound: the name silently detaches from what the caller passed; bind a new name instead (suppress: `# rebind-ok: <reason>`)
/tmp/lit_demo.py:8: LIT011 parameter `payload` of `send` is mutated in place: the caller's object is rewritten at a distance; build and return a new value instead (suppress: `# rebind-ok: <reason>`)
/tmp/lit_demo.py:11: LIT010 `a` is re-bound here after an earlier binding: unpacking and walrus targets cannot carry Final, so their names are implicitly final; bind a fresh name instead, or suppress with `# rebind-ok: <reason>`
/tmp/lit_demo.py:11: LIT010 `b` is re-bound here after an earlier binding: unpacking and walrus targets cannot carry Final, so their names are implicitly final; bind a fresh name instead, or suppress with `# rebind-ok: <reason>`

6 violation(s).

The whole-tree gate at head, with the base comparison exonerating pre-existing drift:

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

basedpyright and the strict ruff gate on the full tree after the sweep:

$ make lint-basedpyright
OK: every rule is within its basedpyright limit or no higher than base (149705 errors total)

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

A net-new rebind of a declared Final reddening the basedpyright gate, proving the zeroed headroom bites (the demo file was deleted right after):

$ printf 'from typing import Final\n\nx: Final = 1\nx = 2\n' > litellm/_lit_demo_rebind.py
$ uv run basedpyright --outputjson | python scripts/type_check_gate.py --base origin/litellm_internal_staging
FAIL: basedpyright errors exceed the per-rule limit:
  reportGeneralTypeIssues: total 158 over limit 157 (this change added 1)
Reduce the new errors or remove an equal number elsewhere; the ceiling is the limit in basedpyright-code-budget.json.
BREACHED RULES: reportGeneralTypeIssues 158/157 (+1)

A live proxy booted from this branch serving a real completion, proving the ~1,590-file annotation sweep changes nothing at runtime:

$ python litellm/proxy/proxy_cli.py --config proof_config.yaml --port 47613
$ curl -s http://localhost:47613/v1/chat/completions \
    -H "Authorization: Bearer sk-lit010-proof" -H "Content-Type: application/json" \
    -d '{"model": "gpt-5.6", "messages": [{"role": "user", "content": "Reply with exactly: final means final"}]}'
{
  "id": "chatcmpl-E9GRDoLotX38ICJYhGlnozJ996ZAn",
  "created": 1785876847,
  "model": "gpt-5.6",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "final means final",
        "role": "assistant",
        "provider_specific_fields": {
          "refusal": null
        },
        "annotations": []
      },
      "provider_specific_fields": {}
    }
  ],
  "usage": {
    "completion_tokens": 6,
    "prompt_tokens": 13,
    "total_tokens": 19,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cached_tokens": 0,
      "cache_write_tokens": 0,
      "cache_creation_tokens": 0
    }
  },
  "service_tier": "default"
}

Type

🆕 New Feature
🚄 Infrastructure

Changes

scripts/check_type_discipline.py gains two rules. LIT010 flags any assignment, annotated assignment, or augmented assignment whose target is not declared Final (or TypeAlias). Unpacking and walrus targets cannot carry Final by Python's grammar, so they are treated as implicitly final: their first binding is exempt and any later rebinding of the same name is flagged. global and nonlocal statements count as the first binding of a name, so assigning after them is a rebind. Loop bodies are exempt because basedpyright forbids Final inside loops, class bodies are left to their own conventions, valueless declarations like x: int bind nothing, and _ plus dunder names are exempt. # rebind-ok: <reason> on the line suppresses the rule

LIT011 flags rebinding a function parameter through any binding form (assignment, augmented assignment, unpacking, walrus, for and with targets, del, and rebinding an enclosing function's parameter through nonlocal) and in-place mutation of a parameter (attribute or subscript stores, del on them, and for or with targets rooted at the parameter). self and cls are exempt from the mutation half only, so self.x = v stays legal but self = other does not. Lambda parameters are covered, and a nested function's decorators, defaults, and annotations are attributed to the enclosing scope, so def inner(q=(p := 2)) correctly flags a rebind of the enclosing p. The same # rebind-ok: <reason> comment bypasses it

A codemod annotated every never-rebound module-level and function-local name with Final, about 31k insertions across about 1,590 files. Three families were deliberately left plain. First, litellm's documented mutable config surface (litellm.success_callback, litellm.api_key, litellm.drop_params, and friends): litellm ships py.typed, so Final there would make downstream mypy reject the documented litellm.x = ... idiom, and LIT010 accordingly exempts the module scope of litellm/__init__.py outright rather than demanding a suppression comment on every config name. Second, names that star imports or duplicate function-local imports rebind (verbose_logger, uuid, the handler singletons in main.py, and friends), which basedpyright reports as reassigning a Final. Third, residual X: Final = Union[...]-style aliases, which mypy refuses to treat as types

type-discipline-budget.json seeds LIT010 at 25327 and LIT011 at 8406, floor(1.5x) of the post-sweep counts (16885 and 5604). The gate fails only when a rule is both over its limit and above the merge-base count, so the headroom is the line CI cannot cross. --update (run by make lint-budget-update) now leaves rules that are absent from the merge-base budget untouched: the base tree predates a seeded rule, so ratcheting against it would misread the whole grandfathered count as fixed and collapse the deliberate headroom to zero

basedpyright-code-budget.json drops reportGeneralTypeIssues from 227 to 157, the live count. Rebinding a name that is declared Final is deliberately not an LIT (LIT010 skips declared names so a bare x: Final[int] can take its single deferred assignment), which makes basedpyright the only gate between a declared Final and a silent rebind; the old ceiling carried 70 errors of headroom, enough for that many rebinds to merge without reddening anything. Unlike reportAny, nothing in this bucket is forced by untyped upstream code (each error is discrete and individually suppressible with a justified # pyright: ignore[reportGeneralTypeIssues]), so it gets zero headroom

One known diagnostics gap: the gate's blame listing attributes new violations by changed line, so a rebind whose second binding sits on an untouched line can be blamed on the line that introduced the first binding. The count itself is exact; only the pointer in the failure listing can be one site off

CLAUDE.md now states the convention for agents and humans alike: annotate bindings with Final, treat unpacking and walrus targets as implicitly final, never rebind or mutate parameters, and justify any exception in its # rebind-ok reason

A possible follow-up rule (not in this PR) is banning runtime monkeypatching, i.e. attribute stores on imported modules and classes; that needs its own inventory and PR

Tests live in tests/test_litellm/test_check_type_discipline.py and tests/test_litellm/test_type_discipline_gate.py: every binding form, exemption, and suppression path of both rules is pinned, including the implicit-final rebind detection, nonlocal owner attribution, lambda and defaults scoping, the seeded-rule passthrough in the ratchet, and a budget-integrity check that derives the expected rule set from the checker source

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

[greptile-apps]

Too many files changed for review. (1587 files found, 500 file limit)

[codecov]

Codecov Report

❌ Patch coverage is 76.00000% with 780 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/evals/main.py	1.31%	150 Missing ⚠️
...tellm/integrations/SlackAlerting/slack_alerting.py	20.19%	83 Missing ⚠️
litellm/caching/redis_cache.py	57.01%	49 Missing ⚠️
litellm/integrations/argilla.py	2.94%	33 Missing ⚠️
litellm/files/main.py	65.85%	28 Missing ⚠️
...col/providers/pydantic_ai_agents/transformation.py	0.00%	24 Missing ⚠️
litellm/integrations/braintrust_logging.py	38.46%	24 Missing ⚠️
litellm/experimental_mcp_client/client.py	58.18%	23 Missing ⚠️
litellm/integrations/datadog/datadog.py	61.40%	22 Missing ⚠️
litellm/images/main.py	71.23%	21 Missing ⚠️
... and 62 more

📢 Thoughts on this report? Let us know!

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Final on rebindable public config
  • Dropped Final from litellm/init.py module vars that consumers or the proxy rebind (api_key and the *_key family, service_callback/pre_call_rules/_async_input_callback, s3_callback_params, default_team_settings, fallbacks family, prometheus/guardrail toggles, and dozens of feature flags) while keeping Final on true constants.

Or push these changes by commenting:

@cursor push eefb99450f

Preview (eefb99450f)

diff --git a/litellm/__init__.py b/litellm/__init__.py
--- a/litellm/__init__.py
+++ b/litellm/__init__.py
@@ -107,7 +107,7 @@
 input_callback: List[CALLBACK_TYPES] = []
 success_callback: List[CALLBACK_TYPES] = []
 failure_callback: List[CALLBACK_TYPES] = []
-service_callback: Final[List[CALLBACK_TYPES]] = []
+service_callback: List[CALLBACK_TYPES] = []
 audit_log_callbacks: List[CALLBACK_TYPES] = []
 # logging_callback_manager is lazy-loaded via __getattr__
 _custom_logger_compatible_callbacks_literal = Literal[
@@ -163,25 +163,25 @@
     "compression_interception",
     "newrelic",
 ]
-cold_storage_custom_logger: Final[Optional[_custom_logger_compatible_callbacks_literal]] = None
-logged_real_time_event_types: Final[Optional[Union[List[str], Literal["*"]]]] = None
-_known_custom_logger_compatible_callbacks: Final[List] = list(get_args(_custom_logger_compatible_callbacks_literal))
+cold_storage_custom_logger: Optional[_custom_logger_compatible_callbacks_literal] = None
+logged_real_time_event_types: Optional[Union[List[str], Literal["*"]]] = None
+_known_custom_logger_compatible_callbacks: List = list(get_args(_custom_logger_compatible_callbacks_literal))
 callbacks: List[
     Union[Callable, _custom_logger_compatible_callbacks_literal, "CustomLogger"]  # CustomLogger is lazy-loaded
 ] = []
 callback_settings: Dict[str, Dict[str, Any]] = {}
 initialized_langfuse_clients: int = 0
-langfuse_default_tags: Final[Optional[List[str]]] = None
-langsmith_batch_size: Final[Optional[int]] = None
-prometheus_initialize_budget_metrics: Final[Optional[bool]] = False
-prometheus_latency_buckets: Final[Optional[List[float]]] = None
-require_auth_for_metrics_endpoint: Final[Optional[bool]] = True
-argilla_batch_size: Final[Optional[int]] = None
+langfuse_default_tags: Optional[List[str]] = None
+langsmith_batch_size: Optional[int] = None
+prometheus_initialize_budget_metrics: Optional[bool] = False
+prometheus_latency_buckets: Optional[List[float]] = None
+require_auth_for_metrics_endpoint: Optional[bool] = True
+argilla_batch_size: Optional[int] = None
 datadog_use_v1: Optional[bool] = False  # if you want to use v1 datadog logged payload.
-gcs_pub_sub_use_v1: Final[Optional[bool]] = False  # if you want to use v1 gcs pubsub logged payload
-generic_api_use_v1: Final[Optional[bool]] = False  # if you want to use v1 generic api logged payload
-argilla_transformation_object: Final[Optional[Dict[str, Any]]] = None
-_async_input_callback: Final[List[Union[str, Callable, "CustomLogger"]]] = (  # CustomLogger is lazy-loaded
+gcs_pub_sub_use_v1: Optional[bool] = False  # if you want to use v1 gcs pubsub logged payload
+generic_api_use_v1: Optional[bool] = False  # if you want to use v1 generic api logged payload
+argilla_transformation_object: Optional[Dict[str, Any]] = None
+_async_input_callback: List[Union[str, Callable, "CustomLogger"]] = (  # CustomLogger is lazy-loaded
     []
 )  # internal variable - async custom callbacks are routed here.
 _async_success_callback: List[Union[str, Callable, "CustomLogger"]] = (  # CustomLogger is lazy-loaded
@@ -190,13 +190,13 @@
 _async_failure_callback: List[Union[str, Callable, "CustomLogger"]] = (  # CustomLogger is lazy-loaded
     []
 )  # internal variable - async custom callbacks are routed here.
-pre_call_rules: Final[List[Callable]] = []
+pre_call_rules: List[Callable] = []
 post_call_rules: List[Callable] = []
 turn_off_message_logging: Optional[bool] = False
-standard_logging_payload_excluded_fields: Final[Optional[List[str]]] = (
+standard_logging_payload_excluded_fields: Optional[List[str]] = (
     None  # Fields to exclude from StandardLoggingPayload before callbacks receive it
 )
-log_raw_request_response: Final[bool] = False
+log_raw_request_response: bool = False
 redact_messages_in_exceptions: Optional[bool] = False
 redact_user_api_key_info: Optional[bool] = False
 # When True (default — preserves historical behavior), the Router appends
@@ -207,27 +207,27 @@
 # Deprecation: planned to flip to False (redact by default) in a future
 # major release; opt in early with `litellm.expose_router_debug_in_errors
 # = False`.
-expose_router_debug_in_errors: Final[bool] = True
-filter_invalid_headers: Final[Optional[bool]] = False
-add_user_information_to_llm_headers: Final[Optional[bool]] = (
+expose_router_debug_in_errors: bool = True
+filter_invalid_headers: Optional[bool] = False
+add_user_information_to_llm_headers: Optional[bool] = (
     None  # adds user_id, team_id, token hash (params from StandardLoggingMetadata) to request headers
 )
-overwrite_user_with_key_hash: Final[bool] = (
+overwrite_user_with_key_hash: bool = (
     False  # force the outgoing `user` param to the hashed api key, so providers see a stable, tamper-proof id
 )
 store_audit_logs = False  # Enterprise feature, allow users to see audit logs
-skip_system_message_in_guardrail: Final[bool] = False
-skip_tool_message_in_guardrail: Final[bool] = False
+skip_system_message_in_guardrail: bool = False
+skip_tool_message_in_guardrail: bool = False
 ### end of callbacks #############
 
-email: Final[Optional[str]] = (
+email: Optional[str] = (
     None  # Not used anymore, will be removed in next MAJOR release - https://github.com/BerriAI/litellm/discussions/648
 )
-token: Final[Optional[str]] = (
+token: Optional[str] = (
     None  # Not used anymore, will be removed in next MAJOR release - https://github.com/BerriAI/litellm/discussions/648
 )
-telemetry: Final = True
-max_tokens: Final[int] = DEFAULT_MAX_TOKENS  # OpenAI Defaults
+telemetry = True
+max_tokens: int = DEFAULT_MAX_TOKENS  # OpenAI Defaults
 drop_params = bool(os.getenv("LITELLM_DROP_PARAMS", False))
 modify_params = bool(os.getenv("LITELLM_MODIFY_PARAMS", False))
 use_chat_completions_url_for_anthropic_messages: bool = bool(
@@ -244,7 +244,7 @@
 # Or via `litellm_settings.strip_anthropic_total_tokens: true` in
 # config.yaml.
 strip_anthropic_total_tokens: bool = False
-route_all_chat_openai_to_responses: Final[bool] = (
+route_all_chat_openai_to_responses: bool = (
     os.getenv("LITELLM_ROUTE_ALL_CHAT_OPENAI_TO_RESPONSES", "false").lower() == "true"
 )  # When True, routes all OpenAI /chat/completions requests through the Responses API bridge
 # When True, Gemini/Vertex Live setup is deferred until client `session.update`.
@@ -254,71 +254,71 @@
     os.getenv("LITELLM_USE_LEGACY_INTERACTIONS_SCHEMA", "false").lower() == "true"
 )  # When True, sends Api-Revision: 2026-05-07 to Google so responses use the legacy `outputs`
 # schema instead of the new `steps` schema. Remove this flag after June 8, 2026.
-retry: Final = True
+retry = True
 ### AUTH ###
-api_key: Final[Optional[str]] = None
-openai_key: Final[Optional[str]] = None
-groq_key: Final[Optional[str]] = None
-gigachat_key: Final[Optional[str]] = None
-xai_key: Final[Optional[str]] = None
-databricks_key: Final[Optional[str]] = None
-openai_like_key: Final[Optional[str]] = None
-azure_key: Final[Optional[str]] = None
-anthropic_key: Final[Optional[str]] = None
-autorouter_savings_baseline_model: Final[Optional[str]] = None
-replicate_key: Final[Optional[str]] = None
-bytez_key: Final[Optional[str]] = None
-gdc_key: Final[Optional[str]] = None
-gdc_api_base: Final[Optional[str]] = None
-cohere_key: Final[Optional[str]] = None
-infinity_key: Final[Optional[str]] = None
-clarifai_key: Final[Optional[str]] = None
-maritalk_key: Final[Optional[str]] = None
-ai21_key: Final[Optional[str]] = None
-ollama_key: Final[Optional[str]] = None
-openrouter_key: Final[Optional[str]] = None
-datarobot_key: Final[Optional[str]] = None
-predibase_key: Final[Optional[str]] = None
-huggingface_key: Final[Optional[str]] = None
-vertex_project: Final[Optional[str]] = None
-vertex_location: Final[Optional[str]] = None
-predibase_tenant_id: Final[Optional[str]] = None
-togetherai_api_key: Final[Optional[str]] = None
-cloudflare_api_key: Final[Optional[str]] = None
-vercel_ai_gateway_key: Final[Optional[str]] = None
-baseten_key: Final[Optional[str]] = None
-llama_api_key: Final[Optional[str]] = None
-aleph_alpha_key: Final[Optional[str]] = None
-nlp_cloud_key: Final[Optional[str]] = None
-novita_api_key: Final[Optional[str]] = None
-snowflake_key: Final[Optional[str]] = None
-gradient_ai_api_key: Final[Optional[str]] = None
-nebius_key: Final[Optional[str]] = None
-wandb_key: Final[Optional[str]] = None
-heroku_key: Final[Optional[str]] = None
-cometapi_key: Final[Optional[str]] = None
-ovhcloud_key: Final[Optional[str]] = None
-lemonade_key: Final[Optional[str]] = None
-sap_service_key: Final[Optional[str]] = None
-amazon_nova_api_key: Final[Optional[str]] = None
-inception_key: Final[Optional[str]] = None
-common_cloud_provider_auth_params: Final[dict] = {
+api_key: Optional[str] = None
+openai_key: Optional[str] = None
+groq_key: Optional[str] = None
+gigachat_key: Optional[str] = None
+xai_key: Optional[str] = None
+databricks_key: Optional[str] = None
+openai_like_key: Optional[str] = None
+azure_key: Optional[str] = None
+anthropic_key: Optional[str] = None
+autorouter_savings_baseline_model: Optional[str] = None
+replicate_key: Optional[str] = None
+bytez_key: Optional[str] = None
+gdc_key: Optional[str] = None
+gdc_api_base: Optional[str] = None
+cohere_key: Optional[str] = None
+infinity_key: Optional[str] = None
+clarifai_key: Optional[str] = None
+maritalk_key: Optional[str] = None
+ai21_key: Optional[str] = None
+ollama_key: Optional[str] = None
+openrouter_key: Optional[str] = None
+datarobot_key: Optional[str] = None
+predibase_key: Optional[str] = None
+huggingface_key: Optional[str] = None
+vertex_project: Optional[str] = None
+vertex_location: Optional[str] = None
+predibase_tenant_id: Optional[str] = None
+togetherai_api_key: Optional[str] = None
+cloudflare_api_key: Optional[str] = None
+vercel_ai_gateway_key: Optional[str] = None
+baseten_key: Optional[str] = None
+llama_api_key: Optional[str] = None
+aleph_alpha_key: Optional[str] = None
+nlp_cloud_key: Optional[str] = None
+novita_api_key: Optional[str] = None
+snowflake_key: Optional[str] = None
+gradient_ai_api_key: Optional[str] = None
+nebius_key: Optional[str] = None
+wandb_key: Optional[str] = None
+heroku_key: Optional[str] = None
+cometapi_key: Optional[str] = None
+ovhcloud_key: Optional[str] = None
+lemonade_key: Optional[str] = None
+sap_service_key: Optional[str] = None
+amazon_nova_api_key: Optional[str] = None
+inception_key: Optional[str] = None
+common_cloud_provider_auth_params: dict = {
     "params": ["project", "region_name", "token"],
     "providers": ["vertex_ai", "bedrock", "watsonx", "azure", "vertex_ai_beta"],
 }
-use_litellm_proxy: Final[bool] = False  # when True, requests will be sent to the specified litellm proxy endpoint
-use_client: Final[bool] = False
+use_litellm_proxy: bool = False  # when True, requests will be sent to the specified litellm proxy endpoint
+use_client: bool = False
 ssl_verify: Union[str, bool] = True
-ssl_security_level: Final[Optional[str]] = None
-ssl_certificate: Final[Optional[str]] = None
+ssl_security_level: Optional[str] = None
+ssl_certificate: Optional[str] = None
 user_url_validation: bool = True
 user_url_allowed_hosts: List[str] = []
 provider_url_destination_allowed_hosts: List[str] = []
-ssl_ecdh_curve: Final[Optional[str]] = None  # Set to 'X25519' to disable PQC and improve performance
+ssl_ecdh_curve: Optional[str] = None  # Set to 'X25519' to disable PQC and improve performance
 disable_streaming_logging: bool = False
-disable_token_counter: Final[bool] = False
-disable_add_transform_inline_image_block: Final[bool] = False
-disable_add_user_agent_to_request_tags: Final[bool] = False
+disable_token_counter: bool = False
+disable_add_transform_inline_image_block: bool = False
+disable_add_user_agent_to_request_tags: bool = False
 disable_anthropic_gemini_context_caching_transform: bool = False
 enable_anthropic_prompt_caching: bool = os.getenv("LITELLM_ENABLE_ANTHROPIC_PROMPT_CACHING", "false").lower() == "true"
 _anthropic_prompt_caching_ttl_env: Final[Optional[str]] = os.getenv("LITELLM_ANTHROPIC_PROMPT_CACHING_TTL")
@@ -326,10 +326,10 @@
     "1h" if _anthropic_prompt_caching_ttl_env == "1h" else "5m" if _anthropic_prompt_caching_ttl_env == "5m" else None
 )
 disable_vertex_batch_output_transformation: bool = False
-extra_spend_tag_headers: Final[Optional[List[str]]] = None
+extra_spend_tag_headers: Optional[List[str]] = None
 in_memory_llm_clients_cache: "LLMClientCache"
 safe_memory_mode: Final[bool] = False
-enable_azure_ad_token_refresh: Final[Optional[bool]] = False
+enable_azure_ad_token_refresh: Optional[bool] = False
 # Proxy Authentication - auto-obtain/refresh OAuth2/JWT tokens for LiteLLM Proxy
 proxy_auth: Optional[Any] = None
 ### DEFAULT AZURE API VERSION ###
@@ -342,16 +342,16 @@
 credential_list: List["CredentialItem"] = []
 ### GUARDRAILS ###
 llamaguard_model_name: Final[Optional[str]] = None
-openai_moderations_model_name: Final[Optional[str]] = None
+openai_moderations_model_name: Optional[str] = None
 presidio_ad_hoc_recognizers: Final[Optional[str]] = None
 google_moderation_confidence_threshold: Final[Optional[float]] = None
 llamaguard_unsafe_content_categories: Final[Optional[str]] = None
-blocked_user_list: Final[Optional[Union[str, List]]] = None
-banned_keywords_list: Final[Optional[Union[str, List]]] = None
-llm_guard_mode: Final[Literal["all", "key-specific", "request-specific"]] = "all"
+blocked_user_list: Optional[Union[str, List]] = None
+banned_keywords_list: Optional[Union[str, List]] = None
+llm_guard_mode: Literal["all", "key-specific", "request-specific"] = "all"
 guardrail_name_config_map: Dict[str, GuardrailItem] = {}
-include_cost_in_streaming_usage: Final[bool] = False
-reasoning_auto_summary: Final[bool] = False
+include_cost_in_streaming_usage: bool = False
+reasoning_auto_summary: bool = False
 ### PROMPTS ####
 from litellm.types.prompts.init_prompts import PromptSpec
 
@@ -359,21 +359,21 @@
 
 ##################
 ### PREVIEW FEATURES ###
-enable_preview_features: Final[bool] = False
+enable_preview_features: bool = False
 return_response_headers: bool = False  # get response headers from LLM Api providers - example x-remaining-requests,
-enable_json_schema_validation: Final[bool] = False
+enable_json_schema_validation: bool = False
 enable_model_config_credential_overrides: bool = False
-enable_key_alias_format_validation: Final[bool] = (
+enable_key_alias_format_validation: bool = (
     False  # opt-in validation of key_alias format on /key/generate and /key/update
 )
-enable_gemini_default_thinking_level_low: Final[bool] = (
+enable_gemini_default_thinking_level_low: bool = (
     False  # opt-in: force thinkingLevel low/minimal for Gemini 3 thinking param mapping
 )
 ####################
-logging: Final[bool] = True
+logging: bool = True
 enable_loadbalancing_on_batch_endpoints: Final[Optional[bool]] = None
-require_managed_files: Final[bool] = False  # proxy only - require target_model_names on POST /v1/files
-enable_caching_on_provider_specific_optional_params: Final[bool] = (
+require_managed_files: bool = False  # proxy only - require target_model_names on POST /v1/files
+enable_caching_on_provider_specific_optional_params: bool = (
     False  # feature-flag for caching on optional params - e.g. 'top_k'
 )
 caching: bool = False  # Not used anymore, will be removed in next MAJOR release - https://github.com/BerriAI/litellm/discussions/648
@@ -381,16 +381,16 @@
 cache: Optional["Cache"] = None  # cache object <- use this - https://docs.litellm.ai/docs/caching
 default_in_memory_ttl: Optional[float] = None
 default_redis_ttl: Optional[float] = None
-default_redis_batch_cache_expiry: Final[Optional[float]] = None
-model_alias_map: Final[Dict[str, str]] = {}
+default_redis_batch_cache_expiry: Optional[float] = None
+model_alias_map: Dict[str, str] = {}
 model_group_settings: Optional["ModelGroupSettings"] = None
 max_budget: float = 0.0  # set the max budget across all providers
-budget_duration: Final[Optional[str]] = (
+budget_duration: Optional[str] = (
     None  # proxy only - resets budget after fixed duration. You can set duration as seconds ("30s"), minutes ("30m"), hours ("30h"), days ("30d").
 )
-default_soft_budget: Final[float] = DEFAULT_SOFT_BUDGET  # by default all litellm proxy keys have a soft budget of 50.0
-budget_exceeded_throttle_percentage: Final[Optional[float]] = None
-forward_traceparent_to_llm_provider: Final[bool] = False
+default_soft_budget: float = DEFAULT_SOFT_BUDGET  # by default all litellm proxy keys have a soft budget of 50.0
+budget_exceeded_throttle_percentage: Optional[float] = None
+forward_traceparent_to_llm_provider: bool = False
 
 
 _current_cost = 0.0  # private variable, used if max budget is set
@@ -398,9 +398,9 @@
 add_function_to_prompt: bool = (
     False  # if function calling not supported by api, append function call details to system prompt
 )
-client_session: Final[Optional[httpx.Client]] = None
-aclient_session: Final[Optional[httpx.AsyncClient]] = None
-model_fallbacks: Final[Optional[List]] = None  # Deprecated for 'litellm.fallbacks'
+client_session: Optional[httpx.Client] = None
+aclient_session: Optional[httpx.AsyncClient] = None
+model_fallbacks: Optional[List] = None  # Deprecated for 'litellm.fallbacks'
 model_cost_map_url: Final[str] = os.getenv(
     "LITELLM_MODEL_COST_MAP_URL",
     "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
@@ -415,57 +415,57 @@
 )
 suppress_debug_info: bool = False
 dynamodb_table_name: Optional[str] = None
-s3_callback_params: Final[Optional[Dict]] = None
-s3_audit_callback_params: Final[Optional[Dict]] = None
-datadog_llm_observability_params: Final[Optional[Union[DatadogLLMObsInitParams, Dict]]] = None
-datadog_params: Final[Optional[Union[DatadogInitParams, Dict]]] = None
-newrelic_params: Final[Optional[Union[NewRelicInitParams, Dict]]] = None
+s3_callback_params: Optional[Dict] = None
+s3_audit_callback_params: Optional[Dict] = None
+datadog_llm_observability_params: Optional[Union[DatadogLLMObsInitParams, Dict]] = None
+datadog_params: Optional[Union[DatadogInitParams, Dict]] = None
+newrelic_params: Optional[Union[NewRelicInitParams, Dict]] = None
 aws_sqs_callback_params: Optional[Dict] = None
-generic_logger_headers: Final[Optional[Dict]] = None
-default_key_generate_params: Final[Optional[Dict]] = None
-default_key_max_budget_alert_emails: Final[Optional[Dict[str, list]]] = None
+generic_logger_headers: Optional[Dict] = None
+default_key_generate_params: Optional[Dict] = None
+default_key_max_budget_alert_emails: Optional[Dict[str, list]] = None
 upperbound_key_generate_params: Optional[LiteLLM_UpperboundKeyGenerateParams] = None
-key_generation_settings: Final[Optional["StandardKeyGenerationConfig"]] = None
+key_generation_settings: Optional["StandardKeyGenerationConfig"] = None
 default_internal_user_params: Optional[Dict] = None
-default_team_params: Final[Optional[Union[DefaultTeamSSOParams, Dict]]] = None
-default_team_settings: Final[Optional[List]] = None
-max_user_budget: Final[Optional[float]] = None
+default_team_params: Optional[Union[DefaultTeamSSOParams, Dict]] = None
+default_team_settings: Optional[List] = None
+max_user_budget: Optional[float] = None
 default_max_internal_user_budget: Optional[float] = None
 max_internal_user_budget: Optional[float] = None
 max_ui_session_budget: Optional[float] = (
     1.0  # USD budget for each dashboard login session (playground, test connection)
 )
-internal_user_budget_duration: Final[Optional[str]] = None
-tag_budget_config: Final[Optional[Dict[str, "BudgetConfig"]]] = None
-max_end_user_budget: Final[Optional[float]] = None
-max_end_user_budget_id: Final[Optional[str]] = None
+internal_user_budget_duration: Optional[str] = None
+tag_budget_config: Optional[Dict[str, "BudgetConfig"]] = None
+max_end_user_budget: Optional[float] = None
+max_end_user_budget_id: Optional[str] = None
 # When True, end-user IDs extracted from requests are validated against
 # LiteLLM_EndUserTable / LiteLLM_UserTable. Values that do not resolve to a
 # known row are dropped before reaching spend logs. Defaults to False for
 # backwards compatibility — arbitrary client-supplied identifiers still
 # pass through unchanged.
-validate_end_user_id_in_db: Final[bool] = False
-disable_end_user_cost_tracking: Final[Optional[bool]] = None
-disable_end_user_cost_tracking_prometheus_only: Final[Optional[bool]] = None
-enable_end_user_cost_tracking_prometheus_only: Final[Optional[bool]] = None
-custom_prometheus_metadata_labels: Final[List[str]] = []
-custom_prometheus_tags: Final[List[str]] = []
-prometheus_metrics_config: Final[Optional[List]] = None
-prometheus_exclude_metrics: Final[Optional[List[str]]] = None
-prometheus_exclude_labels: Final[Optional[List[str]]] = None
-prometheus_emit_stream_label: Final[bool] = False
+validate_end_user_id_in_db: bool = False
+disable_end_user_cost_tracking: Optional[bool] = None
+disable_end_user_cost_tracking_prometheus_only: Optional[bool] = None
+enable_end_user_cost_tracking_prometheus_only: Optional[bool] = None
+custom_prometheus_metadata_labels: List[str] = []
+custom_prometheus_tags: List[str] = []
+prometheus_metrics_config: Optional[List] = None
+prometheus_exclude_metrics: Optional[List[str]] = None
+prometheus_exclude_labels: Optional[List[str]] = None
+prometheus_emit_stream_label: bool = False
 # Opt-in: emit `rate_limit_category` and `rate_limit_type` labels on
 # `litellm_proxy_failed_requests_metric`. Off by default to preserve the
 # pre-unification label set so existing dashboards / recording rules keyed on
 # that metric keep matching after upgrade. Enable when downstream consumers
 # are ready to split 429s by source (vendor vs. litellm) and dimension
 # (RPM/TPM/concurrent/budget).
-prometheus_emit_rate_limit_labels: Final[bool] = False
-prometheus_user_budget_label_include_email_alias: Final[bool] = False
-prometheus_end_user_metrics_max_series_per_metric: Final[Optional[int]] = 10000
-prometheus_end_user_metrics_ttl_seconds: Final[Optional[float]] = 3600.0
-prometheus_end_user_metrics_cleanup_interval_seconds: Final[Optional[float]] = 60.0
-disable_add_prefix_to_prompt: Final[bool] = False  # used by anthropic, to disable adding prefix to prompt
+prometheus_emit_rate_limit_labels: bool = False
+prometheus_user_budget_label_include_email_alias: bool = False
+prometheus_end_user_metrics_max_series_per_metric: Optional[int] = 10000
+prometheus_end_user_metrics_ttl_seconds: Optional[float] = 3600.0
+prometheus_end_user_metrics_cleanup_interval_seconds: Optional[float] = 60.0
+disable_add_prefix_to_prompt: bool = False  # used by anthropic, to disable adding prefix to prompt
 disable_copilot_system_to_assistant: bool = False  # If false (default), converts all 'system' role messages to 'assistant' for GitHub Copilot compatibility. Set to true to disable this behavior.
 public_mcp_servers: Optional[List[str]] = None
 public_mcp_hub_strict_whitelist: bool = True
@@ -476,7 +476,7 @@
 # Old format: { "displayName": "url" } (for backward compatibility)
 public_model_groups_links: Dict[str, Union[str, Dict[str, Any]]] = {}
 #### REQUEST PRIORITIZATION #######
-priority_reservation: Final[Optional[Dict[str, Union[float, "PriorityReservationDict"]]]] = None
+priority_reservation: Optional[Dict[str, Union[float, "PriorityReservationDict"]]] = None
 # priority_reservation_settings is lazy-loaded via __getattr__
 # Only declare for type checking - at runtime __getattr__ handles it
 if TYPE_CHECKING:
@@ -487,23 +487,23 @@
 use_aiohttp_transport: bool = True  # Older variable, aiohttp is now the default. use disable_aiohttp_transport instead.
 aiohttp_trust_env: Final[bool] = False  # set to true to use HTTP_ Proxy settings
 disable_aiohttp_transport: bool = False  # Set this to true to use httpx instead
-disable_aiohttp_trust_env: Final[bool] = False  # When False, aiohttp will respect HTTP(S)_PROXY env vars
+disable_aiohttp_trust_env: bool = False  # When False, aiohttp will respect HTTP(S)_PROXY env vars
 force_ipv4: bool = False  # when True, litellm will force ipv4 for all LLM requests. Some users have seen httpx ConnectionError when using ipv6.
 network_mock: Final[bool] = False  # When True, use mock transport — no real network calls
 
 ####### STOP SEQUENCE LIMIT #######
-disable_stop_sequence_limit: Final[bool] = False  # when True, stop sequence limit is disabled
+disable_stop_sequence_limit: bool = False  # when True, stop sequence limit is disabled
 
 #### RETRIES ####
 num_retries: Optional[int] = None  # per model endpoint
-max_fallbacks: Final[Optional[int]] = None
-default_fallbacks: Final[Optional[List]] = None
-fallbacks: Final[Optional[List]] = None
-context_window_fallbacks: Final[Optional[List]] = None
-content_policy_fallbacks: Final[Optional[List]] = None
-allowed_fails: Final[int] = 3
-allow_dynamic_callback_disabling: Final[bool] = True
-num_retries_per_request: Final[Optional[int]] = None  # for the request overall (incl. fallbacks + model retries)
+max_fallbacks: Optional[int] = None
+default_fallbacks: Optional[List] = None
+fallbacks: Optional[List] = None
+context_window_fallbacks: Optional[List] = None
+content_policy_fallbacks: Optional[List] = None
+allowed_fails: int = 3
+allow_dynamic_callback_disabling: bool = True
+num_retries_per_request: Optional[int] = None  # for the request overall (incl. fallbacks + model retries)
 ####### SECRET MANAGERS #####################
 secret_manager_client: Optional[Any] = (
     None  # list of instantiated key management clients - e.g. azure kv, infisical, etc.
@@ -515,7 +515,7 @@
 # We'll import it after the lazy import system is set up
 # We can't define it here because KeyManagementSettings is lazy-loaded
 #### PII MASKING ####
-output_parse_pii: Final[bool] = False
+output_parse_pii: bool = False
 #############################################
 from litellm.litellm_core_utils.get_model_cost_map import get_model_cost_map
 
@@ -528,7 +528,7 @@
 # Fixed: {"openai": {"fixed_amount": 0.001}} = $0.001 per request
 # Global: {"global": 0.05} = 5% global margin on all providers
 # Combined: {"vertex_ai": {"percentage": 0.08, "fixed_amount": 0.0005}}
-custom_prompt_dict: Final[Dict[str, dict]] = {}
+custom_prompt_dict: Dict[str, dict] = {}
 check_provider_endpoint: Final = False
 
 
@@ -554,19 +554,19 @@
 organization: Final = None
 project: Final = None
 config_path = None
-vertex_ai_safety_settings: Final[Optional[dict]] = None
+vertex_ai_safety_settings: Optional[dict] = None
 
 ####### COMPLETION MODELS ###################
 from typing import Set
 
 open_ai_chat_completion_models: Final[Set] = set()
 open_ai_text_completion_models: Final[Set] = set()
-cohere_models: Final[Set] = set()
+cohere_models: Set = set()
 cohere_chat_models: Final[Set] = set()
 mistral_chat_models: Final[Set] = set()
 text_completion_codestral_models: Final[Set] = set()
-text_completion_inception_models: Final[Set] = set()
-anthropic_models: Final[Set] = set()
+text_completion_inception_models: Set = set()
+anthropic_models: Set = set()
 openrouter_models: Final[Set] = set()
 datarobot_models: Final[Set] = set()
 vertex_language_models: Final[Set] = set()
@@ -579,10 +579,10 @@
 vertex_code_text_models: Final[Set] = set()
 vertex_embedding_models: Final[Set] = set()
 vertex_anthropic_models: Final[Set] = set()
-vertex_llama3_models: Final[Set] = set()
+vertex_llama3_models: Set = set()
 vertex_deepseek_models: Final[Set] = set()
 vertex_ai_ai21_models: Final[Set] = set()
-vertex_mistral_models: Final[Set] = set()
+vertex_mistral_models: Set = set()
 vertex_openai_models: Final[Set] = set()
 vertex_minimax_models: Final[Set] = set()
 vertex_moonshot_models: Final[Set] = set()
@@ -645,8 +645,8 @@
 darkbloom_models: Final[Set] = set()
 v0_models: Final[Set] = set()
 morph_models: Final[Set] = set()
-lambda_ai_models: Final[Set] = set()
-inception_models: Final[Set] = set()
+lambda_ai_models: Set = set()
+inception_models: Set = set()
 hyperbolic_models: Final[Set] = set()
 black_forest_labs_models: Final[Set] = set()
 recraft_models: Final[Set] = set()

_{You can send follow-ups to the cloud agent here.}

[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 258d154. Configure here.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_enforce_final_variables (258d154) with litellm_internal_staging (49eb19c)¹}

Footnotes

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