feat(proxy): type Customer Management response_model for OpenAPI coverage

[ryan-crabbe-berri]

Relevant issues

Linear ticket

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Screenshots / Proof of Fix

With a proxy running against this branch, the OpenAPI schema documents a concrete response body for every Customer Management operation:

curl -s http://localhost:4000/openapi.json \
  | jq '.paths["/customer/new"].post.responses."200".content."application/json".schema,
        .paths["/customer/delete"].post.responses."200".content."application/json".schema'

/customer/new, /customer/update, /customer/info, /customer/list reference CustomerResponse; block/unblock/delete reference their dedicated models. Previously these returned the default untyped 200 response.

Type

🆕 New Feature
🧹 Refactoring
✅ Test

Changes

Two things, in order.

First, the Customer Management endpoint group is fully typed for OpenAPI coverage. The five previously-untyped operations (block, unblock, new, update, delete) get response models; block/unblock/delete get three small dedicated models in litellm/types/proxy/management_endpoints/customer_endpoints.py, and the customer-object endpoints (new/update/info/list) share CustomerResponse. Response fidelity was checked against the table schema: budget_id was missing from LiteLLM_EndUserTable and is added back, and the nested budget now uses LiteLLM_BudgetTableFull so server-managed fields (budget_reset_at, created_at) survive rather than being narrowed to the write-allowlist shape. No field the endpoints used to return is dropped. This also resolves the earlier review feedback on this PR (the silent budget_id / nested-budget narrowing, and the misleading UnblockUsersResponse.blocked_users name, now documented via a Field description).

Second, the customer response flow is made type-safe rather than relying on a runtime filter. The handlers no longer return an untyped dict from .model_dump() with response_model doing the shaping at the exit. Instead a single mapper, _to_customer_response, validates a DB row into CustomerResponse at one typed boundary, and the handlers construct and return typed models with real return annotations (-> CustomerResponse, -> List[CustomerResponse], -> DeleteCustomersResponse). basedpyright now verifies the return shapes. This also let four copy-pasted object_permission reverse-relation cleanup loops be deleted: pydantic's extra=ignore drops those undeclared fields during validation, so the loops were dead code. basedpyright errors on the endpoint file drop from 140 to 116.

To guarantee the refactor changes no behavior, it was done under a characterization (golden-master) safety net: tests that lock the exact JSON body each customer-object endpoint emits today, committed green against the old code, then kept green byte-for-byte through the refactor. Those live in test_customer_endpoints.py alongside the per-endpoint response-model assertions, the budget_id and nested-budget fidelity regressions, and the existing error-schema tests.

response_model= stays on the decorators for OpenAPI generation and defense in depth; it now matches the handler return annotations instead of compensating for an untyped return.

[greptile-apps]

Greptile Summary

• Adds concrete response models for Customer Management endpoints so OpenAPI documents typed response bodies.
• Routes customer-object endpoint responses through a shared CustomerResponse mapper.
• Restores budget_id on end-user response typing and preserves full nested budget fields.
• Regenerates dashboard API types and adds tests for response models and response-shape preservation.

Confidence Score: 4/5

The change is narrowly scoped, but the customer response typing can reject valid partial nested budget payloads and surface as endpoint failures.

The modified response model path is well covered conceptually, and focused runtime evidence confirms the remaining issue is concrete and localized.

litellm/types/proxy/management_endpoints/customer_endpoints.py

T-Rex Logs

What T-Rex did

• The nested budget validation break was reproduced using a focused Python harness that validates a fake customer row through the same mapper used by the endpoints.
• OpenAPI response-model snippets were captured before and after the change, showing the base 200 responses with default schemas and later the after-state with the expected $ref schemas.
• Observed response contract deltas between base and head: budget_id, budget_reset_at, and created_at were added to /customer/info and /customer/list, and nested audit fields were removed from /customer/new and /customer/update.
• The head contract under validation passed, though the base artifact already showed budget_id and full nested budget fields, so the exact contrast was not reproduced.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   Customer object endpoint JSON bodies changed across typed response mapper refactor

   • Bug
     • The refactor to _to_customer_response does not preserve the JSON response body contract for customer-object endpoints. In the executed TestClient harness, base /customer/info and /customer/list responses omitted top-level budget_id and nested budget budget_reset_at/created_at, while head includes them. Conversely, base /customer/new and /customer/update nested budget responses included created_by, updated_at, and updated_by, while head omits those fields. /customer/delete remained unchanged, and object_permission reverse relations were still omitted.
   • Cause
     • _to_customer_response validates rows into the new CustomerResponse model, whose field set differs from the pre-refactor mixture of raw dict returns and response_model filtering. That changes which top-level and nested budget fields survive serialization for different endpoints.
   • Fix
     • If no behavior change is intended, make CustomerResponse and _to_customer_response reproduce the previous endpoint-specific serialized shapes, or keep endpoint-specific serialization where legacy responses differed. If the new shape is intentional, update the contract/tests and document the response body change.

   _{Ran code and verified through T-Rex}

_{Reviews (4): Last reviewed commit: "fix(ui): make generated API types stable..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 82.75862% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...m/proxy/management_endpoints/customer_endpoints.py	66.66%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[ryan-crabbe-berri]

@greptileai re review

[ryan-crabbe-berri]

@greptileai

[mateo-berri]

Love this! ❤️

LGTM just minor non-blocking nit

[mateo-berri]

also, you might need to reformat + pull latest internal staging to fix linting issues

[ryan-crabbe-berri]

@greptileai re review

[greptile-apps]

Nested budget validation breaks

CustomerResponse now validates every customer row's nested budget as LiteLLM_BudgetTableFull, but that model requires created_at. When _to_customer_response() receives a customer row whose joined budget payload lacks created_at, the customer endpoints can fail response validation and return a 500. This can happen with partial joined budget rows or existing callers/tests that previously used the narrower LiteLLM_BudgetTable shape, which did not require created_at.

Artifacts

Repro: focused mapper and endpoint harness source

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Repro: direct validation error and HTTP 500 Internal Server Error output

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

[ryan-crabbe-berri]

Greptile's repro fabricates a budget object with no created_at and feeds it straight to the internal mapper, but no real /customer/* request can reach that state since the budget is always None or a DB row whose created_at is NOT NULL DEFAULT now()

[greptile-apps]

Fair point — litellm_budgettable.created_at is NOT NULL DEFAULT now(), so any real DB row returned from a /customer/* handler will always carry it. The concern only applies to hand-crafted test stubs that omit created_at, which isn't a production failure path. I'll withdraw this comment.