refactor(repositories): type prisma table access with one generic protocol

[mateo-berri]

TLDR

Problem this solves:

• Every prisma table call handed callers back Any
• That Any hid nullable rows, so real crashes shipped
• 12 near-identical hand-rolled table Protocols had drifted apart

How it solves it:

• One generic TableActions[RowT_co] types every repository's .table
• Nullable returns are visible now, so 500s became 404s
• Drops 1,444 reportAny and 73 reportExplicitAny

User Flow

A team runs a shared notes entry on the memory API. Their keys carry "allowed_routes": ["/v1/memory", "/v1/memory/*"] so the team reaches it without a proxy admin key: a service key scoped to the team writes, and the team's own members read and curate

Before: the team admin can never edit or delete the entry their own team owns, and every attempt comes back 500

1. The team-scoped service key (issued with "team_id": "team-shared" and no user attached) seeds the entry with POST https://litellm-domain/v1/memory and body {"key": "team-notes", "value": "sprint goals"}, which returns 200 and a row whose user_id is null and team_id is team-shared
2. The team admin reads it with GET https://litellm-domain/v1/memory/team-notes and gets 200 with "value": "sprint goals"
3. The team admin edits it with PUT https://litellm-domain/v1/memory/team-notes and body {"value": "revised sprint goals"}, and the response is 500 with {"detail": "Internal error updating memory entry."}
4. A team member who is not an admin sends that same PUT and gets the identical 500, so the 403 they were owed never arrives and a refusal is indistinguishable from an outage
5. The admin tries removing the entry instead with DELETE https://litellm-domain/v1/memory/team-notes, which returns 500 with {"error": {"message": "Internal server error", "type": "internal_server_error"}}
6. GET https://litellm-domain/v1/memory/team-notes still returns 200 with "sprint goals", so the entry is frozen and only a proxy admin key can change or remove it

After: the same team admin edits and deletes the entry normally, and the non-admin member is refused in a way they can read

1. The team-scoped service key (issued with "team_id": "team-shared" and no user attached) seeds the entry with POST https://litellm-domain/v1/memory and body {"key": "team-notes", "value": "sprint goals"}, which returns 200 and a row whose user_id is null and team_id is team-shared
2. The team admin reads it with GET https://litellm-domain/v1/memory/team-notes and gets 200 with "value": "sprint goals"
3. The team admin edits it with PUT https://litellm-domain/v1/memory/team-notes and body {"value": "revised sprint goals"}, and the response is 200 with "value": "revised sprint goals" and updated_by set to the admin's user id
4. A team member who is not an admin sends that same PUT and gets 403 with {"detail": "You do not have permission to modify this memory entry."}, so a refusal reads as a refusal
5. The admin removes the entry with DELETE https://litellm-domain/v1/memory/team-notes, which returns 200 with {"key": "team-notes", "deleted": true}
6. GET https://litellm-domain/v1/memory/team-notes returns 404 with {"detail": "Memory with key 'team-notes' not found"}, so the entry is gone

A team admin can now curate the entries their team owns without borrowing a proxy admin key, and a non-admin member still cannot change them

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
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• 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

Both legs run the same script against their own proxy: an own worktree, venv, and postgres:16-alpine container, booted with --num_workers 2 (two uvicorn workers in one proxy process). Before is the merge base ba8d8b6 on port 20129 with RUN=f7; After is the tip 7965cfd on port 36119 with RUN=g8. Models are the latest in their families (gpt-5.4-mini, anthropic/claude-haiku-4-5) and every LLM call hit the real provider

Shared setup, run once per leg with the proxy's master key:

export MK="sk-1234" J="Content-Type: application/json"
export BASE="http://127.0.0.1:$PORT" TEAM="team-shared-$RUN" KEY="team-notes-$RUN"
export ROUTES='"allowed_routes":["/v1/memory","/v1/memory/*"]'
curl -s -X POST "$BASE/team/new" -H "Authorization: Bearer $MK" -H "$J" \
  -d "{\"team_id\":\"$TEAM\",\"team_alias\":\"$TEAM\",\"members_with_roles\":[{\"user_id\":\"alice-$RUN\",\"role\":\"admin\"},{\"user_id\":\"bob-$RUN\",\"role\":\"user\"}]}"
SVC=$(curl -s -X POST "$BASE/key/generate" -H "Authorization: Bearer $MK" -H "$J" -d "{\"team_id\":\"$TEAM\",$ROUTES}" | jq -r .key)
ALICE=$(curl -s -X POST "$BASE/key/generate" -H "Authorization: Bearer $MK" -H "$J" -d "{\"team_id\":\"$TEAM\",\"user_id\":\"alice-$RUN\",$ROUTES}" | jq -r .key)
BOB=$(curl -s -X POST "$BASE/key/generate" -H "Authorization: Bearer $MK" -H "$J" -d "{\"team_id\":\"$TEAM\",\"user_id\":\"bob-$RUN\",$ROUTES}" | jq -r .key)

Before (ba8d8b6)

Team admin edits the entry their team owns

1. The team's service key seeds the shared entry

   curl -s -X POST "$BASE/v1/memory" -H "Authorization: Bearer $SVC" -H "$J" \
     -d "{\"key\":\"$KEY\",\"value\":\"sprint goals\"}" -w "\nHTTP %{http_code}\n"

   {"memory_id":"bc7b16b6-d115-4092-bc21-2fccdf2d3c7d","key":"team-notes-f7","value":"sprint goals","metadata":null,"user_id":null,"team_id":"team-shared-f7","created_at":"2026-08-25T23:50:05.412000Z","created_by":null,"updated_at":"2026-08-25T23:50:05.412000Z","updated_by":null}
   HTTP 200
   

2. The team admin reads it back

   curl -s "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -w "\nHTTP %{http_code}\n"

   {"memory_id":"bc7b16b6-d115-4092-bc21-2fccdf2d3c7d","key":"team-notes-f7","value":"sprint goals","metadata":null,"user_id":null,"team_id":"team-shared-f7","created_at":"2026-08-25T23:50:05.412000Z","created_by":null,"updated_at":"2026-08-25T23:50:05.412000Z","updated_by":null}
   HTTP 200
   

3. The team admin edits it

   curl -s -X PUT "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -H "$J" \
     -d '{"value":"revised sprint goals"}' -w "\nHTTP %{http_code}\n"

   {"detail":"Internal error updating memory entry."}
   HTTP 500
   

A non-admin team member is refused

1. The non-admin member sends the same edit

   curl -s -X PUT "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $BOB" -H "$J" \
     -d '{"value":"bob was here"}' -w "\nHTTP %{http_code}\n"

   {"detail":"Internal error updating memory entry."}
   HTTP 500
   

Team admin deletes the entry

1. The team admin deletes it

   curl -s -X DELETE "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -w "\nHTTP %{http_code}\n"

   {"error":{"message":"Internal server error","type":"internal_server_error"}}
   HTTP 500
   

2. The team admin reads it again

   curl -s "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -w "\nHTTP %{http_code}\n"

   {"memory_id":"bc7b16b6-d115-4092-bc21-2fccdf2d3c7d","key":"team-notes-f7","value":"sprint goals","metadata":null,"user_id":null,"team_id":"team-shared-f7","created_at":"2026-08-25T23:50:05.412000Z","created_by":null,"updated_at":"2026-08-25T23:50:05.412000Z","updated_by":null}
   HTTP 200
   

Proxy admin adds and removes a team member

1. Add carol as a member

   curl -s -X POST "$BASE/team/member_add" -H "Authorization: Bearer $MK" -H "$J" \
     -d "{\"team_id\":\"$TEAM\",\"member\":{\"user_id\":\"carol-$RUN\",\"role\":\"user\"}}" -w "\nHTTP %{http_code}\n" | jq -c "if type==\"object\" then {team_id, members: [.members_with_roles[]?.user_id]} else . end" 2>/dev/null || true

   {"team_id":"team-shared-f7","members":["alice-f7","bob-f7","default_user_id","carol-f7"]}
   

2. Team info lists carol

   curl -s "$BASE/team/info?team_id=$TEAM" -H "Authorization: Bearer $MK" | jq -c "{members: [.team_info.members_with_roles[].user_id], memberships: [.team_memberships[].user_id]}"

   {"members":["alice-f7","bob-f7","default_user_id","carol-f7"],"memberships":[]}
   

3. Remove carol again

   curl -s -X POST "$BASE/team/member_delete" -H "Authorization: Bearer $MK" -H "$J" \
     -d "{\"team_id\":\"$TEAM\",\"user_id\":\"carol-$RUN\"}" -w "\nHTTP %{http_code}\n" | jq -c "if type==\"object\" then {team_id, members: [.members_with_roles[]?.user_id]} else . end" 2>/dev/null || true

   {"team_id":"team-shared-f7","members":["alice-f7","bob-f7","default_user_id"]}
   

4. Team info no longer lists carol

   curl -s "$BASE/team/info?team_id=$TEAM" -H "Authorization: Bearer $MK" | jq -c "{members: [.team_info.members_with_roles[].user_id], memberships: [.team_memberships[].user_id]}"

   {"members":["alice-f7","bob-f7","default_user_id"],"memberships":[]}
   

LLM traffic keeps flowing

1. Chat completions against OpenAI

   curl -s -X POST "$BASE/v1/chat/completions" -H "Authorization: Bearer $MK" -H "$J" \
     -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Reply with the single word: pong"}]}' | jq -c "{text: .choices[0].message.content, usage}"

   {"text":"pong","usage":{"completion_tokens":4,"prompt_tokens":13,"total_tokens":17,"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}}}
   

2. Responses against OpenAI

   curl -s -X POST "$BASE/v1/responses" -H "Authorization: Bearer $MK" -H "$J" \
     -d '{"model":"gpt-5.4-mini","input":"Reply with the single word: pong"}' | jq -c "{text: [.output[] | select(.type==\"message\") | .content[0].text][0], usage}"

   {"text":"pong","usage":{"input_tokens":13,"input_tokens_details":{"audio_tokens":null,"cached_tokens":0,"text_tokens":null,"cache_write_tokens":0},"output_tokens":5,"output_tokens_details":{"reasoning_tokens":0,"text_tokens":null},"total_tokens":18,"cost":null}}
   

3. Messages against Anthropic

   curl -s -X POST "$BASE/v1/messages" -H "Authorization: Bearer $MK" -H "$J" \
     -d '{"model":"anthropic-haiku-4-5","max_tokens":16,"messages":[{"role":"user","content":"Reply with the single word: pong"}]}' | jq -c "{text: .content[0].text, usage}"

   {"text":"pong","usage":{"input_tokens":15,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":5,"service_tier":"standard","inference_geo":"not_available"}}
   

After (7965cfd)

Team admin edits the entry their team owns

1. The team's service key seeds the shared entry

   curl -s -X POST "$BASE/v1/memory" -H "Authorization: Bearer $SVC" -H "$J" \
     -d "{\"key\":\"$KEY\",\"value\":\"sprint goals\"}" -w "\nHTTP %{http_code}\n"

   {"memory_id":"247a737b-62b4-4a2e-8251-2b29f903bb81","key":"team-notes-g8","value":"sprint goals","metadata":null,"user_id":null,"team_id":"team-shared-g8","created_at":"2026-08-25T23:52:28.288000Z","created_by":null,"updated_at":"2026-08-25T23:52:28.288000Z","updated_by":null}
   HTTP 200
   

2. The team admin reads it back

   curl -s "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -w "\nHTTP %{http_code}\n"

   {"memory_id":"247a737b-62b4-4a2e-8251-2b29f903bb81","key":"team-notes-g8","value":"sprint goals","metadata":null,"user_id":null,"team_id":"team-shared-g8","created_at":"2026-08-25T23:52:28.288000Z","created_by":null,"updated_at":"2026-08-25T23:52:28.288000Z","updated_by":null}
   HTTP 200
   

3. The team admin edits it

   curl -s -X PUT "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -H "$J" \
     -d '{"value":"revised sprint goals"}' -w "\nHTTP %{http_code}\n"

   {"memory_id":"247a737b-62b4-4a2e-8251-2b29f903bb81","key":"team-notes-g8","value":"revised sprint goals","metadata":null,"user_id":null,"team_id":"team-shared-g8","created_at":"2026-08-25T23:52:28.288000Z","created_by":null,"updated_at":"2026-08-25T23:52:28.354000Z","updated_by":"alice-g8"}
   HTTP 200
   

A non-admin team member is refused

1. The non-admin member sends the same edit

   curl -s -X PUT "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $BOB" -H "$J" \
     -d '{"value":"bob was here"}' -w "\nHTTP %{http_code}\n"

   {"detail":"You do not have permission to modify this memory entry."}
   HTTP 403
   

Team admin deletes the entry

1. The team admin deletes it

   curl -s -X DELETE "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -w "\nHTTP %{http_code}\n"

   {"key":"team-notes-g8","deleted":true}
   HTTP 200
   

2. The team admin reads it again

   curl -s "$BASE/v1/memory/$KEY" -H "Authorization: Bearer $ALICE" -w "\nHTTP %{http_code}\n"

   {"detail":"Memory with key 'team-notes-g8' not found"}
   HTTP 404
   

Proxy admin adds and removes a team member

1. Add carol as a member

   curl -s -X POST "$BASE/team/member_add" -H "Authorization: Bearer $MK" -H "$J" \
     -d "{\"team_id\":\"$TEAM\",\"member\":{\"user_id\":\"carol-$RUN\",\"role\":\"user\"}}" -w "\nHTTP %{http_code}\n" | jq -c "if type==\"object\" then {team_id, members: [.members_with_roles[]?.user_id]} else . end" 2>/dev/null || true

   {"team_id":"team-shared-g8","members":["alice-g8","bob-g8","default_user_id","carol-g8"]}
   

2. Team info lists carol

   curl -s "$BASE/team/info?team_id=$TEAM" -H "Authorization: Bearer $MK" | jq -c "{members: [.team_info.members_with_roles[].user_id], memberships: [.team_memberships[].user_id]}"

   {"members":["alice-g8","bob-g8","default_user_id","carol-g8"],"memberships":[]}
   

3. Remove carol again

   curl -s -X POST "$BASE/team/member_delete" -H "Authorization: Bearer $MK" -H "$J" \
     -d "{\"team_id\":\"$TEAM\",\"user_id\":\"carol-$RUN\"}" -w "\nHTTP %{http_code}\n" | jq -c "if type==\"object\" then {team_id, members: [.members_with_roles[]?.user_id]} else . end" 2>/dev/null || true

   {"team_id":"team-shared-g8","members":["alice-g8","bob-g8","default_user_id"]}
   

4. Team info no longer lists carol

   curl -s "$BASE/team/info?team_id=$TEAM" -H "Authorization: Bearer $MK" | jq -c "{members: [.team_info.members_with_roles[].user_id], memberships: [.team_memberships[].user_id]}"

   {"members":["alice-g8","bob-g8","default_user_id"],"memberships":[]}
   

LLM traffic keeps flowing

1. Chat completions against OpenAI

   curl -s -X POST "$BASE/v1/chat/completions" -H "Authorization: Bearer $MK" -H "$J" \
     -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Reply with the single word: pong"}]}' | jq -c "{text: .choices[0].message.content, usage}"

   {"text":"pong","usage":{"completion_tokens":4,"prompt_tokens":13,"total_tokens":17,"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}}}
   

2. Responses against OpenAI

   curl -s -X POST "$BASE/v1/responses" -H "Authorization: Bearer $MK" -H "$J" \
     -d '{"model":"gpt-5.4-mini","input":"Reply with the single word: pong"}' | jq -c "{text: [.output[] | select(.type==\"message\") | .content[0].text][0], usage}"

   {"text":"pong","usage":{"input_tokens":13,"input_tokens_details":{"audio_tokens":null,"cached_tokens":0,"text_tokens":null,"cache_write_tokens":0},"output_tokens":5,"output_tokens_details":{"reasoning_tokens":0,"text_tokens":null},"total_tokens":18,"cost":null}}
   

3. Messages against Anthropic

   curl -s -X POST "$BASE/v1/messages" -H "Authorization: Bearer $MK" -H "$J" \
     -d '{"model":"anthropic-haiku-4-5","max_tokens":16,"messages":[{"role":"user","content":"Reply with the single word: pong"}]}' | jq -c "{text: .content[0].text, usage}"

   {"text":"pong","usage":{"input_tokens":15,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":5,"service_tier":"standard","inference_geo":"not_available"}}
   

Observed alongside the fix, all identical on both legs and left alone by this PR:

• team/info returns empty team_memberships after member_add (pre-existing)
• default_user_id shows up in members_with_roles after team/new (pre-existing)

Type

🐛 Bug Fix
🧹 Refactoring

Caveats (if any)

Low

• Behavior changes only on paths that already crashed
• find_many returns Sequence, keeping TableActions covariant
• Four team write routes now 404, and /team/{team_id}/callback now 400s, on a concurrently deleted team
• /key/list with an unknown key_hash now 403s instead of 500 for non-admins
• Org member add with an unknown user_email now 400s instead of 500
• Memory delete now 404s when the row vanished mid-request
• /team/new with non-string models or members now 422s instead of 500

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

• 7965cfd passes /live-pr-risk

---

Note

Medium Risk
Touches auth, virtual-key, team/user deletion, and MCP DB paths with real HTTP status changes when updates hit missing rows; scope is broad but changes are mostly typing plus null guards rather than new business rules.

Overview
Replaces scattered per-file Prisma table Protocols with the shared generic TableActions[RowT_co] from litellm.repositories.prisma_protocols, wiring repositories across MCP, agents, guardrails, key/user/org management, config sync, and related proxy paths through one seam. basedpyright error budgets are tightened to match the resulting drop in Any/unknown-type noise.

Call sites now treat update/delete as RowT | None instead of assuming a row always comes back. That drives explicit None checks (404/ValueError/HTTP errors) in agents, MCP server DB helpers, guardrails, JWT mappings, Claude Code plugins, model updates, team callbacks, SCIM group updates, and key lookup—so missing rows fail as client errors instead of blowing up later on attribute access.

Smaller typing cleanups ride along: TeamBase admins/members/models become list[str]; many list[...] Prisma reads become Sequence[...]; auth and container code use narrower row protocols or prisma_models types; model_dump() replaces .dict() in several paths; targeted cast/pyright suppressions document Prisma JSON vs domain-model boundaries.

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

[codecov]

Codecov Report

❌ Patch coverage is 91.57143% with 59 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...lm/proxy/policy_engine/policy_resolve_endpoints.py	36.84%	12 Missing ⚠️
...xy/management_endpoints/internal_user_endpoints.py	75.86%	7 Missing ⚠️
litellm/proxy/_experimental/mcp_server/db.py	70.00%	6 Missing ⚠️
...itellm_completion_transformation/transformation.py	80.00%	6 Missing ⚠️
litellm/proxy/proxy_server.py	88.23%	4 Missing ⚠️
...y/management_endpoints/key_management_endpoints.py	90.32%	3 Missing ⚠️
litellm/proxy/spend_tracking/vantage_endpoints.py	70.00%	3 Missing ⚠️
litellm/proxy/utils.py	83.33%	3 Missing ⚠️
litellm/responses/sse_output_recovery.py	81.25%	3 Missing ⚠️
litellm/proxy/guardrails/usage_endpoints.py	66.66%	2 Missing ⚠️
... and 9 more

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_decrease_anys_opus5_round2 (7965cfd) with litellm_internal_staging (ba8d8b6)¹}

Footnotes

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

[mateo-berri]

@greptileai

[greptile-apps]

Greptile Summary

The PR consolidates Prisma repository typing behind a generic TableActions protocol and updates callers to handle nullable database results explicitly.

• Replaces duplicated table protocols with one covariant generic interface.
• Adds missing-row handling across repository-backed proxy operations.
• Fixes memory update/delete authorization and concurrent-delete responses.
• Tightens team request field types and reduces static-analysis debt.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
litellm/repositories/prisma_protocols.py	Defines the shared generic Prisma table protocol, including nullable single-row mutation results.
litellm/repositories/base_repository.py	Types repository table access through the new generic protocol.
litellm/proxy/memory/memory_endpoints.py	Handles nullable memory rows and correctly returns 404 when deletion loses a race.
tests/test_litellm/proxy/memory/test_memory_endpoints.py	Covers team-owned memory authorization and the concurrent-delete missing-row response.
litellm/models/team.py	Tightens team list fields to string lists, making invalid payloads fail validation.

_{Reviews (4): Last reviewed commit: "fix(proxy): keep listing a keyless user'..." | Re-trigger Greptile}

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[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 7965cfd. Configure here.}