From 1618617ea9f2b758f7ff95b8eb226579f739e522 Mon Sep 17 00:00:00 2001
From: milan <milan@berri.ai>
Date: Fri, 31 Jul 2026 21:47:22 +0000
Subject: [PATCH 01/76] feat(ui): accept ssh clone urls when registering a
 skill

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../skills/_components/add_plugin_form.tsx    |  2 +-
 .../claude_code_plugins/helpers.test.ts       | 43 +++++++++++++++
 .../components/claude_code_plugins/helpers.ts | 52 +++++++++++++++++--
 3 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/skills/_components/add_plugin_form.tsx b/ui/litellm-dashboard/src/app/(dashboard)/skills/_components/add_plugin_form.tsx
index 04b8c88ae8d..226f9d19837 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/skills/_components/add_plugin_form.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/skills/_components/add_plugin_form.tsx
@@ -167,7 +167,7 @@ const AddPluginForm: React.FC<AddPluginFormProps> = ({ visible, onClose, accessT
           label="Repository URL"
           name="skillUrl"
           rules={[{ required: true, message: "Please enter a repository URL" }]}
-          tooltip="Paste an HTTPS git repository URL from GitHub, GitLab, Bitbucket, or a self-hosted host. E.g. github.com/org/repo, gitlab.com/org/repo, or github.com/org/repo/tree/main/my-skill"
+          tooltip="Paste an HTTPS git repository URL from GitHub, GitLab, Bitbucket, or a self-hosted host, e.g. github.com/org/repo or github.com/org/repo/tree/main/my-skill. For a private repository use its SSH clone URL (git@ghe.example.com:org/repo.git) so Claude Code clones it with your own SSH key"
         >
           <Input
             placeholder="https://github.com/org/repo or https://gitlab.com/org/repo"
diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
index c16eba24f7b..dc51dd19e78 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
@@ -159,6 +159,11 @@ describe("getSourceLink", () => {
   it("returns null when no repo or url", () => {
     expect(getSourceLink({ source: "github" })).toBeNull();
   });
+
+  it("returns null for an ssh clone url, which is not browsable", () => {
+    expect(getSourceLink({ source: "url", url: "git@ghe.example.com:org/repo.git" })).toBeNull();
+    expect(getSourceLink({ source: "url", url: "ssh://git@ghe.example.com/org/repo.git" })).toBeNull();
+  });
 });
 
 describe("getCategoryBadgeColor", () => {
@@ -455,6 +460,44 @@ describe("parseSkillSource", () => {
     expect(parseSkillSource("gitlab.com/org/repo", "a//b")).toBeNull();
   });
 
+  it("keeps an scp-style ssh clone url so private hosts authenticate with the user's key", () => {
+    expect(parseSkillSource("git@ghe.example.com:org/repo.git")?.parsed).toEqual({
+      source: "url",
+      url: "git@ghe.example.com:org/repo.git",
+    });
+    expect(parseSkillSource("git@ghe.example.com:org/repo")?.parsed).toEqual({
+      source: "url",
+      url: "git@ghe.example.com:org/repo.git",
+    });
+    expect(parseSkillSource("git@ghe.example.com:org/repo.git")?.suggestedName).toBe("repo");
+  });
+
+  it("normalizes an ssh:// clone url and keeps a custom port", () => {
+    expect(parseSkillSource("ssh://git@ghe.example.com/org/repo")?.parsed).toEqual({
+      source: "url",
+      url: "ssh://git@ghe.example.com/org/repo.git",
+    });
+    expect(parseSkillSource("ssh://git@ghe.example.com:2222/org/nested/repo.git")?.parsed).toEqual({
+      source: "url",
+      url: "ssh://git@ghe.example.com:2222/org/nested/repo.git",
+    });
+  });
+
+  it("combines an ssh clone url with an explicit subfolder", () => {
+    expect(parseSkillSource("git@ghe.example.com:org/repo.git", "plugins/my-skill")?.parsed).toEqual({
+      source: "git-subdir",
+      url: "git@ghe.example.com:org/repo.git",
+      path: "plugins/my-skill",
+    });
+    expect(parseSkillSource("git@ghe.example.com:org/repo.git", "../etc")).toBeNull();
+  });
+
+  it("rejects ssh-looking input without a host or repo path", () => {
+    expect(parseSkillSource("git@ghe.example.com:repo.git")).toBeNull();
+    expect(parseSkillSource("git@localhost:org/repo.git")).toBeNull();
+    expect(parseSkillSource("git@:org/repo.git")).toBeNull();
+  });
+
   it("returns null for empty and garbage input", () => {
     expect(parseSkillSource("")).toBeNull();
     expect(parseSkillSource("   ")).toBeNull();
diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
index a4e70f78af1..caf59c71b76 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
@@ -30,6 +30,10 @@ const IPV4_HOST_REGEX = /^\d{1,3}(\.\d{1,3}){3}$/;
 const GITHUB_ORG_REGEX = /^[A-Za-z0-9-]+$/;
 const GITHUB_REPO_REGEX = /^[A-Za-z0-9._-]+$/;
 
+const SSH_SCP_REGEX = /^([a-z0-9._-]+)@([a-z0-9.-]+\.[a-z]{2,}):([a-z0-9._-]+(?:\/[a-z0-9._-]+)+?)(?:\.git)?\/?$/i;
+const SSH_URL_REGEX =
+  /^ssh:\/\/([a-z0-9._-]+)@([a-z0-9.-]+\.[a-z]{2,})(:\d+)?\/([a-z0-9._-]+(?:\/[a-z0-9._-]+)+?)(?:\.git)?\/?$/i;
+
 const buildRepoUrl = (url: URL): string => `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`;
 
 const pathSegments = (url: URL): string[] => url.pathname.split("/").filter((seg) => seg !== "");
@@ -160,12 +164,54 @@ const parseRawGitSource = (url: URL, subPath?: string): SkillSourcePreview | nul
   };
 };
 
+const withGitSuffix = (path: string): string => `${path.replace(/\.git$/i, "")}.git`;
+
+const parseSshRepoUrl = (raw: string): string | null => {
+  const trimmed = raw.trim();
+  const sshUrl = SSH_URL_REGEX.exec(trimmed);
+  if (sshUrl) {
+    const [, user, host, port, path] = sshUrl;
+    return `ssh://${user}@${host}${port ?? ""}/${withGitSuffix(path)}`;
+  }
+  const scp = SSH_SCP_REGEX.exec(trimmed);
+  if (scp) {
+    const [, user, host, path] = scp;
+    return `${user}@${host}:${withGitSuffix(path)}`;
+  }
+  return null;
+};
+
+const parseSshSource = (cloneUrl: string, subPath?: string): SkillSourcePreview | null => {
+  const repoName = lastSegment(cloneUrl.replace(/\.git$/, "").replace(/^[^:]*:/, ""));
+  const normalized = normalizeSubPath(subPath ?? "");
+  if (normalized !== "") {
+    if (!SUBDIR_PATH_REGEX.test(normalized)) {
+      return null;
+    }
+    return {
+      parsed: { source: "git-subdir", url: cloneUrl, path: normalized },
+      label: `SSH subdir — ${cloneUrl} @ ${normalized}`,
+      suggestedName: toKebabCase(lastSegment(normalized)),
+    };
+  }
+  return {
+    parsed: { source: "url", url: cloneUrl },
+    label: `SSH repo — ${cloneUrl}`,
+    suggestedName: toKebabCase(repoName),
+  };
+};
+
 /**
  * Parse any git-accessible repository URL into a registerable skill source.
- * GitHub URLs keep their `github`/`git-subdir` shorthand; every other host is
- * treated as a raw repo URL, with an optional subfolder turning it into git-subdir.
+ * GitHub https URLs keep their `github`/`git-subdir` shorthand; ssh clone URLs stay ssh so a
+ * private host authenticates with the user's own key; every other host is treated as a raw repo
+ * URL, with an optional subfolder turning it into git-subdir.
  */
 export const parseSkillSource = (rawUrl: string, subPath?: string): SkillSourcePreview | null => {
+  const sshCloneUrl = parseSshRepoUrl(rawUrl);
+  if (sshCloneUrl) {
+    return parseSshSource(sshCloneUrl, subPath);
+  }
   const url = parseRepoUrl(rawUrl);
   if (!url) {
     return null;
@@ -268,7 +314,7 @@ export const getSourceLink = (source: PluginSource): string | null => {
     return `https://github.com/${source.repo}`;
   }
   if ((source.source === "url" || source.source === "git-subdir") && source.url) {
-    return source.url;
+    return source.url.startsWith("https://") ? source.url : null;
   }
   return null;
 };

From 66e1ea6090e5e97a5fa6c17aba376a1d57bc6e66 Mon Sep 17 00:00:00 2001
From: milan <milan@berri.ai>
Date: Fri, 31 Jul 2026 21:58:27 +0000
Subject: [PATCH 02/76] fix(ui): render non-browsable skill sources as text on
 the detail page

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../claude_code_plugins/skill_detail.test.tsx | 42 +++++++++++++++++++
 .../claude_code_plugins/skill_detail.tsx      | 21 +++++++---
 2 files changed, 57 insertions(+), 6 deletions(-)
 create mode 100644 ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx

diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
new file mode 100644
index 00000000000..98ae4a44ae6
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { Plugin } from "./types";
+
+import SkillDetail from "./skill_detail";
+
+const buildSkill = (source: Plugin["source"]): Plugin => ({
+  id: "plugin-id",
+  name: "my-skill",
+  source,
+  enabled: true,
+});
+
+describe("SkillDetail source", () => {
+  it("links a github source to the repository", () => {
+    render(<SkillDetail skill={buildSkill({ source: "github", repo: "org/repo" })} onBack={vi.fn()} />);
+    expect(screen.getByRole("link", { name: /github.com\/org\/repo/ })).toHaveAttribute(
+      "href",
+      "https://github.com/org/repo",
+    );
+  });
+
+  it("renders an ssh clone url as plain text instead of an unusable link", () => {
+    render(
+      <SkillDetail skill={buildSkill({ source: "url", url: "git@ghe.example.com:org/repo.git" })} onBack={vi.fn()} />,
+    );
+    expect(screen.getByText("git@ghe.example.com:org/repo.git")).toBeInTheDocument();
+    expect(screen.queryByRole("link", { name: /ghe.example.com/ })).not.toBeInTheDocument();
+  });
+
+  it("renders an ssh git-subdir source as plain text without a tree path", () => {
+    render(
+      <SkillDetail
+        skill={buildSkill({ source: "git-subdir", url: "git@ghe.example.com:org/repo.git", path: "plugins/x" })}
+        onBack={vi.fn()}
+      />,
+    );
+    expect(screen.getByText("git@ghe.example.com:org/repo.git")).toBeInTheDocument();
+    expect(screen.queryByRole("link", { name: /ghe.example.com/ })).not.toBeInTheDocument();
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx
index fe001641135..0f25b8ad515 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx
@@ -1,6 +1,6 @@
 import React, { useState } from "react";
 import { ArrowLeftOutlined, CopyOutlined, CheckOutlined, LinkOutlined } from "@ant-design/icons";
-import { buildMarketplaceSettingsSnippet, formatInstallCommand } from "./helpers";
+import { buildMarketplaceSettingsSnippet, formatInstallCommand, getSourceLink } from "./helpers";
 import { Plugin } from "./types";
 
 interface SkillDetailProps {
@@ -21,13 +21,15 @@ const SkillDetail: React.FC<SkillDetailProps> = ({ skill, onBack }) => {
     setTimeout(() => setCopiedKey(null), 2000);
   };
 
+  const sourceLink = getSourceLink(skill.source);
   const sourceUrl = (() => {
     const src = skill.source;
-    if (src.source === "github" && src.repo) return `https://github.com/${src.repo}`;
-    if (src.source === "git-subdir" && src.url) return src.path ? `${src.url}/tree/main/${src.path}` : src.url;
-    if (src.source === "url" && src.url) return src.url;
-    return null;
+    if (sourceLink && src.source === "git-subdir" && src.path) {
+      return `${sourceLink}/tree/main/${src.path}`;
+    }
+    return sourceLink;
   })();
+  const sourceText = skill.source.url ?? sourceUrl;
 
   const installCommand = formatInstallCommand(skill);
 
@@ -146,7 +148,7 @@ const SkillDetail: React.FC<SkillDetailProps> = ({ skill, onBack }) => {
               </span>
             </div>
 
-            {sourceUrl && (
+            {sourceUrl ? (
               <div style={{ marginBottom: 24 }}>
                 <div style={{ fontSize: 12, color: "#5f6368", marginBottom: 4 }}>Source</div>
                 <a
@@ -166,6 +168,13 @@ const SkillDetail: React.FC<SkillDetailProps> = ({ skill, onBack }) => {
                   <LinkOutlined style={{ fontSize: 11, flexShrink: 0 }} />
                 </a>
               </div>
+            ) : (
+              sourceText && (
+                <div style={{ marginBottom: 24 }}>
+                  <div style={{ fontSize: 12, color: "#5f6368", marginBottom: 4 }}>Source</div>
+                  <div style={{ fontSize: 13, color: "#3c4043", wordBreak: "break-all" }}>{sourceText}</div>
+                </div>
+              )
             )}
 
             {skill.keywords && skill.keywords.length > 0 && (

From 7d5c5d8873e55cb47b82a351046f2af31be06cf3 Mon Sep 17 00:00:00 2001
From: milan <milan@berri.ai>
Date: Fri, 31 Jul 2026 22:03:38 +0000
Subject: [PATCH 03/76] fix(ui): show the subfolder path for non-browsable
 skill sources

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../src/components/claude_code_plugins/skill_detail.test.tsx  | 2 +-
 .../src/components/claude_code_plugins/skill_detail.tsx       | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
index 98ae4a44ae6..2f600397a4b 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
@@ -36,7 +36,7 @@ describe("SkillDetail source", () => {
         onBack={vi.fn()}
       />,
     );
-    expect(screen.getByText("git@ghe.example.com:org/repo.git")).toBeInTheDocument();
+    expect(screen.getByText("git@ghe.example.com:org/repo.git @ plugins/x")).toBeInTheDocument();
     expect(screen.queryByRole("link", { name: /ghe.example.com/ })).not.toBeInTheDocument();
   });
 });
diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx
index 0f25b8ad515..ad98fdf232c 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.tsx
@@ -29,7 +29,9 @@ const SkillDetail: React.FC<SkillDetailProps> = ({ skill, onBack }) => {
     }
     return sourceLink;
   })();
-  const sourceText = skill.source.url ?? sourceUrl;
+  const sourceText = skill.source.url
+    ? `${skill.source.url}${skill.source.path ? ` @ ${skill.source.path}` : ""}`
+    : sourceUrl;
 
   const installCommand = formatInstallCommand(skill);
 

From 07bed091194a4b49a4440357da3f106bd7798e5d Mon Sep 17 00:00:00 2001
From: Elif Naz Ozdamar <83784925+elifozdamar@users.noreply.github.com>
Date: Sat, 12 Sep 2026 08:45:15 +0000
Subject: [PATCH 04/76] fix(proxy): release completed max-parallel slots
 promptly

---
 .../hooks/parallel_request_limiter_v3.py      |  78 +++++------
 .../hooks/test_parallel_request_limiter_v3.py | 121 ++++++++++++++++++
 2 files changed, 153 insertions(+), 46 deletions(-)

diff --git a/litellm/proxy/hooks/parallel_request_limiter_v3.py b/litellm/proxy/hooks/parallel_request_limiter_v3.py
index c398abff099..55638ab9071 100644
--- a/litellm/proxy/hooks/parallel_request_limiter_v3.py
+++ b/litellm/proxy/hooks/parallel_request_limiter_v3.py
@@ -522,6 +522,7 @@ class RequestRateLimiterStash:
     owner_litellm_call_id: str | None = None
     rate_limit_response: RateLimitResponse | None = None
     parallel_slot: ParallelSlotAcquisition | None = None
+    parallel_slot_release_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False, compare=False)
     reserved_tokens: int = 0
     reserved_model: str | None = None
     reserved_scopes: frozenset[tuple[str, str]] = field(default_factory=frozenset)
@@ -1609,6 +1610,20 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
             statuses.append(self._gauge_status(gauge, in_flight + 1, "OK"))
         return RateLimitResponse(overall_code="OK", statuses=statuses)
 
+    async def _release_stashed_parallel_slot(
+        self,
+        stash: RequestRateLimiterStash | None,
+        parent_otel_span: Span | None,
+    ) -> None:
+        if stash is None:
+            return
+        async with stash.parallel_slot_release_lock:
+            acquisition: Final = stash.parallel_slot
+            if acquisition is None:
+                return
+            await self._release_parallel_request_slots(acquisition, parent_otel_span)
+            stash.parallel_slot = None  # rebind-ok: marks this request's slot as released
+
     async def _release_parallel_request_slots(
         self,
         acquisition: ParallelSlotAcquisition,
@@ -3368,13 +3383,7 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
                     parent_otel_span=user_api_key_dict.parent_otel_span,
                 )
                 stash.reservation_released = True
-            acquisition: Final = stash.parallel_slot
-            if acquisition is not None:
-                await self._release_parallel_request_slots(
-                    acquisition=acquisition,
-                    parent_otel_span=user_api_key_dict.parent_otel_span,
-                )
-                stash.parallel_slot = None
+            await self._release_stashed_parallel_slot(stash, user_api_key_dict.parent_otel_span)
             self._handle_rate_limit_error(
                 response=io_response,
                 descriptors=descriptors,
@@ -3631,13 +3640,7 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
                 )
 
                 if tpm_response["overall_code"] == "OVER_LIMIT":
-                    acquisition: Final = stash.parallel_slot
-                    if acquisition is not None:
-                        await self._release_parallel_request_slots(
-                            acquisition=acquisition,
-                            parent_otel_span=user_api_key_dict.parent_otel_span,
-                        )
-                        stash.parallel_slot = None
+                    await self._release_stashed_parallel_slot(stash, user_api_key_dict.parent_otel_span)
                     self._handle_rate_limit_error(
                         response=tpm_response,
                         descriptors=descriptors,
@@ -4450,13 +4453,7 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
             verbose_proxy_logger.debug("INSIDE parallel request limiter ASYNC SUCCESS LOGGING")
 
             stash: Final = get_request_stash_for_call(_call_id_from_callback_kwargs(kwargs))
-            acquisition: Final = stash.parallel_slot if stash is not None else None
-            if stash is not None and acquisition is not None:
-                await self._release_parallel_request_slots(
-                    acquisition=acquisition,
-                    parent_otel_span=litellm_parent_otel_span,
-                )
-                stash.parallel_slot = None
+            await self._release_stashed_parallel_slot(stash, litellm_parent_otel_span)
 
             pipeline_operations: Final = self._build_success_event_pipeline_operations(
                 kwargs=kwargs,
@@ -4576,13 +4573,7 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
             pipeline_operations: Final[list[RedisPipelineIncrementOperation]] = []
 
             stash: Final = get_request_stash_for_call(_call_id_from_callback_kwargs(kwargs))
-            acquisition: Final = stash.parallel_slot if stash is not None else None
-            if stash is not None and acquisition is not None:
-                await self._release_parallel_request_slots(
-                    acquisition=acquisition,
-                    parent_otel_span=litellm_parent_otel_span,
-                )
-                stash.parallel_slot = None
+            await self._release_stashed_parallel_slot(stash, litellm_parent_otel_span)
 
             # Skip the reservation refund if async_post_call_failure_hook
             # already released it (proxy-level rejection that also bubbles up
@@ -4690,23 +4681,23 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
         object's current max_parallel_requests configuration, which can
         change mid-request) decides whether there is anything to release.
         """
-        stash: Final = get_request_stash()
-        if stash is None or stash.parallel_slot is None:
-            return
-
-        await self._release_parallel_request_slots(
-            acquisition=stash.parallel_slot,
-            parent_otel_span=None,
-        )
-        stash.parallel_slot = None
+        await self._release_stashed_parallel_slot(get_request_stash(), None)
 
     async def async_post_call_success_hook(self, data: dict, user_api_key_dict: UserAPIKeyAuth, response):
         """
-        Post-call hook to update rate limit headers in the response.
+        Release completed-request slots and update rate limit headers in the response.
         """
         try:
-            stash: Final = get_request_stash()
-            litellm_proxy_rate_limit_response: Final = stash.rate_limit_response if stash is not None else None
+            slot_stash: Final = get_request_stash_for_call(_call_id_from_callback_kwargs(data))
+            await self._release_stashed_parallel_slot(slot_stash, user_api_key_dict.parent_otel_span)
+        except Exception as e:
+            verbose_proxy_logger.exception("Error releasing parallel request slot in post-call hook: %s", e)
+
+        try:
+            header_stash: Final = get_request_stash()
+            litellm_proxy_rate_limit_response: Final = (
+                header_stash.rate_limit_response if header_stash is not None else None
+            )
 
             if litellm_proxy_rate_limit_response is not None and response_has_hidden_params(response):
                 additional_headers: Final = ensure_response_additional_headers(response)
@@ -4774,12 +4765,7 @@ class _PROXY_MaxParallelRequestsHandler_v3(CustomLogger):
             stash: Final = get_request_stash()
             if stash is None:
                 return
-            if stash.parallel_slot is not None:
-                await self._release_parallel_request_slots(
-                    acquisition=stash.parallel_slot,
-                    parent_otel_span=user_api_key_dict.parent_otel_span,
-                )
-                stash.parallel_slot = None
+            await self._release_stashed_parallel_slot(stash, user_api_key_dict.parent_otel_span)
 
             if stash.batch_enqueued_reservation is not None:
                 await self.batch_enqueued_token_store.refund(
diff --git a/tests/test_litellm/proxy/hooks/test_parallel_request_limiter_v3.py b/tests/test_litellm/proxy/hooks/test_parallel_request_limiter_v3.py
index 10c0bb88a82..86f0d76e063 100644
--- a/tests/test_litellm/proxy/hooks/test_parallel_request_limiter_v3.py
+++ b/tests/test_litellm/proxy/hooks/test_parallel_request_limiter_v3.py
@@ -7,6 +7,7 @@ import logging
 import os
 import sys
 import time
+from collections.abc import Sequence
 from contextlib import contextmanager
 from datetime import datetime, timedelta
 from typing import Any, Dict, List, Optional
@@ -32,6 +33,7 @@ from litellm.proxy.hooks.parallel_request_limiter_v3 import (
 )
 from litellm.proxy.utils import InternalUsageCache, ProxyLogging, hash_token
 from litellm.types.caching import RedisPipelineIncrementOperation
+from litellm.types.llms.openai import ResponsesAPIResponse
 from litellm.types.utils import (
     EmbeddingResponse,
     ModelResponse,
@@ -4054,6 +4056,125 @@ async def _seed_max_parallel_requests_slots(
     )
 
 
+@pytest.mark.asyncio
+async def test_completed_responses_post_call_releases_parallel_slot() -> None:
+    api_key = hash_token("sk-responses-post-call")
+    local_cache = DualCache()
+    handler = _PROXY_MaxParallelRequestsHandler(
+        internal_usage_cache=InternalUsageCache(local_cache)
+    )
+    user_api_key_dict = UserAPIKeyAuth(api_key=api_key, max_parallel_requests=1)
+    data = {
+        "model": "gpt-4o-mini",
+        "input": "hello",
+        "litellm_call_id": "responses-owner",
+    }
+    parallel_key = f"{{api_key:{api_key}}}:max_parallel_requests"
+
+    await handler.async_pre_call_hook(
+        user_api_key_dict=user_api_key_dict,
+        cache=local_cache,
+        data=data,
+        call_type="aresponses",
+    )
+    assert handler._gauge_in_flight_from_cache_value(
+        await local_cache.async_get_cache(key=parallel_key)
+    ) == 1
+
+    await handler.async_post_call_success_hook(
+        data=data,
+        user_api_key_dict=user_api_key_dict,
+        response=ResponsesAPIResponse(
+            id="resp_parallel_slot",
+            created_at=0,
+            model="gpt-4o-mini",
+            object="response",
+            output=[],
+            status="completed",
+        ),
+    )
+    assert handler._gauge_in_flight_from_cache_value(
+        await local_cache.async_get_cache(key=parallel_key)
+    ) == 0
+
+    await handler.async_log_success_event(
+        kwargs={"litellm_call_id": data["litellm_call_id"]},
+        response_obj=None,
+        start_time=None,
+        end_time=None,
+    )
+    assert handler._gauge_in_flight_from_cache_value(
+        await local_cache.async_get_cache(key=parallel_key)
+    ) == 0
+
+
+@pytest.mark.asyncio
+async def test_concurrent_success_callbacks_release_parallel_slot_once_when_redis_fails() -> None:
+    from unittest.mock import AsyncMock
+
+    api_key = hash_token("sk-concurrent-release")
+    local_cache = DualCache()
+    handler = _PROXY_MaxParallelRequestsHandler(
+        internal_usage_cache=InternalUsageCache(local_cache)
+    )
+    user_api_key_dict = UserAPIKeyAuth(api_key=api_key, max_parallel_requests=2)
+    call_id = "concurrent-release-owner"
+    parallel_key = f"{{api_key:{api_key}}}:max_parallel_requests"
+    release_started = asyncio.Event()
+    allow_redis_failure = asyncio.Event()
+
+    async def failing_release(
+        keys: Sequence[str], args: Sequence[object]
+    ) -> list[int]:
+        release_started.set()
+        await allow_redis_failure.wait()
+        raise ConnectionError("redis unavailable")
+
+    release_script = AsyncMock(side_effect=failing_release)
+    handler.parallel_release_script = release_script
+    await local_cache.async_set_cache(key=parallel_key, value=2, local_only=True)
+    stash = get_or_create_request_stash()
+    stash.owner_litellm_call_id = call_id
+    stash.parallel_slot = ParallelSlotAcquisition(
+        slot_id="slot-concurrent-release",
+        counter_keys=[parallel_key],
+    )
+    data = {"litellm_call_id": call_id}
+
+    post_call_task = asyncio.create_task(
+        handler.async_post_call_success_hook(
+            data=data,
+            user_api_key_dict=user_api_key_dict,
+            response=ResponsesAPIResponse(
+                id="resp_concurrent_release",
+                created_at=0,
+                model="gpt-4o-mini",
+                object="response",
+                output=[],
+                status="completed",
+            ),
+        )
+    )
+    await asyncio.wait_for(release_started.wait(), timeout=5)
+    logging_task = asyncio.create_task(
+        handler.async_log_success_event(
+            kwargs=data,
+            response_obj=None,
+            start_time=None,
+            end_time=None,
+        )
+    )
+    allow_redis_failure.set()
+    await asyncio.wait_for(
+        asyncio.gather(post_call_task, logging_task),
+        timeout=5,
+    )
+
+    assert release_script.await_count == 1
+    assert await local_cache.async_get_cache(key=parallel_key) == 1
+    assert stash.parallel_slot is None
+
+
 async def _build_seeded_limiter():
     """Build a v3 limiter whose api-key slot registry already holds the pre-call slot."""
     api_key = hash_token("sk-disconnect")

From 6c8b9a7b0554482974fb3043875f550096e36de9 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 22:12:01 +0000
Subject: [PATCH 05/76] feat(keys): filter /key/list by active, expired,
 revoked or deleted status and serve deleted keys from /key/info

Persist and expose the lifecycle of API keys so spend, audit and FinOps
workflows can still resolve a key after it is revoked, expires or is
deleted.

/key/list?status= now accepts active, expired and revoked next to the
existing deleted value. revoked means blocked=true, expired means not
blocked with a past expiry, active is the rest, so the three values
partition the live key table. deleted keeps reading the
LiteLLM_DeletedVerificationToken archive.

/key/info falls back to that archive when the key is no longer in the
live table, running the same owner/team/org authorization check, and
every response now carries a derived status field. The hashed token is
still stripped.

The Virtual Keys page gets a Status filter (URL-persisted) and a Deleted
badge that shows when and by whom the key was deleted.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../key_management_endpoints.py               | 108 +++++++--
 .../test_key_management_endpoints.py          | 218 ++++++++++++++++++
 .../VirtualKeysPage/VirtualKeysTable.test.tsx |  54 +++++
 .../VirtualKeysPage/VirtualKeysTable.tsx      |  52 ++++-
 .../VirtualKeysPage/keyTableColumns.tsx       |   7 +
 .../components/key_team_helpers/key_list.tsx  |   2 +
 ui/litellm-dashboard/src/lib/http/schema.d.ts |  11 +-
 7 files changed, 422 insertions(+), 30 deletions(-)

diff --git a/litellm/proxy/management_endpoints/key_management_endpoints.py b/litellm/proxy/management_endpoints/key_management_endpoints.py
index ee8ae66ea11..7a363729541 100644
--- a/litellm/proxy/management_endpoints/key_management_endpoints.py
+++ b/litellm/proxy/management_endpoints/key_management_endpoints.py
@@ -4166,7 +4166,10 @@ async def info_key_fn(
 
     Returns:
     - key: str - The key that was looked up, echoed back as it was passed in
-    - info: dict - The key's row, minus the hashed token
+    - info: dict - The key's row, minus the hashed token. Deleted keys are served from the
+      LiteLLM_DeletedVerificationToken archive and carry deleted_at / deleted_by
+        - status: "active" | "expired" | "revoked" | "deleted" - Derived from blocked, expires and
+          whether the row came from the archive
         - key_alias: str | None - User-friendly key alias
         - spend: float - Amount spent by the key. When budget_duration is set this covers only the
           current budget window, not the key's lifetime
@@ -4220,10 +4223,15 @@ async def info_key_fn(
         hashed_key: str | None = key
         if key is not None:
             hashed_key = _hash_token_if_needed(token=key)
-        key_info = await _prisma_table(VerificationTokenRepository(prisma_client)).find_unique(
+        live_key_info: Final = await _prisma_table(VerificationTokenRepository(prisma_client)).find_unique(
             where={"token": hashed_key},
             include={"litellm_budget_table": True},
         )
+        key_info: Final = (
+            live_key_info
+            if live_key_info is not None
+            else await _find_deleted_key_info(prisma_client=prisma_client, hashed_key=hashed_key)
+        )
         if key_info is None:
             raise ProxyException(
                 message="Key not found in database",
@@ -4231,7 +4239,6 @@ async def info_key_fn(
                 param="key",
                 code=status.HTTP_404_NOT_FOUND,
             )
-
         if (
             await _can_user_query_key_info(
                 user_api_key_dict=user_api_key_dict,
@@ -4245,38 +4252,46 @@ async def info_key_fn(
                 detail=f"You are not allowed to access this key's info. Your role={user_api_key_dict.user_role}",
             )
         ## REMOVE HASHED TOKEN INFO BEFORE RETURNING ##
-        try:
-            key_info = key_info.model_dump()
-        except Exception:
-            # if using pydantic v1
-            key_info = key_info.dict()  # pyright: ignore[reportDeprecated]  # deliberate pydantic v1 fallback
-        key_token_hash: Final[str | None] = key_info.pop("token")
+        key_info_dict: Final = key_info.model_dump()
+        key_token_hash: Final[str | None] = key_info_dict.pop("token")
+        key_info_dict["status"] = (
+            "deleted" if live_key_info is None else _derive_key_status(key_info_dict, now=datetime.now(timezone.utc))
+        )
 
-        model_max_budget = key_info.get("model_max_budget") or {}
-        budget_table: Final = key_info.get("litellm_budget_table") or {}
+        model_max_budget = key_info_dict.get("model_max_budget") or {}
+        budget_table: Final = key_info_dict.get("litellm_budget_table") or {}
         if not model_max_budget and isinstance(budget_table, dict):
             model_max_budget = budget_table.get("model_max_budget") or {}
         if model_max_budget and key_token_hash:
-            key_info["model_max_budget_usage"] = await _build_model_max_budget_usage(
+            key_info_dict["model_max_budget_usage"] = await _build_model_max_budget_usage(
                 api_key_hash=key_token_hash,
                 model_max_budget=model_max_budget,
                 user_api_key_cache=model_max_budget_limiter.dual_cache,
             )
         budget_limits_usage: Final = await _build_budget_limits_usage(
-            budget_limits=key_info.get("budget_limits"),
+            budget_limits=key_info_dict.get("budget_limits"),
             api_key_hash=key_token_hash,
         )
         if budget_limits_usage is not None:
-            key_info["budget_limits_usage"] = budget_limits_usage
+            key_info_dict["budget_limits_usage"] = budget_limits_usage
 
-        # Attach object_permission if object_permission_id is set
-        key_info = await attach_object_permission_to_dict(key_info, prisma_client)
-
-        return {"key": key, "info": key_info}
+        return {"key": key, "info": await attach_object_permission_to_dict(key_info_dict, prisma_client)}
     except Exception as e:
         raise handle_exception_on_proxy(e)
 
 
+async def _find_deleted_key_info(
+    prisma_client: PrismaClient, hashed_key: str | None
+) -> LiteLLM_DeletedVerificationToken | None:
+    archived_row: Final = await _deleted_verification_token_table(prisma_client).find_first(
+        where={"token": hashed_key},
+        order={"deleted_at": "desc"},
+    )
+    if archived_row is None:
+        return None
+    return LiteLLM_DeletedVerificationToken.model_validate(archived_row.model_dump())
+
+
 def _check_model_access_group(models: list[str] | None, llm_router: Router | None, premium_user: bool) -> Literal[True]:
     """
     if is_model_access_group is True + is_wildcard_route is True, check if user is a premium user
@@ -6216,6 +6231,25 @@ async def get_member_team_ids(
 
 VALID_EXPIRES_FILTER_VALUES: Final = frozenset({"active", "expired"})
 
+KeyStatus = Literal["active", "expired", "revoked", "deleted"]
+VALID_STATUS_FILTER_VALUES: Final[frozenset[KeyStatus]] = frozenset({"active", "expired", "revoked", "deleted"})
+
+
+class _KeyStatusSource(BaseModel):
+    blocked: bool | None = None
+    expires: datetime | None = None
+
+
+def _derive_key_status(row: Mapping[str, object], now: datetime) -> KeyStatus:
+    """Status of a live key row; mirrors the partition `_build_status_where_clause` applies at query time."""
+    source: Final = _KeyStatusSource.model_validate(row)
+    if source.blocked is True:
+        return "revoked"
+    if source.expires is None:
+        return "active"
+    expires_utc: Final = source.expires if source.expires.tzinfo else source.expires.replace(tzinfo=timezone.utc)
+    return "expired" if expires_utc < now else "active"
+
 
 @router.get(
     "/key/list",
@@ -6252,7 +6286,10 @@ async def list_keys(
     ),
     sort_order: str = Query(default="desc", description="Sort order ('asc' or 'desc')"),
     expand: list[str] | None = Query(None, description="Expand related objects (e.g. 'user')"),
-    status: str | None = Query(None, description="Filter by status (e.g. 'deleted')"),
+    status: str | None = Query(
+        None,
+        description="Filter by status: 'active' (not blocked, not expired), 'expired' (not blocked, past expiry), 'revoked' (blocked) or 'deleted' (archived keys). Omit to return live keys regardless of status.",
+    ),
     project_id: str | None = Query(None, description="Filter keys by project ID"),
     access_group_id: str | None = Query(None, description="Filter keys by access group ID"),
     agent_id: str | None = Query(None, description="Filter keys by agent ID"),
@@ -6270,7 +6307,9 @@ async def list_keys(
 
     Parameters:
         expand: Optional[List[str]] - Expand related objects (e.g. 'user' to include user information)
-        status: Optional[str] - Filter by status. Currently supports "deleted" to query deleted keys.
+        status: Optional[str] - Filter by status: "active", "expired", "revoked" (blocked) or "deleted".
+        "deleted" reads the LiteLLM_DeletedVerificationToken archive; the other values partition the
+        live key table, so every live key matches exactly one of them.
 
     Returns:
         {
@@ -6292,11 +6331,10 @@ async def list_keys(
             verbose_proxy_logger.error("Database not connected")
             raise Exception("Database not connected")
 
-        # Validate status parameter
-        if status is not None and status != "deleted":
+        if status is not None and status not in VALID_STATUS_FILTER_VALUES:
             raise HTTPException(
                 status_code=400,
-                detail={"error": "Invalid status value. Currently only 'deleted' is supported."},
+                detail={"error": "Invalid status value. Supported: 'active', 'expired', 'revoked', 'deleted'."},
             )
 
         if isinstance(expires, str) and expires not in VALID_EXPIRES_FILTER_VALUES:
@@ -6608,6 +6646,23 @@ def _build_expires_where_clause(expires_filter: str, now: datetime) -> dict[str,
     return {"OR": [{"expires": None}, {"expires": {"gte": now}}]}
 
 
+def _not_blocked_where_clause() -> dict[str, object]:
+    return {"OR": [{"blocked": None}, {"blocked": False}]}
+
+
+def _build_status_where_clause(status_filter: str | None, now: datetime) -> dict[str, object] | None:
+    """Live-table clause for a status filter; None when the status needs no clause (deleted rows live elsewhere)."""
+    match status_filter:
+        case "revoked":
+            return {"blocked": True}
+        case "expired":
+            return {"AND": [_not_blocked_where_clause(), _build_expires_where_clause("expired", now)]}
+        case "active":
+            return {"AND": [_not_blocked_where_clause(), _build_expires_where_clause("active", now)]}
+        case _:
+            return None
+
+
 def _build_key_search_where(search: str) -> KeySearchWhere:
     search_where: Final[KeySearchWhere] = {
         "OR": (
@@ -6635,6 +6690,7 @@ def _build_key_filter_conditions(
     use_key_alias_substring_matching: bool = False,
     expires_filter: str | None = None,
     search: str | None = None,
+    status_filter: str | None = None,
 ) -> Mapping[str, object]:
     """Build filter conditions for key listing.
 
@@ -6724,6 +6780,8 @@ def _build_key_filter_conditions(
 
     # Apply team_id, project_id and access_group_id as global AND filters so they
     # narrow results across all visibility conditions (own keys, team keys, etc.)
+    now: Final = datetime.now(timezone.utc)
+    status_where: Final = _build_status_where_clause(status_filter, now)
     global_filters: Final[tuple[Mapping[str, object], ...]] = (
         *(
             (
@@ -6741,10 +6799,11 @@ def _build_key_filter_conditions(
         *(({"access_group_ids": {"hasSome": [access_group_id]}},) if access_group_id else ()),
         *(({"agent_id": agent_id},) if agent_id and isinstance(agent_id, str) else ()),
         *(
-            (_build_expires_where_clause(expires_filter, datetime.now(timezone.utc)),)
+            (_build_expires_where_clause(expires_filter, now),)
             if expires_filter is not None and expires_filter in VALID_EXPIRES_FILTER_VALUES
             else ()
         ),
+        *((status_where,) if status_where is not None else ()),
     )
     combined_where: Final[Mapping[str, object]] = {"AND": [where, *global_filters]} if global_filters else where
     verbose_proxy_logger.debug("Filter conditions: %s", combined_where)
@@ -6817,6 +6876,7 @@ async def _list_key_helper(
         use_key_alias_substring_matching=use_key_alias_substring_matching,
         expires_filter=expires_filter,
         search=search,
+        status_filter=status,
     )
 
     # Calculate skip for pagination
diff --git a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
index 63055872aa1..852b8632846 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
@@ -6017,6 +6017,224 @@ async def test_list_keys_with_invalid_status():
         assert "deleted" in str(exc_info.value.message)
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status_filter", ["active", "expired", "revoked"])
+async def test_list_keys_accepts_live_status_filters(monkeypatch, status_filter):
+    """LIT-1650: /key/list used to 400 on every status but "deleted"; the live statuses reach the helper."""
+    from unittest.mock import Mock
+
+    from litellm.proxy.management_endpoints import key_management_endpoints
+
+    helper = AsyncMock(return_value={"keys": [], "total_count": 0, "current_page": 1, "total_pages": 0})
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", AsyncMock())
+    monkeypatch.setattr(key_management_endpoints, "_list_key_helper", helper)
+    await key_management_endpoints.list_keys(
+        request=Mock(),
+        user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN),
+        status=status_filter,
+    )
+
+    assert helper.await_args is not None
+    assert helper.await_args.kwargs["status"] == status_filter
+
+
+def _status_filter_where(status_filter: str | None) -> Mapping[str, object]:
+    from litellm.proxy.management_endpoints.key_management_endpoints import _build_key_filter_conditions
+
+    return _build_key_filter_conditions(
+        user_id=None,
+        team_id=None,
+        organization_id=None,
+        key_alias=None,
+        key_hash=None,
+        exclude_team_id=None,
+        admin_team_ids=None,
+        status_filter=status_filter,
+    )
+
+
+def test_build_key_filter_conditions_status_filter_partitions_live_keys():
+    """LIT-1650: active, expired and revoked are disjoint predicates over blocked + expires on the live table."""
+    not_blocked = {"OR": [{"blocked": None}, {"blocked": False}]}
+
+    revoked_where = _status_filter_where("revoked")
+    assert {"blocked": True} in revoked_where["AND"]
+
+    expired_clause = next(clause for clause in _status_filter_where("expired")["AND"] if "AND" in clause)
+    assert expired_clause["AND"][0] == not_blocked
+    assert expired_clause["AND"][1]["AND"][0] == {"expires": {"not": None}}
+    assert "lt" in expired_clause["AND"][1]["AND"][1]["expires"]
+
+    active_clause = next(clause for clause in _status_filter_where("active")["AND"] if "AND" in clause)
+    assert active_clause["AND"][0] == not_blocked
+    assert active_clause["AND"][1]["OR"][0] == {"expires": None}
+    assert "gte" in active_clause["AND"][1]["OR"][1]["expires"]
+
+
+def test_build_key_filter_conditions_deleted_status_adds_no_live_clause():
+    """Deleted rows live in the archive table, so the status must not narrow the live-table query."""
+    assert _status_filter_where("deleted") == _status_filter_where(None)
+
+
+@pytest.mark.asyncio
+async def test_list_key_helper_revoked_status_filters_live_table_on_blocked():
+    """LIT-1650: status="revoked" stays on the live table and narrows it to blocked keys."""
+    mock_prisma_client = AsyncMock()
+    mock_find_many = AsyncMock(return_value=[])
+    mock_prisma_client.db.litellm_verificationtoken.find_many = mock_find_many
+    mock_prisma_client.db.litellm_verificationtoken.count = AsyncMock(return_value=0)
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_many = AsyncMock(return_value=[])
+
+    await _list_key_helper(
+        prisma_client=mock_prisma_client,
+        page=1,
+        size=50,
+        user_id=None,
+        team_id=None,
+        organization_id=None,
+        key_alias=None,
+        key_hash=None,
+        exclude_team_id=None,
+        return_full_object=True,
+        admin_team_ids=None,
+        include_created_by_keys=False,
+        status="revoked",
+    )
+
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_many.assert_not_called()
+    where = mock_find_many.call_args.kwargs["where"]
+    assert {"blocked": True} in where["AND"]
+
+
+def _archived_key_row(token: str, user_id: str) -> MagicMock:
+    row = MagicMock()
+    row.model_dump.return_value = {
+        "id": "archive-row-1",
+        "token": token,
+        "key_alias": "finops-2024",
+        "user_id": user_id,
+        "team_id": None,
+        "blocked": None,
+        "deleted_at": datetime(2024, 11, 15, 10, 0, tzinfo=timezone.utc),
+        "deleted_by": "admin-1",
+    }
+    return row
+
+
+@pytest.mark.asyncio
+async def test_info_key_fn_serves_deleted_key_from_archive(monkeypatch):
+    """LIT-1650: /key/info falls back to LiteLLM_DeletedVerificationToken and reports status="deleted"."""
+    from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
+
+    hashed = "hashed_deleted_token"
+    mock_prisma_client = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+    mock_prisma_client.db.litellm_verificationtoken.find_unique = AsyncMock(return_value=None)
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_first = AsyncMock(
+        return_value=_archived_key_row(hashed, "user-x")
+    )
+
+    result = await info_key_fn(
+        key=hashed,
+        user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, api_key="sk-admin"),
+    )
+
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_first.assert_awaited_once()
+    assert mock_prisma_client.db.litellm_deletedverificationtoken.find_first.await_args.kwargs["where"] == {
+        "token": hashed
+    }
+    info = result["info"]
+    assert info["status"] == "deleted"
+    assert info["key_alias"] == "finops-2024"
+    assert info["deleted_by"] == "admin-1"
+    assert info["deleted_at"] is not None
+    assert "token" not in info
+
+
+@pytest.mark.asyncio
+async def test_info_key_fn_archived_key_keeps_owner_authorization(monkeypatch):
+    """An archived key is still scoped: a different internal user gets 403, the owner gets the record."""
+    from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
+
+    hashed = "hashed_deleted_token"
+    mock_prisma_client = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+    mock_prisma_client.db.litellm_verificationtoken.find_unique = AsyncMock(return_value=None)
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_first = AsyncMock(
+        return_value=_archived_key_row(hashed, "owner-1")
+    )
+
+    with pytest.raises(ProxyException) as exc_info:
+        await info_key_fn(
+            key=hashed,
+            user_api_key_dict=UserAPIKeyAuth(
+                user_role=LitellmUserRoles.INTERNAL_USER, user_id="someone-else", api_key="sk-other"
+            ),
+        )
+    assert exc_info.value.code == "403"
+
+    owner_result = await info_key_fn(
+        key=hashed,
+        user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER, user_id="owner-1", api_key="sk-own"),
+    )
+    assert owner_result["info"]["status"] == "deleted"
+
+
+@pytest.mark.asyncio
+async def test_info_key_fn_unknown_key_still_404s(monkeypatch):
+    from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
+
+    mock_prisma_client = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+    mock_prisma_client.db.litellm_verificationtoken.find_unique = AsyncMock(return_value=None)
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_first = AsyncMock(return_value=None)
+
+    with pytest.raises(ProxyException) as exc_info:
+        await info_key_fn(
+            key="hashed_missing",
+            user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, api_key="sk-admin"),
+        )
+    assert exc_info.value.code == "404"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("blocked", "expires", "expected_status"),
+    [
+        (True, None, "revoked"),
+        (True, "2020-01-01T00:00:00Z", "revoked"),
+        (False, "2020-01-01T00:00:00Z", "expired"),
+        (None, datetime(2020, 1, 1, tzinfo=timezone.utc), "expired"),
+        (False, None, "active"),
+        (None, "2999-01-01T00:00:00Z", "active"),
+    ],
+)
+async def test_info_key_fn_reports_live_key_status(monkeypatch, blocked, expires, expected_status):
+    """LIT-1650: live keys carry the same status vocabulary /key/list filters on."""
+    from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
+
+    mock_prisma_client = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+    live_row = MagicMock(spec=LiteLLM_VerificationToken)
+    live_row.model_dump.return_value = {
+        "token": "hashed_live",
+        "user_id": "user-x",
+        "team_id": None,
+        "object_permission_id": None,
+        "blocked": blocked,
+        "expires": expires,
+    }
+    mock_prisma_client.db.litellm_verificationtoken.find_unique = AsyncMock(return_value=live_row)
+
+    result = await info_key_fn(
+        key="hashed_live",
+        user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, api_key="sk-admin"),
+    )
+
+    assert result["info"]["status"] == expected_status
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_first.assert_not_called()
+
+
 @pytest.mark.asyncio
 async def test_list_keys_non_admin_user_id_auto_set():
     """
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
index 617b9209a41..fa09b2c1b5b 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
@@ -638,6 +638,23 @@ describe("server-side filtering – the LIT-4080 regression guard", () => {
     });
   });
 
+  it("threads the Status drawer filter into the useKeys query and the URL", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    renderWithProviders(<VirtualKeysTable />, { onUrlUpdate });
+
+    openFilters();
+    const user = userEvent.setup();
+    await chooseSelectOption(user, await screen.findByRole("combobox", { name: "Status" }), "Revoked (blocked)");
+    fireEvent.click(screen.getByTestId("filter-drawer-apply"));
+
+    await waitFor(() => {
+      expect(mockUseKeys).toHaveBeenLastCalledWith(1, 50, expect.objectContaining({ status: "revoked" }));
+    });
+    await waitFor(() => {
+      expect(lastSearchParam(onUrlUpdate, "filter_status")).toBe("revoked");
+    });
+  });
+
   it("sends the search box as the combined alias-or-ID search rather than the key-alias filter", async () => {
     renderWithProviders(<VirtualKeysTable />);
 
@@ -745,6 +762,25 @@ describe("Status column reflects blocked / expiry / scim metadata", () => {
     expect(screen.queryByText(/Blocked by SCIM/i)).not.toBeInTheDocument();
   });
 
+  it("renders Deleted for an archived key, even when the archived row was also blocked", async () => {
+    mockUseKeys.mockReturnValue(
+      keysResult([
+        { ...mockKey, blocked: true, metadata: {}, deleted_at: "2024-11-15T10:00:00Z", deleted_by: "admin-1" },
+      ]),
+    );
+
+    renderWithProviders(<VirtualKeysTable />);
+
+    const tag = await screen.findByTestId(`key-status-${mockKey.token_id}`);
+    expect(tag).toHaveTextContent("Deleted");
+
+    const user = userEvent.setup();
+    await user.hover(tag);
+    await waitFor(() => {
+      expect(screen.getByText(/by admin-1/)).toBeInTheDocument();
+    });
+  });
+
   it("marks a SCIM-blocked key with the SCIM tooltip reason", async () => {
     mockUseKeys.mockReturnValue(keysResult([{ ...mockKey, blocked: true, metadata: { scim_blocked: true } }]));
 
@@ -790,6 +826,24 @@ describe("table state lives in the URL so it survives leaving and returning to t
     expect(screen.getByTestId("filter-chip-team_id")).toHaveTextContent("Test Team");
   });
 
+  it("restores the status filter from the URL and sends it to /key/list", async () => {
+    renderWithProviders(<VirtualKeysTable />, { searchParams: { filter_status: "deleted" } });
+
+    await waitFor(() => {
+      expect(mockUseKeys).toHaveBeenLastCalledWith(1, 50, expect.objectContaining({ status: "deleted" }));
+    });
+    expect(screen.getByTestId("filter-chip-status")).toHaveTextContent("Deleted");
+  });
+
+  it("ignores a hand-edited status the backend would reject instead of 400ing the page", async () => {
+    renderWithProviders(<VirtualKeysTable />, { searchParams: { filter_status: "bogus" } });
+
+    await waitFor(() => {
+      expect(mockUseKeys).toHaveBeenLastCalledWith(1, 50, expect.objectContaining({ status: undefined }));
+    });
+    expect(screen.queryByTestId("filter-chip-status")).not.toBeInTheDocument();
+  });
+
   it("writes the search term to the URL", async () => {
     const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
     renderWithProviders(<VirtualKeysTable />, { onUrlUpdate });
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx
index 907ee28bd05..1f52bdd7335 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx
@@ -14,6 +14,7 @@ import {
 import { SearchSelect } from "@/components/shared/SearchSelect";
 import { PageHeader } from "@/components/shared/PageHeader";
 import { Input } from "@/components/ui/input";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { useDebouncedValue } from "@tanstack/react-pacer/debouncer";
 import { ColumnFiltersState, functionalUpdate, OnChangeFn, PaginationState, SortingState } from "@tanstack/react-table";
 import { KeyRound } from "lucide-react";
@@ -28,7 +29,7 @@ interface VirtualKeysTableProps {
   headerActions?: React.ReactNode;
 }
 
-const FILTER_COLUMNS = ["team_id", "org_id", "user_id", "key_hash"] as const;
+const FILTER_COLUMNS = ["team_id", "org_id", "user_id", "key_hash", "status"] as const;
 type FilterColumn = (typeof FILTER_COLUMNS)[number];
 
 const FILTER_LABELS: Record<FilterColumn, string> = {
@@ -36,8 +37,28 @@ const FILTER_LABELS: Record<FilterColumn, string> = {
   org_id: "Organization",
   user_id: "User ID",
   key_hash: "Key ID",
+  status: "Status",
 };
 
+const KEY_STATUS_VALUES = ["active", "expired", "revoked", "deleted"] as const;
+type KeyStatusFilter = (typeof KEY_STATUS_VALUES)[number];
+const ALL_STATUSES = "all";
+
+const KEY_STATUS_LABELS: Record<KeyStatusFilter, string> = {
+  active: "Active",
+  expired: "Expired",
+  revoked: "Revoked (blocked)",
+  deleted: "Deleted",
+};
+
+const STATUS_FILTER_ITEMS = [
+  { value: ALL_STATUSES, label: "All statuses" },
+  ...KEY_STATUS_VALUES.map((value) => ({ value, label: KEY_STATUS_LABELS[value] })),
+];
+
+const isKeyStatusFilter = (value: string): value is KeyStatusFilter =>
+  (KEY_STATUS_VALUES as readonly string[]).includes(value);
+
 const DEFAULT_SORT_BY = "created_at";
 const DEFAULT_SORT_ORDER = "desc";
 const DEFAULT_PAGE_SIZE = 50;
@@ -65,6 +86,7 @@ const TABLE_STATE = {
   filter_org: parseAsString.withDefault(""),
   filter_user: parseAsString.withDefault(""),
   filter_key_id: parseAsString.withDefault(""),
+  filter_status: parseAsString.withDefault(""),
 };
 
 const toSortOrder = (active: SortingState[number]): "asc" | "desc" => (active.desc ? "desc" : "asc");
@@ -96,15 +118,16 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
     () => ({ pageIndex: tableState.page - 1, pageSize: tableState.page_size }),
     [tableState.page, tableState.page_size],
   );
-  const { filter_team, filter_org, filter_user, filter_key_id } = tableState;
+  const { filter_team, filter_org, filter_user, filter_key_id, filter_status } = tableState;
   const appliedFilters = useMemo(
     () => ({
       team_id: filter_team.trim(),
       org_id: filter_org.trim(),
       user_id: filter_user.trim(),
       key_hash: filter_key_id.trim(),
+      status: isKeyStatusFilter(filter_status) ? filter_status : "",
     }),
-    [filter_team, filter_org, filter_user, filter_key_id],
+    [filter_team, filter_org, filter_user, filter_key_id, filter_status],
   );
   const columnFilters = useMemo<ColumnFiltersState>(
     () =>
@@ -121,6 +144,7 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
     search: searchQuery.trim() || undefined,
     userID: appliedFilters.user_id || undefined,
     keyHash: appliedFilters.key_hash || undefined,
+    status: appliedFilters.status || undefined,
     sortBy,
     sortOrder: tableState.sort_order,
     expand: "user",
@@ -164,6 +188,7 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
         filter_org: filterValue(next, "org_id"),
         filter_user: filterValue(next, "user_id"),
         filter_key_id: filterValue(next, "key_hash"),
+        filter_status: filterValue(next, "status"),
         page: null,
       };
       void setTableState(nextFilters);
@@ -233,6 +258,9 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
       if (columnId === "org_id") {
         return organizations.find((org) => org.organization_id === raw)?.organization_alias || raw;
       }
+      if (columnId === "status" && isKeyStatusFilter(raw)) {
+        return KEY_STATUS_LABELS[raw];
+      }
       return raw;
     },
     [allTeams, organizations],
@@ -340,6 +368,24 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
                       placeholder="Enter Key ID…"
                     />
                   </DataTableFilterField>
+                  <DataTableFilterField label="Status">
+                    <Select
+                      items={STATUS_FILTER_ITEMS}
+                      value={(get("status") as string) || ALL_STATUSES}
+                      onValueChange={(value) => set("status", value === ALL_STATUSES ? undefined : value)}
+                    >
+                      <SelectTrigger className="w-full" aria-label="Status">
+                        <SelectValue placeholder="All statuses" />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {STATUS_FILTER_ITEMS.map((item) => (
+                          <SelectItem key={item.value} value={item.value}>
+                            {item.label}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </DataTableFilterField>
                 </>
               )}
             </DataTableFilterDrawer>
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx
index 6eea77ae827..ff608365500 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx
@@ -43,6 +43,13 @@ export const KEY_TABLE_SORT_FIELDS: readonly string[] = [
 ];
 
 const getKeyStatus = (key: KeyResponse): KeyStatus => {
+  if (key.deleted_at) {
+    return {
+      tone: "neutral",
+      label: "Deleted",
+      tooltip: `Deleted ${new Date(key.deleted_at).toLocaleString()}${key.deleted_by ? ` by ${key.deleted_by}` : ""}. Kept for audit and spend history; requests using this key are rejected.`,
+    };
+  }
   if (key.blocked === true) {
     const isScimBlocked = (key.metadata as Record<string, unknown> | null | undefined)?.scim_blocked === true;
     return {
diff --git a/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx b/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx
index eadbca87140..b42bef04be8 100644
--- a/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx
+++ b/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx
@@ -64,6 +64,8 @@ export interface KeyResponse {
   model_max_budget_usage?: Record<string, ModelBudgetUsage> | null;
   soft_budget_cooldown: boolean;
   blocked: boolean;
+  deleted_at?: string | null;
+  deleted_by?: string | null;
   litellm_budget_table: Record<string, unknown>;
   organization_id: string | null;
   org_id?: string | null;
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 4c16a8613eb..542d491e2d7 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -7859,7 +7859,10 @@ export interface paths {
          *
          *     Returns:
          *     - key: str - The key that was looked up, echoed back as it was passed in
-         *     - info: dict - The key's row, minus the hashed token
+         *     - info: dict - The key's row, minus the hashed token. Deleted keys are served from the
+         *       LiteLLM_DeletedVerificationToken archive and carry deleted_at / deleted_by
+         *         - status: "active" | "expired" | "revoked" | "deleted" - Derived from blocked, expires and
+         *           whether the row came from the archive
          *         - key_alias: str | None - User-friendly key alias
          *         - spend: float - Amount spent by the key. When budget_duration is set this covers only the
          *           current budget window, not the key's lifetime
@@ -7917,7 +7920,9 @@ export interface paths {
          *
          *     Parameters:
          *         expand: Optional[List[str]] - Expand related objects (e.g. 'user' to include user information)
-         *         status: Optional[str] - Filter by status. Currently supports "deleted" to query deleted keys.
+         *         status: Optional[str] - Filter by status: "active", "expired", "revoked" (blocked) or "deleted".
+         *         "deleted" reads the LiteLLM_DeletedVerificationToken archive; the other values partition the
+         *         live key table, so every live key matches exactly one of them.
          *
          *     Returns:
          *         {
@@ -51185,7 +51190,7 @@ export interface operations {
                 sort_order?: string;
                 /** @description Expand related objects (e.g. 'user') */
                 expand?: string[] | null;
-                /** @description Filter by status (e.g. 'deleted') */
+                /** @description Filter by status: 'active' (not blocked, not expired), 'expired' (not blocked, past expiry), 'revoked' (blocked) or 'deleted' (archived keys). Omit to return live keys regardless of status. */
                 status?: string | null;
                 /** @description Filter keys by project ID */
                 project_id?: string | null;

From f6f782ff67168b6e52e8e03828c5c6270c850944 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 22:56:37 +0000
Subject: [PATCH 06/76] feat(s3): add s3_log_prompts_only option to log prompts
 without responses

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/constants.py                          |   1 +
 litellm/integrations/callback_configs.json    |   6 +
 litellm/integrations/custom_logger.py         |   1 +
 litellm/integrations/s3.py                    |  69 ++++++---
 litellm/integrations/s3_v2.py                 |  16 ++-
 litellm/proxy/_types.py                       |   1 +
 tests/test_litellm/integrations/test_s3.py    | 136 +++++++++++++++++-
 tests/test_litellm/integrations/test_s3_v2.py | 130 +++++++++++++++++
 .../src/components/settings.test.tsx          | 106 ++++++++++++++
 .../src/components/settings.tsx               |  47 +++++-
 10 files changed, 485 insertions(+), 28 deletions(-)

diff --git a/litellm/constants.py b/litellm/constants.py
index 1dbb8a842fb..3268c871ca6 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -53,6 +53,7 @@ S3_BOUNDED_OBJECT_KEY_HEAD_BYTES: Final = 64
 S3_PREFIX_DIGEST_CHARS: Final = 16
 # s3 allows 2048 bytes of combined metadata headers, which Content-Disposition counts against
 MAX_S3_OBJECT_DOWNLOAD_FILENAME_BYTES: Final = 1024
+S3_LOG_PROMPTS_ONLY_ENV_VAR: Final = "S3_LOG_PROMPTS_ONLY"
 MAX_FILE_LIST_LIMIT: Final = 10000
 DEFAULT_SQS_FLUSH_INTERVAL_SECONDS: Final = int(os.getenv("DEFAULT_SQS_FLUSH_INTERVAL_SECONDS", 10))
 DEFAULT_NUM_WORKERS_LITELLM_PROXY: Final = int(os.getenv("DEFAULT_NUM_WORKERS_LITELLM_PROXY", 1))
diff --git a/litellm/integrations/callback_configs.json b/litellm/integrations/callback_configs.json
index 85bfcc6e7ed..6806188c97c 100644
--- a/litellm/integrations/callback_configs.json
+++ b/litellm/integrations/callback_configs.json
@@ -446,6 +446,12 @@
         "ui_name": "S3 Path Prefix",
         "description": "Path prefix within the bucket for organizing logs",
         "required": false
+      },
+      "s3_log_prompts_only": {
+        "type": "boolean",
+        "ui_name": "Log Prompts Only",
+        "description": "Log request messages to S3 but drop the model response from each logged object",
+        "required": false
       }
     },
     "description": "S3 Bucket (AWS) Logging Integration"
diff --git a/litellm/integrations/custom_logger.py b/litellm/integrations/custom_logger.py
index 70d2f3ae5c3..5b5261fab6b 100644
--- a/litellm/integrations/custom_logger.py
+++ b/litellm/integrations/custom_logger.py
@@ -118,6 +118,7 @@ class CustomLogger:  # https://docs.litellm.ai/docs/observability/custom_callbac
 
         alias_map: Final = {
             "langfuse_otel": "langfuse",
+            "s3_v2": "s3",
         }
         lookup_name: Final = alias_map.get(normalized_name, normalized_name)
 
diff --git a/litellm/integrations/s3.py b/litellm/integrations/s3.py
index 8ce461eea5b..796784fb993 100644
--- a/litellm/integrations/s3.py
+++ b/litellm/integrations/s3.py
@@ -2,19 +2,42 @@
 #    On success + failure, log events to Supabase
 
 import hashlib
+import os
+from collections.abc import Mapping
 from datetime import datetime
 from typing import Final, cast
 
+from pydantic import TypeAdapter, ValidationError
+
 import litellm
 from litellm._logging import print_verbose, verbose_logger
 from litellm.constants import (
     MAX_S3_OBJECT_DOWNLOAD_FILENAME_BYTES,
     MAX_S3_OBJECT_KEY_BYTES,
     S3_BOUNDED_OBJECT_KEY_HEAD_BYTES,
+    S3_LOG_PROMPTS_ONLY_ENV_VAR,
     S3_PREFIX_DIGEST_CHARS,
 )
 from litellm.types.utils import StandardLoggingPayload
 
+_S3_LOG_PROMPTS_ONLY: Final = TypeAdapter(bool)
+
+
+def resolve_s3_log_prompts_only(configured: object, environ: Mapping[str, str] | None = None) -> bool:
+    env: Final = os.environ if environ is None else environ
+    raw: Final = env.get(S3_LOG_PROMPTS_ONLY_ENV_VAR) if configured is None else configured
+    if raw is None or raw == "":
+        return False
+    try:
+        return _S3_LOG_PROMPTS_ONLY.validate_python(raw.strip() if isinstance(raw, str) else raw)
+    except ValidationError:
+        verbose_logger.warning("s3 logging: s3_log_prompts_only=%r is not a boolean, logging prompts only", raw)
+        return True
+
+
+def prompts_only_payload(payload: StandardLoggingPayload) -> StandardLoggingPayload:
+    return {**payload, "response": None}
+
 
 class S3Logger:
     # Class variables or attributes
@@ -33,6 +56,7 @@ class S3Logger:
         s3_config=None,
         s3_server_side_encryption: str | None = None,
         s3_sse_kms_key_id: str | None = None,
+        s3_log_prompts_only: bool | None = None,
         **kwargs,
     ):
         import boto3
@@ -41,29 +65,30 @@ class S3Logger:
             verbose_logger.debug("in init s3 logger - s3_callback_params %s", litellm.s3_callback_params)
 
             s3_use_team_prefix = False
+            params: Final = {
+                key: litellm.get_secret(value) if isinstance(value, str) and value.startswith("os.environ/") else value
+                for key, value in (litellm.s3_callback_params or {}).items()
+            }
 
             if litellm.s3_callback_params is not None:
-                # read in .env variables - example os.environ/AWS_BUCKET_NAME
-                for key, value in litellm.s3_callback_params.items():
-                    if isinstance(value, str) and value.startswith("os.environ/"):
-                        litellm.s3_callback_params[key] = litellm.get_secret(value)
-                # now set s3 params from litellm.s3_logger_params
-                s3_bucket_name = litellm.s3_callback_params.get("s3_bucket_name")
-                s3_region_name = litellm.s3_callback_params.get("s3_region_name")
-                s3_api_version = litellm.s3_callback_params.get("s3_api_version")
-                s3_use_ssl = litellm.s3_callback_params.get("s3_use_ssl", True)
-                s3_verify = litellm.s3_callback_params.get("s3_verify")
-                s3_endpoint_url = litellm.s3_callback_params.get("s3_endpoint_url")
-                s3_aws_access_key_id = litellm.s3_callback_params.get("s3_aws_access_key_id")
-                s3_aws_secret_access_key = litellm.s3_callback_params.get("s3_aws_secret_access_key")
-                s3_aws_session_token = litellm.s3_callback_params.get("s3_aws_session_token")
-                s3_config = litellm.s3_callback_params.get("s3_config")
-                s3_path = litellm.s3_callback_params.get("s3_path")
-                s3_server_side_encryption = litellm.s3_callback_params.get("s3_server_side_encryption")
-                s3_sse_kms_key_id = litellm.s3_callback_params.get("s3_sse_kms_key_id")
-                # done reading litellm.s3_callback_params
-                s3_use_team_prefix = bool(litellm.s3_callback_params.get("s3_use_team_prefix", False))
+                s3_bucket_name = params.get("s3_bucket_name")
+                s3_region_name = params.get("s3_region_name")
+                s3_api_version = params.get("s3_api_version")
+                s3_use_ssl = params.get("s3_use_ssl", True)
+                s3_verify = params.get("s3_verify")
+                s3_endpoint_url = params.get("s3_endpoint_url")
+                s3_aws_access_key_id = params.get("s3_aws_access_key_id")
+                s3_aws_secret_access_key = params.get("s3_aws_secret_access_key")
+                s3_aws_session_token = params.get("s3_aws_session_token")
+                s3_config = params.get("s3_config")
+                s3_path = params.get("s3_path")
+                s3_server_side_encryption = params.get("s3_server_side_encryption")
+                s3_sse_kms_key_id = params.get("s3_sse_kms_key_id")
+                s3_use_team_prefix = bool(params.get("s3_use_team_prefix", False))
             self.s3_use_team_prefix = s3_use_team_prefix
+            self.s3_log_prompts_only: object = (
+                params.get("s3_log_prompts_only") if s3_log_prompts_only is None else s3_log_prompts_only
+            )
             self.bucket_name = s3_bucket_name
             self.s3_path = s3_path
             self.s3_server_side_encryption, self.s3_sse_kms_key_id = resolve_sse_params(
@@ -144,7 +169,9 @@ class S3Logger:
 
             from litellm.litellm_core_utils.safe_json_dumps import safe_dumps
 
-            payload_str: Final = safe_dumps(payload)
+            payload_str: Final = safe_dumps(
+                prompts_only_payload(payload) if resolve_s3_log_prompts_only(self.s3_log_prompts_only) else payload
+            )
 
             print_verbose(f"\ns3 Logger - Logging payload = {payload_str}")
 
diff --git a/litellm/integrations/s3_v2.py b/litellm/integrations/s3_v2.py
index 972ac79e306..826f55cc798 100644
--- a/litellm/integrations/s3_v2.py
+++ b/litellm/integrations/s3_v2.py
@@ -21,6 +21,8 @@ from litellm.constants import DEFAULT_S3_BATCH_SIZE, DEFAULT_S3_FLUSH_INTERVAL_S
 from litellm.integrations.s3 import (
     get_s3_object_download_filename,
     get_s3_object_key,
+    prompts_only_payload,
+    resolve_s3_log_prompts_only,
     resolve_sse_params,
 )
 from litellm.litellm_core_utils.aws_partition import get_aws_dns_suffix
@@ -68,6 +70,7 @@ class S3Logger(CustomBatchLogger, BaseAWSLLM):
         s3_use_virtual_hosted_style: bool = False,
         s3_server_side_encryption: str | None = None,
         s3_sse_kms_key_id: str | None = None,
+        s3_log_prompts_only: bool | None = None,
         s3_callback_params_override: dict | None = None,
         **kwargs,
     ):
@@ -108,6 +111,7 @@ class S3Logger(CustomBatchLogger, BaseAWSLLM):
                 s3_use_virtual_hosted_style=s3_use_virtual_hosted_style,
                 s3_server_side_encryption=s3_server_side_encryption,
                 s3_sse_kms_key_id=s3_sse_kms_key_id,
+                s3_log_prompts_only=s3_log_prompts_only,
             )
             verbose_logger.debug("s3 logger using endpoint url %s", s3_endpoint_url)
 
@@ -163,6 +167,7 @@ class S3Logger(CustomBatchLogger, BaseAWSLLM):
         s3_use_virtual_hosted_style: bool = False,
         s3_server_side_encryption: str | None = None,
         s3_sse_kms_key_id: str | None = None,
+        s3_log_prompts_only: bool | None = None,
         params_source: dict | None = None,
     ):
         """
@@ -212,6 +217,10 @@ class S3Logger(CustomBatchLogger, BaseAWSLLM):
             bool(params.get("s3_use_virtual_hosted_style", False)) or s3_use_virtual_hosted_style
         )
 
+        self.s3_log_prompts_only: object = (
+            params.get("s3_log_prompts_only") if s3_log_prompts_only is None else s3_log_prompts_only
+        )
+
         self.s3_server_side_encryption, self.s3_sse_kms_key_id = resolve_sse_params(
             params.get("s3_server_side_encryption") or s3_server_side_encryption,
             params.get("s3_sse_kms_key_id") or s3_sse_kms_key_id,
@@ -489,8 +498,13 @@ class S3Logger(CustomBatchLogger, BaseAWSLLM):
 
         s3_object_download_filename: Final = get_s3_object_download_filename(start_time, standard_logging_payload["id"])
 
+        payload: Final = (
+            prompts_only_payload(standard_logging_payload)
+            if resolve_s3_log_prompts_only(self.s3_log_prompts_only)
+            else standard_logging_payload
+        )
         return s3BatchLoggingElement(
-            payload=dict(standard_logging_payload),
+            payload=dict(payload),
             s3_object_key=s3_object_key,
             s3_object_download_filename=s3_object_download_filename,
         )
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index ad55fa5d2be..e426e83bbe7 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -3708,6 +3708,7 @@ class AllCallbacks(LiteLLMPydanticObjectBase):
             "AWS_ACCESS_KEY_ID",
             "AWS_SECRET_ACCESS_KEY",
             "AWS_REGION_NAME",
+            "S3_LOG_PROMPTS_ONLY",
         ],
     )
 
diff --git a/tests/test_litellm/integrations/test_s3.py b/tests/test_litellm/integrations/test_s3.py
index 58b15b79e76..ba8d575c1b7 100644
--- a/tests/test_litellm/integrations/test_s3.py
+++ b/tests/test_litellm/integrations/test_s3.py
@@ -1,16 +1,24 @@
+import copy
+import json
 from datetime import datetime
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 import litellm
 from litellm.constants import MAX_S3_OBJECT_DOWNLOAD_FILENAME_BYTES, MAX_S3_OBJECT_KEY_BYTES
-from litellm.integrations.s3 import S3Logger
+from litellm.integrations.s3 import S3Logger, prompts_only_payload, resolve_s3_log_prompts_only
 
 TEST_KMS_KEY_ARN = "arn:aws:kms:us-east-1:111122223333:key/test-key-id"
+TEST_MESSAGES = [{"role": "user", "content": "Reply with exactly the word PINEAPPLE."}]
+TEST_RESPONSE = {"choices": [{"message": {"role": "assistant", "content": "PINEAPPLE"}}]}
 
 
 def _standard_logging_payload(response_id: str = "chatcmpl-test-id") -> dict:
     return {
         "id": response_id,
+        "messages": copy.deepcopy(TEST_MESSAGES),
+        "response": copy.deepcopy(TEST_RESPONSE),
         "metadata": {"user_api_key_team_alias": None},
     }
 
@@ -22,7 +30,9 @@ def _log_event_kwargs(response_id: str = "chatcmpl-test-id") -> dict:
     }
 
 
-def _run_log_event(callback_params: dict, response_id: str = "chatcmpl-test-id") -> MagicMock:
+def _run_log_event(
+    callback_params: dict, response_id: str = "chatcmpl-test-id", log_kwargs: dict | None = None
+) -> MagicMock:
     original = litellm.s3_callback_params
     litellm.s3_callback_params = callback_params
     try:
@@ -31,7 +41,7 @@ def _run_log_event(callback_params: dict, response_id: str = "chatcmpl-test-id")
             mock_boto3_client.return_value = mock_s3_client
             logger = S3Logger()
             logger.log_event(
-                kwargs=_log_event_kwargs(response_id),
+                kwargs=_log_event_kwargs(response_id) if log_kwargs is None else log_kwargs,
                 response_obj={"id": response_id},
                 start_time=datetime(2026, 7, 30, 12, 0, 0),
                 end_time=datetime(2026, 7, 30, 12, 0, 1),
@@ -182,3 +192,123 @@ def test_put_object_keeps_the_configured_path_intact_when_only_the_id_has_to_shr
     key = mock_s3_client.put_object.call_args.kwargs["Key"]
     assert key.startswith(long_path + "/2026-07-30/")
     assert len(key.encode("utf-8")) == MAX_S3_OBJECT_KEY_BYTES
+
+
+def _uploaded_body(mock_s3_client: MagicMock) -> dict:
+    return json.loads(mock_s3_client.put_object.call_args.kwargs["Body"])
+
+
+def test_log_event_prompts_only_drops_response_and_keeps_messages(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("S3_LOG_PROMPTS_ONLY", raising=False)
+    log_kwargs = _log_event_kwargs()
+    original_payload = copy.deepcopy(log_kwargs["standard_logging_object"])
+
+    mock_s3_client = _run_log_event(
+        {"s3_bucket_name": "test-bucket", "s3_region_name": "us-east-1", "s3_log_prompts_only": True},
+        log_kwargs=log_kwargs,
+    )
+
+    body = _uploaded_body(mock_s3_client)
+    assert body["messages"] == TEST_MESSAGES
+    assert body["response"] is None
+    assert body["id"] == "chatcmpl-test-id"
+    assert log_kwargs["standard_logging_object"] == original_payload
+
+
+def test_log_event_default_keeps_response(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("S3_LOG_PROMPTS_ONLY", raising=False)
+
+    mock_s3_client = _run_log_event({"s3_bucket_name": "test-bucket", "s3_region_name": "us-east-1"})
+
+    body = _uploaded_body(mock_s3_client)
+    assert body["response"] == TEST_RESPONSE
+    assert body["messages"] == TEST_MESSAGES
+
+
+def test_log_event_reads_prompts_only_env_var_at_log_time(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("S3_LOG_PROMPTS_ONLY", raising=False)
+    original = litellm.s3_callback_params
+    litellm.s3_callback_params = {"s3_bucket_name": "test-bucket", "s3_region_name": "us-east-1"}
+    try:
+        with patch("boto3.client") as mock_boto3_client:
+            mock_s3_client = MagicMock()
+            mock_boto3_client.return_value = mock_s3_client
+            logger = S3Logger()
+            monkeypatch.setenv("S3_LOG_PROMPTS_ONLY", "true")
+            logger.log_event(
+                kwargs=_log_event_kwargs(),
+                response_obj={"id": "chatcmpl-test-id"},
+                start_time=datetime(2026, 7, 30, 12, 0, 0),
+                end_time=datetime(2026, 7, 30, 12, 0, 1),
+                print_verbose=lambda *args, **kwargs: None,
+            )
+    finally:
+        litellm.s3_callback_params = original
+
+    body = _uploaded_body(mock_s3_client)
+    assert body["response"] is None
+    assert body["messages"] == TEST_MESSAGES
+
+
+def test_log_event_explicit_false_param_beats_env_var(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("S3_LOG_PROMPTS_ONLY", "true")
+
+    mock_s3_client = _run_log_event(
+        {"s3_bucket_name": "test-bucket", "s3_region_name": "us-east-1", "s3_log_prompts_only": False}
+    )
+
+    assert _uploaded_body(mock_s3_client)["response"] == TEST_RESPONSE
+
+
+def test_s3_logger_init_does_not_mutate_global_callback_params(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("MY_S3_BUCKET", "resolved-bucket")
+    callback_params = {"s3_bucket_name": "os.environ/MY_S3_BUCKET", "s3_region_name": "us-east-1"}
+    snapshot = copy.deepcopy(callback_params)
+    original = litellm.s3_callback_params
+    litellm.s3_callback_params = callback_params
+    try:
+        with patch("boto3.client"):
+            logger = S3Logger()
+    finally:
+        litellm.s3_callback_params = original
+
+    assert logger.bucket_name == "resolved-bucket"
+    assert callback_params == snapshot
+
+
+@pytest.mark.parametrize(
+    "configured,env_value,expected",
+    [
+        (True, None, True),
+        (False, "true", False),
+        ("true", None, True),
+        ("False", "true", False),
+        ("1", None, True),
+        ("0", None, False),
+        (" yes ", None, True),
+        (None, None, False),
+        (None, "true", True),
+        (None, "false", False),
+        (None, "", False),
+        ("", "true", False),
+    ],
+)
+def test_resolve_s3_log_prompts_only(configured: object, env_value: str | None, expected: bool):
+    environ = {} if env_value is None else {"S3_LOG_PROMPTS_ONLY": env_value}
+    assert resolve_s3_log_prompts_only(configured, environ) is expected
+
+
+def test_resolve_s3_log_prompts_only_unparseable_value_fails_toward_prompts_only():
+    assert resolve_s3_log_prompts_only("enabled", {}) is True
+
+
+def test_prompts_only_payload_returns_copy_with_response_cleared():
+    payload = _standard_logging_payload()
+    snapshot = copy.deepcopy(payload)
+
+    stripped = prompts_only_payload(payload)
+
+    assert stripped["response"] is None
+    assert stripped["messages"] == TEST_MESSAGES
+    assert stripped is not payload
+    assert payload == snapshot
diff --git a/tests/test_litellm/integrations/test_s3_v2.py b/tests/test_litellm/integrations/test_s3_v2.py
index 08d37297ab1..1179aa7e409 100644
--- a/tests/test_litellm/integrations/test_s3_v2.py
+++ b/tests/test_litellm/integrations/test_s3_v2.py
@@ -1,4 +1,6 @@
 import asyncio
+import copy
+import json
 import re
 import sys
 import textwrap
@@ -10,6 +12,7 @@ from unittest.mock import AsyncMock, MagicMock, call, patch
 
 import httpx
 import pytest
+import respx
 
 from litellm.integrations.s3_v2 import S3Logger
 from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler, HTTPHandler
@@ -2310,3 +2313,130 @@ def _s3_logger_for_region(region_name: str) -> S3Logger:
 )
 def test_build_object_url_uses_partition_dns_suffix(region_name: str, expected_url: str) -> None:
     assert _s3_logger_for_region(region_name)._build_object_url("2025-01-01/key.json") == expected_url
+
+
+def _prompts_only_logger(**kwargs) -> S3Logger:
+    return S3Logger(
+        s3_bucket_name="test-bucket",
+        s3_aws_access_key_id="test-key",
+        s3_aws_secret_access_key="test-secret",
+        s3_region_name="us-east-1",
+        **kwargs,
+    )
+
+
+def _chat_payload() -> dict:
+    return {
+        "id": "chatcmpl-prompts-only",
+        "messages": [{"role": "user", "content": "Reply with exactly the word PINEAPPLE."}],
+        "response": {"choices": [{"message": {"role": "assistant", "content": "PINEAPPLE"}}]},
+        "metadata": {"user_api_key_team_alias": None},
+    }
+
+
+async def _queued_body_via_async_upload(logger: S3Logger, log_event) -> dict:
+    payload = _chat_payload()
+    original = copy.deepcopy(payload)
+    await log_event(
+        kwargs={"standard_logging_object": payload},
+        response_obj=None,
+        start_time=datetime(2026, 7, 30, 12, 0, 0),
+        end_time=datetime(2026, 7, 30, 12, 0, 1),
+    )
+    assert payload == original, "the caller's standard_logging_object must not be mutated"
+    (element,) = logger.log_queue
+
+    response = MagicMock()
+    response.status_code = 200
+    response.raise_for_status = MagicMock()
+    logger.async_httpx_client = AsyncMock()
+    logger.async_httpx_client.put.return_value = response
+    await logger.async_upload_data_to_s3(element)
+    return json.loads(logger.async_httpx_client.put.call_args.kwargs["data"])
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("event_name", ["async_log_success_event", "async_log_failure_event"])
+async def test_prompts_only_drops_response_but_keeps_messages_in_uploaded_object(monkeypatch, event_name):
+    import litellm
+
+    monkeypatch.setattr(litellm, "s3_callback_params", {"s3_log_prompts_only": True})
+    logger = _prompts_only_logger()
+
+    body = await _queued_body_via_async_upload(logger, getattr(logger, event_name))
+
+    assert body["messages"] == _chat_payload()["messages"]
+    assert body["response"] is None
+    assert body["id"] == "chatcmpl-prompts-only"
+
+
+@pytest.mark.asyncio
+async def test_prompts_only_default_off_keeps_response_in_uploaded_object(monkeypatch):
+    import litellm
+
+    monkeypatch.setattr(litellm, "s3_callback_params", {})
+    monkeypatch.delenv("S3_LOG_PROMPTS_ONLY", raising=False)
+    logger = _prompts_only_logger()
+
+    body = await _queued_body_via_async_upload(logger, logger.async_log_success_event)
+
+    assert body["response"] == _chat_payload()["response"]
+    assert body["messages"] == _chat_payload()["messages"]
+
+
+@pytest.mark.asyncio
+async def test_prompts_only_explicit_false_in_params_beats_env_var(monkeypatch):
+    import litellm
+
+    monkeypatch.setattr(litellm, "s3_callback_params", {"s3_log_prompts_only": False})
+    monkeypatch.setenv("S3_LOG_PROMPTS_ONLY", "true")
+    logger = _prompts_only_logger()
+
+    body = await _queued_body_via_async_upload(logger, logger.async_log_success_event)
+
+    assert body["response"] == _chat_payload()["response"]
+
+
+@pytest.mark.asyncio
+async def test_prompts_only_env_var_applies_when_param_unset(monkeypatch):
+    import litellm
+
+    monkeypatch.setattr(litellm, "s3_callback_params", {})
+    logger = _prompts_only_logger()
+    monkeypatch.setenv("S3_LOG_PROMPTS_ONLY", "true")
+
+    body = await _queued_body_via_async_upload(logger, logger.async_log_success_event)
+
+    assert body["response"] is None
+    assert body["messages"] == _chat_payload()["messages"]
+
+
+@respx.mock
+def test_prompts_only_constructor_kwarg_applies_to_sync_upload(monkeypatch):
+    import litellm
+
+    monkeypatch.setattr(litellm, "s3_callback_params", {})
+    monkeypatch.delenv("S3_LOG_PROMPTS_ONLY", raising=False)
+    logger = _prompts_only_logger(s3_log_prompts_only=True)
+    payload = _chat_payload()
+
+    element = logger.create_s3_batch_logging_element(
+        start_time=datetime(2026, 7, 30, 12, 0, 0),
+        standard_logging_payload=payload,
+    )
+    assert element is not None
+    assert payload["response"] == _chat_payload()["response"]
+
+    put_route = respx.put(url__regex=r"https://test-bucket\.s3\..*").mock(return_value=httpx.Response(200))
+    logger.upload_data_to_s3(element)
+
+    body = json.loads(put_route.calls.last.request.content)
+    assert body["response"] is None
+    assert body["messages"] == _chat_payload()["messages"]
+
+
+@pytest.mark.parametrize("callback_name", ["s3", "s3_v2"])
+def test_prompts_only_toggle_is_exposed_to_admin_ui_for_both_s3_callbacks(callback_name):
+    from litellm.integrations.custom_logger import CustomLogger
+
+    assert "S3_LOG_PROMPTS_ONLY" in CustomLogger.get_callback_env_vars(callback_name)
diff --git a/ui/litellm-dashboard/src/components/settings.test.tsx b/ui/litellm-dashboard/src/components/settings.test.tsx
index 08cb9550646..c24fa00438a 100644
--- a/ui/litellm-dashboard/src/components/settings.test.tsx
+++ b/ui/litellm-dashboard/src/components/settings.test.tsx
@@ -302,6 +302,112 @@ describe("Settings", () => {
     });
   });
 
+  const mockS3Callback = (variables: Record<string, string | null>, callbackName = "s3") => {
+    mockGetCallbacksCall.mockResolvedValue({
+      callbacks: [{ name: callbackName, variables }],
+      available_callbacks: {
+        s3: {
+          litellm_callback_name: "s3",
+          litellm_callback_params: [
+            "AWS_ACCESS_KEY_ID",
+            "AWS_SECRET_ACCESS_KEY",
+            "AWS_REGION_NAME",
+            "S3_LOG_PROMPTS_ONLY",
+          ],
+          ui_callback_name: "s3 Bucket (AWS)",
+        },
+      },
+      alerts: [],
+    });
+    mockGetCallbackConfigsCall.mockResolvedValue([
+      {
+        id: "s3",
+        displayName: "S3",
+        dynamic_params: {
+          s3_bucket_name: { type: "text", ui_name: "S3 Bucket Name", required: false },
+          s3_log_prompts_only: { type: "boolean", ui_name: "Log Prompts Only", required: false },
+        },
+      },
+    ]);
+  };
+
+  const openS3EditModal = async (callbackName = "s3") => {
+    const user = userEvent.setup();
+    render(<Settings {...defaultProps} />);
+    await user.click(await screen.findByTestId(`callback-actions-${callbackName}-success`));
+    await user.click(await screen.findByTestId("callback-action-edit"));
+    return user;
+  };
+
+  it("should render a saved boolean dynamic param as a checked switch and post false when toggled off", async () => {
+    mockS3Callback({ S3_LOG_PROMPTS_ONLY: "true" });
+    const user = await openS3EditModal();
+
+    const promptsOnlySwitch = await screen.findByRole("switch", { name: "Log Prompts Only" });
+    expect(promptsOnlySwitch).toBeChecked();
+
+    await user.click(promptsOnlySwitch);
+    expect(promptsOnlySwitch).not.toBeChecked();
+    await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(vi.mocked(setCallbacksCall)).toHaveBeenCalledWith(
+        "token",
+        expect.objectContaining({
+          environment_variables: expect.objectContaining({ callback: "s3", s3_log_prompts_only: "false" }),
+        }),
+      );
+    });
+  });
+
+  it("should render an unset boolean dynamic param as an unchecked switch and post true when toggled on", async () => {
+    mockS3Callback({ S3_LOG_PROMPTS_ONLY: null });
+    const user = await openS3EditModal();
+
+    const promptsOnlySwitch = await screen.findByRole("switch", { name: "Log Prompts Only" });
+    expect(promptsOnlySwitch).not.toBeChecked();
+
+    await user.click(promptsOnlySwitch);
+    await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(vi.mocked(setCallbacksCall)).toHaveBeenCalledWith(
+        "token",
+        expect.objectContaining({
+          environment_variables: expect.objectContaining({ callback: "s3", s3_log_prompts_only: "true" }),
+        }),
+      );
+    });
+  });
+
+  it.each(["True", "1"])("should render a boolean dynamic param stored as %s as a checked switch", async (stored) => {
+    mockS3Callback({ S3_LOG_PROMPTS_ONLY: stored });
+    await openS3EditModal();
+
+    expect(await screen.findByRole("switch", { name: "Log Prompts Only" })).toBeChecked();
+  });
+
+  it("should resolve the s3_v2 callback to the s3 dynamic params and post under the s3_v2 name", async () => {
+    mockS3Callback({ S3_LOG_PROMPTS_ONLY: null }, "s3_v2");
+    const user = await openS3EditModal("s3_v2");
+
+    const promptsOnlySwitch = await screen.findByRole("switch", { name: "Log Prompts Only" });
+    expect(promptsOnlySwitch).not.toBeChecked();
+
+    await user.click(promptsOnlySwitch);
+    await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Save Changes" }));
+
+    await waitFor(() => {
+      expect(vi.mocked(setCallbacksCall)).toHaveBeenCalledWith(
+        "token",
+        expect.objectContaining({
+          environment_variables: expect.objectContaining({ callback: "s3_v2", s3_log_prompts_only: "true" }),
+          litellm_settings: { success_callback: ["s3_v2"] },
+        }),
+      );
+    });
+  });
+
   it("should send the typed webhook url for an alert type when the alerting tab is saved", async () => {
     const user = userEvent.setup();
     render(<Settings {...defaultProps} />);
diff --git a/ui/litellm-dashboard/src/components/settings.tsx b/ui/litellm-dashboard/src/components/settings.tsx
index e549770af6e..c0daeac3b72 100644
--- a/ui/litellm-dashboard/src/components/settings.tsx
+++ b/ui/litellm-dashboard/src/components/settings.tsx
@@ -67,19 +67,20 @@ const DynamicParamsFields: React.FC<DynamicParamsFieldsProps> = ({ params, callb
     return null;
   }
 
+  const callbackConfig = findCallbackConfig(callbackConfigs, selectedCallback);
   return (
     <div className="space-y-4 mt-6 p-4 bg-muted rounded-lg border">
       {params.map((param) => {
-        const callbackConfig = callbackConfigs.find((config) => config.id === selectedCallback);
         const paramConfig = callbackConfig?.dynamic_params?.[param] || {};
         const paramType = paramConfig.type || "text";
         const fieldLabel = paramConfig.ui_name || param.replace(/_/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
         const isRequired = paramConfig.required || false;
         const selectOptions: string[] = Array.isArray(paramConfig.options) ? paramConfig.options : [];
         const isSelect = paramType === "select" && selectOptions.length > 0;
+        const isBoolean = paramType === "boolean";
         const fieldId = `${fieldIdPrefix}-${param}`;
         const validationRules = isRequired ? { required: `Please enter the ${fieldLabel.toLowerCase()}` } : undefined;
-        const registration = isSelect ? undefined : register(param, validationRules);
+        const registration = isSelect || isBoolean ? undefined : register(param, validationRules);
 
         return (
           <Field key={param} className="mb-4">
@@ -111,7 +112,22 @@ const DynamicParamsFields: React.FC<DynamicParamsFieldsProps> = ({ params, callb
                 )}
               />
             )}
+            {isBoolean && (
+              <Controller
+                control={control}
+                name={param}
+                render={({ field }) => (
+                  <Switch
+                    id={fieldId}
+                    checked={/^(true|1)$/i.test(String(field.value ?? ""))}
+                    onCheckedChange={(checked: boolean) => field.onChange(checked ? "true" : "false")}
+                    onBlur={field.onBlur}
+                  />
+                )}
+              />
+            )}
             {!isSelect &&
+              !isBoolean &&
               (paramType === "password" ? (
                 <Input
                   id={fieldId}
@@ -221,6 +237,31 @@ export const CallbackSelector: React.FC<CallbackSelectorProps> = ({
   );
 };
 
+const CALLBACK_CONFIG_ALIASES: Record<string, string> = { s3_v2: "s3" };
+
+interface DynamicParamConfig {
+  type?: string;
+  ui_name?: string;
+  required?: boolean;
+  options?: string[];
+}
+
+interface CallbackConfigWithParams {
+  id: string;
+  dynamic_params?: Record<string, DynamicParamConfig>;
+}
+
+const findCallbackConfig = (
+  callbackConfigs: readonly CallbackConfigWithParams[],
+  callbackName: string | null,
+): CallbackConfigWithParams | undefined => {
+  if (!callbackName) {
+    return undefined;
+  }
+  const configId = CALLBACK_CONFIG_ALIASES[callbackName] ?? callbackName;
+  return callbackConfigs.find((config) => config.id === configId);
+};
+
 // Shared helper function to get dynamic params for a callback
 const getDynamicParamsForCallback = (
   callbackName: string | null,
@@ -231,7 +272,7 @@ const getDynamicParamsForCallback = (
     return fallbackVariables ? Object.keys(fallbackVariables) : [];
   }
 
-  const callbackConfig = callbackConfigs.find((config) => config.id === callbackName);
+  const callbackConfig = findCallbackConfig(callbackConfigs, callbackName);
   if (callbackConfig?.dynamic_params) {
     return Object.keys(callbackConfig.dynamic_params);
   }

From 6e7de5fd20836b499faddda3d7c45bf440545a08 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 23:40:35 +0000
Subject: [PATCH 07/76] test(s3): type the prompts-only test helpers

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/test_litellm/integrations/test_s3.py    |  4 +-
 tests/test_litellm/integrations/test_s3_v2.py | 42 +++++++++++--------
 2 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/tests/test_litellm/integrations/test_s3.py b/tests/test_litellm/integrations/test_s3.py
index ba8d575c1b7..fd677b9dfdf 100644
--- a/tests/test_litellm/integrations/test_s3.py
+++ b/tests/test_litellm/integrations/test_s3.py
@@ -31,7 +31,7 @@ def _log_event_kwargs(response_id: str = "chatcmpl-test-id") -> dict:
 
 
 def _run_log_event(
-    callback_params: dict, response_id: str = "chatcmpl-test-id", log_kwargs: dict | None = None
+    callback_params: dict, response_id: str = "chatcmpl-test-id", log_kwargs: dict[str, object] | None = None
 ) -> MagicMock:
     original = litellm.s3_callback_params
     litellm.s3_callback_params = callback_params
@@ -194,7 +194,7 @@ def test_put_object_keeps_the_configured_path_intact_when_only_the_id_has_to_shr
     assert len(key.encode("utf-8")) == MAX_S3_OBJECT_KEY_BYTES
 
 
-def _uploaded_body(mock_s3_client: MagicMock) -> dict:
+def _uploaded_body(mock_s3_client: MagicMock) -> dict[str, object]:
     return json.loads(mock_s3_client.put_object.call_args.kwargs["Body"])
 
 
diff --git a/tests/test_litellm/integrations/test_s3_v2.py b/tests/test_litellm/integrations/test_s3_v2.py
index 1179aa7e409..52fbbe40b0e 100644
--- a/tests/test_litellm/integrations/test_s3_v2.py
+++ b/tests/test_litellm/integrations/test_s3_v2.py
@@ -5,6 +5,7 @@ import re
 import sys
 import textwrap
 import uuid
+from collections.abc import Awaitable, Callable
 from contextlib import asynccontextmanager
 from datetime import datetime
 from pathlib import Path
@@ -2315,26 +2316,28 @@ def test_build_object_url_uses_partition_dns_suffix(region_name: str, expected_u
     assert _s3_logger_for_region(region_name)._build_object_url("2025-01-01/key.json") == expected_url
 
 
-def _prompts_only_logger(**kwargs) -> S3Logger:
+def _prompts_only_logger(s3_log_prompts_only: bool | None = None) -> S3Logger:
     return S3Logger(
         s3_bucket_name="test-bucket",
         s3_aws_access_key_id="test-key",
         s3_aws_secret_access_key="test-secret",
         s3_region_name="us-east-1",
-        **kwargs,
+        s3_log_prompts_only=s3_log_prompts_only,
     )
 
 
-def _chat_payload() -> dict:
-    return {
-        "id": "chatcmpl-prompts-only",
-        "messages": [{"role": "user", "content": "Reply with exactly the word PINEAPPLE."}],
-        "response": {"choices": [{"message": {"role": "assistant", "content": "PINEAPPLE"}}]},
-        "metadata": {"user_api_key_team_alias": None},
-    }
+def _chat_payload() -> StandardLoggingPayload:
+    return StandardLoggingPayload(
+        id="chatcmpl-prompts-only",
+        messages=[{"role": "user", "content": "Reply with exactly the word PINEAPPLE."}],
+        response={"choices": [{"message": {"role": "assistant", "content": "PINEAPPLE"}}]},
+        metadata={"user_api_key_team_alias": None},
+    )
 
 
-async def _queued_body_via_async_upload(logger: S3Logger, log_event) -> dict:
+async def _queued_body_via_async_upload(
+    logger: S3Logger, log_event: Callable[..., Awaitable[None]]
+) -> dict[str, object]:
     payload = _chat_payload()
     original = copy.deepcopy(payload)
     await log_event(
@@ -2357,13 +2360,18 @@ async def _queued_body_via_async_upload(logger: S3Logger, log_event) -> dict:
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("event_name", ["async_log_success_event", "async_log_failure_event"])
-async def test_prompts_only_drops_response_but_keeps_messages_in_uploaded_object(monkeypatch, event_name):
+async def test_prompts_only_drops_response_but_keeps_messages_in_uploaded_object(
+    monkeypatch: pytest.MonkeyPatch, event_name: str
+):
     import litellm
 
     monkeypatch.setattr(litellm, "s3_callback_params", {"s3_log_prompts_only": True})
     logger = _prompts_only_logger()
 
-    body = await _queued_body_via_async_upload(logger, getattr(logger, event_name))
+    log_event: Callable[..., Awaitable[None]] = (
+        logger.async_log_success_event if event_name == "async_log_success_event" else logger.async_log_failure_event
+    )
+    body = await _queued_body_via_async_upload(logger, log_event)
 
     assert body["messages"] == _chat_payload()["messages"]
     assert body["response"] is None
@@ -2371,7 +2379,7 @@ async def test_prompts_only_drops_response_but_keeps_messages_in_uploaded_object
 
 
 @pytest.mark.asyncio
-async def test_prompts_only_default_off_keeps_response_in_uploaded_object(monkeypatch):
+async def test_prompts_only_default_off_keeps_response_in_uploaded_object(monkeypatch: pytest.MonkeyPatch):
     import litellm
 
     monkeypatch.setattr(litellm, "s3_callback_params", {})
@@ -2385,7 +2393,7 @@ async def test_prompts_only_default_off_keeps_response_in_uploaded_object(monkey
 
 
 @pytest.mark.asyncio
-async def test_prompts_only_explicit_false_in_params_beats_env_var(monkeypatch):
+async def test_prompts_only_explicit_false_in_params_beats_env_var(monkeypatch: pytest.MonkeyPatch):
     import litellm
 
     monkeypatch.setattr(litellm, "s3_callback_params", {"s3_log_prompts_only": False})
@@ -2398,7 +2406,7 @@ async def test_prompts_only_explicit_false_in_params_beats_env_var(monkeypatch):
 
 
 @pytest.mark.asyncio
-async def test_prompts_only_env_var_applies_when_param_unset(monkeypatch):
+async def test_prompts_only_env_var_applies_when_param_unset(monkeypatch: pytest.MonkeyPatch):
     import litellm
 
     monkeypatch.setattr(litellm, "s3_callback_params", {})
@@ -2412,7 +2420,7 @@ async def test_prompts_only_env_var_applies_when_param_unset(monkeypatch):
 
 
 @respx.mock
-def test_prompts_only_constructor_kwarg_applies_to_sync_upload(monkeypatch):
+def test_prompts_only_constructor_kwarg_applies_to_sync_upload(monkeypatch: pytest.MonkeyPatch):
     import litellm
 
     monkeypatch.setattr(litellm, "s3_callback_params", {})
@@ -2436,7 +2444,7 @@ def test_prompts_only_constructor_kwarg_applies_to_sync_upload(monkeypatch):
 
 
 @pytest.mark.parametrize("callback_name", ["s3", "s3_v2"])
-def test_prompts_only_toggle_is_exposed_to_admin_ui_for_both_s3_callbacks(callback_name):
+def test_prompts_only_toggle_is_exposed_to_admin_ui_for_both_s3_callbacks(callback_name: str):
     from litellm.integrations.custom_logger import CustomLogger
 
     assert "S3_LOG_PROMPTS_ONLY" in CustomLogger.get_callback_env_vars(callback_name)

From 251aeea97d4e67b5baf4238d851d365f239b5c2e Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 23:56:31 +0000
Subject: [PATCH 08/76] fix(ui): show the S3 label when editing the s3_v2
 callback

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ui/litellm-dashboard/src/components/settings.test.tsx | 1 +
 ui/litellm-dashboard/src/components/settings.tsx      | 8 ++++----
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/settings.test.tsx b/ui/litellm-dashboard/src/components/settings.test.tsx
index c24fa00438a..4ba5dd23fd1 100644
--- a/ui/litellm-dashboard/src/components/settings.test.tsx
+++ b/ui/litellm-dashboard/src/components/settings.test.tsx
@@ -393,6 +393,7 @@ describe("Settings", () => {
 
     const promptsOnlySwitch = await screen.findByRole("switch", { name: "Log Prompts Only" });
     expect(promptsOnlySwitch).not.toBeChecked();
+    expect(within(screen.getByRole("dialog")).getByRole("combobox", { name: "Callback" })).toHaveValue("S3");
 
     await user.click(promptsOnlySwitch);
     await user.click(within(screen.getByRole("dialog")).getByRole("button", { name: "Save Changes" }));
diff --git a/ui/litellm-dashboard/src/components/settings.tsx b/ui/litellm-dashboard/src/components/settings.tsx
index c0daeac3b72..9247f22ec28 100644
--- a/ui/litellm-dashboard/src/components/settings.tsx
+++ b/ui/litellm-dashboard/src/components/settings.tsx
@@ -178,7 +178,7 @@ export const CallbackSelector: React.FC<CallbackSelectorProps> = ({
 }) => {
   const { control } = useFormContext<CallbackFormValues>();
   const inputId = React.useId();
-  const selectedConfig = callbackConfigs.find((config) => config.id === selectedCallback) ?? null;
+  const selectedConfig = findCallbackConfig(callbackConfigs, selectedCallback) ?? null;
 
   return (
     <Controller
@@ -251,10 +251,10 @@ interface CallbackConfigWithParams {
   dynamic_params?: Record<string, DynamicParamConfig>;
 }
 
-const findCallbackConfig = (
-  callbackConfigs: readonly CallbackConfigWithParams[],
+const findCallbackConfig = <T extends { id: string }>(
+  callbackConfigs: readonly T[],
   callbackName: string | null,
-): CallbackConfigWithParams | undefined => {
+): T | undefined => {
   if (!callbackName) {
     return undefined;
   }

From 9541b0734b5aee13bd386a23068504d438424247 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 00:35:45 +0000
Subject: [PATCH 09/76] refactor(keys): drop status helper docstrings and test
 /key/list status through the endpoint

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../key_management_endpoints.py               | 16 ++-----
 .../test_key_management_endpoints.py          | 46 +++++++++++++------
 2 files changed, 37 insertions(+), 25 deletions(-)

diff --git a/litellm/proxy/management_endpoints/key_management_endpoints.py b/litellm/proxy/management_endpoints/key_management_endpoints.py
index 7a363729541..802a7c3e469 100644
--- a/litellm/proxy/management_endpoints/key_management_endpoints.py
+++ b/litellm/proxy/management_endpoints/key_management_endpoints.py
@@ -6241,7 +6241,6 @@ class _KeyStatusSource(BaseModel):
 
 
 def _derive_key_status(row: Mapping[str, object], now: datetime) -> KeyStatus:
-    """Status of a live key row; mirrors the partition `_build_status_where_clause` applies at query time."""
     source: Final = _KeyStatusSource.model_validate(row)
     if source.blocked is True:
         return "revoked"
@@ -6651,16 +6650,11 @@ def _not_blocked_where_clause() -> dict[str, object]:
 
 
 def _build_status_where_clause(status_filter: str | None, now: datetime) -> dict[str, object] | None:
-    """Live-table clause for a status filter; None when the status needs no clause (deleted rows live elsewhere)."""
-    match status_filter:
-        case "revoked":
-            return {"blocked": True}
-        case "expired":
-            return {"AND": [_not_blocked_where_clause(), _build_expires_where_clause("expired", now)]}
-        case "active":
-            return {"AND": [_not_blocked_where_clause(), _build_expires_where_clause("active", now)]}
-        case _:
-            return None
+    if status_filter == "revoked":
+        return {"blocked": True}
+    if status_filter in ("expired", "active"):
+        return {"AND": [_not_blocked_where_clause(), _build_expires_where_clause(status_filter, now)]}
+    return None
 
 
 def _build_key_search_where(search: str) -> KeySearchWhere:
diff --git a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
index 852b8632846..a8ff860c7c9 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
@@ -6020,22 +6020,46 @@ async def test_list_keys_with_invalid_status():
 @pytest.mark.asyncio
 @pytest.mark.parametrize("status_filter", ["active", "expired", "revoked"])
 async def test_list_keys_accepts_live_status_filters(monkeypatch, status_filter):
-    """LIT-1650: /key/list used to 400 on every status but "deleted"; the live statuses reach the helper."""
     from unittest.mock import Mock
 
-    from litellm.proxy.management_endpoints import key_management_endpoints
+    from litellm.proxy.management_endpoints.key_management_endpoints import list_keys
 
-    helper = AsyncMock(return_value={"keys": [], "total_count": 0, "current_page": 1, "total_pages": 0})
-    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", AsyncMock())
-    monkeypatch.setattr(key_management_endpoints, "_list_key_helper", helper)
-    await key_management_endpoints.list_keys(
+    live_row = MagicMock()
+    live_row.model_dump.return_value = {"token": "hashed_live_token", "object_permission_id": None}
+    mock_prisma_client = AsyncMock()
+    mock_prisma_client.db.litellm_verificationtoken.find_many = AsyncMock(return_value=[live_row])
+    mock_prisma_client.db.litellm_verificationtoken.count = AsyncMock(return_value=1)
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_many = AsyncMock(return_value=[])
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+
+    response = await list_keys(
         request=Mock(),
         user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN),
+        page=1,
+        size=10,
+        user_id=None,
+        team_id=None,
+        organization_id=None,
+        key_hash=None,
+        key_alias=None,
+        search=None,
+        return_full_object=False,
+        include_team_keys=False,
+        include_created_by_keys=False,
+        sort_by=None,
+        sort_order="desc",
+        expand=None,
         status=status_filter,
+        project_id=None,
+        access_group_id=None,
+        agent_id=None,
+        substring_matching=False,
+        expires=None,
     )
 
-    assert helper.await_args is not None
-    assert helper.await_args.kwargs["status"] == status_filter
+    assert response["keys"] == ["hashed_live_token"]
+    assert response["total_count"] == 1
+    mock_prisma_client.db.litellm_deletedverificationtoken.find_many.assert_not_called()
 
 
 def _status_filter_where(status_filter: str | None) -> Mapping[str, object]:
@@ -6054,7 +6078,6 @@ def _status_filter_where(status_filter: str | None) -> Mapping[str, object]:
 
 
 def test_build_key_filter_conditions_status_filter_partitions_live_keys():
-    """LIT-1650: active, expired and revoked are disjoint predicates over blocked + expires on the live table."""
     not_blocked = {"OR": [{"blocked": None}, {"blocked": False}]}
 
     revoked_where = _status_filter_where("revoked")
@@ -6072,13 +6095,11 @@ def test_build_key_filter_conditions_status_filter_partitions_live_keys():
 
 
 def test_build_key_filter_conditions_deleted_status_adds_no_live_clause():
-    """Deleted rows live in the archive table, so the status must not narrow the live-table query."""
     assert _status_filter_where("deleted") == _status_filter_where(None)
 
 
 @pytest.mark.asyncio
 async def test_list_key_helper_revoked_status_filters_live_table_on_blocked():
-    """LIT-1650: status="revoked" stays on the live table and narrows it to blocked keys."""
     mock_prisma_client = AsyncMock()
     mock_find_many = AsyncMock(return_value=[])
     mock_prisma_client.db.litellm_verificationtoken.find_many = mock_find_many
@@ -6123,7 +6144,6 @@ def _archived_key_row(token: str, user_id: str) -> MagicMock:
 
 @pytest.mark.asyncio
 async def test_info_key_fn_serves_deleted_key_from_archive(monkeypatch):
-    """LIT-1650: /key/info falls back to LiteLLM_DeletedVerificationToken and reports status="deleted"."""
     from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
 
     hashed = "hashed_deleted_token"
@@ -6153,7 +6173,6 @@ async def test_info_key_fn_serves_deleted_key_from_archive(monkeypatch):
 
 @pytest.mark.asyncio
 async def test_info_key_fn_archived_key_keeps_owner_authorization(monkeypatch):
-    """An archived key is still scoped: a different internal user gets 403, the owner gets the record."""
     from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
 
     hashed = "hashed_deleted_token"
@@ -6210,7 +6229,6 @@ async def test_info_key_fn_unknown_key_still_404s(monkeypatch):
     ],
 )
 async def test_info_key_fn_reports_live_key_status(monkeypatch, blocked, expires, expected_status):
-    """LIT-1650: live keys carry the same status vocabulary /key/list filters on."""
     from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
 
     mock_prisma_client = AsyncMock()

From 260ff5f491e08d0c357a39c8b99a286403da8255 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Tue, 15 Sep 2026 23:39:29 +0000
Subject: [PATCH 10/76] feat(team): team-level model_max_budget with key-level
 overrides

A team can now carry a per-model budget map that every key on the team
inherits. A key's own model_max_budget entry for the same model takes
precedence, so it is gated on and billed to the key alone.

Backend: NewTeamRequest/UpdateTeamRequest accept model_max_budget (validated
like the key-level field, enterprise gated); the value is hydrated onto
UserAPIKeyAuth via the token view, TeamGrants and the carried budget state;
_check_team_model_budget enforces it in the centralized common checks; the
limiter meters spend under team_model_spend:<team>:<model>:<duration> and
skips the team counter when the key overrides; /team/update lets only a
proxy admin raise, re-window or drop a cap; /team/info exposes usage.
The Anthropic context-management compaction summary subrequest runs the
same team gate. Both fallback token-view SQL definitions project the column.

UI: team create and edit forms reuse the key-level ModelMaxBudgetEditor,
premium gated, sending {} to clear and omitting unchanged fields.

A key entry overrides the team cap only when it spend-gates the model
(non-negative max_budget); a row that only carries tpm/rpm limits or a
negative cap leaves the team cap in force.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../context_management/editors/compact.py     |  27 +-
 litellm/proxy/_types.py                       |  16 ++
 litellm/proxy/auth/team_grants.py             |   2 +
 litellm/proxy/auth/user_api_key_auth.py       |  47 +++
 litellm/proxy/db/create_views.py              |   1 +
 .../proxy/hooks/model_max_budget_limiter.py   |  58 +++-
 litellm/proxy/litellm_pre_call_utils.py       |   1 +
 .../management_endpoints/common_utils.py      |  51 ++++
 .../management_endpoints/team_endpoints.py    |  77 ++++-
 .../pass_through_endpoints.py                 |   1 +
 .../spend_tracking/carried_budget_state.py    |   1 +
 litellm/proxy/utils.py                        |   2 +
 ...test_unit_test_max_model_budget_limiter.py | 267 ++++++++++++++++++
 .../context_management/test_compact.py        |  74 +++++
 .../proxy/auth/test_team_grants.py            |   2 +
 .../proxy/auth/test_user_api_key_auth.py      |  68 +++++
 .../proxy/db/test_create_views.py             |   1 +
 .../management_endpoints/test_common_utils.py |  52 ++++
 .../test_team_endpoints.py                    | 229 +++++++++++++++
 .../test_carried_budget_state.py              |  13 +
 .../test_prisma_client_get_data.py            |  11 +-
 .../src/components/Teams.test.tsx             |  31 ++
 ui/litellm-dashboard/src/components/Teams.tsx |  15 +
 .../key_team_helpers/ModelMaxBudgetEditor.tsx |   1 +
 .../src/components/team/TeamInfo.test.tsx     |  93 ++++++
 .../src/components/team/TeamInfo.tsx          |  36 +++
 ui/litellm-dashboard/src/lib/http/schema.d.ts |  27 ++
 27 files changed, 1192 insertions(+), 12 deletions(-)

diff --git a/litellm/llms/anthropic/experimental_pass_through/context_management/editors/compact.py b/litellm/llms/anthropic/experimental_pass_through/context_management/editors/compact.py
index fb6a1c40253..ecaf8f2e7e1 100644
--- a/litellm/llms/anthropic/experimental_pass_through/context_management/editors/compact.py
+++ b/litellm/llms/anthropic/experimental_pass_through/context_management/editors/compact.py
@@ -78,6 +78,7 @@ _PROPAGATED_METADATA_KEYS: Final = (
     "user_api_key_end_user_id",
     "user_api_end_user_max_budget",
     "user_api_key_model_max_budget",
+    "user_api_key_team_model_max_budget",
     "user_api_key_user_model_max_budget",
     "user_api_key_end_user_model_max_budget",
     "litellm_call_id",
@@ -395,9 +396,9 @@ async def _check_summary_model_budget(
     ``user_api_key_auth`` runs for the client-requested model. Returns True outside the proxy or when no
     per-model budget is configured.
 
-    All three scopes are checked because the summary's spend is charged to all
-    three: this file propagates the key, user and end-user budgets into the
-    subrequest's metadata, so enforcing only two of them would let compaction
+    Every scope is checked because the summary's spend is charged to every
+    scope: this file propagates the key, team, user and end-user budgets into the
+    subrequest's metadata, so skipping one of them would let compaction
     increment a counter it can never be refused by.
     """
     if user_api_key_auth is None:
@@ -444,6 +445,26 @@ async def _check_summary_model_budget(
             )
             return False
 
+    team_model_max_budget: Final = user_api_key_auth.team_model_max_budget
+    team_id: Final = user_api_key_auth.team_id
+    if isinstance(team_model_max_budget, dict) and team_model_max_budget and team_id is not None:
+        try:
+            await model_max_budget_limiter.is_team_within_model_budget(
+                team_id=team_id,
+                team_model_max_budget=team_model_max_budget,
+                key_model_max_budget=model_max_budget if isinstance(model_max_budget, dict) else None,
+                model=summary_model,
+            )
+        except litellm.BudgetExceededError:
+            return False
+        except Exception as e:  # noqa: BLE001  # a budget gate denies on any failure, as the other scopes do
+            verbose_logger.warning(
+                "compact_20260112: unexpected error during team model-budget check for summary_model=%s; denying: %s",
+                summary_model,
+                e,
+            )
+            return False
+
     end_user_model_max_budget: Final[dict[str, object] | None] = getattr(
         user_api_key_auth, "end_user_model_max_budget", None
     )
diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py
index ad55fa5d2be..72852c7c20c 100644
--- a/litellm/proxy/_types.py
+++ b/litellm/proxy/_types.py
@@ -2002,6 +2002,13 @@ RouterSettingsDict = Annotated[
 class NewTeamRequest(TeamBase):
     router_settings: RouterSettingsDict | None = None
     model_aliases: dict | None = None
+    model_max_budget: GenericBudgetConfigType | None = Field(
+        default=None,
+        description=(
+            "Max budget per model for every key on the team, overridable per key "
+            "(e.g. {'gpt-4o': {'max_budget': 10, 'budget_duration': '1d'}})"
+        ),
+    )
     tags: list | None = None
     guardrails: list[str] | None = None
     policies: list[str] | None = None
@@ -2103,6 +2110,13 @@ class UpdateTeamRequest(LiteLLMPydanticObjectBase):
     access_group_ids: list[str] | None = None
     budget_limits: list[BudgetLimitEntry] | None = None  # multiple concurrent budget windows
     default_team_member_models: list[str] | None = None  # default allowed_models seeded onto new team members
+    model_max_budget: GenericBudgetConfigType | None = Field(
+        default=None,
+        description=(
+            "Max budget per model for every key on the team, overridable per key "
+            "(e.g. {'gpt-4o': {'max_budget': 10, 'budget_duration': '1d'}})"
+        ),
+    )
 
 
 class PatchTeamRequest(UpdateTeamRequest):
@@ -3030,6 +3044,7 @@ class LiteLLM_VerificationTokenView(LiteLLM_VerificationToken):
     team_tpd_limit: int | None = None
     team_max_budget: float | None = None
     team_soft_budget: float | None = None
+    team_model_max_budget: dict[str, object] | None = None
     team_models: list = []
     team_blocked: bool = False
     soft_budget: float | None = None
@@ -4444,6 +4459,7 @@ class TeamInfoResponseObjectTeamTable(LiteLLM_TeamTable):
     # Parent org's model ceiling, reported only to callers who can manage the team.
     # None = no org or not a manager; [] or ["all-proxy-models"] = no ceiling.
     organization_models: list[str] | None = None
+    model_max_budget_usage: Mapping[str, Mapping[str, object]] | None = None
 
 
 class TeamInfoResponseObject(TypedDict):
diff --git a/litellm/proxy/auth/team_grants.py b/litellm/proxy/auth/team_grants.py
index 0421659c331..2029ee342ae 100644
--- a/litellm/proxy/auth/team_grants.py
+++ b/litellm/proxy/auth/team_grants.py
@@ -59,6 +59,7 @@ class TeamGrants(TypedDict, total=False):
     team_tpd_limit: ReadOnly[int | None]
     team_max_budget: ReadOnly[float | None]
     team_soft_budget: ReadOnly[float | None]
+    team_model_max_budget: ReadOnly[dict[str, object] | None]
     team_spend: ReadOnly[float | None]
     team_models: ReadOnly[Sequence[str]]
     team_blocked: ReadOnly[bool]
@@ -101,6 +102,7 @@ def team_grants(
         team_tpd_limit=team_object.tpd_limit,
         team_max_budget=team_object.max_budget,
         team_soft_budget=team_object.soft_budget,
+        team_model_max_budget=team_object.model_max_budget,
         team_spend=team_object.spend,
         team_models=tuple(team_object.models),
         team_blocked=team_object.blocked,
diff --git a/litellm/proxy/auth/user_api_key_auth.py b/litellm/proxy/auth/user_api_key_auth.py
index 5958a68f975..0a5aa9ea793 100644
--- a/litellm/proxy/auth/user_api_key_auth.py
+++ b/litellm/proxy/auth/user_api_key_auth.py
@@ -264,6 +264,16 @@ class _UserModelBudgetLimiter(Protocol):
     ) -> bool: ...
 
 
+class _TeamModelBudgetLimiter(Protocol):
+    async def is_team_within_model_budget(
+        self,
+        team_id: str,
+        team_model_max_budget: Mapping[str, object],
+        key_model_max_budget: Mapping[str, object] | None,
+        model: str,
+    ) -> bool: ...
+
+
 class _TokenTeamModels(Protocol):
     @property
     def team_models(self) -> list[str]: ...
@@ -334,6 +344,25 @@ async def _check_user_model_budget(
         )
 
 
+async def _check_team_model_budget(
+    valid_token: UserAPIKeyAuth,
+    model_max_budget_limiter: _TeamModelBudgetLimiter,
+    models: list[str],
+) -> None:
+    """Enforce the team's `model_max_budget` for every requested model the key does not override."""
+    team_model_max_budget: Final = valid_token.team_model_max_budget
+    if valid_token.team_id is None or not team_model_max_budget:
+        return
+    key_model_max_budget: Final[Mapping[str, object] | None] = valid_token.model_max_budget
+    for model_name in models:
+        await model_max_budget_limiter.is_team_within_model_budget(
+            team_id=valid_token.team_id,
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=key_model_max_budget,
+            model=model_name,
+        )
+
+
 async def _check_key_model_budget_with_fallback(
     valid_token: UserAPIKeyAuth,
     model_max_budget_limiter: _KeyModelBudgetLimiter,
@@ -2369,6 +2398,7 @@ async def _user_api_key_auth_builder(
                         team_id=valid_token.team_id,
                         max_budget=valid_token.team_max_budget,
                         soft_budget=valid_token.team_soft_budget,
+                        model_max_budget=valid_token.team_model_max_budget,
                         spend=valid_token.team_spend,
                         tpm_limit=valid_token.team_tpm_limit,
                         rpm_limit=valid_token.team_rpm_limit,
@@ -2523,6 +2553,7 @@ def _team_obj_from_token(valid_token: UserAPIKeyAuth) -> LiteLLM_TeamTableCached
         team_id=valid_token.team_id,
         max_budget=valid_token.team_max_budget,
         soft_budget=valid_token.team_soft_budget,
+        model_max_budget=valid_token.team_model_max_budget,
         spend=valid_token.team_spend,
         tpm_limit=valid_token.team_tpm_limit,
         rpm_limit=valid_token.team_rpm_limit,
@@ -2592,6 +2623,7 @@ async def _run_centralized_common_checks(
         litellm_proxy_admin_name,
         llm_router,
         master_key,
+        model_max_budget_limiter,
         prisma_client,
         proxy_logging_obj,
         user_api_key_cache,
@@ -2864,6 +2896,21 @@ async def _run_centralized_common_checks(
     finally:
         release_spend_counter_batch()
 
+    if not skip_budget_checks:
+        await _check_team_model_budget(
+            valid_token=user_api_key_auth_obj,
+            model_max_budget_limiter=model_max_budget_limiter,
+            models=_get_model_names_for_budget_checks(
+                model=_get_model_from_request_context(
+                    request_data=request_data,
+                    route=route,
+                    request=request,
+                    llm_router=llm_router,
+                    team_id=user_api_key_auth_obj.team_id,
+                )
+            ),
+        )
+
     await _reserve_budget_after_common_checks(
         user_api_key_auth_obj=user_api_key_auth_obj,
         request=request,
diff --git a/litellm/proxy/db/create_views.py b/litellm/proxy/db/create_views.py
index d3f3de730ab..f7131091c0b 100644
--- a/litellm/proxy/db/create_views.py
+++ b/litellm/proxy/db/create_views.py
@@ -78,6 +78,7 @@ async def create_missing_views(db: SupportsRawQueries) -> None:
                 v.*,
                 t.spend AS team_spend,
                 t.max_budget AS team_max_budget,
+                t.model_max_budget AS team_model_max_budget,
                 t.tpm_limit AS team_tpm_limit,
                 t.rpm_limit AS team_rpm_limit,
                 t.tpd_limit AS team_tpd_limit,
diff --git a/litellm/proxy/hooks/model_max_budget_limiter.py b/litellm/proxy/hooks/model_max_budget_limiter.py
index efaaab277a9..bbfc7325f40 100644
--- a/litellm/proxy/hooks/model_max_budget_limiter.py
+++ b/litellm/proxy/hooks/model_max_budget_limiter.py
@@ -19,12 +19,14 @@ from litellm.types.utils import BudgetConfig, StandardLoggingPayload
 VIRTUAL_KEY_SPEND_CACHE_KEY_PREFIX: Final = "virtual_key_spend"
 END_USER_SPEND_CACHE_KEY_PREFIX: Final = "end_user_model_spend"
 USER_SPEND_CACHE_KEY_PREFIX: Final = "user_model_spend"
+TEAM_SPEND_CACHE_KEY_PREFIX: Final = "team_model_spend"
 
 _SPEND_CACHE_KEY_PREFIXES: Final = MappingProxyType(
     {
         Litellm_EntityType.KEY: VIRTUAL_KEY_SPEND_CACHE_KEY_PREFIX,
         Litellm_EntityType.USER: USER_SPEND_CACHE_KEY_PREFIX,
         Litellm_EntityType.END_USER: END_USER_SPEND_CACHE_KEY_PREFIX,
+        Litellm_EntityType.TEAM: TEAM_SPEND_CACHE_KEY_PREFIX,
     }
 )
 
@@ -37,6 +39,7 @@ _BUDGET_START_TIME_KEY_PREFIXES: Final = MappingProxyType(
         Litellm_EntityType.KEY: "virtual_key_budget_start_time",
         Litellm_EntityType.USER: "user_model_budget_start_time",
         Litellm_EntityType.END_USER: "end_user_budget_start_time",
+        Litellm_EntityType.TEAM: "team_model_budget_start_time",
     }
 )
 
@@ -139,6 +142,18 @@ def resolve_model_budget(model: str, model_max_budget: Mapping[str, object]) ->
     return None
 
 
+def team_model_budget_applies(model: str, key_model_max_budget: Mapping[str, object] | None) -> bool:
+    """A key entry that spend-gates `model` overrides the team cap: it is then gated on and billed to the key alone."""
+    if not key_model_max_budget:
+        return True
+    resolved: Final = resolve_model_budget(model=model, model_max_budget=key_model_max_budget)
+    return resolved is None or not _spend_gated(resolved.budget_config)
+
+
+def _spend_gated(budget_config: BudgetConfig) -> bool:
+    return budget_config.max_budget is not None and budget_config.max_budget >= 0
+
+
 def _budget_model_candidates(model: str) -> tuple[str, ...]:
     """Names a budget may be configured under for a request on `model`, most specific first.
 
@@ -346,6 +361,30 @@ class _PROXY_VirtualKeyModelMaxBudgetLimiter(RouterBudgetLimiting):
             exceeded_message=f"LiteLLM End User: {end_user_id}, exceeded budget for model={model}",
         )
 
+    async def is_team_within_model_budget(
+        self,
+        team_id: str,
+        team_model_max_budget: Mapping[str, object],
+        key_model_max_budget: Mapping[str, object] | None,
+        model: str,
+    ) -> bool:
+        """
+        Check if the team is within the model budget, unless the key's own
+        `model_max_budget` overrides it for `model`
+
+        Raises:
+            BudgetExceededError: If the team has exceeded the model budget
+        """
+        if not team_model_budget_applies(model=model, key_model_max_budget=key_model_max_budget):
+            return True
+        return await self._is_entity_within_model_budget(
+            entity_type=Litellm_EntityType.TEAM,
+            entity_id=team_id,
+            model_max_budget=team_model_max_budget,
+            model=model,
+            exceeded_message=f"LiteLLM Team: {team_id}, exceeded budget for model={model}",
+        )
+
     async def _is_entity_within_model_budget(
         self,
         entity_type: Litellm_EntityType,
@@ -456,11 +495,26 @@ class _PROXY_VirtualKeyModelMaxBudgetLimiter(RouterBudgetLimiting):
             return
 
         response_cost: Final[float] = standard_logging_payload.get("response_cost", 0)
+        key_model_max_budget: Final = _metadata.get("user_api_key_model_max_budget")
         entity_budgets: Final = (
             (
                 Litellm_EntityType.KEY,
                 payload_metadata.get("user_api_key_hash"),
-                _metadata.get("user_api_key_model_max_budget"),
+                key_model_max_budget,
+            ),
+            (
+                Litellm_EntityType.TEAM,
+                payload_metadata.get("user_api_key_team_id"),
+                (
+                    _metadata.get("user_api_key_team_model_max_budget")
+                    if team_model_budget_applies(
+                        model=model,
+                        key_model_max_budget=(
+                            key_model_max_budget if isinstance(key_model_max_budget, Mapping) else None
+                        ),
+                    )
+                    else None
+                ),
             ),
             (
                 Litellm_EntityType.USER,
@@ -478,7 +532,7 @@ class _PROXY_VirtualKeyModelMaxBudgetLimiter(RouterBudgetLimiting):
         if not resolved_budgets:
             verbose_proxy_logger.debug(
                 "Not running _PROXY_VirtualKeyModelMaxBudgetLimiter.async_log_success_event: "
-                "no key, user or end-user model_max_budget covers model=%s",
+                "no key, team, user or end-user model_max_budget covers model=%s",
                 model,
             )
             return
diff --git a/litellm/proxy/litellm_pre_call_utils.py b/litellm/proxy/litellm_pre_call_utils.py
index 563db811edc..93374eb099b 100644
--- a/litellm/proxy/litellm_pre_call_utils.py
+++ b/litellm/proxy/litellm_pre_call_utils.py
@@ -2287,6 +2287,7 @@ async def add_litellm_data_to_request(
     # Team spend, budget - used by prometheus.py
     data[_metadata_variable_name]["user_api_key_team_max_budget"] = user_api_key_dict.team_max_budget
     data[_metadata_variable_name]["user_api_key_team_spend"] = user_api_key_dict.team_spend
+    data[_metadata_variable_name]["user_api_key_team_model_max_budget"] = user_api_key_dict.team_model_max_budget
     data[_metadata_variable_name]["user_api_key_request_route"] = user_api_key_dict.request_route
 
     # API Key spend, budget - used by prometheus.py
diff --git a/litellm/proxy/management_endpoints/common_utils.py b/litellm/proxy/management_endpoints/common_utils.py
index 98155ad6839..973311608ed 100644
--- a/litellm/proxy/management_endpoints/common_utils.py
+++ b/litellm/proxy/management_endpoints/common_utils.py
@@ -55,6 +55,7 @@ def validate_budget_duration(budget_duration: str | None, status_code: int = 400
 from litellm._logging import verbose_proxy_logger
 from litellm.caching import DualCache
 from litellm.proxy._types import (
+    CommonProxyErrors,
     KeyRequestBase,
     LiteLLM_ManagementEndpoint_MetadataFields,
     LiteLLM_ManagementEndpoint_MetadataFields_Premium,
@@ -73,12 +74,62 @@ from litellm.proxy._types import (  # noqa: F401  re-exported
 from litellm.proxy.common_utils.timezone_utils import get_budget_reset_time
 from litellm.proxy.utils import _premium_user_check
 from litellm.repositories.team_repository import TeamRepository
+from litellm.types.utils import BudgetConfig
 
 if TYPE_CHECKING:
     from litellm.proxy._types import NewProjectRequest, UpdateProjectRequest
     from litellm.proxy.utils import PrismaClient, ProxyLogging
 
 
+def validate_team_model_max_budget(
+    model_max_budget: Mapping[str, BudgetConfig] | None,
+    premium_user: bool,
+) -> None:
+    """Reject a team `model_max_budget` the limiter could not enforce (no duration, bad cap, tpm/rpm limits)."""
+    if not model_max_budget:
+        return
+    if premium_user is not True:
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "error": f"Setting model_max_budget on a team is an enterprise feature. {CommonProxyErrors.not_premium_user.value}"
+            },
+        )
+    for model_name, budget_config in model_max_budget.items():
+        if not model_name.strip():
+            raise HTTPException(
+                status_code=400,
+                detail={"error": "model_max_budget keys must be non-empty model names"},
+            )
+        max_budget = budget_config.max_budget
+        if max_budget is None or not math.isfinite(max_budget) or max_budget < 0:
+            raise HTTPException(
+                status_code=400,
+                detail={
+                    "error": (
+                        f"model_max_budget[{model_name!r}].max_budget must be a non-negative finite number. "
+                        f"Received: {max_budget}"
+                    )
+                },
+            )
+        if budget_config.budget_duration is None:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": f"model_max_budget[{model_name!r}] requires a budget_duration, e.g. '1d' or '30d'"},
+            )
+        validate_budget_duration(budget_config.budget_duration)
+        if budget_config.tpm_limit is not None or budget_config.rpm_limit is not None:
+            raise HTTPException(
+                status_code=400,
+                detail={
+                    "error": (
+                        f"model_max_budget[{model_name!r}] tpm_limit/rpm_limit are not enforced on a team; "
+                        "set per-model rate limits on the key instead"
+                    )
+                },
+            )
+
+
 def require_caller_user_id_for_non_admin(
     user_api_key_dict: UserAPIKeyAuth,
 ) -> str:
diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py
index e719d6d761a..6fb1ef5ec93 100644
--- a/litellm/proxy/management_endpoints/team_endpoints.py
+++ b/litellm/proxy/management_endpoints/team_endpoints.py
@@ -22,7 +22,7 @@ from typing import TYPE_CHECKING, Annotated, Final, NamedTuple, NoReturn, Protoc
 
 import fastapi
 from fastapi import APIRouter, Depends, Header, HTTPException, Request, status
-from pydantic import BaseModel, JsonValue
+from pydantic import BaseModel, JsonValue, ValidationError
 from typing_extensions import ReadOnly, TypedDict
 
 import litellm
@@ -38,6 +38,7 @@ from litellm.proxy._types import (
     DeleteTeamRequest,
     LiteLLM_AuditLogs,
     LiteLLM_DeletedTeamTable,
+    Litellm_EntityType,
     LiteLLM_ManagementEndpoint_MetadataFields,
     LiteLLM_ManagementEndpoint_MetadataFields_Premium,
     LiteLLM_ModelTable,
@@ -95,6 +96,7 @@ from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.proxy.common_utils.callback_utils import encrypt_callback_vars
 from litellm.proxy.common_utils.json_merge_patch import apply_json_merge_patch
 from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
+from litellm.proxy.hooks.model_max_budget_limiter import build_model_max_budget_usage
 from litellm.proxy.management_endpoints.common_daily_activity import (
     get_daily_activity_aggregated,
 )
@@ -108,6 +110,7 @@ from litellm.proxy.management_endpoints.common_utils import (
     _upsert_budget_and_membership,
     _user_has_admin_view,
     validate_budget_duration,
+    validate_team_model_max_budget,
 )
 from litellm.proxy.management_endpoints.organization_endpoints import (
     add_member_to_organization,
@@ -177,6 +180,7 @@ from litellm.types.proxy.management_endpoints.team_endpoints import (
     TeamUserSpendRow,
     UpdateTeamMemberPermissionsRequest,
 )
+from litellm.types.utils import BudgetConfig
 
 if TYPE_CHECKING:
     from prisma import Prisma
@@ -1170,6 +1174,56 @@ def _check_team_budget_update_authority(
         )
 
 
+def _existing_model_cap(raw_budget_config: object) -> BudgetConfig | None:
+    try:
+        return BudgetConfig.model_validate(raw_budget_config)
+    except ValidationError:
+        return None
+
+
+def _check_team_model_budget_update_authority(
+    data: UpdateTeamRequest,
+    user_api_key_dict: UserAPIKeyAuth,
+    existing_model_max_budget: Mapping[str, object] | None,
+) -> None:
+    """Like `_check_team_budget_update_authority`: only a proxy admin may raise, re-window or drop a per-model cap."""
+    if user_api_key_dict.user_role == LitellmUserRoles.PROXY_ADMIN:
+        return
+    if "model_max_budget" not in data.model_fields_set or not existing_model_max_budget:
+        return
+    requested: Final[Mapping[str, BudgetConfig]] = data.model_max_budget or {}
+    for model_name, raw_existing in existing_model_max_budget.items():
+        existing = _existing_model_cap(raw_existing)
+        if existing is None or existing.max_budget is None:
+            continue
+        proposed = requested.get(model_name)
+        if proposed is None:
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": (
+                        f"Only a proxy admin can remove a team's model_max_budget for {model_name!r}. "
+                        f"Current max_budget={existing.max_budget}."
+                    )
+                },
+            )
+        if (
+            proposed.max_budget is None
+            or proposed.max_budget > existing.max_budget
+            or proposed.budget_duration != existing.budget_duration
+        ):
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "error": (
+                        f"Only a proxy admin can raise a team's model_max_budget for {model_name!r} or change its "
+                        f"budget_duration. Current max_budget={existing.max_budget} per {existing.budget_duration}, "
+                        f"requested={proposed.max_budget} per {proposed.budget_duration}."
+                    )
+                },
+            )
+
+
 def _should_auto_add_team_creator(
     user_api_key_dict: UserAPIKeyAuth,
     general_settings: Mapping[str, object],
@@ -1230,6 +1284,7 @@ async def new_team(
     - prompts: Optional[List[str]] - List of prompts that the team is allowed to use.
     - organization_id: Optional[str] - The organization id of the team. Default is None. Create via `/organization/new`.
     - model_aliases: Optional[dict] - Model aliases for the team. [Docs](https://docs.litellm.ai/docs/proxy/team_based_routing#create-team-with-model-alias)
+    - model_max_budget: Optional[dict] - Per-model max budget every key on the team inherits unless the key sets its own for that model. Example: {"gpt-4o": {"max_budget": 10, "budget_duration": "1d"}}
     - guardrails: Optional[List[str]] - Guardrails for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails)
     - policies: Optional[List[str]] - Policies for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails/guardrail_policies)
     - disable_global_guardrails: Optional[bool] - Whether to disable global guardrails for the key.
@@ -1291,6 +1346,7 @@ async def new_team(
             general_settings,
             litellm_proxy_admin_name,
             llm_router,
+            premium_user,
             prisma_client,
             user_api_key_cache,
         )
@@ -1321,6 +1377,7 @@ async def new_team(
 
         validate_budget_duration(data.budget_duration)
         validate_budget_duration(data.team_member_budget_duration)
+        validate_team_model_max_budget(model_max_budget=data.model_max_budget, premium_user=premium_user)
 
         if data.soft_budget is not None:
             if data.max_budget is not None:
@@ -1980,6 +2037,7 @@ async def update_team(
     - tags: Optional[List[str]] - Tags for [tracking spend](https://litellm.vercel.app/docs/proxy/enterprise#tracking-spend-for-custom-tags) and/or doing [tag-based routing](https://litellm.vercel.app/docs/proxy/tag_routing).
     - organization_id: Optional[str] - The organization id of the team. Default is None. Create via `/organization/new`.
     - model_aliases: Optional[dict] - Model aliases for the team. [Docs](https://docs.litellm.ai/docs/proxy/team_based_routing#create-team-with-model-alias)
+    - model_max_budget: Optional[dict] - Per-model max budget every key on the team inherits unless the key sets its own for that model. Example: {"gpt-4o": {"max_budget": 10, "budget_duration": "1d"}}
     - guardrails: Optional[List[str]] - Guardrails for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails)
     - policies: Optional[List[str]] - Policies for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails/guardrail_policies)
     - disable_global_guardrails: Optional[bool] - Whether to disable global guardrails for the key.
@@ -2031,6 +2089,7 @@ async def update_team(
         from litellm.proxy.proxy_server import (
             litellm_proxy_admin_name,
             llm_router,
+            premium_user,
             prisma_client,
             proxy_logging_obj,
             user_api_key_cache,
@@ -2069,6 +2128,7 @@ async def update_team(
 
         validate_budget_duration(data.budget_duration)
         validate_budget_duration(data.team_member_budget_duration)
+        validate_team_model_max_budget(model_max_budget=data.model_max_budget, premium_user=premium_user)
 
         existing_team_row = await _raw_team_db(TeamRepository(prisma_client)).find_unique(
             where={"team_id": data.team_id}
@@ -2204,8 +2264,15 @@ async def update_team(
                 user_api_key_dict=user_api_key_dict,
                 existing_team_max_budget=existing_team_row.max_budget,
             )
+        _check_team_model_budget_update_authority(
+            data=data,
+            user_api_key_dict=user_api_key_dict,
+            existing_model_max_budget=existing_team_row.model_max_budget,
+        )
 
         updated_kv = data.json(exclude_unset=True)
+        if "model_max_budget" in updated_kv and updated_kv["model_max_budget"] is None:
+            updated_kv["model_max_budget"] = {}
 
         # Drop server-owned metadata keys from caller input so they can only
         # be written by the same code path that creates the underlying rows.
@@ -4473,7 +4540,7 @@ async def team_info(
     ```
     """
     from litellm.proxy._types import TeamInfoResponseObjectTeamTable
-    from litellm.proxy.proxy_server import prisma_client
+    from litellm.proxy.proxy_server import model_max_budget_limiter, prisma_client
 
     try:
         if prisma_client is None:
@@ -4573,6 +4640,12 @@ async def team_info(
             update={  # mutable-ok: pydantic update payload
                 "members_with_roles": hydrated_members,
                 "organization_models": organization_models,
+                "model_max_budget_usage": await build_model_max_budget_usage(
+                    entity_type=Litellm_EntityType.TEAM,
+                    entity_id=team_id,
+                    model_max_budget=resolved_team_info.model_max_budget,
+                    cache=model_max_budget_limiter.dual_cache,
+                ),
             }
         )
 
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 686544d352c..de6f9cb7647 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -609,6 +609,7 @@ class HttpPassThroughEndpointHelpers(BasePassthroughUtils):
         # merely shares the name.
         if not request_dispatched_to_pass_through_endpoint(request):
             _metadata["user_api_key_model_max_budget"] = user_api_key_dict.model_max_budget
+            _metadata["user_api_key_team_model_max_budget"] = user_api_key_dict.team_model_max_budget
             _metadata["user_api_key_user_model_max_budget"] = user_api_key_dict.user_model_max_budget
             _metadata["user_api_key_end_user_model_max_budget"] = user_api_key_dict.end_user_model_max_budget
         _metadata.update(
diff --git a/litellm/proxy/spend_tracking/carried_budget_state.py b/litellm/proxy/spend_tracking/carried_budget_state.py
index efd3a78d211..da8bf60ebda 100644
--- a/litellm/proxy/spend_tracking/carried_budget_state.py
+++ b/litellm/proxy/spend_tracking/carried_budget_state.py
@@ -25,6 +25,7 @@ def carry_team_and_user_budget_state(
             budget_reset_at=team_object.budget_reset_at,
             max_budget=team_object.max_budget,
         )
+        valid_token.team_model_max_budget = team_object.model_max_budget  # rebind-ok: caller keeps this object
     if user_object is not None:
         valid_token.user_budget_snapshot = UserBudgetSnapshot(  # rebind-ok: same object the caller keeps using
             budget_reset_at=user_object.budget_reset_at,
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index 479bd0a55af..b77f25389c6 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -4319,6 +4319,7 @@ class PrismaClient:
                             v.*,
                             t.spend AS team_spend,
                             t.max_budget AS team_max_budget,
+                            t.model_max_budget AS team_model_max_budget,
                             t.tpm_limit AS team_tpm_limit,
                             t.rpm_limit AS team_rpm_limit,
                             t.tpd_limit AS team_tpd_limit
@@ -4758,6 +4759,7 @@ class PrismaClient:
                             t.spend AS team_spend, 
                             t.max_budget AS team_max_budget,
                             t.soft_budget AS team_soft_budget,
+                            t.model_max_budget AS team_model_max_budget,
                             t.tpm_limit AS team_tpm_limit,
                             t.rpm_limit AS team_rpm_limit,
                             t.tpd_limit AS team_tpd_limit,
diff --git a/tests/proxy_unit_tests/test_unit_test_max_model_budget_limiter.py b/tests/proxy_unit_tests/test_unit_test_max_model_budget_limiter.py
index 096efc33aaf..efe41e1da9a 100644
--- a/tests/proxy_unit_tests/test_unit_test_max_model_budget_limiter.py
+++ b/tests/proxy_unit_tests/test_unit_test_max_model_budget_limiter.py
@@ -587,6 +587,8 @@ def _success_kwargs(
     response_cost=0.5,
     key_hash=None,
     key_model_max_budget=None,
+    team_id=None,
+    team_model_max_budget=None,
     user_id=None,
     user_model_max_budget=None,
     end_user_id=None,
@@ -600,6 +602,7 @@ def _success_kwargs(
             "end_user": end_user_id,
             "metadata": {
                 "user_api_key_hash": key_hash,
+                "user_api_key_team_id": team_id,
                 "user_api_key_user_id": user_id,
                 "user_api_key_end_user_id": end_user_id,
             },
@@ -607,6 +610,7 @@ def _success_kwargs(
         "litellm_params": {
             "metadata": {
                 "user_api_key_model_max_budget": key_model_max_budget,
+                "user_api_key_team_model_max_budget": team_model_max_budget,
                 "user_api_key_user_model_max_budget": user_model_max_budget,
                 "user_api_key_end_user_model_max_budget": end_user_model_max_budget,
             },
@@ -1417,3 +1421,266 @@ async def test_spend_logged_on_one_replica_is_enforced_and_reported_on_another()
     replica_c = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=DualCache(redis_cache=shared_redis))
     with pytest.raises(litellm.BudgetExceededError):
         await replica_c.is_key_within_model_budget(user_api_key, "gpt-4")
+
+
+def _log_success(limiter, **kwargs):
+    return limiter.async_log_success_event(
+        _success_kwargs(**kwargs), response_obj=None, start_time=None, end_time=None
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "request_model",
+    ["gpt-4", "openai/gpt-4"],
+    ids=["bare_model", "provider_prefixed_model"],
+)
+async def test_team_model_budget_is_shared_by_every_key_without_an_override(request_model):
+    """
+    Two keys on the same team, neither carrying a matching key-level entry,
+    charge one team counter and are both refused once it is spent.
+    """
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {"gpt-4": {"budget_limit": 1.0, "time_period": "1d"}}
+    check = lambda: limiter.is_team_within_model_budget(
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+        key_model_max_budget=None,
+        model=request_model,
+    )
+
+    assert await check() is True
+    await _log_success(
+        limiter,
+        model_group=request_model,
+        response_cost=0.6,
+        key_hash="vk-a",
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+    )
+    assert await check() is True
+    await _log_success(
+        limiter,
+        model_group=request_model,
+        response_cost=0.6,
+        key_hash="vk-b",
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+    )
+
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:gpt-4:1d") == pytest.approx(1.2)
+    with pytest.raises(litellm.BudgetExceededError) as exc:
+        await check()
+    assert exc.value.entity_type == Litellm_EntityType.TEAM.value
+    assert await build_model_max_budget_usage(
+        entity_type=Litellm_EntityType.TEAM,
+        entity_id="team-1",
+        model_max_budget=team_model_max_budget,
+        cache=dual_cache,
+    ) == {"gpt-4": {"current_spend": pytest.approx(1.2), "budget_limit": 1.0, "time_period": "1d"}}
+
+
+@pytest.mark.asyncio
+async def test_key_override_replaces_the_team_cap_for_that_model():
+    """
+    A key with its own entry for the model is gated on the key counter alone:
+    the exhausted team counter does not block it, and its spend never lands on
+    the team counter.
+    """
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {"gpt-4": {"budget_limit": 1.0, "time_period": "1d"}}
+    key_model_max_budget = {"gpt-4": {"budget_limit": 5.0, "time_period": "1d"}}
+    await dual_cache.async_set_cache(key="team_model_spend:team-1:gpt-4:1d", value=9.0)
+
+    assert (
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=key_model_max_budget,
+            model="openai/gpt-4",
+        )
+        is True
+    )
+
+    await _log_success(
+        limiter,
+        model_group="openai/gpt-4",
+        response_cost=2.0,
+        key_hash="vk-override",
+        key_model_max_budget=key_model_max_budget,
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+    )
+
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:gpt-4:1d") == 9.0
+    assert await dual_cache.async_get_cache(key="virtual_key_spend:vk-override:gpt-4:1d") == 2.0
+
+
+@pytest.mark.asyncio
+async def test_key_entry_for_another_model_does_not_lift_the_team_cap():
+    """A key override only covers the model it names; other models stay on the team counter."""
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {"gpt-4": {"budget_limit": 1.0, "time_period": "1d"}}
+    key_model_max_budget = {"claude-3": {"budget_limit": 5.0, "time_period": "1d"}}
+
+    await _log_success(
+        limiter,
+        model_group="gpt-4",
+        response_cost=1.5,
+        key_hash="vk-other",
+        key_model_max_budget=key_model_max_budget,
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+    )
+
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:gpt-4:1d") == 1.5
+    with pytest.raises(litellm.BudgetExceededError):
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=key_model_max_budget,
+            model="gpt-4",
+        )
+
+
+@pytest.mark.asyncio
+async def test_team_budget_leaves_unconfigured_models_alone():
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {"gpt-4": {"budget_limit": 0.0, "time_period": "1d"}}
+
+    assert (
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=None,
+            model="claude-3",
+        )
+        is True
+    )
+    with patch.object(limiter, "_increment_spend_for_key", new_callable=AsyncMock) as mock_increment:
+        await _log_success(
+            limiter,
+            model_group="claude-3",
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+        )
+    mock_increment.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_team_counters_are_isolated_by_team_model_and_window():
+    """Same model on two teams, and two models with different windows on one team, never share a counter."""
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {
+        "gpt-4": {"budget_limit": 10.0, "time_period": "1d"},
+        "claude-3": {"budget_limit": 10.0, "time_period": "30d"},
+    }
+
+    for team_id, model in (("team-1", "gpt-4"), ("team-2", "gpt-4"), ("team-1", "claude-3")):
+        await _log_success(
+            limiter,
+            model_group=model,
+            response_cost=1.0,
+            team_id=team_id,
+            team_model_max_budget=team_model_max_budget,
+        )
+
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:gpt-4:1d") == 1.0
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-2:gpt-4:1d") == 1.0
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:claude-3:30d") == 1.0
+    assert await dual_cache.async_get_cache(key="team_model_budget_start_time:team-1:claude-3:30d") is not None
+
+
+@pytest.mark.asyncio
+async def test_malformed_team_entry_is_skipped_and_its_sibling_still_enforced():
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=DualCache())
+    team_model_max_budget = {
+        "gpt-4": {"budget_limit": "not-a-number", "time_period": "1d"},
+        "claude-3": {"budget_limit": 0.0, "time_period": "1d"},
+    }
+
+    assert (
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=None,
+            model="gpt-4",
+        )
+        is True
+    )
+    with pytest.raises(litellm.BudgetExceededError):
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=None,
+            model="claude-3",
+        )
+
+
+@pytest.mark.asyncio
+async def test_malformed_key_entry_does_not_count_as_an_override():
+    """A key entry the limiter cannot enforce must not also switch the team cap off."""
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {"gpt-4": {"budget_limit": 1.0, "time_period": "1d"}}
+    key_model_max_budget = {"gpt-4": {"budget_limit": "not-a-number", "time_period": "1d"}}
+
+    await _log_success(
+        limiter,
+        model_group="gpt-4",
+        response_cost=1.5,
+        key_hash="vk-bad",
+        key_model_max_budget=key_model_max_budget,
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+    )
+
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:gpt-4:1d") == 1.5
+    with pytest.raises(litellm.BudgetExceededError):
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=key_model_max_budget,
+            model="gpt-4",
+        )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "key_entry",
+    [
+        {"time_period": "1d", "tpm_limit": 100},
+        {"time_period": "1d", "rpm_limit": 10},
+        {"budget_limit": -1.0, "time_period": "1d"},
+    ],
+)
+async def test_key_entry_without_a_spend_cap_does_not_lift_the_team_cap(key_entry):
+    """A key row that only rate-limits the model, or has no enforceable cap, leaves the team cap in force."""
+    dual_cache = DualCache()
+    limiter = _PROXY_VirtualKeyModelMaxBudgetLimiter(dual_cache=dual_cache)
+    team_model_max_budget = {"gpt-4": {"budget_limit": 1.0, "time_period": "1d"}}
+    key_model_max_budget = {"gpt-4": key_entry}
+
+    await _log_success(
+        limiter,
+        model_group="openai/gpt-4",
+        response_cost=1.5,
+        key_hash="vk-rate-limited",
+        key_model_max_budget=key_model_max_budget,
+        team_id="team-1",
+        team_model_max_budget=team_model_max_budget,
+    )
+
+    assert await dual_cache.async_get_cache(key="team_model_spend:team-1:gpt-4:1d") == 1.5
+    with pytest.raises(litellm.BudgetExceededError):
+        await limiter.is_team_within_model_budget(
+            team_id="team-1",
+            team_model_max_budget=team_model_max_budget,
+            key_model_max_budget=key_model_max_budget,
+            model="openai/gpt-4",
+        )
diff --git a/tests/test_litellm/llms/anthropic/experimental_pass_through/context_management/test_compact.py b/tests/test_litellm/llms/anthropic/experimental_pass_through/context_management/test_compact.py
index 7660a8649b5..fc5d807bc23 100644
--- a/tests/test_litellm/llms/anthropic/experimental_pass_through/context_management/test_compact.py
+++ b/tests/test_litellm/llms/anthropic/experimental_pass_through/context_management/test_compact.py
@@ -1200,6 +1200,7 @@ def _fake_user_api_key_auth(
     team_models=None,
     team_id=None,
     model_max_budget=None,
+    team_model_max_budget=None,
     end_user_model_max_budget=None,
     end_user_id=None,
     user_model_max_budget=None,
@@ -1220,6 +1221,7 @@ def _fake_user_api_key_auth(
     auth.team_id = team_id
     auth.team_model_aliases = None
     auth.model_max_budget = model_max_budget
+    auth.team_model_max_budget = team_model_max_budget
     auth.end_user_model_max_budget = end_user_model_max_budget
     auth.end_user_id = end_user_id
     auth.user_model_max_budget = user_model_max_budget
@@ -1860,6 +1862,78 @@ async def test_summary_model_rate_limit_skipped_for_legacy_limiter():
     assert not result.applied_edits[0].get("error")
 
 
+async def test_summary_model_denied_when_team_over_model_budget():
+    """The team per-model budget gates the summary subrequest, whose spend is
+    charged to the team counter via the propagated `user_api_key_team_model_max_budget`.
+    The key's own `model_max_budget` is handed to the limiter so a key-level
+    override keeps taking precedence over the team cap here as it does in auth."""
+    import litellm
+
+    messages = _simple_messages()
+    mock_call = AsyncMock(return_value=_make_mock_response("<summary>x</summary>"))
+    key_budget = {"claude-opus-4-8": {"budget_limit": 1}}
+    team_budget = {"claude-haiku-4-5": {"budget_limit": 5, "time_period": "1d"}}
+
+    auth = _fake_user_api_key_auth(
+        key_models=["all-proxy-models"],
+        model_max_budget=key_budget,
+        team_model_max_budget=team_budget,
+        team_id="team-over-budget",
+        token="hashed-token",
+    )
+
+    limiter = MagicMock()
+    limiter.is_key_within_model_budget = AsyncMock(return_value=True)
+    limiter.is_team_within_model_budget = AsyncMock(
+        side_effect=litellm.BudgetExceededError(
+            message="over budget", current_cost=10, max_budget=5
+        )
+    )
+
+    with (
+        patch(  # test-quality-ok: apply_compact_20260112 reads the summary model setting as a module global, no seam
+            "litellm.llms.anthropic.experimental_pass_through.context_management.editors.compact._read_summary_model_setting",
+            return_value="claude-haiku-4-5",
+        ),
+        patch("litellm.token_counter", return_value=200_000),  # test-quality-ok: forces the over-threshold branch
+        patch(  # test-quality-ok: the summary call is the observable that must NOT happen when the team is over budget
+            "litellm.llms.anthropic.experimental_pass_through.context_management.editors.compact._call_summary_model",
+            mock_call,
+        ),
+        patch(  # test-quality-ok: the limiter is a proxy_server module global the editor imports, no injection seam
+            "litellm.proxy.proxy_server.model_max_budget_limiter", limiter
+        ),
+    ):
+        result = await apply_compact_20260112(
+            model=MODEL,
+            messages=messages,
+            tools=None,
+            system=None,
+            edit_spec=_EDIT_SPEC_DEFAULT,
+            user_api_key_auth=auth,
+        )
+
+    mock_call.assert_not_awaited()
+    assert result.applied_edits[0].get("error") == "summary_model_budget_exceeded"
+    limiter.is_team_within_model_budget.assert_awaited_once_with(
+        team_id="team-over-budget",
+        team_model_max_budget=team_budget,
+        key_model_max_budget=key_budget,
+        model="claude-haiku-4-5",
+    )
+    import inspect
+
+    from litellm.proxy.hooks.model_max_budget_limiter import (
+        _PROXY_VirtualKeyModelMaxBudgetLimiter,
+    )
+
+    real_params = inspect.signature(
+        _PROXY_VirtualKeyModelMaxBudgetLimiter.is_team_within_model_budget
+    ).parameters
+    for kwarg in ("team_id", "team_model_max_budget", "key_model_max_budget", "model"):
+        assert kwarg in real_params, f"compact.py passes {kwarg}=, which the limiter does not accept"
+
+
 async def test_scoped_budget_metadata_propagated_to_summary_call():
     """The end-user/project scope identifiers and the end-user budget the post-call
     spend and rate-limit hooks key on are forwarded to the summary subrequest, and
diff --git a/tests/test_litellm/proxy/auth/test_team_grants.py b/tests/test_litellm/proxy/auth/test_team_grants.py
index 7b6717f804f..f74531beaf0 100644
--- a/tests/test_litellm/proxy/auth/test_team_grants.py
+++ b/tests/test_litellm/proxy/auth/test_team_grants.py
@@ -31,6 +31,7 @@ def _full_team(model_aliases=ALIASES) -> LiteLLM_TeamTable:
         max_budget=50.0,
         soft_budget=25.0,
         spend=12.5,
+        model_max_budget={"gpt-4o": {"max_budget": 5.0, "budget_duration": "1d"}},
         models=["gpt-4o", "gpt-4o-mini"],
         blocked=True,
         metadata={"tier": "gold"},
@@ -72,6 +73,7 @@ def test_team_grants_cover_every_team_field_the_key_path_gets():
     assert token.team_max_budget == 50.0
     assert token.team_soft_budget == 25.0
     assert token.team_spend == 12.5
+    assert token.team_model_max_budget == {"gpt-4o": {"max_budget": 5.0, "budget_duration": "1d"}}
     assert token.team_models == ["gpt-4o", "gpt-4o-mini"]
     assert token.team_blocked is True
     assert token.team_metadata == {"tier": "gold"}
diff --git a/tests/test_litellm/proxy/auth/test_user_api_key_auth.py b/tests/test_litellm/proxy/auth/test_user_api_key_auth.py
index bd7ff62ac8b..c55dd966b2b 100644
--- a/tests/test_litellm/proxy/auth/test_user_api_key_auth.py
+++ b/tests/test_litellm/proxy/auth/test_user_api_key_auth.py
@@ -4372,6 +4372,74 @@ async def test_centralized_common_checks_carries_team_and_user_budget_state_on_t
     }
 
 
+class _RecordingTeamModelBudgetLimiter:
+    def __init__(self):
+        self.calls = []
+
+    async def is_team_within_model_budget(self, team_id, team_model_max_budget, key_model_max_budget, model):
+        self.calls.append((team_id, dict(team_model_max_budget), key_model_max_budget, model))
+        return True
+
+
+@pytest.mark.asyncio
+async def test_centralized_common_checks_enforces_team_model_max_budget_from_the_resolved_team():
+    """The team's model_max_budget is enforced at the single authz gate, off the
+    team object auth resolved (not the possibly stale token copy), and the key's
+    own model_max_budget is handed to the limiter so a matching key entry can
+    override the team cap."""
+    from fastapi import Request
+    from starlette.datastructures import URL
+
+    import litellm.proxy.proxy_server as _proxy_server_mod
+
+    team_caps = {"gpt-4o": {"max_budget": 5.0, "budget_duration": "1d"}}
+    key_caps = {"claude-sonnet-4-6": {"max_budget": 1.0, "budget_duration": "1d"}}
+    token = UserAPIKeyAuth(
+        api_key="sk-test",
+        token="hashed",
+        team_id="t1",
+        team_model_max_budget={"gpt-4o": {"max_budget": 999.0, "budget_duration": "30d"}},
+        model_max_budget=key_caps,
+    )
+    request = Request(scope={"type": "http"})
+    request._url = URL(url="/chat/completions")
+
+    user_api_key_cache = DualCache()
+    await user_api_key_cache.async_set_cache(
+        key="team_id:t1",
+        value=LiteLLM_TeamTableCachedObj(team_id="t1", model_max_budget=team_caps),
+    )
+    limiter = _RecordingTeamModelBudgetLimiter()
+    attrs = {
+        **_proxy_attrs_for_centralized_checks(user_custom_auth=None),
+        "prisma_client": MagicMock(),
+        "user_api_key_cache": user_api_key_cache,
+        "model_max_budget_limiter": limiter,
+    }
+    originals = {a: getattr(_proxy_server_mod, a, None) for a in attrs}
+    try:
+        for k, v in attrs.items():
+            setattr(_proxy_server_mod, k, v)
+        with (
+            patch("litellm.proxy.auth.user_api_key_auth.common_checks", new_callable=AsyncMock),  # test-quality-ok: stubs the sibling check so only the team model-budget gate is under test
+            patch(  # test-quality-ok: stubs the budget reservation so only the team model-budget gate is under test
+                "litellm.proxy.auth.user_api_key_auth._reserve_budget_after_common_checks",
+                new_callable=AsyncMock,
+            ),
+        ):
+            await _run_centralized_common_checks(
+                user_api_key_auth_obj=token,
+                request=request,
+                request_data={"model": "gpt-4o"},
+                route="/chat/completions",
+            )
+    finally:
+        for k, v in originals.items():
+            setattr(_proxy_server_mod, k, v)
+
+    assert limiter.calls == [("t1", team_caps, key_caps, "gpt-4o")]
+
+
 @pytest.mark.asyncio
 async def test_centralized_common_checks_skipped_for_custom_auth_without_flag():
     """Existing RPS guarantee: custom-auth deployments without
diff --git a/tests/test_litellm/proxy/db/test_create_views.py b/tests/test_litellm/proxy/db/test_create_views.py
index ecc6d70123e..54418e10bdf 100644
--- a/tests/test_litellm/proxy/db/test_create_views.py
+++ b/tests/test_litellm/proxy/db/test_create_views.py
@@ -71,6 +71,7 @@ async def test_create_views_creates_view_on_does_not_exist():
     mock_db.execute_raw.assert_called_once()
     created_sql = mock_db.execute_raw.call_args[0][0]
     assert 'CREATE VIEW "LiteLLM_VerificationTokenView"' in created_sql
+    assert "t.model_max_budget AS team_model_max_budget" in created_sql
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_litellm/proxy/management_endpoints/test_common_utils.py b/tests/test_litellm/proxy/management_endpoints/test_common_utils.py
index 7352ca0e9ee..2b614632346 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_common_utils.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_common_utils.py
@@ -35,6 +35,7 @@ from litellm.proxy.management_endpoints.common_utils import (
     admin_can_invite_user,
 )
 from litellm.proxy.management_endpoints.common_utils import _has_non_empty_value
+from litellm.types.utils import BudgetConfig
 
 
 class TestUpdateMetadataFieldsEmptyCollections:
@@ -1162,3 +1163,54 @@ async def test_router_weights_validate_current_deployment_scope(
         assert exc.value.detail == error
     else:
         await validation
+
+
+@pytest.mark.parametrize(
+    "model_max_budget, error",
+    [
+        ({"gpt-4o": BudgetConfig(max_budget=-1.0, budget_duration="1d")}, "non-negative finite"),
+        ({"gpt-4o": BudgetConfig(max_budget=float("inf"), budget_duration="1d")}, "non-negative finite"),
+        ({"gpt-4o": BudgetConfig(max_budget=float("nan"), budget_duration="1d")}, "non-negative finite"),
+        ({"gpt-4o": BudgetConfig(budget_duration="1d")}, "non-negative finite"),
+        ({"gpt-4o": BudgetConfig(max_budget=5.0)}, "requires a budget_duration"),
+        ({"gpt-4o": BudgetConfig(max_budget=5.0, budget_duration="fortnight")}, "budget_duration"),
+        ({"  ": BudgetConfig(max_budget=5.0, budget_duration="1d")}, "non-empty model names"),
+        ({"gpt-4o": BudgetConfig(max_budget=5.0, budget_duration="1d", tpm_limit=1000)}, "not enforced on a team"),
+        ({"gpt-4o": BudgetConfig(max_budget=5.0, budget_duration="1d", rpm_limit=10)}, "not enforced on a team"),
+    ],
+    ids=["negative", "inf", "nan", "no_cap", "no_duration", "bad_duration", "blank_model", "tpm_limit", "rpm_limit"],
+)
+def test_validate_team_model_max_budget_rejects_unenforceable_entries(model_max_budget, error) -> None:
+    from litellm.proxy.management_endpoints.common_utils import validate_team_model_max_budget
+
+    with pytest.raises(HTTPException) as exc:
+        validate_team_model_max_budget(model_max_budget=model_max_budget, premium_user=True)
+    assert exc.value.status_code == 400
+    assert error in exc.value.detail["error"]
+
+
+def test_validate_team_model_max_budget_accepts_a_zero_cap_and_prefixed_models() -> None:
+    from litellm.proxy.management_endpoints.common_utils import validate_team_model_max_budget
+
+    assert (
+        validate_team_model_max_budget(
+            model_max_budget={
+                "gpt-4o": BudgetConfig(max_budget=0.0, budget_duration="1d"),
+                "openai/gpt-4o-mini": BudgetConfig(max_budget=2.5, budget_duration="30d"),
+            },
+            premium_user=True,
+        )
+        is None
+    )
+
+
+def test_validate_team_model_max_budget_is_license_gated_only_when_set() -> None:
+    from litellm.proxy.management_endpoints.common_utils import validate_team_model_max_budget
+
+    validate_team_model_max_budget(model_max_budget=None, premium_user=False)
+    validate_team_model_max_budget(model_max_budget={}, premium_user=False)
+    with pytest.raises(HTTPException) as exc:
+        validate_team_model_max_budget(
+            model_max_budget={"gpt-4o": BudgetConfig(max_budget=1.0, budget_duration="1d")}, premium_user=False
+        )
+    assert exc.value.status_code == 403
diff --git a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py
index ebbedc6541e..dda5bb344b4 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py
@@ -14651,3 +14651,232 @@ async def test_team_info_reports_parent_organization_models_only_to_team_manager
         )
 
     assert response["team_info"].organization_models == expected_models
+
+
+_EXISTING_TEAM_MODEL_CAPS: Final = {
+    "gpt-4o": {"max_budget": 10.0, "budget_duration": "1d"},
+    "claude-sonnet-4-6": {"max_budget": 5.0, "budget_duration": "7d"},
+}
+
+
+@pytest.mark.parametrize(
+    "requested",
+    [
+        {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o": {"max_budget": 20.0, "budget_duration": "1d"}},
+        {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o": {"max_budget": 10.0, "budget_duration": "30d"}},
+        {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o": {"budget_duration": "1d"}},
+        {"claude-sonnet-4-6": _EXISTING_TEAM_MODEL_CAPS["claude-sonnet-4-6"]},
+        {},
+        None,
+    ],
+    ids=["raise", "change_duration", "drop_cap_value", "remove_model", "clear_all", "clear_with_null"],
+)
+def test_team_admin_cannot_loosen_team_model_caps(requested) -> None:
+    from litellm.proxy.management_endpoints.team_endpoints import _check_team_model_budget_update_authority
+
+    with pytest.raises(HTTPException) as exc:
+        _check_team_model_budget_update_authority(
+            data=UpdateTeamRequest(team_id="t1", model_max_budget=requested),
+            user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER, user_id="team-admin"),
+            existing_model_max_budget=_EXISTING_TEAM_MODEL_CAPS,
+        )
+    assert exc.value.status_code == 403
+    assert "proxy admin" in exc.value.detail["error"]
+
+
+@pytest.mark.parametrize(
+    "requested",
+    [
+        {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o": {"max_budget": 2.0, "budget_duration": "1d"}},
+        {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o-mini": {"max_budget": 1.0, "budget_duration": "1d"}},
+        dict(_EXISTING_TEAM_MODEL_CAPS),
+    ],
+    ids=["lower", "add_model", "unchanged"],
+)
+def test_team_admin_can_tighten_or_keep_team_model_caps(requested) -> None:
+    from litellm.proxy.management_endpoints.team_endpoints import _check_team_model_budget_update_authority
+
+    assert (
+        _check_team_model_budget_update_authority(
+            data=UpdateTeamRequest(team_id="t1", model_max_budget=requested),
+            user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER, user_id="team-admin"),
+            existing_model_max_budget=_EXISTING_TEAM_MODEL_CAPS,
+        )
+        is None
+    )
+
+
+def test_team_model_cap_authority_skips_omitted_field_malformed_rows_and_proxy_admins() -> None:
+    from litellm.proxy.management_endpoints.team_endpoints import _check_team_model_budget_update_authority
+
+    team_admin = UserAPIKeyAuth(user_role=LitellmUserRoles.INTERNAL_USER, user_id="team-admin")
+    outcomes = (
+        _check_team_model_budget_update_authority(
+            data=UpdateTeamRequest(team_id="t1", max_budget=1.0),
+            user_api_key_dict=team_admin,
+            existing_model_max_budget=_EXISTING_TEAM_MODEL_CAPS,
+        ),
+        _check_team_model_budget_update_authority(
+            data=UpdateTeamRequest(team_id="t1", model_max_budget={}),
+            user_api_key_dict=team_admin,
+            existing_model_max_budget={"gpt-4o": "not-a-budget", "gpt-4o-mini": {"budget_duration": "1d"}},
+        ),
+        _check_team_model_budget_update_authority(
+            data=UpdateTeamRequest(team_id="t1", model_max_budget=None),
+            user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN),
+            existing_model_max_budget=_EXISTING_TEAM_MODEL_CAPS,
+        ),
+    )
+    assert outcomes == (None, None, None)
+
+
+@pytest.mark.asyncio
+async def test_new_team_persists_model_max_budget(mock_db_client, mock_admin_auth):
+    mock_db_client.jsonify_team_object = lambda db_data: db_data
+    mock_db_client.get_data = AsyncMock(return_value=None)
+    mock_db_client.update_data = AsyncMock(return_value=MagicMock())
+    mock_db_client.db = MagicMock()
+    mock_db_client.db.litellm_modeltable = MagicMock()
+    mock_db_client.db.litellm_modeltable.create = AsyncMock(return_value=MagicMock(id="model123"))
+
+    team_create_result = MagicMock(team_id="team-model-caps")
+    team_create_result.model_dump.return_value = {"team_id": "team-model-caps"}
+    mock_team_create = AsyncMock(return_value=team_create_result)
+    mock_db_client.db.litellm_teamtable = MagicMock()
+    mock_db_client.db.litellm_teamtable.create = mock_team_create
+    _wire_team_create_tx(mock_db_client)
+    mock_db_client.db.litellm_teamtable.count = AsyncMock(return_value=0)
+    mock_db_client.db.litellm_teamtable.update = AsyncMock(return_value=team_create_result)
+    mock_db_client.db.litellm_usertable = MagicMock()
+    mock_db_client.db.litellm_usertable.update = AsyncMock(return_value=MagicMock())
+
+    from fastapi import Request
+
+    from litellm.proxy._types import NewTeamRequest
+    from litellm.proxy.management_endpoints.team_endpoints import new_team
+
+    with patch("litellm.proxy.proxy_server.premium_user", True):  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        await new_team(
+            data=NewTeamRequest(
+                team_alias="model-caps",
+                model_max_budget={"gpt-4o": {"max_budget": 10.0, "budget_duration": "1d"}},
+            ),
+            http_request=MagicMock(spec=Request),
+            user_api_key_dict=mock_admin_auth,
+        )
+
+    team_data = mock_team_create.call_args.kwargs["data"]
+    assert team_data["model_max_budget"] == {
+        "gpt-4o": {"max_budget": 10.0, "budget_duration": "1d", "tpm_limit": None, "rpm_limit": None}
+    }
+
+
+@pytest.mark.asyncio
+async def test_new_team_rejects_unenforceable_model_max_budget(mock_db_client, mock_admin_auth):
+    from fastapi import Request
+
+    from litellm.proxy._types import NewTeamRequest, ProxyException
+    from litellm.proxy.management_endpoints.team_endpoints import new_team
+
+    mock_db_client.db.litellm_teamtable.create = AsyncMock()
+
+    with patch("litellm.proxy.proxy_server.premium_user", True), pytest.raises(ProxyException) as exc:  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        await new_team(
+            data=NewTeamRequest(team_alias="model-caps", model_max_budget={"gpt-4o": {"max_budget": 10.0}}),
+            http_request=MagicMock(spec=Request),
+            user_api_key_dict=mock_admin_auth,
+        )
+
+    assert exc.value.code == "400"
+    assert "budget_duration" in str(exc.value.message)
+    mock_db_client.db.litellm_teamtable.create.assert_not_awaited()
+
+
+def _existing_team_with_model_caps(caps):
+    existing = MagicMock()
+    existing.team_id = "standalone-team-123"
+    existing.organization_id = None
+    existing.max_budget = None
+    existing.model_id = None
+    existing.model_max_budget = caps
+    existing.model_dump.return_value = {
+        "team_id": "standalone-team-123",
+        "organization_id": None,
+        "model_max_budget": caps,
+        "members_with_roles": [{"user_id": "team-admin-model-caps", "role": "admin"}],
+    }
+    return existing
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cleared_with", [{}, None], ids=["empty_mapping", "null"])
+async def test_update_team_clearing_model_max_budget_writes_an_empty_mapping(
+    disable_audit_logging_for_mocked_team, cleared_with
+):
+    from fastapi import Request
+
+    from litellm.proxy.management_endpoints.team_endpoints import update_team
+
+    with (
+        patch("litellm.proxy.proxy_server.prisma_client") as mock_prisma,  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.user_api_key_cache") as mock_cache,  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.litellm_proxy_admin_name", "admin"),  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.premium_user", True),  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+    ):
+        mock_prisma.db.litellm_teamtable.find_unique = AsyncMock(
+            return_value=_existing_team_with_model_caps(_EXISTING_TEAM_MODEL_CAPS)
+        )
+        mock_prisma.jsonify_team_object = lambda db_data: db_data
+        mock_cache.async_get_cache = AsyncMock(return_value=None)
+        mock_cache.async_set_cache = AsyncMock()
+        updated = _existing_team_with_model_caps({})
+        updated.litellm_model_table = None
+        mock_prisma.db.litellm_teamtable.update = AsyncMock(return_value=updated)
+
+        await update_team(
+            data=UpdateTeamRequest(team_id="standalone-team-123", model_max_budget=cleared_with),
+            http_request=MagicMock(spec=Request),
+            user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, user_id="admin"),
+        )
+
+    assert mock_prisma.db.litellm_teamtable.update.call_args.kwargs["data"]["model_max_budget"] == {}
+
+
+@pytest.mark.asyncio
+async def test_update_team_model_max_budget_raise_blocked_for_team_admin():
+    from fastapi import Request
+
+    from litellm.proxy._types import ProxyException
+    from litellm.proxy.management_endpoints.team_endpoints import update_team
+
+    with (
+        patch("litellm.proxy.proxy_server.prisma_client") as mock_prisma,  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.user_api_key_cache") as mock_cache,  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.litellm_proxy_admin_name", "admin"),  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.premium_user", True),  # test-quality-ok: proxy_server module global is the endpoint's only injection point
+        patch("litellm.proxy.proxy_server.create_audit_log_for_update", new=AsyncMock()),  # test-quality-ok: stubs the audit write so the test observes only the team update result
+    ):
+        mock_prisma.db.litellm_teamtable.find_unique = AsyncMock(
+            return_value=_existing_team_with_model_caps(_EXISTING_TEAM_MODEL_CAPS)
+        )
+        mock_cache.async_get_cache = AsyncMock(return_value=None)
+        mock_prisma.db.litellm_teamtable.update = AsyncMock()
+
+        with pytest.raises(ProxyException) as exc:
+            await update_team(
+                data=UpdateTeamRequest(
+                    team_id="standalone-team-123",
+                    model_max_budget={
+                        **_EXISTING_TEAM_MODEL_CAPS,
+                        "gpt-4o": {"max_budget": 100.0, "budget_duration": "1d"},
+                    },
+                ),
+                http_request=MagicMock(spec=Request),
+                user_api_key_dict=UserAPIKeyAuth(
+                    user_role=LitellmUserRoles.INTERNAL_USER, user_id="team-admin-model-caps", models=[]
+                ),
+            )
+
+    assert exc.value.code == "403"
+    assert "proxy admin" in str(exc.value.message).lower()
+    mock_prisma.db.litellm_teamtable.update.assert_not_awaited()
diff --git a/tests/test_litellm/proxy/spend_tracking/test_carried_budget_state.py b/tests/test_litellm/proxy/spend_tracking/test_carried_budget_state.py
index fe852be775c..0bdf43b396c 100644
--- a/tests/test_litellm/proxy/spend_tracking/test_carried_budget_state.py
+++ b/tests/test_litellm/proxy/spend_tracking/test_carried_budget_state.py
@@ -47,6 +47,19 @@ def test_team_and_user_state_round_trips_through_metadata():
     )
 
 
+def test_team_model_max_budget_rides_on_the_token():
+    """The team's per-model caps must reach the token, or the auth check and the spend hook never see them."""
+    token = UserAPIKeyAuth(token="hashed", team_id="t1")
+    team_model_max_budget = {"gpt-4o": {"max_budget": 5.0, "budget_duration": "1d"}}
+    carry_team_and_user_budget_state(
+        valid_token=token,
+        team_object=LiteLLM_TeamTable(team_id="t1", model_max_budget=team_model_max_budget),
+        user_object=None,
+    )
+
+    assert token.team_model_max_budget == team_model_max_budget
+
+
 def test_missing_objects_leave_no_metadata_and_no_snapshot():
     token = UserAPIKeyAuth(token="hashed", team_id="t1", user_id="u1")
     carry_team_and_user_budget_state(valid_token=token, team_object=None, user_object=None)
diff --git a/tests/test_litellm/proxy/utils/prisma_and_spend/test_prisma_client_get_data.py b/tests/test_litellm/proxy/utils/prisma_and_spend/test_prisma_client_get_data.py
index ce6ecc2ea65..672dd1eb674 100644
--- a/tests/test_litellm/proxy/utils/prisma_and_spend/test_prisma_client_get_data.py
+++ b/tests/test_litellm/proxy/utils/prisma_and_spend/test_prisma_client_get_data.py
@@ -401,19 +401,20 @@ async def test_check_view_exists_creates_token_view_when_missing(
     prisma_client.db.execute_raw = AsyncMock()
     prisma_client.health_check = AsyncMock(return_value=[{"?column?": 1}])
     result = await prisma_client.check_view_exists()
+    created_sql = prisma_client.db.execute_raw.await_args.args[0]
     actual = {
         "result": result,
         "create_called": prisma_client.db.execute_raw.await_count,
-        "create_sql_starts_with_create_view": prisma_client.db.execute_raw.await_args.args[
-            0
-        ]
-        .strip()
-        .startswith('CREATE VIEW "LiteLLM_VerificationTokenView"'),
+        "create_sql_starts_with_create_view": created_sql.strip().startswith(
+            'CREATE VIEW "LiteLLM_VerificationTokenView"'
+        ),
+        "projects_team_model_max_budget": "t.model_max_budget AS team_model_max_budget" in created_sql,
     }
     assert actual == {
         "result": None,
         "create_called": 1,
         "create_sql_starts_with_create_view": True,
+        "projects_team_model_max_budget": True,
     }
 
 
diff --git a/ui/litellm-dashboard/src/components/Teams.test.tsx b/ui/litellm-dashboard/src/components/Teams.test.tsx
index 851c9e6d487..f2d7cff2ec4 100644
--- a/ui/litellm-dashboard/src/components/Teams.test.tsx
+++ b/ui/litellm-dashboard/src/components/Teams.test.tsx
@@ -7,6 +7,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useTeamMetadataSchema } from "@/app/(dashboard)/hooks/teams/useTeamMetadataSchema";
 import { toast } from "@/lib/toast";
 import { fetchAvailableModelsForTeamOrKey } from "./key_team_helpers/fetch_available_models_team_key";
+import { MODEL_MAX_BUDGET_PREMIUM_HINT } from "./key_team_helpers/ModelMaxBudgetEditor";
 import {
   fetchMCPAccessGroups,
   getDefaultTeamSettings,
@@ -1547,6 +1548,36 @@ describe("Teams - the exact bytes the create call sends", () => {
     expect(await screen.findByText("Please input a team name")).toBeInTheDocument();
     expect(teamCreateCall).not.toHaveBeenCalled();
   });
+
+  it("locks the per-model budget editor and says why when the proxy has no enterprise license", async () => {
+    await openCreateModal({ premiumUser: false });
+
+    expect(screen.getByRole("button", { name: /Add Model Budget/i })).toBeDisabled();
+    expect(screen.getByText(MODEL_MAX_BUDGET_PREMIUM_HINT)).toBeInTheDocument();
+  });
+
+  it("sends the per-model budget a licensed operator fills in, keyed by model", async () => {
+    const user = userEvent.setup({ delay: null });
+    await openCreateModal({ premiumUser: true });
+
+    await user.click(screen.getByRole("button", { name: /Add Model Budget/i }));
+    await chooseSelectOption(user, screen.getByPlaceholderText("Select model"), "gpt-4");
+    fireEvent.change(screen.getByPlaceholderText("Max spend ($)"), { target: { value: "3" } });
+
+    const payload = await submit();
+
+    expect(payload.model_max_budget).toStrictEqual({ "gpt-4": { budget_limit: 3, time_period: "30d" } });
+  });
+
+  it("leaves model_max_budget out when a started row is removed again", async () => {
+    const user = userEvent.setup({ delay: null });
+    await openCreateModal({ premiumUser: true });
+
+    await user.click(screen.getByRole("button", { name: /Add Model Budget/i }));
+    await user.click(screen.getByRole("button", { name: "Remove model budget" }));
+
+    expect(wireBody(await submit())).not.toHaveProperty("model_max_budget");
+  });
 });
 
 describe("Teams - the create form keeps the organization and models picks while it is open", () => {
diff --git a/ui/litellm-dashboard/src/components/Teams.tsx b/ui/litellm-dashboard/src/components/Teams.tsx
index 4f3367d8b98..7214d16f665 100644
--- a/ui/litellm-dashboard/src/components/Teams.tsx
+++ b/ui/litellm-dashboard/src/components/Teams.tsx
@@ -48,6 +48,7 @@ import BudgetDurationDropdown, {
 } from "./common_components/budget_duration_dropdown";
 import { Organization, getDefaultTeamSettings, getGuardrailsList, getPoliciesList, teamDeleteCall } from "./networking";
 import NumericalInput from "./shared/numerical_input";
+import { ModelMaxBudget, ModelMaxBudgetField } from "./key_team_helpers/ModelMaxBudgetEditor";
 import VectorStoreSelector from "./vector_store_management/VectorStoreSelector";
 import SearchToolSelector from "./search_tools/SearchToolSelector";
 import SkillSelector from "./skills/SkillSelector";
@@ -271,6 +272,7 @@ const Teams: React.FC<TeamProps> = ({ accessToken, userID, userRole, premiumUser
   const [policiesList, setPoliciesList] = useState<string[]>([]);
   const [loggingSettings, setLoggingSettings] = useState<any[]>([]);
   const [modelAliases, setModelAliases] = useState<{ [key: string]: string }>({});
+  const [modelMaxBudget, setModelMaxBudget] = useState<ModelMaxBudget>({});
   const [routerSettings, setRouterSettings] = useState<RouterSettingsAccordionValue | null>(null);
   const [routerSettingsKey, setRouterSettingsKey] = useState<number>(0);
 
@@ -348,6 +350,7 @@ const Teams: React.FC<TeamProps> = ({ accessToken, userID, userRole, premiumUser
     setSearchToolSettingsOpen(false);
     setLoggingSettings([]);
     setModelAliases({});
+    setModelMaxBudget({});
     setRouterSettings(null);
     setRouterSettingsKey((prev) => prev + 1);
   };
@@ -525,6 +528,10 @@ const Teams: React.FC<TeamProps> = ({ accessToken, userID, userRole, premiumUser
           formValues.model_aliases = modelAliases;
         }
 
+        if (Object.keys(modelMaxBudget).length > 0) {
+          formValues.model_max_budget = modelMaxBudget;
+        }
+
         // Add router_settings if any are defined
         if (routerSettings?.router_settings) {
           // Only include router_settings if it has at least one non-null value
@@ -813,6 +820,14 @@ const Teams: React.FC<TeamProps> = ({ accessToken, userID, userRole, premiumUser
                       />
                     )}
                   </FormField>
+                  <ModelMaxBudgetField
+                    key={`model-max-budget-${routerSettingsKey}`}
+                    premiumUser={premiumUser}
+                    value={modelMaxBudget}
+                    onChange={setModelMaxBudget}
+                    availableModels={userModels}
+                    hint="Cap this team's spend on individual models, each with its own reset window. Every key on the team shares the cap unless the key sets its own budget for that model."
+                  />
                   <FormField control={form.control} name="tpm_limit" label="Tokens per minute Limit (TPM)">
                     {({ ref, value, ...field }) => (
                       <NumericalInput {...field} ref={ref} value={value ?? ""} step={1} width={400} />
diff --git a/ui/litellm-dashboard/src/components/key_team_helpers/ModelMaxBudgetEditor.tsx b/ui/litellm-dashboard/src/components/key_team_helpers/ModelMaxBudgetEditor.tsx
index 0fab5555343..4d2a0e88f84 100644
--- a/ui/litellm-dashboard/src/components/key_team_helpers/ModelMaxBudgetEditor.tsx
+++ b/ui/litellm-dashboard/src/components/key_team_helpers/ModelMaxBudgetEditor.tsx
@@ -144,6 +144,7 @@ export function ModelMaxBudgetEditor({
               onClick={() => removeEntry(entry.id)}
               disabled={!premiumUser}
               title={hintWhenLocked}
+              aria-label="Remove model budget"
               className="absolute top-2 right-2 text-muted-foreground hover:text-destructive transition-colors p-1"
             >
               <X className="w-4 h-4" />
diff --git a/ui/litellm-dashboard/src/components/team/TeamInfo.test.tsx b/ui/litellm-dashboard/src/components/team/TeamInfo.test.tsx
index eb912ffa3cc..16eb70fdf5e 100644
--- a/ui/litellm-dashboard/src/components/team/TeamInfo.test.tsx
+++ b/ui/litellm-dashboard/src/components/team/TeamInfo.test.tsx
@@ -1609,6 +1609,99 @@ describe("TeamInfoView", () => {
     });
   });
 
+  describe("per-model budgets", () => {
+    const teamWithModelBudget = () =>
+      createMockTeamData({
+        models: ["gpt-4"],
+        model_max_budget: { "gpt-4": { max_budget: 5, budget_duration: "1d" } },
+        model_max_budget_usage: { "gpt-4": { current_spend: 1.25, budget_limit: 5, time_period: "1d" } },
+      });
+
+    const openSettingsEditor = async (user: ReturnType<typeof userEvent.setup>) => {
+      await waitFor(() => {
+        expect(screen.queryAllByText("Test Team").length).toBeGreaterThan(0);
+      });
+      await user.click(screen.getByRole("tab", { name: "Settings" }));
+      await user.click(await screen.findByRole("button", { name: /edit settings/i }));
+      await screen.findByLabelText("Team Name");
+    };
+
+    const savedPayload = async () => {
+      await waitFor(() => {
+        expect(networking.teamUpdateCall).toHaveBeenCalled();
+      });
+      return vi.mocked(networking.teamUpdateCall).mock.calls[0][1] as Record<string, unknown>;
+    };
+
+    it("shows the stored per-model budget and its current spend in the read-only settings view", async () => {
+      const user = userEvent.setup({ delay: null });
+      vi.mocked(networking.teamInfoCall).mockResolvedValue(teamWithModelBudget());
+
+      renderWithProviders(<TeamInfoView {...defaultProps} />);
+
+      await waitFor(() => {
+        expect(screen.queryAllByText("Test Team").length).toBeGreaterThan(0);
+      });
+      await user.click(screen.getByRole("tab", { name: "Settings" }));
+
+      expect(await screen.findByText("Per-Model Budget (gpt-4): $5 per 1d, spent $1.25")).toBeInTheDocument();
+    });
+
+    it("seeds the editor from the stored budget and keeps it read-only without an enterprise license", async () => {
+      const user = userEvent.setup({ delay: null });
+      vi.mocked(networking.teamInfoCall).mockResolvedValue(teamWithModelBudget());
+
+      renderWithProviders(<TeamInfoView {...defaultProps} premiumUser={false} />);
+
+      await openSettingsEditor(user);
+
+      expect(screen.getByPlaceholderText("Max spend ($)")).toHaveValue(5);
+      expect(screen.getByPlaceholderText("Max spend ($)")).toBeDisabled();
+      expect(screen.getByRole("button", { name: /Add Model Budget/i })).toBeDisabled();
+    });
+
+    it("leaves model_max_budget out of a save that did not touch it", async () => {
+      const user = userEvent.setup({ delay: null });
+      vi.mocked(networking.teamInfoCall).mockResolvedValue(teamWithModelBudget());
+      vi.mocked(networking.teamUpdateCall).mockResolvedValue({ data: {}, team_id: "123" } as any);
+
+      renderWithProviders(<TeamInfoView {...defaultProps} premiumUser={true} />);
+
+      await openSettingsEditor(user);
+      await user.click(screen.getByRole("button", { name: /save changes/i }));
+
+      expect(await savedPayload()).not.toHaveProperty("model_max_budget");
+    });
+
+    it("sends the edited cap for the model", async () => {
+      const user = userEvent.setup({ delay: null });
+      vi.mocked(networking.teamInfoCall).mockResolvedValue(teamWithModelBudget());
+      vi.mocked(networking.teamUpdateCall).mockResolvedValue({ data: {}, team_id: "123" } as any);
+
+      renderWithProviders(<TeamInfoView {...defaultProps} premiumUser={true} />);
+
+      await openSettingsEditor(user);
+      fireEvent.change(screen.getByPlaceholderText("Max spend ($)"), { target: { value: "2.5" } });
+      await user.click(screen.getByRole("button", { name: /save changes/i }));
+
+      expect((await savedPayload()).model_max_budget).toEqual({ "gpt-4": { budget_limit: 2.5, time_period: "1d" } });
+    });
+
+    it("sends an empty model_max_budget when the last row is removed, so the stored cap is cleared", async () => {
+      const user = userEvent.setup({ delay: null });
+      vi.mocked(networking.teamInfoCall).mockResolvedValue(teamWithModelBudget());
+      vi.mocked(networking.teamUpdateCall).mockResolvedValue({ data: {}, team_id: "123" } as any);
+
+      renderWithProviders(<TeamInfoView {...defaultProps} premiumUser={true} />);
+
+      await openSettingsEditor(user);
+      await user.click(screen.getByRole("button", { name: "Remove model budget" }));
+      await user.click(screen.getByRole("button", { name: /save changes/i }));
+
+      expect((await savedPayload()).model_max_budget).toEqual({});
+    });
+  });
+
   describe("team member settings", () => {
     it("should populate Default Key Duration from the team's stored metadata", async () => {
       const user = userEvent.setup({ delay: null });
diff --git a/ui/litellm-dashboard/src/components/team/TeamInfo.tsx b/ui/litellm-dashboard/src/components/team/TeamInfo.tsx
index ce705008678..c476f3492a3 100644
--- a/ui/litellm-dashboard/src/components/team/TeamInfo.tsx
+++ b/ui/litellm-dashboard/src/components/team/TeamInfo.tsx
@@ -51,6 +51,13 @@ import GuardrailsSelect from "./GuardrailsSelect";
 import { copyToClipboard as utilCopyToClipboard } from "../../utils/dataUtils";
 import AccessGroupSelector from "../common_components/AccessGroupSelector";
 import BudgetDurationDropdown, { NEVER_RESETS_BUDGET_DURATION } from "../common_components/budget_duration_dropdown";
+import {
+  ModelBudgetUsage,
+  ModelMaxBudget,
+  ModelMaxBudgetField,
+  modelMaxBudgetToEntries,
+} from "../key_team_helpers/ModelMaxBudgetEditor";
+import { modelMaxBudgetUpdate, StoredModelMaxBudget } from "../key_team_helpers/modelMaxBudgetPayload";
 import {
   computeTeamModelBadges,
   normalizeTeamModelSelection,
@@ -268,6 +275,8 @@ export interface TeamData {
     max_budget: number | null;
     soft_budget?: number | null;
     budget_duration: string | null;
+    model_max_budget?: StoredModelMaxBudget | null;
+    model_max_budget_usage?: Record<string, ModelBudgetUsage> | null;
     models: string[];
     blocked: boolean;
     spend: number;
@@ -563,6 +572,7 @@ const TeamInfoView: React.FC<TeamInfoProps> = ({
   const [isDeleting, setIsDeleting] = useState(false);
   const [isTeamSaving, setIsTeamSaving] = useState(false);
   const [teamModelAliases, setTeamModelAliases] = useState<Record<string, string>>({});
+  const [teamModelMaxBudget, setTeamModelMaxBudget] = useState<ModelMaxBudget>({});
   const routerSettingsRef = React.useRef<RouterSettingsAccordionRef>(null);
   const [organization, setOrganization] = useState<Organization | null>(null);
   const { userRole, userId } = useAuthorized();
@@ -628,6 +638,7 @@ const TeamInfoView: React.FC<TeamInfoProps> = ({
 
   const startEditing = () => {
     form.reset(teamFormValues());
+    setTeamModelMaxBudget((teamData?.team_info?.model_max_budget ?? {}) as ModelMaxBudget);
     setTeamMemberSettingsOpen(false);
     setSearchToolSettingsOpen(false);
     setIsEditing(true);
@@ -1078,6 +1089,11 @@ const TeamInfoView: React.FC<TeamInfoProps> = ({
         updateData.model_aliases = teamModelAliases;
       }
 
+      const modelBudgets = modelMaxBudgetUpdate(teamModelMaxBudget, info.model_max_budget);
+      if (modelBudgets !== undefined) {
+        updateData.model_max_budget = modelBudgets;
+      }
+
       // Handle router_settings - read fresh values from DOM at save time.
       const currentRouterSettings = routerSettingsRef.current?.getValue();
       if (currentRouterSettings?.router_settings) {
@@ -1536,6 +1552,15 @@ const TeamInfoView: React.FC<TeamInfoProps> = ({
                     )}
                   </FormField>
 
+                  <ModelMaxBudgetField
+                    premiumUser={premiumUser}
+                    value={teamModelMaxBudget}
+                    onChange={setTeamModelMaxBudget}
+                    availableModels={availableRateLimitModels}
+                    usage={info.model_max_budget_usage}
+                    hint="Cap this team's spend on individual models, each with its own reset window. Every key on the team shares the cap unless the key sets its own budget for that model."
+                  />
+
                   <FormField control={form.control} name="tpm_limit" label="Tokens per minute Limit (TPM)">
                     {({ ref, value, ...field }) => <NumericalInput {...field} ref={ref} value={value ?? ""} step={1} />}
                   </FormField>
@@ -2051,6 +2076,17 @@ const TeamInfoView: React.FC<TeamInfoProps> = ({
                     : "No Limit"}
                 </div>
                 <div>Budget Reset: {info.budget_duration || "Never"}</div>
+                {modelMaxBudgetToEntries(info.model_max_budget as ModelMaxBudget | null | undefined).map(
+                  ({ model, budgetLimit, timePeriod }) => {
+                    const spent = model === null ? undefined : info.model_max_budget_usage?.[model]?.current_spend;
+                    return (
+                      <div key={model}>
+                        Per-Model Budget ({model}): ${budgetLimit ?? "?"} per {timePeriod}
+                        {spent !== undefined && `, spent $${spent}`}
+                      </div>
+                    );
+                  },
+                )}
                 {info.metadata?.soft_budget_alerting_emails &&
                   Array.isArray(info.metadata.soft_budget_alerting_emails) &&
                   info.metadata.soft_budget_alerting_emails.length > 0 && (
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 7ca30d5c4f0..f7a26a26370 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -15626,6 +15626,7 @@ export interface paths {
          *     - prompts: Optional[List[str]] - List of prompts that the team is allowed to use.
          *     - organization_id: Optional[str] - The organization id of the team. Default is None. Create via `/organization/new`.
          *     - model_aliases: Optional[dict] - Model aliases for the team. [Docs](https://docs.litellm.ai/docs/proxy/team_based_routing#create-team-with-model-alias)
+         *     - model_max_budget: Optional[dict] - Per-model max budget every key on the team inherits unless the key sets its own for that model. Example: {"gpt-4o": {"max_budget": 10, "budget_duration": "1d"}}
          *     - guardrails: Optional[List[str]] - Guardrails for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails)
          *     - policies: Optional[List[str]] - Policies for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails/guardrail_policies)
          *     - disable_global_guardrails: Optional[bool] - Whether to disable global guardrails for the key.
@@ -15852,6 +15853,7 @@ export interface paths {
          *     - tags: Optional[List[str]] - Tags for [tracking spend](https://litellm.vercel.app/docs/proxy/enterprise#tracking-spend-for-custom-tags) and/or doing [tag-based routing](https://litellm.vercel.app/docs/proxy/tag_routing).
          *     - organization_id: Optional[str] - The organization id of the team. Default is None. Create via `/organization/new`.
          *     - model_aliases: Optional[dict] - Model aliases for the team. [Docs](https://docs.litellm.ai/docs/proxy/team_based_routing#create-team-with-model-alias)
+         *     - model_max_budget: Optional[dict] - Per-model max budget every key on the team inherits unless the key sets its own for that model. Example: {"gpt-4o": {"max_budget": 10, "budget_duration": "1d"}}
          *     - guardrails: Optional[List[str]] - Guardrails for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails)
          *     - policies: Optional[List[str]] - Policies for the team. [Docs](https://docs.litellm.ai/docs/proxy/guardrails/guardrail_policies)
          *     - disable_global_guardrails: Optional[bool] - Whether to disable global guardrails for the key.
@@ -33328,6 +33330,13 @@ export interface components {
             model_aliases?: {
                 [key: string]: unknown;
             } | null;
+            /**
+             * Model Max Budget
+             * @description Max budget per model for every key on the team, overridable per key (e.g. {'gpt-4o': {'max_budget': 10, 'budget_duration': '1d'}})
+             */
+            model_max_budget?: {
+                [key: string]: components["schemas"]["BudgetConfig"];
+            } | null;
             /** Model Rpm Limit */
             model_rpm_limit?: {
                 [key: string]: number;
@@ -34086,6 +34095,13 @@ export interface components {
             model_aliases?: {
                 [key: string]: unknown;
             } | null;
+            /**
+             * Model Max Budget
+             * @description Max budget per model for every key on the team, overridable per key (e.g. {'gpt-4o': {'max_budget': 10, 'budget_duration': '1d'}})
+             */
+            model_max_budget?: {
+                [key: string]: components["schemas"]["BudgetConfig"];
+            } | null;
             /** Model Rpm Limit */
             model_rpm_limit?: {
                 [key: string]: number;
@@ -39225,6 +39241,13 @@ export interface components {
             model_aliases?: {
                 [key: string]: unknown;
             } | null;
+            /**
+             * Model Max Budget
+             * @description Max budget per model for every key on the team, overridable per key (e.g. {'gpt-4o': {'max_budget': 10, 'budget_duration': '1d'}})
+             */
+            model_max_budget?: {
+                [key: string]: components["schemas"]["BudgetConfig"];
+            } | null;
             /** Model Rpm Limit */
             model_rpm_limit?: {
                 [key: string]: number;
@@ -39936,6 +39959,10 @@ export interface components {
             team_model_aliases?: {
                 [key: string]: unknown;
             } | null;
+            /** Team Model Max Budget */
+            team_model_max_budget?: {
+                [key: string]: unknown;
+            } | null;
             /**
              * Team Models
              * @default []

From b3432abef7920773788382709bc160c4c0c7b9e9 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Wed, 16 Sep 2026 00:58:03 +0000
Subject: [PATCH 11/76] refactor(ui): derive the ssh skill name from the bare
 repo path

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../components/claude_code_plugins/helpers.ts   | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
index cbca22da1f3..3c11a6cedbc 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
@@ -180,17 +180,15 @@ const parseRawGitSource = (url: URL, subPath?: string): SkillSourcePreview | nul
 
 interface SshRemote {
   cloneUrl: string;
-  repoPath: string;
+  repoName: string;
 }
 
-const withGitSuffix = (path: string): string => `${path.replace(/\.git$/i, "")}.git`;
-
 const buildSshRemote = (rawPath: string, toCloneUrl: (repoPath: string) => string): SshRemote | null => {
   if (rawPath.split("/").some((segment) => DOTS_ONLY_SEGMENT_REGEX.test(segment))) {
     return null;
   }
-  const repoPath = withGitSuffix(rawPath);
-  return { cloneUrl: toCloneUrl(repoPath), repoPath };
+  const bare = rawPath.replace(/\.git$/i, "");
+  return { cloneUrl: toCloneUrl(`${bare}.git`), repoName: lastSegment(bare) };
 };
 
 const parseSshRemote = (raw: string): SshRemote | null => {
@@ -208,9 +206,6 @@ const parseSshRemote = (raw: string): SshRemote | null => {
   return null;
 };
 
-const parseSshSource = (remote: SshRemote, subPath?: string): SkillSourcePreview | null =>
-  buildGitSourcePreview("SSH", remote.cloneUrl, lastSegment(remote.repoPath).replace(/\.git$/, ""), subPath);
-
 const parseArchiveSource = (url: URL): SkillSourcePreview => ({
   parsed: { source: "archive", url: url.href },
   label: `Zip archive — ${url.host}${url.pathname}`,
@@ -225,9 +220,9 @@ const parseArchiveSource = (url: URL): SkillSourcePreview => ({
  * with an optional subfolder turning it into git-subdir.
  */
 export const parseSkillSource = (rawUrl: string, subPath?: string): SkillSourcePreview | null => {
-  const sshRemote = parseSshRemote(rawUrl);
-  if (sshRemote) {
-    return parseSshSource(sshRemote, subPath);
+  const ssh = parseSshRemote(rawUrl);
+  if (ssh) {
+    return buildGitSourcePreview("SSH", ssh.cloneUrl, ssh.repoName, subPath);
   }
   const url = parseRepoUrl(rawUrl);
   if (!url) {

From 3e8566d87849b20299f2a07889e2dfe5ab35cab6 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 01:03:40 +0000
Subject: [PATCH 12/76] fix(keys): keep organization_id on archived key records
 and /key/info

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/models/verification_token.py          |  1 +
 .../test_key_management_endpoints.py          | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/litellm/models/verification_token.py b/litellm/models/verification_token.py
index 06ff877a41a..1b807c46c40 100644
--- a/litellm/models/verification_token.py
+++ b/litellm/models/verification_token.py
@@ -69,6 +69,7 @@ class LiteLLM_DeletedVerificationToken(LiteLLM_VerificationToken):
     """Audit record for deleted keys; mirrors the token plus deletion metadata."""
 
     id: str | None = None
+    organization_id: str | None = None
     deleted_at: datetime | None = None
     deleted_by: str | None = None
     deleted_by_api_key: str | None = None
diff --git a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
index a8ff860c7c9..34cfc2a8fac 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
@@ -4919,6 +4919,23 @@ def test_transform_verification_tokens_to_deleted_records():
     assert json.loads(record2["budget_fallbacks"]) == {"gpt-4": ["gpt-4o-mini"]}
 
 
+def test_transform_verification_tokens_to_deleted_records_keeps_organization_id():
+    live_row = MagicMock()
+    live_row.model_dump.return_value = {
+        "token": "hashed-token-org",
+        "user_id": "user-123",
+        "team_id": None,
+        "organization_id": "org-finops",
+    }
+
+    records = _transform_verification_tokens_to_deleted_records(
+        keys=[live_row],
+        user_api_key_dict=UserAPIKeyAuth(user_id="admin-1", api_key="sk-admin"),
+    )
+
+    assert records[0]["organization_id"] == "org-finops"
+
+
 def test_transform_verification_tokens_to_deleted_records_empty_list():
     user_api_key_dict = UserAPIKeyAuth(
         user_id="user-123",
@@ -6135,6 +6152,7 @@ def _archived_key_row(token: str, user_id: str) -> MagicMock:
         "key_alias": "finops-2024",
         "user_id": user_id,
         "team_id": None,
+        "organization_id": "org-finops",
         "blocked": None,
         "deleted_at": datetime(2024, 11, 15, 10, 0, tzinfo=timezone.utc),
         "deleted_by": "admin-1",
@@ -6166,6 +6184,7 @@ async def test_info_key_fn_serves_deleted_key_from_archive(monkeypatch):
     info = result["info"]
     assert info["status"] == "deleted"
     assert info["key_alias"] == "finops-2024"
+    assert info["organization_id"] == "org-finops"
     assert info["deleted_by"] == "admin-1"
     assert info["deleted_at"] is not None
     assert "token" not in info

From d8ef940232b906001113d6aaf35ded908213437a Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 01:06:36 +0000
Subject: [PATCH 13/76] chore(ui): regenerate schema.d.ts for organization_id
 on archived key records

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ui/litellm-dashboard/src/lib/http/schema.d.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 542d491e2d7..49c67dcafc8 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -29528,6 +29528,8 @@ export interface components {
             object_permission_id?: string | null;
             /** Org Id */
             org_id?: string | null;
+            /** Organization Id */
+            organization_id?: string | null;
             /**
              * Permissions
              * @default {}

From d90e7b3aecb2f9494df669de90f80037e80bc8c5 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 01:26:40 +0000
Subject: [PATCH 14/76] fix(team): resolve model aliases in team admin
 model_max_budget authority check

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../management_endpoints/team_endpoints.py    | 43 +++++++++++--------
 .../test_team_endpoints.py                    | 18 +++++++-
 2 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/litellm/proxy/management_endpoints/team_endpoints.py b/litellm/proxy/management_endpoints/team_endpoints.py
index 6fb1ef5ec93..23b02c22f24 100644
--- a/litellm/proxy/management_endpoints/team_endpoints.py
+++ b/litellm/proxy/management_endpoints/team_endpoints.py
@@ -96,7 +96,10 @@ from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.proxy.common_utils.callback_utils import encrypt_callback_vars
 from litellm.proxy.common_utils.json_merge_patch import apply_json_merge_patch
 from litellm.proxy.common_utils.user_api_key_cache import UserApiKeyCache
-from litellm.proxy.hooks.model_max_budget_limiter import build_model_max_budget_usage
+from litellm.proxy.hooks.model_max_budget_limiter import (
+    build_model_max_budget_usage,
+    resolve_model_budget,
+)
 from litellm.proxy.management_endpoints.common_daily_activity import (
     get_daily_activity_aggregated,
 )
@@ -1194,31 +1197,37 @@ def _check_team_model_budget_update_authority(
     requested: Final[Mapping[str, BudgetConfig]] = data.model_max_budget or {}
     for model_name, raw_existing in existing_model_max_budget.items():
         existing = _existing_model_cap(raw_existing)
-        if existing is None or existing.max_budget is None:
+        if existing is None or existing.max_budget is None or model_name in requested:
+            continue
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "error": (
+                    f"Only a proxy admin can remove a team's model_max_budget for {model_name!r}. "
+                    f"Current max_budget={existing.max_budget}."
+                )
+            },
+        )
+    for model_name, proposed in requested.items():
+        governing = resolve_model_budget(model=model_name, model_max_budget=existing_model_max_budget)
+        if governing is None:
+            continue
+        cap = governing.budget_config
+        if cap.max_budget is None:
             continue
-        proposed = requested.get(model_name)
-        if proposed is None:
-            raise HTTPException(
-                status_code=403,
-                detail={
-                    "error": (
-                        f"Only a proxy admin can remove a team's model_max_budget for {model_name!r}. "
-                        f"Current max_budget={existing.max_budget}."
-                    )
-                },
-            )
         if (
             proposed.max_budget is None
-            or proposed.max_budget > existing.max_budget
-            or proposed.budget_duration != existing.budget_duration
+            or proposed.max_budget > cap.max_budget
+            or proposed.budget_duration != cap.budget_duration
         ):
             raise HTTPException(
                 status_code=403,
                 detail={
                     "error": (
                         f"Only a proxy admin can raise a team's model_max_budget for {model_name!r} or change its "
-                        f"budget_duration. Current max_budget={existing.max_budget} per {existing.budget_duration}, "
-                        f"requested={proposed.max_budget} per {proposed.budget_duration}."
+                        f"budget_duration. Current max_budget={cap.max_budget} per {cap.budget_duration} "
+                        f"(entry {governing.budget_model!r}), requested={proposed.max_budget} per "
+                        f"{proposed.budget_duration}."
                     )
                 },
             )
diff --git a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py
index dda5bb344b4..6478b18e553 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_team_endpoints.py
@@ -14668,8 +14668,21 @@ _EXISTING_TEAM_MODEL_CAPS: Final = {
         {"claude-sonnet-4-6": _EXISTING_TEAM_MODEL_CAPS["claude-sonnet-4-6"]},
         {},
         None,
+        {**_EXISTING_TEAM_MODEL_CAPS, "openai/gpt-4o": {"max_budget": 1000.0, "budget_duration": "1d"}},
+        {**_EXISTING_TEAM_MODEL_CAPS, "openai/gpt-4o": {"max_budget": 10.0, "budget_duration": "30d"}},
+        {**_EXISTING_TEAM_MODEL_CAPS, "anthropic/claude-sonnet-4-6": {"budget_duration": "7d"}},
+    ],
+    ids=[
+        "raise",
+        "change_duration",
+        "drop_cap_value",
+        "remove_model",
+        "clear_all",
+        "clear_with_null",
+        "raise_via_provider_alias",
+        "rewindow_via_provider_alias",
+        "uncap_via_provider_alias",
     ],
-    ids=["raise", "change_duration", "drop_cap_value", "remove_model", "clear_all", "clear_with_null"],
 )
 def test_team_admin_cannot_loosen_team_model_caps(requested) -> None:
     from litellm.proxy.management_endpoints.team_endpoints import _check_team_model_budget_update_authority
@@ -14690,8 +14703,9 @@ def test_team_admin_cannot_loosen_team_model_caps(requested) -> None:
         {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o": {"max_budget": 2.0, "budget_duration": "1d"}},
         {**_EXISTING_TEAM_MODEL_CAPS, "gpt-4o-mini": {"max_budget": 1.0, "budget_duration": "1d"}},
         dict(_EXISTING_TEAM_MODEL_CAPS),
+        {**_EXISTING_TEAM_MODEL_CAPS, "openai/gpt-4o": {"max_budget": 2.0, "budget_duration": "1d"}},
     ],
-    ids=["lower", "add_model", "unchanged"],
+    ids=["lower", "add_model", "unchanged", "tighten_via_provider_alias"],
 )
 def test_team_admin_can_tighten_or_keep_team_model_caps(requested) -> None:
     from litellm.proxy.management_endpoints.team_endpoints import _check_team_model_budget_update_authority

From 1aa2e19ee4dc46a861c65ba7ebb506d41c307908 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 19:52:00 -0700
Subject: [PATCH 15/76] test(together_ai): stop depending on a serverless model
 we do not control

Together moved openai/gpt-oss-20b off serverless, so three tests started
failing with a 400 model_not_available from the live API. None of them was
really testing Together: they cover provider-prefix parsing, prompt shaping
and streaming, all litellm side. Mock the transport and assert those, so the
tests answer to our code instead of a vendor catalog.
---
 tests/local_testing/test_completion.py | 109 ++++++++++++++++++-------
 1 file changed, 80 insertions(+), 29 deletions(-)

diff --git a/tests/local_testing/test_completion.py b/tests/local_testing/test_completion.py
index 43ed57f63af..a6ac112a3b7 100644
--- a/tests/local_testing/test_completion.py
+++ b/tests/local_testing/test_completion.py
@@ -11,6 +11,7 @@ import io
 
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import httpx
 import pytest
 
 import litellm
@@ -57,21 +58,49 @@ def test_response_model_none():
     assert isinstance(x, litellm.ModelResponse)
 
 
+TOGETHER_AI_CHAT_URL = "https://api.together.ai/v1/chat/completions"
+
+
+def _together_ai_chat_response(content="Hello!"):
+    return httpx.Response(
+        200,
+        json={
+            "id": "chatcmpl-together",
+            "object": "chat.completion",
+            "created": 1,
+            "model": "openai/gpt-oss-20b",
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {"role": "assistant", "content": content},
+                    "finish_reason": "stop",
+                }
+            ],
+            "usage": {
+                "prompt_tokens": 1,
+                "completion_tokens": 1,
+                "total_tokens": 2,
+            },
+        },
+        request=httpx.Request("POST", TOGETHER_AI_CHAT_URL),
+    )
+
+
 def test_completion_custom_provider_model_name():
-    try:
-        litellm.cache = None
+    litellm.cache = None
+    with patch.object(
+        HTTPHandler, "post", return_value=_together_ai_chat_response()
+    ) as mock_post:
         response = completion(
             model="together_ai/openai/gpt-oss-20b",
             messages=messages,
             logger_fn=logger_fn,
+            api_key="fake-key",
         )
-        # Add assertions here to check the-response
-        print(response)
-        print(response["choices"][0]["finish_reason"])
-    except litellm.Timeout as e:
-        pass
-    except Exception as e:
-        pytest.fail(f"Error occurred: {e}")
+
+    assert mock_post.call_args.kwargs["url"] == TOGETHER_AI_CHAT_URL
+    assert json.loads(mock_post.call_args.kwargs["data"])["model"] == "openai/gpt-oss-20b"
+    assert response.choices[0].finish_reason == "stop"
 
 
 def _openai_mock_response(*args, **kwargs) -> litellm.ModelResponse:
@@ -2804,12 +2833,11 @@ def test_completion_together_ai_llama():
 
 # test_completion_together_ai()
 def test_customprompt_together_ai():
-    try:
-        litellm.set_verbose = False
-        litellm.num_retries = 0
-        print("in test_customprompt_together_ai")
-        print(litellm.success_callback)
-        print(litellm._async_success_callback)
+    litellm.set_verbose = False
+    litellm.num_retries = 0
+    with patch.object(
+        HTTPHandler, "post", return_value=_together_ai_chat_response()
+    ) as mock_post:
         response = completion(
             model="together_ai/openai/gpt-oss-20b",
             messages=messages,
@@ -2827,14 +2855,14 @@ def test_customprompt_together_ai():
                     "post_message": "<|im_end|>",
                 },
             },
+            api_key="fake-key",
         )
-        print(response)
-    except litellm.exceptions.Timeout as e:
-        print(f"Timeout Error")
-        pass
-    except Exception as e:
-        print(f"ERROR TYPE {type(e)}")
-        pytest.fail(f"Error occurred: {e}")
+
+    body = json.loads(mock_post.call_args.kwargs["data"])
+    assert body["messages"] == messages
+    assert "prompt" not in body
+    assert "roles" not in body
+    assert response.choices[0].finish_reason == "stop"
 
 
 # test_customprompt_together_ai()
@@ -3648,19 +3676,42 @@ def test_completion_together_ai_stream():
     litellm.set_verbose = True
     user_message = "Write 1pg about YC & litellm"
     messages = [{"content": user_message, "role": "user"}]
-    try:
+    sse_body = (
+        'data: {"id":"chatcmpl-together","object":"chat.completion.chunk","created":1,'
+        '"model":"openai/gpt-oss-20b","choices":[{"index":0,"delta":{"role":"assistant",'
+        '"content":"YC"},"finish_reason":null}]}\n\n'
+        'data: {"id":"chatcmpl-together","object":"chat.completion.chunk","created":1,'
+        '"model":"openai/gpt-oss-20b","choices":[{"index":0,"delta":{"content":" and '
+        'litellm"},"finish_reason":null}]}\n\n'
+        'data: {"id":"chatcmpl-together","object":"chat.completion.chunk","created":1,'
+        '"model":"openai/gpt-oss-20b","choices":[{"index":0,"delta":{},'
+        '"finish_reason":"stop"}]}\n\n'
+        "data: [DONE]\n\n"
+    )
+    stream_response = httpx.Response(
+        200,
+        content=sse_body.encode(),
+        headers={"content-type": "text/event-stream"},
+        request=httpx.Request("POST", TOGETHER_AI_CHAT_URL),
+    )
+
+    with patch.object(
+        HTTPHandler, "post", return_value=stream_response
+    ) as mock_post:
         response = completion(
             model="together_ai/openai/gpt-oss-20b",
             messages=messages,
             stream=True,
             max_tokens=5,
+            api_key="fake-key",
         )
-        print(response)
-        for chunk in response:
-            print(chunk)
-        # print(string_response)
-    except Exception as e:
-        pytest.fail(f"Error occurred: {e}")
+        chunks = list(response)
+
+    assert json.loads(mock_post.call_args.kwargs["data"])["stream"] is True
+    assert "".join(
+        chunk.choices[0].delta.content or "" for chunk in chunks
+    ) == "YC and litellm"
+    assert chunks[-1].choices[0].finish_reason == "stop"
 
 
 # test_completion_together_ai_stream()

From 8c046e13bdcbd61f570f10f674ff57b2dcf19afb Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Tue, 15 Sep 2026 20:17:42 -0700
Subject: [PATCH 16/76] test(together_ai): move request-shape checks to the
 mapped file, drop the live ones

Together moved openai/gpt-oss-20b off serverless and three tests in
test_completion.py died on a live 400. None of them needed Together to be up:
streaming is already covered live by tests/e2e/llm_translation/test_together_ai_e2e.py,
which picks its model from the cost map instead of pinning one, and the other
two are request-shape questions. Delete all three and assert the two shapes in
the mapped transformation file: the provider prefix is stripped without eating
the rest of a slashed model name, and custom role wrappers never reach the
request.
---
 tests/local_testing/test_completion.py        | 125 ------------------
 .../test_together_ai_chat_transformation.py   |  64 +++++++++
 2 files changed, 64 insertions(+), 125 deletions(-)

diff --git a/tests/local_testing/test_completion.py b/tests/local_testing/test_completion.py
index a6ac112a3b7..25c6c50251d 100644
--- a/tests/local_testing/test_completion.py
+++ b/tests/local_testing/test_completion.py
@@ -11,7 +11,6 @@ import io
 
 from unittest.mock import AsyncMock, MagicMock, patch
 
-import httpx
 import pytest
 
 import litellm
@@ -58,51 +57,6 @@ def test_response_model_none():
     assert isinstance(x, litellm.ModelResponse)
 
 
-TOGETHER_AI_CHAT_URL = "https://api.together.ai/v1/chat/completions"
-
-
-def _together_ai_chat_response(content="Hello!"):
-    return httpx.Response(
-        200,
-        json={
-            "id": "chatcmpl-together",
-            "object": "chat.completion",
-            "created": 1,
-            "model": "openai/gpt-oss-20b",
-            "choices": [
-                {
-                    "index": 0,
-                    "message": {"role": "assistant", "content": content},
-                    "finish_reason": "stop",
-                }
-            ],
-            "usage": {
-                "prompt_tokens": 1,
-                "completion_tokens": 1,
-                "total_tokens": 2,
-            },
-        },
-        request=httpx.Request("POST", TOGETHER_AI_CHAT_URL),
-    )
-
-
-def test_completion_custom_provider_model_name():
-    litellm.cache = None
-    with patch.object(
-        HTTPHandler, "post", return_value=_together_ai_chat_response()
-    ) as mock_post:
-        response = completion(
-            model="together_ai/openai/gpt-oss-20b",
-            messages=messages,
-            logger_fn=logger_fn,
-            api_key="fake-key",
-        )
-
-    assert mock_post.call_args.kwargs["url"] == TOGETHER_AI_CHAT_URL
-    assert json.loads(mock_post.call_args.kwargs["data"])["model"] == "openai/gpt-oss-20b"
-    assert response.choices[0].finish_reason == "stop"
-
-
 def _openai_mock_response(*args, **kwargs) -> litellm.ModelResponse:
     new_response = MagicMock()
     new_response.headers = {"hello": "world"}
@@ -2832,40 +2786,6 @@ def test_completion_together_ai_llama():
 
 
 # test_completion_together_ai()
-def test_customprompt_together_ai():
-    litellm.set_verbose = False
-    litellm.num_retries = 0
-    with patch.object(
-        HTTPHandler, "post", return_value=_together_ai_chat_response()
-    ) as mock_post:
-        response = completion(
-            model="together_ai/openai/gpt-oss-20b",
-            messages=messages,
-            roles={
-                "system": {
-                    "pre_message": "<|im_start|>system\n",
-                    "post_message": "<|im_end|>",
-                },
-                "assistant": {
-                    "pre_message": "<|im_start|>assistant\n",
-                    "post_message": "<|im_end|>",
-                },
-                "user": {
-                    "pre_message": "<|im_start|>user\n",
-                    "post_message": "<|im_end|>",
-                },
-            },
-            api_key="fake-key",
-        )
-
-    body = json.loads(mock_post.call_args.kwargs["data"])
-    assert body["messages"] == messages
-    assert "prompt" not in body
-    assert "roles" not in body
-    assert response.choices[0].finish_reason == "stop"
-
-
-# test_customprompt_together_ai()
 
 
 def response_format_tests(response: litellm.ModelResponse):
@@ -3672,51 +3592,6 @@ async def test_acompletion_stream_watsonx():
 # test_maritalk()
 
 
-def test_completion_together_ai_stream():
-    litellm.set_verbose = True
-    user_message = "Write 1pg about YC & litellm"
-    messages = [{"content": user_message, "role": "user"}]
-    sse_body = (
-        'data: {"id":"chatcmpl-together","object":"chat.completion.chunk","created":1,'
-        '"model":"openai/gpt-oss-20b","choices":[{"index":0,"delta":{"role":"assistant",'
-        '"content":"YC"},"finish_reason":null}]}\n\n'
-        'data: {"id":"chatcmpl-together","object":"chat.completion.chunk","created":1,'
-        '"model":"openai/gpt-oss-20b","choices":[{"index":0,"delta":{"content":" and '
-        'litellm"},"finish_reason":null}]}\n\n'
-        'data: {"id":"chatcmpl-together","object":"chat.completion.chunk","created":1,'
-        '"model":"openai/gpt-oss-20b","choices":[{"index":0,"delta":{},'
-        '"finish_reason":"stop"}]}\n\n'
-        "data: [DONE]\n\n"
-    )
-    stream_response = httpx.Response(
-        200,
-        content=sse_body.encode(),
-        headers={"content-type": "text/event-stream"},
-        request=httpx.Request("POST", TOGETHER_AI_CHAT_URL),
-    )
-
-    with patch.object(
-        HTTPHandler, "post", return_value=stream_response
-    ) as mock_post:
-        response = completion(
-            model="together_ai/openai/gpt-oss-20b",
-            messages=messages,
-            stream=True,
-            max_tokens=5,
-            api_key="fake-key",
-        )
-        chunks = list(response)
-
-    assert json.loads(mock_post.call_args.kwargs["data"])["stream"] is True
-    assert "".join(
-        chunk.choices[0].delta.content or "" for chunk in chunks
-    ) == "YC and litellm"
-    assert chunks[-1].choices[0].finish_reason == "stop"
-
-
-# test_completion_together_ai_stream()
-
-
 def test_moderation():
     response = litellm.moderation(input="i'm ishaan cto of litellm")
     print(response)
diff --git a/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py b/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py
index 7eb7dc41d4f..a7347edb2c7 100644
--- a/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py
+++ b/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py
@@ -1108,3 +1108,67 @@ def test_get_optional_params_preserves_max_for_declared_levels_model():
     )
 
     assert optional_params["reasoning_effort"] == "max"
+
+
+def _together_chat_transport() -> tuple[HTTPHandler, list[httpx.Request]]:
+    captured_requests: list[httpx.Request] = []
+
+    def respond(request: httpx.Request) -> httpx.Response:
+        captured_requests.append(request)
+        return httpx.Response(
+            200,
+            json={
+                "id": "chatcmpl-together",
+                "object": "chat.completion",
+                "created": 1234567890,
+                "model": TOOL_CALLING_MODEL,
+                "choices": [
+                    {
+                        "index": 0,
+                        "message": {"role": "assistant", "content": "Hello!"},
+                        "finish_reason": "stop",
+                    }
+                ],
+                "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+            },
+        )
+
+    client = HTTPHandler(client=httpx.Client(transport=httpx.MockTransport(respond)))
+    return client, captured_requests
+
+
+def test_only_the_provider_prefix_is_stripped_from_a_slashed_model_name():
+    client, captured_requests = _together_chat_transport()
+
+    litellm.completion(
+        model=f"together_ai/{TOOL_CALLING_MODEL}",
+        messages=[{"role": "user", "content": "Hello!"}],
+        api_key="fake-key",
+        client=client,
+    )
+
+    assert "/" in TOOL_CALLING_MODEL
+    assert str(captured_requests[0].url) == "https://api.together.ai/v1/chat/completions"
+    assert json.loads(captured_requests[0].content)["model"] == TOOL_CALLING_MODEL
+
+
+def test_custom_role_wrappers_never_reach_the_request():
+    client, captured_requests = _together_chat_transport()
+    messages = [{"role": "user", "content": "Hello!"}]
+
+    litellm.completion(
+        model=f"together_ai/{TOOL_CALLING_MODEL}",
+        messages=messages,
+        roles={
+            "system": {"pre_message": "<|im_start|>system\n", "post_message": "<|im_end|>"},
+            "assistant": {"pre_message": "<|im_start|>assistant\n", "post_message": "<|im_end|>"},
+            "user": {"pre_message": "<|im_start|>user\n", "post_message": "<|im_end|>"},
+        },
+        api_key="fake-key",
+        client=client,
+    )
+
+    request_body = json.loads(captured_requests[0].content)
+    assert request_body["messages"] == messages
+    assert "prompt" not in request_body
+    assert "roles" not in request_body

From 7bce15f7d8493096ced51023f7a239091bfcc1f2 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Fri, 11 Sep 2026 02:45:43 +0000
Subject: [PATCH 17/76] fix(otel): propagate W3C trace context on passthrough
 upstream requests

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/integrations/otel/plumbing/context.py | 36 ++++++++
 .../pass_through_endpoints.py                 | 30 +++---
 .../otel/test_otel_v2_components.py           | 81 ++++++++++++++++-
 .../test_pass_through_endpoints.py            | 91 +++++++++++++++++++
 4 files changed, 224 insertions(+), 14 deletions(-)

diff --git a/litellm/integrations/otel/plumbing/context.py b/litellm/integrations/otel/plumbing/context.py
index 21e61c71fb7..851097a17e7 100644
--- a/litellm/integrations/otel/plumbing/context.py
+++ b/litellm/integrations/otel/plumbing/context.py
@@ -310,6 +310,42 @@ def extract_traceparent(headers: Mapping[str, str]) -> Context | None:
     return _PROPAGATOR.extract(carrier)
 
 
+def _outgoing_trace_context(inbound_headers: Mapping[str, str] | None = None) -> Context | None:
+    root: Final = request_root_span()
+    if root is not None:
+        return context_from_span(root)
+
+    current: Final = get_current()
+    if is_recordable_span(get_current_span(current)):
+        return current
+
+    if inbound_headers is None:
+        return None
+    inbound_context: Final = extract_traceparent(inbound_headers)
+    if inbound_context is None or not is_recordable_span(get_current_span(inbound_context)):
+        return None
+    return inbound_context
+
+
+def inject_trace_context(
+    headers: Mapping[str, str],
+    inbound_headers: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """``headers`` plus W3C ``traceparent``/``tracestate`` for the current request's span.
+
+    Parent preference: the anchored request root span, then the ambient active span,
+    then the trace context the caller sent inbound. Only trace context is injected,
+    never Baggage, so per-request identity baggage cannot leak upstream. Unchanged
+    when no valid span context exists anywhere.
+    """
+    context: Final = _outgoing_trace_context(inbound_headers)
+    if context is None:
+        return dict(headers)  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
+    carrier: Final = dict(headers)  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
+    _PROPAGATOR.inject(carrier, context=context)
+    return carrier
+
+
 # The OTLP destinations this request's key or team pointed its traces at, resolved
 # once during auth. A ``ContextVar`` for the same reason the root span above is one:
 # it rides the request task's context into the ``asyncio.create_task`` children that
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 686544d352c..1c4f8d59c9c 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -955,6 +955,7 @@ async def pass_through_request(
             general_settings.pass_through_request_timeout, then 600s.
     """
     from litellm.exceptions import ModifyResponseException
+    from litellm.integrations.otel.plumbing.context import inject_trace_context
     from litellm.litellm_core_utils.litellm_logging import Logging
     from litellm.proxy.pass_through_endpoints.passthrough_guardrails import (
         PassthroughGuardrailHandler,
@@ -985,6 +986,7 @@ async def pass_through_request(
             headers=headers,
             forward_headers=forward_headers,
         )
+        headers = inject_trace_context(headers, inbound_headers=_safe_get_request_headers(request))
 
         requested_query_params: dict | None = query_params or dict(request.query_params)
 
@@ -2199,20 +2201,22 @@ async def websocket_passthrough_request(
         await websocket.accept()
         verbose_proxy_logger.debug("WebSocket passthrough (%s): WebSocket connection accepted", endpoint)
 
-    # Prepare headers for the upstream connection
-    upstream_headers: Final = custom_headers.copy()
+    from litellm.integrations.otel.plumbing.context import inject_trace_context
 
-    if forward_headers:
-        # Forward relevant headers from the incoming request
-        incoming_headers: Final = dict(websocket.headers)
-        for header_name, header_value in incoming_headers.items():
-            # Only forward certain headers to avoid conflicts
-            if header_name.lower() in [
-                "authorization",
-                "x-api-key",
-                "x-goog-user-project",
-            ]:
-                upstream_headers[header_name] = header_value
+    incoming_headers: Final = dict(websocket.headers)  # mutable-ok: websocket headers are copied for context extraction
+    forwarded_headers: Final = {  # mutable-ok: assembled as the upstream header carrier
+        **custom_headers,
+        **{
+            header_name: header_value
+            for header_name, header_value in incoming_headers.items()
+            if forward_headers
+            and header_name.lower() in frozenset(("authorization", "x-api-key", "x-goog-user-project"))
+        },
+    }
+    upstream_headers: Final = inject_trace_context(
+        forwarded_headers,
+        inbound_headers=incoming_headers,
+    )
 
     # Initialize logging object similar to HTTP passthrough
     team_callbacks: Final = _resolve_team_callback_wiring(
diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_components.py b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
index ae41c74944d..b1e65da1661 100644
--- a/tests/test_litellm/integrations/otel/test_otel_v2_components.py
+++ b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
@@ -5,6 +5,7 @@ builders, and the registry validator's failure paths. Needs the OTel SDK."""
 import json
 import threading
 from collections.abc import Iterator
+from contextvars import Context as ContextVarContext
 from dataclasses import replace
 from http.server import BaseHTTPRequestHandler, HTTPServer, ThreadingHTTPServer
 
@@ -15,6 +16,8 @@ pytest.importorskip("opentelemetry")
 from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (  # noqa: E402
     ExportTraceServiceRequest,
 )
+from opentelemetry import baggage  # noqa: E402
+from opentelemetry.context import attach, detach  # noqa: E402
 from opentelemetry.sdk.metrics import MeterProvider  # noqa: E402
 from opentelemetry.sdk.metrics.export import InMemoryMetricReader  # noqa: E402
 from opentelemetry.sdk.trace import TracerProvider  # noqa: E402
@@ -26,7 +29,10 @@ from opentelemetry.sdk.trace.export import (  # noqa: E402
 from opentelemetry.sdk.trace.export.in_memory_span_exporter import (  # noqa: E402
     InMemorySpanExporter,
 )
-from opentelemetry.trace import SpanKind  # noqa: E402
+from opentelemetry.trace import SpanKind, get_current_span  # noqa: E402
+from opentelemetry.trace.propagation.tracecontext import (  # noqa: E402
+    TraceContextTextMapPropagator,
+)
 
 from litellm.integrations.otel.plumbing import context as ctx_mod  # noqa: E402
 from litellm.integrations.otel.plumbing import providers  # noqa: E402
@@ -464,6 +470,79 @@ def test_extract_traceparent():
     assert ctx_mod.extract_traceparent({"x": "y"}) is None
 
 
+def _test_tracer():
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    return provider.get_tracer("test")
+
+
+def test_inject_trace_context_prefers_request_root_span():
+    def run():
+        tracer = _test_tracer()
+        with tracer.start_as_current_span("root") as root:
+            ctx_mod.set_request_root_span(root)
+            result = ctx_mod.inject_trace_context(
+                {"traceparent": "00-11111111111111111111111111111111-2222222222222222-01"}
+            )
+            propagated = get_current_span(TraceContextTextMapPropagator().extract(result))
+            return result, root, propagated
+
+    result, root, propagated = ContextVarContext().run(run)
+    assert result["traceparent"] != "00-11111111111111111111111111111111-2222222222222222-01"
+    assert propagated.get_span_context().trace_id == root.get_span_context().trace_id
+    assert propagated.get_span_context().span_id == root.get_span_context().span_id
+
+
+def test_inject_trace_context_uses_ambient_span_without_request_root():
+    def run():
+        tracer = _test_tracer()
+        with tracer.start_as_current_span("ambient") as ambient:
+            result = ctx_mod.inject_trace_context({})
+            propagated = get_current_span(TraceContextTextMapPropagator().extract(result))
+            return ambient, propagated
+
+    ambient, propagated = ContextVarContext().run(run)
+    assert propagated.get_span_context().trace_id == ambient.get_span_context().trace_id
+    assert propagated.get_span_context().span_id == ambient.get_span_context().span_id
+
+
+def test_inject_trace_context_forwards_valid_inbound_context_without_span():
+    inbound = {"traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}
+
+    def run():
+        result = ctx_mod.inject_trace_context({}, inbound_headers=inbound)
+        return get_current_span(TraceContextTextMapPropagator().extract(result))
+
+    propagated = ContextVarContext().run(run)
+    assert propagated.get_span_context().trace_id == int("0af7651916cd43dd8448eb211c80319c", 16)
+    assert propagated.get_span_context().span_id == int("b7ad6b7169203331", 16)
+
+
+def test_inject_trace_context_returns_headers_unchanged_without_context():
+    headers = {"x-custom": "value"}
+
+    result = ContextVarContext().run(lambda: ctx_mod.inject_trace_context(headers))
+
+    assert result == headers
+    assert "traceparent" not in result
+    assert result is not headers
+
+
+def test_inject_trace_context_does_not_forward_baggage():
+    def run():
+        tracer = _test_tracer()
+        with tracer.start_as_current_span("ambient"):
+            token = attach(baggage.set_baggage("litellm.team.id", "team"))
+            try:
+                return ctx_mod.inject_trace_context({})
+            finally:
+                detach(token)
+
+    result = ContextVarContext().run(run)
+    assert "baggage" not in result
+
+
 def test_set_request_baggage_empty_returns_context():
     assert ctx_mod.set_request_baggage({}) is not None
 
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index 0fc961cf8c9..c3ad900cc9e 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -4270,6 +4270,40 @@ def _relay_client_request(method="GET"):
     return mock_request
 
 
+@pytest.mark.asyncio
+async def test_pass_through_request_propagates_active_trace_context():
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.trace import get_current_span
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+    from litellm.proxy._types import UserAPIKeyAuth
+
+    captured: dict[str, httpx.Headers] = {}
+
+    def transport_handler(upstream_request: httpx.Request) -> httpx.Response:
+        captured["headers"] = upstream_request.headers
+        return httpx.Response(200, json={"ok": True}, request=upstream_request)
+
+    fake_client, cleanup = _inject_fake_passthrough_client(httpx.MockTransport(transport_handler), timeout=None)
+    try:
+        with ExitStack() as stack:
+            _enter_relay_logging_mocks(stack, {})
+            tracer = TracerProvider().get_tracer("test")
+            with tracer.start_as_current_span("passthrough") as span:
+                response = await pass_through_request(
+                    request=_relay_client_request(method="POST"),
+                    target="http://internal-api.test/v1/generate",
+                    custom_headers={},
+                    user_api_key_dict=UserAPIKeyAuth(api_key="sk-test"),
+                )
+    finally:
+        cleanup()
+        await fake_client.aclose()
+
+    assert response.status_code == 200
+    propagated = get_current_span(TraceContextTextMapPropagator().extract(captured["headers"]))
+    assert propagated.get_span_context().trace_id == span.get_span_context().trace_id
+
+
 @pytest.mark.asyncio
 async def test_pass_through_request_relays_non_json_body_without_buffering():
     """
@@ -4866,6 +4900,63 @@ async def test_websocket_passthrough_forwards_non_ascii_first_frame():
     assert all(call.kwargs.get("code") != 1011 for call in websocket.close.await_args_list)
 
 
+@pytest.mark.asyncio
+async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch):
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.trace import get_current_span
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+    from starlette.websockets import WebSocketState
+
+    captured: dict[str, dict[str, str]] = {}
+    upstream_ws = FakeUpstreamWebSocket(b"{}")
+
+    def fake_connect(target, additional_headers):
+        captured["headers"] = additional_headers
+        return FakeUpstreamConnect(upstream_ws)
+
+    websocket = MagicMock()
+    websocket.accept = AsyncMock()
+    websocket.send_text = AsyncMock()
+    websocket.send_bytes = AsyncMock()
+    websocket.receive = AsyncMock(return_value={"type": "websocket.disconnect"})
+    websocket.close = AsyncMock()
+    websocket.headers = {}
+    websocket.client_state = WebSocketState.CONNECTED
+    websocket.application_state = WebSocketState.CONNECTED
+    tracer = TracerProvider().get_tracer("test")
+
+    mock_proxy_logging = MagicMock()
+    mock_proxy_logging.pre_call_hook = AsyncMock(return_value={})
+    mock_proxy_logging.post_call_success_hook = AsyncMock()
+    mock_proxy_logging.post_call_failure_hook = AsyncMock()
+    mock_worker = MagicMock()
+    mock_worker.ensure_initialized_and_enqueue = MagicMock(
+        side_effect=lambda async_coroutine: async_coroutine.close()
+    )
+    monkeypatch.setattr("litellm.proxy.proxy_server.proxy_logging_obj", mock_proxy_logging)
+    monkeypatch.setattr(
+        "litellm.proxy.pass_through_endpoints.pass_through_endpoints.connect",
+        fake_connect,
+    )
+    monkeypatch.setattr(
+        "litellm.proxy.pass_through_endpoints.pass_through_endpoints.GLOBAL_LOGGING_WORKER",
+        mock_worker,
+    )
+    with tracer.start_as_current_span("websocket_passthrough") as span:
+        await websocket_passthrough_request(
+            websocket=websocket,
+            target="wss://upstream.example.test/v1/realtime",
+            custom_headers={},
+            user_api_key_dict=UserAPIKeyAuth(),
+            forward_headers=False,
+            endpoint="/realtime",
+            accept_websocket=True,
+        )
+
+    propagated = get_current_span(TraceContextTextMapPropagator().extract(captured["headers"]))
+    assert propagated.get_span_context().trace_id == span.get_span_context().trace_id
+
+
 class ClosingUpstreamWebSocket:
     def __init__(self, close_exc: Exception):
         self._close_exc = close_exc

From 7bcf848b39883c651514d8df0c366a8c89ce54e2 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Fri, 11 Sep 2026 02:47:01 +0000
Subject: [PATCH 18/76] refactor(passthrough): hoist websocket forwarded header
 set

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../pass_through_endpoints.py                  | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 1c4f8d59c9c..186318dccc1 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -2159,6 +2159,9 @@ def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
     return upstream_close
 
 
+_WEBSOCKET_FORWARDED_HEADERS: Final = frozenset(("authorization", "x-api-key", "x-goog-user-project"))
+
+
 async def websocket_passthrough_request(
     websocket: WebSocket,
     target: str,
@@ -2183,6 +2186,7 @@ async def websocket_passthrough_request(
         cost_per_request: Optional field - cost per request to the target endpoint
         setup_model_rewriter: Optional rewrite of the setup frame's model before it reaches the upstream
     """
+    from litellm.integrations.otel.plumbing.context import inject_trace_context
     from litellm.litellm_core_utils.litellm_logging import Logging
     from litellm.proxy.proxy_server import proxy_config, proxy_logging_obj
     from litellm.types.passthrough_endpoints.pass_through_endpoints import (
@@ -2201,22 +2205,16 @@ async def websocket_passthrough_request(
         await websocket.accept()
         verbose_proxy_logger.debug("WebSocket passthrough (%s): WebSocket connection accepted", endpoint)
 
-    from litellm.integrations.otel.plumbing.context import inject_trace_context
-
-    incoming_headers: Final = dict(websocket.headers)  # mutable-ok: websocket headers are copied for context extraction
-    forwarded_headers: Final = {  # mutable-ok: assembled as the upstream header carrier
+    incoming_headers: Final = dict(websocket.headers)  # mutable-ok: propagator carrier
+    forwarded_headers: Final = {  # mutable-ok: propagator carrier
         **custom_headers,
         **{
             header_name: header_value
             for header_name, header_value in incoming_headers.items()
-            if forward_headers
-            and header_name.lower() in frozenset(("authorization", "x-api-key", "x-goog-user-project"))
+            if forward_headers and header_name.lower() in _WEBSOCKET_FORWARDED_HEADERS
         },
     }
-    upstream_headers: Final = inject_trace_context(
-        forwarded_headers,
-        inbound_headers=incoming_headers,
-    )
+    upstream_headers: Final = inject_trace_context(forwarded_headers, inbound_headers=incoming_headers)
 
     # Initialize logging object similar to HTTP passthrough
     team_callbacks: Final = _resolve_team_callback_wiring(

From d2e8b9c6565478c9ce1f5ba1cca834537a1759af Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Fri, 11 Sep 2026 03:05:05 +0000
Subject: [PATCH 19/76] fix(otel): keep passthrough working when opentelemetry
 is not installed

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../pass_through_endpoints.py                      | 14 ++++++++++----
 .../test_pass_through_endpoints.py                 | 11 +++++++++++
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 186318dccc1..6d44b4fa6dc 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -955,7 +955,6 @@ async def pass_through_request(
             general_settings.pass_through_request_timeout, then 600s.
     """
     from litellm.exceptions import ModifyResponseException
-    from litellm.integrations.otel.plumbing.context import inject_trace_context
     from litellm.litellm_core_utils.litellm_logging import Logging
     from litellm.proxy.pass_through_endpoints.passthrough_guardrails import (
         PassthroughGuardrailHandler,
@@ -986,7 +985,7 @@ async def pass_through_request(
             headers=headers,
             forward_headers=forward_headers,
         )
-        headers = inject_trace_context(headers, inbound_headers=_safe_get_request_headers(request))
+        headers = _with_trace_context(headers, inbound_headers=_safe_get_request_headers(request))
 
         requested_query_params: dict | None = query_params or dict(request.query_params)
 
@@ -2162,6 +2161,14 @@ def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
 _WEBSOCKET_FORWARDED_HEADERS: Final = frozenset(("authorization", "x-api-key", "x-goog-user-project"))
 
 
+def _with_trace_context(headers: Mapping[str, str], inbound_headers: Mapping[str, str]) -> dict[str, str]:
+    try:
+        from litellm.integrations.otel.plumbing.context import inject_trace_context
+    except ImportError:
+        return dict(headers)  # mutable-ok: matches inject_trace_context's carrier return type
+    return inject_trace_context(headers, inbound_headers=inbound_headers)
+
+
 async def websocket_passthrough_request(
     websocket: WebSocket,
     target: str,
@@ -2186,7 +2193,6 @@ async def websocket_passthrough_request(
         cost_per_request: Optional field - cost per request to the target endpoint
         setup_model_rewriter: Optional rewrite of the setup frame's model before it reaches the upstream
     """
-    from litellm.integrations.otel.plumbing.context import inject_trace_context
     from litellm.litellm_core_utils.litellm_logging import Logging
     from litellm.proxy.proxy_server import proxy_config, proxy_logging_obj
     from litellm.types.passthrough_endpoints.pass_through_endpoints import (
@@ -2214,7 +2220,7 @@ async def websocket_passthrough_request(
             if forward_headers and header_name.lower() in _WEBSOCKET_FORWARDED_HEADERS
         },
     }
-    upstream_headers: Final = inject_trace_context(forwarded_headers, inbound_headers=incoming_headers)
+    upstream_headers: Final = _with_trace_context(forwarded_headers, inbound_headers=incoming_headers)
 
     # Initialize logging object similar to HTTP passthrough
     team_callbacks: Final = _resolve_team_callback_wiring(
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index c3ad900cc9e..05371dccb23 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -2,6 +2,7 @@ import asyncio
 import json
 import logging
 import os
+import sys
 from collections.abc import Callable
 from contextlib import ExitStack, contextmanager
 from io import BytesIO
@@ -29,6 +30,7 @@ from litellm.proxy.pass_through_endpoints.pass_through_endpoints import (
     resolve_pass_through_request_timeout,
     resolve_llm_passthrough_timeout,
     websocket_passthrough_request,
+    _with_trace_context,
 )
 from litellm.integrations.custom_logger import CustomLogger
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
@@ -46,6 +48,15 @@ import litellm
 MESSAGE_START_SSE_FRAME = b'event: message_start\ndata: {"type": "message_start"}\n\n'
 
 
+def test_with_trace_context_without_opentelemetry(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setitem(sys.modules, "litellm.integrations.otel.plumbing.context", None)
+
+    headers = _with_trace_context({"authorization": "x"}, {})
+
+    assert headers == {"authorization": "x"}
+    assert "traceparent" not in headers
+
+
 # Test is_multipart
 def test_is_multipart():
     # Test with multipart content type

From e4a12510f647fb9ef5a790f93f1b829b78f7d905 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Fri, 11 Sep 2026 03:22:10 +0000
Subject: [PATCH 20/76] test(otel): cover websocket forwarded headers

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../pass_through_endpoints/test_pass_through_endpoints.py     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index 05371dccb23..d81e3ae5af8 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -4931,7 +4931,7 @@ async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch
     websocket.send_bytes = AsyncMock()
     websocket.receive = AsyncMock(return_value={"type": "websocket.disconnect"})
     websocket.close = AsyncMock()
-    websocket.headers = {}
+    websocket.headers = {"authorization": "Bearer client"}
     websocket.client_state = WebSocketState.CONNECTED
     websocket.application_state = WebSocketState.CONNECTED
     tracer = TracerProvider().get_tracer("test")
@@ -4959,7 +4959,7 @@ async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch
             target="wss://upstream.example.test/v1/realtime",
             custom_headers={},
             user_api_key_dict=UserAPIKeyAuth(),
-            forward_headers=False,
+            forward_headers=True,
             endpoint="/realtime",
             accept_websocket=True,
         )

From 68cc12e848fb445b42aa27e6c005e91b17595e41 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Fri, 11 Sep 2026 03:36:35 +0000
Subject: [PATCH 21/76] test(otel): assert websocket forwarded header reaches
 upstream

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../proxy/pass_through_endpoints/test_pass_through_endpoints.py  | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index d81e3ae5af8..a21f695493b 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -4966,6 +4966,7 @@ async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch
 
     propagated = get_current_span(TraceContextTextMapPropagator().extract(captured["headers"]))
     assert propagated.get_span_context().trace_id == span.get_span_context().trace_id
+    assert captured["headers"]["authorization"] == "Bearer client"
 
 
 class ClosingUpstreamWebSocket:

From 7ba073aa2668820a35c69dede3ef46ed7b837cc6 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Fri, 11 Sep 2026 03:47:09 +0000
Subject: [PATCH 22/76] test(otel): cover websocket trace propagation with
 forwarding on and off

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../pass_through_endpoints/test_pass_through_endpoints.py  | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index a21f695493b..0603b5cb2ff 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -4912,7 +4912,8 @@ async def test_websocket_passthrough_forwards_non_ascii_first_frame():
 
 
 @pytest.mark.asyncio
-async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch):
+@pytest.mark.parametrize("forward_headers", [True, False])
+async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch, forward_headers: bool):
     from opentelemetry.sdk.trace import TracerProvider
     from opentelemetry.trace import get_current_span
     from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
@@ -4959,14 +4960,14 @@ async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch
             target="wss://upstream.example.test/v1/realtime",
             custom_headers={},
             user_api_key_dict=UserAPIKeyAuth(),
-            forward_headers=True,
+            forward_headers=forward_headers,
             endpoint="/realtime",
             accept_websocket=True,
         )
 
     propagated = get_current_span(TraceContextTextMapPropagator().extract(captured["headers"]))
     assert propagated.get_span_context().trace_id == span.get_span_context().trace_id
-    assert captured["headers"]["authorization"] == "Bearer client"
+    assert captured["headers"].get("authorization") == ("Bearer client" if forward_headers else None)
 
 
 class ClosingUpstreamWebSocket:

From 05ededf8a05c3b290c38e73a747bd602a49033d3 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Wed, 16 Sep 2026 07:24:52 +0000
Subject: [PATCH 23/76] fix(otel): parent passthrough trace propagation on the
 legacy request span

Pass user_api_key_dict.parent_otel_span into the outgoing W3C injection so the
legacy otel callback propagates its litellm_request span, falling back to the
otel_v2 request root span and then the ambient span. Extend the mapped unit
tests to assert the propagated trace and span ids over real captured headers
for HTTP and WebSocket passthrough with forwarding on and off.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/integrations/otel/plumbing/context.py | 29 +++++-------
 .../pass_through_endpoints.py                 | 13 +++---
 .../otel/test_otel_v2_components.py           | 32 +++++++++----
 .../test_pass_through_endpoints.py            | 46 +++++++++++++------
 4 files changed, 74 insertions(+), 46 deletions(-)

diff --git a/litellm/integrations/otel/plumbing/context.py b/litellm/integrations/otel/plumbing/context.py
index 851097a17e7..3dabd34c81c 100644
--- a/litellm/integrations/otel/plumbing/context.py
+++ b/litellm/integrations/otel/plumbing/context.py
@@ -310,7 +310,10 @@ def extract_traceparent(headers: Mapping[str, str]) -> Context | None:
     return _PROPAGATOR.extract(carrier)
 
 
-def _outgoing_trace_context(inbound_headers: Mapping[str, str] | None = None) -> Context | None:
+def _outgoing_trace_context(parent_span: object) -> Context | None:
+    if isinstance(parent_span, Span) and is_recordable_span(parent_span):
+        return context_from_span(parent_span)
+
     root: Final = request_root_span()
     if root is not None:
         return context_from_span(root)
@@ -318,27 +321,19 @@ def _outgoing_trace_context(inbound_headers: Mapping[str, str] | None = None) ->
     current: Final = get_current()
     if is_recordable_span(get_current_span(current)):
         return current
-
-    if inbound_headers is None:
-        return None
-    inbound_context: Final = extract_traceparent(inbound_headers)
-    if inbound_context is None or not is_recordable_span(get_current_span(inbound_context)):
-        return None
-    return inbound_context
+    return None
 
 
-def inject_trace_context(
-    headers: Mapping[str, str],
-    inbound_headers: Mapping[str, str] | None = None,
-) -> dict[str, str]:
+def inject_trace_context(headers: Mapping[str, str], parent_span: object = None) -> dict[str, str]:
     """``headers`` plus W3C ``traceparent``/``tracestate`` for the current request's span.
 
-    Parent preference: the anchored request root span, then the ambient active span,
-    then the trace context the caller sent inbound. Only trace context is injected,
-    never Baggage, so per-request identity baggage cannot leak upstream. Unchanged
-    when no valid span context exists anywhere.
+    Parent preference: the request span auth stashed on the key (the legacy
+    ``litellm_request`` SERVER span, or the FastAPI server span under otel_v2), then
+    the anchored request root span, then the ambient active span. Only trace context
+    is injected, never Baggage, so per-request identity baggage cannot leak upstream.
+    Unchanged when no valid span context exists anywhere.
     """
-    context: Final = _outgoing_trace_context(inbound_headers)
+    context: Final = _outgoing_trace_context(parent_span)
     if context is None:
         return dict(headers)  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
     carrier: Final = dict(headers)  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index 6d44b4fa6dc..c8c2db0dbd6 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -985,7 +985,7 @@ async def pass_through_request(
             headers=headers,
             forward_headers=forward_headers,
         )
-        headers = _with_trace_context(headers, inbound_headers=_safe_get_request_headers(request))
+        headers = _with_trace_context(headers, parent_span=user_api_key_dict.parent_otel_span)
 
         requested_query_params: dict | None = query_params or dict(request.query_params)
 
@@ -2161,12 +2161,12 @@ def _upstream_close_to_relay(task_results: Iterable[object]) -> Close | None:
 _WEBSOCKET_FORWARDED_HEADERS: Final = frozenset(("authorization", "x-api-key", "x-goog-user-project"))
 
 
-def _with_trace_context(headers: Mapping[str, str], inbound_headers: Mapping[str, str]) -> dict[str, str]:
+def _with_trace_context(headers: Mapping[str, str], parent_span: object) -> dict[str, str]:
     try:
         from litellm.integrations.otel.plumbing.context import inject_trace_context
     except ImportError:
         return dict(headers)  # mutable-ok: matches inject_trace_context's carrier return type
-    return inject_trace_context(headers, inbound_headers=inbound_headers)
+    return inject_trace_context(headers, parent_span=parent_span)
 
 
 async def websocket_passthrough_request(
@@ -2211,16 +2211,15 @@ async def websocket_passthrough_request(
         await websocket.accept()
         verbose_proxy_logger.debug("WebSocket passthrough (%s): WebSocket connection accepted", endpoint)
 
-    incoming_headers: Final = dict(websocket.headers)  # mutable-ok: propagator carrier
-    forwarded_headers: Final = {  # mutable-ok: propagator carrier
+    forwarded_headers: Final = {  # mutable-ok: one-shot upstream header dict, read as a Mapping
         **custom_headers,
         **{
             header_name: header_value
-            for header_name, header_value in incoming_headers.items()
+            for header_name, header_value in websocket.headers.items()
             if forward_headers and header_name.lower() in _WEBSOCKET_FORWARDED_HEADERS
         },
     }
-    upstream_headers: Final = _with_trace_context(forwarded_headers, inbound_headers=incoming_headers)
+    upstream_headers: Final = _with_trace_context(forwarded_headers, parent_span=user_api_key_dict.parent_otel_span)
 
     # Initialize logging object similar to HTTP passthrough
     team_callbacks: Final = _resolve_team_callback_wiring(
diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_components.py b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
index b1e65da1661..43546241d06 100644
--- a/tests/test_litellm/integrations/otel/test_otel_v2_components.py
+++ b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
@@ -507,16 +507,32 @@ def test_inject_trace_context_uses_ambient_span_without_request_root():
     assert propagated.get_span_context().span_id == ambient.get_span_context().span_id
 
 
-def test_inject_trace_context_forwards_valid_inbound_context_without_span():
-    inbound = {"traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}
-
+def test_inject_trace_context_prefers_explicit_parent_span_over_root_and_ambient():
     def run():
-        result = ctx_mod.inject_trace_context({}, inbound_headers=inbound)
-        return get_current_span(TraceContextTextMapPropagator().extract(result))
+        tracer = _test_tracer()
+        parent = tracer.start_span("litellm_request")
+        with tracer.start_as_current_span("ambient") as ambient:
+            ctx_mod.set_request_root_span(ambient)
+            result = ctx_mod.inject_trace_context({}, parent_span=parent)
+            propagated = get_current_span(TraceContextTextMapPropagator().extract(result))
+            return parent, ambient, propagated
 
-    propagated = ContextVarContext().run(run)
-    assert propagated.get_span_context().trace_id == int("0af7651916cd43dd8448eb211c80319c", 16)
-    assert propagated.get_span_context().span_id == int("b7ad6b7169203331", 16)
+    parent, ambient, propagated = ContextVarContext().run(run)
+    assert propagated.get_span_context().trace_id == parent.get_span_context().trace_id
+    assert propagated.get_span_context().span_id == parent.get_span_context().span_id
+    assert propagated.get_span_context().span_id != ambient.get_span_context().span_id
+
+
+def test_inject_trace_context_skips_unusable_parent_span():
+    def run():
+        tracer = _test_tracer()
+        with tracer.start_as_current_span("ambient") as ambient:
+            result = ctx_mod.inject_trace_context({}, parent_span=object())
+            propagated = get_current_span(TraceContextTextMapPropagator().extract(result))
+            return ambient, propagated
+
+    ambient, propagated = ContextVarContext().run(run)
+    assert propagated.get_span_context().span_id == ambient.get_span_context().span_id
 
 
 def test_inject_trace_context_returns_headers_unchanged_without_context():
diff --git a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
index 0603b5cb2ff..d6b9a782f99 100644
--- a/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
+++ b/tests/test_litellm/proxy/pass_through_endpoints/test_pass_through_endpoints.py
@@ -51,7 +51,7 @@ MESSAGE_START_SSE_FRAME = b'event: message_start\ndata: {"type": "message_start"
 def test_with_trace_context_without_opentelemetry(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.setitem(sys.modules, "litellm.integrations.otel.plumbing.context", None)
 
-    headers = _with_trace_context({"authorization": "x"}, {})
+    headers = _with_trace_context({"authorization": "x"}, parent_span=None)
 
     assert headers == {"authorization": "x"}
     assert "traceparent" not in headers
@@ -4282,11 +4282,11 @@ def _relay_client_request(method="GET"):
 
 
 @pytest.mark.asyncio
-async def test_pass_through_request_propagates_active_trace_context():
+@pytest.mark.parametrize("span_source", ["auth_parent_span", "ambient_span"])
+async def test_pass_through_request_propagates_active_trace_context(span_source: str):
     from opentelemetry.sdk.trace import TracerProvider
     from opentelemetry.trace import get_current_span
     from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
-    from litellm.proxy._types import UserAPIKeyAuth
 
     captured: dict[str, httpx.Headers] = {}
 
@@ -4295,17 +4295,23 @@ async def test_pass_through_request_propagates_active_trace_context():
         return httpx.Response(200, json={"ok": True}, request=upstream_request)
 
     fake_client, cleanup = _inject_fake_passthrough_client(httpx.MockTransport(transport_handler), timeout=None)
+    tracer = TracerProvider().get_tracer("test")
     try:
         with ExitStack() as stack:
             _enter_relay_logging_mocks(stack, {})
-            tracer = TracerProvider().get_tracer("test")
-            with tracer.start_as_current_span("passthrough") as span:
-                response = await pass_through_request(
-                    request=_relay_client_request(method="POST"),
-                    target="http://internal-api.test/v1/generate",
-                    custom_headers={},
-                    user_api_key_dict=UserAPIKeyAuth(api_key="sk-test"),
-                )
+            if span_source == "auth_parent_span":
+                span = tracer.start_span("litellm_request")
+                stack.callback(span.end)
+                user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", parent_otel_span=span)
+            else:
+                span = stack.enter_context(tracer.start_as_current_span("passthrough"))
+                user_api_key_dict = UserAPIKeyAuth(api_key="sk-test")
+            response = await pass_through_request(
+                request=_relay_client_request(method="POST"),
+                target="http://internal-api.test/v1/generate",
+                custom_headers={},
+                user_api_key_dict=user_api_key_dict,
+            )
     finally:
         cleanup()
         await fake_client.aclose()
@@ -4313,6 +4319,7 @@ async def test_pass_through_request_propagates_active_trace_context():
     assert response.status_code == 200
     propagated = get_current_span(TraceContextTextMapPropagator().extract(captured["headers"]))
     assert propagated.get_span_context().trace_id == span.get_span_context().trace_id
+    assert propagated.get_span_context().span_id == span.get_span_context().span_id
 
 
 @pytest.mark.asyncio
@@ -4913,7 +4920,10 @@ async def test_websocket_passthrough_forwards_non_ascii_first_frame():
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize("forward_headers", [True, False])
-async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch, forward_headers: bool):
+@pytest.mark.parametrize("span_source", ["auth_parent_span", "ambient_span"])
+async def test_websocket_passthrough_propagates_active_trace_context(
+    monkeypatch, forward_headers: bool, span_source: str
+):
     from opentelemetry.sdk.trace import TracerProvider
     from opentelemetry.trace import get_current_span
     from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
@@ -4954,12 +4964,19 @@ async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch
         "litellm.proxy.pass_through_endpoints.pass_through_endpoints.GLOBAL_LOGGING_WORKER",
         mock_worker,
     )
-    with tracer.start_as_current_span("websocket_passthrough") as span:
+    with ExitStack() as stack:
+        if span_source == "auth_parent_span":
+            span = tracer.start_span("litellm_request")
+            stack.callback(span.end)
+            user_api_key_dict = UserAPIKeyAuth(parent_otel_span=span)
+        else:
+            span = stack.enter_context(tracer.start_as_current_span("websocket_passthrough"))
+            user_api_key_dict = UserAPIKeyAuth()
         await websocket_passthrough_request(
             websocket=websocket,
             target="wss://upstream.example.test/v1/realtime",
             custom_headers={},
-            user_api_key_dict=UserAPIKeyAuth(),
+            user_api_key_dict=user_api_key_dict,
             forward_headers=forward_headers,
             endpoint="/realtime",
             accept_websocket=True,
@@ -4967,6 +4984,7 @@ async def test_websocket_passthrough_propagates_active_trace_context(monkeypatch
 
     propagated = get_current_span(TraceContextTextMapPropagator().extract(captured["headers"]))
     assert propagated.get_span_context().trace_id == span.get_span_context().trace_id
+    assert propagated.get_span_context().span_id == span.get_span_context().span_id
     assert captured["headers"].get("authorization") == ("Bearer client" if forward_headers else None)
 
 

From 8899583d06ea4f570136cdcdecceb41f2de652f6 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Wed, 16 Sep 2026 07:33:39 +0000
Subject: [PATCH 24/76] docs(otel): tighten inject_trace_context docstring

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/integrations/otel/plumbing/context.py | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/litellm/integrations/otel/plumbing/context.py b/litellm/integrations/otel/plumbing/context.py
index 3dabd34c81c..57e220815b5 100644
--- a/litellm/integrations/otel/plumbing/context.py
+++ b/litellm/integrations/otel/plumbing/context.py
@@ -325,13 +325,11 @@ def _outgoing_trace_context(parent_span: object) -> Context | None:
 
 
 def inject_trace_context(headers: Mapping[str, str], parent_span: object = None) -> dict[str, str]:
-    """``headers`` plus W3C ``traceparent``/``tracestate`` for the current request's span.
+    """``headers`` plus W3C ``traceparent``/``tracestate`` for this request's span.
 
-    Parent preference: the request span auth stashed on the key (the legacy
-    ``litellm_request`` SERVER span, or the FastAPI server span under otel_v2), then
-    the anchored request root span, then the ambient active span. Only trace context
-    is injected, never Baggage, so per-request identity baggage cannot leak upstream.
-    Unchanged when no valid span context exists anywhere.
+    Parent preference: ``parent_span`` (the request span auth stashed on the key), then
+    the anchored request root span, then the ambient active span. Only trace context is
+    injected, never Baggage. Unchanged when no valid span exists anywhere.
     """
     context: Final = _outgoing_trace_context(parent_span)
     if context is None:

From b82de95625cb807e892a223f90004d46c43589c0 Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Wed, 16 Sep 2026 08:04:27 +0000
Subject: [PATCH 25/76] refactor(passthrough): bind trace-enriched headers to a
 Final local

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../pass_through_endpoints.py                    | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
index c8c2db0dbd6..7d2fe8c45a9 100644
--- a/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
+++ b/litellm/proxy/pass_through_endpoints/pass_through_endpoints.py
@@ -985,7 +985,7 @@ async def pass_through_request(
             headers=headers,
             forward_headers=forward_headers,
         )
-        headers = _with_trace_context(headers, parent_span=user_api_key_dict.parent_otel_span)
+        upstream_headers: Final = _with_trace_context(headers, parent_span=user_api_key_dict.parent_otel_span)
 
         requested_query_params: dict | None = query_params or dict(request.query_params)
 
@@ -1019,7 +1019,7 @@ async def pass_through_request(
         verbose_proxy_logger.debug(
             "Pass through endpoint sending request to \nURL %s\nheaders: %s\nbody: %s\n",
             url,
-            headers,
+            upstream_headers,
             _parsed_body,
         )
 
@@ -1257,7 +1257,7 @@ async def pass_through_request(
             additional_args={
                 "complete_input_dict": _parsed_body,
                 "api_base": str(logging_url),
-                "headers": headers,
+                "headers": upstream_headers,
             },
         )
         stream = HttpPassThroughEndpointHelpers._update_stream_param_based_on_request_body(
@@ -1274,7 +1274,7 @@ async def pass_through_request(
                     request=request,
                     async_client=async_client,
                     url=url,
-                    headers=headers,
+                    headers=upstream_headers,
                     requested_query_params=requested_query_params,
                     stream=True,
                 )
@@ -1286,7 +1286,7 @@ async def pass_through_request(
                         request.method,
                         url,
                         params=requested_query_params,
-                        headers=headers,
+                        headers=upstream_headers,
                         content=state_raw_body,
                     )
                     if state_raw_body is not None
@@ -1294,7 +1294,7 @@ async def pass_through_request(
                         request.method,
                         url,
                         params=requested_query_params,
-                        headers=headers,
+                        headers=upstream_headers,
                         json=_parsed_body,
                     )
                 )
@@ -1371,7 +1371,7 @@ async def pass_through_request(
             raw_body_request: Final = async_client.build_request(
                 request.method,
                 url,
-                headers=headers,
+                headers=upstream_headers,
                 params=requested_query_params,
                 content=state_raw_body,
             )
@@ -1381,7 +1381,7 @@ async def pass_through_request(
                 request=request,
                 async_client=async_client,
                 url=url,
-                headers=headers,
+                headers=upstream_headers,
                 requested_query_params=requested_query_params,
                 _parsed_body=_parsed_body,
                 forward_multipart=is_multipart,

From cd594f104af2ab72242f6512e3b6aa240df658a4 Mon Sep 17 00:00:00 2001
From: shivam <shivam@berri.ai>
Date: Wed, 16 Sep 2026 08:34:53 +0000
Subject: [PATCH 26/76] fix(otel): drop stale trace headers before injecting
 passthrough trace context

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/integrations/otel/plumbing/context.py |  5 ++++-
 .../otel/test_otel_v2_components.py           | 20 +++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/litellm/integrations/otel/plumbing/context.py b/litellm/integrations/otel/plumbing/context.py
index 57e220815b5..1282e654365 100644
--- a/litellm/integrations/otel/plumbing/context.py
+++ b/litellm/integrations/otel/plumbing/context.py
@@ -26,6 +26,7 @@ if TYPE_CHECKING:
     from litellm.integrations.otel.model.destination import OtelDestination
 
 _PROPAGATOR: Final = TraceContextTextMapPropagator()
+_W3C_TRACE_HEADERS: Final = frozenset(("traceparent", "tracestate"))
 
 # The request's root span — the FastAPI-owned SERVER span — captured ONCE when the
 # proxy first resolves it, so request-level spans (the LLM call, guardrails) can
@@ -334,7 +335,9 @@ def inject_trace_context(headers: Mapping[str, str], parent_span: object = None)
     context: Final = _outgoing_trace_context(parent_span)
     if context is None:
         return dict(headers)  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
-    carrier: Final = dict(headers)  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
+    carrier: Final = {  # mutable-ok: OpenTelemetry propagator requires a mutable carrier
+        key: value for key, value in headers.items() if key.lower() not in _W3C_TRACE_HEADERS
+    }
     _PROPAGATOR.inject(carrier, context=context)
     return carrier
 
diff --git a/tests/test_litellm/integrations/otel/test_otel_v2_components.py b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
index 43546241d06..72f6213e880 100644
--- a/tests/test_litellm/integrations/otel/test_otel_v2_components.py
+++ b/tests/test_litellm/integrations/otel/test_otel_v2_components.py
@@ -507,6 +507,26 @@ def test_inject_trace_context_uses_ambient_span_without_request_root():
     assert propagated.get_span_context().span_id == ambient.get_span_context().span_id
 
 
+def test_inject_trace_context_replaces_stale_trace_headers():
+    def run():
+        tracer = _test_tracer()
+        with tracer.start_as_current_span("ambient") as ambient:
+            headers = {
+                "Traceparent": "00-" + "a" * 32 + "-" + "b" * 16 + "-01",
+                "Tracestate": "vendor=old",
+                "x-keep": "1",
+            }
+            result = ctx_mod.inject_trace_context(headers)
+            propagated = get_current_span(TraceContextTextMapPropagator().extract(result))
+            return result, ambient, propagated
+
+    result, ambient, propagated = ContextVarContext().run(run)
+    assert sum(key.lower() == "traceparent" for key in result) == 1
+    assert not any(key.lower() == "tracestate" for key in result)
+    assert result["x-keep"] == "1"
+    assert propagated.get_span_context().trace_id == ambient.get_span_context().trace_id
+
+
 def test_inject_trace_context_prefers_explicit_parent_span_over_root_and_ambient():
     def run():
         tracer = _test_tracer()

From 2d40254b57a62be9bce95586cb902b90c8505c4c Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 02:15:46 -0700
Subject: [PATCH 27/76] feat(e2e): key the provider cache per test and mount
 Bedrock behind it

The exact-request cache reused 5% of routed traffic (build 218: 19 hits,
350 misses) because every test salts its prompt with a fresh unique_marker(),
so the same test could never match itself across builds. It also routed only
openai and anthropic, while the week's flakiness was Bedrock.

Key is now HMAC(test id + method + URL + headers + body, with every
unique_marker() token replaced by a placeholder, + FIFO slot index). The slot
index is what keeps two marker-only-different calls in one test on two
recordings and therefore two provider response ids, so spend rows still
reconcile one per invocation. A call outside any test is not cacheable.

Bedrock gets a region-qualified mount and SigV4 re-signing, since the edge
rewrites the Host the proxy signed. Signature headers are excluded from the
key for signing mounts only, because x-amz-date would otherwise make every
Bedrock request a permanent miss; every other mount still keys on its
credentials whole. Only Anthropic-on-Bedrock chat deployments route:
embeddings, image generation, rerank and realtime keep their direct path, and
so do deployments carrying their own aws_role_name or static keys, whose whole
point is to prove the product's assume-role chain rather than the runner's.
The two eventstream actions bypass the cache and go live, still signed.

Counters are now attributed per mount as well as in total, so a build can
report a per-provider hit rate instead of one number.
---
 .../test_provider_cache.py                    | 509 +++++++++++++++---
 tests/e2e/fixture_canonical.py                |   5 +-
 tests/e2e/models.py                           |   1 +
 tests/e2e/provider_cache.py                   | 171 ++++--
 tests/e2e/provider_cache_routing.py           |  47 +-
 tests/e2e/provider_edge.py                    |  62 ++-
 tests/e2e/provider_edge_bedrock.py            |  72 +++
 tests/e2e/test_provider_edge.py               |  19 +-
 8 files changed, 768 insertions(+), 118 deletions(-)
 create mode 100644 tests/e2e/provider_edge_bedrock.py

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 828227ed239..5d35981344d 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -7,7 +7,7 @@ import subprocess
 import threading
 import time
 import uuid
-from collections.abc import Generator
+from collections.abc import Generator, Mapping
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
 from dataclasses import dataclass, replace
@@ -18,21 +18,58 @@ from urllib.parse import urlsplit
 
 import pytest
 from e2e_http import NetworkError, PreparedForward, RawResponse, StreamChunk, StreamHead, forward, prepare_forward
-from models import LiteLLMParamsBody
-from provider_cache import CacheEdge, CacheHit, CaptureLease, exact_key, successful_response
+from models import LiteLLMParamsBody, ModelMode
+from botocore.credentials import Credentials
+from provider_cache import (
+    SIGNATURE_HEADERS,
+    CacheEdge,
+    CacheHit,
+    CaptureLease,
+    ResponseStore,
+    cacheable_endpoint,
+    request_identity,
+    slotted_key,
+    successful_response,
+)
 from provider_cache_redis import PUBLISH, RedisCommands, RedisResponseStore, configured_cache, redis_store
 from provider_cache_routing import LIVE_PROVIDER_REQUIRED, route_cache_model
-from provider_edge import configured_cache_backend, start_provider_edge
+from fixture_mode import SESSION_TEST_KEY
+from provider_edge import EDGE_MOUNTS, configured_cache_backend, resolve_mount, start_provider_edge
+from provider_edge_bedrock import bedrock_signer
 from redis.exceptions import ConnectionError as RedisConnectionError
 
 SECRET: Final = b"synthetic-cache-hmac-key-for-tests"
 BODY: Final = b'{"model":"test","messages":[{"role":"user","content":"hello"}]}'
 SUCCESS: Final = b'{"id":"provider-fixed-id","choices":[{"message":{"content":"hello"},"finish_reason":"stop"}],"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}'
 HEADERS: Final = {"content-type": "application/json", "authorization": "Bearer synthetic-account-one"}
+TEST_KEY: Final = "tests/e2e/synthetic_suite.py::TestCase::test_case"
+OTHER_TEST_KEY: Final = "tests/e2e/synthetic_suite.py::TestCase::test_other_case"
+
+
+def marked(marker: str) -> bytes:
+    """One request body shaped like the suite's own: a fixed prompt salted with a
+    12-lowercase-hex ``unique_marker()`` token, fresh on every run."""
+    return b'{"model":"test","messages":[{"role":"user","content":"hello %s"}]}' % marker.encode()
+
+
+MARKED: Final = marked("0a1b2c3d4e5f")
+BEDROCK_MOUNT: Final = "bedrock/us-east-1"
+BEDROCK_MODEL: Final = "us.anthropic.claude-haiku-4-5-20251001-v1%3A0"
+BEDROCK_BODY: Final = b'{"messages":[{"role":"user","content":[{"text":"hello 0a1b2c3d4e5f"}]}]}'
+CONVERSE_SUCCESS: Final = (
+    b'{"output":{"message":{"role":"assistant","content":[{"text":"hi"}]}},'
+    b'"stopReason":"end_turn","usage":{"inputTokens":1,"outputTokens":1,"totalTokens":2}}'
+)
+INVOKE_SUCCESS: Final = (
+    b'{"id":"msg_synthetic","type":"message","role":"assistant",'
+    b'"content":[{"type":"text","text":"hi"}],"stop_reason":"end_turn"}'
+)
+STATIC_CREDENTIALS: Final = Credentials("AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
 
 
 class Provider(ThreadingHTTPServer):
     hits: tuple[tuple[str, bytes], ...] = ()
+    authorizations: tuple[str, ...] = ()
     response: bytes = SUCCESS
     status: int = 200
     delay: float = 0
@@ -49,6 +86,7 @@ class Handler(BaseHTTPRequestHandler):
         assert isinstance(server, Provider)
         body: Final = self.rfile.read(int(self.headers.get("content-length", "0")))
         server.hits += ((self.path, body),)
+        server.authorizations += (self.headers.get("authorization", ""),)
         time.sleep(server.delay)
         self.send_response(server.status)
         if server.stream:
@@ -122,6 +160,29 @@ def store(redis_url: str) -> RedisResponseStore:
     return redis_store(redis_url, "test-" + uuid.uuid4().hex)
 
 
+def cache_edge(store: ResponseStore, test_key: str = TEST_KEY) -> CacheEdge:
+    """A cache edge standing in for one pytest process. A fresh instance over the
+    same store is the next build running the same test: the recordings survive,
+    the per-test FIFO slot counters start over."""
+    return CacheEdge(store, SECRET, test_key=lambda: test_key)
+
+
+def slot_key(
+    url: str, slot: int = 0, body: bytes | None = BODY,
+    headers: dict[str, str] = HEADERS, test_key: str = TEST_KEY,
+) -> str:
+    prepared: Final = prepare_forward("POST", url, headers, body)
+    assert isinstance(prepared, PreparedForward)
+    return slotted_key(SECRET, request_identity(SECRET, test_key, "POST", url, prepared.headers, body), slot)
+
+
+def bedrock_cache_edge(store: ResponseStore, test_key: str = TEST_KEY) -> CacheEdge:
+    return CacheEdge(
+        store, SECRET, test_key=lambda: test_key,
+        signers={BEDROCK_MOUNT: bedrock_signer("us-east-1", lambda: STATIC_CREDENTIALS)},
+    )
+
+
 @contextmanager
 def edge(cache: CacheEdge, provider: Provider) -> Generator[str, None, None]:
     upstream: Final = f"http://127.0.0.1:{provider.server_port}"
@@ -132,34 +193,54 @@ def edge(cache: CacheEdge, provider: Provider) -> Generator[str, None, None]:
         running.shutdown()
 
 
+@contextmanager
+def bedrock_edge(cache: CacheEdge, provider: Provider, action: str = "converse") -> Generator[str, None, None]:
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}"
+    running: Final = start_provider_edge(cache, mounts={BEDROCK_MOUNT: upstream})
+    try:
+        yield f"{running.edge.api_base(BEDROCK_MOUNT)}/model/{BEDROCK_MODEL}/{action}"
+    finally:
+        running.shutdown()
+
+
 def call(url: str, body: bytes = BODY, headers: dict[str, str] = HEADERS) -> RawResponse:
     result: Final = forward("POST", url, headers=headers, body=body, timeout=5)
     assert isinstance(result, RawResponse), result
     return result
 
 
-def test_success_is_reusable_across_fresh_edges(store: RedisResponseStore, provider: Provider) -> None:
-    with edge(CacheEdge(store, SECRET), provider) as url:
+def test_repeated_call_takes_its_own_slot_and_both_replay_next_run(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    with edge(cache_edge(store), provider) as url:
         assert call(url).body == SUCCESS
         assert call(url).body == SUCCESS
-    with edge(CacheEdge(store, SECRET), provider) as other:
+    assert len(provider.hits) == 2
+    with edge(cache_edge(store), provider) as other:
         assert call(other).body == SUCCESS
-    assert len(provider.hits) == 1
+        assert call(other).body == SUCCESS
+    assert len(provider.hits) == 2
 
 
 @pytest.mark.parametrize("body", [BODY + b" ", BODY.replace(b"hello", b"Hello"), BODY.replace(b"test", b"test2")])
 def test_any_body_change_calls_live(store: RedisResponseStore, provider: Provider, body: bytes) -> None:
-    with edge(CacheEdge(store, SECRET), provider) as url:
+    with edge(cache_edge(store), provider) as url:
         call(url)
+    assert len(provider.hits) == 1
+    with edge(cache_edge(store), provider) as url:
         call(url, body)
+    assert len(provider.hits) == 2
+    with edge(cache_edge(store), provider) as url:
         call(url, body)
     assert len(provider.hits) == 2
 
 
 @pytest.mark.parametrize("name,value", [("authorization", "Bearer another-account"), ("x-request-id", "one"), ("anthropic-version", "new")])
 def test_changed_header_cannot_reuse(store: RedisResponseStore, provider: Provider, name: str, value: str) -> None:
-    with edge(CacheEdge(store, SECRET), provider) as url:
+    with edge(cache_edge(store), provider) as url:
         call(url)
+    assert len(provider.hits) == 1
+    with edge(cache_edge(store), provider) as url:
         call(url, headers=HEADERS | {name: value})
         call(url + "?x=1")
     assert len(provider.hits) == 3
@@ -169,36 +250,59 @@ def test_changed_header_cannot_reuse(store: RedisResponseStore, provider: Provid
 def test_failed_provider_responses_never_enter_cache(store: RedisResponseStore, provider: Provider, status: int, response: bytes) -> None:
     provider.status = status
     provider.response = response
-    with edge(CacheEdge(store, SECRET), provider) as url:
+    with edge(cache_edge(store), provider) as url:
         assert call(url).status_code == status
+    assert len(provider.hits) == 1
+    with edge(cache_edge(store), provider) as url:
         assert call(url).body == response
     assert len(provider.hits) == 2
 
 
 def test_cookie_setting_success_is_reused_without_the_cookie(store: RedisResponseStore, provider: Provider) -> None:
     provider.cookie = "__cf_bm=synthetic-bot-management; Path=/; HttpOnly; Secure"
-    with edge(CacheEdge(store, SECRET), provider) as url:
-        replies: Final = tuple(call(url) for _ in range(2))
+    with edge(cache_edge(store), provider) as url:
+        live: Final = call(url)
+    with edge(cache_edge(store), provider) as url:
+        replayed: Final = call(url)
     assert len(provider.hits) == 1
-    assert all(reply.body == SUCCESS and "set-cookie" not in reply.headers for reply in replies)
+    assert all(reply.body == SUCCESS and "set-cookie" not in reply.headers for reply in (live, replayed))
 
 
 def test_expiry_does_not_slide(store: RedisResponseStore, provider: Provider) -> None:
     short: Final = replace(store, lifetime_ms=250)
-    with edge(CacheEdge(short, SECRET), provider) as url:
-        call(url)
-        call(url)
-        time.sleep(0.3)
-        call(url)
-        call(url)
+    url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
+
+    def drain() -> None:
+        head = cache_edge(short).forward("openai", "POST", url, dict(HEADERS), BODY, 5)
+        assert isinstance(head, StreamHead)
+        assert b"".join(step.data for step in head.steps if isinstance(step, StreamChunk)) == SUCCESS
+
+    drain()
+    assert len(provider.hits) == 1
+    drain()
+    assert len(provider.hits) == 1
+    time.sleep(0.3)
+    drain()
     assert len(provider.hits) == 2
 
 
-def test_concurrent_requests_publish_atomically(store: RedisResponseStore, provider: Provider) -> None:
+def test_concurrent_builds_publish_one_recording_atomically(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    """Five processes running the same test at the same time all reach slot 0 of
+    one key, which is the only way the capture lease is contended now that a
+    repeat inside a single test takes its own slot."""
     provider.delay = 0.15
-    with edge(CacheEdge(store, SECRET), provider) as url:
-        with ThreadPoolExecutor(max_workers=5) as executor:
-            replies: Final = tuple(executor.map(lambda _: call(url).body, range(5)))
+    url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
+    edges: Final = tuple(cache_edge(store) for _ in range(5))
+
+    def drain(cache: CacheEdge) -> bytes:
+        head = cache.forward("openai", "POST", url, dict(HEADERS), BODY, 5)
+        assert isinstance(head, StreamHead)
+        return b"".join(step.data for step in head.steps if isinstance(step, StreamChunk))
+
+    with ThreadPoolExecutor(max_workers=5) as executor:
+        replies: Final = tuple(executor.map(drain, edges))
     assert replies == (SUCCESS,) * 5
     assert len(provider.hits) == 1
 
@@ -231,9 +335,9 @@ def test_stream_completion_controls_publication(store: RedisResponseStore, provi
     provider.stream = True
     provider.truncated = truncated
     provider.response = b'data: {"choices":[{"index":0,"delta":{"content":"hello"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n'
-    with edge(CacheEdge(store, SECRET), provider) as url:
-        for _ in range(2):
-            result: Final = forward("POST", url, headers=HEADERS, body=BODY, timeout=5)
+    for _ in range(2):
+        with edge(cache_edge(store), provider) as url:
+            result = forward("POST", url, headers=HEADERS, body=BODY, timeout=5)
             if truncated:
                 assert isinstance(result, NetworkError)
             else:
@@ -246,9 +350,9 @@ def test_store_outage_preserves_provider_success(provider: Provider) -> None:
         probe.bind(("127.0.0.1", 0))
         port: Final = probe.getsockname()[1]
         unavailable: Final = redis_store(f"redis://127.0.0.1:{port}/0", "unavailable")
-        with edge(CacheEdge(unavailable, SECRET), provider) as url:
-            assert call(url).body == SUCCESS
-            assert call(url).body == SUCCESS
+        for _ in range(2):
+            with edge(cache_edge(unavailable), provider) as url:
+                assert call(url).body == SUCCESS
     assert len(provider.hits) == 2
 
 
@@ -267,7 +371,8 @@ def test_old_lease_cannot_overwrite_new_owner(store: RedisResponseStore) -> None
 
 def test_identity_preserves_values_and_never_contains_credentials() -> None:
     variants: Final = (b'{}', b'{"a":null}', b'{"a":false}', b'{"a":0}', b'{"a":0.0}', b'{"a":"0"}', b' { }', None, b'')
-    keys: Final = tuple(exact_key(SECRET, "POST", "https://example.invalid/v1/chat/completions", HEADERS, body) for body in variants)
+    url: Final = "https://example.invalid/v1/chat/completions"
+    keys: Final = tuple(request_identity(SECRET, TEST_KEY, "POST", url, HEADERS, body) for body in variants)
     assert len(set(keys)) == len(variants)
     assert all(len(key) == 64 and "synthetic-account" not in key for key in keys)
 
@@ -275,21 +380,22 @@ def test_identity_preserves_values_and_never_contains_credentials() -> None:
 @pytest.mark.parametrize("payload", [b"corrupt response", '{"response":"{}","signature":"é"}'.encode()])
 def test_corrupt_entry_is_replaced_by_same_successful_request(store: RedisResponseStore, provider: Provider, payload: bytes) -> None:
     upstream: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
-    prepared: Final = prepare_forward("POST", upstream, HEADERS, BODY)
-    assert isinstance(prepared, PreparedForward)
-    key: Final = exact_key(SECRET, "POST", upstream, prepared.headers, BODY)
+    key: Final = slot_key(upstream)
     lease: Final = store.lookup(key)
     assert isinstance(lease, CaptureLease)
     assert store.publish(key, lease, payload)
-    cache: Final = CacheEdge(store, SECRET)
-    for _ in range(2):
-        head = cache.forward("POST", upstream, HEADERS, BODY, 5)
+    caches: Final = tuple(cache_edge(store) for _ in range(2))
+    for cache in caches:
+        head = cache.forward("openai", "POST", upstream, dict(HEADERS), BODY, 5)
         assert isinstance(head, StreamHead)
         assert b"".join(step.data for step in head.steps if isinstance(step, StreamChunk)) == SUCCESS
     assert len(provider.hits) == 1
-    assert dict(cache.counters.counts) == {
-        "corrupt": 1, "misses": 1, "upstream_attempts": 1, "writes": 1, "hits": 1,
+    assert dict(caches[0].counters.counts) == {
+        "corrupt": 1, "mount:openai:corrupt": 1, "misses": 1, "mount:openai:misses": 1,
+        "upstream_attempts": 1, "mount:openai:upstream_attempts": 1,
+        "writes": 1, "mount:openai:writes": 1,
     }
+    assert dict(caches[1].counters.counts) == {"hits": 1, "mount:openai:hits": 1}
 
 
 @pytest.mark.parametrize("payload", [
@@ -301,22 +407,242 @@ def test_corrupt_entry_is_replaced_by_same_successful_request(store: RedisRespon
 def test_malformed_success_stream_is_never_cached(store: RedisResponseStore, provider: Provider, payload: bytes) -> None:
     provider.stream = True
     provider.response = payload
-    with edge(CacheEdge(store, SECRET), provider) as url:
-        assert call(url).body == payload
-        assert call(url).body == payload
+    for _ in range(2):
+        with edge(cache_edge(store), provider) as url:
+            assert call(url).body == payload
     assert len(provider.hits) == 2
 
 
+def test_requests_differing_only_by_marker_share_one_recording_per_slot(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    """The whole point of the canonical key. Every e2e test salts its prompt with
+    a fresh ``unique_marker()``, so before this the same test could never reuse
+    anything across builds. The second run mints markers it has never sent, which
+    is what a later build actually does, and must still serve both from the two
+    slots the first run recorded."""
+    with edge(cache_edge(store), provider) as url:
+        assert call(url, MARKED).body == SUCCESS
+        assert call(url, marked("f5e4d3c2b1a0")).body == SUCCESS
+    assert len(provider.hits) == 2
+    with edge(cache_edge(store), provider) as url:
+        assert call(url, marked("7c6b5a493827")).body == SUCCESS
+        assert call(url, marked("1122334455ff")).body == SUCCESS
+    assert len(provider.hits) == 2
+
+
+@pytest.mark.parametrize("body", [
+    b'{"model":"test","messages":[{"role":"user","content":"hello 0a1b2c3d4e5"}]}',
+    b'{"model":"test","messages":[{"role":"user","content":"hello 0a1b2c3d4e5f0"}]}',
+    b'{"model":"test","messages":[{"role":"user","content":"hello 0A1B2C3D4E5F"}]}',
+    b'{"model":"0a1b2c3d4e5f","messages":[{"role":"user","content":"hello"}]}',
+])
+def test_a_token_that_is_not_a_marker_keeps_its_own_key(
+    store: RedisResponseStore, provider: Provider, body: bytes,
+) -> None:
+    """Too short, too long, upper case, or in another field: none of these is the
+    12-lowercase-hex token ``unique_marker`` mints, so none may fold onto it."""
+    with edge(cache_edge(store), provider) as url:
+        call(url, MARKED)
+    assert len(provider.hits) == 1
+    with edge(cache_edge(store), provider) as url:
+        call(url, body)
+    assert len(provider.hits) == 2
+
+
+def test_another_test_never_reuses_this_tests_recording(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    with edge(cache_edge(store), provider) as url:
+        call(url)
+    assert len(provider.hits) == 1
+    with edge(cache_edge(store, OTHER_TEST_KEY), provider) as url:
+        call(url)
+    assert len(provider.hits) == 2
+    with edge(cache_edge(store, OTHER_TEST_KEY), provider) as url:
+        call(url)
+    assert len(provider.hits) == 2
+
+
+def test_calls_outside_any_test_are_never_cached(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
+    cache: Final = CacheEdge(store, SECRET, test_key=lambda: SESSION_TEST_KEY)
+    for _ in range(2):
+        head = cache.forward("openai", "POST", url, dict(HEADERS), BODY, 5)
+        assert isinstance(head, StreamHead)
+        assert b"".join(step.data for step in head.steps if isinstance(step, StreamChunk)) == SUCCESS
+    assert len(provider.hits) == 2
+    assert dict(cache.counters.counts) == {
+        "bypass": 2, "mount:openai:bypass": 2,
+        "upstream_attempts": 2, "mount:openai:upstream_attempts": 2,
+    }
+
+
+def test_counters_attribute_every_outcome_to_its_mount(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    """The build report needs per-provider hit counts, and the flat totals cannot
+    supply them. Anthropic is served a chat-shaped body here, which its validator
+    rejects, so one mount writes and the other does not."""
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}"
+    cache: Final = cache_edge(store)
+    running: Final = start_provider_edge(cache, mounts={"openai": upstream, "anthropic": upstream})
+    try:
+        call(running.edge.api_base("openai") + "/v1/chat/completions")
+        call(running.edge.api_base("anthropic") + "/v1/messages")
+    finally:
+        running.shutdown()
+    counts: Final = dict(cache.counters.counts)
+    assert counts["misses"] == 2
+    assert counts["mount:openai:misses"] == 1 and counts["mount:anthropic:misses"] == 1
+    assert counts["mount:openai:writes"] == 1 and "mount:anthropic:writes" not in counts
+    assert counts["mount:anthropic:rejected"] == 1 and "mount:openai:rejected" not in counts
+
+
+class TestBedrockSigning:
+    """Bedrock is the reason the edge could not mount it before: SigV4 covers the
+    Host header, so forwarding through a rewritten api_base invalidates the
+    proxy's signature. The edge mints its own over the upstream URL instead."""
+
+    def test_the_proxys_signature_is_replaced_not_forwarded(self) -> None:
+        signer: Final = bedrock_signer("us-east-1", lambda: STATIC_CREDENTIALS)
+        signed: Final = signer(
+            "POST",
+            f"https://bedrock-runtime.us-east-1.amazonaws.com/model/{BEDROCK_MODEL}/converse",
+            {"content-type": "application/json", "Authorization": "AWS4-HMAC-SHA256 Credential=PROXY/...",
+             "X-Amz-Date": "19700101T000000Z", "X-Amz-Security-Token": "proxy-session-token"},
+            BEDROCK_BODY,
+        )
+        assert "PROXY" not in str(signed) and "proxy-session-token" not in str(signed)
+        assert signed["Authorization"].startswith("AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/")
+        assert "/us-east-1/bedrock/aws4_request" in signed["Authorization"]
+        assert signed["X-Amz-Date"] != "19700101T000000Z"
+        assert signed["content-type"] == "application/json"
+
+    def test_the_signed_url_reaches_the_wire_byte_for_byte(self) -> None:
+        """SigV4 hashes the canonical URI, so if the HTTP layer re-encoded the
+        colon in an inference-profile id after signing, every call would fail
+        with a signature mismatch rather than anything that names the cause."""
+        url: Final = f"https://bedrock-runtime.us-east-1.amazonaws.com/model/{BEDROCK_MODEL}/converse"
+        signer: Final = bedrock_signer("us-east-1", lambda: STATIC_CREDENTIALS)
+        prepared: Final = prepare_forward("POST", url, signer("POST", url, dict(HEADERS), BEDROCK_BODY), BEDROCK_BODY)
+        assert isinstance(prepared, PreparedForward)
+        assert urlsplit(prepared.url).path == urlsplit(url).path
+
+    def test_signature_headers_are_excluded_from_the_key(
+        self, store: RedisResponseStore, provider: Provider,
+    ) -> None:
+        """A real signature is fresh on every call, so keying on it would make
+        every Bedrock request a permanent miss. The stub signer here varies its
+        stamp per call on purpose: the real one only varies once a second, which
+        would let this pass by luck when it should fail."""
+        provider.response = CONVERSE_SUCCESS
+        stamps: Final = iter(("20260101T000000Z", "20260102T111111Z"))
+
+        def varying(method: str, url: str, headers: Mapping[str, str], body: bytes | None) -> dict[str, str]:
+            return dict(headers) | {"authorization": f"AWS4-HMAC-SHA256 {url}", "x-amz-date": next(stamps)}
+
+        def signing_edge() -> CacheEdge:
+            return CacheEdge(store, SECRET, test_key=lambda: TEST_KEY, signers={BEDROCK_MOUNT: varying})
+
+        for _ in range(2):
+            with bedrock_edge(signing_edge(), provider) as url:
+                assert call(url, BEDROCK_BODY).body == CONVERSE_SUCCESS
+        assert len(provider.hits) == 1
+        assert provider.authorizations[0] == (
+            f"AWS4-HMAC-SHA256 http://127.0.0.1:{provider.server_port}/model/{BEDROCK_MODEL}/converse"
+        ), "the signature must cover the upstream URL the edge calls, not the edge URL the proxy called"
+
+    def test_a_mount_without_a_signer_still_keys_on_its_credentials(
+        self, store: RedisResponseStore, provider: Provider,
+    ) -> None:
+        """The exclusion is per mount. Dropping authorization globally would let
+        one OpenAI account read another's recording."""
+        cache: Final = bedrock_cache_edge(store)
+        assert "authorization" in SIGNATURE_HEADERS
+        assert "authorization" in cache.keyed("openai", HEADERS)
+        assert "authorization" not in cache.keyed(BEDROCK_MOUNT, HEADERS)
+        with edge(cache, provider) as url:
+            call(url)
+        with edge(bedrock_cache_edge(store), provider) as url:
+            call(url, headers=HEADERS | {"authorization": "Bearer synthetic-account-two"})
+        assert len(provider.hits) == 2
+
+    @pytest.mark.parametrize("action,response", [("converse", CONVERSE_SUCCESS), ("invoke", INVOKE_SUCCESS)])
+    def test_complete_responses_replay_on_the_next_run(
+        self, store: RedisResponseStore, provider: Provider, action: str, response: bytes,
+    ) -> None:
+        provider.response = response
+        for _ in range(2):
+            with bedrock_edge(bedrock_cache_edge(store), provider, action) as url:
+                assert call(url, BEDROCK_BODY).body == response
+        assert len(provider.hits) == 1
+
+    @pytest.mark.parametrize("action,response", [
+        ("converse", b'{"output":{"message":{}}}'),
+        ("converse", b'{"stopReason":"end_turn"}'),
+        ("converse", b'{"message":"The provided model identifier is invalid."}'),
+        ("converse", CONVERSE_SUCCESS[:-20]),
+        ("invoke", b'{"id":"msg_x","type":"message","content":[{"type":"text","text":"hi"}]}'),
+        ("invoke", b'{"id":"msg_x","type":"message","stop_reason":"end_turn"}'),
+        ("invoke", b'{"message":"Too many requests, please wait before trying again."}'),
+    ])
+    def test_incomplete_or_error_bodies_never_enter_the_cache(
+        self, store: RedisResponseStore, provider: Provider, action: str, response: bytes,
+    ) -> None:
+        provider.response = response
+        for _ in range(2):
+            with bedrock_edge(bedrock_cache_edge(store), provider, action) as url:
+                assert call(url, BEDROCK_BODY).body == response
+        assert len(provider.hits) == 2
+
+    @pytest.mark.parametrize("action", ["converse-stream", "invoke-with-response-stream"])
+    def test_streaming_endpoints_go_live_every_time(
+        self, store: RedisResponseStore, provider: Provider, action: str,
+    ) -> None:
+        """An eventstream's completeness cannot be proven without parsing its
+        frames, so these bypass rather than risk recording a truncated answer.
+        They are still signed: a bypass is a forward, not a passthrough."""
+        provider.response = CONVERSE_SUCCESS
+        cache: Final = bedrock_cache_edge(store)
+        for _ in range(2):
+            with bedrock_edge(cache, provider, action) as url:
+                assert call(url, BEDROCK_BODY).body == CONVERSE_SUCCESS
+        assert len(provider.hits) == 2
+        assert dict(cache.counters.counts)[f"mount:{BEDROCK_MOUNT}:bypass"] == 2
+        assert all(
+            sent.startswith("AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/")
+            for sent in provider.authorizations
+        ), provider.authorizations
+
+    @pytest.mark.parametrize("action,cacheable", [
+        ("converse", True), ("invoke", True),
+        ("converse-stream", False), ("invoke-with-response-stream", False),
+    ])
+    def test_only_the_unary_bedrock_actions_are_cacheable(self, action: str, cacheable: bool) -> None:
+        url: Final = f"https://bedrock-runtime.us-east-1.amazonaws.com/model/{BEDROCK_MODEL}/{action}"
+        assert cacheable_endpoint(BEDROCK_MOUNT, "POST", url, BEDROCK_BODY) is cacheable
+
+    def test_a_region_mount_resolves_whole(self) -> None:
+        resolved: Final = resolve_mount(f"/{BEDROCK_MOUNT}/model/{BEDROCK_MODEL}/converse", EDGE_MOUNTS)
+        assert resolved is not None
+        assert resolved.mount == BEDROCK_MOUNT
+        assert resolved.upstream_base == "https://bedrock-runtime.us-east-1.amazonaws.com"
+        assert resolved.upstream_path == f"model/{BEDROCK_MODEL}/converse"
+
+
 def test_anthropic_stream_requires_start_finish_and_stop() -> None:
     start: Final = b'data: {"type":"message_start","message":{}}\n\n'
     finish: Final = b'data: {"type":"message_delta","delta":{"stop_reason":"end_turn"}}\n\n'
     stop: Final = b'data: {"type":"message_stop"}\n\n'
     url: Final = "https://example.invalid/v1/messages"
     headers: Final = {"content-type": "text/event-stream"}
-    assert successful_response(url, 200, headers, start + finish + stop)
-    assert not successful_response(url, 200, headers, start + stop)
-    assert not successful_response(url, 200, headers, finish + stop)
-    assert not successful_response(url, 200, headers, start + finish)
+    assert successful_response("anthropic", url, 200, headers, start + finish + stop)
+    assert not successful_response("anthropic", url, 200, headers, start + stop)
+    assert not successful_response("anthropic", url, 200, headers, finish + stop)
+    assert not successful_response("anthropic", url, 200, headers, start + finish)
 
 
 @pytest.mark.parametrize("provider,suffix", [("openai", "/v1"), ("anthropic", "")])
@@ -342,6 +668,53 @@ def test_registration_preserves_unsupported_or_explicit_routes(params: LiteLLMPa
     assert route_cache_model(params, unexpected_edge, enabled=True) is params
 
 
+@pytest.mark.parametrize("model", [
+    "bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0",
+    "bedrock/converse/us.anthropic.claude-sonnet-5",
+    "bedrock/invoke/us.anthropic.claude-haiku-4-5-20251001-v1:0",
+])
+def test_anthropic_on_bedrock_registers_the_edge_as_its_runtime_endpoint(model: str) -> None:
+    params: Final = LiteLLMParamsBody(model=model)
+    routed: Final = route_cache_model(params, lambda mount: f"http://edge.invalid/{mount}", enabled=True)
+    assert routed.aws_bedrock_runtime_endpoint == "http://edge.invalid/bedrock/us-east-1"
+    assert routed.api_base is None
+    assert routed.model_dump(exclude={"aws_bedrock_runtime_endpoint"}) == params.model_dump(
+        exclude={"aws_bedrock_runtime_endpoint"}
+    )
+
+
+@pytest.mark.parametrize("params", [
+    LiteLLMParamsBody(model="bedrock/amazon.titan-embed-text-v2:0"),
+    LiteLLMParamsBody(model="bedrock/amazon.nova-canvas-v1:0"),
+    LiteLLMParamsBody(model="bedrock/amazon.nova-sonic-v1:0"),
+    LiteLLMParamsBody(model="bedrock/arn:aws:bedrock:us-east-1::foundation-model/cohere.rerank-v3-5:0"),
+    LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", aws_role_name="arn:aws:iam::1:role/x"),
+    LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", aws_access_key_id="AKIA"),
+    LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", api_base="https://custom.invalid"),
+    LiteLLMParamsBody(
+        model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0",
+        aws_bedrock_runtime_endpoint="https://custom.invalid",
+    ),
+    LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", aws_region_name="eu-west-1"),
+])
+def test_bedrock_deployments_the_edge_must_not_touch_keep_their_direct_route(params: LiteLLMParamsBody) -> None:
+    """Non-Anthropic models the runner role cannot invoke, deployments carrying
+    their own AWS identity (routing those would replace the assume-role chain the
+    batch suite exists to prove), explicit endpoints, and unmounted regions."""
+    routed: Final = route_cache_model(
+        params, lambda mount: None if mount not in EDGE_MOUNTS else f"http://edge.invalid/{mount}", enabled=True,
+    )
+    assert routed is params or routed.aws_bedrock_runtime_endpoint == params.aws_bedrock_runtime_endpoint
+
+
+@pytest.mark.parametrize("mode", ["batch", "realtime", "image_generation"])
+def test_a_bedrock_deployment_with_a_mode_keeps_its_direct_route(mode: ModelMode) -> None:
+    params: Final = LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0")
+    assert route_cache_model(
+        params, lambda mount: f"http://edge.invalid/{mount}", enabled=True, mode=mode,
+    ) is params
+
+
 def test_rollback_and_live_only_policy_keep_direct_provider_route() -> None:
     params: Final = LiteLLMParamsBody(model="openai/test")
     assert route_cache_model(params, lambda _: "http://edge.invalid", enabled=False) is params
@@ -366,14 +739,16 @@ class PublishOutage:
 
 def test_write_outage_preserves_success_without_hidden_retry(store: RedisResponseStore, provider: Provider) -> None:
     unavailable: Final = replace(store, client=PublishOutage(store.client))
-    cache: Final = CacheEdge(unavailable, SECRET)
+    cache: Final = cache_edge(unavailable)
     with edge(cache, provider) as url:
         assert call(url).body == SUCCESS
         assert call(url).body == SUCCESS
     assert len(provider.hits) == 2
     assert dict(cache.counters.counts)["write_failures"] == 2
-    with edge(CacheEdge(store, SECRET), provider) as url:
+    with edge(cache_edge(store), provider) as url:
         assert call(url).body == SUCCESS
+    assert len(provider.hits) == 3
+    with edge(cache_edge(store), provider) as url:
         assert call(url).body == SUCCESS
     assert len(provider.hits) == 3
 
@@ -382,45 +757,41 @@ def test_connection_failure_releases_capture_lease(store: RedisResponseStore) ->
     with socket.socket() as unavailable:
         unavailable.bind(("127.0.0.1", 0))
         url: Final = f"http://127.0.0.1:{unavailable.getsockname()[1]}/v1/chat/completions"
-        cache: Final = CacheEdge(store, SECRET)
-        assert isinstance(cache.forward("POST", url, HEADERS, BODY, 0.2), NetworkError)
-        prepared: Final = prepare_forward("POST", url, HEADERS, BODY)
-        assert isinstance(prepared, PreparedForward)
-        key: Final = exact_key(SECRET, "POST", url, prepared.headers, BODY)
-        slot: Final = store.lookup(key)
-        assert isinstance(slot, CaptureLease)
-        assert store.release(key, slot)
+        cache: Final = cache_edge(store)
+        assert isinstance(cache.forward("openai", "POST", url, dict(HEADERS), BODY, 0.2), NetworkError)
+        key: Final = slot_key(url)
+        lease: Final = store.lookup(key)
+        assert isinstance(lease, CaptureLease)
+        assert store.release(key, lease)
         assert dict(cache.counters.counts)["rejected"] == 1
 
 
 def test_close_before_first_chunk_releases_lease(store: RedisResponseStore, provider: Provider) -> None:
     url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
-    cache: Final = CacheEdge(store, SECRET)
-    head: Final = cache.forward("POST", url, HEADERS, BODY, 5)
+    cache: Final = cache_edge(store)
+    head: Final = cache.forward("openai", "POST", url, dict(HEADERS), BODY, 5)
     assert isinstance(head, StreamHead)
     head.steps.close()
-    prepared: Final = prepare_forward("POST", url, HEADERS, BODY)
-    assert isinstance(prepared, PreparedForward)
-    key: Final = exact_key(SECRET, "POST", url, prepared.headers, BODY)
-    slot: Final = store.lookup(key)
-    assert isinstance(slot, CaptureLease)
-    assert store.release(key, slot)
+    key: Final = slot_key(url)
+    lease: Final = store.lookup(key)
+    assert isinstance(lease, CaptureLease)
+    assert store.release(key, lease)
 
 
 def test_effective_account_change_cannot_reuse_cache(
     store: RedisResponseStore, provider: Provider, monkeypatch: pytest.MonkeyPatch, tmp_path,
 ) -> None:
     url: Final = f"http://127.0.0.1:{provider.server_port}/v1/chat/completions"
-    cache: Final = CacheEdge(store, SECRET)
-    for account in ("account-a", "account-b", "account-b"):
+    caches: Final = tuple(cache_edge(store) for _ in range(3))
+    for account, cache in zip(("account-a", "account-b", "account-b"), caches, strict=True):
         netrc = tmp_path / account
         netrc.write_text(f"machine 127.0.0.1 login {account} password synthetic\n")
         monkeypatch.setenv("NETRC", str(netrc))
-        head = cache.forward("POST", url, HEADERS, BODY, 5)
+        head = cache.forward("openai", "POST", url, dict(HEADERS), BODY, 5)
         assert isinstance(head, StreamHead)
         assert b"".join(step.data for step in head.steps if isinstance(step, StreamChunk)) == SUCCESS
     assert len(provider.hits) == 2
-    assert dict(cache.counters.counts)["hits"] == 1
+    assert dict(caches[2].counters.counts)["hits"] == 1
 
 
 def test_enabled_environment_reuses_store_across_fresh_backends(
@@ -449,7 +820,7 @@ def test_enabled_environment_reuses_store_across_fresh_backends(
 def test_duplicate_headers_bypass_cache_and_count_live_calls(
     store: RedisResponseStore, provider: Provider, known_mount: bool,
 ) -> None:
-    cache: Final = CacheEdge(store, SECRET)
+    cache: Final = cache_edge(store)
     with edge(cache, provider) as url:
         parsed: Final = urlsplit(url)
         for _ in range(2):
diff --git a/tests/e2e/fixture_canonical.py b/tests/e2e/fixture_canonical.py
index e76d63ca33b..019c011aa67 100644
--- a/tests/e2e/fixture_canonical.py
+++ b/tests/e2e/fixture_canonical.py
@@ -51,6 +51,9 @@ SECRET_FIELD_SUFFIXES: Final[tuple[str, ...]] = (
 )
 SECRET_PLACEHOLDER: Final = "<secret>"
 
+MARKER_PATTERN: Final = re.compile(r"(?<![0-9a-fA-F])[0-9a-f]{12}(?![0-9a-fA-F])")
+MARKER_PLACEHOLDER: Final = "<marker>"
+
 PLACEHOLDER_RULES: Final[tuple[tuple[re.Pattern[str], str], ...]] = (
     (re.compile(r"(?<![0-9a-fA-F])[0-9a-f]{64}(?![0-9a-fA-F])"), "<sha256>"),
     (
@@ -67,7 +70,7 @@ PLACEHOLDER_RULES: Final[tuple[tuple[re.Pattern[str], str], ...]] = (
         re.compile(r"\b(?:chatcmpl|msgbatch|msg|resp|batch|call|req|ftjob|gen|file)[-_][A-Za-z0-9]{8,}\b"),
         "<id>",
     ),
-    (re.compile(r"(?<![0-9a-fA-F])[0-9a-f]{12}(?![0-9a-fA-F])"), "<marker>"),
+    (MARKER_PATTERN, MARKER_PLACEHOLDER),
 )
 
 
diff --git a/tests/e2e/models.py b/tests/e2e/models.py
index 7101438c5f8..7550bfdc150 100644
--- a/tests/e2e/models.py
+++ b/tests/e2e/models.py
@@ -951,6 +951,7 @@ class LiteLLMParamsBody(BaseModel):
     aws_access_key_id: str | None = None
     aws_secret_access_key: str | None = None
     aws_region_name: str | None = None
+    aws_bedrock_runtime_endpoint: str | None = None
     vertex_project: str | None = None
     vertex_location: str | None = None
     vertex_credentials: str | None = None
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 0c6eac75a43..1dc2f99abe5 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -23,12 +23,18 @@ from e2e_http import (
     prepare_forward,
     primed_steps,
 )
+from fixture_canonical import MARKER_PATTERN, MARKER_PLACEHOLDER
+from fixture_mode import SESSION_TEST_KEY, current_test_key
 from pydantic import BaseModel, ConfigDict, JsonValue, TypeAdapter, ValidationError
 
 LIFETIME_SECONDS: Final = 86_400
 MAX_REQUEST_BYTES: Final = 256 * 1024
 MAX_RESPONSE_BYTES: Final = 8 * 1024 * 1024
 UNRECORDED_RESPONSE_HEADERS: Final = frozenset({"set-cookie"})
+SIGNATURE_HEADERS: Final = frozenset(
+    {"authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"}
+)
+BEDROCK_MOUNT_PREFIX: Final = "bedrock"
 JSON_VALUE: Final[TypeAdapter[JsonValue]] = TypeAdapter(JsonValue)
 
 
@@ -56,6 +62,7 @@ class CacheUnavailable:
 
 
 type CacheLookup = CacheHit | CaptureLease | CacheBusy | CacheUnavailable
+type RequestSigner = Callable[[str, str, Mapping[str, str], bytes | None], dict[str, str]]
 
 
 class ResponseStore(Protocol):
@@ -83,28 +90,51 @@ class SignedResponse(BaseModel):
     signature: str
 
 
-def exact_key(secret: bytes, method: str, url: str, headers: Mapping[str, str], body: bytes | None) -> str:
+def canonical_text(value: str) -> str:
+    return MARKER_PATTERN.sub(MARKER_PLACEHOLDER, value)
+
+
+def canonical_body(body: bytes) -> bytes:
+    try:
+        return canonical_text(body.decode("utf-8")).encode("utf-8")
+    except UnicodeDecodeError:
+        return body
+
+
+def request_identity(
+    secret: bytes, test_key: str, method: str, url: str, headers: Mapping[str, str], body: bytes | None,
+) -> str:
     fields: Final = (
-        b"provider-cache-exact-v1", method.encode(), url.encode(),
+        b"provider-cache-canonical-v2", test_key.encode(), method.encode(), canonical_text(url).encode(),
         *(part.encode() for pair in sorted(headers.items()) for part in pair),
-        b"no-body" if body is None else b"body", b"" if body is None else body,
+        b"no-body" if body is None else b"body", b"" if body is None else canonical_body(body),
     )
     encoded: Final = b"".join(len(part).to_bytes(8, "big") + part for part in fields)
     return hmac.new(secret, encoded, hashlib.sha256).hexdigest()
 
 
-def cacheable_endpoint(method: str, url: str, body: bytes | None) -> bool:
-    return (
-        method == "POST"
-        and urlsplit(url).path in {"/v1/chat/completions", "/v1/messages"}
-        and body is not None
-        and len(body) <= MAX_REQUEST_BYTES
-    )
+def slotted_key(secret: bytes, identity: str, slot: int) -> str:
+    return hmac.new(secret, f"{identity}:{slot}".encode(), hashlib.sha256).hexdigest()
 
 
-def successful_response(url: str, status: int, headers: Mapping[str, str], body: bytes) -> bool:
+def is_bedrock(mount: str) -> bool:
+    return mount.partition("/")[0] == BEDROCK_MOUNT_PREFIX
+
+
+def cacheable_endpoint(mount: str, method: str, url: str, body: bytes | None) -> bool:
+    if method != "POST" or body is None or len(body) > MAX_REQUEST_BYTES:
+        return False
+    path: Final = urlsplit(url).path
+    if is_bedrock(mount):
+        return path.startswith("/model/") and path.endswith(("/converse", "/invoke"))
+    return path in {"/v1/chat/completions", "/v1/messages"}
+
+
+def successful_response(mount: str, url: str, status: int, headers: Mapping[str, str], body: bytes) -> bool:
     if not 200 <= status < 300 or len(body) > MAX_RESPONSE_BYTES:
         return False
+    if is_bedrock(mount):
+        return complete_bedrock_response(url, body)
     streaming: Final = "text/event-stream" in headers.get("content-type", "").lower()
     if streaming:
         try:
@@ -147,6 +177,26 @@ def successful_response(url: str, status: int, headers: Mapping[str, str], body:
     )
 
 
+def complete_bedrock_response(url: str, body: bytes) -> bool:
+    """Converse answers with ``output`` plus a ``stopReason``; InvokeModel on an
+    Anthropic model answers the Anthropic message shape. Either way a truncated
+    or error body is missing the terminator field, which is what makes it safe to
+    record. The streaming variants never reach here: they are not cacheable."""
+    try:
+        value: Final = JSON_VALUE.validate_json(body)
+    except ValidationError:
+        return False
+    if not isinstance(value, dict) or "message" in value:
+        return False
+    if urlsplit(url).path.endswith("/converse"):
+        return isinstance(value.get("output"), dict) and isinstance(value.get("stopReason"), str)
+    return (
+        value.get("type") == "message"
+        and isinstance(value.get("content"), list)
+        and isinstance(value.get("stop_reason"), str)
+    )
+
+
 def complete_chat_stream(values: tuple[JsonValue, ...]) -> bool:
     if any(not isinstance(value, dict) or not isinstance(value.get("choices"), list) for value in values):
         return False
@@ -172,7 +222,7 @@ def encode_response(secret: bytes, response: CachedResponse) -> bytes:
     return SignedResponse(response=raw, signature=hmac.new(secret, raw.encode(), hashlib.sha256).hexdigest()).model_dump_json().encode()
 
 
-def decode_response(secret: bytes, key: str, payload: bytes, url: str) -> CachedResponse | None:
+def decode_response(secret: bytes, key: str, payload: bytes, mount: str, url: str) -> CachedResponse | None:
     if len(payload) > 2 * MAX_RESPONSE_BYTES:
         return None
     try:
@@ -183,7 +233,9 @@ def decode_response(secret: bytes, key: str, payload: bytes, url: str) -> Cached
         chunks: Final = tuple(base64.b64decode(chunk, validate=True) for chunk in response.chunks)
     except (ValidationError, ValueError):
         return None
-    if response.request_key != key or not successful_response(url, response.status_code, response.headers, b"".join(chunks)):
+    if response.request_key != key or not successful_response(
+        mount, url, response.status_code, response.headers, b"".join(chunks)
+    ):
         return None
     return response
 
@@ -199,6 +251,24 @@ class CacheCounters:
             self.counts = tuple((current | {name: current.get(name, 0) + 1}).items())
 
 
+@dataclass(slots=True)
+class SlotCounter:
+    """FIFO position of a request among the canonically identical ones its test
+    has already sent. Two calls in one test that differ only by ``unique_marker``
+    canonicalize the same, so without this they would share one recording and the
+    second would replay the first's provider response id."""
+
+    counts: tuple[tuple[str, int], ...] = ()
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def take(self, identity: str) -> int:
+        with self.lock:
+            current: Final = dict(self.counts)
+            taken: Final = current.get(identity, 0)
+            self.counts = tuple((current | {identity: taken + 1}).items())
+            return taken
+
+
 @dataclass(slots=True)
 class ResponseCapture:
     buffer: io.BytesIO = field(default_factory=io.BytesIO)
@@ -231,9 +301,12 @@ class CacheEdge:
     store: ResponseStore
     secret: bytes = field(repr=False)
     counters: CacheCounters = field(default_factory=CacheCounters)
+    slots: SlotCounter = field(default_factory=SlotCounter)
+    signers: Mapping[str, RequestSigner] = field(default_factory=dict)
     wait_seconds: float = 2.0
     clock: Callable[[], float] = time.monotonic
     sleep: Callable[[float], None] = time.sleep
+    test_key: Callable[[], str] = current_test_key
 
     def lookup(self, key: str) -> CacheLookup:
         deadline: Final = self.clock() + self.wait_seconds
@@ -241,39 +314,71 @@ class CacheEdge:
             self.sleep(min(0.05, max(0, deadline - self.clock())))
         return result
 
-    def forward(self, method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float) -> StreamHead | NetworkError:
-        if not cacheable_endpoint(method, url, body):
-            self.counters.increment("bypass")
-            self.counters.increment("upstream_attempts")
-            return forward_stream(method, url, headers=headers, body=body, timeout=timeout)
-        prepared: Final = prepare_forward(method, url, headers, body)
+    def count(self, mount: str, name: str) -> None:
+        self.counters.increment(name)
+        self.counters.increment(f"mount:{mount}:{name}")
+
+    def outbound(self, mount: str, method: str, url: str, headers: dict[str, str], body: bytes | None) -> dict[str, str]:
+        """The headers actually sent upstream. A signing mount gets a signature
+        minted over the upstream URL, because the edge rewrote the Host the proxy
+        signed and Bedrock verifies it."""
+        signer: Final = self.signers.get(mount)
+        return headers if signer is None else signer(method, url, headers, body)
+
+    def keyed(self, mount: str, headers: Mapping[str, str]) -> Mapping[str, str]:
+        """A signing mount's signature headers are the edge's own and carry a
+        timestamp, so keying on them would make every request a permanent miss.
+        Every other mount keys on its headers whole, credentials included, so a
+        different account can never read another's recording."""
+        if mount not in self.signers:
+            return headers
+        return {name: value for name, value in headers.items() if name.lower() not in SIGNATURE_HEADERS}
+
+    def forward(
+        self, mount: str, method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float,
+    ) -> StreamHead | NetworkError:
+        test_key: Final = self.test_key()
+        if test_key == SESSION_TEST_KEY or not cacheable_endpoint(mount, method, url, body):
+            self.count(mount, "bypass")
+            self.count(mount, "upstream_attempts")
+            return forward_stream(
+                method, url, headers=self.outbound(mount, method, url, headers, body), body=body, timeout=timeout,
+            )
+        prepared: Final = prepare_forward(method, url, self.outbound(mount, method, url, headers, body), body)
         if isinstance(prepared, NetworkError):
-            self.counters.increment("rejected")
+            self.count(mount, "rejected")
             return prepared
-        key: Final = exact_key(self.secret, method, url, prepared.headers, body)
+        identity: Final = request_identity(
+            self.secret, test_key, method, url, self.keyed(mount, prepared.headers), body,
+        )
+        key: Final = slotted_key(self.secret, identity, self.slots.take(identity))
         found: Final = self.lookup(key)
         if isinstance(found, CacheHit):
-            response: Final = decode_response(self.secret, key, found.payload, url)
+            response: Final = decode_response(self.secret, key, found.payload, mount, url)
             if response is not None and self.clock() < found.valid_until:
-                self.counters.increment("hits")
+                self.count(mount, "hits")
                 return StreamHead(response.status_code, response.headers, response_steps(response))
-            self.counters.increment("corrupt" if response is None else "expired")
+            self.count(mount, "corrupt" if response is None else "expired")
             self.store.discard(key, found.payload)
         capture_slot: Final = self.lookup(key) if isinstance(found, CacheHit) else found
-        self.counters.increment("misses")
+        self.count(mount, "misses")
         if isinstance(capture_slot, CacheUnavailable):
-            self.counters.increment("cache_errors")
-        self.counters.increment("upstream_attempts")
+            self.count(mount, "cache_errors")
+        self.count(mount, "upstream_attempts")
         head: Final = forward_prepared_stream(prepared, timeout)
         if not isinstance(capture_slot, CaptureLease):
             return head
         if isinstance(head, NetworkError):
             self.store.release(key, capture_slot)
-            self.counters.increment("rejected")
+            self.count(mount, "rejected")
             return head
-        return StreamHead(head.status_code, head.headers, primed_steps(self.capture(key, capture_slot, url, head)))
+        return StreamHead(
+            head.status_code, head.headers, primed_steps(self.capture(mount, key, capture_slot, url, head)),
+        )
 
-    def capture(self, key: str, lease: CaptureLease, url: str, head: StreamHead) -> Generator[StreamStep, None, None]:
+    def capture(
+        self, mount: str, key: str, lease: CaptureLease, url: str, head: StreamHead,
+    ) -> Generator[StreamStep, None, None]:
         capture: Final = ResponseCapture()
         try:
             with closing(head.steps):
@@ -285,15 +390,15 @@ class CacheEdge:
             headers: Final = {
                 name: value for name, value in head.headers.items() if name.lower() not in UNRECORDED_RESPONSE_HEADERS
             }
-            if not capture.eligible or not successful_response(url, head.status_code, headers, b"".join(chunks)):
-                self.counters.increment("rejected")
+            if not capture.eligible or not successful_response(mount, url, head.status_code, headers, b"".join(chunks)):
+                self.count(mount, "rejected")
                 return
             response: Final = CachedResponse(
                 request_key=key, status_code=head.status_code, headers=headers,
                 chunks=tuple(base64.b64encode(chunk).decode("ascii") for chunk in chunks),
             )
             published: Final = self.store.publish(key, lease, encode_response(self.secret, response))
-            self.counters.increment("writes" if published else "write_failures")
+            self.count(mount, "writes" if published else "write_failures")
         finally:
             self.store.release(key, lease)
             capture.buffer.close()
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
index 24599b5a313..e7e4899eb71 100644
--- a/tests/e2e/provider_cache_routing.py
+++ b/tests/e2e/provider_cache_routing.py
@@ -8,14 +8,57 @@ from models import LiteLLMParamsBody, ModelMode
 
 LIVE_PROVIDER_REQUIRED: Final[ContextVar[bool]] = ContextVar("live_provider_required", default=False)
 
+DEFAULT_BEDROCK_REGION: Final = "us-east-1"
+BEDROCK_ANTHROPIC_INFIX: Final = "anthropic."
+
+
+def bedrock_mount(params: LiteLLMParamsBody) -> str | None:
+    """The edge mount an Anthropic-on-Bedrock deployment belongs to, or None.
+
+    Only the Anthropic models route. The edge validates converse and invoke
+    bodies by their Anthropic and Converse terminator fields, and the runner role
+    is allowed to invoke exactly those models, so Bedrock embeddings, image
+    generation, rerank and realtime keep their existing direct path rather than
+    reaching an edge that could neither sign nor validate for them."""
+    route: Final = params.model.partition("/")[2]
+    model: Final = route.partition("/")[2] or route
+    if BEDROCK_ANTHROPIC_INFIX not in model:
+        return None
+    return f"bedrock/{params.aws_region_name or DEFAULT_BEDROCK_REGION}"
+
+
+def route_bedrock(
+    params: LiteLLMParamsBody, base_for: Callable[[str], str | None], mode: ModelMode | None,
+) -> LiteLLMParamsBody:
+    """Deployments that carry their own AWS identity stay off the edge. The edge
+    re-signs with the run pod's role, so routing an `aws_role_name` deployment
+    would quietly replace the very assume-role chain that test exists to prove."""
+    if mode is not None or params.aws_role_name is not None or params.aws_access_key_id is not None:
+        return params
+    if params.api_base is not None or params.aws_bedrock_runtime_endpoint is not None:
+        return params
+    mount: Final = bedrock_mount(params)
+    if mount is None:
+        return params
+    base: Final = base_for(mount)
+    if base is None:
+        return params
+    return params.model_copy(update={"aws_bedrock_runtime_endpoint": base})
+
 
 def route_cache_model(
     params: LiteLLMParamsBody, base_for: Callable[[str], str | None], *, enabled: bool, mode: ModelMode | None = None,
 ) -> LiteLLMParamsBody:
-    if not enabled or mode == "realtime" or LIVE_PROVIDER_REQUIRED.get() or params.api_base is not None or params.mock_response is not None:
+    if not enabled or LIVE_PROVIDER_REQUIRED.get() or params.mock_response is not None:
+        return params
+    if params.litellm_credential_name is not None:
         return params
     provider: Final = params.model.partition("/")[0]
-    if provider not in {"openai", "anthropic"} or params.litellm_credential_name is not None:
+    if provider == "bedrock":
+        return route_bedrock(params, base_for, mode)
+    if mode == "realtime" or params.api_base is not None:
+        return params
+    if provider not in {"openai", "anthropic"}:
         return params
     base: Final = base_for(provider)
     if base is None:
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index dda9e6f8e4f..8f718ad1967 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -48,7 +48,7 @@ import threading
 from collections import deque
 from collections.abc import Generator, Mapping, Sequence
 from contextlib import closing, contextmanager
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from itertools import islice
 from pathlib import Path
@@ -94,17 +94,41 @@ from fixture_mode import (
     parse_fixture_mode,
 )
 from fixture_profile import IneligibleRequest, MatchProfile, match_profile, strict_identity
-from provider_cache import CacheEdge
+from provider_cache import CacheEdge, RequestSigner, is_bedrock
 from provider_cache_routing import LIVE_PROVIDER_REQUIRED
 from pydantic import JsonValue, TypeAdapter
 
+BEDROCK_REGIONS: Final[tuple[str, ...]] = ("us-east-1",)
+
 EDGE_MOUNTS: Final[Mapping[str, str]] = MappingProxyType(
     {
         "openai": "https://api.openai.com",
         "anthropic": "https://api.anthropic.com",
+        **{
+            f"bedrock/{region}": f"https://bedrock-runtime.{region}.amazonaws.com"
+            for region in BEDROCK_REGIONS
+        },
     }
 )
 
+
+@dataclass(frozen=True, slots=True)
+class ResolvedMount:
+    mount: str
+    upstream_base: str
+    upstream_path: str
+
+
+def resolve_mount(path: str, mounts: Mapping[str, str]) -> ResolvedMount | None:
+    """Longest mount prefix wins, so a region-qualified mount such as
+    ``bedrock/us-east-1`` resolves whole instead of leaving the region as the
+    first segment of the upstream path."""
+    trimmed: Final = path.lstrip("/")
+    for mount in sorted(mounts, key=len, reverse=True):
+        if trimmed == mount or trimmed.startswith(f"{mount}/"):
+            return ResolvedMount(mount, mounts[mount], trimmed[len(mount):].lstrip("/"))
+    return None
+
 REPLAY_MISS_STATUS: Final = 599
 
 _HOP_BY_HOP_HEADERS: Final[frozenset[str]] = frozenset(
@@ -754,14 +778,14 @@ def _handle_record(
 
 def _handle_live(
     method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float,
-    cache: CacheEdge | None = None,
+    cache: CacheEdge | None = None, mount: str = "",
 ) -> EdgeOutcome:
     forwarded: Final = {
         name: value for name, value in headers.items() if name.lower() not in _REQUEST_DROPPED_HEADERS
     }
     head: Final = (
         forward_stream(method, url, headers=forwarded, body=body, timeout=timeout)
-        if cache is None else cache.forward(method, url, forwarded, body, timeout)
+        if cache is None else cache.forward(mount, method, url, forwarded, body, timeout)
     )
     match head:
         case NetworkError(message=message):
@@ -796,10 +820,13 @@ def handle_edge_request(
     prefix, then record (forward + persist) or replay (serve from the bundle).
     Socket-free so unit tests exercise every branch without a server."""
     split: Final = urlsplit(raw_path)
-    mount, _, upstream_path = split.path.lstrip("/").partition("/")
-    upstream_base: Final = mounts.get(mount)
-    if upstream_base is None:
-        return _text_reply(404, f"unknown provider mount {mount!r}; known mounts: {', '.join(sorted(mounts))}")
+    resolved: Final = resolve_mount(split.path, mounts)
+    if resolved is None:
+        unknown: Final = split.path.lstrip("/").partition("/")[0]
+        return _text_reply(404, f"unknown provider mount {unknown!r}; known mounts: {', '.join(sorted(mounts))}")
+    mount: Final = resolved.mount
+    upstream_base: Final = resolved.upstream_base
+    upstream_path: Final = resolved.upstream_path
     profile: Final = (
         backend.recorder.profile
         if isinstance(backend, RecordEdge)
@@ -830,7 +857,8 @@ def handle_edge_request(
     match backend:
         case CacheEdge():
             return _handle_live(
-                method, _upstream_url(upstream_base, upstream_path, split.query), headers, body, timeout, backend,
+                method, _upstream_url(upstream_base, upstream_path, split.query), headers, body, timeout,
+                backend, mount,
             )
         case LiveEdge():
             return _handle_live(
@@ -891,7 +919,7 @@ class _EdgeHandler(BaseHTTPRequestHandler):
         )
         if isinstance(edge_server.backend, CacheEdge) and duplicate_headers:
             edge_server.backend.counters.increment("duplicate_header_bypass")
-            if urlsplit(self.path).path.lstrip("/").partition("/")[0] in edge_server.mounts:
+            if resolve_mount(urlsplit(self.path).path, edge_server.mounts) is not None:
                 edge_server.backend.counters.increment("upstream_attempts")
         outcome: Final = handle_edge_request(
             selected_backend,
@@ -1079,6 +1107,8 @@ def provider_edge_api_base(
                 return _shared_cache_edge(bind_host, advertise_host, forward_timeout).api_base(mount)
             return None
         case "record" | "replay":
+            if is_bedrock(mount):
+                return None
             if mount not in EDGE_MOUNTS:
                 raise ValueError(f"unknown provider mount {mount!r}; known mounts: {', '.join(sorted(EDGE_MOUNTS))}")
             return _shared_edge(mode, bundle_dir, bind_host, advertise_host, forward_timeout, match_profile()).api_base(
@@ -1108,7 +1138,17 @@ def configured_cache_backend() -> CacheEdge | None:
         return None
     from provider_cache_redis import configured_cache
 
-    return configured_cache()
+    cache: Final = configured_cache()
+    return None if cache is None else replace(cache, signers=bedrock_signers())
+
+
+@functools.lru_cache(maxsize=1)
+def bedrock_signers() -> Mapping[str, RequestSigner]:
+    """One signer per mounted Bedrock region, built lazily so a run that never
+    mounts Bedrock neither imports botocore nor resolves an AWS identity."""
+    from provider_edge_bedrock import bedrock_signer
+
+    return MappingProxyType({f"bedrock/{region}": bedrock_signer(region) for region in BEDROCK_REGIONS})
 
 
 @functools.lru_cache(maxsize=8)
diff --git a/tests/e2e/provider_edge_bedrock.py b/tests/e2e/provider_edge_bedrock.py
new file mode 100644
index 00000000000..5d8148482d7
--- /dev/null
+++ b/tests/e2e/provider_edge_bedrock.py
@@ -0,0 +1,72 @@
+"""SigV4 re-signing for Bedrock traffic routed through the provider edge.
+
+Bedrock is the one provider the edge could never mount. SigV4 signs the Host
+header, so rewriting ``api_base`` to point at the edge invalidates the proxy's
+signature and Bedrock rejects the call before it reaches a model. The edge
+therefore has to drop the proxy's signature and mint its own over the upstream
+URL it is actually about to call.
+
+The identity it signs with is the run pod's own, from the EKS Pod Identity
+association on ServiceAccount ``buildkite-e2e-run``. That role carries Bedrock
+invoke and converse on an allowlist of the Anthropic models the suite registers
+and nothing else, so a re-signed call can reach exactly the models the suite
+already uses. The proxy's own Bedrock credentials are not involved in a routed
+deployment, which is why ``aws_role_name`` deployments stay off the edge: their
+whole point is to prove the product's assume-role chain.
+
+Signature headers are excluded from the cache key by the caller, and they have
+to be: ``x-amz-date`` is a timestamp, so keying on it would make every Bedrock
+request a permanent miss.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.credentials import Credentials
+from botocore.session import Session
+from provider_cache import SIGNATURE_HEADERS
+
+BEDROCK_SERVICE: Final = "bedrock"
+
+
+class MissingAwsCredentials(RuntimeError):
+    """No AWS identity is resolvable, so the edge cannot sign for Bedrock."""
+
+
+@dataclass(frozen=True, slots=True)
+class BedrockSigner:
+    region: str
+    credentials: Callable[[], Credentials]
+
+    def __call__(self, method: str, url: str, headers: Mapping[str, str], body: bytes | None) -> dict[str, str]:
+        unsigned: Final = {
+            name: value for name, value in headers.items() if name.lower() not in SIGNATURE_HEADERS
+        }
+        request: Final = AWSRequest(method=method, url=url, headers=unsigned, data=body or b"")
+        SigV4Auth(self.credentials(), BEDROCK_SERVICE, self.region).add_auth(request)
+        return dict(request.headers)
+
+
+@functools.lru_cache(maxsize=1)
+def pod_credentials() -> Credentials:
+    """The run pod's own identity, resolved once per process through botocore's
+    ordinary chain, which reaches Pod Identity at the ``container-role`` link."""
+    resolved: Final = Session().get_credentials()
+    if resolved is None:
+        raise MissingAwsCredentials(
+            "the provider edge is mounted for Bedrock but no AWS credentials resolve; "
+            "the run pod gets them from the Pod Identity association on buildkite-e2e-run"
+        )
+    return resolved
+
+
+def bedrock_signer(region: str, credentials: Callable[[], Credentials] = pod_credentials) -> BedrockSigner:
+    """Credentials are resolved on the first signed request, not here, so a run
+    that mounts Bedrock but never calls it needs no AWS identity at all."""
+    return BedrockSigner(region, credentials)
diff --git a/tests/e2e/test_provider_edge.py b/tests/e2e/test_provider_edge.py
index 5d0c79f26f6..c8d70697182 100644
--- a/tests/e2e/test_provider_edge.py
+++ b/tests/e2e/test_provider_edge.py
@@ -1279,15 +1279,30 @@ class TestApiBaseSeam:
             )
 
     def test_unknown_mount_raises_naming_the_known_mounts(self, tmp_path: Path) -> None:
-        with pytest.raises(ValueError, match="unknown provider mount 'bedrock'"):
+        with pytest.raises(ValueError, match="unknown provider mount 'cohere'"):
             provider_edge_api_base(
-                "bedrock",
+                "cohere",
                 mode_raw="record",
                 bundle_dir=tmp_path / "bundle",
                 bind_host="127.0.0.1",
                 advertise_host="127.0.0.1",
             )
 
+    @pytest.mark.parametrize("mode_raw", ["record", "replay"])
+    def test_bedrock_never_wires_a_bundle_because_the_edge_cannot_sign_into_one(
+        self, tmp_path: Path, mode_raw: str,
+    ) -> None:
+        """Record and replay serve from a bundle without re-signing, so a Bedrock
+        deployment pointed at that edge would send the proxy's signature over a
+        rewritten Host. It keeps its direct route in both modes."""
+        assert provider_edge_api_base(
+            "bedrock/us-east-1",
+            mode_raw=mode_raw,
+            bundle_dir=tmp_path / "bundle",
+            bind_host="127.0.0.1",
+            advertise_host="127.0.0.1",
+        ) is None
+
     def test_record_mode_boots_one_shared_edge_and_prepares_the_bundle(self, tmp_path: Path) -> None:
         root = tmp_path / "bundle"
         first = provider_edge_api_base(

From b68e60f7061a2102fa076ff7ca6368f819d13770 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 02:34:09 -0700
Subject: [PATCH 28/76] feat(e2e): cache the responses and embeddings endpoints
 behind the edge

Chat completions and messages were the only cacheable paths. The suite also
drives /v1/embeddings and /v1/responses through the same OpenAI mount, so both
now cache, each with its own completeness rule: a chat response's `choices`
check would reject a perfectly good embedding, and a Responses run that never
reached `response.completed` must stay out of the cache the same way a
truncated stream does.

Vertex and Gemini stay off the edge. litellm's `_check_custom_proxy` rewrites a
path-prefixed vertex api_base into `{api_base}:{endpoint}`, dropping project,
location and model, so a mount under a path prefix cannot work without a
root-mounted edge on its own port or a change in litellm. Shipping an
unvalidated URL guess would have been worse than saying so in PROVIDER_CACHE.md.

Also finishes the MountPolicy move: a mount now carries its signer and its
unkeyed headers together instead of a bare signer map.
---
 .../test_provider_cache.py                    | 102 +++++++++++++++++-
 tests/e2e/PROVIDER_CACHE.md                   |  28 ++++-
 tests/e2e/provider_cache.py                   |  63 +++++++++--
 tests/e2e/provider_edge.py                    |  15 ++-
 tests/e2e/provider_edge_bedrock.py            |   2 +-
 5 files changed, 186 insertions(+), 24 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 5d35981344d..5c491e1cdcd 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -25,6 +25,7 @@ from provider_cache import (
     CacheEdge,
     CacheHit,
     CaptureLease,
+    MountPolicy,
     ResponseStore,
     cacheable_endpoint,
     request_identity,
@@ -179,7 +180,9 @@ def slot_key(
 def bedrock_cache_edge(store: ResponseStore, test_key: str = TEST_KEY) -> CacheEdge:
     return CacheEdge(
         store, SECRET, test_key=lambda: test_key,
-        signers={BEDROCK_MOUNT: bedrock_signer("us-east-1", lambda: STATIC_CREDENTIALS)},
+        policies={BEDROCK_MOUNT: MountPolicy(
+            sign=bedrock_signer("us-east-1", lambda: STATIC_CREDENTIALS), unkeyed_headers=SIGNATURE_HEADERS,
+        )},
     )
 
 
@@ -501,6 +504,98 @@ def test_counters_attribute_every_outcome_to_its_mount(
     assert counts["mount:anthropic:rejected"] == 1 and "mount:openai:rejected" not in counts
 
 
+EMBEDDING_SUCCESS: Final = (
+    b'{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2]}],'
+    b'"model":"text-embedding-3-small","usage":{"prompt_tokens":2,"total_tokens":2}}'
+)
+RESPONSE_SUCCESS: Final = b'{"id":"resp_synthetic","object":"response","status":"completed","output":[]}'
+RESPONSE_STREAM_SUCCESS: Final = (
+    b'data: {"type":"response.created","response":{"id":"resp_synthetic"}}\n\n'
+    b'data: {"type":"response.completed","response":{"id":"resp_synthetic","status":"completed"}}\n\n'
+)
+
+
+@contextmanager
+def openai_edge(cache: CacheEdge, provider: Provider, path: str) -> Generator[str, None, None]:
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}"
+    running: Final = start_provider_edge(cache, mounts={"openai": upstream})
+    try:
+        yield running.edge.api_base("openai") + path
+    finally:
+        running.shutdown()
+
+
+class TestNonChatOpenAiEndpoints:
+    """Chat and messages were the only cacheable paths. Embeddings and responses
+    are the other two JSON endpoints the suite drives through the same mount, and
+    each needs its own completeness rule: a chat response's ``choices`` check
+    would reject a perfectly good embedding."""
+
+    @pytest.mark.parametrize("path,response", [
+        ("/v1/embeddings", EMBEDDING_SUCCESS),
+        ("/v1/responses", RESPONSE_SUCCESS),
+    ])
+    def test_complete_responses_replay_on_the_next_run(
+        self, store: RedisResponseStore, provider: Provider, path: str, response: bytes,
+    ) -> None:
+        provider.response = response
+        for _ in range(2):
+            with openai_edge(cache_edge(store), provider, path) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 1
+
+    def test_a_completed_response_stream_replays(
+        self, store: RedisResponseStore, provider: Provider,
+    ) -> None:
+        provider.stream = True
+        provider.response = RESPONSE_STREAM_SUCCESS
+        for _ in range(2):
+            with openai_edge(cache_edge(store), provider, "/v1/responses") as url:
+                assert call(url, MARKED).body == RESPONSE_STREAM_SUCCESS
+        assert len(provider.hits) == 1
+
+    @pytest.mark.parametrize("path,response", [
+        ("/v1/embeddings", b'{"object":"list","data":[],"usage":{"prompt_tokens":0}}'),
+        ("/v1/embeddings", b'{"object":"list","data":[{"object":"embedding","index":0,"embedding":[]}],"usage":{}}'),
+        ("/v1/embeddings", b'{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1]}]}'),
+        ("/v1/responses", b'{"id":"resp_x","object":"response","status":"incomplete","output":[]}'),
+        ("/v1/responses", b'{"id":"resp_x","object":"response","status":"in_progress","output":[]}'),
+        ("/v1/responses", b'{"id":"resp_x","object":"response","output":[]}'),
+    ])
+    def test_incomplete_bodies_never_enter_the_cache(
+        self, store: RedisResponseStore, provider: Provider, path: str, response: bytes,
+    ) -> None:
+        provider.response = response
+        for _ in range(2):
+            with openai_edge(cache_edge(store), provider, path) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 2
+
+    @pytest.mark.parametrize("payload", [
+        b'data: {"type":"response.created","response":{"id":"resp_x"}}\n\n',
+        b'data: {"type":"response.created","response":{"id":"resp_x"}}\n\ndata: {"type":"response.failed"}\n\n',
+        b'data: {"type":"response.completed","response":{"id":"resp_x"}}\n\ndata: {"type":"response.created"}\n\n',
+    ])
+    def test_a_response_stream_that_never_completed_is_never_cached(
+        self, store: RedisResponseStore, provider: Provider, payload: bytes,
+    ) -> None:
+        provider.stream = True
+        provider.response = payload
+        for _ in range(2):
+            with openai_edge(cache_edge(store), provider, "/v1/responses") as url:
+                assert call(url, MARKED).body == payload
+        assert len(provider.hits) == 2
+
+    @pytest.mark.parametrize("path,cacheable", [
+        ("/v1/chat/completions", True), ("/v1/messages", True),
+        ("/v1/embeddings", True), ("/v1/responses", True),
+        ("/v1/audio/speech", False), ("/v1/images/generations", False),
+        ("/v1/files", False), ("/v1/batches", False),
+    ])
+    def test_only_the_json_endpoints_are_cacheable(self, path: str, cacheable: bool) -> None:
+        assert cacheable_endpoint("openai", "POST", f"https://api.openai.com{path}", MARKED) is cacheable
+
+
 class TestBedrockSigning:
     """Bedrock is the reason the edge could not mount it before: SigV4 covers the
     Host header, so forwarding through a rewritten api_base invalidates the
@@ -545,7 +640,10 @@ class TestBedrockSigning:
             return dict(headers) | {"authorization": f"AWS4-HMAC-SHA256 {url}", "x-amz-date": next(stamps)}
 
         def signing_edge() -> CacheEdge:
-            return CacheEdge(store, SECRET, test_key=lambda: TEST_KEY, signers={BEDROCK_MOUNT: varying})
+            return CacheEdge(
+                store, SECRET, test_key=lambda: TEST_KEY,
+                policies={BEDROCK_MOUNT: MountPolicy(sign=varying, unkeyed_headers=SIGNATURE_HEADERS)},
+            )
 
         for _ in range(2):
             with bedrock_edge(signing_edge(), provider) as url:
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 8635c9ed9ae..393a96e8c16 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -1,11 +1,29 @@
 # Shared provider-response cache
 
-`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
+`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge, as do Anthropic-on-Bedrock registrations that carry no AWS identity of their own. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
 
-The edge caches complete successful POST responses for `/v1/chat/completions` and `/v1/messages`, including streams. Unsupported endpoints pass through. It matches the method, original URL, effective outbound headers (including authentication and HTTP-library defaults), body presence and exact body bytes using a full keyed digest. It sends the same prepared request used for matching. No prompts, random markers, JSON values or credentials are normalized away. Provider `Set-Cookie` headers are dropped before validation and never recorded: the edge already withholds them from the proxy, and OpenAI responses always carry Cloudflare bot-management cookies
+The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, and for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount, including streams. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
+
+## Request identity
+
+A recording belongs to one test. The key is a keyed digest over the test's node id, the method, the URL, the effective outbound headers (including authentication and HTTP-library defaults), body presence and the body bytes, with one normalization: a 12-hex-digit run, the shape `unique_marker()` mints, is replaced by a placeholder in both the URL and a UTF-8 body. Nothing else is normalized away. No prompts, JSON values or credentials are rewritten, and the rule is the one `fixture_canonical.py` already applies for record/replay, so there is a single definition of what a marker is
+
+Requests that differ only by their markers therefore share a canonical identity, which is what makes the cache reusable across builds: every e2e test salts its prompt afresh, so an exact-byte key would miss on every call. Within one test, calls that share a canonical identity are still recorded and replayed separately, by a FIFO slot index appended to the key. That matters because a replayed response carries the recorded provider response id, `LiteLLM_SpendLogs.request_id` is that id, and one shared recording answering two calls would collapse two spend rows into one
+
+Two different tests never share a recording, and a provider call made outside any test (fixtures, session setup) is never cached, because the identity has no test node id to bind to
+
+Provider `Set-Cookie` headers are dropped before validation and never recorded: the edge already withholds them from the proxy, and OpenAI responses always carry Cloudflare bot-management cookies
 
 An eligible miss calls the provider. A complete successful response is stored immediately even if a later test assertion fails. Provider errors, malformed responses, truncated streams and cancelled captures are not stored. Cache reads, writes and lease failures fall through to normal provider behavior; they introduce no provider retry. An already-started response cannot be restarted after a delivery failure
 
+## Bedrock
+
+Bedrock could not be mounted before because SigV4 signs the `Host` header, so a rewritten `api_base` failed signature verification at the provider. The edge now re-signs: it drops the proxy's signature headers, signs the upstream request with the run pod's own AWS identity from its EKS Pod Identity association, and forwards that. The signature headers are excluded from the key, since `x-amz-date` is a timestamp and keying on it would make every Bedrock call a permanent miss
+
+Only deployments that carry no AWS identity of their own route to the edge. A deployment with `aws_role_name`, `aws_access_key_id`, an `api_base` or an `aws_bedrock_runtime_endpoint` keeps its direct path, because re-signing it would quietly replace the very credential chain that test exists to prove. Only Anthropic models route, matching what the runner role is allowed to invoke and what the edge knows how to validate
+
+Vertex and Gemini are not mounted. litellm's `_check_custom_proxy` rewrites a path-prefixed Vertex `api_base` into `{api_base}:{endpoint}`, dropping project, location and model, so a mount under a path prefix cannot work without either a root-mounted edge on its own port or a change in litellm
+
 Recordings are shared across workers and builds through dedicated Redis, separate from the candidate's own cache. They expire 86,400 seconds after capture starts, based on Redis time. Reads never extend expiry. There is no scheduled recapture: the next miss calls the provider again. Bounded coordination reduces duplicate concurrent calls, but slow or failed captures may lead to extra live calls after the wait expires
 
 ## Configuration
@@ -18,16 +36,16 @@ The trusted runner receives:
 - `E2E_PROVIDER_CACHE_NAMESPACE`: shared environment namespace, independent of build and candidate revision
 - `E2E_PROVIDER_CACHE_METRICS_DIR`: optional per-process counter artifact directory
 
-Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
+Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
 
 Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
 
 ## Recorded response semantics
 
-Replay preserves the original response ID, usage and end-to-end headers. The proxy can therefore deduplicate repeated provider IDs when storing spend-log rows, just as it does when a live upstream returns the same ID twice. One spend-log row per invocation is not guaranteed for identical recorded responses. Existing spend reconciliation requests use distinct prompt markers and retain their distinct-ID and row-count assertions; accounting tests are not automatically excluded from caching
+Replay preserves the original response ID, usage and end-to-end headers. The proxy can therefore deduplicate repeated provider IDs when storing spend-log rows, just as it does when a live upstream returns the same ID twice. One spend-log row per invocation is not guaranteed for identical recorded responses. Spend reconciliation keeps its distinct-ID and row-count assertions: its prompts differ by an index as well as a marker, so they stay distinct once markers are normalized, and calls that are canonically equal within one test take separate FIFO slots and separate recordings anyway. Accounting tests are not automatically excluded from caching
 
 Provider remaining-quota headers describe the captured response. Metrics derived from them are historical on a cache hit, not a measurement of current provider capacity. Gateway-generated API-key quota headers are a separate contract. A test of fresh provider quota or timing must use the live-provider policy; replay can still exercise how the proxy processes the recorded headers
 
 ## Qualification
 
-`tests/code_coverage_tests/test_provider_cache.py` exercises local HTTP providers and disposable real Redis. CI runs these checks with the existing provider-edge and replay harness tests. These component checks do not establish Buildkite deployment, full-suite cross-build reuse or a genuine 24-hour expiry observation; those require separate runtime evidence
+`tests/code_coverage_tests/test_provider_cache.py` exercises local HTTP providers and disposable real Redis, including the marker-canonical key, the FIFO slot index, per-test isolation, SigV4 re-signing against a local upstream, and each endpoint's completeness rule. CI runs these checks with the existing provider-edge and replay harness tests. These component checks do not establish Buildkite deployment, full-suite cross-build reuse or a genuine 24-hour expiry observation; those require separate runtime evidence
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 1dc2f99abe5..a2b18a3a466 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -9,6 +9,7 @@ import time
 from collections.abc import Callable, Generator, Mapping
 from contextlib import closing
 from dataclasses import dataclass, field
+from types import MappingProxyType
 from typing import Final, Literal, Protocol
 from urllib.parse import urlsplit
 
@@ -35,6 +36,7 @@ SIGNATURE_HEADERS: Final = frozenset(
     {"authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"}
 )
 BEDROCK_MOUNT_PREFIX: Final = "bedrock"
+OPENAI_JSON_PATHS: Final = frozenset({"/v1/chat/completions", "/v1/messages", "/v1/embeddings", "/v1/responses"})
 JSON_VALUE: Final[TypeAdapter[JsonValue]] = TypeAdapter(JsonValue)
 
 
@@ -65,6 +67,23 @@ type CacheLookup = CacheHit | CaptureLease | CacheBusy | CacheUnavailable
 type RequestSigner = Callable[[str, str, Mapping[str, str], bytes | None], dict[str, str]]
 
 
+@dataclass(frozen=True, slots=True)
+class MountPolicy:
+    """What a mount needs beyond plain forwarding.
+
+    ``sign`` mints a fresh credential over the upstream URL, for providers whose
+    auth covers the Host the edge rewrote. ``unkeyed_headers`` names headers that
+    must stay out of the cache key because they change on every call and would
+    otherwise make the mount a permanent miss: a minted signature, or an OAuth
+    token the provider rotates. Naming one costs the guarantee that a recording
+    can never cross credentials, so a mount with a rotating token relies on the
+    environment holding one identity for that provider. Mounts with a static API
+    key name nothing here and keep the guarantee whole."""
+
+    sign: RequestSigner | None = None
+    unkeyed_headers: frozenset[str] = frozenset()
+
+
 class ResponseStore(Protocol):
     def lookup(self, key: str) -> CacheLookup: ...
 
@@ -127,7 +146,7 @@ def cacheable_endpoint(mount: str, method: str, url: str, body: bytes | None) ->
     path: Final = urlsplit(url).path
     if is_bedrock(mount):
         return path.startswith("/model/") and path.endswith(("/converse", "/invoke"))
-    return path in {"/v1/chat/completions", "/v1/messages"}
+    return path in OPENAI_JSON_PATHS
 
 
 def successful_response(mount: str, url: str, status: int, headers: Mapping[str, str], body: bytes) -> bool:
@@ -150,6 +169,8 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
             return False
         if not values or any(not isinstance(value, dict) or "error" in value or value.get("type") == "error" for value in values):
             return False
+        if urlsplit(url).path == "/v1/responses":
+            return complete_responses_stream(values)
         if urlsplit(url).path == "/v1/chat/completions":
             return events[-1] == "[DONE]" and "[DONE]" not in events[:-1] and complete_chat_stream(values)
         return (
@@ -168,8 +189,17 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
         return False
     if not isinstance(value, dict) or "error" in value:
         return False
-    if urlsplit(url).path == "/v1/messages":
+    path: Final = urlsplit(url).path
+    if path == "/v1/messages":
         return value.get("type") == "message" and isinstance(value.get("content"), list) and isinstance(value.get("stop_reason"), str)
+    if path == "/v1/embeddings":
+        data: Final = value.get("data")
+        return isinstance(data, list) and bool(data) and isinstance(value.get("usage"), dict) and all(
+            isinstance(item, dict) and isinstance(item.get("embedding"), list) and bool(item["embedding"])
+            for item in data
+        )
+    if path == "/v1/responses":
+        return value.get("object") == "response" and value.get("status") == "completed"
     choices: Final = value.get("choices")
     return isinstance(choices, list) and bool(choices) and all(
         isinstance(choice, dict) and isinstance(choice.get("message"), dict) and isinstance(choice.get("finish_reason"), str)
@@ -197,6 +227,14 @@ def complete_bedrock_response(url: str, body: bytes) -> bool:
     )
 
 
+def complete_responses_stream(values: tuple[JsonValue, ...]) -> bool:
+    """The Responses API streams typed events and ends with ``response.completed``.
+    A run that failed, was cancelled, or ran out of tokens ends with a different
+    terminal event, so requiring that one keeps a half-finished response out."""
+    last: Final = values[-1]
+    return isinstance(last, dict) and last.get("type") == "response.completed"
+
+
 def complete_chat_stream(values: tuple[JsonValue, ...]) -> bool:
     if any(not isinstance(value, dict) or not isinstance(value.get("choices"), list) for value in values):
         return False
@@ -296,13 +334,16 @@ def response_steps(response: CachedResponse) -> Generator[StreamStep, None, None
         yield StreamChunk(base64.b64decode(chunk, validate=True))
 
 
+NO_POLICIES: Final[Mapping[str, MountPolicy]] = MappingProxyType({})
+
+
 @dataclass(frozen=True, slots=True)
 class CacheEdge:
     store: ResponseStore
     secret: bytes = field(repr=False)
     counters: CacheCounters = field(default_factory=CacheCounters)
     slots: SlotCounter = field(default_factory=SlotCounter)
-    signers: Mapping[str, RequestSigner] = field(default_factory=dict)
+    policies: Mapping[str, MountPolicy] = NO_POLICIES
     wait_seconds: float = 2.0
     clock: Callable[[], float] = time.monotonic
     sleep: Callable[[float], None] = time.sleep
@@ -321,18 +362,18 @@ class CacheEdge:
     def outbound(self, mount: str, method: str, url: str, headers: dict[str, str], body: bytes | None) -> dict[str, str]:
         """The headers actually sent upstream. A signing mount gets a signature
         minted over the upstream URL, because the edge rewrote the Host the proxy
-        signed and Bedrock verifies it."""
-        signer: Final = self.signers.get(mount)
+        signed and the provider verifies it."""
+        signer: Final = self.policies.get(mount, MountPolicy()).sign
         return headers if signer is None else signer(method, url, headers, body)
 
     def keyed(self, mount: str, headers: Mapping[str, str]) -> Mapping[str, str]:
-        """A signing mount's signature headers are the edge's own and carry a
-        timestamp, so keying on them would make every request a permanent miss.
-        Every other mount keys on its headers whole, credentials included, so a
-        different account can never read another's recording."""
-        if mount not in self.signers:
+        """Headers the cache key is built from. A mount keeps its credentials in
+        the key unless its policy names them unkeyed, so by default one account
+        can never read another's recording."""
+        unkeyed: Final = self.policies.get(mount, MountPolicy()).unkeyed_headers
+        if not unkeyed:
             return headers
-        return {name: value for name, value in headers.items() if name.lower() not in SIGNATURE_HEADERS}
+        return {name: value for name, value in headers.items() if name.lower() not in unkeyed}
 
     def forward(
         self, mount: str, method: str, url: str, headers: dict[str, str], body: bytes | None, timeout: float,
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index 8f718ad1967..2606b26fe99 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -94,7 +94,7 @@ from fixture_mode import (
     parse_fixture_mode,
 )
 from fixture_profile import IneligibleRequest, MatchProfile, match_profile, strict_identity
-from provider_cache import CacheEdge, RequestSigner, is_bedrock
+from provider_cache import SIGNATURE_HEADERS, CacheEdge, MountPolicy, is_bedrock
 from provider_cache_routing import LIVE_PROVIDER_REQUIRED
 from pydantic import JsonValue, TypeAdapter
 
@@ -1139,16 +1139,21 @@ def configured_cache_backend() -> CacheEdge | None:
     from provider_cache_redis import configured_cache
 
     cache: Final = configured_cache()
-    return None if cache is None else replace(cache, signers=bedrock_signers())
+    return None if cache is None else replace(cache, policies=bedrock_policies())
 
 
 @functools.lru_cache(maxsize=1)
-def bedrock_signers() -> Mapping[str, RequestSigner]:
-    """One signer per mounted Bedrock region, built lazily so a run that never
+def bedrock_policies() -> Mapping[str, MountPolicy]:
+    """One policy per mounted Bedrock region, built lazily so a run that never
     mounts Bedrock neither imports botocore nor resolves an AWS identity."""
     from provider_edge_bedrock import bedrock_signer
 
-    return MappingProxyType({f"bedrock/{region}": bedrock_signer(region) for region in BEDROCK_REGIONS})
+    return MappingProxyType(
+        {
+            f"bedrock/{region}": MountPolicy(sign=bedrock_signer(region), unkeyed_headers=SIGNATURE_HEADERS)
+            for region in BEDROCK_REGIONS
+        }
+    )
 
 
 @functools.lru_cache(maxsize=8)
diff --git a/tests/e2e/provider_edge_bedrock.py b/tests/e2e/provider_edge_bedrock.py
index 5d8148482d7..73e4a16d272 100644
--- a/tests/e2e/provider_edge_bedrock.py
+++ b/tests/e2e/provider_edge_bedrock.py
@@ -58,7 +58,7 @@ def pod_credentials() -> Credentials:
     """The run pod's own identity, resolved once per process through botocore's
     ordinary chain, which reaches Pod Identity at the ``container-role`` link."""
     resolved: Final = Session().get_credentials()
-    if resolved is None:
+    if resolved is None:  # pyright: ignore[reportUnnecessaryComparison]  # stubs miss the empty-chain None
         raise MissingAwsCredentials(
             "the provider edge is mounted for Bedrock but no AWS credentials resolve; "
             "the run pod gets them from the Pod Identity association on buildkite-e2e-run"

From 6cf35ed71bf769154eb70bfff69e6c70202961e6 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 09:42:20 +0000
Subject: [PATCH 29/76] feat(proxy): expose lifetime total_spend on virtual
 keys

Adds a persistent total_spend column to LiteLLM_VerificationToken and LiteLLM_DeletedVerificationToken, incremented in the same write as spend and left alone by budget resets. Surfaces it on /key/info, /key/list and the Admin UI Virtual Keys table and key detail view

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../migration.sql                             |  5 ++
 .../litellm_proxy_extras/schema.prisma        |  2 +
 litellm/models/verification_token.py          |  1 +
 litellm/proxy/db/db_spend_update_writer.py    |  1 +
 litellm/proxy/schema.prisma                   |  2 +
 schema.prisma                                 |  2 +
 tests/test_litellm/models/test_models.py      |  8 +++
 .../common_utils/test_reset_budget_job.py     | 17 ++++++
 .../proxy/db/test_db_spend_update_writer.py   | 54 ++++++++++++++++++-
 .../test_key_management_endpoints.py          | 54 +++++++++++++++++++
 .../DeletedKeysPage/DeletedKeysPage.test.tsx  |  1 +
 .../VirtualKeysPage/VirtualKeysTable.test.tsx |  9 ++++
 .../VirtualKeysPage/keyTableColumns.tsx       | 15 ++++++
 .../components/key_team_helpers/key_list.tsx  |  1 +
 .../key_edit_view.integration.test.tsx        |  1 +
 .../templates/key_info_view.test.tsx          | 18 +++++++
 .../components/templates/key_info_view.tsx    |  8 +++
 ui/litellm-dashboard/src/lib/http/schema.d.ts | 15 ++++++
 18 files changed, 213 insertions(+), 1 deletion(-)
 create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260916000000_add_key_total_spend/migration.sql

diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260916000000_add_key_total_spend/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260916000000_add_key_total_spend/migration.sql
new file mode 100644
index 00000000000..daacd66db39
--- /dev/null
+++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260916000000_add_key_total_spend/migration.sql
@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN IF NOT EXISTS "total_spend" DOUBLE PRECISION NOT NULL DEFAULT 0.0;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_DeletedVerificationToken" ADD COLUMN IF NOT EXISTS "total_spend" DOUBLE PRECISION NOT NULL DEFAULT 0.0;
diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
index d2375903c47..139fb031671 100644
--- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
+++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma
@@ -426,6 +426,7 @@ model LiteLLM_VerificationToken {
     key_alias   String?
     soft_budget_cooldown Boolean @default(false) // key-level state on if budget alerts need to be cooled down
     spend      Float    @default(0.0)
+    total_spend Float   @default(0.0)
     expires    DateTime?
     models     String[]
     aliases    Json  @default("{}")
@@ -528,6 +529,7 @@ model LiteLLM_DeletedVerificationToken {
     key_alias               String?
     soft_budget_cooldown    Boolean  @default(false)
     spend                   Float    @default(0.0)
+    total_spend             Float    @default(0.0)
     expires                 DateTime?
     models                  String[]
     aliases                 Json     @default("{}")
diff --git a/litellm/models/verification_token.py b/litellm/models/verification_token.py
index 06ff877a41a..15ecf5fe026 100644
--- a/litellm/models/verification_token.py
+++ b/litellm/models/verification_token.py
@@ -18,6 +18,7 @@ class LiteLLM_VerificationToken(LiteLLMPydanticObjectBase):
     key_name: str | None = None
     key_alias: str | None = None
     spend: float = 0.0
+    total_spend: float = 0.0
     max_budget: float | None = None
     expires: str | datetime | None = None
     models: list = []
diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index a90d1351fd7..5b43ed53117 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -1619,6 +1619,7 @@ class DBSpendUpdateWriter:
                                     where={"token": token},
                                     data={
                                         "spend": {"increment": response_cost},
+                                        "total_spend": {"increment": response_cost},
                                         "last_active": datetime.now(timezone.utc),
                                     },
                                 )
diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma
index d2375903c47..139fb031671 100644
--- a/litellm/proxy/schema.prisma
+++ b/litellm/proxy/schema.prisma
@@ -426,6 +426,7 @@ model LiteLLM_VerificationToken {
     key_alias   String?
     soft_budget_cooldown Boolean @default(false) // key-level state on if budget alerts need to be cooled down
     spend      Float    @default(0.0)
+    total_spend Float   @default(0.0)
     expires    DateTime?
     models     String[]
     aliases    Json  @default("{}")
@@ -528,6 +529,7 @@ model LiteLLM_DeletedVerificationToken {
     key_alias               String?
     soft_budget_cooldown    Boolean  @default(false)
     spend                   Float    @default(0.0)
+    total_spend             Float    @default(0.0)
     expires                 DateTime?
     models                  String[]
     aliases                 Json     @default("{}")
diff --git a/schema.prisma b/schema.prisma
index d2375903c47..139fb031671 100644
--- a/schema.prisma
+++ b/schema.prisma
@@ -426,6 +426,7 @@ model LiteLLM_VerificationToken {
     key_alias   String?
     soft_budget_cooldown Boolean @default(false) // key-level state on if budget alerts need to be cooled down
     spend      Float    @default(0.0)
+    total_spend Float   @default(0.0)
     expires    DateTime?
     models     String[]
     aliases    Json  @default("{}")
@@ -528,6 +529,7 @@ model LiteLLM_DeletedVerificationToken {
     key_alias               String?
     soft_budget_cooldown    Boolean  @default(false)
     spend                   Float    @default(0.0)
+    total_spend             Float    @default(0.0)
     expires                 DateTime?
     models                  String[]
     aliases                 Json     @default("{}")
diff --git a/tests/test_litellm/models/test_models.py b/tests/test_litellm/models/test_models.py
index aa6449c98dd..9b803c14062 100644
--- a/tests/test_litellm/models/test_models.py
+++ b/tests/test_litellm/models/test_models.py
@@ -362,6 +362,14 @@ class TestVerificationToken:
         assert deleted.deleted_at is not None
         assert deleted.token == "t1"
 
+    def test_total_spend_is_carried_separately_from_resettable_spend(self):
+        token = LiteLLM_VerificationToken(token="t1", spend=0.0, total_spend=12.5)
+        assert token.model_dump()["total_spend"] == 12.5
+        assert token.model_dump()["spend"] == 0.0
+
+        deleted = LiteLLM_DeletedVerificationToken.model_validate({**token.model_dump(), "deleted_by": "admin"})
+        assert deleted.total_spend == 12.5
+
 
 class TestConfigTable:
     def test_config_creation(self):
diff --git a/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py b/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py
index 943a6c905c0..1ccf9be37b9 100644
--- a/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py
+++ b/tests/test_litellm/proxy/common_utils/test_reset_budget_job.py
@@ -291,6 +291,23 @@ def test_reset_budget_for_key(reset_budget_job, mock_prisma_client):
     assert set(write["data"].keys()) == {"spend", "budget_reset_at"}
 
 
+def test_reset_budget_for_key_leaves_lifetime_total_spend_alone(reset_budget_job, mock_prisma_client):
+    """A period reset zeroes spend but must neither write nor touch the lifetime total_spend."""
+    now = datetime.now(timezone.utc)
+    key = LiteLLM_VerificationToken(
+        token="tok-key-1", spend=100.0, total_spend=340.0, budget_duration="30d", budget_reset_at=now
+    )
+    mock_prisma_client.data["key"] = [key]
+
+    asyncio.run(reset_budget_job.reset_budget_for_litellm_keys())
+
+    (write,) = _batch_writes(mock_prisma_client, "key")
+    assert write["data"]["spend"] == {"decrement": 100.0}
+    assert "total_spend" not in write["data"]
+    assert key.spend == 0.0
+    assert key.total_spend == 340.0
+
+
 def test_reset_budget_for_key_honors_injected_reset_time(mock_prisma_client, mock_proxy_logging):
     """Injected BudgetResetSettings drives the written reset time end to end (DI, no globals).
 
diff --git a/tests/test_litellm/proxy/db/test_db_spend_update_writer.py b/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
index c547d06904b..7be6f809c0d 100644
--- a/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
+++ b/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
@@ -1658,6 +1658,58 @@ async def test_commit_key_spend_updates_includes_last_active():
     assert before_call <= last_active <= after_call
 
 
+@pytest.mark.asyncio
+async def test_commit_spend_updates_to_db_increments_key_total_spend_alongside_spend():
+    """
+    The key table write must increment the lifetime total_spend by the same amount as the
+    resettable spend, in the same update so the two cannot drift.
+    """
+    db_writer = DBSpendUpdateWriter()
+
+    mock_batcher = MagicMock()
+    mock_batcher.litellm_verificationtoken = MagicMock()
+    mock_batcher.litellm_verificationtoken.update_many = MagicMock()
+
+    mock_transaction = AsyncMock()
+    mock_transaction.__aenter__ = AsyncMock(return_value=mock_transaction)
+    mock_transaction.__aexit__ = AsyncMock(return_value=False)
+    mock_transaction.batch_ = MagicMock(
+        return_value=AsyncMock(
+            __aenter__=AsyncMock(return_value=mock_batcher),
+            __aexit__=AsyncMock(return_value=False),
+        )
+    )
+
+    mock_prisma_client = MagicMock()
+    mock_prisma_client.db = MagicMock()
+    mock_prisma_client.db.tx = MagicMock(return_value=mock_transaction)
+
+    db_spend_update_transactions = {
+        "user_list_transactions": {},
+        "end_user_list_transactions": {},
+        "key_list_transactions": {"hashed_token_abc": 0.05, "hashed_token_def": 1.25},
+        "team_list_transactions": {},
+        "team_member_list_transactions": {},
+        "org_list_transactions": {},
+        "tag_list_transactions": {},
+        "agent_list_transactions": {},
+    }
+
+    with patch("litellm.proxy.utils._raise_failed_update_spend_exception"):
+        await db_writer._commit_spend_updates_to_db(
+            prisma_client=mock_prisma_client,
+            n_retry_times=0,
+            proxy_logging_obj=MagicMock(),
+            db_spend_update_transactions=db_spend_update_transactions,
+        )
+
+    calls = mock_batcher.litellm_verificationtoken.update_many.call_args_list
+    assert [c.kwargs["where"] for c in calls] == [{"token": "hashed_token_abc"}, {"token": "hashed_token_def"}]
+    for call, expected_cost in zip(calls, (0.05, 1.25)):
+        assert call.kwargs["data"]["spend"] == {"increment": expected_cost}
+        assert call.kwargs["data"]["total_spend"] == call.kwargs["data"]["spend"]
+
+
 @pytest.mark.asyncio
 async def test_update_database_creates_single_task():
     """
@@ -2813,7 +2865,7 @@ async def test_commit_spend_updates_to_db_does_not_stamp_key_settings_updated_at
     mock_batcher.litellm_verificationtoken.update_many.assert_called_once()
     call_kwargs = mock_batcher.litellm_verificationtoken.update_many.call_args[1]
     assert call_kwargs["where"] == {"token": token}
-    assert set(call_kwargs["data"]) == {"spend", "last_active"}
+    assert set(call_kwargs["data"]) == {"spend", "total_spend", "last_active"}
     assert call_kwargs["data"]["spend"] == {"increment": response_cost}
 
 
diff --git a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
index 4e70063015d..60224960bb3 100644
--- a/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
+++ b/tests/test_litellm/proxy/management_endpoints/test_key_management_endpoints.py
@@ -1431,6 +1431,60 @@ async def test_key_info_returns_object_permission(monkeypatch):
     )
 
 
+def _stored_key_with_lifetime_spend(token: str, spend: float, total_spend: float) -> LiteLLM_VerificationToken:
+    return LiteLLM_VerificationToken.model_validate(
+        {"token": token, "user_id": "user123", "spend": spend, "total_spend": total_spend}
+    )
+
+
+@pytest.mark.asyncio
+async def test_key_info_returns_lifetime_total_spend_next_to_resettable_spend(monkeypatch):
+    """After a budget reset the period spend is 0 while total_spend keeps the lifetime figure."""
+    from litellm.proxy.management_endpoints.key_management_endpoints import info_key_fn
+
+    mock_prisma_client = AsyncMock()
+    monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", mock_prisma_client)
+    mock_prisma_client.db.litellm_verificationtoken.find_unique = AsyncMock(
+        return_value=_stored_key_with_lifetime_spend(token="hashed_key", spend=0.0, total_spend=3.75)
+    )
+
+    result = await info_key_fn(
+        key="sk-test-key-456",
+        user_api_key_dict=UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, api_key="sk-test-key-456"),
+    )
+
+    assert result["info"]["spend"] == 0.0
+    assert result["info"]["total_spend"] == 3.75
+
+
+@pytest.mark.asyncio
+async def test_list_keys_full_object_returns_lifetime_total_spend():
+    mock_prisma_client = AsyncMock()
+    mock_prisma_client.db.litellm_verificationtoken.find_many = AsyncMock(
+        return_value=[_stored_key_with_lifetime_spend(token="hashed_key", spend=0.0, total_spend=3.75)]
+    )
+    mock_prisma_client.db.litellm_verificationtoken.count = AsyncMock(return_value=1)
+
+    result = await _list_key_helper(
+        prisma_client=mock_prisma_client,
+        page=1,
+        size=50,
+        user_id=None,
+        team_id=None,
+        organization_id=None,
+        key_alias=None,
+        key_hash=None,
+        exclude_team_id=None,
+        return_full_object=True,
+        admin_team_ids=None,
+    )
+
+    listed_key = result["keys"][0]
+    assert isinstance(listed_key, UserAPIKeyAuth)
+    assert listed_key.spend == 0.0
+    assert listed_key.total_spend == 3.75
+
+
 @pytest.mark.asyncio
 async def test_get_new_token_with_valid_key(monkeypatch):
     """Test get_new_token function when provided with a valid key that starts with 'sk-'"""
diff --git a/ui/litellm-dashboard/src/components/DeletedKeysPage/DeletedKeysPage.test.tsx b/ui/litellm-dashboard/src/components/DeletedKeysPage/DeletedKeysPage.test.tsx
index 31cd407a5e6..cf0c13ee152 100644
--- a/ui/litellm-dashboard/src/components/DeletedKeysPage/DeletedKeysPage.test.tsx
+++ b/ui/litellm-dashboard/src/components/DeletedKeysPage/DeletedKeysPage.test.tsx
@@ -22,6 +22,7 @@ const mockDeletedKey: DeletedKeyResponse = {
   key_name: "test-key",
   key_alias: "Test Key Alias",
   spend: 5.5,
+  total_spend: 5.5,
   max_budget: 100,
   expires: "2024-12-31T23:59:59Z",
   models: ["gpt-3.5-turbo"],
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
index 617b9209a41..8f1b7acaac0 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
@@ -79,6 +79,7 @@ const mockKey: KeyResponse = {
   key_name: "test-key",
   key_alias: "Test Key Alias",
   spend: 5.5,
+  total_spend: 42.25,
   max_budget: 100,
   expires: "2999-12-31T23:59:59Z",
   models: ["gpt-3.5-turbo", "gpt-4"],
@@ -236,6 +237,14 @@ it("should display key information correctly", async () => {
   });
 });
 
+it("shows lifetime spend in its own column next to the period spend meter", async () => {
+  renderWithProviders(<VirtualKeysTable />);
+
+  expect(await screen.findByText("Lifetime Spend")).toBeInTheDocument();
+  expect(screen.getByText("$42.2500")).toBeInTheDocument();
+  expect(screen.getByText("$5.5000")).toBeInTheDocument();
+});
+
 it("should display user email correctly", async () => {
   renderWithProviders(<VirtualKeysTable />);
 
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx
index 6eea77ae827..cf5585e3486 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/keyTableColumns.tsx
@@ -13,6 +13,7 @@ import {
   IdCell,
   IdentityCell,
   ModelsCell,
+  MoneyCell,
   SpendBudgetCell,
   StatusBadge,
   UserPopoverCell,
@@ -274,6 +275,20 @@ export const getKeyTableColumns = ({
       );
     },
   },
+  {
+    id: "total_spend",
+    accessorKey: "total_spend",
+    meta: { title: "Lifetime Spend" },
+    header: () => (
+      <InfoHeader
+        label="Lifetime Spend"
+        tooltip="Cumulative spend across every budget period. Budget resets do not touch this value. Keys created before this field existed only count spend from then on."
+      />
+    ),
+    size: 130,
+    enableSorting: false,
+    cell: (info) => <MoneyCell value={info.getValue() as number | null | undefined} showZero />,
+  },
   {
     id: "budget_reset_at",
     accessorKey: "budget_reset_at",
diff --git a/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx b/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx
index eadbca87140..60439e5c52c 100644
--- a/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx
+++ b/ui/litellm-dashboard/src/components/key_team_helpers/key_list.tsx
@@ -39,6 +39,7 @@ export interface KeyResponse {
   key_name: string;
   key_alias: string;
   spend: number;
+  total_spend: number;
   max_budget: number;
   expires: string;
   models: string[];
diff --git a/ui/litellm-dashboard/src/components/templates/key_edit_view.integration.test.tsx b/ui/litellm-dashboard/src/components/templates/key_edit_view.integration.test.tsx
index 9efcff04832..6a2f778d4a9 100644
--- a/ui/litellm-dashboard/src/components/templates/key_edit_view.integration.test.tsx
+++ b/ui/litellm-dashboard/src/components/templates/key_edit_view.integration.test.tsx
@@ -174,6 +174,7 @@ describe("KeyEditView", () => {
     key_name: "sk-...TUuw",
     key_alias: "asdasdas",
     spend: 0,
+    total_spend: 0,
     max_budget: 0,
     expires: "null",
     models: [],
diff --git a/ui/litellm-dashboard/src/components/templates/key_info_view.test.tsx b/ui/litellm-dashboard/src/components/templates/key_info_view.test.tsx
index b403255b329..4bf41c1f3a8 100644
--- a/ui/litellm-dashboard/src/components/templates/key_info_view.test.tsx
+++ b/ui/litellm-dashboard/src/components/templates/key_info_view.test.tsx
@@ -119,6 +119,7 @@ describe("KeyInfoView", () => {
     key_name: "sk-...TUuw",
     key_alias: "asdasdas",
     spend: 0,
+    total_spend: 0,
     max_budget: 0,
     expires: "null",
     models: [],
@@ -272,6 +273,23 @@ describe("KeyInfoView", () => {
     });
   });
 
+  it("shows lifetime spend separately from the resettable period spend", async () => {
+    vi.mocked(useAuthorized).mockReturnValue(baseUseAuthorizedMock);
+
+    renderWithProviders(
+      <KeyInfoView
+        keyData={{ ...MOCK_KEY_DATA, spend: 0.25, total_spend: 340.5 }}
+        onClose={() => {}}
+        keyId={"test-key-id"}
+        onKeyDataUpdate={() => {}}
+        teams={[]}
+      />,
+    );
+
+    expect(await screen.findByText("$0.2500")).toBeInTheDocument();
+    expect(screen.getByTestId("key-lifetime-spend")).toHaveTextContent("Lifetime spend: $340.5000");
+  });
+
   it("should render the key's saved router fallbacks", async () => {
     vi.mocked(useAuthorized).mockReturnValue(baseUseAuthorizedMock);
 
diff --git a/ui/litellm-dashboard/src/components/templates/key_info_view.tsx b/ui/litellm-dashboard/src/components/templates/key_info_view.tsx
index 0e6dba64110..06e088f956b 100644
--- a/ui/litellm-dashboard/src/components/templates/key_info_view.tsx
+++ b/ui/litellm-dashboard/src/components/templates/key_info_view.tsx
@@ -677,6 +677,9 @@ export default function KeyInfoView({
                   {currentKeyData.budget_reset_at && (
                     <p className="text-sm">Resets {formatTimestamp(currentKeyData.budget_reset_at)}</p>
                   )}
+                  <p className="text-sm mt-2" data-testid="key-lifetime-spend">
+                    Lifetime spend: ${formatNumberWithCommas(currentKeyData.total_spend ?? 0, 4)}
+                  </p>
                 </div>
               </Card>
 
@@ -935,6 +938,11 @@ export default function KeyInfoView({
                     <p className="text-sm">${formatNumberWithCommas(currentKeyData.spend, 4)} USD</p>
                   </div>
 
+                  <div>
+                    <p className="text-sm font-medium">Lifetime Spend</p>
+                    <p className="text-sm">${formatNumberWithCommas(currentKeyData.total_spend ?? 0, 4)} USD</p>
+                  </div>
+
                   <div>
                     <p className="text-sm font-medium">Budget</p>
                     <p className="text-sm">
diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts
index 17ec8367324..57b0f29e3de 100644
--- a/ui/litellm-dashboard/src/lib/http/schema.d.ts
+++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts
@@ -29686,6 +29686,11 @@ export interface components {
             team_id?: string | null;
             /** Token */
             token?: string | null;
+            /**
+             * Total Spend
+             * @default 0
+             */
+            total_spend: number;
             /** Tpd Limit */
             tpd_limit?: number | null;
             /** Tpm Limit */
@@ -31259,6 +31264,11 @@ export interface components {
             team_id?: string | null;
             /** Token */
             token?: string | null;
+            /**
+             * Total Spend
+             * @default 0
+             */
+            total_spend: number;
             /** Tpd Limit */
             tpd_limit?: number | null;
             /** Tpm Limit */
@@ -40057,6 +40067,11 @@ export interface components {
             team_tpm_limit?: number | null;
             /** Token */
             token?: string | null;
+            /**
+             * Total Spend
+             * @default 0
+             */
+            total_spend: number;
             /** Tpd Limit */
             tpd_limit?: number | null;
             /** Tpm Limit */

From aebfcf7da3b5b13591232f4b559978d4f92aafb5 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 02:45:06 -0700
Subject: [PATCH 30/76] fix(e2e): route Bedrock deployments whose region only
 the proxy can resolve

Almost every Bedrock deployment in the suite declares
aws_region_name="os.environ/AWS_REGION". The mount resolver treated that
string as a region name, produced a mount nothing serves, and left the whole
Anthropic-on-Bedrock surface on its direct path, which is the one thing
mounting Bedrock was for.

The run pod does not share the proxy's environment, so the harness genuinely
cannot resolve that reference. A `us.` inference profile fans out across the US
regions and is reachable from any of them, so those route to the default mount
whatever the proxy resolved. A model that is not cross-region and declares its
region that way keeps its direct path rather than being sent to a region it may
not exist in.
---
 .../test_provider_cache.py                    | 27 +++++++++++++------
 tests/e2e/PROVIDER_CACHE.md                   |  2 ++
 tests/e2e/provider_cache_routing.py           | 23 +++++++++++++++-
 3 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 5c491e1cdcd..0278bf8fd48 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -766,13 +766,20 @@ def test_registration_preserves_unsupported_or_explicit_routes(params: LiteLLMPa
     assert route_cache_model(params, unexpected_edge, enabled=True) is params
 
 
-@pytest.mark.parametrize("model", [
-    "bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0",
-    "bedrock/converse/us.anthropic.claude-sonnet-5",
-    "bedrock/invoke/us.anthropic.claude-haiku-4-5-20251001-v1:0",
+@pytest.mark.parametrize("model,region", [
+    ("bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", None),
+    ("bedrock/converse/us.anthropic.claude-sonnet-5", None),
+    ("bedrock/invoke/us.anthropic.claude-haiku-4-5-20251001-v1:0", None),
+    ("bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", "us-east-1"),
+    ("bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", "os.environ/AWS_REGION"),
+    ("bedrock/invoke/us.anthropic.claude-sonnet-5", "os.environ/AWS_REGION"),
 ])
-def test_anthropic_on_bedrock_registers_the_edge_as_its_runtime_endpoint(model: str) -> None:
-    params: Final = LiteLLMParamsBody(model=model)
+def test_anthropic_on_bedrock_registers_the_edge_as_its_runtime_endpoint(model: str, region: str | None) -> None:
+    """Almost every Bedrock deployment in the suite declares its region as
+    `os.environ/AWS_REGION`, which only the proxy can resolve. Treating that
+    string as a region name would leave the whole Anthropic-on-Bedrock surface
+    off the edge, which is the point of mounting it at all."""
+    params: Final = LiteLLMParamsBody(model=model, aws_region_name=region)
     routed: Final = route_cache_model(params, lambda mount: f"http://edge.invalid/{mount}", enabled=True)
     assert routed.aws_bedrock_runtime_endpoint == "http://edge.invalid/bedrock/us-east-1"
     assert routed.api_base is None
@@ -794,15 +801,19 @@ def test_anthropic_on_bedrock_registers_the_edge_as_its_runtime_endpoint(model:
         aws_bedrock_runtime_endpoint="https://custom.invalid",
     ),
     LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", aws_region_name="eu-west-1"),
+    LiteLLMParamsBody(model="bedrock/anthropic.claude-sonnet-5", aws_region_name="os.environ/AWS_REGION"),
+    LiteLLMParamsBody(model="bedrock/invoke/eu.anthropic.claude-sonnet-5", aws_region_name="os.environ/AWS_REGION"),
 ])
 def test_bedrock_deployments_the_edge_must_not_touch_keep_their_direct_route(params: LiteLLMParamsBody) -> None:
     """Non-Anthropic models the runner role cannot invoke, deployments carrying
     their own AWS identity (routing those would replace the assume-role chain the
-    batch suite exists to prove), explicit endpoints, and unmounted regions."""
+    batch suite exists to prove), explicit endpoints, unmounted regions, and a
+    region only the proxy can resolve on a model that is not cross-region, whose
+    real region the harness cannot know."""
     routed: Final = route_cache_model(
         params, lambda mount: None if mount not in EDGE_MOUNTS else f"http://edge.invalid/{mount}", enabled=True,
     )
-    assert routed is params or routed.aws_bedrock_runtime_endpoint == params.aws_bedrock_runtime_endpoint
+    assert routed is params
 
 
 @pytest.mark.parametrize("mode", ["batch", "realtime", "image_generation"])
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 393a96e8c16..c530574cda2 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -20,6 +20,8 @@ An eligible miss calls the provider. A complete successful response is stored im
 
 Bedrock could not be mounted before because SigV4 signs the `Host` header, so a rewritten `api_base` failed signature verification at the provider. The edge now re-signs: it drops the proxy's signature headers, signs the upstream request with the run pod's own AWS identity from its EKS Pod Identity association, and forwards that. The signature headers are excluded from the key, since `x-amz-date` is a timestamp and keying on it would make every Bedrock call a permanent miss
 
+Almost every Bedrock deployment in the suite declares its region as `os.environ/AWS_REGION`, which only the proxy can resolve, and the run pod does not share that environment. A `us.` inference profile fans out across the US regions and is reachable from any of them, so those route to the default mount whatever the proxy resolved. A model that is not cross-region and declares its region that way keeps its direct path rather than being sent to a region it may not exist in.
+
 Only deployments that carry no AWS identity of their own route to the edge. A deployment with `aws_role_name`, `aws_access_key_id`, an `api_base` or an `aws_bedrock_runtime_endpoint` keeps its direct path, because re-signing it would quietly replace the very credential chain that test exists to prove. Only Anthropic models route, matching what the runner role is allowed to invoke and what the edge knows how to validate
 
 Vertex and Gemini are not mounted. litellm's `_check_custom_proxy` rewrites a path-prefixed Vertex `api_base` into `{api_base}:{endpoint}`, dropping project, location and model, so a mount under a path prefix cannot work without either a root-mounted edge on its own port or a change in litellm
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
index e7e4899eb71..d2237bb49bc 100644
--- a/tests/e2e/provider_cache_routing.py
+++ b/tests/e2e/provider_cache_routing.py
@@ -10,6 +10,26 @@ LIVE_PROVIDER_REQUIRED: Final[ContextVar[bool]] = ContextVar("live_provider_requ
 
 DEFAULT_BEDROCK_REGION: Final = "us-east-1"
 BEDROCK_ANTHROPIC_INFIX: Final = "anthropic."
+BEDROCK_CROSS_REGION_PREFIX: Final = "us."
+ENV_REFERENCE_PREFIX: Final = "os.environ/"
+
+
+def bedrock_region(declared: str | None, model: str) -> str | None:
+    """The region whose edge mount a deployment belongs to, or None when the
+    harness cannot know it.
+
+    Most Bedrock deployments declare `os.environ/AWS_REGION`, which the proxy
+    resolves from its own environment. The run pod does not share that
+    environment, so the harness genuinely does not know the region. A `us.`
+    inference profile fans out across the US regions and is reachable from any
+    of them, so the default entry point is correct for those whatever the proxy
+    resolved; anything else keeps its direct path rather than being sent to a
+    region the model may not exist in."""
+    if declared is None:
+        return DEFAULT_BEDROCK_REGION
+    if not declared.startswith(ENV_REFERENCE_PREFIX):
+        return declared
+    return DEFAULT_BEDROCK_REGION if model.startswith(BEDROCK_CROSS_REGION_PREFIX) else None
 
 
 def bedrock_mount(params: LiteLLMParamsBody) -> str | None:
@@ -24,7 +44,8 @@ def bedrock_mount(params: LiteLLMParamsBody) -> str | None:
     model: Final = route.partition("/")[2] or route
     if BEDROCK_ANTHROPIC_INFIX not in model:
         return None
-    return f"bedrock/{params.aws_region_name or DEFAULT_BEDROCK_REGION}"
+    region: Final = bedrock_region(params.aws_region_name, model)
+    return None if region is None else f"bedrock/{region}"
 
 
 def route_bedrock(

From 6b7cafe92b7d94e9f80cb16b4d3cf3fe359801c5 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 09:58:36 +0000
Subject: [PATCH 31/76] refactor(proxy): share one typed increment for key
 spend and total_spend writes

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/proxy/db/db_spend_update_writer.py          | 11 +++++++++--
 .../proxy/db/test_db_spend_update_writer.py         | 13 ++++++-------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/litellm/proxy/db/db_spend_update_writer.py b/litellm/proxy/db/db_spend_update_writer.py
index 5b43ed53117..599ae90bcae 100644
--- a/litellm/proxy/db/db_spend_update_writer.py
+++ b/litellm/proxy/db/db_spend_update_writer.py
@@ -18,6 +18,8 @@ from types import MappingProxyType
 from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, cast, overload
 from urllib.parse import quote, unquote
 
+from typing_extensions import ReadOnly, TypedDict
+
 import litellm
 from litellm._logging import verbose_proxy_logger
 from litellm.caching import RedisCache
@@ -109,6 +111,10 @@ def _batch_cost_row_to_write(payload: SpendLogsPayload, disable_spend_logs: bool
     return MappingProxyType({field: value for field, value in payload.items() if field in _BATCH_COST_CLAIM_FIELDS})
 
 
+class _SpendIncrement(TypedDict):
+    increment: ReadOnly[float]
+
+
 class _SpendBatch(Protocol):
     litellm_usertable: BatchTable
     litellm_verificationtoken: BatchTable
@@ -1615,11 +1621,12 @@ class DBSpendUpdateWriter:
                         async with transaction.batch_() as batcher:
                             # Sort by token for consistent lock ordering across pods to prevent deadlocks.
                             for token, response_cost in sorted(key_list_transactions.items()):
+                                spend_increment: _SpendIncrement = {"increment": response_cost}
                                 batcher.litellm_verificationtoken.update_many(  # 'update_many' prevents error from being raised if no row exists
                                     where={"token": token},
                                     data={
-                                        "spend": {"increment": response_cost},
-                                        "total_spend": {"increment": response_cost},
+                                        "spend": spend_increment,
+                                        "total_spend": spend_increment,
                                         "last_active": datetime.now(timezone.utc),
                                     },
                                 )
diff --git a/tests/test_litellm/proxy/db/test_db_spend_update_writer.py b/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
index 7be6f809c0d..8f72e1d6248 100644
--- a/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
+++ b/tests/test_litellm/proxy/db/test_db_spend_update_writer.py
@@ -1695,13 +1695,12 @@ async def test_commit_spend_updates_to_db_increments_key_total_spend_alongside_s
         "agent_list_transactions": {},
     }
 
-    with patch("litellm.proxy.utils._raise_failed_update_spend_exception"):
-        await db_writer._commit_spend_updates_to_db(
-            prisma_client=mock_prisma_client,
-            n_retry_times=0,
-            proxy_logging_obj=MagicMock(),
-            db_spend_update_transactions=db_spend_update_transactions,
-        )
+    await db_writer._commit_spend_updates_to_db(
+        prisma_client=mock_prisma_client,
+        n_retry_times=0,
+        proxy_logging_obj=MagicMock(),
+        db_spend_update_transactions=db_spend_update_transactions,
+    )
 
     calls = mock_batcher.litellm_verificationtoken.update_many.call_args_list
     assert [c.kwargs["where"] for c in calls] == [{"token": "hashed_token_abc"}, {"token": "hashed_token_def"}]

From 30c6241e3a5f534037dc57a6ea544d5ff9d8bdeb Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 03:01:07 -0700
Subject: [PATCH 32/76] fix(e2e): a null error field is not an error

Every OpenAI Responses body carries `error: null` at the top level, and the
completeness check tested the key's presence rather than its value, so it
rejected every single one. The cost was silent: nothing failed, the endpoint
simply never cached, which is exactly the outcome the endpoint was added for.

Found by driving the edge against the real providers rather than the synthetic
fixtures, which carried no error key at all. Reading the value instead of the
key is also more accurate for chat completions and messages, where a real error
body carries a populated error object.
---
 .../test_provider_cache.py                    | 42 +++++++++++++++++--
 tests/e2e/provider_cache.py                   |  7 +++-
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 0278bf8fd48..3dafbadf508 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -508,10 +508,13 @@ EMBEDDING_SUCCESS: Final = (
     b'{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2]}],'
     b'"model":"text-embedding-3-small","usage":{"prompt_tokens":2,"total_tokens":2}}'
 )
-RESPONSE_SUCCESS: Final = b'{"id":"resp_synthetic","object":"response","status":"completed","output":[]}'
+RESPONSE_SUCCESS: Final = (
+    b'{"id":"resp_synthetic","object":"response","status":"completed","error":null,'
+    b'"incomplete_details":null,"output":[]}'
+)
 RESPONSE_STREAM_SUCCESS: Final = (
-    b'data: {"type":"response.created","response":{"id":"resp_synthetic"}}\n\n'
-    b'data: {"type":"response.completed","response":{"id":"resp_synthetic","status":"completed"}}\n\n'
+    b'data: {"type":"response.created","response":{"id":"resp_synthetic","error":null}}\n\n'
+    b'data: {"type":"response.completed","response":{"id":"resp_synthetic","status":"completed"},"error":null}\n\n'
 )
 
 
@@ -586,6 +589,39 @@ class TestNonChatOpenAiEndpoints:
                 assert call(url, MARKED).body == payload
         assert len(provider.hits) == 2
 
+    @pytest.mark.parametrize("path,response", [
+        ("/v1/chat/completions", b'{"id":"x","error":null,"choices":[{"message":{"content":"hi"},'
+                                 b'"finish_reason":"stop"}]}'),
+        ("/v1/messages", b'{"id":"msg_x","type":"message","role":"assistant","error":null,'
+                         b'"content":[{"type":"text","text":"hi"}],"stop_reason":"end_turn"}'),
+        ("/v1/responses", RESPONSE_SUCCESS),
+    ])
+    def test_a_null_error_field_is_not_an_error(
+        self, store: RedisResponseStore, provider: Provider, path: str, response: bytes,
+    ) -> None:
+        """Every OpenAI Responses body carries `error: null`, and testing the key's
+        presence rather than its value rejected all of them. The cost was silent:
+        nothing failed, the endpoint simply never cached."""
+        assert b'"error":null' in response
+        provider.response = response
+        for _ in range(2):
+            with openai_edge(cache_edge(store), provider, path) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 1
+
+    @pytest.mark.parametrize("path,response", [
+        ("/v1/chat/completions", b'{"error":{"message":"rate limited","type":"rate_limit_error"}}'),
+        ("/v1/responses", b'{"object":"response","status":"completed","error":{"message":"bad"},"output":[]}'),
+    ])
+    def test_a_populated_error_field_still_rejects(
+        self, store: RedisResponseStore, provider: Provider, path: str, response: bytes,
+    ) -> None:
+        provider.response = response
+        for _ in range(2):
+            with openai_edge(cache_edge(store), provider, path) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 2
+
     @pytest.mark.parametrize("path,cacheable", [
         ("/v1/chat/completions", True), ("/v1/messages", True),
         ("/v1/embeddings", True), ("/v1/responses", True),
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index a2b18a3a466..0dee33f33c6 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -167,7 +167,10 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
             values: Final = tuple(JSON_VALUE.validate_json(event) for event in events if event != "[DONE]")
         except (UnicodeDecodeError, ValidationError):
             return False
-        if not values or any(not isinstance(value, dict) or "error" in value or value.get("type") == "error" for value in values):
+        if not values or any(
+            not isinstance(value, dict) or value.get("error") is not None or value.get("type") == "error"
+            for value in values
+        ):
             return False
         if urlsplit(url).path == "/v1/responses":
             return complete_responses_stream(values)
@@ -187,7 +190,7 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
         value: Final = JSON_VALUE.validate_json(body)
     except ValidationError:
         return False
-    if not isinstance(value, dict) or "error" in value:
+    if not isinstance(value, dict) or value.get("error") is not None:
         return False
     path: Final = urlsplit(url).path
     if path == "/v1/messages":

From 4a70bc3ba366b550fdf096ffa4ccadc008ad65ba Mon Sep 17 00:00:00 2001
From: runjivu <romano31415@gmail.com>
Date: Wed, 16 Sep 2026 15:19:46 +0900
Subject: [PATCH 33/76] fix: re-check budget on router fallback targets

Budget is enforced once during auth, against the requested model group.
`_is_model_cost_zero` waives every budget check for a zero-cost group, and the
router then picks a fallback target afterwards, inside `run_async_fallback`,
where nothing re-checks budget. A free model with a paid fallback therefore
bills with no budget gate at all.

Add `fallback_budget_check`, the budget sibling of the existing
`fallback_access_check`: a predicate awaited per fallback target that skips
targets the caller cannot pay for. The primary attempt is untouched, so a
zero-cost model is never blocked by budget and only the paid fallback is
refused.

Counter reads pass `max_budget` so `get_current_spend` verifies against
authoritative recorded spend, matching the auth-time key and user checks; a
counter restored from an older snapshot reads as a hit rather than a clean
miss, so without it a stale-low value would keep admitting paid fallbacks.

A zero-cost fallback target is always allowed, and a team key does not inherit
the key owner's personal budget unless `apply_user_budget_to_team_keys` is set,
matching `_PROXY_MaxBudgetLimiter`.

Scope is key and user budgets. Team, team-member, end-user, org, global and
per-model budgets are not covered yet: those auth-path functions enforce rather
than report, so reusing them would fire threshold alerts and take spend
reservations for a target that is then skipped. Two limitations of that scope
are documented in the module docstring: the check reads the spend counter
rather than reserving against it, so concurrent fallbacks can cross a cap
together; and a request reaching the router without
`metadata["user_api_key_auth"]` is not restricted. Both are shared with
`fallback_model_access.py`.

Opt-in via `general_settings.enforce_fallback_budget`.

Relates to #41344

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 litellm/constants.py                          |   1 +
 litellm/proxy/auth/fallback_budget.py         | 166 ++++++++++++++++
 litellm/proxy/proxy_server.py                 |   3 +
 litellm/router.py                             |   4 +
 .../router_utils/fallback_event_handlers.py   |  21 ++
 litellm/types/router.py                       |  13 ++
 .../proxy/auth/test_fallback_budget.py        | 184 ++++++++++++++++++
 tests/test_litellm/proxy/test_proxy_server.py |  38 ++++
 .../test_fallback_event_handlers.py           |   8 +
 9 files changed, 438 insertions(+)
 create mode 100644 litellm/proxy/auth/fallback_budget.py
 create mode 100644 tests/test_litellm/proxy/auth/test_fallback_budget.py

diff --git a/litellm/constants.py b/litellm/constants.py
index 745a4d9294e..b1fec17b6ed 100644
--- a/litellm/constants.py
+++ b/litellm/constants.py
@@ -40,6 +40,7 @@ ROUTER_SETTINGS_MANAGED_OUTSIDE_CONFIG: Final[frozenset[str]] = frozenset(
         "router_general_settings",
         "ignore_invalid_deployments",
         "fallback_access_check",
+        "fallback_budget_check",
         "auto_router_capability_limit",
     }
 )
diff --git a/litellm/proxy/auth/fallback_budget.py b/litellm/proxy/auth/fallback_budget.py
new file mode 100644
index 00000000000..00e885d8d88
--- /dev/null
+++ b/litellm/proxy/auth/fallback_budget.py
@@ -0,0 +1,166 @@
+"""
+Enforce the caller's budget against router fallback targets.
+
+Budget is checked once, during auth, against the *requested* model group. A zero-cost group takes
+`_is_model_cost_zero`'s bypass and waives every budget check; the router then picks a fallback
+target after auth, inside `run_async_fallback`, and nothing re-checks budget on the group that
+actually bills. So a free model with a paid fallback spends without a gate.
+
+This predicate is injected into the router to re-check budget for each fallback target before it is
+attempted, mirroring `fallback_model_access.py`. It deliberately leaves the primary attempt alone:
+a zero-cost model is never blocked by budget, and only the paid fallback is refused. Opt-in via
+`general_settings.enforce_fallback_budget: true`.
+
+Scope: the key's and the user's `max_budget`. Not covered yet, and each needs a read-only evaluation
+path before it can be: team, team-member, end-user, org, global and per-model budgets, whose
+auth-path functions enforce rather than report (they raise), so reusing them would fire threshold
+alerts and take spend reservations for a target that is then skipped; and the key's rolling
+`budget_limits` windows, whose accumulated spend lives only in per-window counters
+(`spend:key:{token}:window:{budget_duration}`), so enforcing them means more counter reads on the
+fallback path rather than reusing state auth already loaded.
+
+Two known limitations of that narrow scope, both shared with `fallback_model_access.py`:
+
+* This reads the spend counter, it does not reserve against it. Requests already in flight all
+  observe the same pre-billing figure, so a cap can be crossed by roughly the number of concurrent
+  fallbacks times their cost. Auth-time enforcement avoids this by pre-filling the counter through
+  `reserve_budget_for_request`, which the zero-cost bypass skips. Turning the soft cap into a hard
+  one means reserving per fallback attempt and reconciling on completion.
+* A request that reaches the router without `metadata["user_api_key_auth"]` is not restricted.
+  Only `add_litellm_data_to_request` populates that key, so endpoints that assemble metadata by
+  hand (for example `/queue/chat/completions`) fall through as unauthenticated.
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from pydantic import BaseModel, ValidationError
+
+from litellm._logging import verbose_proxy_logger
+from litellm.proxy._types import UserAPIKeyAuth
+from litellm.proxy.auth.auth_checks import (
+    _is_model_cost_zero,  # pyright: ignore[reportPrivateUsage]  # the zero-cost predicate the auth-time budget checks use; no public equivalent
+)
+from litellm.router import Router
+
+
+class _RequestMetadata(BaseModel):
+    user_api_key_auth: UserAPIKeyAuth | None = None
+
+
+class _FallbackBudgetSettings(BaseModel):
+    enforce_fallback_budget: bool = False
+
+
+def _token_in_metadata(metadata: object) -> UserAPIKeyAuth | None:
+    try:
+        return _RequestMetadata.model_validate(metadata).user_api_key_auth
+    except ValidationError:
+        return None
+
+
+def _user_api_key_auth_from_request(request_kwargs: Mapping[str, object]) -> UserAPIKeyAuth | None:
+    return next(
+        (
+            token
+            for field in ("metadata", "litellm_metadata")
+            if (token := _token_in_metadata(request_kwargs.get(field))) is not None
+        ),
+        None,
+    )
+
+
+def _enforced_by_general_settings() -> bool:
+    from litellm.proxy.proxy_server import general_settings
+
+    return _FallbackBudgetSettings.model_validate(general_settings).enforce_fallback_budget
+
+
+def _applies_user_budget_to_team_keys() -> bool:
+    from litellm.proxy.proxy_server import general_settings
+
+    return general_settings.get("apply_user_budget_to_team_keys") is True
+
+
+async def _counter_spend(counter_key: str, fallback_spend: float, max_budget: float) -> float:
+    """
+    Read a spend counter the same way the auth-time budget checks do.
+
+    `max_budget` is not advisory: it makes `get_current_spend` re-check the counter against the
+    authoritative recorded spend before admitting. A counter restored from an older Redis snapshot
+    reads as a hit rather than a clean miss, so without this the reseed path never runs and a
+    stale-low counter would keep admitting paid fallbacks past the cap.
+    """
+    from litellm.proxy.proxy_server import get_current_spend
+
+    return await get_current_spend(
+        counter_key=counter_key,
+        fallback_spend=fallback_spend,
+        max_budget=max_budget,
+    )
+
+
+async def is_token_within_budget_for_model(*, model: str, valid_token: UserAPIKeyAuth, llm_router: Router) -> bool:
+    """
+    True when the key and the user behind it can still pay for `model`.
+
+    A zero-cost fallback target is always allowed: refusing it would deny a request on spend some
+    other model accrued, which is the same reasoning behind the auth-time bypass.
+    """
+    if _is_model_cost_zero(model=model, llm_router=llm_router):
+        return True
+
+    key_budget: Final = valid_token.max_budget
+    if key_budget is not None and valid_token.token is not None:
+        key_spend: Final = await _counter_spend(
+            counter_key=f"spend:key:{valid_token.token}",
+            fallback_spend=valid_token.spend or 0.0,
+            max_budget=key_budget,
+        )
+        if key_spend >= key_budget:
+            return False
+
+    # Mirrors `_PROXY_MaxBudgetLimiter`: a team key does not carry the key owner's personal budget
+    # unless the proxy opts in, so the personal cap must not gate the fallback either.
+    user_budget: Final = valid_token.user_max_budget
+    if (
+        user_budget is not None
+        and valid_token.user_id is not None
+        and (valid_token.team_id is None or _applies_user_budget_to_team_keys())
+    ):
+        user_spend: Final = await _counter_spend(
+            counter_key=f"spend:user:{valid_token.user_id}",
+            fallback_spend=valid_token.user_spend or 0.0,
+            max_budget=user_budget,
+        )
+        if user_spend >= user_budget:
+            return False
+
+    return True
+
+
+@dataclass(frozen=True, slots=True)
+class RouterFallbackBudgetCheck:
+    """
+    `FallbackBudgetCheck` for the proxy's router: while `is_enforced()` is true, a paid fallback
+    target is attempted only when the caller is still within budget. Requests that carry no key
+    (for example internal health checks) are not restricted.
+    """
+
+    is_enforced: Callable[[], bool]
+
+    async def __call__(self, *, model: str, request_kwargs: Mapping[str, object], llm_router: Router) -> bool:
+        if not self.is_enforced():
+            return True
+        valid_token: Final = _user_api_key_auth_from_request(request_kwargs)
+        if valid_token is None:
+            return True
+        try:
+            return await is_token_within_budget_for_model(model=model, valid_token=valid_token, llm_router=llm_router)
+        except Exception as e:  # noqa: BLE001  # fail closed: a spend lookup failure must not bill the caller
+            verbose_proxy_logger.warning("Skipping fallback to model=%s: budget lookup failed: %s", model, e)
+            return False
+
+
+router_fallback_budget_check: Final = RouterFallbackBudgetCheck(is_enforced=_enforced_by_general_settings)
diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py
index d7964556531..0f6d84c33e7 100644
--- a/litellm/proxy/proxy_server.py
+++ b/litellm/proxy/proxy_server.py
@@ -322,6 +322,7 @@ from litellm.proxy.auth.auth_utils import (
     log_once_if_budget_reservation_disabled,
     warn_once_if_custom_auth_skips_common_checks,
 )
+from litellm.proxy.auth.fallback_budget import router_fallback_budget_check
 from litellm.proxy.auth.fallback_model_access import router_fallback_access_check
 from litellm.proxy.auth.handle_jwt import JWTHandler
 from litellm.proxy.auth.litellm_license import AUTO_ROUTER_LICENSE_REMEDY, LicenseCheck
@@ -6153,6 +6154,7 @@ class ProxyConfig:
             ),
             ignore_invalid_deployments=True,  # don't raise an error if a deployment is invalid
             fallback_access_check=router_fallback_access_check,
+            fallback_budget_check=router_fallback_budget_check,
             auto_router_capability_limit=_license_check.auto_router_capability_limit,
         )
 
@@ -6614,6 +6616,7 @@ class ProxyConfig:
                         search_tools=search_tools,
                         ignore_invalid_deployments=True,
                         fallback_access_check=router_fallback_access_check,
+                        fallback_budget_check=router_fallback_budget_check,
                         auto_router_capability_limit=_license_check.auto_router_capability_limit,
                     )
                     verbose_proxy_logger.debug("updated llm_router: %s", llm_router)
diff --git a/litellm/router.py b/litellm/router.py
index d531072530b..9fcda7d2e97 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -240,6 +240,7 @@ from litellm.types.router import (
     DeploymentModelListingInfo,
     DeploymentTypedDict,
     FallbackAccessCheck,
+    FallbackBudgetCheck,
     GuardrailTypedDict,
     LiteLLM_Params,
     MockRouterTestingParams,
@@ -755,6 +756,7 @@ class Router:
         background_health_check_model_groups: Sequence[str] | None = None,
         enable_weighted_failover: bool = False,
         fallback_access_check: FallbackAccessCheck | None = None,
+        fallback_budget_check: FallbackBudgetCheck | None = None,
         auto_router_capability_limit: AutoRouterCapabilityLimit | None = None,
     ) -> None:
         """
@@ -793,6 +795,7 @@ class Router:
             ignore_invalid_deployments (bool): Ignores invalid deployments, and continues with other deployments. Default is to raise an error.
             enable_weighted_failover (bool): When True and the routing strategy is "simple-shuffle", a retryable failure on one deployment causes the request to re-pick (weighted) across the other deployments in the same model group before any cross-group fallback runs. Bounded by `max_fallbacks`. Async-only: currently honored by `router.acompletion()` and other async entrypoints. The sync `router.completion()` path falls back to the regular fallback flow. Defaults to False.
             fallback_access_check (Optional[FallbackAccessCheck]): Awaited before each cross-model-group fallback attempt on the async path; a fallback target it rejects is skipped. Defaults to None (every configured fallback is attempted).
+            fallback_budget_check (Optional[FallbackBudgetCheck]): Awaited before each cross-model-group fallback attempt on the async path; a fallback target it rejects as over budget is skipped. Defaults to None (budget is not re-checked on fallback).
         Returns:
             Router: An instance of the litellm.Router class.
 
@@ -834,6 +837,7 @@ class Router:
         self.ignore_invalid_deployments = ignore_invalid_deployments
         self.auto_router_capability_limit = auto_router_capability_limit
         self.fallback_access_check: Final = fallback_access_check
+        self.fallback_budget_check: Final = fallback_budget_check
         self.debug_level = debug_level
         self.enable_pre_call_checks = enable_pre_call_checks
         self.enable_tag_filtering = enable_tag_filtering
diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py
index 94164d0ea0c..d0abaed4d3a 100644
--- a/litellm/router_utils/fallback_event_handlers.py
+++ b/litellm/router_utils/fallback_event_handlers.py
@@ -421,6 +421,25 @@ async def _is_fallback_target_authorized(
     return False
 
 
+async def _is_fallback_target_within_budget(
+    litellm_router: LitellmRouter,
+    fallback_entry: str | Mapping[str, object],
+    original_model_group: str,
+    kwargs: Mapping[str, object],
+) -> bool:
+    budget_check: Final = litellm_router.fallback_budget_check
+    target: Final = _get_fallback_target_model_group(fallback_entry)
+    if budget_check is None or target is None or target == original_model_group:
+        return True
+    if await budget_check(model=target, request_kwargs=kwargs, llm_router=litellm_router):
+        return True
+    verbose_router_logger.info(
+        "Skipping fallback to model_group = %s: caller is over budget",
+        mask_sensitive_structure(fallback_entry),
+    )
+    return False
+
+
 def references_provider_scoped_resource(kwargs: Mapping[str, object]) -> bool:
     """
     True when a file, batch, or fine-tuning job operation names an id that only exists
@@ -528,6 +547,8 @@ async def run_async_fallback(
             continue
         if not await _is_fallback_target_authorized(litellm_router, mg, original_model_group, kwargs):
             continue
+        if not await _is_fallback_target_within_budget(litellm_router, mg, original_model_group, kwargs):
+            continue
         attempt_key = fallback_attempt_key(mg)
         if attempt_key is not None:
             if attempt_key in attempted:
diff --git a/litellm/types/router.py b/litellm/types/router.py
index 7c3e4d6943f..584d2494db4 100644
--- a/litellm/types/router.py
+++ b/litellm/types/router.py
@@ -963,6 +963,19 @@ class FallbackAccessCheck(Protocol):
     async def __call__(self, *, model: str, request_kwargs: Mapping[str, object], llm_router: "Router") -> bool: ...
 
 
+class FallbackBudgetCheck(Protocol):
+    """
+    Decides whether the caller behind `request_kwargs` is still within budget for fallback `model`.
+
+    Budget is enforced once during auth, against the *requested* model group. A fallback target is
+    chosen later, inside the router, so a zero-cost group that falls back to a priced one bills
+    without any budget gate. The router runs this before every cross-model-group fallback attempt
+    and skips targets it rejects, leaving the free attempt itself untouched.
+    """
+
+    async def __call__(self, *, model: str, request_kwargs: Mapping[str, object], llm_router: "Router") -> bool: ...
+
+
 class AutoRouterCapabilityLimit(Protocol):
     """
     Resolves how many complexity routers may claim each licensed capability right now; None means unlimited.
diff --git a/tests/test_litellm/proxy/auth/test_fallback_budget.py b/tests/test_litellm/proxy/auth/test_fallback_budget.py
new file mode 100644
index 00000000000..0ff1e05826d
--- /dev/null
+++ b/tests/test_litellm/proxy/auth/test_fallback_budget.py
@@ -0,0 +1,184 @@
+import pytest
+
+from litellm import Router
+from litellm.proxy._types import UserAPIKeyAuth
+from litellm.proxy.auth.fallback_budget import (
+    RouterFallbackBudgetCheck,
+    is_token_within_budget_for_model,
+)
+
+FREE_MODEL = {
+    "model_name": "free-model",
+    "litellm_params": {
+        "model": "ollama/llama2",
+        "api_base": "http://localhost:11434",
+        "input_cost_per_token": 0.0,
+        "output_cost_per_token": 0.0,
+    },
+    "model_info": {
+        "id": "free-model-id",
+        "input_cost_per_token": 0.0,
+        "output_cost_per_token": 0.0,
+    },
+}
+
+PAID_MODEL = {
+    "model_name": "paid-model",
+    "litellm_params": {"model": "openai/gpt-4o", "api_key": "k"},
+    "model_info": {"id": "paid-model-id"},
+}
+
+
+def _router() -> Router:
+    return Router(model_list=[FREE_MODEL, PAID_MODEL], fallbacks=[{"free-model": ["paid-model"]}])
+
+
+def _token(**overrides) -> UserAPIKeyAuth:
+    fields = {
+        "api_key": "hashed",
+        "token": "hashed",
+        "spend": 0.0,
+        "max_budget": None,
+        "user_id": "u1",
+        "user_spend": 0.0,
+        "user_max_budget": None,
+    }
+    fields.update(overrides)
+    return UserAPIKeyAuth(**fields)
+
+
+ENFORCED = RouterFallbackBudgetCheck(is_enforced=lambda: True)
+NOT_ENFORCED = RouterFallbackBudgetCheck(is_enforced=lambda: False)
+
+
+@pytest.mark.asyncio
+async def test_paid_target_allowed_when_under_budget():
+    token = _token(spend=1.0, max_budget=50.0, user_spend=1.0, user_max_budget=50.0)
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+async def test_paid_target_refused_when_over_key_budget():
+    token = _token(spend=100.0, max_budget=50.0)
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is False
+
+
+@pytest.mark.asyncio
+async def test_paid_target_refused_when_over_user_budget():
+    token = _token(user_spend=1900.0, user_max_budget=50.0)
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is False
+
+
+@pytest.mark.asyncio
+async def test_zero_cost_target_allowed_even_when_over_budget():
+    """Refusing a free target would deny a request on spend some other model accrued."""
+    token = _token(user_spend=1900.0, user_max_budget=50.0)
+    assert await is_token_within_budget_for_model(model="free-model", valid_token=token, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+async def test_no_budget_configured_is_always_within_budget():
+    token = _token(spend=9999.0, user_spend=9999.0)
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+async def test_team_key_does_not_inherit_personal_budget_by_default(monkeypatch):
+    """Mirrors _PROXY_MaxBudgetLimiter: a team key ignores the owner's personal cap."""
+    from litellm.proxy import proxy_server
+
+    monkeypatch.setattr(proxy_server, "general_settings", {}, raising=False)
+    token = _token(team_id="t1", user_spend=1900.0, user_max_budget=50.0)
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+async def test_team_key_inherits_personal_budget_when_opted_in(monkeypatch):
+    from litellm.proxy import proxy_server
+
+    monkeypatch.setattr(proxy_server, "general_settings", {"apply_user_budget_to_team_keys": True}, raising=False)
+    token = _token(team_id="t1", user_spend=1900.0, user_max_budget=50.0)
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is False
+
+
+@pytest.mark.asyncio
+async def test_check_is_a_no_op_while_not_enforced():
+    request = {"metadata": {"user_api_key_auth": _token(user_spend=1900.0, user_max_budget=50.0)}}
+    assert await NOT_ENFORCED(model="paid-model", request_kwargs=request, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+async def test_request_without_a_key_is_unrestricted():
+    assert await ENFORCED(model="paid-model", request_kwargs={}, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("metadata_field", ["metadata", "litellm_metadata"])
+async def test_enforced_check_reads_the_key_from_request_metadata(metadata_field: str):
+    over = {metadata_field: {"user_api_key_auth": _token(user_spend=1900.0, user_max_budget=50.0)}}
+    under = {metadata_field: {"user_api_key_auth": _token(user_spend=1.0, user_max_budget=50.0)}}
+
+    assert await ENFORCED(model="paid-model", request_kwargs=over, llm_router=_router()) is False
+    assert await ENFORCED(model="paid-model", request_kwargs=under, llm_router=_router()) is True
+
+
+@pytest.mark.asyncio
+async def test_a_stale_low_counter_still_refuses_a_paid_target(monkeypatch):
+    """
+    The counter can read low (e.g. restored from an older Redis snapshot). Passing the budget makes
+    `get_current_spend` verify against authoritative spend instead of trusting that read, so the
+    paid target is still refused.
+    """
+    from litellm.proxy import proxy_server
+
+    seen: list[dict] = []
+
+    async def _stale_counter(**kwargs):
+        seen.append(kwargs)
+        # a stale-low counter read; the authoritative spend is what the budget must be judged on
+        return 0.0 if kwargs.get("max_budget") is None else kwargs["fallback_spend"]
+
+    monkeypatch.setattr(proxy_server, "get_current_spend", _stale_counter, raising=False)
+    token = _token(user_spend=1900.0, user_max_budget=50.0)
+
+    assert await is_token_within_budget_for_model(model="paid-model", valid_token=token, llm_router=_router()) is False
+    assert [call["max_budget"] for call in seen] == [50.0]
+
+
+@pytest.mark.asyncio
+async def test_check_fails_closed_when_the_spend_lookup_breaks(monkeypatch):
+    from litellm.proxy import proxy_server
+
+    async def _boom(**kwargs):
+        raise RuntimeError("spend counter unavailable")
+
+    monkeypatch.setattr(proxy_server, "get_current_spend", _boom, raising=False)
+    request = {"metadata": {"user_api_key_auth": _token(user_spend=1.0, user_max_budget=50.0)}}
+
+    assert await ENFORCED(model="paid-model", request_kwargs=request, llm_router=_router()) is False
+
+
+@pytest.mark.asyncio
+async def test_router_skips_the_paid_fallback_target_when_over_budget():
+    from litellm.router_utils.fallback_event_handlers import _is_fallback_target_within_budget
+
+    router = Router(
+        model_list=[FREE_MODEL, PAID_MODEL],
+        fallbacks=[{"free-model": ["paid-model"]}],
+        fallback_budget_check=ENFORCED,
+    )
+    over = {"metadata": {"user_api_key_auth": _token(user_spend=1900.0, user_max_budget=50.0)}}
+    under = {"metadata": {"user_api_key_auth": _token(user_spend=1.0, user_max_budget=50.0)}}
+
+    assert await _is_fallback_target_within_budget(router, "paid-model", "free-model", over) is False
+    assert await _is_fallback_target_within_budget(router, "paid-model", "free-model", under) is True
+
+
+@pytest.mark.asyncio
+async def test_router_without_a_budget_check_attempts_every_fallback():
+    from litellm.router_utils.fallback_event_handlers import _is_fallback_target_within_budget
+
+    router = _router()  # fallback_budget_check defaults to None
+    over = {"metadata": {"user_api_key_auth": _token(user_spend=1900.0, user_max_budget=50.0)}}
+
+    assert await _is_fallback_target_within_budget(router, "paid-model", "free-model", over) is True
diff --git a/tests/test_litellm/proxy/test_proxy_server.py b/tests/test_litellm/proxy/test_proxy_server.py
index 6f55449abab..ca53887623f 100644
--- a/tests/test_litellm/proxy/test_proxy_server.py
+++ b/tests/test_litellm/proxy/test_proxy_server.py
@@ -13387,6 +13387,44 @@ async def test_load_config_router_authorizes_fallback_targets_against_the_callin
     assert router.fallback_access_check is router_fallback_access_check
 
 
+@pytest.mark.asyncio
+async def test_load_config_router_budget_checks_fallback_targets_against_the_calling_key(tmp_path, monkeypatch):
+    """A config-loaded router refuses a paid fallback target for an over-budget caller."""
+    from litellm.proxy import proxy_server
+    from litellm.proxy._types import UserAPIKeyAuth
+    from litellm.proxy.proxy_server import ProxyConfig
+
+    config_file = tmp_path / "config.yaml"
+    config_file.write_text(
+        yaml.dump({"model_list": [{"model_name": "m", "litellm_params": {"model": "openai/m", "api_key": "k"}}]})
+    )
+
+    router, _, _ = await ProxyConfig().load_config(router=None, config_file_path=str(config_file))
+
+    over_budget = {
+        "metadata": {
+            "user_api_key_auth": UserAPIKeyAuth(
+                api_key="hashed", token="hashed", user_id="u1", user_spend=99.0, user_max_budget=1.0
+            )
+        }
+    }
+    under_budget = {
+        "metadata": {
+            "user_api_key_auth": UserAPIKeyAuth(
+                api_key="hashed", token="hashed", user_id="u1", user_spend=0.0, user_max_budget=100.0
+            )
+        }
+    }
+
+    # off by default: the paid fallback is still attempted for an over-budget caller
+    monkeypatch.setattr(proxy_server, "general_settings", {}, raising=False)
+    assert await router.fallback_budget_check(model="m", request_kwargs=over_budget, llm_router=router) is True
+
+    monkeypatch.setattr(proxy_server, "general_settings", {"enforce_fallback_budget": True}, raising=False)
+    assert await router.fallback_budget_check(model="m", request_kwargs=over_budget, llm_router=router) is False
+    assert await router.fallback_budget_check(model="m", request_kwargs=under_budget, llm_router=router) is True
+
+
 @pytest.mark.asyncio
 async def test_load_config_user_api_key_cache_max_size_keeps_more_than_200_entries(tmp_path, monkeypatch):
     """The auth cache used to be pinned at InMemoryCache's 200 entry default, so a
diff --git a/tests/test_litellm/router_utils/test_fallback_event_handlers.py b/tests/test_litellm/router_utils/test_fallback_event_handlers.py
index 9318f306c89..dfe06bffd09 100644
--- a/tests/test_litellm/router_utils/test_fallback_event_handlers.py
+++ b/tests/test_litellm/router_utils/test_fallback_event_handlers.py
@@ -27,6 +27,7 @@ class StreamingWrapper:
 
 class FakeRouter:
     fallback_access_check = None
+    fallback_budget_check = None
 
     def log_retry(self, kwargs, e):
         return kwargs
@@ -37,6 +38,7 @@ class FakeRouter:
 
 class AlwaysFailRouter:
     fallback_access_check = None
+    fallback_budget_check = None
 
     def log_retry(self, kwargs, e):
         return kwargs
@@ -101,6 +103,7 @@ async def test_run_async_fallback_raises_when_all_fallbacks_fail():
 
 class RecordingRouter:
     fallback_access_check = None
+    fallback_budget_check = None
 
     def __init__(self):
         self.received_kwargs = None
@@ -162,6 +165,7 @@ async def test_run_async_fallback_skips_original_model_group():
 
 class AttemptRecordingRouter:
     fallback_access_check = None
+    fallback_budget_check = None
 
     def __init__(self):
         self.attempted_model_groups = []
@@ -471,6 +475,8 @@ class AccessCheckedRouter(AttemptRecordingRouter):
         self.allowed_models = allowed_models
         self.access_checks = []
 
+    fallback_budget_check = None
+
     async def fallback_access_check(self, *, model, request_kwargs, llm_router):
         self.access_checks.append((model, request_kwargs["metadata"]["user_api_key"], llm_router is self))
         return model in self.allowed_models
@@ -542,6 +548,7 @@ async def test_run_async_fallback_does_not_consult_access_check_for_same_model_g
 
 class RecordingFailRouter:
     fallback_access_check = None
+    fallback_budget_check = None
 
     def __init__(self):
         self.attempted_models = []
@@ -1053,6 +1060,7 @@ class TestTriggerCooldownForFailedDeployment:
 class TestRunAsyncFallbackTriggersCooldown:
     class RouterWithLoggingKwarg:
         fallback_access_check = None
+        fallback_budget_check = None
 
         def __init__(self):
             self.cooldown_time = 60.0

From c7246adc1dd571069a2cb3c77b3a40b720eb0da6 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 03:29:02 -0700
Subject: [PATCH 34/76] fix(e2e): route only the Bedrock models the runner role
 can invoke

The edge re-signs with the run pod's identity, whose IAM policy is an explicit
per-model allowlist. Matching on the `anthropic.` infix instead routed every
Anthropic-on-Bedrock model, so a model outside the policy came back 403 from
Bedrock with no fallback, taking the whole claude_code Bedrock matrix red.
An unlisted model now keeps its direct path and loses only caching.
---
 .../test_provider_cache.py                    |  4 ++++
 tests/e2e/PROVIDER_CACHE.md                   |  4 +++-
 tests/e2e/provider_cache_routing.py           | 23 ++++++++++++-------
 3 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 3dafbadf508..ac1ccd5692b 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -809,6 +809,8 @@ def test_registration_preserves_unsupported_or_explicit_routes(params: LiteLLMPa
     ("bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", "us-east-1"),
     ("bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", "os.environ/AWS_REGION"),
     ("bedrock/invoke/us.anthropic.claude-sonnet-5", "os.environ/AWS_REGION"),
+    ("bedrock/us.anthropic.claude-opus-4-7", "us-east-1"),
+    ("bedrock/converse/us.anthropic.claude-opus-4-7", "us-east-1"),
 ])
 def test_anthropic_on_bedrock_registers_the_edge_as_its_runtime_endpoint(model: str, region: str | None) -> None:
     """Almost every Bedrock deployment in the suite declares its region as
@@ -839,6 +841,8 @@ def test_anthropic_on_bedrock_registers_the_edge_as_its_runtime_endpoint(model:
     LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0", aws_region_name="eu-west-1"),
     LiteLLMParamsBody(model="bedrock/anthropic.claude-sonnet-5", aws_region_name="os.environ/AWS_REGION"),
     LiteLLMParamsBody(model="bedrock/invoke/eu.anthropic.claude-sonnet-5", aws_region_name="os.environ/AWS_REGION"),
+    LiteLLMParamsBody(model="bedrock/us.anthropic.claude-opus-4-5", aws_region_name="us-east-1"),
+    LiteLLMParamsBody(model="bedrock/converse/us.anthropic.claude-haiku-9-9", aws_region_name="us-east-1"),
 ])
 def test_bedrock_deployments_the_edge_must_not_touch_keep_their_direct_route(params: LiteLLMParamsBody) -> None:
     """Non-Anthropic models the runner role cannot invoke, deployments carrying
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index c530574cda2..3a29c7b6fe4 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -22,7 +22,9 @@ Bedrock could not be mounted before because SigV4 signs the `Host` header, so a
 
 Almost every Bedrock deployment in the suite declares its region as `os.environ/AWS_REGION`, which only the proxy can resolve, and the run pod does not share that environment. A `us.` inference profile fans out across the US regions and is reachable from any of them, so those route to the default mount whatever the proxy resolved. A model that is not cross-region and declares its region that way keeps its direct path rather than being sent to a region it may not exist in.
 
-Only deployments that carry no AWS identity of their own route to the edge. A deployment with `aws_role_name`, `aws_access_key_id`, an `api_base` or an `aws_bedrock_runtime_endpoint` keeps its direct path, because re-signing it would quietly replace the very credential chain that test exists to prove. Only Anthropic models route, matching what the runner role is allowed to invoke and what the edge knows how to validate
+Only deployments that carry no AWS identity of their own route to the edge. A deployment with `aws_role_name`, `aws_access_key_id`, an `api_base` or an `aws_bedrock_runtime_endpoint` keeps its direct path, because re-signing it would quietly replace the very credential chain that test exists to prove
+
+Which models route is an explicit allowlist in `provider_cache_routing.py`, mirroring the runner role's IAM policy, which names its models one by one. That coupling is deliberate: the edge re-signs with the run pod's identity, so a model the role cannot invoke comes back 403 from Bedrock rather than falling back. An unlisted model keeps its direct path and loses only caching, so adding a Bedrock model to the suite can never turn it red. Adding one to the edge is a policy edit in litellm-ops plus a line here
 
 Vertex and Gemini are not mounted. litellm's `_check_custom_proxy` rewrites a path-prefixed Vertex `api_base` into `{api_base}:{endpoint}`, dropping project, location and model, so a mount under a path prefix cannot work without either a root-mounted edge on its own port or a change in litellm
 
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
index d2237bb49bc..97e05344423 100644
--- a/tests/e2e/provider_cache_routing.py
+++ b/tests/e2e/provider_cache_routing.py
@@ -9,8 +9,15 @@ from models import LiteLLMParamsBody, ModelMode
 LIVE_PROVIDER_REQUIRED: Final[ContextVar[bool]] = ContextVar("live_provider_required", default=False)
 
 DEFAULT_BEDROCK_REGION: Final = "us-east-1"
-BEDROCK_ANTHROPIC_INFIX: Final = "anthropic."
 BEDROCK_CROSS_REGION_PREFIX: Final = "us."
+BEDROCK_EDGE_MODELS: Final = frozenset(
+    {
+        "us.anthropic.claude-haiku-4-5-20251001-v1:0",
+        "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        "us.anthropic.claude-sonnet-5",
+        "us.anthropic.claude-opus-4-7",
+    }
+)
 ENV_REFERENCE_PREFIX: Final = "os.environ/"
 
 
@@ -33,16 +40,16 @@ def bedrock_region(declared: str | None, model: str) -> str | None:
 
 
 def bedrock_mount(params: LiteLLMParamsBody) -> str | None:
-    """The edge mount an Anthropic-on-Bedrock deployment belongs to, or None.
+    """The edge mount a Bedrock deployment belongs to, or None.
 
-    Only the Anthropic models route. The edge validates converse and invoke
-    bodies by their Anthropic and Converse terminator fields, and the runner role
-    is allowed to invoke exactly those models, so Bedrock embeddings, image
-    generation, rerank and realtime keep their existing direct path rather than
-    reaching an edge that could neither sign nor validate for them."""
+    The allowlist mirrors the runner role's IAM policy, which names its models
+    one by one. A model outside it would be re-signed with an identity that
+    cannot invoke it and come back 403 from Bedrock, so an unlisted model keeps
+    its direct path and loses only caching. Adding a model is a policy edit in
+    litellm-ops and a line here."""
     route: Final = params.model.partition("/")[2]
     model: Final = route.partition("/")[2] or route
-    if BEDROCK_ANTHROPIC_INFIX not in model:
+    if model not in BEDROCK_EDGE_MODELS:
         return None
     region: Final = bedrock_region(params.aws_region_name, model)
     return None if region is None else f"bedrock/{region}"

From ebf34cd88006110c78a50648578e3dc7e0f115cd Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 03:35:00 -0700
Subject: [PATCH 35/76] docs(e2e): say plainly that Bedrock streaming is not
 cached

---
 tests/e2e/PROVIDER_CACHE.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 3a29c7b6fe4..fe289e406aa 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -2,7 +2,9 @@
 
 `E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge, as do Anthropic-on-Bedrock registrations that carry no AWS identity of their own. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
 
-The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, and for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount, including streams. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
+The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, SSE streams included, and for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
+
+Bedrock's streaming endpoints, `converse-stream` and `invoke-with-response-stream`, are not cacheable. They still cross the edge and are still re-signed, so they need the same IAM, but they always call the provider. AWS frames them as binary `vnd.amazon.eventstream` rather than SSE, and reading a terminal event out of that is what a completeness rule for them would need. That matters more than the endpoint count suggests: the Claude Code compat cells drive the real CLI, which always streams, so most Bedrock traffic in the suite is not cached today
 
 ## Request identity
 

From 7c2234be3a91a600c02f416e678b163dd53746ac Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 04:41:29 -0700
Subject: [PATCH 36/76] test(e2e): enforce the cross-region invariant on the
 Bedrock allowlist

The allowlist rejects an unlisted model before the region resolver runs, so the
two negative cases that used to cover the resolver were passing for the wrong
reason and two mutations of it survived. Answering an env-referenced region with
the default mount is only sound because every allowlisted model is a `us.`
profile that fans out across the US regions, so assert that on the list itself
and drop the per-call branch it made unreachable.
---
 .../test_provider_cache.py                    | 33 ++++++++++++++++++-
 tests/e2e/provider_cache_routing.py           | 27 +++++++--------
 2 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index ac1ccd5692b..c24ba8d6221 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -33,7 +33,13 @@ from provider_cache import (
     successful_response,
 )
 from provider_cache_redis import PUBLISH, RedisCommands, RedisResponseStore, configured_cache, redis_store
-from provider_cache_routing import LIVE_PROVIDER_REQUIRED, route_cache_model
+from provider_cache_routing import (
+    BEDROCK_CROSS_REGION_PREFIX,
+    BEDROCK_EDGE_MODELS,
+    LIVE_PROVIDER_REQUIRED,
+    bedrock_region,
+    route_cache_model,
+)
 from fixture_mode import SESSION_TEST_KEY
 from provider_edge import EDGE_MOUNTS, configured_cache_backend, resolve_mount, start_provider_edge
 from provider_edge_bedrock import bedrock_signer
@@ -856,6 +862,31 @@ def test_bedrock_deployments_the_edge_must_not_touch_keep_their_direct_route(par
     assert routed is params
 
 
+@pytest.mark.parametrize("declared,expected", [
+    (None, "us-east-1"),
+    ("us-west-2", "us-west-2"),
+    ("eu-west-1", "eu-west-1"),
+    ("os.environ/AWS_REGION", "us-east-1"),
+    ("os.environ/ANY_OTHER_NAME", "us-east-1"),
+])
+def test_a_region_only_the_proxy_can_resolve_falls_back_to_the_default_mount(
+    declared: str | None, expected: str,
+) -> None:
+    """A declared literal region is the one the deployment meant. A region the
+    proxy resolves from its own environment is one the run pod cannot see, and
+    the default mount answers it."""
+    assert bedrock_region(declared) == expected
+
+
+def test_every_model_on_the_edge_allowlist_is_a_cross_region_profile() -> None:
+    """Answering an env-referenced region with the default mount is only correct
+    for a profile that fans out across the US regions and is reachable from any
+    of them. A single-region model on this list would be sent to a region it may
+    not exist in, so the list is where that is caught."""
+    assert BEDROCK_EDGE_MODELS
+    assert all(model.startswith(BEDROCK_CROSS_REGION_PREFIX) for model in BEDROCK_EDGE_MODELS)
+
+
 @pytest.mark.parametrize("mode", ["batch", "realtime", "image_generation"])
 def test_a_bedrock_deployment_with_a_mode_keeps_its_direct_route(mode: ModelMode) -> None:
     params: Final = LiteLLMParamsBody(model="bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0")
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
index 97e05344423..f9775a2b152 100644
--- a/tests/e2e/provider_cache_routing.py
+++ b/tests/e2e/provider_cache_routing.py
@@ -21,22 +21,18 @@ BEDROCK_EDGE_MODELS: Final = frozenset(
 ENV_REFERENCE_PREFIX: Final = "os.environ/"
 
 
-def bedrock_region(declared: str | None, model: str) -> str | None:
-    """The region whose edge mount a deployment belongs to, or None when the
-    harness cannot know it.
+def bedrock_region(declared: str | None) -> str:
+    """The region whose edge mount a deployment belongs to.
 
-    Most Bedrock deployments declare `os.environ/AWS_REGION`, which the proxy
-    resolves from its own environment. The run pod does not share that
-    environment, so the harness genuinely does not know the region. A `us.`
-    inference profile fans out across the US regions and is reachable from any
-    of them, so the default entry point is correct for those whatever the proxy
-    resolved; anything else keeps its direct path rather than being sent to a
-    region the model may not exist in."""
-    if declared is None:
+    Most Bedrock deployments declare `os.environ/AWS_REGION`, which only the
+    proxy can resolve from its own environment; the run pod does not share it.
+    Answering those with the default mount is correct because every model on the
+    edge allowlist is a `us.` inference profile, which fans out across the US
+    regions and is reachable from any of them. That invariant is enforced on the
+    allowlist itself rather than re-checked per call."""
+    if declared is None or declared.startswith(ENV_REFERENCE_PREFIX):
         return DEFAULT_BEDROCK_REGION
-    if not declared.startswith(ENV_REFERENCE_PREFIX):
-        return declared
-    return DEFAULT_BEDROCK_REGION if model.startswith(BEDROCK_CROSS_REGION_PREFIX) else None
+    return declared
 
 
 def bedrock_mount(params: LiteLLMParamsBody) -> str | None:
@@ -51,8 +47,7 @@ def bedrock_mount(params: LiteLLMParamsBody) -> str | None:
     model: Final = route.partition("/")[2] or route
     if model not in BEDROCK_EDGE_MODELS:
         return None
-    region: Final = bedrock_region(params.aws_region_name, model)
-    return None if region is None else f"bedrock/{region}"
+    return f"bedrock/{bedrock_region(params.aws_region_name)}"
 
 
 def route_bedrock(

From bd1c2d6f07d7b9edd46bb11d95ad22cb7e029ea9 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 05:09:04 -0700
Subject: [PATCH 37/76] fix(e2e): keep the tool-continuation echo-back test on
 the live path

The key normalizes a unique marker so two builds match, which is the whole
point, but it makes this test's identity collide with an earlier run's: it mints
a fresh receipt, sends it through a tool result, and asserts the model echoes it
back verbatim, so a stale recording matched and answered with the old receipt.
Build 223 is where that surfaced, once the corpus was full enough for the first
call to hit. A test that asserts a provider echoed this run's own unique value
belongs on the live path.
---
 tests/e2e/PROVIDER_CACHE.md                    | 4 +++-
 tests/e2e/conftest.py                          | 6 +++++-
 tests/e2e/llm_translation/test_messages_e2e.py | 1 +
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index fe289e406aa..698e78a5aa1 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -44,7 +44,9 @@ The trusted runner receives:
 
 Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
 
-Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
+Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read.
+
+One more class needs it, and it is the cost of normalizing the marker. A test that mints a fresh marker, sends it, and then asserts the provider's answer contains that exact value is asserting on the marker rather than using it as a salt. The key treats two such requests as the same identity, so a stale recording matches and answers with the marker from the run that recorded it. `TestOpenAIMessagesToolContinuation` is the one in the suite today: it sends a freshly minted receipt through a tool result and asserts the model echoes it back verbatim. If you add a test that asserts a provider echoed your own unique value, it belongs on the live path. Ordinary assertion failures still fail E2E. The shared cache does not modify provider response IDs or make the proxy aware of replay
 
 ## Recorded response semantics
 
diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py
index 829c84910a9..430e16525d5 100644
--- a/tests/e2e/conftest.py
+++ b/tests/e2e/conftest.py
@@ -85,7 +85,11 @@ def jwt_identity(idp: Keycloak, resources: ResourceManager, proxy: ProxyClient)
 
 
 def pytest_configure(config: pytest.Config) -> None:
-    config.addinivalue_line("markers", "provider_live: requires actual provider timing, limits or state; bypass shared cache")
+    config.addinivalue_line(
+        "markers",
+        "provider_live: requires actual provider timing, limits, state, or a response that echoes this"
+        " run's own unique value; bypass shared cache",
+    )
     config.addinivalue_line(
         "markers",
         "e2e: live test that requires a running proxy and real provider keys",
diff --git a/tests/e2e/llm_translation/test_messages_e2e.py b/tests/e2e/llm_translation/test_messages_e2e.py
index 44c416a3e78..09ec48daa2f 100644
--- a/tests/e2e/llm_translation/test_messages_e2e.py
+++ b/tests/e2e/llm_translation/test_messages_e2e.py
@@ -372,6 +372,7 @@ def _request_tool(
 
 
 class TestOpenAIMessagesToolContinuation:
+    @pytest.mark.provider_live
     @pytest.mark.parametrize("stream", [True, False], ids=["stream", "nonstream"])
     def test_required_tool_arguments_and_correlated_result(
         self, endpoints_client: EndpointsClient, resources: ResourceManager, stream: bool

From 30a691ed55c59d8fd19c28e5356ba196bf5ae45a Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 06:46:19 -0700
Subject: [PATCH 38/76] feat(e2e): cache Bedrock streaming responses

The Claude Code compat cells drive the real CLI, which always streams, so
converse-stream and invoke-with-response-stream were most of the suite's
Bedrock traffic and all of it bypassed the edge.

AWS frames those as binary vnd.amazon.eventstream rather than SSE, so
botocore's own parser reads the frames and validates both CRCs, and each
endpoint is then held to its terminal grammar. Two details drove the rule.
A ConverseStream ends with metadata, not with messageStop, and metadata is
what carries the token usage litellm prices the call from, so a stream cut
between the two names a stop reason but would replay as a free call. And a
dropped connection is invisible to the parser: it yields the frames it did
receive and silently discards a trailing partial one, so a stream cut one
byte short parses clean. The body is checked against the frame lengths it
declares to catch that.

The invoke stream carries the ordinary Anthropic event grammar inside its
chunk frames, so it shares the completeness rule with the SSE mounts.

Validated against three real Bedrock eventstream captures, and the tests
build their own frames rather than pasting a capture, with one test holding
that framing to botocore's parser.
---
 .../test_provider_cache.py                    | 258 ++++++++++++++++--
 tests/e2e/PROVIDER_CACHE.md                   |   4 +-
 tests/e2e/provider_cache.py                   | 141 +++++++++-
 3 files changed, 370 insertions(+), 33 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index c24ba8d6221..4c131434ecd 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -1,9 +1,13 @@
 from __future__ import annotations
 
+import base64
+import binascii
+import json
 import os
 import shutil
 import socket
 import subprocess
+import struct
 import threading
 import time
 import uuid
@@ -17,9 +21,11 @@ from typing import Final
 from urllib.parse import urlsplit
 
 import pytest
+from pydantic import JsonValue
 from e2e_http import NetworkError, PreparedForward, RawResponse, StreamChunk, StreamHead, forward, prepare_forward
 from models import LiteLLMParamsBody, ModelMode
 from botocore.credentials import Credentials
+from botocore.eventstream import EventStreamBuffer
 from provider_cache import (
     SIGNATURE_HEADERS,
     CacheEdge,
@@ -638,6 +644,53 @@ class TestNonChatOpenAiEndpoints:
         assert cacheable_endpoint("openai", "POST", f"https://api.openai.com{path}", MARKED) is cacheable
 
 
+BEDROCK_STREAM_MODEL: Final = "us.anthropic.claude-haiku-4-5-20251001-v1:0"
+CONVERSE_STREAM_URL: Final = f"https://bedrock.invalid/model/{BEDROCK_STREAM_MODEL}/converse-stream"
+INVOKE_STREAM_URL: Final = f"https://bedrock.invalid/model/{BEDROCK_STREAM_MODEL}/invoke-with-response-stream"
+
+
+def eventstream_frame(headers: Mapping[str, str], payload: bytes) -> bytes:
+    """AWS eventstream wire framing, the shape `vnd.amazon.eventstream` bodies
+    arrive in. Built here rather than pasted from a capture so a test can express
+    the stream it means; `test_the_frames_these_tests_build_are_real_aws_framing`
+    holds it to botocore's own parser."""
+    encoded: Final = b"".join(
+        bytes([len(name)]) + name.encode() + b"\x07" + struct.pack(">H", len(value)) + value.encode()
+        for name, value in headers.items()
+    )
+    prelude: Final = struct.pack(">II", 16 + len(encoded) + len(payload), len(encoded))
+    framed: Final = prelude + struct.pack(">I", binascii.crc32(prelude)) + encoded + payload
+    return framed + struct.pack(">I", binascii.crc32(framed))
+
+
+def eventstream_event(event_type: str, payload: JsonValue, message_type: str = "event") -> bytes:
+    return eventstream_frame(
+        {":event-type": event_type, ":message-type": message_type, ":content-type": "application/json"},
+        json.dumps(payload).encode(),
+    )
+
+
+def invoke_chunk(inner: JsonValue) -> bytes:
+    return eventstream_event("chunk", {"bytes": base64.b64encode(json.dumps(inner).encode()).decode("ascii")})
+
+
+CONVERSE_STREAM_OK: Final = (
+    eventstream_event("messageStart", {"role": "assistant"})
+    + eventstream_event("contentBlockDelta", {"contentBlockIndex": 0, "delta": {"text": "hi"}})
+    + eventstream_event("contentBlockStop", {"contentBlockIndex": 0})
+    + eventstream_event("messageStop", {"stopReason": "end_turn"})
+    + eventstream_event("metadata", {"usage": {"inputTokens": 12, "outputTokens": 6, "totalTokens": 18}})
+)
+INVOKE_STREAM_OK: Final = (
+    invoke_chunk({"type": "message_start", "message": {"id": "msg_bdrk_x", "role": "assistant"}})
+    + invoke_chunk({"type": "content_block_start", "index": 0})
+    + invoke_chunk({"type": "content_block_delta", "index": 0, "delta": {"text": "hi"}})
+    + invoke_chunk({"type": "content_block_stop", "index": 0})
+    + invoke_chunk({"type": "message_delta", "delta": {"stop_reason": "end_turn"}})
+    + invoke_chunk({"type": "message_stop"})
+)
+
+
 class TestBedrockSigning:
     """Bedrock is the reason the edge could not mount it before: SigV4 covers the
     Host header, so forwarding through a rewritten api_base invalidates the
@@ -738,32 +791,55 @@ class TestBedrockSigning:
                 assert call(url, BEDROCK_BODY).body == response
         assert len(provider.hits) == 2
 
-    @pytest.mark.parametrize("action", ["converse-stream", "invoke-with-response-stream"])
-    def test_streaming_endpoints_go_live_every_time(
-        self, store: RedisResponseStore, provider: Provider, action: str,
+    @pytest.mark.parametrize("action,response", [
+        ("converse-stream", CONVERSE_STREAM_OK),
+        ("invoke-with-response-stream", INVOKE_STREAM_OK),
+    ], ids=["converse-stream", "invoke-stream"])
+    def test_a_finished_stream_is_served_from_the_cache_the_second_time(
+        self, store: RedisResponseStore, provider: Provider, action: str, response: bytes,
     ) -> None:
-        """An eventstream's completeness cannot be proven without parsing its
-        frames, so these bypass rather than risk recording a truncated answer.
-        They are still signed: a bypass is a forward, not a passthrough."""
-        provider.response = CONVERSE_SUCCESS
-        cache: Final = bedrock_cache_edge(store)
-        for _ in range(2):
-            with bedrock_edge(cache, provider, action) as url:
-                assert call(url, BEDROCK_BODY).body == CONVERSE_SUCCESS
-        assert len(provider.hits) == 2
-        assert dict(cache.counters.counts)[f"mount:{BEDROCK_MOUNT}:bypass"] == 2
+        provider.response = response
+        with bedrock_edge(bedrock_cache_edge(store), provider, action) as url:
+            assert call(url, BEDROCK_BODY).body == response
+        assert len(provider.hits) == 1
+        replay: Final = bedrock_cache_edge(store)
+        with bedrock_edge(replay, provider, action) as url:
+            assert call(url, BEDROCK_BODY).body == response
+        assert len(provider.hits) == 1
+        assert dict(replay.counters.counts)[f"mount:{BEDROCK_MOUNT}:hits"] == 1
         assert all(
             sent.startswith("AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/")
             for sent in provider.authorizations
         ), provider.authorizations
 
-    @pytest.mark.parametrize("action,cacheable", [
-        ("converse", True), ("invoke", True),
-        ("converse-stream", False), ("invoke-with-response-stream", False),
-    ])
-    def test_only_the_unary_bedrock_actions_are_cacheable(self, action: str, cacheable: bool) -> None:
+    @pytest.mark.parametrize("action,response", [
+        ("converse-stream", CONVERSE_STREAM_OK[:-1]),
+        ("invoke-with-response-stream", INVOKE_STREAM_OK[:-1]),
+    ], ids=["converse-stream", "invoke-stream"])
+    def test_a_stream_the_connection_cut_short_calls_the_provider_every_time(
+        self, store: RedisResponseStore, provider: Provider, action: str, response: bytes,
+    ) -> None:
+        """The whole risk of caching an eventstream is recording a half-finished
+        one, so a truncated body has to be rejected rather than stored."""
+        provider.response = response
+        with bedrock_edge(bedrock_cache_edge(store), provider, action) as url:
+            assert call(url, BEDROCK_BODY).body == response
+        replay: Final = bedrock_cache_edge(store)
+        with bedrock_edge(replay, provider, action) as url:
+            assert call(url, BEDROCK_BODY).body == response
+        assert len(provider.hits) == 2
+        assert dict(replay.counters.counts)[f"mount:{BEDROCK_MOUNT}:rejected"] == 1
+        assert f"mount:{BEDROCK_MOUNT}:hits" not in dict(replay.counters.counts)
+
+    @pytest.mark.parametrize("action", ["converse", "invoke", "converse-stream", "invoke-with-response-stream"])
+    def test_every_anthropic_bedrock_action_is_cacheable(self, action: str) -> None:
         url: Final = f"https://bedrock-runtime.us-east-1.amazonaws.com/model/{BEDROCK_MODEL}/{action}"
-        assert cacheable_endpoint(BEDROCK_MOUNT, "POST", url, BEDROCK_BODY) is cacheable
+        assert cacheable_endpoint(BEDROCK_MOUNT, "POST", url, BEDROCK_BODY)
+
+    @pytest.mark.parametrize("action", ["count-tokens", "invoke-async", "converse-stream-x"])
+    def test_an_unknown_bedrock_action_is_not_cacheable(self, action: str) -> None:
+        url: Final = f"https://bedrock-runtime.us-east-1.amazonaws.com/model/{BEDROCK_MODEL}/{action}"
+        assert not cacheable_endpoint(BEDROCK_MOUNT, "POST", url, BEDROCK_BODY)
 
     def test_a_region_mount_resolves_whole(self) -> None:
         resolved: Final = resolve_mount(f"/{BEDROCK_MOUNT}/model/{BEDROCK_MODEL}/converse", EDGE_MOUNTS)
@@ -1021,3 +1097,147 @@ def test_duplicate_headers_bypass_cache_and_count_live_calls(
     assert len(provider.hits) == (2 if known_mount else 0)
     assert dict(cache.counters.counts)["duplicate_header_bypass"] == 2
     assert dict(cache.counters.counts).get("upstream_attempts", 0) == (2 if known_mount else 0)
+
+
+class TestBedrockStreams:
+    def test_the_frames_these_tests_build_are_real_aws_framing(self) -> None:
+        buffer: Final = EventStreamBuffer()
+        buffer.add_data(CONVERSE_STREAM_OK)
+        assert [event.headers[":event-type"] for event in buffer] == [
+            "messageStart", "contentBlockDelta", "contentBlockStop", "messageStop", "metadata",
+        ]
+
+    @pytest.mark.parametrize("url,body", [
+        (CONVERSE_STREAM_URL, CONVERSE_STREAM_OK),
+        (INVOKE_STREAM_URL, INVOKE_STREAM_OK),
+    ])
+    def test_a_finished_stream_is_recordable(self, url: str, body: bytes) -> None:
+        assert cacheable_endpoint(BEDROCK_MOUNT, "POST", url, b"{}")
+        assert successful_response(BEDROCK_MOUNT, url, 200, {}, body)
+
+    @pytest.mark.parametrize("url,body", [
+        (CONVERSE_STREAM_URL, CONVERSE_STREAM_OK),
+        (INVOKE_STREAM_URL, INVOKE_STREAM_OK),
+    ])
+    @pytest.mark.parametrize("keep", [1, -1, -4])
+    def test_a_stream_the_connection_cut_short_is_not_recordable(
+        self, url: str, body: bytes, keep: int,
+    ) -> None:
+        """botocore yields the frames it did receive and silently drops a trailing
+        partial one, so a stream cut a single byte short parses clean and only the
+        byte accounting and the terminator rule catch it."""
+        assert not successful_response(BEDROCK_MOUNT, url, 200, {}, body[:keep])
+
+    @pytest.mark.parametrize("url,body", [
+        (CONVERSE_STREAM_URL, CONVERSE_STREAM_OK),
+        (INVOKE_STREAM_URL, INVOKE_STREAM_OK),
+    ])
+    def test_a_corrupted_frame_is_not_recordable(self, url: str, body: bytes) -> None:
+        flipped: Final = bytearray(body)
+        flipped[len(body) // 2] ^= 0xFF
+        assert not successful_response(BEDROCK_MOUNT, url, 200, {}, bytes(flipped))
+
+    def test_a_converse_stream_that_lost_its_usage_is_not_recordable(self) -> None:
+        """ConverseStream names its stop reason a frame before it reports usage,
+        and litellm prices the call from that usage, so a stream cut between the
+        two would replay as a free call."""
+        without_metadata: Final = (
+            eventstream_event("messageStart", {"role": "assistant"})
+            + eventstream_event("messageStop", {"stopReason": "end_turn"})
+        )
+        assert not successful_response(BEDROCK_MOUNT, CONVERSE_STREAM_URL, 200, {}, without_metadata)
+
+    def test_a_converse_stream_that_never_stopped_is_not_recordable(self) -> None:
+        assert not successful_response(
+            BEDROCK_MOUNT, CONVERSE_STREAM_URL, 200, {},
+            eventstream_event("messageStart", {"role": "assistant"})
+            + eventstream_event("metadata", {"usage": {"totalTokens": 18}}),
+        )
+
+    def test_a_stream_that_failed_after_answering_200_is_not_recordable(self) -> None:
+        """Bedrock reports a fault that began after the headers went out as an
+        exception frame in place of the terminator it never got to send."""
+        assert not successful_response(
+            BEDROCK_MOUNT, CONVERSE_STREAM_URL, 200, {},
+            eventstream_event("messageStart", {"role": "assistant"})
+            + eventstream_event("contentBlockDelta", {"contentBlockIndex": 0, "delta": {"text": "hi"}})
+            + eventstream_event("modelStreamErrorException", {"message": "boom"}, message_type="exception"),
+        )
+
+    @pytest.mark.parametrize("url,body", [
+        (CONVERSE_STREAM_URL, CONVERSE_STREAM_OK),
+        (INVOKE_STREAM_URL, INVOKE_STREAM_OK),
+    ], ids=["converse-stream", "invoke-stream"])
+    def test_a_stream_cut_after_its_terminator_is_not_recordable(self, url: str, body: bytes) -> None:
+        """The terminator rules cannot see this one. Every frame the stream owes
+        has arrived and the partial frame after them is the one botocore drops
+        without a word, so only counting the bytes against the frame lengths
+        tells this from a stream that ended where it meant to."""
+        assert successful_response(BEDROCK_MOUNT, url, 200, {}, body)
+        assert not successful_response(BEDROCK_MOUNT, url, 200, {}, body + b"\x00\x00\x02")
+
+    def test_a_converse_stream_whose_stop_frame_names_no_reason_is_not_recordable(self) -> None:
+        assert not successful_response(
+            BEDROCK_MOUNT, CONVERSE_STREAM_URL, 200, {},
+            eventstream_event("messageStart", {"role": "assistant"})
+            + eventstream_event("messageStop", {})
+            + eventstream_event("metadata", {"usage": {"totalTokens": 18}}),
+        )
+
+    def test_an_invoke_stream_carrying_a_frame_that_is_not_a_chunk_is_not_recordable(self) -> None:
+        """Every frame of an invoke stream is a `chunk` holding one base64 event.
+        A frame that is not one carries an event this rule cannot read, so the
+        stream can no longer be judged complete."""
+        assert not successful_response(
+            BEDROCK_MOUNT, INVOKE_STREAM_URL, 200, {},
+            invoke_chunk({"type": "message_start", "message": {"id": "msg_bdrk_x"}})
+            + eventstream_event("metadata", {"usage": {"totalTokens": 18}})
+            + invoke_chunk({"type": "message_delta", "delta": {"stop_reason": "end_turn"}})
+            + invoke_chunk({"type": "message_stop"}),
+        )
+
+    def test_a_frame_claiming_no_length_is_rejected_rather_than_walked_forever(self) -> None:
+        """A frame length of zero never advances the cursor. Rejecting it is what
+        keeps a corrupt body from spinning the edge instead of answering."""
+        assert not successful_response(BEDROCK_MOUNT, CONVERSE_STREAM_URL, 200, {}, b"\x00\x00\x00\x00" * 4)
+
+    @pytest.mark.parametrize("url,terminator", [
+        (INVOKE_STREAM_URL, invoke_chunk({"type": "message_stop"})),
+        (CONVERSE_STREAM_URL, eventstream_event("metadata", {"usage": {"totalTokens": 18}})),
+    ], ids=["invoke-stream", "converse-stream"])
+    def test_a_delta_that_names_no_stop_reason_does_not_finish_a_stream(
+        self, url: str, terminator: bytes,
+    ) -> None:
+        """A `message_delta` arriving without its stop reason is the shape of a
+        turn the connection cut short partway through the delta itself."""
+        head: Final = (
+            invoke_chunk({"type": "message_start", "message": {"id": "msg_bdrk_x"}})
+            + invoke_chunk({"type": "message_delta", "delta": {}})
+        )
+        assert not successful_response(BEDROCK_MOUNT, url, 200, {}, head + terminator)
+
+    def test_an_invoke_chunk_that_is_not_base64_is_not_recordable(self) -> None:
+        assert not successful_response(
+            BEDROCK_MOUNT, INVOKE_STREAM_URL, 200, {},
+            invoke_chunk({"type": "message_start", "message": {"id": "msg_bdrk_x"}})
+            + eventstream_event("chunk", {"bytes": "not base64 at all !!"})
+            + invoke_chunk({"type": "message_stop"}),
+        )
+
+    def test_an_invoke_stream_missing_its_stop_reason_is_not_recordable(self) -> None:
+        assert not successful_response(
+            BEDROCK_MOUNT, INVOKE_STREAM_URL, 200, {},
+            invoke_chunk({"type": "message_start", "message": {"id": "msg_bdrk_x"}})
+            + invoke_chunk({"type": "message_stop"}),
+        )
+
+    def test_an_empty_stream_is_not_recordable(self) -> None:
+        for url in (CONVERSE_STREAM_URL, INVOKE_STREAM_URL):
+            assert not successful_response(BEDROCK_MOUNT, url, 200, {}, b"")
+
+    def test_each_streaming_endpoint_is_held_to_its_own_grammar(self) -> None:
+        assert not successful_response(BEDROCK_MOUNT, CONVERSE_STREAM_URL, 200, {}, INVOKE_STREAM_OK)
+        assert not successful_response(BEDROCK_MOUNT, INVOKE_STREAM_URL, 200, {}, CONVERSE_STREAM_OK)
+
+    def test_a_stream_that_errored_before_it_started_is_not_recordable(self) -> None:
+        assert not successful_response(BEDROCK_MOUNT, CONVERSE_STREAM_URL, 503, {}, CONVERSE_STREAM_OK)
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 698e78a5aa1..29d6e5ab4f2 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -4,7 +4,9 @@
 
 The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, SSE streams included, and for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
 
-Bedrock's streaming endpoints, `converse-stream` and `invoke-with-response-stream`, are not cacheable. They still cross the edge and are still re-signed, so they need the same IAM, but they always call the provider. AWS frames them as binary `vnd.amazon.eventstream` rather than SSE, and reading a terminal event out of that is what a completeness rule for them would need. That matters more than the endpoint count suggests: the Claude Code compat cells drive the real CLI, which always streams, so most Bedrock traffic in the suite is not cached today
+Bedrock's streaming endpoints, `converse-stream` and `invoke-with-response-stream`, cache too. AWS frames those as binary `vnd.amazon.eventstream` rather than SSE, so botocore's own parser reads the frames and validates both CRCs, and each endpoint is then held to its terminal grammar. That matters more than the endpoint count suggests: the Claude Code compat cells drive the real CLI, which always streams, so streaming is most of the suite's Bedrock traffic
+
+Two details of that rule are worth knowing before changing it. A ConverseStream ends with `metadata`, not with `messageStop`, and the `metadata` frame is what carries the token usage litellm prices the call from, so the rule requires it: a stream cut between the two still names a stop reason but would replay as a free call. And a dropped connection is invisible to the parser, which yields the frames it did receive and silently discards a trailing partial one, so the body is also checked against the frame lengths it declares. A stream cut one byte short parses clean and has to be caught that way
 
 ## Request identity
 
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 0dee33f33c6..9ae89861f63 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -13,6 +13,7 @@ from types import MappingProxyType
 from typing import Final, Literal, Protocol
 from urllib.parse import urlsplit
 
+from botocore.eventstream import EventStreamBuffer, ParserError
 from e2e_http import (
     NetworkError,
     StreamChunk,
@@ -36,6 +37,19 @@ SIGNATURE_HEADERS: Final = frozenset(
     {"authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"}
 )
 BEDROCK_MOUNT_PREFIX: Final = "bedrock"
+BEDROCK_CONVERSE_SUFFIX: Final = "/converse"
+BEDROCK_INVOKE_SUFFIX: Final = "/invoke"
+BEDROCK_CONVERSE_STREAM_SUFFIX: Final = "/converse-stream"
+BEDROCK_INVOKE_STREAM_SUFFIX: Final = "/invoke-with-response-stream"
+BEDROCK_SUFFIXES: Final = (
+    BEDROCK_CONVERSE_SUFFIX,
+    BEDROCK_INVOKE_SUFFIX,
+    BEDROCK_CONVERSE_STREAM_SUFFIX,
+    BEDROCK_INVOKE_STREAM_SUFFIX,
+)
+EVENTSTREAM_PRELUDE_BYTES: Final = 4
+EVENT_TYPE_HEADER: Final = ":event-type"
+EVENTSTREAM_HEADERS: Final[TypeAdapter[dict[str, str]]] = TypeAdapter(dict[str, str])
 OPENAI_JSON_PATHS: Final = frozenset({"/v1/chat/completions", "/v1/messages", "/v1/embeddings", "/v1/responses"})
 JSON_VALUE: Final[TypeAdapter[JsonValue]] = TypeAdapter(JsonValue)
 
@@ -145,7 +159,7 @@ def cacheable_endpoint(mount: str, method: str, url: str, body: bytes | None) ->
         return False
     path: Final = urlsplit(url).path
     if is_bedrock(mount):
-        return path.startswith("/model/") and path.endswith(("/converse", "/invoke"))
+        return path.startswith("/model/") and path.endswith(BEDROCK_SUFFIXES)
     return path in OPENAI_JSON_PATHS
 
 
@@ -176,16 +190,7 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
             return complete_responses_stream(values)
         if urlsplit(url).path == "/v1/chat/completions":
             return events[-1] == "[DONE]" and "[DONE]" not in events[:-1] and complete_chat_stream(values)
-        return (
-            "[DONE]" not in events
-            and isinstance(values[0], dict) and values[0].get("type") == "message_start"
-            and isinstance(values[-1], dict) and values[-1].get("type") == "message_stop"
-            and any(
-                isinstance(value, dict) and value.get("type") == "message_delta"
-                and isinstance(delta := value.get("delta"), dict) and isinstance(delta.get("stop_reason"), str)
-                for value in values
-            )
-        )
+        return "[DONE]" not in events and complete_anthropic_stream(values)
     try:
         value: Final = JSON_VALUE.validate_json(body)
     except ValidationError:
@@ -214,14 +219,19 @@ def complete_bedrock_response(url: str, body: bytes) -> bool:
     """Converse answers with ``output`` plus a ``stopReason``; InvokeModel on an
     Anthropic model answers the Anthropic message shape. Either way a truncated
     or error body is missing the terminator field, which is what makes it safe to
-    record. The streaming variants never reach here: they are not cacheable."""
+    record."""
+    path: Final = urlsplit(url).path
+    if path.endswith(BEDROCK_CONVERSE_STREAM_SUFFIX):
+        return complete_converse_stream(body)
+    if path.endswith(BEDROCK_INVOKE_STREAM_SUFFIX):
+        return complete_invoke_stream(body)
     try:
         value: Final = JSON_VALUE.validate_json(body)
     except ValidationError:
         return False
     if not isinstance(value, dict) or "message" in value:
         return False
-    if urlsplit(url).path.endswith("/converse"):
+    if path.endswith(BEDROCK_CONVERSE_SUFFIX):
         return isinstance(value.get("output"), dict) and isinstance(value.get("stopReason"), str)
     return (
         value.get("type") == "message"
@@ -230,6 +240,111 @@ def complete_bedrock_response(url: str, body: bytes) -> bool:
     )
 
 
+def whole_eventstream_messages(body: bytes) -> bool:
+    """Whether the body is exactly a whole number of eventstream messages.
+
+    A dropped connection is the failure this catches, and it has to be caught
+    here: botocore yields the messages it did receive and silently discards a
+    trailing partial one, so a stream cut a single byte short parses clean. Each
+    message declares its own total length in its first four bytes, so walking
+    those is enough to tell a complete body from a cut one."""
+    offset = 0  # rebind-ok: a cursor walking the declared frame lengths
+    while offset + EVENTSTREAM_PRELUDE_BYTES <= len(body):
+        total: int = int.from_bytes(body[offset : offset + EVENTSTREAM_PRELUDE_BYTES], "big")
+        if total <= 0 or offset + total > len(body):
+            return False
+        offset += total
+    return offset == len(body)
+
+
+def eventstream_events(body: bytes) -> tuple[tuple[str, JsonValue], ...] | None:
+    """The stream's (event type, decoded payload) pairs, or None if it is not a
+    complete, uncorrupted stream.
+
+    botocore validates both CRCs and raises ``ParserError`` rather than decoding
+    corruption into something plausible. A failure that began after Bedrock had
+    already answered 200 arrives as an ``exception`` frame in place of the
+    terminator, so it is the terminator rules below that reject it and this does
+    not need to inspect ``:message-type`` as well."""
+    if not body or not whole_eventstream_messages(body):
+        return None
+    buffer: Final = EventStreamBuffer()
+    buffer.add_data(body)
+    try:
+        return tuple(
+            (event_type(event.headers), JSON_VALUE.validate_json(event.payload))
+            for event in buffer
+        )
+    except (ParserError, ValidationError, ValueError):
+        return None
+
+
+def event_type(headers: object) -> str:
+    """botocore's eventstream headers come back untyped, so the one header this
+    reads is validated into a string rather than trusted."""
+    parsed: Final = EVENTSTREAM_HEADERS.validate_python(headers)
+    return parsed.get(EVENT_TYPE_HEADER, "")
+
+
+def complete_converse_stream(body: bytes) -> bool:
+    """ConverseStream ends with ``metadata``, not with ``messageStop``.
+
+    Requiring the metadata frame rather than the stop frame is deliberate: it
+    carries the token usage litellm prices the call from, so a stream cut between
+    the two still names a stop reason but would replay as a free call."""
+    events: Final = eventstream_events(body)
+    if not events or events[-1][0] != "metadata":
+        return False
+    return any(
+        event_type == "messageStop" and isinstance(payload, dict) and isinstance(payload.get("stopReason"), str)
+        for event_type, payload in events
+    )
+
+
+def complete_invoke_stream(body: bytes) -> bool:
+    """InvokeModelWithResponseStream wraps the ordinary Anthropic event grammar
+    in ``chunk`` frames, one base64 payload each, so it is held to the same
+    terminator rule as the Anthropic SSE path. A frame Bedrock sends instead of a
+    chunk, an exception among them, carries no such payload and fails the rule
+    without the frame type needing to be read."""
+    events: Final = eventstream_events(body)
+    if not events:
+        return False
+    values: Final = tuple(invoke_chunk_value(payload) for _, payload in events)
+    return all(value is not None for value in values) and complete_anthropic_stream(values)
+
+
+def invoke_chunk_value(payload: JsonValue) -> JsonValue | None:
+    """The Anthropic event inside one ``chunk`` frame, or None for a frame that
+    carries no readable one."""
+    if not isinstance(payload, dict) or not isinstance(encoded := payload.get("bytes"), str):
+        return None
+    try:
+        return JSON_VALUE.validate_json(base64.b64decode(encoded, validate=True))
+    except (ValidationError, ValueError):
+        return None
+
+
+def complete_anthropic_stream(values: tuple[JsonValue, ...]) -> bool:
+    """The Anthropic event grammar, shared by the SSE mounts and by Bedrock's
+    invoke stream, which carries the same events inside eventstream frames. A
+    ``message_delta`` naming a stop reason is what separates a finished turn from
+    one the connection cut short."""
+    if not values:
+        return False
+    first: Final = values[0]
+    last: Final = values[-1]
+    return (
+        isinstance(first, dict) and first.get("type") == "message_start"
+        and isinstance(last, dict) and last.get("type") == "message_stop"
+        and any(
+            isinstance(value, dict) and value.get("type") == "message_delta"
+            and isinstance(delta := value.get("delta"), dict) and isinstance(delta.get("stop_reason"), str)
+            for value in values
+        )
+    )
+
+
 def complete_responses_stream(values: tuple[JsonValue, ...]) -> bool:
     """The Responses API streams typed events and ends with ``response.completed``.
     A run that failed, was cancelled, or ran out of tokens ends with a different

From 4d596082deecbf414abac3ee33e465717fa1e0e7 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 16 Sep 2026 14:20:32 +0000
Subject: [PATCH 39/76] feat(guardrails): release buffered stream chunks after
 each passing scan

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../guardrail_hooks/bedrock_guardrails.py     |   3 +
 .../crowdstrike_aidr/__init__.py              |   2 +
 .../crowdstrike_aidr/crowdstrike_aidr.py      |   6 +
 .../unified_guardrail/unified_guardrail.py    |  61 ++++----
 .../guardrails/guardrail_initializers.py      |   1 +
 litellm/types/guardrails.py                   |   6 +
 .../guardrail_hooks/crowdstrike_aidr.py       |   8 +
 .../test_bedrock_guardrails.py                |   3 +
 .../guardrail_hooks/test_crowdstrike_aidr.py  |  13 ++
 .../test_streaming_buffer_until_moderated.py  | 139 +++++++++++++++++-
 10 files changed, 215 insertions(+), 27 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py b/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py
index 2c407d91a48..db68c7b5c3f 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py
@@ -248,6 +248,7 @@ class BedrockGuardrail(CustomGuardrail, BaseAWSLLM):
         streaming_buffer_until_moderated: bool | None = None,
         streaming_sampling_rate: int | None = None,
         streaming_end_of_stream_only: bool | None = None,
+        streaming_buffer_release_on_scan: bool | None = None,
         **kwargs,
     ):
         self.async_handler = get_async_httpx_client(llm_provider=httpxSpecialProvider.GuardrailCallback)
@@ -258,6 +259,7 @@ class BedrockGuardrail(CustomGuardrail, BaseAWSLLM):
                         "streaming_buffer_until_moderated": streaming_buffer_until_moderated,
                         "streaming_sampling_rate": streaming_sampling_rate,
                         "streaming_end_of_stream_only": streaming_end_of_stream_only,
+                        "streaming_buffer_release_on_scan": streaming_buffer_release_on_scan,
                     }
                 )
             )
@@ -321,6 +323,7 @@ class BedrockGuardrail(CustomGuardrail, BaseAWSLLM):
         self.streaming_buffer_until_moderated = streaming_params.streaming_buffer_until_moderated
         self.streaming_sampling_rate = streaming_params.streaming_sampling_rate
         self.streaming_end_of_stream_only = streaming_params.streaming_end_of_stream_only
+        self.streaming_buffer_release_on_scan = streaming_params.streaming_buffer_release_on_scan
 
     def update_in_memory_litellm_params(self, litellm_params: LitellmParams) -> None:
         super().update_in_memory_litellm_params(litellm_params)
diff --git a/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/__init__.py b/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/__init__.py
index c88e6e97a96..59f02817e5f 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/__init__.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/__init__.py
@@ -23,6 +23,8 @@ def initialize_guardrail(litellm_params: "LitellmParams", guardrail: "Guardrail"
         event_hook=litellm_params.mode,
         default_on=litellm_params.default_on,
         fail_on_error=litellm_params.fail_on_error,
+        streaming_buffer_until_moderated=streaming_params.streaming_buffer_until_moderated,
+        streaming_buffer_release_on_scan=streaming_params.streaming_buffer_release_on_scan,
         streaming_end_of_stream_only=streaming_params.streaming_end_of_stream_only,
         streaming_sampling_rate=streaming_params.streaming_sampling_rate,
     )
diff --git a/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py b/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py
index 8fed1f906e5..924bbd2bc1a 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/crowdstrike_aidr/crowdstrike_aidr.py
@@ -260,6 +260,8 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
         api_key: str | None = None,
         api_base: str | None = None,
         fail_on_error: bool | None = True,
+        streaming_buffer_until_moderated: bool | None = None,
+        streaming_buffer_release_on_scan: bool | None = None,
         streaming_end_of_stream_only: bool | None = None,
         streaming_sampling_rate: int | None = None,
         async_handler: AsyncHTTPHandler | None = None,
@@ -287,6 +289,8 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
             CrowdStrikeAIDRGuardrailConfigModelOptionalParams(
                 streaming_end_of_stream_only=streaming_end_of_stream_only,
                 streaming_sampling_rate=streaming_sampling_rate,
+                streaming_buffer_until_moderated=streaming_buffer_until_moderated,
+                streaming_buffer_release_on_scan=streaming_buffer_release_on_scan,
             )
         )
 
@@ -310,6 +314,8 @@ class CrowdStrikeAIDRHandler(CustomGuardrail):
         )
 
     def _set_streaming_params(self, streaming_params: CrowdStrikeAIDRGuardrailConfigModelOptionalParams) -> None:
+        self.streaming_buffer_until_moderated: bool = streaming_params.streaming_buffer_until_moderated or False
+        self.streaming_buffer_release_on_scan: bool = streaming_params.streaming_buffer_release_on_scan or False
         self.streaming_end_of_stream_only: bool = streaming_params.streaming_end_of_stream_only or False
         self.streaming_sampling_rate: int = streaming_params.streaming_sampling_rate or 5
 
diff --git a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
index ee5cd7c4cb8..f231ac68c6a 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
@@ -956,6 +956,7 @@ class UnifiedLLMGuardrails(CustomLogger):
         buffer_until_moderated: bool = _streaming_flag(
             "streaming_buffer_until_moderated", buffer_until_moderated_default
         )
+        release_on_scan: bool = _streaming_flag("streaming_buffer_release_on_scan", False)
 
         if (
             buffer_until_moderated
@@ -972,7 +973,7 @@ class UnifiedLLMGuardrails(CustomLogger):
 
         # Buffering can only moderate the assembled response, so it always
         # defers to end-of-stream.
-        if buffer_until_moderated:
+        if buffer_until_moderated and not release_on_scan:
             end_of_stream_only = True
 
         if guardrail_to_apply is None:
@@ -1026,6 +1027,7 @@ class UnifiedLLMGuardrails(CustomLogger):
         chunk_counter = 0
         responses_so_far: Final[list[object]] = []
         responses_yielded: Final[list[object]] = []
+        withheld_items: Final[list[object]] = []  # mutable-ok: streaming window must be released incrementally
         pending_end_of_stream_items: Final[list[object]] = []
         # Whether any real response chunk has been forwarded to the client.
         # Drives how a block terminates the stream: continue the in-progress
@@ -1069,9 +1071,13 @@ class UnifiedLLMGuardrails(CustomLogger):
                         chunks_yielded = True
                         responses_yielded.append(item)
                         yield item
+                else:
+                    withheld_items.append(item)
                 continue
 
             # Process chunk based on sampling rate
+            if buffer_until_moderated:
+                withheld_items.append(item)
             if chunk_counter % sampling_rate == 0:
                 endpoint_translation = mappings[CallTypes(call_type)]()
                 scan_key = endpoint_translation.get_streaming_scan_key(responses_so_far)
@@ -1081,9 +1087,16 @@ class UnifiedLLMGuardrails(CustomLogger):
                         chunk_counter,
                         guardrail_to_apply.guardrail_name,
                     )
-                    chunks_yielded = True
-                    responses_yielded.append(item)
-                    yield item
+                    if buffer_until_moderated:
+                        for withheld_item in withheld_items:
+                            chunks_yielded = True
+                            responses_yielded.append(withheld_item)
+                            yield withheld_item
+                        withheld_items.clear()
+                    else:
+                        chunks_yielded = True
+                        responses_yielded.append(item)
+                        yield item
                     continue
 
                 verbose_proxy_logger.debug(
@@ -1093,13 +1106,9 @@ class UnifiedLLMGuardrails(CustomLogger):
                     guardrail_to_apply.guardrail_name,
                 )
 
-                # Deep-copy the current chunk before guardrail processing.
-                # process_output_streaming_response modifies responses_so_far
-                # in-place: it puts the combined guardrailed text in the first
-                # chunk and clears all subsequent chunks to "". Without this
-                # copy, yielding processed_items[-1] would yield an empty
-                # string, permanently losing this chunk's content.
-                original_item = copy.deepcopy(item)
+                original_items = (
+                    tuple(copy.deepcopy(withheld_items)) if buffer_until_moderated else (copy.deepcopy(item),)
+                )
 
                 try:
                     await endpoint_translation.process_output_streaming_response(
@@ -1144,13 +1153,16 @@ class UnifiedLLMGuardrails(CustomLogger):
                     return
                 if scan_key is not None:
                     last_scan_key = scan_key
-                chunks_yielded = True
-                responses_yielded.append(original_item)
-                yield original_item
+                for original_item in original_items:
+                    chunks_yielded = True
+                    responses_yielded.append(original_item)
+                    yield original_item
+                withheld_items.clear()
             else:
-                chunks_yielded = True
-                responses_yielded.append(item)
-                yield item
+                if not buffer_until_moderated:
+                    chunks_yielded = True
+                    responses_yielded.append(item)
+                    yield item
 
         # Stream has ended - do final processing with all collected chunks
         if call_type is not None and CallTypes(call_type) in mappings:
@@ -1162,14 +1174,13 @@ class UnifiedLLMGuardrails(CustomLogger):
 
             endpoint_translation = mappings[CallTypes(call_type)]()
 
-            # When buffering, snapshot the original chunks before moderation.
-            # A shallow copy suffices: end-of-stream
-            # process_output_streaming_response builds a separate assembled
-            # response (it does not mutate the individual chunks in place), and
-            # the chunks themselves are replayed verbatim -- so we only need to
-            # preserve the list, not clone every chunk (deepcopy would double
-            # peak memory for large responses).
-            buffered_items: Final = list(responses_so_far) if buffer_until_moderated else None
+            buffered_items: Final = (
+                tuple(copy.deepcopy(withheld_items))
+                if buffer_until_moderated and release_on_scan and not end_of_stream_only
+                else tuple(withheld_items)
+                if buffer_until_moderated
+                else None
+            )
             end_scan_key: Final = endpoint_translation.get_streaming_scan_key(responses_so_far)
             if _is_redundant_scan(end_scan_key, last_scan_key):
                 verbose_proxy_logger.debug(
diff --git a/litellm/proxy/guardrails/guardrail_initializers.py b/litellm/proxy/guardrails/guardrail_initializers.py
index 7858adeb55d..5dc9af2c081 100644
--- a/litellm/proxy/guardrails/guardrail_initializers.py
+++ b/litellm/proxy/guardrails/guardrail_initializers.py
@@ -44,6 +44,7 @@ def initialize_bedrock(litellm_params: LitellmParams, guardrail: Guardrail):
         streaming_buffer_until_moderated=streaming_params.streaming_buffer_until_moderated,
         streaming_sampling_rate=streaming_params.streaming_sampling_rate,
         streaming_end_of_stream_only=streaming_params.streaming_end_of_stream_only,
+        streaming_buffer_release_on_scan=streaming_params.streaming_buffer_release_on_scan,
     )
     litellm.logging_callback_manager.add_litellm_callback(_bedrock_callback)
     return _bedrock_callback
diff --git a/litellm/types/guardrails.py b/litellm/types/guardrails.py
index 92fe41ba717..6346e13f3ba 100644
--- a/litellm/types/guardrails.py
+++ b/litellm/types/guardrails.py
@@ -682,6 +682,12 @@ class BedrockGuardrailStreamingParams(BaseModel):
         "and the scan result lands in guardrail_information; a flagged response still ends the "
         "stream with a block message (disable_exception_on_block=true) or an error frame.",
     )
+    streaming_buffer_release_on_scan: bool = Field(
+        default=False,
+        description="When buffering, scan the accumulated response every streaming_sampling_rate chunks "
+        "and release the withheld chunks once the scan passes, instead of holding everything to end of stream. "
+        "Flagged content is never released. Ignored when streaming_end_of_stream_only is true.",
+    )
 
     @classmethod
     def from_extras(cls, extras: Mapping[str, object] | None) -> "BedrockGuardrailStreamingParams":
diff --git a/litellm/types/proxy/guardrails/guardrail_hooks/crowdstrike_aidr.py b/litellm/types/proxy/guardrails/guardrail_hooks/crowdstrike_aidr.py
index 6beca030a3a..df1caab6af6 100644
--- a/litellm/types/proxy/guardrails/guardrail_hooks/crowdstrike_aidr.py
+++ b/litellm/types/proxy/guardrails/guardrail_hooks/crowdstrike_aidr.py
@@ -4,6 +4,14 @@ from .base import GuardrailConfigModel
 
 
 class CrowdStrikeAIDRGuardrailConfigModelOptionalParams(BaseModel):
+    streaming_buffer_until_moderated: bool | None = Field(
+        default=None,
+        description="When True, withhold streamed chunks until moderation passes. Defaults to False when unset.",
+    )
+    streaming_buffer_release_on_scan: bool | None = Field(
+        default=None,
+        description="When buffering, release withheld chunks after each passing scan. Defaults to False when unset.",
+    )
     streaming_end_of_stream_only: bool | None = Field(
         default=None,
         description="If False (default when unset), post_call scans the accumulated streamed response every "
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py
index d173c5f5c70..dc275c912c8 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py
@@ -5603,6 +5603,7 @@ def test_initialize_bedrock_wires_streaming_flags():
             streaming_buffer_until_moderated=False,
             streaming_sampling_rate=3,
             streaming_end_of_stream_only=True,
+            streaming_buffer_release_on_scan=True,
         ),
         {"guardrail_name": "bedrock-streaming"},
     )
@@ -5616,9 +5617,11 @@ def test_initialize_bedrock_wires_streaming_flags():
     assert configured.streaming_buffer_until_moderated is False
     assert configured.streaming_sampling_rate == 3
     assert configured.streaming_end_of_stream_only is True
+    assert configured.streaming_buffer_release_on_scan is True
     assert defaulted.streaming_buffer_until_moderated is True
     assert defaulted.streaming_sampling_rate == 5
     assert defaulted.streaming_end_of_stream_only is False
+    assert defaulted.streaming_buffer_release_on_scan is False
 
 
 def test_initialize_bedrock_rejects_non_positive_sampling_rate():
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_crowdstrike_aidr.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_crowdstrike_aidr.py
index 9849ad7ec88..a1aae119d56 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_crowdstrike_aidr.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_crowdstrike_aidr.py
@@ -1622,10 +1622,23 @@ def test_initialize_guardrail_rejects_unsupported_mode_instead_of_running_other_
 def test_initialize_guardrail_defaults_streaming_params() -> None:
     handler = _initialize_from_config(mode="post_call")
 
+    assert handler.streaming_buffer_until_moderated is False
+    assert handler.streaming_buffer_release_on_scan is False
     assert handler.streaming_end_of_stream_only is False
     assert handler.streaming_sampling_rate == 5
 
 
+def test_initialize_guardrail_forwards_buffer_streaming_params() -> None:
+    handler = _initialize_from_config(
+        mode="post_call",
+        streaming_buffer_until_moderated=True,
+        streaming_buffer_release_on_scan=True,
+    )
+
+    assert handler.streaming_buffer_until_moderated is True
+    assert handler.streaming_buffer_release_on_scan is True
+
+
 @pytest.mark.parametrize(
     "configured",
     [
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
index 2b163ee5233..89d51866533 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
@@ -11,7 +11,7 @@ released unchanged after moderation passes.
 """
 
 import json
-from typing import Any, List, Literal, Optional
+from typing import Any, AsyncGenerator, List, Literal, Optional
 
 import pytest
 
@@ -23,7 +23,7 @@ from litellm.proxy._types import UserAPIKeyAuth
 from litellm.proxy.guardrails.guardrail_hooks.unified_guardrail.unified_guardrail import (
     UnifiedLLMGuardrails,
 )
-from litellm.types.utils import GenericGuardrailAPIInputs
+from litellm.types.utils import Delta, GenericGuardrailAPIInputs, ModelResponseStream, StreamingChoices
 
 BLOCK_MESSAGE = "Blocked by policy: this response was withheld."
 ORIGINAL_MARKER = "ORIGINAL-SECRET-ANSWER"
@@ -60,6 +60,41 @@ class _PassingGuardrail(CustomGuardrail):
         return inputs
 
 
+class _CountingPassingGuardrail(_PassingGuardrail):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.scan_count = 0
+
+    async def apply_guardrail(
+        self,
+        inputs: GenericGuardrailAPIInputs,
+        request_data: dict,
+        input_type: Literal["request", "response"],
+        logging_obj: Optional[Any] = None,
+    ) -> GenericGuardrailAPIInputs:
+        self.scan_count += 1
+        return inputs
+
+
+class _SecondScanBlockingGuardrail(_CountingPassingGuardrail):
+    async def apply_guardrail(
+        self,
+        inputs: GenericGuardrailAPIInputs,
+        request_data: dict,
+        input_type: Literal["request", "response"],
+        logging_obj: Optional[Any] = None,
+    ) -> GenericGuardrailAPIInputs:
+        self.scan_count += 1
+        if self.scan_count == 2:
+            raise ModifyResponseException(
+                message=BLOCK_MESSAGE,
+                model="gpt-4",
+                request_data=request_data,
+                guardrail_name=self.guardrail_name,
+            )
+        return inputs
+
+
 def _sse_event(event_type: str, data: dict) -> bytes:
     return f"event: {event_type}\ndata: {json.dumps(data)}\n\n".encode()
 
@@ -115,6 +150,67 @@ def _decode(chunks: List[Any]) -> str:
     return "".join(c.decode() if isinstance(c, bytes) else str(c) for c in chunks)
 
 
+def _chat_chunk(content: str = "", finish_reason: str | None = None) -> ModelResponseStream:
+    return ModelResponseStream(
+        id="chatcmpl-windowed",
+        created=1724900000,
+        model="gpt-4",
+        choices=[
+            StreamingChoices(
+                index=0,
+                delta=Delta(role="assistant", content=content),
+                finish_reason=finish_reason,
+            )
+        ],
+    )
+
+
+async def _windowed_chat_stream(
+    yielded_count: List[int], collected: List[Any], content_chunks: List[str]
+) -> AsyncGenerator[ModelResponseStream, None]:
+    for content in content_chunks:
+        yielded_count.append(len(collected))
+        yield _chat_chunk(content)
+    yielded_count.append(len(collected))
+    yield _chat_chunk(finish_reason="stop")
+
+
+async def _run_windowed(
+    guardrail: CustomGuardrail,
+    content_chunks: List[str],
+    end_of_stream_only: bool = False,
+) -> tuple[List[Any], List[int]]:
+    guardrail.streaming_buffer_until_moderated = True
+    guardrail.streaming_buffer_release_on_scan = True
+    guardrail.streaming_end_of_stream_only = end_of_stream_only
+    guardrail.streaming_sampling_rate = 2
+    unified = UnifiedLLMGuardrails()
+    user_api_key_dict = UserAPIKeyAuth(api_key="test", request_route="/v1/chat/completions")
+    request_data = {
+        "messages": [{"role": "user", "content": "hi"}],
+        "guardrail_to_apply": guardrail,
+        "metadata": {"guardrails": [guardrail.guardrail_name]},
+    }
+    collected: List[Any] = []
+    yielded_count: List[int] = []
+    async for chunk in unified.async_post_call_streaming_iterator_hook(
+        user_api_key_dict=user_api_key_dict,
+        response=_windowed_chat_stream(yielded_count, collected, content_chunks),
+        request_data=request_data,
+    ):
+        collected.append(chunk)
+    return collected, yielded_count
+
+
+def _chat_text(chunks: List[Any]) -> str:
+    return "".join(
+        choice.delta.content or ""
+        for chunk in chunks
+        if isinstance(chunk, ModelResponseStream)
+        for choice in chunk.choices
+    )
+
+
 async def _run(guardrail: CustomGuardrail) -> str:
     # Rubrik's real config: end-of-stream-only moderation. Without buffering
     # this releases every chunk before moderation runs (content leaks on
@@ -159,6 +255,45 @@ async def test_buffered_clean_releases_all_content():
     assert BLOCK_MESSAGE not in raw
 
 
+@pytest.mark.asyncio
+async def test_windowed_buffer_releases_after_each_passing_scan():
+    guardrail = _CountingPassingGuardrail(guardrail_name="windowed-pass", event_hook="post_call")
+    content_chunks = ["one ", "two ", "three ", "four ", "five ", "six "]
+
+    collected, yielded_count = await _run_windowed(guardrail, content_chunks)
+
+    assert yielded_count[2] >= 2
+    assert yielded_count == [0, 0, 2, 2, 4, 4, 6]
+    assert _chat_text(collected) == "".join(content_chunks)
+    assert guardrail.scan_count > 1
+
+
+@pytest.mark.asyncio
+async def test_windowed_buffer_drops_blocked_window():
+    guardrail = _SecondScanBlockingGuardrail(guardrail_name="windowed-block", event_hook="post_call")
+    content_chunks = ["one ", "two ", "MARKER ", "four ", "five ", "six "]
+
+    collected, _ = await _run_windowed(guardrail, content_chunks)
+    raw = _decode(collected)
+
+    assert _chat_text(collected) == "one two "
+    assert "MARKER" not in raw
+    assert BLOCK_MESSAGE in raw
+    assert '"error"' not in raw
+
+
+@pytest.mark.asyncio
+async def test_windowed_buffer_with_explicit_end_of_stream_only_stays_fully_buffered():
+    guardrail = _CountingPassingGuardrail(guardrail_name="windowed-eos", event_hook="post_call")
+    content_chunks = ["one ", "two ", "three ", "four ", "five ", "six "]
+
+    collected, yielded_count = await _run_windowed(guardrail, content_chunks, end_of_stream_only=True)
+
+    assert yielded_count == [0, 0, 0, 0, 0, 0, 0]
+    assert _chat_text(collected) == "".join(content_chunks)
+    assert guardrail.scan_count == 1
+
+
 @pytest.mark.asyncio
 async def test_buffered_mode_disabled_for_content_rewriting_guardrail():
     """Buffered replay yields the withheld *original* chunks verbatim, which

From e64552867a1a3efd3f1ca88b94d94b5a982f8727 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Wed, 16 Sep 2026 14:21:36 +0000
Subject: [PATCH 40/76] refactor(guardrails): drop stale buffering comment

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../guardrail_hooks/unified_guardrail/unified_guardrail.py      | 2 --
 1 file changed, 2 deletions(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
index f231ac68c6a..70dc6eec24c 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
@@ -971,8 +971,6 @@ class UnifiedLLMGuardrails(CustomLogger):
             )
             buffer_until_moderated = False
 
-        # Buffering can only moderate the assembled response, so it always
-        # defers to end-of-stream.
         if buffer_until_moderated and not release_on_scan:
             end_of_stream_only = True
 

From 8a553ceb58887c8aa2aa24c7cfb75ce662d2e321 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 07:38:44 -0700
Subject: [PATCH 41/76] feat(e2e): mount Gemini on the provider cache

Gemini needs none of the machinery Bedrock needed. litellm composes
{api_base}/models/{model}:{endpoint} from a custom api_base, so a plain
path-prefixed mount reaches it, and the credential travels as a static
x-goog-api-key header that no host rewrite invalidates. Nothing is
re-signed and nothing leaves the cache key, so a recording still cannot
cross credentials.

A finished turn names a finishReason on every candidate and reports
usageMetadata. The reason is read as a string rather than compared to
STOP: MAX_TOKENS and the safety reasons end a turn just as finally, and
rejecting them would send every one of them upstream forever. Streaming
is the half worth care. Gemini repeats usageMetadata on every chunk and
names a finishReason only on the last, so the terminator is the final
event rather than any event, and a stream the connection cut short ends
on a chunk carrying usage and no reason.

The mount's upstream base carries the API version, so the path the rules
see is /v1beta/models/..., not the one the proxy sent. The first version
of this anchored the rule at the start of that path, which passed every
test against a stub with no version prefix and would have cached nothing
at all in a real run. Caught by replaying the rules over responses
captured from live gemini-2.5-flash, which is also why the tests now
mount their stub under the version prefix.

Vertex stays unmounted and is a separate provider here: litellm grafts
the default Vertex path onto an api_base only when that api_base has no
path of its own, so Vertex needs a root-mounted edge on its own port.
---
 .../test_provider_cache.py                    | 154 +++++++++++++++++-
 tests/e2e/PROVIDER_CACHE.md                   |  16 +-
 tests/e2e/provider_cache.py                   |  46 ++++++
 tests/e2e/provider_cache_routing.py           |   3 +-
 tests/e2e/provider_edge.py                    |   1 +
 5 files changed, 215 insertions(+), 5 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 4c131434ecd..520317a0678 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -861,7 +861,7 @@ def test_anthropic_stream_requires_start_finish_and_stop() -> None:
     assert not successful_response("anthropic", url, 200, headers, start + finish)
 
 
-@pytest.mark.parametrize("provider,suffix", [("openai", "/v1"), ("anthropic", "")])
+@pytest.mark.parametrize("provider,suffix", [("openai", "/v1"), ("anthropic", ""), ("gemini", "")])
 def test_normal_registration_routes_supported_providers(provider: str, suffix: str) -> None:
     params: Final = LiteLLMParamsBody(model=f"{provider}/test", api_key="os.environ/SYNTHETIC_KEY", timeout=12)
     routed: Final = route_cache_model(params, lambda mount: f"http://edge.invalid/{mount}", enabled=True)
@@ -873,6 +873,8 @@ def test_normal_registration_routes_supported_providers(provider: str, suffix: s
 @pytest.mark.parametrize("params", [
     LiteLLMParamsBody(model="bedrock/test"),
     LiteLLMParamsBody(model="azure/test"),
+    LiteLLMParamsBody(model="vertex_ai/gemini-2.5-flash"),
+    LiteLLMParamsBody(model="gemini/gemini-2.5-flash", api_base="https://custom.invalid"),
     LiteLLMParamsBody(model="openai/test", api_base="https://custom.invalid/v1"),
     LiteLLMParamsBody(model="openai/test", api_base=""),
     LiteLLMParamsBody(model="openai/test", litellm_credential_name="named-credential"),
@@ -1241,3 +1243,153 @@ class TestBedrockStreams:
 
     def test_a_stream_that_errored_before_it_started_is_not_recordable(self) -> None:
         assert not successful_response(BEDROCK_MOUNT, CONVERSE_STREAM_URL, 503, {}, CONVERSE_STREAM_OK)
+
+
+GEMINI_MODEL: Final = "gemini-2.5-flash"
+GEMINI_API_VERSION: Final = "/v1beta"
+GEMINI_GENERATE_PATH: Final = f"/models/{GEMINI_MODEL}:generateContent"
+GEMINI_STREAM_PATH: Final = f"/models/{GEMINI_MODEL}:streamGenerateContent"
+GEMINI_USAGE: Final = {"promptTokenCount": 7, "candidatesTokenCount": 1, "totalTokenCount": 25}
+
+
+def gemini_body(finish_reason: str | None, usage: bool = True, candidates: bool = True) -> JsonValue:
+    candidate: Final[dict[str, JsonValue]] = {"content": {"parts": [{"text": "OK"}], "role": "model"}, "index": 0}
+    return {
+        "candidates": [{**candidate, "finishReason": finish_reason} if finish_reason else candidate]
+        if candidates else [],
+        **({"usageMetadata": GEMINI_USAGE} if usage else {}),
+        "modelVersion": GEMINI_MODEL,
+    }
+
+
+def gemini_unary(finish_reason: str | None = "STOP", usage: bool = True, candidates: bool = True) -> bytes:
+    return json.dumps(gemini_body(finish_reason, usage, candidates)).encode()
+
+
+def gemini_stream(*finish_reasons: str | None) -> bytes:
+    return b"".join(
+        b"data: " + json.dumps(gemini_body(reason)).encode() + b"\r\n\r\n" for reason in finish_reasons
+    )
+
+
+@contextmanager
+def gemini_edge(cache: CacheEdge, provider: Provider, path: str) -> Generator[str, None, None]:
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}{GEMINI_API_VERSION}"
+    running: Final = start_provider_edge(cache, mounts={"gemini": upstream})
+    try:
+        yield running.edge.api_base("gemini") + path
+    finally:
+        running.shutdown()
+
+
+class TestGemini:
+    """Gemini reaches the edge by path prefix alone: litellm composes
+    `{api_base}/models/{model}:{endpoint}` and sends a static `x-goog-api-key`,
+    so nothing has to be re-signed and nothing leaves the cache key. The response
+    grammar is its own though, and the streaming one is the interesting half: every
+    chunk repeats `usageMetadata`, so only `finishReason` on the last chunk
+    separates a finished turn from a dropped connection."""
+
+    @pytest.mark.parametrize("path,response", [
+        (GEMINI_GENERATE_PATH, gemini_unary()),
+        (GEMINI_STREAM_PATH, gemini_stream(None, None, "STOP")),
+    ], ids=["generate", "stream"])
+    def test_a_finished_turn_replays_on_the_next_run(
+        self, store: RedisResponseStore, provider: Provider, path: str, response: bytes,
+    ) -> None:
+        provider.stream = path == GEMINI_STREAM_PATH
+        provider.response = response
+        for _ in range(2):
+            with gemini_edge(cache_edge(store), provider, path) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 1
+
+    @pytest.mark.parametrize("reason", ["MAX_TOKENS", "SAFETY", "RECITATION"])
+    def test_a_turn_the_provider_ended_for_its_own_reasons_is_still_finished(
+        self, store: RedisResponseStore, provider: Provider, reason: str,
+    ) -> None:
+        """Reading `finishReason` as a string rather than comparing it to STOP is
+        deliberate. A turn cut off by the token limit or a safety filter is over,
+        and rejecting those would send every one of them upstream forever."""
+        provider.response = gemini_unary(reason)
+        for _ in range(2):
+            with gemini_edge(cache_edge(store), provider, GEMINI_GENERATE_PATH) as url:
+                assert call(url, MARKED).body == provider.response
+        assert len(provider.hits) == 1
+
+    @pytest.mark.parametrize("response", [
+        gemini_unary(None),
+        gemini_unary("STOP", usage=False),
+        gemini_unary("STOP", candidates=False),
+        b'{"error":{"code":400,"message":"API key not valid","status":"INVALID_ARGUMENT"}}',
+    ], ids=["no-finish-reason", "no-usage", "no-candidates", "error-body"])
+    def test_an_unfinished_or_failed_turn_never_enters_the_cache(
+        self, store: RedisResponseStore, provider: Provider, response: bytes,
+    ) -> None:
+        provider.response = response
+        for _ in range(2):
+            with gemini_edge(cache_edge(store), provider, GEMINI_GENERATE_PATH) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 2
+
+    @pytest.mark.parametrize("response", [
+        gemini_stream(None, None),
+        gemini_stream("STOP", None),
+        gemini_stream(),
+    ], ids=["cut-before-the-reason", "reason-then-another-chunk", "empty"])
+    def test_a_stream_that_never_named_a_reason_calls_the_provider_every_time(
+        self, store: RedisResponseStore, provider: Provider, response: bytes,
+    ) -> None:
+        provider.stream = True
+        provider.response = response
+        for _ in range(2):
+            with gemini_edge(cache_edge(store), provider, GEMINI_STREAM_PATH) as url:
+                assert call(url, MARKED).body == response
+        assert len(provider.hits) == 2
+
+    def test_a_response_whose_candidates_did_not_all_finish_is_not_recordable(
+        self, store: RedisResponseStore, provider: Provider,
+    ) -> None:
+        """A request for more than one candidate is answered by more than one, and
+        the turn is over only when every one of them names a reason. Holding the
+        whole list to that rule rather than its first entry is what keeps a
+        half-finished answer from being stored and replayed as a finished one."""
+        finished: Final = json.loads(gemini_unary("STOP"))["candidates"][0]
+        unfinished: Final = json.loads(gemini_unary(None))["candidates"][0]
+        provider.response = json.dumps(
+            {"candidates": [finished, {**unfinished, "index": 1}], "usageMetadata": GEMINI_USAGE}
+        ).encode()
+        for _ in range(2):
+            with gemini_edge(cache_edge(store), provider, GEMINI_GENERATE_PATH) as url:
+                assert call(url, MARKED).body == provider.response
+        assert len(provider.hits) == 2
+
+    @pytest.mark.parametrize("path,cacheable", [
+        (GEMINI_GENERATE_PATH, True),
+        (GEMINI_STREAM_PATH, True),
+        (f"/models/{GEMINI_MODEL}:countTokens", False),
+        (f"/models/{GEMINI_MODEL}:embedContent", False),
+        ("/v1/chat/completions", False),
+        (f"/files/{GEMINI_MODEL}:generateContent", False),
+    ])
+    @pytest.mark.parametrize("version", ["", GEMINI_API_VERSION], ids=["bare", "versioned"])
+    def test_only_the_generate_endpoints_are_cacheable(self, version: str, path: str, cacheable: bool) -> None:
+        """The mount's upstream base carries the API version, so the path the cache
+        sees is the upstream one and starts `/v1beta`. A rule anchored at the start
+        of the path would pass every test against a stub with no version prefix and
+        then cache nothing at all in a real run."""
+        assert cacheable_endpoint("gemini", "POST", f"https://gemini.invalid{version}{path}", MARKED) is cacheable
+
+    def test_the_bodies_these_tests_build_match_a_real_gemini_response(self) -> None:
+        """The shapes above are hand-built so a test can express the turn it means.
+        This holds them to the fields a live `generativelanguage.googleapis.com`
+        answer carries, captured 2026-09-16 against gemini-2.5-flash."""
+        captured: Final = json.loads(
+            '{"candidates":[{"content":{"parts":[{"text":"OK"}],"role":"model"},"finishReason":"STOP",'
+            '"index":0}],"usageMetadata":{"promptTokenCount":7,"candidatesTokenCount":1,'
+            '"totalTokenCount":25},"modelVersion":"gemini-2.5-flash","responseId":"1J6qauKFI8ut1MkPgNjI4AI"}'
+        )
+        built: Final = json.loads(gemini_unary())
+        assert captured.keys() >= built.keys()
+        assert captured["candidates"][0].keys() >= built["candidates"][0].keys()
+        assert successful_response("gemini", GEMINI_GENERATE_PATH, 200, {}, json.dumps(captured).encode())
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 29d6e5ab4f2..e2f8030074d 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -1,13 +1,23 @@
 # Shared provider-response cache
 
-`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge, as do Anthropic-on-Bedrock registrations that carry no AWS identity of their own. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
+`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI, Anthropic and Gemini model registrations use the provider edge, as do Anthropic-on-Bedrock registrations that carry no AWS identity of their own. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
 
-The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, SSE streams included, and for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
+The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, SSE streams included, for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount, and for `models/{model}:generateContent` and `:streamGenerateContent` on the Gemini mount. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
 
 Bedrock's streaming endpoints, `converse-stream` and `invoke-with-response-stream`, cache too. AWS frames those as binary `vnd.amazon.eventstream` rather than SSE, so botocore's own parser reads the frames and validates both CRCs, and each endpoint is then held to its terminal grammar. That matters more than the endpoint count suggests: the Claude Code compat cells drive the real CLI, which always streams, so streaming is most of the suite's Bedrock traffic
 
 Two details of that rule are worth knowing before changing it. A ConverseStream ends with `metadata`, not with `messageStop`, and the `metadata` frame is what carries the token usage litellm prices the call from, so the rule requires it: a stream cut between the two still names a stop reason but would replay as a free call. And a dropped connection is invisible to the parser, which yields the frames it did receive and silently discards a trailing partial one, so the body is also checked against the frame lengths it declares. A stream cut one byte short parses clean and has to be caught that way
 
+## Gemini
+
+Gemini needs nothing that Bedrock needed. litellm composes `{api_base}/models/{model}:{endpoint}` from a custom api_base, so a path-prefixed mount reaches it, and the credential travels as a static `x-goog-api-key` header that no host rewrite invalidates. Nothing is re-signed and nothing is excluded from the key, so a recording still cannot cross credentials
+
+The mount's upstream base carries the API version, which is the one detail worth remembering: the path the cache rules see is the upstream one, `/v1beta/models/...`, not the one the proxy sent. A rule anchored at the start of that path would look right against a local stub and then cache nothing at all in a real run
+
+A finished turn names a `finishReason` on every candidate and reports `usageMetadata`. The reason is read as a string rather than compared to `STOP`, because `MAX_TOKENS` and the safety reasons end a turn just as finally and rejecting them would send every one of them upstream forever. Streaming is the more interesting half: Gemini repeats `usageMetadata` on every chunk and names a `finishReason` only on the last one, so the terminator is the final event rather than any event, and a stream the connection cut short ends on a chunk with usage and no reason
+
+Vertex is not mounted. litellm grafts the default Vertex path onto an api_base only when that api_base has no path of its own, so a Vertex mount needs a root-mounted edge on its own port rather than a path prefix. Gemini and Vertex are separate providers in litellm and the Gemini mount does not cover Vertex deployments
+
 ## Request identity
 
 A recording belongs to one test. The key is a keyed digest over the test's node id, the method, the URL, the effective outbound headers (including authentication and HTTP-library defaults), body presence and the body bytes, with one normalization: a 12-hex-digit run, the shape `unique_marker()` mints, is replaced by a placeholder in both the URL and a UTF-8 body. Nothing else is normalized away. No prompts, JSON values or credentials are rewritten, and the rule is the one `fixture_canonical.py` already applies for record/replay, so there is a single definition of what a marker is
@@ -30,7 +40,7 @@ Only deployments that carry no AWS identity of their own route to the edge. A de
 
 Which models route is an explicit allowlist in `provider_cache_routing.py`, mirroring the runner role's IAM policy, which names its models one by one. That coupling is deliberate: the edge re-signs with the run pod's identity, so a model the role cannot invoke comes back 403 from Bedrock rather than falling back. An unlisted model keeps its direct path and loses only caching, so adding a Bedrock model to the suite can never turn it red. Adding one to the edge is a policy edit in litellm-ops plus a line here
 
-Vertex and Gemini are not mounted. litellm's `_check_custom_proxy` rewrites a path-prefixed Vertex `api_base` into `{api_base}:{endpoint}`, dropping project, location and model, so a mount under a path prefix cannot work without either a root-mounted edge on its own port or a change in litellm
+Vertex is not mounted. litellm's `_check_custom_proxy` rewrites a path-prefixed Vertex `api_base` into `{api_base}:{endpoint}`, dropping project, location and model, so a mount under a path prefix cannot work without either a root-mounted edge on its own port or a change in litellm. Gemini is a separate provider there and does have a working path-prefixed form, so it is mounted; see the Gemini section
 
 Recordings are shared across workers and builds through dedicated Redis, separate from the candidate's own cache. They expire 86,400 seconds after capture starts, based on Redis time. Reads never extend expiry. There is no scheduled recapture: the next miss calls the provider again. Bounded coordination reduces duplicate concurrent calls, but slow or failed captures may lead to extra live calls after the wait expires
 
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 9ae89861f63..7bba93321b5 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -37,6 +37,10 @@ SIGNATURE_HEADERS: Final = frozenset(
     {"authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"}
 )
 BEDROCK_MOUNT_PREFIX: Final = "bedrock"
+GEMINI_MOUNT: Final = "gemini"
+GEMINI_MODELS_SEGMENT: Final = "/models"
+GEMINI_GENERATE_SUFFIX: Final = ":generateContent"
+GEMINI_STREAM_SUFFIX: Final = ":streamGenerateContent"
 BEDROCK_CONVERSE_SUFFIX: Final = "/converse"
 BEDROCK_INVOKE_SUFFIX: Final = "/invoke"
 BEDROCK_CONVERSE_STREAM_SUFFIX: Final = "/converse-stream"
@@ -154,12 +158,21 @@ def is_bedrock(mount: str) -> bool:
     return mount.partition("/")[0] == BEDROCK_MOUNT_PREFIX
 
 
+def is_gemini(mount: str) -> bool:
+    return mount == GEMINI_MOUNT
+
+
 def cacheable_endpoint(mount: str, method: str, url: str, body: bytes | None) -> bool:
     if method != "POST" or body is None or len(body) > MAX_REQUEST_BYTES:
         return False
     path: Final = urlsplit(url).path
     if is_bedrock(mount):
         return path.startswith("/model/") and path.endswith(BEDROCK_SUFFIXES)
+    if is_gemini(mount):
+        collection, _, resource = path.rpartition("/")
+        return collection.endswith(GEMINI_MODELS_SEGMENT) and resource.endswith(
+            (GEMINI_GENERATE_SUFFIX, GEMINI_STREAM_SUFFIX)
+        )
     return path in OPENAI_JSON_PATHS
 
 
@@ -186,6 +199,8 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
             for value in values
         ):
             return False
+        if is_gemini(mount):
+            return complete_gemini_stream(values)
         if urlsplit(url).path == "/v1/responses":
             return complete_responses_stream(values)
         if urlsplit(url).path == "/v1/chat/completions":
@@ -197,6 +212,8 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
         return False
     if not isinstance(value, dict) or value.get("error") is not None:
         return False
+    if is_gemini(mount):
+        return complete_gemini_candidates(value)
     path: Final = urlsplit(url).path
     if path == "/v1/messages":
         return value.get("type") == "message" and isinstance(value.get("content"), list) and isinstance(value.get("stop_reason"), str)
@@ -215,6 +232,35 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
     )
 
 
+def complete_gemini_candidates(value: Mapping[str, JsonValue]) -> bool:
+    """A finished Gemini turn names a ``finishReason`` on every candidate and
+    reports the usage litellm prices the call from. ``finishReason`` is read as a
+    string rather than compared to ``STOP`` because ``MAX_TOKENS`` and the safety
+    reasons end a turn just as finally, and a cache that rejected them would send
+    every one of them upstream forever."""
+    candidates: Final = value.get("candidates")
+    return (
+        isinstance(value.get("usageMetadata"), dict)
+        and isinstance(candidates, list)
+        and bool(candidates)
+        and all(
+            isinstance(candidate, dict) and isinstance(candidate.get("finishReason"), str)
+            for candidate in candidates
+        )
+    )
+
+
+def complete_gemini_stream(values: tuple[JsonValue, ...]) -> bool:
+    """Gemini repeats ``usageMetadata`` on every chunk but names a
+    ``finishReason`` only on the last one, so the terminator is the final event
+    rather than any event. A stream the connection cut short ends on a chunk that
+    carries usage and no reason, which is exactly what this rejects."""
+    if not values:
+        return False
+    last: Final = values[-1]
+    return isinstance(last, dict) and complete_gemini_candidates(last)
+
+
 def complete_bedrock_response(url: str, body: bytes) -> bool:
     """Converse answers with ``output`` plus a ``stopReason``; InvokeModel on an
     Anthropic model answers the Anthropic message shape. Either way a truncated
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
index f9775a2b152..c4b02beac2d 100644
--- a/tests/e2e/provider_cache_routing.py
+++ b/tests/e2e/provider_cache_routing.py
@@ -19,6 +19,7 @@ BEDROCK_EDGE_MODELS: Final = frozenset(
     }
 )
 ENV_REFERENCE_PREFIX: Final = "os.environ/"
+EDGE_PROVIDERS: Final = frozenset({"openai", "anthropic", "gemini"})
 
 
 def bedrock_region(declared: str | None) -> str:
@@ -81,7 +82,7 @@ def route_cache_model(
         return route_bedrock(params, base_for, mode)
     if mode == "realtime" or params.api_base is not None:
         return params
-    if provider not in {"openai", "anthropic"}:
+    if provider not in EDGE_PROVIDERS:
         return params
     base: Final = base_for(provider)
     if base is None:
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index 2606b26fe99..219df55233a 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -104,6 +104,7 @@ EDGE_MOUNTS: Final[Mapping[str, str]] = MappingProxyType(
     {
         "openai": "https://api.openai.com",
         "anthropic": "https://api.anthropic.com",
+        "gemini": "https://generativelanguage.googleapis.com/v1beta",
         **{
             f"bedrock/{region}": f"https://bedrock-runtime.{region}.amazonaws.com"
             for region in BEDROCK_REGIONS

From 7006da9cde950981379214f3d2dd0f645d68995e Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 07:47:31 -0700
Subject: [PATCH 42/76] feat(e2e): say why a response was not recorded

Build 226 routed Bedrock streaming for the first time and rejected 62 of
220 misses on that mount, and the counters could not say why. A flat
rejected count covers three unrelated things with opposite fixes: the
consumer walking away mid-capture, a body that arrived whole and failed
its endpoint's rule, and a provider that could not be reached. Each now
also counts its own reason.

A consumer that walks away was counting nothing at all. Abandoning the
capture generator raises GeneratorExit at its yield, so neither branch of
the old accounting ran and the miss simply vanished from the report, which
is also why misses could exceed writes plus rejected with nothing to
explain the gap. The decision moves into settle() so the generator's
finally owns the accounting and an abandoned capture is counted like any
other rejection.
---
 .../test_provider_cache.py                    | 39 ++++++++++++++
 tests/e2e/PROVIDER_CACHE.md                   |  2 +-
 tests/e2e/provider_cache.py                   | 53 +++++++++++++------
 3 files changed, 78 insertions(+), 16 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 520317a0678..1271b20438a 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -516,6 +516,45 @@ def test_counters_attribute_every_outcome_to_its_mount(
     assert counts["mount:anthropic:rejected"] == 1 and "mount:openai:rejected" not in counts
 
 
+def test_a_rejection_says_whether_the_body_was_cut_short_or_simply_unfinished(
+    store: RedisResponseStore, provider: Provider,
+) -> None:
+    """One `rejected` count cannot tell a connection that dropped from a body the
+    provider finished sending and the rules turned down, and those have opposite
+    fixes: the first is the client going away mid-capture, the second is a grammar
+    the cache does not accept. A mount whose rejections are mostly one or the other
+    is a different problem, so the report has to be able to say which."""
+    upstream: Final = f"http://127.0.0.1:{provider.server_port}"
+    cut_short: Final = cache_edge(store)
+    provider.stream = True
+    provider.truncated = True
+    provider.response = b'data: {"choices":[{"index":0,"delta":{"content":"hi"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n'
+    running: Final = start_provider_edge(cut_short, mounts={"openai": upstream})
+    try:
+        forward("POST", running.edge.api_base("openai") + "/v1/chat/completions",
+                headers=HEADERS, body=MARKED, timeout=5)
+    finally:
+        running.shutdown()
+
+    unfinished: Final = cache_edge(store)
+    provider.stream = False
+    provider.truncated = False
+    provider.response = b'{"choices":[{"index":0,"message":{"content":"hi"}}]}'
+    second: Final = start_provider_edge(unfinished, mounts={"openai": upstream})
+    try:
+        call(second.edge.api_base("openai") + "/v1/chat/completions", MARKED)
+    finally:
+        second.shutdown()
+
+    cut: Final = dict(cut_short.counters.counts)
+    turned_down: Final = dict(unfinished.counters.counts)
+    assert cut["mount:openai:rejected"] == 1 and turned_down["mount:openai:rejected"] == 1
+    assert cut["mount:openai:rejected_cut_short"] == 1
+    assert "mount:openai:rejected_incomplete" not in cut
+    assert turned_down["mount:openai:rejected_incomplete"] == 1
+    assert "mount:openai:rejected_cut_short" not in turned_down
+
+
 EMBEDDING_SUCCESS: Final = (
     b'{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.1,0.2]}],'
     b'"model":"text-embedding-3-small","usage":{"prompt_tokens":2,"total_tokens":2}}'
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index e2f8030074d..894d9be4efa 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -54,7 +54,7 @@ The trusted runner receives:
 - `E2E_PROVIDER_CACHE_NAMESPACE`: shared environment namespace, independent of build and candidate revision
 - `E2E_PROVIDER_CACHE_METRICS_DIR`: optional per-process counter artifact directory
 
-Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
+Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. A rejection also counts its reason, one of `rejected_cut_short` (the consumer walked away mid-capture), `rejected_incomplete` (the body arrived whole and failed its endpoint's rule) or `rejected_unreachable` (the provider could not be reached). A mount whose rejections are nearly all one or the other is a different problem, and the flat count cannot tell them apart. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
 
 Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read.
 
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 7bba93321b5..f528d08b720 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -52,6 +52,9 @@ BEDROCK_SUFFIXES: Final = (
     BEDROCK_INVOKE_STREAM_SUFFIX,
 )
 EVENTSTREAM_PRELUDE_BYTES: Final = 4
+CUT_SHORT: Final = "cut_short"
+INCOMPLETE: Final = "incomplete"
+UNREACHABLE: Final = "unreachable"
 EVENT_TYPE_HEADER: Final = ":event-type"
 EVENTSTREAM_HEADERS: Final[TypeAdapter[dict[str, str]]] = TypeAdapter(dict[str, str])
 OPENAI_JSON_PATHS: Final = frozenset({"/v1/chat/completions", "/v1/messages", "/v1/embeddings", "/v1/responses"})
@@ -551,7 +554,7 @@ class CacheEdge:
             )
         prepared: Final = prepare_forward(method, url, self.outbound(mount, method, url, headers, body), body)
         if isinstance(prepared, NetworkError):
-            self.count(mount, "rejected")
+            self.reject(mount, UNREACHABLE)
             return prepared
         identity: Final = request_identity(
             self.secret, test_key, method, url, self.keyed(mount, prepared.headers), body,
@@ -575,7 +578,7 @@ class CacheEdge:
             return head
         if isinstance(head, NetworkError):
             self.store.release(key, capture_slot)
-            self.count(mount, "rejected")
+            self.reject(mount, UNREACHABLE)
             return head
         return StreamHead(
             head.status_code, head.headers, primed_steps(self.capture(mount, key, capture_slot, url, head)),
@@ -585,25 +588,45 @@ class CacheEdge:
         self, mount: str, key: str, lease: CaptureLease, url: str, head: StreamHead,
     ) -> Generator[StreamStep, None, None]:
         capture: Final = ResponseCapture()
+        reason = CUT_SHORT  # rebind-ok: a consumer that walks away never reaches the settle call below
         try:
             with closing(head.steps):
                 yield StreamChunk(b"")
                 for step in head.steps:
                     yield step
                     capture.observe(step)
-            chunks: Final = capture.chunks() if capture.eligible else ()
-            headers: Final = {
-                name: value for name, value in head.headers.items() if name.lower() not in UNRECORDED_RESPONSE_HEADERS
-            }
-            if not capture.eligible or not successful_response(mount, url, head.status_code, headers, b"".join(chunks)):
-                self.count(mount, "rejected")
-                return
-            response: Final = CachedResponse(
-                request_key=key, status_code=head.status_code, headers=headers,
-                chunks=tuple(base64.b64encode(chunk).decode("ascii") for chunk in chunks),
-            )
-            published: Final = self.store.publish(key, lease, encode_response(self.secret, response))
-            self.count(mount, "writes" if published else "write_failures")
+            reason = self.settle(mount, key, lease, url, head, capture)
         finally:
+            self.reject(mount, reason)
             self.store.release(key, lease)
             capture.buffer.close()
+
+    def settle(
+        self, mount: str, key: str, lease: CaptureLease, url: str, head: StreamHead, capture: ResponseCapture,
+    ) -> str | None:
+        """None once the response is stored, otherwise the reason it was not."""
+        if not capture.eligible:
+            return CUT_SHORT
+        headers: Final = {
+            name: value for name, value in head.headers.items() if name.lower() not in UNRECORDED_RESPONSE_HEADERS
+        }
+        chunks: Final = capture.chunks()
+        if not successful_response(mount, url, head.status_code, headers, b"".join(chunks)):
+            return INCOMPLETE
+        response: Final = CachedResponse(
+            request_key=key, status_code=head.status_code, headers=headers,
+            chunks=tuple(base64.b64encode(chunk).decode("ascii") for chunk in chunks),
+        )
+        published: Final = self.store.publish(key, lease, encode_response(self.secret, response))
+        self.count(mount, "writes" if published else "write_failures")
+        return None
+
+    def reject(self, mount: str, reason: str | None) -> None:
+        """A flat rejection count cannot separate a connection that went away from
+        a body the provider finished sending and the rules turned down, and the two
+        have opposite fixes. A mount whose rejections are nearly all one or the
+        other is a different problem, so the report has to be able to say which."""
+        if reason is None:
+            return
+        self.count(mount, "rejected")
+        self.count(mount, f"rejected_{reason}")

From c447c3312db1b99e058062f8cd61f2904fa1e9ef Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 08:13:04 -0700
Subject: [PATCH 43/76] feat(e2e): separate a provider error from a body that
 failed its rule

Build 226's 62 Bedrock rejections are the question this is trying to
answer, and "incomplete" would have covered both candidate causes at once.
Replaying the completeness rules over eight streams captured from live
Bedrock, covering tool use, extended thinking and a max-tokens stop on
both streaming endpoints, accepts every one of them, so a rule that is too
strict is the less likely half. A provider that answered 429 or 5xx and
was retried out of sight is the other, and it now counts as
rejected_error_status rather than being folded in with a grammar failure.
---
 .../code_coverage_tests/test_provider_cache.py | 18 +++++++++++++++---
 tests/e2e/PROVIDER_CACHE.md                    |  2 +-
 tests/e2e/provider_cache.py                    |  3 +++
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 1271b20438a..9668de35a02 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -546,13 +546,25 @@ def test_a_rejection_says_whether_the_body_was_cut_short_or_simply_unfinished(
     finally:
         second.shutdown()
 
+    refused: Final = cache_edge(store)
+    provider.status = 429
+    provider.response = b'{"message":"Too many requests"}'
+    third: Final = start_provider_edge(refused, mounts={"openai": upstream})
+    try:
+        call(third.edge.api_base("openai") + "/v1/chat/completions", MARKED)
+    finally:
+        third.shutdown()
+
     cut: Final = dict(cut_short.counters.counts)
     turned_down: Final = dict(unfinished.counters.counts)
-    assert cut["mount:openai:rejected"] == 1 and turned_down["mount:openai:rejected"] == 1
+    errored: Final = dict(refused.counters.counts)
+    assert cut["mount:openai:rejected"] == turned_down["mount:openai:rejected"] == errored["mount:openai:rejected"] == 1
     assert cut["mount:openai:rejected_cut_short"] == 1
-    assert "mount:openai:rejected_incomplete" not in cut
     assert turned_down["mount:openai:rejected_incomplete"] == 1
-    assert "mount:openai:rejected_cut_short" not in turned_down
+    assert errored["mount:openai:rejected_error_status"] == 1
+    assert not {"mount:openai:rejected_incomplete", "mount:openai:rejected_error_status"} & set(cut)
+    assert not {"mount:openai:rejected_cut_short", "mount:openai:rejected_error_status"} & set(turned_down)
+    assert not {"mount:openai:rejected_cut_short", "mount:openai:rejected_incomplete"} & set(errored)
 
 
 EMBEDDING_SUCCESS: Final = (
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index 894d9be4efa..ed1e7d517b0 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -54,7 +54,7 @@ The trusted runner receives:
 - `E2E_PROVIDER_CACHE_NAMESPACE`: shared environment namespace, independent of build and candidate revision
 - `E2E_PROVIDER_CACHE_METRICS_DIR`: optional per-process counter artifact directory
 
-Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. A rejection also counts its reason, one of `rejected_cut_short` (the consumer walked away mid-capture), `rejected_incomplete` (the body arrived whole and failed its endpoint's rule) or `rejected_unreachable` (the provider could not be reached). A mount whose rejections are nearly all one or the other is a different problem, and the flat count cannot tell them apart. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
+Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. A rejection also counts its reason, one of `rejected_cut_short` (the consumer walked away mid-capture), `rejected_error_status` (the provider answered, with an error), `rejected_incomplete` (the body arrived whole with a success status and failed its endpoint's rule) or `rejected_unreachable` (the provider could not be reached at all). A mount whose rejections are nearly all one or the other is a different problem, and the flat count cannot tell them apart. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
 
 Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read.
 
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index f528d08b720..399a0379889 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -55,6 +55,7 @@ EVENTSTREAM_PRELUDE_BYTES: Final = 4
 CUT_SHORT: Final = "cut_short"
 INCOMPLETE: Final = "incomplete"
 UNREACHABLE: Final = "unreachable"
+ERROR_STATUS: Final = "error_status"
 EVENT_TYPE_HEADER: Final = ":event-type"
 EVENTSTREAM_HEADERS: Final[TypeAdapter[dict[str, str]]] = TypeAdapter(dict[str, str])
 OPENAI_JSON_PATHS: Final = frozenset({"/v1/chat/completions", "/v1/messages", "/v1/embeddings", "/v1/responses"})
@@ -610,6 +611,8 @@ class CacheEdge:
         headers: Final = {
             name: value for name, value in head.headers.items() if name.lower() not in UNRECORDED_RESPONSE_HEADERS
         }
+        if not 200 <= head.status_code < 300:
+            return ERROR_STATUS
         chunks: Final = capture.chunks()
         if not successful_response(mount, url, head.status_code, headers, b"".join(chunks)):
             return INCOMPLETE

From 1972a30defcea23d170ba431af99f2e82e652b24 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 08:37:25 -0700
Subject: [PATCH 44/76] revert(e2e): unmount Gemini, its api_base means two
 things

Build 227 mounted Gemini and turned TestGeminiFiles::test_gemini_file_upload
red. litellm's two Gemini endpoints disagree about what api_base means.
Chat composes {api_base}/models/{model}:{endpoint} and defaults api_base to
https://generativelanguage.googleapis.com/v1beta, so the version lives
inside it. File upload composes {api_base}/upload/v1beta/files and defaults
to the host root, so the version lives outside it. A single api_base cannot
satisfy both, and a registration carries no signal about which endpoint the
deployment will be used for, so the edge cannot route one and not the other.

Backing it out rather than working around it. The cache must never turn a
passing test red, which is the same rule the Bedrock model allowlist
follows, and Gemini was 7 of roughly 1030 edge calls in that build. Anyone
pointing litellm's Gemini provider at an AI gateway or a corporate proxy
hits this too, so the fix belongs in litellm; mounting Gemini is one line
once it lands.

This reverts commit 8a553ceb58887c8aa2aa24c7cfb75ce662d2e321.
---
 .../test_provider_cache.py                    | 154 +-----------------
 tests/e2e/PROVIDER_CACHE.md                   |  18 +-
 tests/e2e/provider_cache.py                   |  46 ------
 tests/e2e/provider_cache_routing.py           |   3 +-
 tests/e2e/provider_edge.py                    |   1 -
 5 files changed, 7 insertions(+), 215 deletions(-)

diff --git a/tests/code_coverage_tests/test_provider_cache.py b/tests/code_coverage_tests/test_provider_cache.py
index 9668de35a02..e57d33a0406 100644
--- a/tests/code_coverage_tests/test_provider_cache.py
+++ b/tests/code_coverage_tests/test_provider_cache.py
@@ -912,7 +912,7 @@ def test_anthropic_stream_requires_start_finish_and_stop() -> None:
     assert not successful_response("anthropic", url, 200, headers, start + finish)
 
 
-@pytest.mark.parametrize("provider,suffix", [("openai", "/v1"), ("anthropic", ""), ("gemini", "")])
+@pytest.mark.parametrize("provider,suffix", [("openai", "/v1"), ("anthropic", "")])
 def test_normal_registration_routes_supported_providers(provider: str, suffix: str) -> None:
     params: Final = LiteLLMParamsBody(model=f"{provider}/test", api_key="os.environ/SYNTHETIC_KEY", timeout=12)
     routed: Final = route_cache_model(params, lambda mount: f"http://edge.invalid/{mount}", enabled=True)
@@ -924,8 +924,6 @@ def test_normal_registration_routes_supported_providers(provider: str, suffix: s
 @pytest.mark.parametrize("params", [
     LiteLLMParamsBody(model="bedrock/test"),
     LiteLLMParamsBody(model="azure/test"),
-    LiteLLMParamsBody(model="vertex_ai/gemini-2.5-flash"),
-    LiteLLMParamsBody(model="gemini/gemini-2.5-flash", api_base="https://custom.invalid"),
     LiteLLMParamsBody(model="openai/test", api_base="https://custom.invalid/v1"),
     LiteLLMParamsBody(model="openai/test", api_base=""),
     LiteLLMParamsBody(model="openai/test", litellm_credential_name="named-credential"),
@@ -1294,153 +1292,3 @@ class TestBedrockStreams:
 
     def test_a_stream_that_errored_before_it_started_is_not_recordable(self) -> None:
         assert not successful_response(BEDROCK_MOUNT, CONVERSE_STREAM_URL, 503, {}, CONVERSE_STREAM_OK)
-
-
-GEMINI_MODEL: Final = "gemini-2.5-flash"
-GEMINI_API_VERSION: Final = "/v1beta"
-GEMINI_GENERATE_PATH: Final = f"/models/{GEMINI_MODEL}:generateContent"
-GEMINI_STREAM_PATH: Final = f"/models/{GEMINI_MODEL}:streamGenerateContent"
-GEMINI_USAGE: Final = {"promptTokenCount": 7, "candidatesTokenCount": 1, "totalTokenCount": 25}
-
-
-def gemini_body(finish_reason: str | None, usage: bool = True, candidates: bool = True) -> JsonValue:
-    candidate: Final[dict[str, JsonValue]] = {"content": {"parts": [{"text": "OK"}], "role": "model"}, "index": 0}
-    return {
-        "candidates": [{**candidate, "finishReason": finish_reason} if finish_reason else candidate]
-        if candidates else [],
-        **({"usageMetadata": GEMINI_USAGE} if usage else {}),
-        "modelVersion": GEMINI_MODEL,
-    }
-
-
-def gemini_unary(finish_reason: str | None = "STOP", usage: bool = True, candidates: bool = True) -> bytes:
-    return json.dumps(gemini_body(finish_reason, usage, candidates)).encode()
-
-
-def gemini_stream(*finish_reasons: str | None) -> bytes:
-    return b"".join(
-        b"data: " + json.dumps(gemini_body(reason)).encode() + b"\r\n\r\n" for reason in finish_reasons
-    )
-
-
-@contextmanager
-def gemini_edge(cache: CacheEdge, provider: Provider, path: str) -> Generator[str, None, None]:
-    upstream: Final = f"http://127.0.0.1:{provider.server_port}{GEMINI_API_VERSION}"
-    running: Final = start_provider_edge(cache, mounts={"gemini": upstream})
-    try:
-        yield running.edge.api_base("gemini") + path
-    finally:
-        running.shutdown()
-
-
-class TestGemini:
-    """Gemini reaches the edge by path prefix alone: litellm composes
-    `{api_base}/models/{model}:{endpoint}` and sends a static `x-goog-api-key`,
-    so nothing has to be re-signed and nothing leaves the cache key. The response
-    grammar is its own though, and the streaming one is the interesting half: every
-    chunk repeats `usageMetadata`, so only `finishReason` on the last chunk
-    separates a finished turn from a dropped connection."""
-
-    @pytest.mark.parametrize("path,response", [
-        (GEMINI_GENERATE_PATH, gemini_unary()),
-        (GEMINI_STREAM_PATH, gemini_stream(None, None, "STOP")),
-    ], ids=["generate", "stream"])
-    def test_a_finished_turn_replays_on_the_next_run(
-        self, store: RedisResponseStore, provider: Provider, path: str, response: bytes,
-    ) -> None:
-        provider.stream = path == GEMINI_STREAM_PATH
-        provider.response = response
-        for _ in range(2):
-            with gemini_edge(cache_edge(store), provider, path) as url:
-                assert call(url, MARKED).body == response
-        assert len(provider.hits) == 1
-
-    @pytest.mark.parametrize("reason", ["MAX_TOKENS", "SAFETY", "RECITATION"])
-    def test_a_turn_the_provider_ended_for_its_own_reasons_is_still_finished(
-        self, store: RedisResponseStore, provider: Provider, reason: str,
-    ) -> None:
-        """Reading `finishReason` as a string rather than comparing it to STOP is
-        deliberate. A turn cut off by the token limit or a safety filter is over,
-        and rejecting those would send every one of them upstream forever."""
-        provider.response = gemini_unary(reason)
-        for _ in range(2):
-            with gemini_edge(cache_edge(store), provider, GEMINI_GENERATE_PATH) as url:
-                assert call(url, MARKED).body == provider.response
-        assert len(provider.hits) == 1
-
-    @pytest.mark.parametrize("response", [
-        gemini_unary(None),
-        gemini_unary("STOP", usage=False),
-        gemini_unary("STOP", candidates=False),
-        b'{"error":{"code":400,"message":"API key not valid","status":"INVALID_ARGUMENT"}}',
-    ], ids=["no-finish-reason", "no-usage", "no-candidates", "error-body"])
-    def test_an_unfinished_or_failed_turn_never_enters_the_cache(
-        self, store: RedisResponseStore, provider: Provider, response: bytes,
-    ) -> None:
-        provider.response = response
-        for _ in range(2):
-            with gemini_edge(cache_edge(store), provider, GEMINI_GENERATE_PATH) as url:
-                assert call(url, MARKED).body == response
-        assert len(provider.hits) == 2
-
-    @pytest.mark.parametrize("response", [
-        gemini_stream(None, None),
-        gemini_stream("STOP", None),
-        gemini_stream(),
-    ], ids=["cut-before-the-reason", "reason-then-another-chunk", "empty"])
-    def test_a_stream_that_never_named_a_reason_calls_the_provider_every_time(
-        self, store: RedisResponseStore, provider: Provider, response: bytes,
-    ) -> None:
-        provider.stream = True
-        provider.response = response
-        for _ in range(2):
-            with gemini_edge(cache_edge(store), provider, GEMINI_STREAM_PATH) as url:
-                assert call(url, MARKED).body == response
-        assert len(provider.hits) == 2
-
-    def test_a_response_whose_candidates_did_not_all_finish_is_not_recordable(
-        self, store: RedisResponseStore, provider: Provider,
-    ) -> None:
-        """A request for more than one candidate is answered by more than one, and
-        the turn is over only when every one of them names a reason. Holding the
-        whole list to that rule rather than its first entry is what keeps a
-        half-finished answer from being stored and replayed as a finished one."""
-        finished: Final = json.loads(gemini_unary("STOP"))["candidates"][0]
-        unfinished: Final = json.loads(gemini_unary(None))["candidates"][0]
-        provider.response = json.dumps(
-            {"candidates": [finished, {**unfinished, "index": 1}], "usageMetadata": GEMINI_USAGE}
-        ).encode()
-        for _ in range(2):
-            with gemini_edge(cache_edge(store), provider, GEMINI_GENERATE_PATH) as url:
-                assert call(url, MARKED).body == provider.response
-        assert len(provider.hits) == 2
-
-    @pytest.mark.parametrize("path,cacheable", [
-        (GEMINI_GENERATE_PATH, True),
-        (GEMINI_STREAM_PATH, True),
-        (f"/models/{GEMINI_MODEL}:countTokens", False),
-        (f"/models/{GEMINI_MODEL}:embedContent", False),
-        ("/v1/chat/completions", False),
-        (f"/files/{GEMINI_MODEL}:generateContent", False),
-    ])
-    @pytest.mark.parametrize("version", ["", GEMINI_API_VERSION], ids=["bare", "versioned"])
-    def test_only_the_generate_endpoints_are_cacheable(self, version: str, path: str, cacheable: bool) -> None:
-        """The mount's upstream base carries the API version, so the path the cache
-        sees is the upstream one and starts `/v1beta`. A rule anchored at the start
-        of the path would pass every test against a stub with no version prefix and
-        then cache nothing at all in a real run."""
-        assert cacheable_endpoint("gemini", "POST", f"https://gemini.invalid{version}{path}", MARKED) is cacheable
-
-    def test_the_bodies_these_tests_build_match_a_real_gemini_response(self) -> None:
-        """The shapes above are hand-built so a test can express the turn it means.
-        This holds them to the fields a live `generativelanguage.googleapis.com`
-        answer carries, captured 2026-09-16 against gemini-2.5-flash."""
-        captured: Final = json.loads(
-            '{"candidates":[{"content":{"parts":[{"text":"OK"}],"role":"model"},"finishReason":"STOP",'
-            '"index":0}],"usageMetadata":{"promptTokenCount":7,"candidatesTokenCount":1,'
-            '"totalTokenCount":25},"modelVersion":"gemini-2.5-flash","responseId":"1J6qauKFI8ut1MkPgNjI4AI"}'
-        )
-        built: Final = json.loads(gemini_unary())
-        assert captured.keys() >= built.keys()
-        assert captured["candidates"][0].keys() >= built["candidates"][0].keys()
-        assert successful_response("gemini", GEMINI_GENERATE_PATH, 200, {}, json.dumps(captured).encode())
diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index ed1e7d517b0..aca81f26c5a 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -1,23 +1,13 @@
 # Shared provider-response cache
 
-`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI, Anthropic and Gemini model registrations use the provider edge, as do Anthropic-on-Bedrock registrations that carry no AWS identity of their own. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
+`E2E_PROVIDER_CACHE=1` enables automatic response reuse in the live E2E mode. Standard OpenAI and Anthropic model registrations use the provider edge, as do Anthropic-on-Bedrock registrations that carry no AWS identity of their own. Existing custom API bases, named credentials, mocked models and realtime WebSocket deployments keep their existing routing. Other provider protocols remain live
 
-The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, SSE streams included, for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount, and for `models/{model}:generateContent` and `:streamGenerateContent` on the Gemini mount. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
+The edge caches complete successful POST responses for `/v1/chat/completions`, `/v1/messages`, `/v1/embeddings` and `/v1/responses` on the OpenAI and Anthropic mounts, SSE streams included, and for `/model/{id}/converse` and `/model/{id}/invoke` on a Bedrock mount. Unsupported endpoints pass through. Each endpoint family has its own completeness rule, so a truncated embedding or a Responses run that never reached `response.completed` is not stored
 
 Bedrock's streaming endpoints, `converse-stream` and `invoke-with-response-stream`, cache too. AWS frames those as binary `vnd.amazon.eventstream` rather than SSE, so botocore's own parser reads the frames and validates both CRCs, and each endpoint is then held to its terminal grammar. That matters more than the endpoint count suggests: the Claude Code compat cells drive the real CLI, which always streams, so streaming is most of the suite's Bedrock traffic
 
 Two details of that rule are worth knowing before changing it. A ConverseStream ends with `metadata`, not with `messageStop`, and the `metadata` frame is what carries the token usage litellm prices the call from, so the rule requires it: a stream cut between the two still names a stop reason but would replay as a free call. And a dropped connection is invisible to the parser, which yields the frames it did receive and silently discards a trailing partial one, so the body is also checked against the frame lengths it declares. A stream cut one byte short parses clean and has to be caught that way
 
-## Gemini
-
-Gemini needs nothing that Bedrock needed. litellm composes `{api_base}/models/{model}:{endpoint}` from a custom api_base, so a path-prefixed mount reaches it, and the credential travels as a static `x-goog-api-key` header that no host rewrite invalidates. Nothing is re-signed and nothing is excluded from the key, so a recording still cannot cross credentials
-
-The mount's upstream base carries the API version, which is the one detail worth remembering: the path the cache rules see is the upstream one, `/v1beta/models/...`, not the one the proxy sent. A rule anchored at the start of that path would look right against a local stub and then cache nothing at all in a real run
-
-A finished turn names a `finishReason` on every candidate and reports `usageMetadata`. The reason is read as a string rather than compared to `STOP`, because `MAX_TOKENS` and the safety reasons end a turn just as finally and rejecting them would send every one of them upstream forever. Streaming is the more interesting half: Gemini repeats `usageMetadata` on every chunk and names a `finishReason` only on the last one, so the terminator is the final event rather than any event, and a stream the connection cut short ends on a chunk with usage and no reason
-
-Vertex is not mounted. litellm grafts the default Vertex path onto an api_base only when that api_base has no path of its own, so a Vertex mount needs a root-mounted edge on its own port rather than a path prefix. Gemini and Vertex are separate providers in litellm and the Gemini mount does not cover Vertex deployments
-
 ## Request identity
 
 A recording belongs to one test. The key is a keyed digest over the test's node id, the method, the URL, the effective outbound headers (including authentication and HTTP-library defaults), body presence and the body bytes, with one normalization: a 12-hex-digit run, the shape `unique_marker()` mints, is replaced by a placeholder in both the URL and a UTF-8 body. Nothing else is normalized away. No prompts, JSON values or credentials are rewritten, and the rule is the one `fixture_canonical.py` already applies for record/replay, so there is a single definition of what a marker is
@@ -40,7 +30,9 @@ Only deployments that carry no AWS identity of their own route to the edge. A de
 
 Which models route is an explicit allowlist in `provider_cache_routing.py`, mirroring the runner role's IAM policy, which names its models one by one. That coupling is deliberate: the edge re-signs with the run pod's identity, so a model the role cannot invoke comes back 403 from Bedrock rather than falling back. An unlisted model keeps its direct path and loses only caching, so adding a Bedrock model to the suite can never turn it red. Adding one to the edge is a policy edit in litellm-ops plus a line here
 
-Vertex is not mounted. litellm's `_check_custom_proxy` rewrites a path-prefixed Vertex `api_base` into `{api_base}:{endpoint}`, dropping project, location and model, so a mount under a path prefix cannot work without either a root-mounted edge on its own port or a change in litellm. Gemini is a separate provider there and does have a working path-prefixed form, so it is mounted; see the Gemini section
+Vertex and Gemini are not mounted, for different reasons. litellm grafts the default Vertex path onto an `api_base` only when that `api_base` has no path of its own, so a path-prefixed Vertex mount instead becomes `{api_base}:{endpoint}`, dropping project, location and model. Vertex needs a root-mounted edge on its own port, or a change in litellm
+
+Gemini reaches a path-prefixed mount perfectly well and was mounted for one build, then backed out, because litellm's two Gemini endpoints disagree about what `api_base` means. Chat composes `{api_base}/models/{model}:{endpoint}` and defaults `api_base` to `https://generativelanguage.googleapis.com/v1beta`, so the version has to be inside it. File upload composes `{api_base}/upload/v1beta/files` and defaults to the host root, so the version has to be outside it. One `api_base` cannot satisfy both, and a deployment gives no signal at registration time about which it will be used for, so mounting Gemini turned `TestGeminiFiles::test_gemini_file_upload` red in build 227. Anyone pointing litellm's Gemini provider at an AI gateway or a corporate proxy hits the same thing; it is a litellm bug rather than a cache limitation, and mounting Gemini is one line once it is fixed
 
 Recordings are shared across workers and builds through dedicated Redis, separate from the candidate's own cache. They expire 86,400 seconds after capture starts, based on Redis time. Reads never extend expiry. There is no scheduled recapture: the next miss calls the provider again. Bounded coordination reduces duplicate concurrent calls, but slow or failed captures may lead to extra live calls after the wait expires
 
diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 399a0379889..444972ffce5 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -37,10 +37,6 @@ SIGNATURE_HEADERS: Final = frozenset(
     {"authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"}
 )
 BEDROCK_MOUNT_PREFIX: Final = "bedrock"
-GEMINI_MOUNT: Final = "gemini"
-GEMINI_MODELS_SEGMENT: Final = "/models"
-GEMINI_GENERATE_SUFFIX: Final = ":generateContent"
-GEMINI_STREAM_SUFFIX: Final = ":streamGenerateContent"
 BEDROCK_CONVERSE_SUFFIX: Final = "/converse"
 BEDROCK_INVOKE_SUFFIX: Final = "/invoke"
 BEDROCK_CONVERSE_STREAM_SUFFIX: Final = "/converse-stream"
@@ -162,21 +158,12 @@ def is_bedrock(mount: str) -> bool:
     return mount.partition("/")[0] == BEDROCK_MOUNT_PREFIX
 
 
-def is_gemini(mount: str) -> bool:
-    return mount == GEMINI_MOUNT
-
-
 def cacheable_endpoint(mount: str, method: str, url: str, body: bytes | None) -> bool:
     if method != "POST" or body is None or len(body) > MAX_REQUEST_BYTES:
         return False
     path: Final = urlsplit(url).path
     if is_bedrock(mount):
         return path.startswith("/model/") and path.endswith(BEDROCK_SUFFIXES)
-    if is_gemini(mount):
-        collection, _, resource = path.rpartition("/")
-        return collection.endswith(GEMINI_MODELS_SEGMENT) and resource.endswith(
-            (GEMINI_GENERATE_SUFFIX, GEMINI_STREAM_SUFFIX)
-        )
     return path in OPENAI_JSON_PATHS
 
 
@@ -203,8 +190,6 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
             for value in values
         ):
             return False
-        if is_gemini(mount):
-            return complete_gemini_stream(values)
         if urlsplit(url).path == "/v1/responses":
             return complete_responses_stream(values)
         if urlsplit(url).path == "/v1/chat/completions":
@@ -216,8 +201,6 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
         return False
     if not isinstance(value, dict) or value.get("error") is not None:
         return False
-    if is_gemini(mount):
-        return complete_gemini_candidates(value)
     path: Final = urlsplit(url).path
     if path == "/v1/messages":
         return value.get("type") == "message" and isinstance(value.get("content"), list) and isinstance(value.get("stop_reason"), str)
@@ -236,35 +219,6 @@ def successful_response(mount: str, url: str, status: int, headers: Mapping[str,
     )
 
 
-def complete_gemini_candidates(value: Mapping[str, JsonValue]) -> bool:
-    """A finished Gemini turn names a ``finishReason`` on every candidate and
-    reports the usage litellm prices the call from. ``finishReason`` is read as a
-    string rather than compared to ``STOP`` because ``MAX_TOKENS`` and the safety
-    reasons end a turn just as finally, and a cache that rejected them would send
-    every one of them upstream forever."""
-    candidates: Final = value.get("candidates")
-    return (
-        isinstance(value.get("usageMetadata"), dict)
-        and isinstance(candidates, list)
-        and bool(candidates)
-        and all(
-            isinstance(candidate, dict) and isinstance(candidate.get("finishReason"), str)
-            for candidate in candidates
-        )
-    )
-
-
-def complete_gemini_stream(values: tuple[JsonValue, ...]) -> bool:
-    """Gemini repeats ``usageMetadata`` on every chunk but names a
-    ``finishReason`` only on the last one, so the terminator is the final event
-    rather than any event. A stream the connection cut short ends on a chunk that
-    carries usage and no reason, which is exactly what this rejects."""
-    if not values:
-        return False
-    last: Final = values[-1]
-    return isinstance(last, dict) and complete_gemini_candidates(last)
-
-
 def complete_bedrock_response(url: str, body: bytes) -> bool:
     """Converse answers with ``output`` plus a ``stopReason``; InvokeModel on an
     Anthropic model answers the Anthropic message shape. Either way a truncated
diff --git a/tests/e2e/provider_cache_routing.py b/tests/e2e/provider_cache_routing.py
index c4b02beac2d..f9775a2b152 100644
--- a/tests/e2e/provider_cache_routing.py
+++ b/tests/e2e/provider_cache_routing.py
@@ -19,7 +19,6 @@ BEDROCK_EDGE_MODELS: Final = frozenset(
     }
 )
 ENV_REFERENCE_PREFIX: Final = "os.environ/"
-EDGE_PROVIDERS: Final = frozenset({"openai", "anthropic", "gemini"})
 
 
 def bedrock_region(declared: str | None) -> str:
@@ -82,7 +81,7 @@ def route_cache_model(
         return route_bedrock(params, base_for, mode)
     if mode == "realtime" or params.api_base is not None:
         return params
-    if provider not in EDGE_PROVIDERS:
+    if provider not in {"openai", "anthropic"}:
         return params
     base: Final = base_for(provider)
     if base is None:
diff --git a/tests/e2e/provider_edge.py b/tests/e2e/provider_edge.py
index 219df55233a..2606b26fe99 100644
--- a/tests/e2e/provider_edge.py
+++ b/tests/e2e/provider_edge.py
@@ -104,7 +104,6 @@ EDGE_MOUNTS: Final[Mapping[str, str]] = MappingProxyType(
     {
         "openai": "https://api.openai.com",
         "anthropic": "https://api.anthropic.com",
-        "gemini": "https://generativelanguage.googleapis.com/v1beta",
         **{
             f"bedrock/{region}": f"https://bedrock-runtime.{region}.amazonaws.com"
             for region in BEDROCK_REGIONS

From 7d42bc751debd3ffa7eaa6166d20f627cee0f067 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 10:05:13 -0700
Subject: [PATCH 45/76] docs(e2e): name all four rejection reasons in the
 counter note

---
 tests/e2e/PROVIDER_CACHE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index aca81f26c5a..e06b3c01653 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -46,7 +46,7 @@ The trusted runner receives:
 - `E2E_PROVIDER_CACHE_NAMESPACE`: shared environment namespace, independent of build and candidate revision
 - `E2E_PROVIDER_CACHE_METRICS_DIR`: optional per-process counter artifact directory
 
-Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. A rejection also counts its reason, one of `rejected_cut_short` (the consumer walked away mid-capture), `rejected_error_status` (the provider answered, with an error), `rejected_incomplete` (the body arrived whole with a success status and failed its endpoint's rule) or `rejected_unreachable` (the provider could not be reached at all). A mount whose rejections are nearly all one or the other is a different problem, and the flat count cannot tell them apart. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
+Do not give cache credentials to candidate deployments. Counter artifacts contain no recorded payloads or credentials. Hits count shared-cache responses; upstream attempts count actual forwards from the edge. A rejection also counts its reason, one of `rejected_cut_short` (the consumer walked away mid-capture), `rejected_error_status` (the provider answered, with an error), `rejected_incomplete` (the body arrived whole with a success status and failed its endpoint's rule) or `rejected_unreachable` (the provider could not be reached at all). A mount whose rejections are nearly all of one kind is a different problem from one whose rejections are nearly all of another, and the flat count cannot tell them apart. Every counter is emitted twice, once as a flat total and once under `mount:{mount}:`, so a hit rate can be read per provider rather than only in aggregate. Existing application-cache observations still count requests arriving at the edge, including shared-cache hits
 
 Tests that require real provider timing, limits or state use `@pytest.mark.provider_live`. The marker keeps newly registered models on live routes without weakening their assertions. The provider prompt-caching tests carry it because a replayed priming response reports cache creation rather than a cache read.
 

From ecd72c51da019f30debf182d44f89e2c2b6e4854 Mon Sep 17 00:00:00 2001
From: ryan-crabbe-berri <ryan@berri.ai>
Date: Wed, 16 Sep 2026 11:29:25 -0700
Subject: [PATCH 46/76] refactor(ui): register ssh skill sources verbatim and
 share the https host rules

The ssh parser rebuilt the clone url it was given, stripping a trailing .git and
appending one back. Git treats that suffix as optional, and the hosts whose clone
paths are not org/repo break when it is forced on, so an Azure DevOps v3 or a
CodeCommit v1/repos url registered through the form would no longer clone.

It also carried its own host pattern, which demanded an alphabetic final label and
so rejected internal hosts like gitlab.internal.k8s2 that the https path accepts.

Rewrite the scp form into an ssh:// url purely to validate it, reuse the https host
and credential checks through a shared isSafeHost, and store exactly what the user
typed. Only a url that survives the round trip unchanged is accepted, which is what
keeps traversal segments out of the feed, so the two ssh regexes, the dots-only
guard and the clone-url builders all collapse into one function.
---
 .../claude_code_plugins/helpers.test.ts       | 36 +++++---
 .../components/claude_code_plugins/helpers.ts | 84 +++++++++----------
 2 files changed, 65 insertions(+), 55 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
index ccdc0a1a388..5bf782aabf3 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
@@ -476,21 +476,30 @@ describe("parseSkillSource", () => {
       source: "url",
       url: "git@ghe.example.com:org/repo.git",
     });
-    expect(parseSkillSource("git@ghe.example.com:org/repo")?.parsed).toEqual({
-      source: "url",
-      url: "git@ghe.example.com:org/repo.git",
-    });
     expect(parseSkillSource("git@ghe.example.com:org/repo.git")?.suggestedName).toBe("repo");
   });
 
-  it("normalizes an ssh:// clone url and keeps a custom port", () => {
-    expect(parseSkillSource("ssh://git@ghe.example.com/org/repo")?.parsed).toEqual({
+  it("stores an ssh clone url exactly as typed, so a forced .git suffix cannot break azure devops or codecommit", () => {
+    for (const url of [
+      "git@ghe.example.com:org/repo",
+      "git@ssh.dev.azure.com:v3/org/project/repo",
+      "ssh://git@ghe.example.com/org/repo",
+      "ssh://apka1234@git-codecommit.us-east-1.amazonaws.com/v1/repos/my-repo",
+      "ssh://git@ghe.example.com:2222/org/nested/repo.git",
+    ]) {
+      expect(parseSkillSource(url)?.parsed).toEqual({ source: "url", url });
+    }
+    expect(parseSkillSource("git@ssh.dev.azure.com:v3/org/project/repo")?.suggestedName).toBe("repo");
+  });
+
+  it("accepts an internal host whose last label is not alphabetic, matching the https rule", () => {
+    expect(parseSkillSource("git@gitlab.internal.k8s2:org/repo.git")?.parsed).toEqual({
       source: "url",
-      url: "ssh://git@ghe.example.com/org/repo.git",
+      url: "git@gitlab.internal.k8s2:org/repo.git",
     });
-    expect(parseSkillSource("ssh://git@ghe.example.com:2222/org/nested/repo.git")?.parsed).toEqual({
+    expect(parseSkillSource("https://gitlab.internal.k8s2/org/repo")?.parsed).toEqual({
       source: "url",
-      url: "ssh://git@ghe.example.com:2222/org/nested/repo.git",
+      url: "https://gitlab.internal.k8s2/org/repo",
     });
   });
 
@@ -510,17 +519,22 @@ describe("parseSkillSource", () => {
     expect(parseSkillSource("ssh://ghe.example.com/org/repo.git")).toBeNull();
   });
 
-  it("rejects ssh remotes with ip hosts or dot-only path segments", () => {
+  it("rejects ssh remotes with ip hosts or traversal segments", () => {
     expect(parseSkillSource("git@10.0.0.5:org/repo.git")).toBeNull();
     expect(parseSkillSource("ssh://git@169.254.169.254/org/repo")).toBeNull();
     expect(parseSkillSource("git@ghe.example.com:../etc")).toBeNull();
     expect(parseSkillSource("ssh://git@ghe.example.com/org/../repo")).toBeNull();
+    expect(parseSkillSource("git@ghe.example.com:org/../../etc/passwd")).toBeNull();
     expect(parseSkillSource("git@ghe.example.com:org/.github")?.parsed).toEqual({
       source: "url",
-      url: "git@ghe.example.com:org/.github.git",
+      url: "git@ghe.example.com:org/.github",
     });
   });
 
+  it("rejects an ssh remote carrying a password, which would publish a secret on the feed", () => {
+    expect(parseSkillSource("ssh://git:s3cret@ghe.example.com/org/repo.git")).toBeNull();
+  });
+
   it("returns null for empty and garbage input", () => {
     expect(parseSkillSource("")).toBeNull();
     expect(parseSkillSource("   ")).toBeNull();
diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
index 3c11a6cedbc..b4d9eab08ec 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
@@ -29,22 +29,33 @@ export const SHA256_REGEX = /^[0-9a-fA-F]{64}$/;
 
 export const isValidSha256 = (digest: string): boolean => digest.trim() === "" || SHA256_REGEX.test(digest.trim());
 
-// WHATWG normalizes obfuscated IPv4 (e.g. 2130706433, 0x7f.0.0.1) to dotted-decimal, so this
-// catches every IPv4 form; bracketed IPv6 is rejected separately.
+// WHATWG normalizes obfuscated IPv4 (e.g. 2130706433, 0x7f.0.0.1) to dotted-decimal on https, so
+// this catches every IPv4 form there; on a non-special scheme like ssh it catches the dotted form
+// only. Bracketed IPv6 is rejected separately.
 const IPV4_HOST_REGEX = /^\d{1,3}(\.\d{1,3}){3}$/;
 
 const GITHUB_ORG_REGEX = /^[A-Za-z0-9-]+$/;
 const GITHUB_REPO_REGEX = /^[A-Za-z0-9._-]+$/;
 
-const SSH_SCP_REGEX = /^([a-z0-9._-]+)@([a-z0-9.-]+\.[a-z]{2,}):([a-z0-9._-]+(?:\/[a-z0-9._-]+)+?)(?:\.git)?\/?$/i;
-const SSH_URL_REGEX =
-  /^ssh:\/\/([a-z0-9._-]+)@([a-z0-9.-]+\.[a-z]{2,})(:\d+)?\/([a-z0-9._-]+(?:\/[a-z0-9._-]+)+?)(?:\.git)?\/?$/i;
-const DOTS_ONLY_SEGMENT_REGEX = /^\.+$/;
+const SSH_SCHEME = "ssh://";
+const SSH_SCP_REGEX = /^([a-z0-9._-]+)@([^:/@]+):(?!\/)(.+)$/i;
 
 const buildRepoUrl = (url: URL): string => `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`;
 
 const pathSegments = (url: URL): string[] => url.pathname.split("/").filter((seg) => seg !== "");
 
+const toUrl = (candidate: string): URL | null => {
+  try {
+    return new URL(candidate);
+  } catch {
+    return null;
+  }
+};
+
+/** One host rule for every scheme, so an ssh remote is neither more nor less trusted than its https twin. */
+const isSafeHost = (url: URL): boolean =>
+  url.hostname.includes(".") && !url.hostname.startsWith("[") && !IPV4_HOST_REGEX.test(url.hostname);
+
 /**
  * Validate and normalize a repository URL into a parsed URL, or null. Enforces https (rejects
  * http/ssh/git/etc.), rejects embedded credentials, and requires a dotted host, so the public
@@ -57,20 +68,8 @@ const parseRepoUrl = (raw: string): URL | null => {
     return null;
   }
   const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
-  let url: URL;
-  try {
-    url = new URL(withScheme);
-  } catch {
-    return null;
-  }
-  if (
-    url.protocol !== "https:" ||
-    url.username !== "" ||
-    url.password !== "" ||
-    !url.hostname.includes(".") ||
-    url.hostname.startsWith("[") ||
-    IPV4_HOST_REGEX.test(url.hostname)
-  ) {
+  const url = toUrl(withScheme);
+  if (!url || url.protocol !== "https:" || url.username !== "" || url.password !== "" || !isSafeHost(url)) {
     return null;
   }
   return url;
@@ -178,32 +177,29 @@ const parseRawGitSource = (url: URL, subPath?: string): SkillSourcePreview | nul
   return buildGitSourcePreview("Git", buildRepoUrl(url), repoName, subPath);
 };
 
-interface SshRemote {
-  cloneUrl: string;
-  repoName: string;
-}
-
-const buildSshRemote = (rawPath: string, toCloneUrl: (repoPath: string) => string): SshRemote | null => {
-  if (rawPath.split("/").some((segment) => DOTS_ONLY_SEGMENT_REGEX.test(segment))) {
+/**
+ * Parse an scp-style `git@host:org/repo` or `ssh://git@host/org/repo` clone URL, registering it
+ * exactly as typed: git treats the `.git` suffix as optional, and forcing one on breaks hosts whose
+ * paths are not `org/repo`, like Azure DevOps `v3/...` and CodeCommit `v1/repos/...`. The scp form is
+ * rewritten to `ssh://` only to reuse the https host and credential rules, and only a URL that
+ * survives that round trip unchanged is accepted, which keeps traversal segments off the feed.
+ */
+const parseSshSource = (raw: string, subPath?: string): SkillSourcePreview | null => {
+  const trimmed = raw.trim();
+  const scp = SSH_SCP_REGEX.exec(trimmed);
+  const candidate = scp ? `${SSH_SCHEME}${scp[1]}@${scp[2]}/${scp[3]}` : trimmed;
+  if (!candidate.toLowerCase().startsWith(SSH_SCHEME)) {
     return null;
   }
-  const bare = rawPath.replace(/\.git$/i, "");
-  return { cloneUrl: toCloneUrl(`${bare}.git`), repoName: lastSegment(bare) };
-};
-
-const parseSshRemote = (raw: string): SshRemote | null => {
-  const trimmed = raw.trim();
-  const sshUrl = SSH_URL_REGEX.exec(trimmed);
-  if (sshUrl) {
-    const [, user, host, port, path] = sshUrl;
-    return buildSshRemote(path, (repoPath) => `ssh://${user}@${host}${port ?? ""}/${repoPath}`);
+  const url = toUrl(candidate);
+  if (!url || url.username === "" || url.password !== "" || !isSafeHost(url)) {
+    return null;
   }
-  const scp = SSH_SCP_REGEX.exec(trimmed);
-  if (scp) {
-    const [, user, host, path] = scp;
-    return buildSshRemote(path, (repoPath) => `${user}@${host}:${repoPath}`);
+  const pathStart = candidate.indexOf("/", SSH_SCHEME.length);
+  if (pathStart === -1 || url.pathname !== candidate.slice(pathStart) || pathSegments(url).length < 2) {
+    return null;
   }
-  return null;
+  return buildGitSourcePreview("SSH", trimmed, lastSegment(url.pathname).replace(/\.git$/i, ""), subPath);
 };
 
 const parseArchiveSource = (url: URL): SkillSourcePreview => ({
@@ -220,9 +216,9 @@ const parseArchiveSource = (url: URL): SkillSourcePreview => ({
  * with an optional subfolder turning it into git-subdir.
  */
 export const parseSkillSource = (rawUrl: string, subPath?: string): SkillSourcePreview | null => {
-  const ssh = parseSshRemote(rawUrl);
+  const ssh = parseSshSource(rawUrl, subPath);
   if (ssh) {
-    return buildGitSourcePreview("SSH", ssh.cloneUrl, ssh.repoName, subPath);
+    return ssh;
   }
   const url = parseRepoUrl(rawUrl);
   if (!url) {

From 0143fe5583e845af20606c9d6becfbff35b9c8c4 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 18:30:12 +0000
Subject: [PATCH 47/76] fix(guardrails): hold tool-call windows until the final
 scan and expose Bedrock streaming flags to the UI

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../chat/guardrail_translation/handler.py     |  4 +-
 .../guardrail_translation/base_translation.py |  6 +-
 .../chat/guardrail_translation/handler.py     |  4 +-
 .../guardrail_translation/handler.py          | 15 ++-
 .../proxy/guardrails/guardrail_endpoints.py   |  6 +-
 .../guardrail_hooks/bedrock_guardrails.py     |  6 +-
 .../unified_guardrail/unified_guardrail.py    | 14 +++
 .../test_anthropic_guardrail_handler.py       |  3 +
 .../test_openai_guardrail_handler.py          |  3 +
 ...test_openai_responses_guardrail_handler.py | 21 +++++
 .../test_bedrock_guardrails.py                | 38 ++++++++
 .../test_streaming_buffer_until_moderated.py  | 91 ++++++++++++++++++-
 .../guardrails/test_guardrail_endpoints.py    | 16 ++++
 13 files changed, 217 insertions(+), 10 deletions(-)

diff --git a/litellm/llms/anthropic/chat/guardrail_translation/handler.py b/litellm/llms/anthropic/chat/guardrail_translation/handler.py
index 2ea20143f0c..93d87585496 100644
--- a/litellm/llms/anthropic/chat/guardrail_translation/handler.py
+++ b/litellm/llms/anthropic/chat/guardrail_translation/handler.py
@@ -1561,10 +1561,12 @@ class AnthropicMessagesHandler(BaseTranslation):
 
     def get_streaming_scan_key(self, responses_so_far: Sequence[object]) -> StreamingScanKey | None:
         stream_ended: Final = self._check_streaming_has_ended(responses_so_far)
+        tool_use_fingerprints: Final = self._streamed_tool_use_fingerprints(responses_so_far)
         return StreamingScanKey(
             texts=(self.get_streaming_string_so_far(responses_so_far),),
-            tool_calls=self._streamed_tool_use_fingerprints(responses_so_far) if stream_ended else (),
+            tool_calls=tool_use_fingerprints if stream_ended else (),
             stream_ended=stream_ended,
+            tool_calls_in_flight=bool(tool_use_fingerprints) and not stream_ended,
         )
 
     @classmethod
diff --git a/litellm/llms/base_llm/guardrail_translation/base_translation.py b/litellm/llms/base_llm/guardrail_translation/base_translation.py
index f1143425ced..89ad67f0485 100644
--- a/litellm/llms/base_llm/guardrail_translation/base_translation.py
+++ b/litellm/llms/base_llm/guardrail_translation/base_translation.py
@@ -40,11 +40,15 @@ class StreamingScanKey:
     """What a streaming guardrail round would hand to ``apply_guardrail``. Two keys
     compare equal when the round would scan the same content again; ``stream_ended``
     stays out of the comparison and only says whether the handler is on its
-    end-of-stream path, where an empty payload is still scanned today."""
+    end-of-stream path, where an empty payload is still scanned today.
+    ``tool_calls_in_flight`` also stays out of the comparison: it flags that tool
+    calls have streamed which this round cannot scan yet, so a buffered window
+    holding them must stay withheld until the end-of-stream scan covers them."""
 
     texts: tuple[str, ...]
     tool_calls: tuple[str, ...] = ()
     stream_ended: bool = field(default=False, compare=False)
+    tool_calls_in_flight: bool = field(default=False, compare=False)
 
     @property
     def has_nothing_to_scan(self) -> bool:
diff --git a/litellm/llms/openai/chat/guardrail_translation/handler.py b/litellm/llms/openai/chat/guardrail_translation/handler.py
index 01e14f2248d..9b818696bbb 100644
--- a/litellm/llms/openai/chat/guardrail_translation/handler.py
+++ b/litellm/llms/openai/chat/guardrail_translation/handler.py
@@ -792,10 +792,12 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
     def get_streaming_scan_key(self, responses_so_far: Sequence[object]) -> StreamingScanKey | None:
         chunks: Final = tuple(chunk for chunk in responses_so_far if isinstance(chunk, ModelResponseStream))
         stream_ended: Final = self._first_choice_has_finished(responses_so_far)
+        tool_call_fingerprints: Final = self._streamed_tool_call_fingerprints(responses_so_far)
         return StreamingScanKey(
             texts=tuple(self._combine_streaming_texts(chunks).values()),
-            tool_calls=self._streamed_tool_call_fingerprints(responses_so_far) if stream_ended else (),
+            tool_calls=tool_call_fingerprints if stream_ended else (),
             stream_ended=stream_ended,
+            tool_calls_in_flight=bool(tool_call_fingerprints) and not stream_ended,
         )
 
     @staticmethod
diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py
index 27ff55f120c..321f0a0d6d3 100644
--- a/litellm/llms/openai/responses/guardrail_translation/handler.py
+++ b/litellm/llms/openai/responses/guardrail_translation/handler.py
@@ -1177,9 +1177,22 @@ class OpenAIResponsesHandler(BaseTranslation):
             return None
         if last_event_type == ResponsesAPIStreamEvents.RESPONSE_COMPLETED.value:
             return self._completed_response_scan_key(stream_item_field(last_event, "response"))
+        stream_ended: Final = self._check_streaming_has_ended(responses_so_far)
         return StreamingScanKey(
             texts=(self.get_streaming_string_so_far(responses_so_far),),
-            stream_ended=self._check_streaming_has_ended(responses_so_far),
+            stream_ended=stream_ended,
+            tool_calls_in_flight=not stream_ended and self._has_streamed_tool_call_events(responses_so_far),
+        )
+
+    @staticmethod
+    def _has_streamed_tool_call_events(responses_so_far: Sequence[object]) -> bool:
+        return any(
+            stream_item_field(event, "type") in _TOOL_CALL_PAYLOAD_EVENT_TYPES
+            or (
+                stream_item_field(event, "type") in _OUTPUT_ITEM_EVENT_TYPES
+                and stream_item_field(stream_item_field(event, "item"), "type") in _TOOL_CALL_ITEM_TYPES
+            )
+            for event in responses_so_far
         )
 
     @staticmethod
diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py
index afb9997f2e6..6874d7aa73e 100644
--- a/litellm/proxy/guardrails/guardrail_endpoints.py
+++ b/litellm/proxy/guardrails/guardrail_endpoints.py
@@ -37,6 +37,7 @@ from litellm.types.guardrails import (
     ApplyGuardrailResponse,
     BaseLitellmParams,
     BedrockGuardrailConfigModel,
+    BedrockGuardrailStreamingParams,
     Guardrail,
     GuardrailEventHooks,
     GuardrailInfoResponse,
@@ -1959,7 +1960,10 @@ async def get_provider_specific_params():
     ```
     """
     # Get fields from the models
-    bedrock_fields: Final = _get_fields_from_model(BedrockGuardrailConfigModel)
+    bedrock_fields: Final = {
+        **_get_fields_from_model(BedrockGuardrailConfigModel),
+        **_get_fields_from_model(BedrockGuardrailStreamingParams),
+    }
     presidio_fields: Final = _get_fields_from_model(PresidioPresidioConfigModelUserInterface)
     lakera_v2_fields: Final = _get_fields_from_model(LakeraV2GuardrailConfigModel)
     tool_permission_fields: Final = _get_fields_from_model(ToolPermissionGuardrailConfigModel)
diff --git a/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py b/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py
index db68c7b5c3f..434c52ca6f3 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/bedrock_guardrails.py
@@ -330,7 +330,11 @@ class BedrockGuardrail(CustomGuardrail, BaseAWSLLM):
         self._set_streaming_params(BedrockGuardrailStreamingParams.from_extras(litellm_params.model_extra))
 
     def _streams_incrementally(self) -> bool:
-        return not self.streaming_buffer_until_moderated and not self.mask_response_content
+        if self.mask_response_content:
+            return False
+        if not self.streaming_buffer_until_moderated:
+            return True
+        return self.streaming_buffer_release_on_scan and not self.streaming_end_of_stream_only
 
     @classmethod
     def get_supported_event_hooks(cls) -> list[GuardrailEventHooks]:
diff --git a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
index 70dc6eec24c..5ac9070faa6 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
@@ -1032,6 +1032,7 @@ class UnifiedLLMGuardrails(CustomLogger):
         # message (True) vs emit a standalone block message (False, buffered).
         chunks_yielded = False
         last_scan_key: StreamingScanKey | None = None  # rebind-ok: replaced after every scan round
+        tool_calls_in_flight = False  # rebind-ok: tracks the latest scan key's unscanned tool calls
 
         async for item in response:
             chunk_counter += 1
@@ -1079,6 +1080,9 @@ class UnifiedLLMGuardrails(CustomLogger):
             if chunk_counter % sampling_rate == 0:
                 endpoint_translation = mappings[CallTypes(call_type)]()
                 scan_key = endpoint_translation.get_streaming_scan_key(responses_so_far)
+                if scan_key is not None:
+                    tool_calls_in_flight = scan_key.tool_calls_in_flight
+                hold_window = buffer_until_moderated and tool_calls_in_flight
                 if _is_redundant_scan(scan_key, last_scan_key):
                     verbose_proxy_logger.debug(
                         "Skipping streaming chunk %s for guardrail %s: nothing new to scan since the last round",
@@ -1086,6 +1090,8 @@ class UnifiedLLMGuardrails(CustomLogger):
                         guardrail_to_apply.guardrail_name,
                     )
                     if buffer_until_moderated:
+                        if hold_window:
+                            continue
                         for withheld_item in withheld_items:
                             chunks_yielded = True
                             responses_yielded.append(withheld_item)
@@ -1151,6 +1157,14 @@ class UnifiedLLMGuardrails(CustomLogger):
                     return
                 if scan_key is not None:
                     last_scan_key = scan_key
+                if hold_window:
+                    verbose_proxy_logger.debug(
+                        "Holding %s buffered chunks for guardrail %s: streamed tool calls await the end-of-stream scan",
+                        len(withheld_items),
+                        guardrail_to_apply.guardrail_name,
+                    )
+                    withheld_items[:] = original_items
+                    continue
                 for original_item in original_items:
                     chunks_yielded = True
                     responses_yielded.append(original_item)
diff --git a/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py b/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py
index 7522e9a62e5..cb18a5f192c 100644
--- a/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py
+++ b/tests/test_litellm/llms/anthropic/chat/guardrail_translation/test_anthropic_guardrail_handler.py
@@ -2482,7 +2482,10 @@ class TestAnthropicMessagesHandlerStreamingScanKey:
         open_key = handler.get_streaming_scan_key([self._text_delta("hi"), tool_use])
         ended_key = handler.get_streaming_scan_key([self._text_delta("hi"), tool_use, self._stop("tool_use")])
         assert open_key == StreamingScanKey(texts=("hi",))
+        assert open_key.tool_calls_in_flight is True
+        assert handler.get_streaming_scan_key([self._text_delta("hi")]).tool_calls_in_flight is False
         assert len(ended_key.tool_calls) == 1 and "get_weather" in ended_key.tool_calls[0]
+        assert ended_key.tool_calls_in_flight is False
         assert ended_key != open_key
 
 
diff --git a/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py b/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py
index cb884fb7cc1..0e59e1d1590 100644
--- a/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py
+++ b/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py
@@ -2206,8 +2206,11 @@ class TestStreamingScanKey:
             [self._chunk("hi"), tool_chunk, self._chunk(None, finish_reason="stop")]
         )
         assert open_key == StreamingScanKey(texts=("hi",))
+        assert open_key.tool_calls_in_flight is True
+        assert handler.get_streaming_scan_key([self._chunk("hi")]).tool_calls_in_flight is False
         assert ended_key.texts == ("hi",)
         assert len(ended_key.tool_calls) == 1 and "get_weather" in ended_key.tool_calls[0]
+        assert ended_key.tool_calls_in_flight is False
         assert ended_key != open_key
 
     def test_text_after_the_first_choice_finishes_still_changes_the_key(self):
diff --git a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
index 48d86384633..60375b03404 100644
--- a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
+++ b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
@@ -3211,3 +3211,24 @@ class TestOpenAIResponsesHandlerStreamingScanKey:
     def test_output_item_done_round_is_never_deduped(self):
         done = {"type": "response.output_item.done", "sequence_number": 1, "item": {"type": "function_call"}}
         assert OpenAIResponsesHandler().get_streaming_scan_key([self._delta(0, "hi"), done]) is None
+
+    def test_streamed_tool_call_events_flag_tool_calls_in_flight_until_the_stream_ends(self):
+        handler = OpenAIResponsesHandler()
+        added = {
+            "type": "response.output_item.added",
+            "sequence_number": 1,
+            "item": {"type": "function_call", "id": "fc_1", "call_id": "call_1", "name": "get_weather"},
+        }
+        arguments_delta = {
+            "type": "response.function_call_arguments.delta",
+            "sequence_number": 2,
+            "item_id": "fc_1",
+            "delta": '{"city":',
+        }
+        function_call = {"type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{}"}
+        assert handler.get_streaming_scan_key([self._delta(0, "hi")]).tool_calls_in_flight is False
+        assert handler.get_streaming_scan_key([self._delta(0, "hi"), added]).tool_calls_in_flight is True
+        assert handler.get_streaming_scan_key([self._delta(0, "hi"), arguments_delta]).tool_calls_in_flight is True
+        ended_key = handler.get_streaming_scan_key([self._delta(0, "hi"), added, self._completed(3, [function_call])])
+        assert ended_key.tool_calls_in_flight is False
+        assert len(ended_key.tool_calls) == 1
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py
index dc275c912c8..1d3d7a452b6 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_bedrock_guardrails.py
@@ -5724,6 +5724,44 @@ async def test_buffered_default_hook_scans_before_any_chunk():
     assert len([e for e in events if e != "scan"]) >= 1
 
 
+@pytest.mark.asyncio
+async def test_buffered_release_on_scan_hook_releases_each_window_after_its_scan():
+    guardrail = BedrockGuardrail(
+        guardrail_name="bedrock-release-on-scan",
+        guardrailIdentifier="test-id",
+        guardrailVersion="DRAFT",
+        event_hook=GuardrailEventHooks.post_call,
+        default_on=True,
+        streaming_buffer_release_on_scan=True,
+        streaming_sampling_rate=1,
+    )
+
+    assert guardrail._streams_incrementally() is True
+    events = await _run_streaming_hook_recording_order(guardrail)
+
+    assert events == ["scan", ("chunk", "Hello"), "scan", ("chunk", " world"), ("chunk", "")]
+
+
+@pytest.mark.asyncio
+async def test_buffered_release_on_scan_defers_to_end_of_stream_only():
+    guardrail = BedrockGuardrail(
+        guardrail_name="bedrock-release-on-scan-end-only",
+        guardrailIdentifier="test-id",
+        guardrailVersion="DRAFT",
+        event_hook=GuardrailEventHooks.post_call,
+        default_on=True,
+        streaming_buffer_release_on_scan=True,
+        streaming_end_of_stream_only=True,
+        streaming_sampling_rate=1,
+    )
+
+    assert guardrail._streams_incrementally() is False
+    events = await _run_streaming_hook_recording_order(guardrail)
+
+    assert events.count("scan") == 1
+    assert events[0] == "scan"
+
+
 @pytest.mark.asyncio
 async def test_masking_keeps_buffered_path_even_when_unbuffered_configured():
     guardrail = BedrockGuardrail(
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
index 89d51866533..cbc17e680f0 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
@@ -23,10 +23,18 @@ from litellm.proxy._types import UserAPIKeyAuth
 from litellm.proxy.guardrails.guardrail_hooks.unified_guardrail.unified_guardrail import (
     UnifiedLLMGuardrails,
 )
-from litellm.types.utils import Delta, GenericGuardrailAPIInputs, ModelResponseStream, StreamingChoices
+from litellm.types.utils import (
+    ChatCompletionDeltaToolCall,
+    Delta,
+    Function,
+    GenericGuardrailAPIInputs,
+    ModelResponseStream,
+    StreamingChoices,
+)
 
 BLOCK_MESSAGE = "Blocked by policy: this response was withheld."
 ORIGINAL_MARKER = "ORIGINAL-SECRET-ANSWER"
+TOOL_ARGUMENTS_MARKER = "TOOL-ARGS-SECRET"
 
 
 class _BlockingGuardrail(CustomGuardrail):
@@ -76,6 +84,24 @@ class _CountingPassingGuardrail(_PassingGuardrail):
         return inputs
 
 
+class _ToolCallRecordingGuardrail(_CountingPassingGuardrail):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.tool_call_scan_indexes: List[int] = []
+
+    async def apply_guardrail(
+        self,
+        inputs: GenericGuardrailAPIInputs,
+        request_data: dict,
+        input_type: Literal["request", "response"],
+        logging_obj: Optional[Any] = None,
+    ) -> GenericGuardrailAPIInputs:
+        self.scan_count += 1
+        if inputs.get("tool_calls"):
+            self.tool_call_scan_indexes.append(self.scan_count)
+        return inputs
+
+
 class _SecondScanBlockingGuardrail(_CountingPassingGuardrail):
     async def apply_guardrail(
         self,
@@ -165,20 +191,63 @@ def _chat_chunk(content: str = "", finish_reason: str | None = None) -> ModelRes
     )
 
 
+def _tool_call_chunk(arguments: str, finish_reason: str | None = None) -> ModelResponseStream:
+    return ModelResponseStream(
+        id="chatcmpl-windowed",
+        created=1724900000,
+        model="gpt-4",
+        choices=[
+            StreamingChoices(
+                index=0,
+                delta=Delta(
+                    role="assistant",
+                    content=None,
+                    tool_calls=[
+                        ChatCompletionDeltaToolCall(
+                            id="call_1",
+                            type="function",
+                            index=0,
+                            function=Function(name="run_shell", arguments=arguments),
+                        )
+                    ],
+                ),
+                finish_reason=finish_reason,
+            )
+        ],
+    )
+
+
 async def _windowed_chat_stream(
-    yielded_count: List[int], collected: List[Any], content_chunks: List[str]
+    yielded_count: List[int],
+    collected: List[Any],
+    content_chunks: List[str],
+    tool_argument_chunks: List[str] | None = None,
 ) -> AsyncGenerator[ModelResponseStream, None]:
     for content in content_chunks:
         yielded_count.append(len(collected))
         yield _chat_chunk(content)
+    for arguments in tool_argument_chunks or []:
+        yielded_count.append(len(collected))
+        yield _tool_call_chunk(arguments)
     yielded_count.append(len(collected))
-    yield _chat_chunk(finish_reason="stop")
+    yield _chat_chunk(finish_reason="tool_calls" if tool_argument_chunks else "stop")
+
+
+def _tool_argument_text(chunks: List[Any]) -> str:
+    return "".join(
+        tool_call.function.arguments or ""
+        for chunk in chunks
+        if isinstance(chunk, ModelResponseStream)
+        for choice in chunk.choices
+        for tool_call in choice.delta.tool_calls or []
+    )
 
 
 async def _run_windowed(
     guardrail: CustomGuardrail,
     content_chunks: List[str],
     end_of_stream_only: bool = False,
+    tool_argument_chunks: List[str] | None = None,
 ) -> tuple[List[Any], List[int]]:
     guardrail.streaming_buffer_until_moderated = True
     guardrail.streaming_buffer_release_on_scan = True
@@ -195,7 +264,7 @@ async def _run_windowed(
     yielded_count: List[int] = []
     async for chunk in unified.async_post_call_streaming_iterator_hook(
         user_api_key_dict=user_api_key_dict,
-        response=_windowed_chat_stream(yielded_count, collected, content_chunks),
+        response=_windowed_chat_stream(yielded_count, collected, content_chunks, tool_argument_chunks),
         request_data=request_data,
     ):
         collected.append(chunk)
@@ -282,6 +351,20 @@ async def test_windowed_buffer_drops_blocked_window():
     assert '"error"' not in raw
 
 
+@pytest.mark.asyncio
+async def test_windowed_buffer_holds_tool_call_windows_until_end_of_stream_scan():
+    guardrail = _ToolCallRecordingGuardrail(guardrail_name="windowed-tools", event_hook="post_call")
+    content_chunks = ["one ", "two ", "three "]
+    tool_argument_chunks = ['{"cmd": "', TOOL_ARGUMENTS_MARKER, '"}']
+
+    collected, yielded_count = await _run_windowed(guardrail, content_chunks, tool_argument_chunks=tool_argument_chunks)
+
+    assert yielded_count == [0, 0, 2, 2, 2, 2, 2]
+    assert _chat_text(collected) == "".join(content_chunks)
+    assert _tool_argument_text(collected) == "".join(tool_argument_chunks)
+    assert guardrail.tool_call_scan_indexes == [guardrail.scan_count]
+
+
 @pytest.mark.asyncio
 async def test_windowed_buffer_with_explicit_end_of_stream_only_stays_fully_buffered():
     guardrail = _CountingPassingGuardrail(guardrail_name="windowed-eos", event_hook="post_call")
diff --git a/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py b/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py
index 530f8ffd854..bf641fd6cd0 100644
--- a/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py
+++ b/tests/test_litellm/proxy/guardrails/test_guardrail_endpoints.py
@@ -682,6 +682,22 @@ async def test_provider_specific_params_includes_embedding_toggle():
         assert field["default_value"] is False
 
 
+@pytest.mark.asyncio
+async def test_provider_specific_params_exposes_bedrock_streaming_flags():
+    from litellm.proxy.guardrails.guardrail_endpoints import get_provider_specific_params
+
+    provider_params = await get_provider_specific_params()
+
+    bedrock = provider_params["bedrock"]
+    assert "guardrailIdentifier" in bedrock
+    assert "guardrailVersion" in bedrock
+    assert bedrock["streaming_buffer_release_on_scan"]["type"] == "boolean"
+    assert bedrock["streaming_buffer_release_on_scan"]["default_value"] is False
+    assert bedrock["streaming_buffer_until_moderated"]["default_value"] is True
+    assert bedrock["streaming_end_of_stream_only"]["type"] == "boolean"
+    assert bedrock["streaming_sampling_rate"]["type"] == "number"
+
+
 @pytest.mark.asyncio
 async def test_provider_specific_params_includes_hide_secrets():
     """hide-secrets lives in the enterprise package so it is not in

From 7cd6869cfaf7f4c84995a8b878800ac73eac65aa Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Wed, 16 Sep 2026 18:40:10 +0000
Subject: [PATCH 48/76] test(ui): match skill source links by exact name so
 codeql stops flagging the host regexes

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../components/claude_code_plugins/skill_detail.test.tsx    | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
index 2f600397a4b..1ec1f72f4a1 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/skill_detail.test.tsx
@@ -15,7 +15,7 @@ const buildSkill = (source: Plugin["source"]): Plugin => ({
 describe("SkillDetail source", () => {
   it("links a github source to the repository", () => {
     render(<SkillDetail skill={buildSkill({ source: "github", repo: "org/repo" })} onBack={vi.fn()} />);
-    expect(screen.getByRole("link", { name: /github.com\/org\/repo/ })).toHaveAttribute(
+    expect(screen.getByRole("link", { name: "github.com/org/repo" })).toHaveAttribute(
       "href",
       "https://github.com/org/repo",
     );
@@ -26,7 +26,7 @@ describe("SkillDetail source", () => {
       <SkillDetail skill={buildSkill({ source: "url", url: "git@ghe.example.com:org/repo.git" })} onBack={vi.fn()} />,
     );
     expect(screen.getByText("git@ghe.example.com:org/repo.git")).toBeInTheDocument();
-    expect(screen.queryByRole("link", { name: /ghe.example.com/ })).not.toBeInTheDocument();
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
   });
 
   it("renders an ssh git-subdir source as plain text without a tree path", () => {
@@ -37,6 +37,6 @@ describe("SkillDetail source", () => {
       />,
     );
     expect(screen.getByText("git@ghe.example.com:org/repo.git @ plugins/x")).toBeInTheDocument();
-    expect(screen.queryByRole("link", { name: /ghe.example.com/ })).not.toBeInTheDocument();
+    expect(screen.queryByRole("link")).not.toBeInTheDocument();
   });
 });

From 2bb478fb59b99d3ea46e473bad44f8c2157b3430 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Wed, 16 Sep 2026 18:45:11 +0000
Subject: [PATCH 49/76] fix(ui): keep http and upper-case https skill sources
 clickable on the detail page

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../src/components/claude_code_plugins/helpers.test.ts   | 9 +++++++++
 .../src/components/claude_code_plugins/helpers.ts        | 3 ++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
index 5bf782aabf3..e40e0e0c783 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.test.ts
@@ -157,6 +157,15 @@ describe("getSourceLink", () => {
     expect(getSourceLink({ source: "github" })).toBeNull();
   });
 
+  it("keeps http and upper-case https urls registered through the api clickable", () => {
+    expect(getSourceLink({ source: "url", url: "http://git.internal.example/org/repo" })).toBe(
+      "http://git.internal.example/org/repo",
+    );
+    expect(getSourceLink({ source: "git-subdir", url: "HTTPS://gitlab.com/org/repo", path: "sub/dir" })).toBe(
+      "HTTPS://gitlab.com/org/repo",
+    );
+  });
+
   it("returns null for an ssh clone url, which is not browsable", () => {
     expect(getSourceLink({ source: "url", url: "git@ghe.example.com:org/repo.git" })).toBeNull();
     expect(getSourceLink({ source: "url", url: "ssh://git@ghe.example.com/org/repo.git" })).toBeNull();
diff --git a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
index b4d9eab08ec..8cf620d9077 100644
--- a/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
+++ b/ui/litellm-dashboard/src/components/claude_code_plugins/helpers.ts
@@ -37,6 +37,7 @@ const IPV4_HOST_REGEX = /^\d{1,3}(\.\d{1,3}){3}$/;
 const GITHUB_ORG_REGEX = /^[A-Za-z0-9-]+$/;
 const GITHUB_REPO_REGEX = /^[A-Za-z0-9._-]+$/;
 
+const BROWSABLE_URL_REGEX = /^https?:\/\//i;
 const SSH_SCHEME = "ssh://";
 const SSH_SCP_REGEX = /^([a-z0-9._-]+)@([^:/@]+):(?!\/)(.+)$/i;
 
@@ -316,7 +317,7 @@ export const getSourceLink = (source: PluginSource): string | null => {
     return `https://github.com/${source.repo}`;
   }
   const linksToUrl = source.source === "url" || source.source === "git-subdir" || source.source === "archive";
-  return linksToUrl && source.url?.startsWith("https://") ? source.url : null;
+  return linksToUrl && source.url && BROWSABLE_URL_REGEX.test(source.url) ? source.url : null;
 };
 
 /**

From ad25fe1886e0444b32d9acef2844c94eb7e4f20d Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 18:56:56 +0000
Subject: [PATCH 50/76] fix(guardrails): hold unscannable Responses windows and
 key terminal envelopes by output items

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../guardrail_translation/handler.py          |   6 +-
 .../unified_guardrail/unified_guardrail.py    |   4 +-
 ...test_openai_responses_guardrail_handler.py |  18 +++
 .../test_streaming_buffer_until_moderated.py  | 125 ++++++++++++++++++
 4 files changed, 147 insertions(+), 6 deletions(-)

diff --git a/litellm/llms/openai/responses/guardrail_translation/handler.py b/litellm/llms/openai/responses/guardrail_translation/handler.py
index 321f0a0d6d3..1ab4811b8a0 100644
--- a/litellm/llms/openai/responses/guardrail_translation/handler.py
+++ b/litellm/llms/openai/responses/guardrail_translation/handler.py
@@ -1175,13 +1175,11 @@ class OpenAIResponsesHandler(BaseTranslation):
         last_event_type: Final = stream_item_field(last_event, "type")
         if last_event_type == ResponsesAPIStreamEvents.OUTPUT_ITEM_DONE.value:
             return None
-        if last_event_type == ResponsesAPIStreamEvents.RESPONSE_COMPLETED.value:
+        if last_event_type in _TERMINAL_ENVELOPE_EVENT_TYPES:
             return self._completed_response_scan_key(stream_item_field(last_event, "response"))
-        stream_ended: Final = self._check_streaming_has_ended(responses_so_far)
         return StreamingScanKey(
             texts=(self.get_streaming_string_so_far(responses_so_far),),
-            stream_ended=stream_ended,
-            tool_calls_in_flight=not stream_ended and self._has_streamed_tool_call_events(responses_so_far),
+            tool_calls_in_flight=self._has_streamed_tool_call_events(responses_so_far),
         )
 
     @staticmethod
diff --git a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
index 5ac9070faa6..15757681d38 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
@@ -1082,7 +1082,7 @@ class UnifiedLLMGuardrails(CustomLogger):
                 scan_key = endpoint_translation.get_streaming_scan_key(responses_so_far)
                 if scan_key is not None:
                     tool_calls_in_flight = scan_key.tool_calls_in_flight
-                hold_window = buffer_until_moderated and tool_calls_in_flight
+                hold_window = buffer_until_moderated and (scan_key is None or tool_calls_in_flight)
                 if _is_redundant_scan(scan_key, last_scan_key):
                     verbose_proxy_logger.debug(
                         "Skipping streaming chunk %s for guardrail %s: nothing new to scan since the last round",
@@ -1159,7 +1159,7 @@ class UnifiedLLMGuardrails(CustomLogger):
                     last_scan_key = scan_key
                 if hold_window:
                     verbose_proxy_logger.debug(
-                        "Holding %s buffered chunks for guardrail %s: streamed tool calls await the end-of-stream scan",
+                        "Holding %s buffered chunks for guardrail %s: this round could not scan the whole window",
                         len(withheld_items),
                         guardrail_to_apply.guardrail_name,
                     )
diff --git a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
index 60375b03404..c714b5d378a 100644
--- a/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
+++ b/tests/test_litellm/llms/openai/responses/test_openai_responses_guardrail_handler.py
@@ -3212,6 +3212,24 @@ class TestOpenAIResponsesHandlerStreamingScanKey:
         done = {"type": "response.output_item.done", "sequence_number": 1, "item": {"type": "function_call"}}
         assert OpenAIResponsesHandler().get_streaming_scan_key([self._delta(0, "hi"), done]) is None
 
+    @pytest.mark.parametrize("terminal_type", ["response.incomplete", "response.failed"])
+    def test_non_completed_terminal_envelopes_key_their_output_items(self, terminal_type):
+        handler = OpenAIResponsesHandler()
+        arguments_delta = {
+            "type": "response.function_call_arguments.delta",
+            "sequence_number": 1,
+            "item_id": "fc_1",
+            "delta": '{"city":',
+        }
+        function_call = {"type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": '{"city":'}
+        terminal = {"type": terminal_type, "sequence_number": 2, "response": {"id": "resp_1", "output": [function_call]}}
+        mid_stream_key = handler.get_streaming_scan_key([arguments_delta])
+        ended_key = handler.get_streaming_scan_key([arguments_delta, terminal])
+        assert ended_key.stream_ended is True
+        assert ended_key.tool_calls_in_flight is False
+        assert len(ended_key.tool_calls) == 1
+        assert ended_key != mid_stream_key
+
     def test_streamed_tool_call_events_flag_tool_calls_in_flight_until_the_stream_ends(self):
         handler = OpenAIResponsesHandler()
         added = {
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
index cbc17e680f0..ed548155b60 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
@@ -121,6 +121,32 @@ class _SecondScanBlockingGuardrail(_CountingPassingGuardrail):
         return inputs
 
 
+class _MarkerBlockingGuardrail(_CountingPassingGuardrail):
+    """Blocks as soon as the inspected input field (texts or tool_calls) carries the marker."""
+
+    def __init__(self, *args, marker: str, field: Literal["texts", "tool_calls"] = "texts", **kwargs):
+        super().__init__(*args, **kwargs)
+        self.marker = marker
+        self.field = field
+
+    async def apply_guardrail(
+        self,
+        inputs: GenericGuardrailAPIInputs,
+        request_data: dict,
+        input_type: Literal["request", "response"],
+        logging_obj: Optional[Any] = None,
+    ) -> GenericGuardrailAPIInputs:
+        self.scan_count += 1
+        if self.marker in json.dumps(inputs.get(self.field, [])):
+            raise ModifyResponseException(
+                message=BLOCK_MESSAGE,
+                model="gpt-4o",
+                request_data=request_data,
+                guardrail_name=self.guardrail_name,
+            )
+        return inputs
+
+
 def _sse_event(event_type: str, data: dict) -> bytes:
     return f"event: {event_type}\ndata: {json.dumps(data)}\n\n".encode()
 
@@ -271,6 +297,76 @@ async def _run_windowed(
     return collected, yielded_count
 
 
+def _responses_message_stream_events(text_chunks: List[str]) -> List[dict]:
+    message = {"type": "message", "id": "msg_1", "status": "completed", "role": "assistant"}
+    content = [{"type": "output_text", "text": "".join(text_chunks), "annotations": []}]
+    return [
+        {"type": "response.output_item.added", "output_index": 0, "item": {**message, "content": []}},
+        *(
+            {"type": "response.output_text.delta", "item_id": "msg_1", "output_index": 0, "content_index": 0, "delta": text}
+            for text in text_chunks
+        ),
+        {"type": "response.output_item.done", "output_index": 0, "item": {**message, "content": content}},
+        {
+            "type": "response.completed",
+            "response": {"id": "resp_1", "model": "gpt-4o", "status": "completed", "output": [{**message, "content": content}]},
+        },
+    ]
+
+
+def _responses_truncated_function_call_events(text: str, argument_chunks: List[str]) -> List[dict]:
+    message = {"type": "message", "id": "msg_1", "status": "completed", "role": "assistant"}
+    content = [{"type": "output_text", "text": text, "annotations": []}]
+    function_call = {"type": "function_call", "id": "fc_1", "call_id": "call_1", "name": "run_shell"}
+    return [
+        {"type": "response.output_item.added", "output_index": 0, "item": {**message, "content": []}},
+        {"type": "response.output_text.delta", "item_id": "msg_1", "output_index": 0, "content_index": 0, "delta": text},
+        {"type": "response.output_item.added", "output_index": 1, "item": {**function_call, "arguments": ""}},
+        *(
+            {"type": "response.function_call_arguments.delta", "item_id": "fc_1", "output_index": 1, "delta": arguments}
+            for arguments in argument_chunks
+        ),
+        {
+            "type": "response.incomplete",
+            "response": {
+                "id": "resp_1",
+                "model": "gpt-4o",
+                "status": "incomplete",
+                "output": [
+                    {**message, "content": content},
+                    {**function_call, "arguments": "".join(argument_chunks), "status": "incomplete"},
+                ],
+            },
+        },
+    ]
+
+
+async def _replay(events: List[dict]) -> AsyncGenerator[dict, None]:
+    for event in events:
+        yield event
+
+
+async def _run_windowed_responses(guardrail: CustomGuardrail, events: List[dict]) -> str:
+    guardrail.streaming_buffer_until_moderated = True
+    guardrail.streaming_buffer_release_on_scan = True
+    guardrail.streaming_sampling_rate = 2
+    unified = UnifiedLLMGuardrails()
+    user_api_key_dict = UserAPIKeyAuth(api_key="test", request_route="/v1/responses")
+    request_data = {
+        "input": "hi",
+        "guardrail_to_apply": guardrail,
+        "metadata": {"guardrails": [guardrail.guardrail_name]},
+    }
+    collected: List[Any] = []
+    async for chunk in unified.async_post_call_streaming_iterator_hook(
+        user_api_key_dict=user_api_key_dict,
+        response=_replay(events),
+        request_data=request_data,
+    ):
+        collected.append(chunk)
+    return json.dumps([chunk if isinstance(chunk, dict) else str(chunk) for chunk in collected])
+
+
 def _chat_text(chunks: List[Any]) -> str:
     return "".join(
         choice.delta.content or ""
@@ -365,6 +461,35 @@ async def test_windowed_buffer_holds_tool_call_windows_until_end_of_stream_scan(
     assert guardrail.tool_call_scan_indexes == [guardrail.scan_count]
 
 
+@pytest.mark.asyncio
+async def test_windowed_responses_output_item_done_round_keeps_text_window_withheld():
+    guardrail = _MarkerBlockingGuardrail(guardrail_name="windowed-responses", event_hook="post_call", marker=ORIGINAL_MARKER)
+    events = _responses_message_stream_events(["one ", f"{ORIGINAL_MARKER} "])
+
+    raw = await _run_windowed_responses(guardrail, events)
+
+    assert ORIGINAL_MARKER not in raw, f"unscanned window leaked: {raw!r}"
+    assert BLOCK_MESSAGE in raw
+    assert guardrail.scan_count >= 1
+
+
+@pytest.mark.asyncio
+async def test_windowed_responses_incomplete_stream_scans_tool_call_before_release():
+    guardrail = _MarkerBlockingGuardrail(
+        guardrail_name="windowed-responses-tools",
+        event_hook="post_call",
+        marker=TOOL_ARGUMENTS_MARKER,
+        field="tool_calls",
+    )
+    events = _responses_truncated_function_call_events("hi ", ['{"cmd": "', TOOL_ARGUMENTS_MARKER, '"}'])
+
+    raw = await _run_windowed_responses(guardrail, events)
+
+    assert '"hi "' in raw
+    assert TOOL_ARGUMENTS_MARKER not in raw, f"unscanned tool call leaked: {raw!r}"
+    assert BLOCK_MESSAGE in raw
+
+
 @pytest.mark.asyncio
 async def test_windowed_buffer_with_explicit_end_of_stream_only_stays_fully_buffered():
     guardrail = _CountingPassingGuardrail(guardrail_name="windowed-eos", event_hook="post_call")

From d5837ab97a91e59e58f24c39979d0af0a827fe0f Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 19:24:14 +0000
Subject: [PATCH 51/76] test(guardrails): pin tool-call-only scan keys as
 non-empty

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../test_streaming_buffer_until_moderated.py               | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
index ed548155b60..318488c6d7b 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
@@ -19,9 +19,11 @@ from litellm.integrations.custom_guardrail import (
     CustomGuardrail,
     ModifyResponseException,
 )
+from litellm.llms.base_llm.guardrail_translation.base_translation import StreamingScanKey
 from litellm.proxy._types import UserAPIKeyAuth
 from litellm.proxy.guardrails.guardrail_hooks.unified_guardrail.unified_guardrail import (
     UnifiedLLMGuardrails,
+    _is_redundant_scan,
 )
 from litellm.types.utils import (
     ChatCompletionDeltaToolCall,
@@ -461,6 +463,11 @@ async def test_windowed_buffer_holds_tool_call_windows_until_end_of_stream_scan(
     assert guardrail.tool_call_scan_indexes == [guardrail.scan_count]
 
 
+def test_tool_call_only_scan_key_is_not_skipped_as_empty():
+    assert _is_redundant_scan(StreamingScanKey(texts=("",)), None) is True
+    assert _is_redundant_scan(StreamingScanKey(texts=("",), tool_calls=("run_shell:{}",)), None) is False
+
+
 @pytest.mark.asyncio
 async def test_windowed_responses_output_item_done_round_keeps_text_window_withheld():
     guardrail = _MarkerBlockingGuardrail(guardrail_name="windowed-responses", event_hook="post_call", marker=ORIGINAL_MARKER)

From 1e169bb912c9a28b3577aca0e0115caa686299b7 Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 19:33:07 +0000
Subject: [PATCH 52/76] refactor(guardrails): mark release_on_scan flag as
 Final

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../guardrail_hooks/unified_guardrail/unified_guardrail.py      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
index 15757681d38..7f51d733d4c 100644
--- a/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
+++ b/litellm/proxy/guardrails/guardrail_hooks/unified_guardrail/unified_guardrail.py
@@ -956,7 +956,7 @@ class UnifiedLLMGuardrails(CustomLogger):
         buffer_until_moderated: bool = _streaming_flag(
             "streaming_buffer_until_moderated", buffer_until_moderated_default
         )
-        release_on_scan: bool = _streaming_flag("streaming_buffer_release_on_scan", False)
+        release_on_scan: Final[bool] = _streaming_flag("streaming_buffer_release_on_scan", False)
 
         if (
             buffer_until_moderated

From 39acea0754e0dd5f291e8f99126b1e0b3f5505b3 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 12:42:15 -0700
Subject: [PATCH 53/76] feat(e2e): make Claude Code send the same bytes every
 build

The compat cells drove the CLI with a fresh HOME per invocation and the
pytest process's own working directory, and both reach the request body.
The system prompt names a memory directory built from
$CLAUDE_CONFIG_DIR/projects/<cwd slug>, so a per-invocation config
directory rewrote every body, and the CLI adds a git block for its
working directory, so inheriting the checkout rewrote every body once
per candidate. The device id churned for the same reason: the CLI mints
it once and persists it in .claude.json, which we threw away each call.

Nothing here was load-bearing. All three ride in metadata.user_id, whose
job is abuse detection, not quota, caching or continuity. So pin the
config directory and the working directory at fixed paths, seed the
device id, and pin the session id.

HOME stays fresh and empty per invocation, so the isolation is no weaker
than before, and the CLI's own state no longer outlives the pod either.
The working directory is deliberately not the checkout, so a
model-directed Read now sees an empty directory rather than the
repository.

A pinned session id needs --no-session-persistence beside it: the CLI
refuses a session id another live process holds, and the matrix runs its
cells across xdist workers. Without the flag, six of eight concurrent
invocations die on "Session ID is already in use".
---
 .../test_request_determinism.py               | 143 ++++++++++++++++++
 tests/e2e/claude_code/cli_driver.py           |  57 +++++++
 2 files changed, 200 insertions(+)
 create mode 100644 tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py

diff --git a/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py b/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
new file mode 100644
index 00000000000..09a181162d2
--- /dev/null
+++ b/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
@@ -0,0 +1,143 @@
+"""The CLI must send the same request bytes from one build to the next.
+
+Markerless harness test: it drives the real `claude` binary against a local
+stub instead of a proxy, so it carries no `e2e` marker. The binary is a
+prerequisite of this whole suite, so a missing one is a failure rather than a
+skip.
+
+Two builds differ in ways the driver does not control: a fresh pod, so no CLI
+state survives, and a different candidate checked out at a different commit.
+Both used to reach the request body, through the memory path the system prompt
+names and through the git block the CLI adds for its working directory, so the
+shared provider cache missed on every Claude Code cell. This replays those two
+differences across a pair of invocations and holds the bytes equal.
+
+A pinned session id is what makes the second test necessary. The matrix runs
+its cells across xdist workers, and the CLI refuses to start a session id that
+another live process already holds, so pinning one without also opting out of
+session persistence turns most of a parallel run red.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import threading
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import List, Tuple
+
+import pytest
+
+from claude_code.cli_driver import _stable_cli_state, run_claude
+from claude_code.rate_limiter import RateLimiter
+
+_STUB_REPLY = {
+    "id": "msg_stub",
+    "type": "message",
+    "role": "assistant",
+    "model": "claude-haiku-4-5",
+    "content": [{"type": "text", "text": "ok"}],
+    "stop_reason": "end_turn",
+    "usage": {"input_tokens": 10, "output_tokens": 2},
+}
+
+
+def _make_repo(root: Path, subject: str) -> Path:
+    root.mkdir(parents=True, exist_ok=True)
+    identity = {"NAME": "t", "EMAIL": "t@e2e"}
+    env = dict(
+        os.environ,
+        **{f"GIT_{role}_{key}": value for role in ("AUTHOR", "COMMITTER") for key, value in identity.items()},
+    )
+    (root / "file.txt").write_text(subject, encoding="utf-8")
+    for args in (["init", "-q"], ["add", "."], ["commit", "-q", "-m", subject]):
+        subprocess.run(["git", *args], cwd=root, env=env, check=True, capture_output=True)
+    return root
+
+
+@pytest.fixture(name="captured")
+def _captured() -> Tuple[str, List[bytes]]:
+    bodies: List[bytes] = []
+    lock = threading.Lock()
+
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def do_POST(self) -> None:
+            raw = self.rfile.read(int(self.headers.get("content-length") or 0))
+            if "count_tokens" not in self.path:
+                with lock:
+                    bodies.append(raw)
+            payload = json.dumps({"input_tokens": 10} if "count_tokens" in self.path else _STUB_REPLY).encode()
+            self.send_response(200)
+            self.send_header("content-type", "application/json")
+            self.send_header("content-length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+
+        def log_message(self, *_args: object) -> None:
+            return
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    try:
+        yield f"http://127.0.0.1:{server.server_address[1]}", bodies
+    finally:
+        server.shutdown()
+
+
+def test_two_builds_send_the_same_request_bytes(captured: Tuple[str, List[bytes]], tmp_path: Path) -> None:
+    base_url, bodies = captured
+    limiter = RateLimiter(state_dir=tmp_path / "limiter")
+    checkouts = (_make_repo(tmp_path / "build-1", "first"), _make_repo(tmp_path / "build-2", "second"))
+    origin = Path.cwd()
+
+    sent = []
+    for checkout in checkouts:
+        shutil.rmtree(Path(_stable_cli_state()[0]).parent, ignore_errors=True)
+        os.chdir(checkout)
+        try:
+            before = len(bodies)
+            run_claude(
+                prompt="say ok",
+                model="claude-haiku-4-5",
+                base_url=base_url,
+                api_key="stub",
+                extra_env={"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"},
+                rate_limiter=limiter,
+            )
+            sent.append(bodies[before:])
+        finally:
+            os.chdir(origin)
+
+    assert sent[0], "the CLI sent no request to the stub, so there is nothing to compare"
+    assert sent[0] == sent[1]
+
+
+def test_concurrent_cells_do_not_collide_on_the_pinned_session(
+    captured: Tuple[str, List[bytes]], tmp_path: Path
+) -> None:
+    base_url, bodies = captured
+    limiter = RateLimiter(state_dir=tmp_path / "limiter")
+
+    def one(_index: int) -> int:
+        return run_claude(
+            prompt="say ok",
+            model="claude-haiku-4-5",
+            base_url=base_url,
+            api_key="stub",
+            extra_env={"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"},
+            rate_limiter=limiter,
+        ).exit_code
+
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        codes = list(pool.map(one, range(4)))
+
+    assert codes == [0, 0, 0, 0]
+    assert bodies, "the CLI sent no request to the stub, so there is nothing to compare"
+    assert set(Counter(bodies).values()) == {4}
diff --git a/tests/e2e/claude_code/cli_driver.py b/tests/e2e/claude_code/cli_driver.py
index 447e8cc0bbb..3fad87c7479 100644
--- a/tests/e2e/claude_code/cli_driver.py
+++ b/tests/e2e/claude_code/cli_driver.py
@@ -132,6 +132,57 @@ def _make_isolated_home() -> str:
     return tempfile.mkdtemp(prefix="claude-cli-home-")
 
 
+_FIXED_CLI_USER_ID = "0" * 64
+_FIXED_CLI_SESSION_ID = "00000000-0000-4000-8000-000000000000"
+
+
+def _seed_cli_identity(config_dir: str) -> None:
+    """Pin the device id the CLI would otherwise mint per config directory.
+
+    It mints 32 random bytes on first run, writes them to `.claude.json` as
+    `userID`, and sends them in `metadata.user_id` forever after, so the value
+    is stable for exactly as long as that file lives. Pinning it, and the
+    session id passed beside it, costs nothing: both feed abuse detection
+    rather than quota, caching or continuity."""
+    path = os.path.join(config_dir, ".claude.json")
+    try:
+        with open(path, encoding="utf-8") as handle:
+            if json.load(handle).get("userID") == _FIXED_CLI_USER_ID:
+                return
+    except (OSError, ValueError):
+        pass
+    staged = f"{path}.{os.getpid()}"
+    with open(staged, "w", encoding="utf-8") as handle:
+        json.dump({"userID": _FIXED_CLI_USER_ID}, handle)
+    os.replace(staged, path)
+
+
+def _stable_cli_state() -> Tuple[str, str]:
+    """Config directory and working directory for the CLI, at fixed paths.
+
+    Both reach the request body. The memory directory the system prompt
+    names is `$CLAUDE_CONFIG_DIR/projects/<cwd slug>/memory`, and a working
+    directory inside a git repository also contributes its branch and recent
+    commits. So a per-invocation config directory rewrites every body, and
+    inheriting the checkout rewrites every body once per candidate, which is
+    why the shared provider cache could never serve a Claude Code cell.
+    Pinning both makes the bodies repeatable across builds.
+
+    This narrows what survives rather than widening it: HOME stays fresh and
+    empty per invocation, so the isolation `_make_isolated_home` describes is
+    unchanged, and the CLI's own state no longer outlives the pod either. The
+    working directory is deliberately not the checkout, so a model-directed
+    `Read` sees an empty directory instead of the repository.
+    """
+    root = os.path.join(tempfile.gettempdir(), f"litellm-e2e-claude-{os.getuid()}")
+    config_dir = os.path.join(root, "config")
+    workspace = os.path.join(root, "workspace")
+    for path in (root, config_dir, workspace):
+        os.makedirs(path, mode=0o700, exist_ok=True)
+    _seed_cli_identity(config_dir)
+    return config_dir, workspace
+
+
 class ClaudeCLIError(RuntimeError):
     """Raised when the `claude` CLI cannot be invoked or returns a fatal error."""
 
@@ -222,6 +273,9 @@ def run_claude(
         "--verbose",
         "--model",
         model,
+        "--session-id",
+        _FIXED_CLI_SESSION_ID,
+        "--no-session-persistence",
     ]
     if extra_args:
         cmd.extend(extra_args)
@@ -244,6 +298,8 @@ def run_claude(
     # regardless of how the subprocess exits.
     isolated_home = _make_isolated_home()
     env["HOME"] = isolated_home
+    config_dir, workspace = _stable_cli_state()
+    env["CLAUDE_CONFIG_DIR"] = config_dir
     if extra_env:
         env.update(extra_env)
 
@@ -262,6 +318,7 @@ def run_claude(
             completed = run_fn(
                 cmd,
                 env=env,
+                cwd=workspace,
                 input=stdin_input,
                 capture_output=True,
                 text=True,

From 2481146727fe3b2613df96ccf8f568f5b0a3cc72 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 12:44:53 -0700
Subject: [PATCH 54/76] docs(e2e): say why the CLI-driving cells needed a
 driver fix, not a rule

---
 tests/e2e/PROVIDER_CACHE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/e2e/PROVIDER_CACHE.md b/tests/e2e/PROVIDER_CACHE.md
index e06b3c01653..d37b37eeba7 100644
--- a/tests/e2e/PROVIDER_CACHE.md
+++ b/tests/e2e/PROVIDER_CACHE.md
@@ -16,6 +16,8 @@ Requests that differ only by their markers therefore share a canonical identity,
 
 Two different tests never share a recording, and a provider call made outside any test (fixtures, session setup) is never cached, because the identity has no test node id to bind to
 
+A client that varies its own request between runs defeats that identity without breaking any rule, and the Claude Code compat cells did. The CLI sends a device id and a session id in `metadata.user_id`, and its system prompt names both its memory directory and its working directory, adding the branch and recent commits when that directory is a git repository. Driven with a fresh HOME and the checkout as its working directory, every cell sent different bytes every build. The fix belongs in the driver rather than here: `claude_code/cli_driver.py` pins the config directory, the working directory and both identifiers, which is why the cache needs no rule for any of it. Normalizing them instead would have hidden a real defect class, since a rule cannot tell a client's own churn from a value a test means to assert on
+
 Provider `Set-Cookie` headers are dropped before validation and never recorded: the edge already withholds them from the proxy, and OpenAI responses always carry Cloudflare bot-management cookies
 
 An eligible miss calls the provider. A complete successful response is stored immediately even if a later test assertion fails. Provider errors, malformed responses, truncated streams and cancelled captures are not stored. Cache reads, writes and lease failures fall through to normal provider behavior; they introduce no provider retry. An already-started response cannot be restarted after a delivery failure

From df9a87f44a09d77b10b3868700ae6569bdedb57d Mon Sep 17 00:00:00 2001
From: yucheng <yucheng@berri.ai>
Date: Wed, 16 Sep 2026 20:28:03 +0000
Subject: [PATCH 55/76] fix(otel): keep caller tracestate on the legacy request
 span

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm/integrations/opentelemetry.py         | 11 +---
 .../integrations/test_opentelemetry.py        | 59 +++++++++++++++++++
 2 files changed, 61 insertions(+), 9 deletions(-)

diff --git a/litellm/integrations/opentelemetry.py b/litellm/integrations/opentelemetry.py
index d4e7fcb577e..2623a9b5a56 100644
--- a/litellm/integrations/opentelemetry.py
+++ b/litellm/integrations/opentelemetry.py
@@ -2932,16 +2932,13 @@ class OpenTelemetry(OTELGenAISemconvMixin, CustomLogger):
         )
 
         propagator: Final = TraceContextTextMapPropagator()
-        carrier: Final = {"traceparent": _traceparent}
+        carrier: Final = {key: headers[key] for key in ("traceparent", "tracestate") if headers.get(key) is not None}
         _parent_context: Final = propagator.extract(carrier=carrier)
 
         return _parent_context
 
     def _get_span_context(self, kwargs, default_span: Span | None = None):
         from opentelemetry import context, trace
-        from opentelemetry.trace.propagation.tracecontext import (
-            TraceContextTextMapPropagator,
-        )
 
         litellm_params: Final = kwargs.get("litellm_params", {}) or {}
         proxy_server_request: Final = litellm_params.get("proxy_server_request", {}) or {}
@@ -2965,11 +2962,7 @@ class OpenTelemetry(OTELGenAISemconvMixin, CustomLogger):
         # Priority 2: HTTP traceparent header
         if traceparent is not None:
             verbose_logger.debug("OpenTelemetry: Using traceparent header for context propagation")
-            carrier: Final = {"traceparent": traceparent}
-            return (
-                TraceContextTextMapPropagator().extract(carrier=carrier),
-                None,
-            )
+            return self.get_traceparent_from_header(headers=headers), None
 
         # Priority 3: Active span from global context (auto-detection)
         try:
diff --git a/tests/test_litellm/integrations/test_opentelemetry.py b/tests/test_litellm/integrations/test_opentelemetry.py
index 9ec8489f784..443b9012235 100644
--- a/tests/test_litellm/integrations/test_opentelemetry.py
+++ b/tests/test_litellm/integrations/test_opentelemetry.py
@@ -5423,6 +5423,65 @@ class TestGetSpanContextLitellmMetadataFallback(unittest.TestCase):
         self.assertIsNone(detected_span)
 
 
+class TestInboundTraceContextKeepsCallerTracestate(unittest.TestCase):
+    """The request span built from inbound W3C headers must carry the caller's
+    tracestate so outbound propagation (passthrough) re-emits it instead of
+    dropping it alongside the stripped stale header."""
+
+    CALLER_TRACEPARENT = "00-" + "a" * 32 + "-" + "b" * 16 + "-01"
+    CALLER_TRACESTATE = "vendor=abc,other=xyz"
+
+    def _otel(self):
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(InMemorySpanExporter()))
+        otel = OpenTelemetry()
+        otel.tracer = provider.get_tracer(__name__)
+        return otel
+
+    def test_request_span_propagates_caller_tracestate_downstream(self):
+        from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+        from litellm.integrations.otel.plumbing.context import inject_trace_context
+
+        inbound = {"traceparent": self.CALLER_TRACEPARENT, "tracestate": self.CALLER_TRACESTATE}
+        span = self._otel().create_litellm_proxy_request_started_span(
+            start_time=datetime.now(timezone.utc), headers=inbound
+        )
+        outbound = inject_trace_context(inbound, parent_span=span)
+        span.end()
+
+        propagated = trace.get_current_span(TraceContextTextMapPropagator().extract(outbound)).get_span_context()
+        self.assertEqual(outbound["tracestate"], self.CALLER_TRACESTATE)
+        self.assertEqual(propagated.trace_id, span.get_span_context().trace_id)
+        self.assertEqual(propagated.span_id, span.get_span_context().span_id)
+        self.assertNotEqual(outbound["traceparent"], self.CALLER_TRACEPARENT)
+
+    def test_request_span_without_caller_tracestate_emits_none(self):
+        from litellm.integrations.otel.plumbing.context import inject_trace_context
+
+        inbound = {"traceparent": self.CALLER_TRACEPARENT}
+        span = self._otel().create_litellm_proxy_request_started_span(
+            start_time=datetime.now(timezone.utc), headers=inbound
+        )
+        outbound = inject_trace_context(inbound, parent_span=span)
+        span.end()
+
+        self.assertNotIn("tracestate", outbound)
+        self.assertNotEqual(outbound["traceparent"], self.CALLER_TRACEPARENT)
+
+    def test_span_context_from_header_keeps_caller_tracestate(self):
+        kwargs = {
+            "litellm_params": {
+                "proxy_server_request": {
+                    "headers": {"traceparent": self.CALLER_TRACEPARENT, "tracestate": self.CALLER_TRACESTATE}
+                }
+            }
+        }
+        ctx, detected_span = self._otel()._get_span_context(kwargs)
+        self.assertIsNone(detected_span)
+        self.assertEqual(trace.get_current_span(ctx).get_span_context().trace_state.to_header(), self.CALLER_TRACESTATE)
+
+
 class TestEndProxySpanLitellmMetadataFallback(unittest.TestCase):
     """
     Tests for _end_proxy_span_from_kwargs() falling back to litellm_metadata.

From 8acd2477a65cf6c36346169afd7b0c644833ab1f Mon Sep 17 00:00:00 2001
From: yassin <yassin@berri.ai>
Date: Wed, 16 Sep 2026 20:34:20 +0000
Subject: [PATCH 56/76] fix(guardrails): hold legacy function_call stream
 windows until the end-of-stream scan

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../chat/guardrail_translation/handler.py     |   8 +-
 .../test_openai_guardrail_handler.py          |  22 ++++
 .../test_streaming_buffer_until_moderated.py  | 100 +++++++++++++-----
 3 files changed, 104 insertions(+), 26 deletions(-)

diff --git a/litellm/llms/openai/chat/guardrail_translation/handler.py b/litellm/llms/openai/chat/guardrail_translation/handler.py
index 9b818696bbb..5b232dd0bf4 100644
--- a/litellm/llms/openai/chat/guardrail_translation/handler.py
+++ b/litellm/llms/openai/chat/guardrail_translation/handler.py
@@ -806,7 +806,7 @@ class OpenAIChatCompletionsHandler(BaseTranslation):
             stream_item_fingerprint(tool_call)
             for chunk in responses_so_far
             for choice in _stream_chunk_choices(chunk)
-            for tool_call in stream_item_items(stream_item_field(choice, "delta"), "tool_calls")
+            for tool_call in _streamed_delta_tool_calls(stream_item_field(choice, "delta"))
         )
 
     @staticmethod
@@ -1344,6 +1344,12 @@ def _stream_chunk_choices(item: object) -> Sequence[object]:
     return ()
 
 
+def _streamed_delta_tool_calls(delta: object) -> tuple[object, ...]:
+    function_call: Final = stream_item_field(delta, "function_call")
+    legacy: Final = () if function_call is None else (function_call,)
+    return stream_item_items(delta, "tool_calls") + legacy
+
+
 def _blocked_stream_identity(
     exc: "ModifyResponseException", responses_so_far: Sequence[object]
 ) -> tuple[str, int, str]:
diff --git a/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py b/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py
index 0e59e1d1590..9b88161aca9 100644
--- a/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py
+++ b/tests/test_litellm/llms/openai/chat/guardrail_translation/test_openai_guardrail_handler.py
@@ -2213,6 +2213,28 @@ class TestStreamingScanKey:
         assert ended_key.tool_calls_in_flight is False
         assert ended_key != open_key
 
+    def test_legacy_function_call_delta_is_held_like_a_tool_call(self):
+        from litellm.types.utils import Delta, FunctionCall, ModelResponseStream, StreamingChoices
+
+        handler = OpenAIChatCompletionsHandler()
+        function_chunk = ModelResponseStream(
+            choices=[
+                StreamingChoices(
+                    index=0,
+                    delta=Delta(content=None, function_call=FunctionCall(name="run_shell", arguments='{"cmd": "rm"}')),
+                    finish_reason=None,
+                )
+            ]
+        )
+        open_key = handler.get_streaming_scan_key([self._chunk("hi"), function_chunk])
+        ended_key = handler.get_streaming_scan_key(
+            [self._chunk("hi"), function_chunk, self._chunk(None, finish_reason="function_call")]
+        )
+        assert open_key.tool_calls_in_flight is True
+        assert open_key.tool_calls == ()
+        assert len(ended_key.tool_calls) == 1 and "run_shell" in ended_key.tool_calls[0]
+        assert ended_key.tool_calls_in_flight is False
+
     def test_text_after_the_first_choice_finishes_still_changes_the_key(self):
         handler = OpenAIChatCompletionsHandler()
         first_done = [self._chunk("a", index=0), self._chunk("b", finish_reason="stop", index=0)]
diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
index 318488c6d7b..db937f18e96 100644
--- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
+++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/unified_guardrails/test_streaming_buffer_until_moderated.py
@@ -29,6 +29,7 @@ from litellm.types.utils import (
     ChatCompletionDeltaToolCall,
     Delta,
     Function,
+    FunctionCall,
     GenericGuardrailAPIInputs,
     ModelResponseStream,
     StreamingChoices,
@@ -219,29 +220,30 @@ def _chat_chunk(content: str = "", finish_reason: str | None = None) -> ModelRes
     )
 
 
-def _tool_call_chunk(arguments: str, finish_reason: str | None = None) -> ModelResponseStream:
+def _tool_call_chunk(
+    arguments: str, finish_reason: str | None = None, legacy_function_call: bool = False
+) -> ModelResponseStream:
+    delta = (
+        Delta(role="assistant", content=None, function_call=FunctionCall(name="run_shell", arguments=arguments))
+        if legacy_function_call
+        else Delta(
+            role="assistant",
+            content=None,
+            tool_calls=[
+                ChatCompletionDeltaToolCall(
+                    id="call_1",
+                    type="function",
+                    index=0,
+                    function=Function(name="run_shell", arguments=arguments),
+                )
+            ],
+        )
+    )
     return ModelResponseStream(
         id="chatcmpl-windowed",
         created=1724900000,
         model="gpt-4",
-        choices=[
-            StreamingChoices(
-                index=0,
-                delta=Delta(
-                    role="assistant",
-                    content=None,
-                    tool_calls=[
-                        ChatCompletionDeltaToolCall(
-                            id="call_1",
-                            type="function",
-                            index=0,
-                            function=Function(name="run_shell", arguments=arguments),
-                        )
-                    ],
-                ),
-                finish_reason=finish_reason,
-            )
-        ],
+        choices=[StreamingChoices(index=0, delta=delta, finish_reason=finish_reason)],
     )
 
 
@@ -250,13 +252,14 @@ async def _windowed_chat_stream(
     collected: List[Any],
     content_chunks: List[str],
     tool_argument_chunks: List[str] | None = None,
+    legacy_function_call: bool = False,
 ) -> AsyncGenerator[ModelResponseStream, None]:
     for content in content_chunks:
         yielded_count.append(len(collected))
         yield _chat_chunk(content)
     for arguments in tool_argument_chunks or []:
         yielded_count.append(len(collected))
-        yield _tool_call_chunk(arguments)
+        yield _tool_call_chunk(arguments, legacy_function_call=legacy_function_call)
     yielded_count.append(len(collected))
     yield _chat_chunk(finish_reason="tool_calls" if tool_argument_chunks else "stop")
 
@@ -271,11 +274,22 @@ def _tool_argument_text(chunks: List[Any]) -> str:
     )
 
 
+def _function_call_argument_text(chunks: list[Any]) -> str:
+    return "".join(
+        choice.delta.function_call.arguments or ""
+        for chunk in chunks
+        if isinstance(chunk, ModelResponseStream)
+        for choice in chunk.choices
+        if choice.delta.function_call is not None
+    )
+
+
 async def _run_windowed(
     guardrail: CustomGuardrail,
     content_chunks: List[str],
     end_of_stream_only: bool = False,
     tool_argument_chunks: List[str] | None = None,
+    legacy_function_call: bool = False,
 ) -> tuple[List[Any], List[int]]:
     guardrail.streaming_buffer_until_moderated = True
     guardrail.streaming_buffer_release_on_scan = True
@@ -292,7 +306,9 @@ async def _run_windowed(
     yielded_count: List[int] = []
     async for chunk in unified.async_post_call_streaming_iterator_hook(
         user_api_key_dict=user_api_key_dict,
-        response=_windowed_chat_stream(yielded_count, collected, content_chunks, tool_argument_chunks),
+        response=_windowed_chat_stream(
+            yielded_count, collected, content_chunks, tool_argument_chunks, legacy_function_call
+        ),
         request_data=request_data,
     ):
         collected.append(chunk)
@@ -305,13 +321,24 @@ def _responses_message_stream_events(text_chunks: List[str]) -> List[dict]:
     return [
         {"type": "response.output_item.added", "output_index": 0, "item": {**message, "content": []}},
         *(
-            {"type": "response.output_text.delta", "item_id": "msg_1", "output_index": 0, "content_index": 0, "delta": text}
+            {
+                "type": "response.output_text.delta",
+                "item_id": "msg_1",
+                "output_index": 0,
+                "content_index": 0,
+                "delta": text,
+            }
             for text in text_chunks
         ),
         {"type": "response.output_item.done", "output_index": 0, "item": {**message, "content": content}},
         {
             "type": "response.completed",
-            "response": {"id": "resp_1", "model": "gpt-4o", "status": "completed", "output": [{**message, "content": content}]},
+            "response": {
+                "id": "resp_1",
+                "model": "gpt-4o",
+                "status": "completed",
+                "output": [{**message, "content": content}],
+            },
         },
     ]
 
@@ -322,7 +349,13 @@ def _responses_truncated_function_call_events(text: str, argument_chunks: List[s
     function_call = {"type": "function_call", "id": "fc_1", "call_id": "call_1", "name": "run_shell"}
     return [
         {"type": "response.output_item.added", "output_index": 0, "item": {**message, "content": []}},
-        {"type": "response.output_text.delta", "item_id": "msg_1", "output_index": 0, "content_index": 0, "delta": text},
+        {
+            "type": "response.output_text.delta",
+            "item_id": "msg_1",
+            "output_index": 0,
+            "content_index": 0,
+            "delta": text,
+        },
         {"type": "response.output_item.added", "output_index": 1, "item": {**function_call, "arguments": ""}},
         *(
             {"type": "response.function_call_arguments.delta", "item_id": "fc_1", "output_index": 1, "delta": arguments}
@@ -463,6 +496,21 @@ async def test_windowed_buffer_holds_tool_call_windows_until_end_of_stream_scan(
     assert guardrail.tool_call_scan_indexes == [guardrail.scan_count]
 
 
+@pytest.mark.asyncio
+async def test_windowed_buffer_holds_legacy_function_call_windows_until_end_of_stream():
+    guardrail = _PassingGuardrail(guardrail_name="windowed-functions", event_hook="post_call")
+    content_chunks = ["one ", "two ", "three "]
+    function_argument_chunks = ['{"cmd": "', TOOL_ARGUMENTS_MARKER, '"}']
+
+    collected, yielded_count = await _run_windowed(
+        guardrail, content_chunks, tool_argument_chunks=function_argument_chunks, legacy_function_call=True
+    )
+
+    assert yielded_count == [0, 0, 2, 2, 2, 2, 2]
+    assert _chat_text(collected) == "".join(content_chunks)
+    assert _function_call_argument_text(collected) == "".join(function_argument_chunks)
+
+
 def test_tool_call_only_scan_key_is_not_skipped_as_empty():
     assert _is_redundant_scan(StreamingScanKey(texts=("",)), None) is True
     assert _is_redundant_scan(StreamingScanKey(texts=("",), tool_calls=("run_shell:{}",)), None) is False
@@ -470,7 +518,9 @@ def test_tool_call_only_scan_key_is_not_skipped_as_empty():
 
 @pytest.mark.asyncio
 async def test_windowed_responses_output_item_done_round_keeps_text_window_withheld():
-    guardrail = _MarkerBlockingGuardrail(guardrail_name="windowed-responses", event_hook="post_call", marker=ORIGINAL_MARKER)
+    guardrail = _MarkerBlockingGuardrail(
+        guardrail_name="windowed-responses", event_hook="post_call", marker=ORIGINAL_MARKER
+    )
     events = _responses_message_stream_events(["one ", f"{ORIGINAL_MARKER} "])
 
     raw = await _run_windowed_responses(guardrail, events)

From 9421b26bf6dcc98bee10e2cbbd45bf6ff1c23166 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 13:47:07 -0700
Subject: [PATCH 57/76] fix(e2e): stage the seeded device id per thread, not
 per process

Build 232 took two compat cells red with a FileNotFoundError renaming
`.claude.json.197` onto `.claude.json`. `run_claude_models_parallel`
drives several models from one process, so a pid-suffixed staged name is
shared between threads: one thread renamed the file the other was still
writing, and the loser died on a path that no longer existed.

mkstemp in the same directory gives a name that is unique per thread as
well as per process, and the rename stays atomic.
---
 .../test_request_determinism.py               | 19 ++++++++++++++++++-
 tests/e2e/claude_code/cli_driver.py           | 11 ++++++++---
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py b/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
index 09a181162d2..5046f35c73b 100644
--- a/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
+++ b/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
@@ -33,7 +33,7 @@ from typing import List, Tuple
 
 import pytest
 
-from claude_code.cli_driver import _stable_cli_state, run_claude
+from claude_code.cli_driver import _FIXED_CLI_USER_ID, _seed_cli_identity, _stable_cli_state, run_claude
 from claude_code.rate_limiter import RateLimiter
 
 _STUB_REPLY = {
@@ -141,3 +141,20 @@ def test_concurrent_cells_do_not_collide_on_the_pinned_session(
     assert codes == [0, 0, 0, 0]
     assert bodies, "the CLI sent no request to the stub, so there is nothing to compare"
     assert set(Counter(bodies).values()) == {4}
+
+
+def test_seeding_the_device_id_survives_threads_racing_on_the_same_directory(tmp_path: Path) -> None:
+    """`run_claude_models_parallel` drives several models from one process, so the
+    seed's staged file has to be unique per thread and not merely per process."""
+    config_dir = tmp_path / "config"
+    config_dir.mkdir()
+    seeded = config_dir / ".claude.json"
+
+    for _round in range(20):
+        seeded.unlink(missing_ok=True)
+        with ThreadPoolExecutor(max_workers=16) as pool:
+            for outcome in [pool.submit(_seed_cli_identity, str(config_dir)) for _ in range(16)]:
+                outcome.result()
+
+    assert json.loads(seeded.read_text(encoding="utf-8"))["userID"] == _FIXED_CLI_USER_ID
+    assert sorted(entry.name for entry in config_dir.iterdir()) == [".claude.json"]
diff --git a/tests/e2e/claude_code/cli_driver.py b/tests/e2e/claude_code/cli_driver.py
index 3fad87c7479..a01d8ab3e7c 100644
--- a/tests/e2e/claude_code/cli_driver.py
+++ b/tests/e2e/claude_code/cli_driver.py
@@ -143,7 +143,12 @@ def _seed_cli_identity(config_dir: str) -> None:
     `userID`, and sends them in `metadata.user_id` forever after, so the value
     is stable for exactly as long as that file lives. Pinning it, and the
     session id passed beside it, costs nothing: both feed abuse detection
-    rather than quota, caching or continuity."""
+    rather than quota, caching or continuity.
+
+    The staged name has to be unique per *thread*, not per process:
+    `run_claude_models_parallel` drives several models from one process, so a
+    pid-suffixed name lets one thread rename the file another is still
+    writing, and the loser dies on a missing path."""
     path = os.path.join(config_dir, ".claude.json")
     try:
         with open(path, encoding="utf-8") as handle:
@@ -151,8 +156,8 @@ def _seed_cli_identity(config_dir: str) -> None:
                 return
     except (OSError, ValueError):
         pass
-    staged = f"{path}.{os.getpid()}"
-    with open(staged, "w", encoding="utf-8") as handle:
+    handle_fd, staged = tempfile.mkstemp(dir=config_dir, prefix=".claude.json.")
+    with os.fdopen(handle_fd, "w", encoding="utf-8") as handle:
         json.dump({"userID": _FIXED_CLI_USER_ID}, handle)
     os.replace(staged, path)
 

From baca62df136bc7e7337b2bb3326e38aaf079dcac Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 13:53:28 -0700
Subject: [PATCH 58/76] test(logging): pick this test's own records out of the
 shared log batch

The generic API logger batches whatever is queued when it flushes, so records
from tests in other files in the same job land in the same request. Two tests
assumed otherwise: one read actual_request[0], the other counted NDJSON lines,
and both broke whenever another file logged first. Select by the messages each
test sent instead, which keeps the format assertions and stops the order from
deciding the outcome.
---
 .../test_generic_api_callback.py              | 23 ++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/tests/logging_callback_tests/test_generic_api_callback.py b/tests/logging_callback_tests/test_generic_api_callback.py
index 29d8f9e5694..2c62741ed38 100644
--- a/tests/logging_callback_tests/test_generic_api_callback.py
+++ b/tests/logging_callback_tests/test_generic_api_callback.py
@@ -98,8 +98,15 @@ async def test_generic_api_callback():
     assert isinstance(actual_request, list), "Request body should be a list"
     assert len(actual_request) > 0, "Request body list should not be empty"
 
-    # Validate the first payload item
-    payload_item: StandardLoggingPayload = StandardLoggingPayload(**actual_request[0])
+    this_test_messages = [{"role": "user", "content": "Hello, world!"}]
+    mine = [
+        item for item in actual_request if item.get("messages") == this_test_messages
+    ]
+    assert (
+        len(mine) == 1
+    ), f"Expected this test's single call in the batch, got {len(mine)} of {len(actual_request)}"
+
+    payload_item: StandardLoggingPayload = StandardLoggingPayload(**mine[0])
     print("##########\n")
     print(json.dumps(payload_item, indent=4))
     print("##########\n")
@@ -448,11 +455,15 @@ async def test_generic_api_callback_sumologic_uses_ndjson():
     assert isinstance(ndjson_data, str), "Data should be a string for NDJSON"
 
     lines = ndjson_data.strip().split("\n")
-    assert len(lines) == 2, f"Expected 2 lines of NDJSON, got {len(lines)}"
+    records = [json.loads(line) for line in lines]
 
-    # Each line should be valid JSON
-    for line in lines:
-        json.loads(line)  # Will raise if invalid JSON
+    this_test_messages = [
+        [{"role": "user", "content": f"Test {i}"}] for i in range(2)
+    ]
+    mine = [record for record in records if record.get("messages") in this_test_messages]
+    assert (
+        len(mine) == 2
+    ), f"Expected this test's 2 calls as NDJSON lines, got {len(mine)} of {len(records)}"
 
 
 @pytest.mark.asyncio

From f10d95fb95371b1cebbec3ccd9fa3cce71fdc8ff Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 13:58:38 -0700
Subject: [PATCH 59/76] test(together_ai): drop the prefix-strip assertion, e2e
 covers it live

tests/e2e/llm_translation/test_together_ai_e2e.py registers its model with the
full registry key, so a slashed together_ai/<vendor>/<model> goes through the
prefix strip on every e2e run and an over-strip would fail against the real
API. The unit assertion was a second copy of that. The roles check stays, since
nothing in e2e exercises it.
---
 .../chat/test_together_ai_chat_transformation.py  | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py b/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py
index a7347edb2c7..1df8c96fb50 100644
--- a/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py
+++ b/tests/test_litellm/llms/together_ai/chat/test_together_ai_chat_transformation.py
@@ -1137,21 +1137,6 @@ def _together_chat_transport() -> tuple[HTTPHandler, list[httpx.Request]]:
     return client, captured_requests
 
 
-def test_only_the_provider_prefix_is_stripped_from_a_slashed_model_name():
-    client, captured_requests = _together_chat_transport()
-
-    litellm.completion(
-        model=f"together_ai/{TOOL_CALLING_MODEL}",
-        messages=[{"role": "user", "content": "Hello!"}],
-        api_key="fake-key",
-        client=client,
-    )
-
-    assert "/" in TOOL_CALLING_MODEL
-    assert str(captured_requests[0].url) == "https://api.together.ai/v1/chat/completions"
-    assert json.loads(captured_requests[0].content)["model"] == TOOL_CALLING_MODEL
-
-
 def test_custom_role_wrappers_never_reach_the_request():
     client, captured_requests = _together_chat_transport()
     messages = [{"role": "user", "content": "Hello!"}]

From c621435ef7de4178b8da74cbde5386400215bf2f Mon Sep 17 00:00:00 2001
From: Yujong Lee <yujong@berri.ai>
Date: Wed, 16 Sep 2026 21:02:30 +0000
Subject: [PATCH 60/76] refactor(ocr): move file preparation from the python
 bridge into litellm-core

Delete litellm/ocr/input.py and the native _ocr_file_document, _ocr_upload_document
and _ocr_mime_type helpers. File documents now project to a typed OcrDocumentInput
and the core lifecycle reads local paths, encodes bytes and asks the host to read
file-like objects through a ReadDocument operation before the provider request

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 litellm-rust/Cargo.lock                       |   1 +
 litellm-rust/crates/core/src/ocr/client.rs    |  13 +-
 litellm-rust/crates/core/src/ocr/document.rs  | 126 ++++--
 litellm-rust/crates/core/src/ocr/error.rs     |   6 +
 litellm-rust/crates/core/src/ocr/lifecycle.rs |  50 ++-
 litellm-rust/crates/core/src/ocr/mod.rs       |   7 +-
 litellm-rust/crates/core/src/ocr/types.rs     |  70 +++-
 litellm-rust/crates/core/src/ocr/wire.rs      |  43 +-
 litellm-rust/crates/core/tests/ocr.rs         | 154 +++++++-
 litellm-rust/crates/python-bridge/Cargo.toml  |   1 +
 .../python-bridge/src/routes/ocr/document.rs  | 370 ++++++++++--------
 .../python-bridge/src/routes/ocr/errors.rs    |   7 +
 .../python-bridge/src/routes/ocr/lifecycle.rs |  22 +-
 .../python-bridge/src/routes/ocr/mod.rs       |   1 -
 .../python-bridge/src/routes/ocr/project.rs   | 141 +++----
 litellm/ocr/input.py                          | 112 ------
 litellm/ocr/legacy.py                         |   7 +-
 litellm/ocr/main.py                           |   2 +-
 litellm/proxy/ocr_endpoints/endpoints.py      |  17 +-
 litellm/rust_bridge/_native.pyi               |  13 -
 tests/test_litellm/ocr/test_ocr_file_input.py |  25 +-
 tests/test_litellm_rust/ocr/test_requests.py  | 139 +++----
 22 files changed, 810 insertions(+), 517 deletions(-)
 delete mode 100644 litellm/ocr/input.py

diff --git a/litellm-rust/Cargo.lock b/litellm-rust/Cargo.lock
index e2a3af77594..7397742369b 100644
--- a/litellm-rust/Cargo.lock
+++ b/litellm-rust/Cargo.lock
@@ -1951,6 +1951,7 @@ dependencies = [
 name = "litellm-python-bridge"
 version = "0.1.0"
 dependencies = [
+ "bytes",
  "criterion",
  "futures-util",
  "litellm-auth",
diff --git a/litellm-rust/crates/core/src/ocr/client.rs b/litellm-rust/crates/core/src/ocr/client.rs
index 00bfeb2b7b2..9a30b2f8e04 100644
--- a/litellm-rust/crates/core/src/ocr/client.rs
+++ b/litellm-rust/crates/core/src/ocr/client.rs
@@ -54,9 +54,16 @@ impl OcrClient {
             match call.resume(result.take()).await? {
                 OcrCallStep::Host(OcrHostOperation::ProjectRequest) => {
                     result = Some(OcrHostResult::Request(Ok((
-                        Box::new(request.take().ok_or_else(|| {
-                            Error::InvalidRequest("OCR request was already projected".into())
-                        })?),
+                        Box::new(
+                            request
+                                .take()
+                                .ok_or_else(|| {
+                                    Error::InvalidRequest(
+                                        "OCR request was already projected".into(),
+                                    )
+                                })?
+                                .into(),
+                        ),
                         false,
                     ))))
                 }
diff --git a/litellm-rust/crates/core/src/ocr/document.rs b/litellm-rust/crates/core/src/ocr/document.rs
index a7afdaf8793..1b3d2dada44 100644
--- a/litellm-rust/crates/core/src/ocr/document.rs
+++ b/litellm-rust/crates/core/src/ocr/document.rs
@@ -1,3 +1,6 @@
+use std::io::Read;
+use std::path::Path;
+
 use base64::{Engine, engine::general_purpose::STANDARD};
 use data_url::mime::Mime;
 use data_url::{DataUrl, DataUrlError, forgiving_base64::DecodeError};
@@ -5,12 +8,52 @@ use reqwest::Url;
 use serde_json::Map;
 
 use super::error::{OcrError, OcrRequestError, OcrResponseError};
-use super::types::{OcrConnection, OcrDocument};
+use super::types::{OcrConnection, OcrDocument, OcrDocumentInput};
 use crate::constants::{OCR_INLINE_MAX_BYTES, OCR_MAX_FETCH_REDIRECTS};
 use crate::media::Error as MediaError;
 use crate::media::{DownloadPolicy, MediaFetcher};
 use crate::transport::Error as TransportError;
 
+pub fn prepare_document(input: OcrDocumentInput) -> Result<OcrDocument, super::Error> {
+    match input {
+        OcrDocumentInput::Document(document) => Ok(document),
+        OcrDocumentInput::Path { path, mime_type } => {
+            read_path_document(&path, mime_type.as_deref())
+        }
+        OcrDocumentInput::Bytes {
+            bytes,
+            file_name,
+            mime_type,
+        } => Ok(encode_file_document(
+            &bytes,
+            file_name.as_deref(),
+            mime_type.as_deref(),
+        )?),
+        OcrDocumentInput::HostReader { .. } => Err(super::Error::InvalidRequest(
+            "OCR file reader was not read by the host".into(),
+        )),
+    }
+}
+
+pub fn read_path_document(
+    path: &Path,
+    mime_type: Option<&str>,
+) -> Result<OcrDocument, super::Error> {
+    let mut bytes = Vec::new();
+    std::fs::File::open(path)
+        .and_then(|file| {
+            file.take(OCR_INLINE_MAX_BYTES as u64 + 1)
+                .read_to_end(&mut bytes)
+        })
+        .map_err(|source| super::Error::FileRead {
+            path: path.to_owned(),
+            kind: source.kind(),
+            message: source.to_string(),
+        })?;
+    let name = path.file_name().map(|name| name.to_string_lossy());
+    Ok(encode_file_document(&bytes, name.as_deref(), mime_type)?)
+}
+
 pub fn encode_file_document(
     bytes: &[u8],
     file_name: Option<&str>,
@@ -75,18 +118,6 @@ pub fn mime_type_for_name(name: &str) -> &'static str {
     }
 }
 
-pub fn upload_mime_type<'a>(file_name: Option<&str>, content_type: Option<&'a str>) -> &'a str {
-    match content_type
-        .and_then(|value| value.split(';').next())
-        .map(str::trim)
-    {
-        Some(value) if !value.is_empty() && value != "application/octet-stream" => value,
-        _ => file_name
-            .map(mime_type_for_name)
-            .unwrap_or("application/octet-stream"),
-    }
-}
-
 pub(crate) struct InlineDocument<'a>(DataUrl<'a>);
 
 impl<'a> InlineDocument<'a> {
@@ -230,24 +261,65 @@ mod tests {
     }
 
     #[test]
-    fn upload_mime_mapping_matches_python() {
+    fn path_documents_are_read_and_named_by_core() {
+        let dir = std::env::temp_dir().join(format!("litellm-ocr-{}", rand::random::<u64>()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join("scan.png");
+        std::fs::write(&path, b"abc").unwrap();
         assert_eq!(
-            upload_mime_type(Some("report.pdf"), Some("application/octet-stream")),
-            "application/pdf"
-        );
-        assert_eq!(upload_mime_type(Some("image.png"), None), "image/png");
-        assert_eq!(upload_mime_type(None, None), "application/octet-stream");
-        assert_eq!(
-            upload_mime_type(Some("doc.pdf"), Some("application/pdf; charset=utf-8")),
-            "application/pdf"
+            prepare_document(OcrDocumentInput::Path {
+                path: path.clone(),
+                mime_type: None,
+            })
+            .unwrap(),
+            OcrDocument::ImageUrl {
+                image_url: "data:image/png;base64,YWJj".into(),
+                extra_fields: Map::new(),
+            }
         );
         assert_eq!(
-            upload_mime_type(
-                Some("img.png"),
-                Some("image/png; charset=utf-8; boundary=something")
-            ),
-            "image/png"
+            prepare_document(OcrDocumentInput::Path {
+                path: path.clone(),
+                mime_type: Some("application/pdf".into()),
+            })
+            .unwrap(),
+            document("data:application/pdf;base64,YWJj")
         );
+        std::fs::write(&path, vec![b'a'; OCR_INLINE_MAX_BYTES + 1]).unwrap();
+        assert_eq!(
+            prepare_document(OcrDocumentInput::Path {
+                path: path.clone(),
+                mime_type: None,
+            }),
+            Err(OcrRequestError::InlineDocumentTooLarge.into())
+        );
+        std::fs::remove_dir_all(&dir).unwrap();
+
+        let missing = dir.join("missing.pdf");
+        let Err(super::super::Error::FileRead { path, kind, .. }) =
+            prepare_document(OcrDocumentInput::Path {
+                path: missing.clone(),
+                mime_type: None,
+            })
+        else {
+            panic!("missing paths must surface a file read error");
+        };
+        assert_eq!(path, missing);
+        assert_eq!(kind, std::io::ErrorKind::NotFound);
+    }
+
+    #[test]
+    fn byte_documents_are_encoded_and_host_readers_must_be_read_first() {
+        assert_eq!(
+            prepare_document(OcrDocumentInput::Bytes {
+                bytes: b"abc".as_slice().into(),
+                file_name: Some("scan.pdf".into()),
+                mime_type: None,
+            })
+            .unwrap(),
+            document("data:application/pdf;base64,YWJj")
+        );
+        assert!(prepare_document(OcrDocumentInput::HostReader { mime_type: None }).is_err());
     }
 
     #[test]
diff --git a/litellm-rust/crates/core/src/ocr/error.rs b/litellm-rust/crates/core/src/ocr/error.rs
index 1c21edb6c91..0c92b511a38 100644
--- a/litellm-rust/crates/core/src/ocr/error.rs
+++ b/litellm-rust/crates/core/src/ocr/error.rs
@@ -50,6 +50,12 @@ pub enum Error {
     Connect(String),
     #[error("routing error: {0}")]
     Routing(String),
+    #[error("Failed to read OCR file {}: {message}", path.display())]
+    FileRead {
+        path: std::path::PathBuf,
+        kind: std::io::ErrorKind,
+        message: String,
+    },
     /// The request is outside the surface this route covers in Rust. Hosts that
     /// keep a reference implementation treat this as "fall back", not "fail".
     #[error("unsupported by the rust path: {0}")]
diff --git a/litellm-rust/crates/core/src/ocr/lifecycle.rs b/litellm-rust/crates/core/src/ocr/lifecycle.rs
index efa2b1f2873..994a9698459 100644
--- a/litellm-rust/crates/core/src/ocr/lifecycle.rs
+++ b/litellm-rust/crates/core/src/ocr/lifecycle.rs
@@ -9,6 +9,7 @@ use super::hooks::{
     OcrDuringCallRequest, OcrHookFuture, OcrHooks, OcrLogFuture, OcrPostCallRequest,
     OcrPreCallRequest,
 };
+use super::types::{OcrDocumentInput, OcrFileContent};
 use super::{LiteLLMOcrRequest, LiteLLMOcrResponse, OcrClient};
 use crate::call_lifecycle::host::{
     HostCall, HostCallFuture, HostCallStep, HostFailure, HostLifecycle, HostPhase,
@@ -52,6 +53,7 @@ impl OcrAdmission {
 #[derive(Clone, Debug)]
 pub enum OcrHostOperation {
     ProjectRequest,
+    ReadDocument,
     Lifecycle(HostPhase),
     ConstructResponse(Arc<LiteLLMOcrResponse>),
     MapFailure(Error),
@@ -83,7 +85,8 @@ impl OcrHostOperation {
 }
 
 pub enum OcrHostResult {
-    Request(Result<(Box<LiteLLMOcrRequest>, bool), Error>),
+    Request(Result<(Box<LiteLLMOcrRequest<OcrDocumentInput>>, bool), Error>),
+    Document(Result<OcrFileContent, Error>),
     Lifecycle(Result<(), HostFailure<Error>>),
     AzureAdToken(Result<ResolvedCredential, AuthError>),
     PreCall(Result<OcrPreCallRequest, Error>),
@@ -313,7 +316,7 @@ struct PendingOperation {
 
 struct OcrExecution {
     client: Option<OcrClient>,
-    request: Option<LiteLLMOcrRequest>,
+    request: Option<LiteLLMOcrRequest<OcrDocumentInput>>,
     operations_tx: mpsc::UnboundedSender<PendingOperation>,
     operations_rx: mpsc::UnboundedReceiver<PendingOperation>,
     pending_result: Option<oneshot::Sender<OcrHostResult>>,
@@ -397,12 +400,14 @@ impl OcrExecution {
                 },
             )));
         }
-        request.hooks = Arc::new(ProtocolHooks {
+        let hooks = Arc::new(ProtocolHooks {
             operations: self.operations_tx.clone(),
             intercepts_requests,
             terminal: self.terminal.clone(),
         });
+        request.hooks = hooks.clone();
         self.execution = Some(tokio::spawn(async move {
+            let request = prepare_request_document(request, &hooks).await?;
             perform_ocr_request(&client, request).await
         }));
     }
@@ -423,6 +428,39 @@ impl OcrExecution {
     }
 }
 
+async fn prepare_request_document(
+    request: LiteLLMOcrRequest<OcrDocumentInput>,
+    hooks: &ProtocolHooks,
+) -> Result<LiteLLMOcrRequest, Error> {
+    let request = match &request.document {
+        OcrDocumentInput::HostReader { mime_type } => {
+            let mime_type = mime_type.clone();
+            let content = match hooks.invoke(OcrHostOperation::ReadDocument).await? {
+                OcrHostResult::Document(result) => result?,
+                _ => {
+                    return Err(Error::InvalidRequest(
+                        "invalid OCR document read host result".into(),
+                    ));
+                }
+            };
+            request.with_document(OcrDocumentInput::Bytes {
+                bytes: content.bytes,
+                file_name: content.file_name,
+                mime_type,
+            })
+        }
+        _ => request,
+    };
+    if let OcrDocumentInput::Document(_) = &request.document {
+        return request.map_document(super::document::prepare_document);
+    }
+    tokio::task::spawn_blocking(move || request.map_document(super::document::prepare_document))
+        .await
+        .map_err(|error| {
+            Error::InvalidRequest(format!("OCR document preparation task failed: {error}"))
+        })?
+}
+
 impl Drop for OcrExecution {
     fn drop(&mut self) {
         if let Some(execution) = &self.execution {
@@ -567,6 +605,9 @@ impl OcrHost for NoopOcrHost {
                 OcrHostOperation::ProjectRequest => OcrHostResult::Request(Err(
                     Error::InvalidRequest("OCR host has no request projection".into()),
                 )),
+                OcrHostOperation::ReadDocument => OcrHostResult::Document(Err(
+                    Error::InvalidRequest("OCR host has no document reader".into()),
+                )),
                 OcrHostOperation::Lifecycle(_)
                 | OcrHostOperation::ConstructResponse(_)
                 | OcrHostOperation::MapFailure(_)
@@ -602,6 +643,9 @@ impl OcrHost for OcrHookHost {
                 OcrHostOperation::ProjectRequest => OcrHostResult::Request(Err(
                     Error::InvalidRequest("OCR hook host has no request projection".into()),
                 )),
+                OcrHostOperation::ReadDocument => OcrHostResult::Document(Err(
+                    Error::InvalidRequest("OCR hook host has no document reader".into()),
+                )),
                 OcrHostOperation::Success {
                     context,
                     response,
diff --git a/litellm-rust/crates/core/src/ocr/mod.rs b/litellm-rust/crates/core/src/ocr/mod.rs
index 3b51ff98356..f2e7aa4f46d 100644
--- a/litellm-rust/crates/core/src/ocr/mod.rs
+++ b/litellm-rust/crates/core/src/ocr/mod.rs
@@ -13,12 +13,15 @@ pub mod types;
 pub mod wire;
 
 pub use client::{OcrClient, ocr};
-pub use document::{encode_file_document, mime_type_for_name, upload_mime_type};
+pub use document::{encode_file_document, mime_type_for_name, read_path_document};
 pub use lifecycle::{
     NativeOutcome, NativeResult, NoopOcrHost, OcrAdmission, OcrCall, OcrCallStep, OcrDecline,
     OcrHookHost, OcrHost, OcrHostOperation, OcrHostResult,
 };
-pub use types::{LiteLLMOcrRequest, LiteLLMOcrResponse, OcrConnection, OcrDocument};
+pub use types::{
+    LiteLLMOcrRequest, LiteLLMOcrResponse, OcrConnection, OcrDocument, OcrDocumentInput,
+    OcrFileContent,
+};
 
 #[cfg(test)]
 #[path = "../../tests/azure_ai_ocr.rs"]
diff --git a/litellm-rust/crates/core/src/ocr/types.rs b/litellm-rust/crates/core/src/ocr/types.rs
index 69e6982414b..bb212674b33 100644
--- a/litellm-rust/crates/core/src/ocr/types.rs
+++ b/litellm-rust/crates/core/src/ocr/types.rs
@@ -1,7 +1,10 @@
 use std::collections::BTreeMap;
+use std::convert::Infallible;
+use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::Duration;
 
+use bytes::Bytes;
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 
@@ -50,6 +53,35 @@ impl OcrDocument {
     }
 }
 
+#[derive(Clone, Debug, PartialEq)]
+pub enum OcrDocumentInput {
+    Document(OcrDocument),
+    Path {
+        path: PathBuf,
+        mime_type: Option<String>,
+    },
+    Bytes {
+        bytes: Bytes,
+        file_name: Option<String>,
+        mime_type: Option<String>,
+    },
+    HostReader {
+        mime_type: Option<String>,
+    },
+}
+
+impl From<OcrDocument> for OcrDocumentInput {
+    fn from(document: OcrDocument) -> Self {
+        Self::Document(document)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OcrFileContent {
+    pub bytes: Bytes,
+    pub file_name: Option<String>,
+}
+
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum OcrResponseFormat {
@@ -89,9 +121,9 @@ impl Default for OcrConnection {
     }
 }
 
-pub struct LiteLLMOcrRequest {
+pub struct LiteLLMOcrRequest<D = OcrDocument> {
     pub model: String,
-    pub document: OcrDocument,
+    pub document: D,
     pub connection: OcrConnection,
     pub hooks: Arc<dyn OcrHooks>,
     pub litellm_call_id: Option<String>,
@@ -101,10 +133,10 @@ pub struct LiteLLMOcrRequest {
     pub(crate) adapter: OcrAdapterKind,
 }
 
-impl LiteLLMOcrRequest {
+impl<D> LiteLLMOcrRequest<D> {
     pub fn new(
         model: String,
-        document: OcrDocument,
+        document: D,
         custom_llm_provider: Option<&str>,
         optional_params: Map<String, Value>,
     ) -> Result<Self, Error> {
@@ -151,6 +183,36 @@ impl LiteLLMOcrRequest {
             ..self
         }
     }
+
+    pub fn map_document<T, E>(
+        self,
+        map: impl FnOnce(D) -> Result<T, E>,
+    ) -> Result<LiteLLMOcrRequest<T>, E> {
+        Ok(LiteLLMOcrRequest {
+            model: self.model,
+            document: map(self.document)?,
+            connection: self.connection,
+            hooks: self.hooks,
+            litellm_call_id: self.litellm_call_id,
+            optional_params: self.optional_params,
+            input_sources: self.input_sources,
+            azure_ad_token_provider: self.azure_ad_token_provider,
+            adapter: self.adapter,
+        })
+    }
+
+    pub fn with_document<T>(self, document: T) -> LiteLLMOcrRequest<T> {
+        let Ok(request) = self.map_document(|_| Ok::<T, Infallible>(document));
+        request
+    }
+}
+
+impl From<LiteLLMOcrRequest> for LiteLLMOcrRequest<OcrDocumentInput> {
+    fn from(request: LiteLLMOcrRequest) -> Self {
+        let Ok(request) = request
+            .map_document(|document| Ok::<_, Infallible>(OcrDocumentInput::Document(document)));
+        request
+    }
 }
 
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
diff --git a/litellm-rust/crates/core/src/ocr/wire.rs b/litellm-rust/crates/core/src/ocr/wire.rs
index 93816effcb1..f0cad2b4e93 100644
--- a/litellm-rust/crates/core/src/ocr/wire.rs
+++ b/litellm-rust/crates/core/src/ocr/wire.rs
@@ -68,9 +68,9 @@ pub struct DecodedOcrResponse<T> {
 
 #[derive(Deserialize)]
 #[serde(deny_unknown_fields)]
-pub struct OcrWireRequest {
+pub struct OcrWireRequest<D = Value> {
     pub model: String,
-    pub document: Value,
+    pub document: D,
     pub api_key: Option<String>,
     pub api_base: Option<String>,
     pub custom_llm_provider: Option<String>,
@@ -141,10 +141,34 @@ pub fn consumed_optional_params(
 }
 
 pub fn decode_request(wire: OcrWireRequest) -> Result<LiteLLMOcrRequest, Error> {
+    let OcrWireRequest {
+        model,
+        document,
+        api_key,
+        api_base,
+        custom_llm_provider,
+        extra_headers,
+        optional_params,
+        input_sources,
+        timeout_seconds,
+    } = wire;
+    decode_request_input(OcrWireRequest {
+        model,
+        document: decode_document(document)?,
+        api_key,
+        api_base,
+        custom_llm_provider,
+        extra_headers,
+        optional_params,
+        input_sources,
+        timeout_seconds,
+    })
+}
+
+pub fn decode_request_input<D>(wire: OcrWireRequest<D>) -> Result<LiteLLMOcrRequest<D>, Error> {
     let api_key_source = source_for(&wire.input_sources, "api_key");
     let api_base_source = source_for(&wire.input_sources, "api_base");
     let extra_headers_source = source_for(&wire.input_sources, "extra_headers");
-    let document = decode_document(wire.document)?;
     let headers = wire
         .extra_headers
         .unwrap_or_default()
@@ -183,7 +207,7 @@ pub fn decode_request(wire: OcrWireRequest) -> Result<LiteLLMOcrRequest, Error>
         .unwrap_or(defaults.max_response_bytes);
     let request = LiteLLMOcrRequest::new(
         wire.model,
-        document,
+        wire.document,
         wire.custom_llm_provider.as_deref(),
         wire.optional_params
             .into_iter()
@@ -209,14 +233,14 @@ pub fn decode_request(wire: OcrWireRequest) -> Result<LiteLLMOcrRequest, Error>
     })
 }
 
-fn decode_document(value: Value) -> Result<OcrDocument, OcrRequestError> {
+pub fn decode_document(value: Value) -> Result<OcrDocument, Error> {
     let kind = value.get("type").and_then(Value::as_str);
     let missing_url = matches!(kind, Some("document_url")) && value.get("document_url").is_none()
         || matches!(kind, Some("image_url")) && value.get("image_url").is_none();
     if missing_url {
-        return Err(OcrRequestError::MissingDocumentUrl);
+        return Err(OcrRequestError::MissingDocumentUrl.into());
     }
-    decode_request_value(value, "document")
+    Ok(decode_request_value(value, "document")?)
 }
 
 fn source_for(sources: &BTreeMap<String, InputSource>, name: &str) -> InputSource {
@@ -334,10 +358,7 @@ mod tests {
             serde_json::json!({"type": "document_url"}),
             serde_json::json!({"type": "image_url"}),
         ] {
-            assert_eq!(
-                decode_document(document),
-                Err(OcrRequestError::MissingDocumentUrl)
-            );
+            assert_eq!(decode_document(document), Err(Error::MissingDocumentUrl));
         }
     }
 }
diff --git a/litellm-rust/crates/core/tests/ocr.rs b/litellm-rust/crates/core/tests/ocr.rs
index 373972cf68b..a24d960422d 100644
--- a/litellm-rust/crates/core/tests/ocr.rs
+++ b/litellm-rust/crates/core/tests/ocr.rs
@@ -348,13 +348,14 @@ async fn fallible_host_phases_do_not_replay_or_reach_transport() {
                     }
                     OcrHostOperation::ProjectRequest => {
                         result = Some(OcrHostResult::Request(Ok((
-                            Box::new(request.take().unwrap()),
+                            Box::new(request.take().unwrap().into()),
                             false,
                         ))))
                     }
                     OcrHostOperation::AcquireAzureAdToken => {
                         panic!("test request has no token provider")
                     }
+                    OcrHostOperation::ReadDocument => panic!("test request has no file reader"),
                     OcrHostOperation::PreCall(request) => {
                         phases.push("pre");
                         result = Some(OcrHostResult::PreCall(if failure_phase == "pre" {
@@ -405,7 +406,7 @@ async fn invalid_provider_response_runs_post_call_before_normalization_failure()
         match call.resume(result.take()).await {
             Ok(OcrCallStep::Host(OcrHostOperation::ProjectRequest)) => {
                 result = Some(OcrHostResult::Request(Ok((
-                    Box::new(request.take().unwrap()),
+                    Box::new(request.take().unwrap().into()),
                     false,
                 ))));
             }
@@ -467,9 +468,10 @@ async fn direct_native_host_drives_the_same_state_machine() {
                     _ => panic!("unexpected OCR operation"),
                 });
                 result = Some(match operation {
-                    OcrHostOperation::ProjectRequest => {
-                        OcrHostResult::Request(Ok((Box::new(request.take().unwrap()), false)))
-                    }
+                    OcrHostOperation::ProjectRequest => OcrHostResult::Request(Ok((
+                        Box::new(request.take().unwrap().into()),
+                        false,
+                    ))),
                     operation => host.invoke(operation).await,
                 });
             }
@@ -501,6 +503,137 @@ async fn direct_native_host_drives_the_same_state_machine() {
     ));
 }
 
+async fn drive_native_file_call(
+    request: super::LiteLLMOcrRequest<super::OcrDocumentInput>,
+    content: Result<super::OcrFileContent, crate::ocr::Error>,
+) -> (Result<super::LiteLLMOcrResponse, crate::ocr::Error>, usize) {
+    let NativeOutcome::Completed(mut call) =
+        OcrCall::admit(super::test_support::ocr_client(), OcrAdmission::all())
+    else {
+        panic!("supported call declined")
+    };
+    let mut request = Some(request);
+    let mut content = Some(content);
+    let mut result = None;
+    let mut reads = 0;
+    let outcome = loop {
+        match call.resume(result.take()).await {
+            Ok(OcrCallStep::Host(OcrHostOperation::ProjectRequest)) => {
+                result = Some(OcrHostResult::Request(Ok((
+                    Box::new(request.take().unwrap()),
+                    false,
+                ))));
+            }
+            Ok(OcrCallStep::Host(OcrHostOperation::ReadDocument)) => {
+                reads += 1;
+                result = Some(OcrHostResult::Document(content.take().unwrap()));
+            }
+            Ok(OcrCallStep::Host(operation)) => result = Some(NoopOcrHost.invoke(operation).await),
+            Ok(OcrCallStep::Complete(response)) => break Ok(response),
+            Err(error) => break Err(error),
+        }
+    };
+    (outcome, reads)
+}
+
+#[tokio::test]
+async fn host_reader_documents_are_read_once_at_the_core_selected_point_and_encoded() {
+    let (base, seen, server) = mock_server(vec![MockResponse::json(json!({
+        "pages":[{"index":0,"markdown":"file"}]
+    }))])
+    .await;
+    let request = wire_request("mistral/model", &base, json!({})).with_document(
+        super::OcrDocumentInput::HostReader {
+            mime_type: Some("application/pdf".into()),
+        },
+    );
+    let (response, reads) = drive_native_file_call(
+        request,
+        Ok(super::OcrFileContent {
+            bytes: b"abc".as_slice().into(),
+            file_name: Some("scan.png".into()),
+        }),
+    )
+    .await;
+    server.await.unwrap();
+    assert_eq!(response.unwrap().pages[0]["markdown"], "file");
+    assert_eq!(reads, 1);
+    assert!(seen.lock().unwrap()[0].contains("data:application/pdf;base64,YWJj"));
+}
+
+#[tokio::test]
+async fn host_reader_failures_and_empty_files_fail_before_the_provider_is_called() {
+    let (base, seen, _server) = mock_server(vec![]).await;
+    let request = wire_request("mistral/model", &base, json!({}));
+    let failure = crate::ocr::Error::InvalidRequest("reader exploded".into());
+    let (response, reads) = drive_native_file_call(
+        request.with_document(super::OcrDocumentInput::HostReader { mime_type: None }),
+        Err(failure.clone()),
+    )
+    .await;
+    assert_eq!(response.unwrap_err(), failure);
+    assert_eq!(reads, 1);
+
+    let request = wire_request("mistral/model", &base, json!({}));
+    let (response, _) = drive_native_file_call(
+        request.with_document(super::OcrDocumentInput::HostReader { mime_type: None }),
+        Ok(super::OcrFileContent {
+            bytes: Default::default(),
+            file_name: None,
+        }),
+    )
+    .await;
+    assert!(matches!(
+        response.unwrap_err(),
+        crate::ocr::Error::InvalidRequest(_)
+    ));
+    assert!(seen.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn path_documents_are_read_by_core_without_a_host_operation() {
+    let (base, seen, server) = mock_server(vec![MockResponse::json(json!({
+        "pages":[{"index":0,"markdown":"path"}]
+    }))])
+    .await;
+    let dir = std::env::temp_dir().join(format!("litellm-ocr-{}", rand::random::<u64>()));
+    std::fs::create_dir_all(&dir).unwrap();
+    let path = dir.join("scan.png");
+    std::fs::write(&path, b"abc").unwrap();
+    let request = wire_request("mistral/model", &base, json!({})).with_document(
+        super::OcrDocumentInput::Path {
+            path: path.clone(),
+            mime_type: None,
+        },
+    );
+    let (response, reads) = drive_native_file_call(
+        request,
+        Err(crate::ocr::Error::InvalidRequest("unused".into())),
+    )
+    .await;
+    server.await.unwrap();
+    std::fs::remove_dir_all(&dir).unwrap();
+    assert_eq!(response.unwrap().pages[0]["markdown"], "path");
+    assert_eq!(reads, 0);
+    assert!(seen.lock().unwrap()[0].contains("data:image/png;base64,YWJj"));
+
+    let (base, seen, _server) = mock_server(vec![]).await;
+    let request = wire_request("mistral/model", &base, json!({}));
+    let (response, _) = drive_native_file_call(
+        request.with_document(super::OcrDocumentInput::Path {
+            path: path.clone(),
+            mime_type: None,
+        }),
+        Err(crate::ocr::Error::InvalidRequest("unused".into())),
+    )
+    .await;
+    assert!(matches!(
+        response.unwrap_err(),
+        crate::ocr::Error::FileRead { path: failed, kind: std::io::ErrorKind::NotFound, .. } if failed == path
+    ));
+    assert!(seen.lock().unwrap().is_empty());
+}
+
 #[tokio::test]
 async fn public_finalization_failure_never_dispatches_success_or_replays_provider() {
     use crate::call_lifecycle::host::{HostFailure, HostPhase};
@@ -543,9 +676,10 @@ async fn public_finalization_failure_never_dispatches_success_or_replays_provide
                     | OcrHostOperation::Lifecycle(HostPhase::DeploymentFailure) => {
                         panic!("finalization failure used provider/success dispatch")
                     }
-                    OcrHostOperation::ProjectRequest => {
-                        OcrHostResult::Request(Ok((Box::new(request.take().unwrap()), false)))
-                    }
+                    OcrHostOperation::ProjectRequest => OcrHostResult::Request(Ok((
+                        Box::new(request.take().unwrap().into()),
+                        false,
+                    ))),
                     operation => host.invoke(operation).await,
                 });
             }
@@ -582,7 +716,7 @@ async fn cancellation_at_provider_hook_prevents_execution_and_further_resumption
             OcrCallStep::Host(OcrHostOperation::PreCall(_)) => break,
             OcrCallStep::Host(OcrHostOperation::ProjectRequest) => {
                 result = Some(OcrHostResult::Request(Ok((
-                    Box::new(request.take().unwrap()),
+                    Box::new(request.take().unwrap().into()),
                     false,
                 ))))
             }
@@ -799,7 +933,7 @@ async fn cancellation_waits_for_provider_capture_drop_even_when_acknowledgement_
                     _ = entered.notified() => break,
                     step = call.resume(result.take()) => {
                         result = Some(match step.unwrap() {
-                            OcrCallStep::Host(OcrHostOperation::ProjectRequest) => OcrHostResult::Request(Ok((Box::new(request.take().unwrap()), false))),
+                            OcrCallStep::Host(OcrHostOperation::ProjectRequest) => OcrHostResult::Request(Ok((Box::new(request.take().unwrap().into()), false))),
                             OcrCallStep::Host(operation) => NoopOcrHost.invoke(operation).await,
                             OcrCallStep::Complete(_) => panic!("pending provider completed"),
                         });
diff --git a/litellm-rust/crates/python-bridge/Cargo.toml b/litellm-rust/crates/python-bridge/Cargo.toml
index 1562d4c1021..6dde7c71af6 100644
--- a/litellm-rust/crates/python-bridge/Cargo.toml
+++ b/litellm-rust/crates/python-bridge/Cargo.toml
@@ -16,6 +16,7 @@ extension-module = ["pyo3/extension-module"]
 panic-test = []
 
 [dependencies]
+bytes.workspace = true
 futures-util.workspace = true
 litellm-core.workspace = true
 litellm-auth.workspace = true
diff --git a/litellm-rust/crates/python-bridge/src/routes/ocr/document.rs b/litellm-rust/crates/python-bridge/src/routes/ocr/document.rs
index d43c2f88775..33c0561184d 100644
--- a/litellm-rust/crates/python-bridge/src/routes/ocr/document.rs
+++ b/litellm-rust/crates/python-bridge/src/routes/ocr/document.rs
@@ -1,97 +1,56 @@
-use std::io::Read;
 use std::path::PathBuf;
 
-use pyo3::exceptions::{PyFileNotFoundError, PyTypeError, PyValueError};
+use bytes::Bytes;
+use pyo3::exceptions::{PyTypeError, PyValueError};
+use pyo3::gc::{PyTraverseError, PyVisit};
 use pyo3::prelude::*;
 use pyo3::pybacked::PyBackedBytes;
-#[cfg(test)]
-use pyo3::types::PyDict;
 use pyo3::types::{PyBytes, PyString};
 
-use litellm_core::constants::OCR_INLINE_MAX_BYTES;
-use litellm_core::ocr::{OcrDocument, encode_file_document, mime_type_for_name, upload_mime_type};
-use litellm_python_interop::to_py_preserving_errors;
+use litellm_core::ocr::{OcrDocumentInput, OcrFileContent};
 
-enum FileBytes {
-    Python(PyBackedBytes),
-    Native(Vec<u8>),
+#[derive(Debug)]
+pub(super) struct PythonFileReader {
+    reader: Py<PyAny>,
+    name: Option<String>,
 }
 
-impl AsRef<[u8]> for FileBytes {
-    fn as_ref(&self) -> &[u8] {
-        match self {
-            Self::Python(bytes) => bytes,
-            Self::Native(bytes) => bytes,
-        }
+impl PythonFileReader {
+    pub(super) fn read(&self, py: Python<'_>) -> PyResult<OcrFileContent> {
+        let value = self.reader.bind(py).call0()?;
+        let bytes = if value.is_instance_of::<PyString>() {
+            Bytes::from(value.extract::<String>()?)
+        } else if value.is_instance_of::<PyBytes>() {
+            extract_bytes(&value)?
+        } else {
+            return Err(PyTypeError::new_err(format!(
+                "OCR file read must return bytes or str, got {}",
+                value.get_type(),
+            )));
+        };
+        Ok(OcrFileContent {
+            bytes,
+            file_name: self.name.clone(),
+        })
+    }
+
+    pub(super) fn traverse(&self, visit: &PyVisit<'_>) -> Result<(), PyTraverseError> {
+        visit.call(&self.reader)
     }
 }
 
-fn read_file_input(
-    py: Python<'_>,
-    file: &Bound<'_, PyAny>,
-) -> PyResult<(FileBytes, Option<String>)> {
-    if file.is_instance_of::<PyString>() {
-        return Err(PyValueError::new_err(
-            "OCR file input does not accept bare str values. Pass bytes, a pathlib.Path, or a file-like object.",
-        ));
+fn extract_bytes(value: &Bound<'_, PyAny>) -> PyResult<Bytes> {
+    if value.is_exact_instance_of::<PyBytes>() {
+        return Ok(Bytes::from_owner(value.extract::<PyBackedBytes>()?));
     }
-    if file.is_instance(&py.import("os")?.getattr("PathLike")?)? {
-        let path: PathBuf = file.extract()?;
-        let name = path
-            .file_name()
-            .map(|value| value.to_string_lossy().into_owned());
-        let bytes = py
-            .detach(|| {
-                let mut bytes = Vec::new();
-                std::fs::File::open(&path)?
-                    .take(OCR_INLINE_MAX_BYTES as u64 + 1)
-                    .read_to_end(&mut bytes)?;
-                Ok::<_, std::io::Error>(bytes)
-            })
-            .map_err(|error| {
-                if error.kind() == std::io::ErrorKind::NotFound {
-                    PyFileNotFoundError::new_err(format!("File not found: {}", path.display()))
-                } else {
-                    error.into()
-                }
-            })?;
-        return Ok((FileBytes::Native(bytes), name));
-    }
-    if file.is_instance_of::<PyBytes>() {
-        return Ok((FileBytes::Python(file.extract()?), None));
-    }
-    let reader = file
-        .getattr_opt("read")?
-        .filter(|value| value.is_callable());
-    let Some(reader) = reader else {
-        return Err(PyValueError::new_err(format!(
-            "Unsupported file input type: {}. Expected pathlib.Path, bytes, or a file-like object.",
-            file.get_type(),
-        )));
-    };
-    let name = file
-        .getattr_opt("name")?
-        .filter(|value| !value.is_none())
-        .map(|value| value.extract::<String>())
-        .transpose()?;
-    let value = reader.call0()?;
-    let bytes = if value.is_instance_of::<PyString>() {
-        FileBytes::Native(value.extract::<String>()?.into_bytes())
-    } else if value.is_instance_of::<PyBytes>() {
-        FileBytes::Python(value.extract()?)
-    } else {
-        return Err(PyTypeError::new_err(format!(
-            "OCR file read must return bytes or str, got {}",
-            value.get_type(),
-        )));
-    };
-    Ok((bytes, name))
+    Ok(Bytes::copy_from_slice(
+        value.extract::<PyBackedBytes>()?.as_ref(),
+    ))
 }
 
 pub(super) struct FileDocumentInput {
-    bytes: FileBytes,
-    name: Option<String>,
-    mime_type: Option<String>,
+    pub input: OcrDocumentInput,
+    pub reader: Option<PythonFileReader>,
 }
 
 impl FromPyObject<'_, '_> for FileDocumentInput {
@@ -104,79 +63,79 @@ impl FromPyObject<'_, '_> for FileDocumentInput {
             Err(error) if error.is_instance_of::<pyo3::exceptions::PyKeyError>(py) => None,
             Err(error) => return Err(error),
         };
+        let missing = || {
+            PyValueError::new_err(
+                "document with type='file' must include a 'file' field containing a pathlib.Path, file-like object, or bytes",
+            )
+        };
         let file = document.get_item("file").map_err(|error| {
             if error.is_instance_of::<pyo3::exceptions::PyKeyError>(py) {
-                PyValueError::new_err("document with type='file' must include a 'file' field containing a pathlib.Path, file-like object, or bytes")
+                missing()
             } else {
                 error
             }
         })?;
         if file.is_none() {
+            return Err(missing());
+        }
+        if file.is_instance_of::<PyString>() {
             return Err(PyValueError::new_err(
-                "document with type='file' must include a 'file' field containing a pathlib.Path, file-like object, or bytes",
+                "OCR file input does not accept bare str values. Pass bytes, a pathlib.Path, or a file-like object.",
             ));
         }
-        let (bytes, name) = read_file_input(py, &file)?;
+        if file.is_instance(&py.import("os")?.getattr("PathLike")?)? {
+            return Ok(Self {
+                input: OcrDocumentInput::Path {
+                    path: file.extract::<PathBuf>()?,
+                    mime_type,
+                },
+                reader: None,
+            });
+        }
+        if file.is_instance_of::<PyBytes>() {
+            return Ok(Self {
+                input: OcrDocumentInput::Bytes {
+                    bytes: extract_bytes(&file)?,
+                    file_name: None,
+                    mime_type,
+                },
+                reader: None,
+            });
+        }
+        let reader = file
+            .getattr_opt("read")?
+            .filter(|value| value.is_callable());
+        let Some(reader) = reader else {
+            return Err(PyValueError::new_err(format!(
+                "Unsupported file input type: {}. Expected pathlib.Path, bytes, or a file-like object.",
+                file.get_type(),
+            )));
+        };
+        let name = file
+            .getattr_opt("name")?
+            .filter(|value| !value.is_none())
+            .map(|value| value.extract::<String>())
+            .transpose()?;
         Ok(Self {
-            bytes,
-            name,
-            mime_type,
+            input: OcrDocumentInput::HostReader { mime_type },
+            reader: Some(PythonFileReader {
+                reader: reader.unbind(),
+                name,
+            }),
         })
     }
 }
 
-pub(super) fn file_document(py: Python<'_>, document: FileDocumentInput) -> PyResult<OcrDocument> {
-    py.detach(|| {
-        encode_file_document(
-            document.bytes.as_ref(),
-            document.name.as_deref(),
-            document.mime_type.as_deref(),
-        )
-    })
-    .map_err(|error| PyValueError::new_err(error.to_string()))
-}
-
-#[pyfunction]
-fn _ocr_file_document(py: Python<'_>, document: Bound<'_, PyAny>) -> PyResult<Py<PyAny>> {
-    to_py_preserving_errors(py, &file_document(py, document.extract()?)?)
-}
-
-#[pyfunction]
-fn _ocr_mime_type(file_name: &str) -> String {
-    mime_type_for_name(file_name).into()
-}
-
-#[pyfunction]
-#[pyo3(signature = (file_content, file_name=None, content_type=None))]
-fn _ocr_upload_document(
-    py: Python<'_>,
-    file_content: &Bound<'_, PyBytes>,
-    file_name: Option<&str>,
-    content_type: Option<&str>,
-) -> PyResult<Py<PyAny>> {
-    let bytes: PyBackedBytes = file_content.extract()?;
-    let document = py
-        .detach(|| {
-            encode_file_document(
-                &bytes,
-                None,
-                Some(upload_mime_type(file_name, content_type)),
-            )
-        })
-        .map_err(|error| PyValueError::new_err(error.to_string()))?;
-    to_py_preserving_errors(py, &document)
-}
-
-pub(super) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {
-    module.add("_OCR_MAX_FILE_BYTES", OCR_INLINE_MAX_BYTES)?;
-    module.add_function(wrap_pyfunction!(_ocr_upload_document, module)?)?;
-    module.add_function(wrap_pyfunction!(_ocr_file_document, module)?)?;
-    module.add_function(wrap_pyfunction!(_ocr_mime_type, module)?)
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
+    use pyo3::types::PyDict;
+
+    fn eval<'py>(py: Python<'py>, source: &std::ffi::CStr) -> Bound<'py, PyDict> {
+        let locals = PyDict::new(py);
+        py.run(source, Some(&locals), Some(&locals)).unwrap();
+        locals
+    }
 
     #[test]
     fn extraction_validates_required_file_and_optional_mime_type() {
@@ -196,69 +155,148 @@ mod tests {
                 let error = document.extract::<FileDocumentInput>().err().unwrap();
                 assert!(error.is_instance_of::<PyTypeError>(py));
             }
-            let document = py.eval(c"{'file': b'abc'}", None, None).unwrap();
+            let error = py
+                .eval(c"{'file': 'scan.pdf'}", None, None)
+                .unwrap()
+                .extract::<FileDocumentInput>()
+                .err()
+                .unwrap();
+            assert!(error.is_instance_of::<PyValueError>(py));
+            assert!(error.to_string().contains("bare str"));
+            let document = py
+                .eval(c"{'file': b'abc', 'mime_type': 'image/png'}", None, None)
+                .unwrap();
             let input: FileDocumentInput = document.extract().unwrap();
-            assert_eq!(input.bytes.as_ref(), b"abc");
-            assert_eq!(input.name, None);
-            assert_eq!(input.mime_type, None);
+            assert!(input.reader.is_none());
+            assert_eq!(
+                input.input,
+                OcrDocumentInput::Bytes {
+                    bytes: b"abc".as_slice().into(),
+                    file_name: None,
+                    mime_type: Some("image/png".into()),
+                }
+            );
         });
     }
 
     #[test]
-    fn extraction_validates_mime_type_before_consuming_file() {
+    fn paths_and_readers_are_projected_without_io() {
         Python::initialize();
         Python::attach(|py| {
-            let locals = PyDict::new(py);
-            py.run(
-                c"class Reader:
+            let locals = eval(
+                py,
+                c"from pathlib import Path
+class Reader:
+    name = 'scan.png'
     def __init__(self):
         self.reads = 0
     def read(self):
         self.reads += 1
         return b'abc'
 reader = Reader()
-document = {'file': reader, 'mime_type': 7}",
-                Some(&locals),
-                Some(&locals),
-            )
-            .unwrap();
+document = {'file': reader, 'mime_type': 7}
+reader_document = {'file': reader}
+path_document = {'file': Path('/nonexistent/ocr-projection-test.pdf'), 'mime_type': 'image/png'}",
+            );
             let document = locals.get_item("document").unwrap().unwrap();
             let error = document.extract::<FileDocumentInput>().err().unwrap();
             assert!(error.is_instance_of::<PyTypeError>(py));
-            let reads: usize = locals
-                .get_item("reader")
-                .unwrap()
-                .unwrap()
-                .getattr("reads")
-                .unwrap()
-                .extract()
-                .unwrap();
-            assert_eq!(reads, 0);
+
+            let document = locals.get_item("reader_document").unwrap().unwrap();
+            let input: FileDocumentInput = document.extract().unwrap();
+            assert_eq!(
+                input.input,
+                OcrDocumentInput::HostReader { mime_type: None }
+            );
+            let reads = || {
+                locals
+                    .get_item("reader")
+                    .unwrap()
+                    .unwrap()
+                    .getattr("reads")
+                    .unwrap()
+                    .extract::<usize>()
+                    .unwrap()
+            };
+            assert_eq!(reads(), 0);
+            let content = input.reader.unwrap().read(py).unwrap();
+            assert_eq!(reads(), 1);
+            assert_eq!(
+                content,
+                OcrFileContent {
+                    bytes: b"abc".as_slice().into(),
+                    file_name: Some("scan.png".into()),
+                }
+            );
+
+            let document = locals.get_item("path_document").unwrap().unwrap();
+            let input: FileDocumentInput = document.extract().unwrap();
+            assert!(input.reader.is_none());
+            assert_eq!(
+                input.input,
+                OcrDocumentInput::Path {
+                    path: PathBuf::from("/nonexistent/ocr-projection-test.pdf"),
+                    mime_type: Some("image/png".into()),
+                }
+            );
         });
     }
 
     #[test]
-    fn extraction_preserves_reader_key_error_identity() {
+    fn reader_results_are_normalized_and_exceptions_keep_their_identity() {
         Python::initialize();
         Python::attach(|py| {
-            let locals = PyDict::new(py);
-            py.run(
+            let locals = eval(
+                py,
                 c"failure = KeyError('reader failed')
-class Reader:
+class Raising:
     def read(self):
         raise failure
-document = {'file': Reader()}",
-                Some(&locals),
-                Some(&locals),
-            )
-            .unwrap();
-            let document = locals.get_item("document").unwrap().unwrap();
-            let error = document.extract::<FileDocumentInput>().err().unwrap();
+class Text:
+    def read(self):
+        return 'héllo'
+class Wrong:
+    def read(self):
+        return 7
+raising = {'file': Raising()}
+text = {'file': Text()}
+wrong = {'file': Wrong()}",
+            );
+            let reader = |name: &str| {
+                locals
+                    .get_item(name)
+                    .unwrap()
+                    .unwrap()
+                    .extract::<FileDocumentInput>()
+                    .unwrap()
+                    .reader
+                    .unwrap()
+            };
+            let error = reader("raising").read(py).unwrap_err();
             assert!(
                 error
                     .value(py)
                     .is(locals.get_item("failure").unwrap().unwrap())
             );
+            assert_eq!(
+                reader("text").read(py).unwrap().bytes.as_ref(),
+                "héllo".as_bytes()
+            );
+            let error = reader("wrong").read(py).unwrap_err();
+            assert!(error.is_instance_of::<PyTypeError>(py));
+            assert!(error.to_string().contains("bytes or str"));
         });
     }
+
+    #[test]
+    fn exact_python_bytes_transfer_without_copying_and_outlive_the_input() {
+        Python::initialize();
+        let (bytes, pointer) = Python::attach(|py| {
+            let value = PyBytes::new(py, b"document bytes");
+            let pointer = value.as_bytes().as_ptr() as usize;
+            (extract_bytes(value.as_any()).unwrap(), pointer)
+        });
+        assert_eq!(bytes.as_ptr() as usize, pointer);
+        assert_eq!(bytes.as_ref(), b"document bytes");
+    }
 }
diff --git a/litellm-rust/crates/python-bridge/src/routes/ocr/errors.rs b/litellm-rust/crates/python-bridge/src/routes/ocr/errors.rs
index e4ce813d297..7dbc35289ff 100644
--- a/litellm-rust/crates/python-bridge/src/routes/ocr/errors.rs
+++ b/litellm-rust/crates/python-bridge/src/routes/ocr/errors.rs
@@ -1,4 +1,5 @@
 use litellm_core::ocr::Error;
+use pyo3::exceptions::{PyFileNotFoundError, PyOSError};
 use pyo3::prelude::*;
 
 use crate::errors::{RustUpstreamError, core_error_to_pyerr};
@@ -7,6 +8,12 @@ pub(super) fn to_pyerr(error: Error) -> PyErr {
     let status = error.http_status_code();
     let mapped = match error {
         Error::Http { status, body } => RustUpstreamError::new_err((status, body)),
+        Error::FileRead {
+            path,
+            kind: std::io::ErrorKind::NotFound,
+            ..
+        } => PyFileNotFoundError::new_err(format!("File not found: {}", path.display())),
+        Error::FileRead { message, .. } => PyOSError::new_err(message),
         other => core_error_to_pyerr(other.into()),
     };
     attach_status(mapped, status)
diff --git a/litellm-rust/crates/python-bridge/src/routes/ocr/lifecycle.rs b/litellm-rust/crates/python-bridge/src/routes/ocr/lifecycle.rs
index 32794936899..e710b0d82f9 100644
--- a/litellm-rust/crates/python-bridge/src/routes/ocr/lifecycle.rs
+++ b/litellm-rust/crates/python-bridge/src/routes/ocr/lifecycle.rs
@@ -66,13 +66,27 @@ impl PythonOcrHost {
                 retained_fields.set_item(name, value)?;
             }
         }
-        retained_fields.set_item("document", &self.projected()?.fields.document)?;
         let projected = self.projected_mut()?;
+        let document = match &projected.fields.document {
+            Some(document) => document.clone_ref(py),
+            None => to_py(py, &request.document)?,
+        };
+        retained_fields.set_item("document", &document)?;
+        projected.fields.document = Some(document);
         projected.retained_fields = Some(retained_fields.unbind());
         projected.pre_call = Some((&request).into());
         Ok(request)
     }
 
+    fn read_document(&self, py: Python<'_>) -> PyResult<litellm_core::ocr::OcrFileContent> {
+        self.projected()?
+            .fields
+            .reader
+            .as_ref()
+            .ok_or_else(missing_state)?
+            .read(py)
+    }
+
     fn acquire_azure_ad_token(&self, py: Python<'_>) -> PyResult<ResolvedCredential> {
         let provider = self
             .projected()?
@@ -193,7 +207,7 @@ impl PythonRoute for PythonOcrHost {
                 let OcrHostData::Unprojected { request } = &self.data else {
                     return Err(missing_state());
                 };
-                let projected = project_request(py, request.bind(py), self.state.kwargs.bind(py))?;
+                let projected = project_request(request.bind(py), self.state.kwargs.bind(py))?;
                 let has_token_provider = projected.fields.azure_ad_token_provider.is_some();
                 let request = projected.request;
                 self.data = OcrHostData::Projected(Box::new(ProjectedOcrHost {
@@ -205,6 +219,7 @@ impl PythonRoute for PythonOcrHost {
                 }));
                 OcrHostResult::Request(Ok((Box::new(request), has_token_provider)))
             }
+            OcrHostOperation::ReadDocument => OcrHostResult::Document(Ok(self.read_document(py)?)),
             OcrHostOperation::AcquireAzureAdToken => {
                 OcrHostResult::AzureAdToken(Ok(self.acquire_azure_ad_token(py)?))
             }
@@ -258,6 +273,9 @@ impl PythonRoute for PythonOcrHost {
             OcrHostData::Projected(projected) => {
                 visit.call(&projected.fields.boundary_request)?;
                 visit.call(&projected.fields.document)?;
+                if let Some(reader) = &projected.fields.reader {
+                    reader.traverse(visit)?;
+                }
                 visit.call(&projected.fields.api_key)?;
                 if let Some(provider) = &projected.fields.azure_ad_token_provider {
                     provider.traverse(visit)?;
diff --git a/litellm-rust/crates/python-bridge/src/routes/ocr/mod.rs b/litellm-rust/crates/python-bridge/src/routes/ocr/mod.rs
index f17bf249b7f..5eae8ccf33f 100644
--- a/litellm-rust/crates/python-bridge/src/routes/ocr/mod.rs
+++ b/litellm-rust/crates/python-bridge/src/routes/ocr/mod.rs
@@ -9,6 +9,5 @@ use pyo3::prelude::*;
 
 pub(super) fn register(module: &Bound<'_, PyModule>) -> PyResult<()> {
     value::register(module)?;
-    document::register(module)?;
     lifecycle::register(module)
 }
diff --git a/litellm-rust/crates/python-bridge/src/routes/ocr/project.rs b/litellm-rust/crates/python-bridge/src/routes/ocr/project.rs
index 8d8d5f8c518..ad223645c62 100644
--- a/litellm-rust/crates/python-bridge/src/routes/ocr/project.rs
+++ b/litellm-rust/crates/python-bridge/src/routes/ocr/project.rs
@@ -1,14 +1,15 @@
 use std::sync::Arc;
 
-use litellm_core::ocr::wire::{OcrWireRequest, consumed_optional_params, decode_request};
-use litellm_core::ocr::{LiteLLMOcrRequest, NativeOutcome, OcrCall};
-use litellm_python_interop::{
-    from_py_preserving_errors as from_py, to_py_preserving_errors as to_py,
+use litellm_core::ocr::wire::{
+    OcrWireRequest, consumed_optional_params, decode_document, decode_request_input,
 };
+use litellm_core::ocr::{LiteLLMOcrRequest, NativeOutcome, OcrCall, OcrDocumentInput};
+use litellm_python_interop::from_py_preserving_errors as from_py;
 use pyo3::prelude::*;
 use pyo3::types::PyDict;
 use serde_json::{Map, Value};
 
+use super::document::{FileDocumentInput, PythonFileReader};
 use super::errors::to_pyerr as ocr_error_to_pyerr;
 use super::lifecycle::BridgeOcrHooks;
 use crate::auth::{AZURE_AD_TOKEN_PROVIDER, PythonTokenProvider};
@@ -17,7 +18,8 @@ use crate::marshal::{project_optional_fields, python_timeout_seconds, request_in
 
 pub(super) struct ProjectedOcrFields {
     pub boundary_request: Py<PyAny>,
-    pub document: Py<PyAny>,
+    pub document: Option<Py<PyAny>>,
+    pub reader: Option<PythonFileReader>,
     pub api_key: Py<PyAny>,
     pub azure_ad_token_provider: Option<PythonTokenProvider>,
     pub provider: &'static str,
@@ -25,7 +27,7 @@ pub(super) struct ProjectedOcrFields {
 }
 
 pub(super) struct ProjectedOcrCall {
-    pub request: LiteLLMOcrRequest,
+    pub request: LiteLLMOcrRequest<OcrDocumentInput>,
     pub fields: ProjectedOcrFields,
 }
 
@@ -80,12 +82,12 @@ impl<'py> OcrArguments<'_, 'py> {
 }
 
 enum ProjectedDocument {
-    File { wire: Value, retained: Py<PyAny> },
+    File(FileDocumentInput),
     Other { wire: Value, retained: Py<PyAny> },
 }
 
 impl ProjectedDocument {
-    fn project(py: Python<'_>, document: &Bound<'_, PyAny>) -> PyResult<Self> {
+    fn project(document: &Bound<'_, PyAny>) -> PyResult<Self> {
         let kind: String = document.get_item("type")?.extract()?;
         if kind != "file" {
             return Ok(Self::Other {
@@ -93,25 +95,28 @@ impl ProjectedDocument {
                 retained: document.clone().unbind(),
             });
         }
-        let input = document.extract()?;
-        let encoded = super::document::file_document(py, input)?;
-        let wire = serde_json::to_value(encoded)
-            .map_err(|error| pyo3::exceptions::PyValueError::new_err(error.to_string()))?;
-        Ok(Self::File {
-            retained: to_py(py, &wire)?,
-            wire,
-        })
+        Ok(Self::File(document.extract()?))
     }
 
-    fn into_parts(self) -> (Value, Py<PyAny>) {
+    fn into_parts(
+        self,
+    ) -> PyResult<(
+        OcrDocumentInput,
+        Option<Py<PyAny>>,
+        Option<PythonFileReader>,
+    )> {
         match self {
-            Self::File { wire, retained } | Self::Other { wire, retained } => (wire, retained),
+            Self::File(FileDocumentInput { input, reader }) => Ok((input, None, reader)),
+            Self::Other { wire, retained } => Ok((
+                decode_document(wire).map_err(ocr_error_to_pyerr)?.into(),
+                Some(retained),
+                None,
+            )),
         }
     }
 }
 
 pub(super) fn project_request(
-    py: Python<'_>,
     request: &Bound<'_, PyAny>,
     kwargs: &Bound<'_, PyDict>,
 ) -> PyResult<ProjectedOcrCall> {
@@ -119,8 +124,7 @@ pub(super) fn project_request(
     let arguments = OcrArguments { request, kwargs };
     let model = arguments.model()?;
     let custom_llm_provider = arguments.custom_llm_provider()?;
-    let (wire_document, retained_document) =
-        ProjectedDocument::project(py, &arguments.document()?)?.into_parts();
+    let document = ProjectedDocument::project(&arguments.document()?)?;
     let api_key = arguments.api_key()?;
     let specs = consumed_optional_params(&model, custom_llm_provider.as_deref())
         .map_err(ocr_error_to_pyerr)?;
@@ -136,9 +140,10 @@ pub(super) fn project_request(
     let azure_ad_token_provider = kwargs
         .get_item("azure_ad_token_provider")?
         .and_then(|provider| PythonTokenProvider::select(provider, AZURE_AD_TOKEN_PROVIDER));
+    let (document, retained_document, reader) = document.into_parts()?;
     let wire = OcrWireRequest {
         model,
-        document: wire_document,
+        document,
         api_key: api_key.extract()?,
         api_base: arguments.api_base()?,
         custom_llm_provider,
@@ -147,13 +152,14 @@ pub(super) fn project_request(
         input_sources,
         timeout_seconds: arguments.timeout_seconds()?,
     };
-    let request = decode_request(wire).map_err(ocr_error_to_pyerr)?;
+    let request = decode_request_input(wire).map_err(ocr_error_to_pyerr)?;
     let provider = request.provider_name();
     Ok(ProjectedOcrCall {
         request: request.with_host_hooks(Arc::new(BridgeOcrHooks), None),
         fields: ProjectedOcrFields {
             boundary_request,
             document: retained_document,
+            reader,
             api_key: api_key.unbind(),
             azure_ad_token_provider,
             provider,
@@ -197,10 +203,21 @@ mod tests {
     }
 
     fn project_document(
-        py: Python<'_>,
         document: &Bound<'_, PyAny>,
-    ) -> PyResult<(Value, Py<PyAny>)> {
-        ProjectedDocument::project(py, document).map(ProjectedDocument::into_parts)
+    ) -> PyResult<(
+        OcrDocumentInput,
+        Option<Py<PyAny>>,
+        Option<PythonFileReader>,
+    )> {
+        ProjectedDocument::project(document)?.into_parts()
+    }
+
+    fn url_document(url: &str) -> OcrDocumentInput {
+        litellm_core::ocr::OcrDocument::DocumentUrl {
+            document_url: url.into(),
+            extra_fields: Map::new(),
+        }
+        .into()
     }
 
     fn stub_timeout_conversion(py: Python<'_>) {
@@ -374,7 +391,7 @@ kwargs = {}
     }
 
     #[test]
-    fn document_reader_mutations_are_visible_to_later_field_reads() {
+    fn document_readers_are_not_consumed_during_projection() {
         Python::initialize();
         Python::attach(|py| {
             stub_timeout_conversion(py);
@@ -406,7 +423,12 @@ kwargs = {}
                 .unwrap();
             let arguments = arguments(&request, &kwargs);
             let document = arguments.document().unwrap();
-            project_document(py, &document).unwrap();
+            let (input, retained, reader) = project_document(&document).unwrap();
+            assert_eq!(input, OcrDocumentInput::HostReader { mime_type: None });
+            assert!(retained.is_none());
+            assert_eq!(arguments.api_base().unwrap().as_deref(), Some("original"));
+            assert_eq!(arguments.timeout_seconds().unwrap(), Some(1.0));
+            reader.unwrap().read(py).unwrap();
             assert_eq!(arguments.api_base().unwrap().as_deref(), Some("mutated"));
             assert_eq!(arguments.timeout_seconds().unwrap(), Some(9.0));
         });
@@ -444,7 +466,7 @@ kwargs = {'api_key': key}
     }
 
     #[test]
-    fn file_documents_are_encoded_and_other_documents_keep_the_python_object() {
+    fn file_documents_become_typed_inputs_and_other_documents_keep_the_python_object() {
         Python::initialize();
         Python::attach(|py| {
             let file = py
@@ -454,13 +476,17 @@ kwargs = {'api_key': key}
                     None,
                 )
                 .unwrap();
+            let (input, retained, reader) = project_document(&file).unwrap();
             assert_eq!(
-                project_document(py, &file).unwrap().0,
-                serde_json::json!({
-                    "type": "document_url",
-                    "document_url": "data:application/pdf;base64,JVBERi0xLjQ=",
-                })
+                input,
+                OcrDocumentInput::Bytes {
+                    bytes: b"%PDF-1.4".as_slice().into(),
+                    file_name: None,
+                    mime_type: Some("application/pdf".into()),
+                }
             );
+            assert!(retained.is_none());
+            assert!(reader.is_none());
 
             let original = py
                 .eval(
@@ -469,44 +495,21 @@ kwargs = {'api_key': key}
                     None,
                 )
                 .unwrap();
-            let (wire, retained) = project_document(py, &original).unwrap();
-            assert_eq!(
-                wire,
-                serde_json::json!({
-                    "type": "document_url",
-                    "document_url": "https://example.com/a.pdf",
-                })
-            );
-            assert!(retained.bind(py).is(&original));
+            let (input, retained, _) = project_document(&original).unwrap();
+            assert_eq!(input, url_document("https://example.com/a.pdf"));
+            assert!(retained.unwrap().bind(py).is(&original));
         });
     }
 
     #[test]
-    fn unknown_document_types_reach_existing_downstream_validation() {
+    fn unknown_document_types_reach_existing_core_validation() {
         Python::initialize();
         Python::attach(|py| {
             let document = py
                 .eval(c"{'type': 'mystery', 'mystery': 'x'}", None, None)
                 .unwrap();
-            let wire_document = project_document(py, &document).unwrap().0;
-            assert_eq!(
-                wire_document,
-                serde_json::json!({"type": "mystery", "mystery": "x"})
-            );
-            let error = match decode_request(OcrWireRequest {
-                model: "mistral/mistral-ocr-latest".into(),
-                document: wire_document,
-                api_key: None,
-                api_base: None,
-                custom_llm_provider: None,
-                extra_headers: None,
-                optional_params: Map::new(),
-                input_sources: Default::default(),
-                timeout_seconds: None,
-            }) {
-                Ok(_) => panic!("unknown discriminators belong to core validation"),
-                Err(error) => error,
-            };
+            let error = project_document(&document).unwrap_err();
+            assert!(error.is_instance_of::<PyValueError>(py));
             assert!(error.to_string().contains("document"));
         });
     }
@@ -517,14 +520,14 @@ kwargs = {'api_key': key}
         Python::attach(|py| {
             let missing = py.eval(c"{}", None, None).unwrap();
             assert!(
-                project_document(py, &missing)
+                project_document(&missing)
                     .unwrap_err()
                     .is_instance_of::<PyKeyError>(py)
             );
 
             let non_string = py.eval(c"{'type': 1}", None, None).unwrap();
             assert!(
-                project_document(py, &non_string)
+                project_document(&non_string)
                     .unwrap_err()
                     .is_instance_of::<PyTypeError>(py)
             );
@@ -540,7 +543,7 @@ document = Document()
 ",
             );
             let error =
-                project_document(py, &locals.get_item("document").unwrap().unwrap()).unwrap_err();
+                project_document(&locals.get_item("document").unwrap().unwrap()).unwrap_err();
             assert!(
                 error
                     .value(py)
@@ -569,9 +572,9 @@ document = Document()
 ",
             );
             let document = locals.get_item("document").unwrap().unwrap();
-            let (wire, retained) = project_document(py, &document).unwrap();
-            assert_eq!(wire["type"], "document_url");
-            assert!(!retained.bind(py).is(&document));
+            let (input, retained, _) = project_document(&document).unwrap();
+            assert!(matches!(input, OcrDocumentInput::Bytes { .. }));
+            assert!(retained.is_none());
             let reads: Vec<String> = document.getattr("reads").unwrap().extract().unwrap();
             assert_eq!(reads, ["type", "mime_type", "file"]);
         });
diff --git a/litellm/ocr/input.py b/litellm/ocr/input.py
deleted file mode 100644
index bcb448371c4..00000000000
--- a/litellm/ocr/input.py
+++ /dev/null
@@ -1,112 +0,0 @@
-from collections.abc import Mapping
-from os import PathLike
-from typing import Final, Literal, Protocol, cast  # noqa: TID251  # native callables are validated when loaded
-
-from typing_extensions import NotRequired, ReadOnly, TypedDict
-
-from litellm.rust_bridge.bindings import NativeBinding
-from litellm.rust_bridge.configuration import rust_ocr_enabled
-
-
-class FileReader(Protocol):
-    def read(self) -> bytes | str: ...
-
-
-class FileDocument(TypedDict):
-    type: ReadOnly[Literal["file"]]
-    file: ReadOnly[bytes | PathLike[str] | FileReader]
-    mime_type: ReadOnly[NotRequired[str]]
-
-
-class NativeFileDocument(Protocol):
-    def __call__(self, document: Mapping[str, object]) -> dict[str, str]: ...
-
-
-class NativeUploadDocument(Protocol):
-    def __call__(self, file_content: bytes, file_name: str | None, content_type: str | None) -> dict[str, str]: ...
-
-
-class NativeMimeType(Protocol):
-    def __call__(self, file_name: str) -> str: ...
-
-
-_FILE_DOCUMENT: Final = NativeBinding(
-    "_ocr_file_document",
-    validate=lambda value: (
-        cast(  # cast-ok: native export owns the callable signature
-            NativeFileDocument, value
-        )
-        if callable(value)
-        else None
-    ),
-)
-_UPLOAD_DOCUMENT: Final = NativeBinding(
-    "_ocr_upload_document",
-    validate=lambda value: (
-        cast(  # cast-ok: native export owns the callable signature
-            NativeUploadDocument, value
-        )
-        if callable(value)
-        else None
-    ),
-)
-_MAX_FILE_BYTES: Final = NativeBinding(
-    "_OCR_MAX_FILE_BYTES", validate=lambda value: value if isinstance(value, int) and value > 0 else None
-)
-_MIME_TYPE: Final = NativeBinding(
-    "_ocr_mime_type",
-    validate=lambda value: (
-        cast(  # cast-ok: native export owns the callable signature
-            NativeMimeType, value
-        )
-        if callable(value)
-        else None
-    ),
-)
-_PYTHON_MAX_FILE_BYTES: Final = 50 * 1024 * 1024
-
-
-def get_mime_type(file_path: str) -> str:
-    native: Final = _MIME_TYPE.load() if rust_ocr_enabled() else None
-    if native is None:
-        from litellm.ocr import legacy
-
-        return legacy.get_mime_type(file_path)
-    return native(file_path)
-
-
-def get_max_file_bytes() -> int:
-    limit: Final = _MAX_FILE_BYTES.load() if rust_ocr_enabled() else None
-    if limit is None:
-        return _PYTHON_MAX_FILE_BYTES
-    return limit
-
-
-def convert_file_document_to_url_document(document: FileDocument) -> dict[str, str]:
-    native: Final = _FILE_DOCUMENT.load() if rust_ocr_enabled() else None
-    if native is None:
-        from litellm.ocr import legacy
-
-        return legacy.convert_file_document_to_url_document(document)
-    return native(document)
-
-
-def convert_upload_to_url_document(
-    file_content: bytes, filename: str | None, content_type: str | None
-) -> dict[str, str]:
-    native: Final = _UPLOAD_DOCUMENT.load() if rust_ocr_enabled() else None
-    if native is None:
-        from litellm.ocr import legacy
-
-        if len(file_content) > _PYTHON_MAX_FILE_BYTES:
-            raise ValueError("OCR file exceeds the size limit")
-        content_mime: Final = content_type.split(";")[0].strip() if content_type else None
-        mime_type: Final = (
-            legacy.get_mime_type(filename)
-            if filename and (not content_mime or content_mime == "application/octet-stream")
-            else content_mime or "application/octet-stream"
-        )
-        return legacy.convert_file_document_to_url_document(
-            {"type": "file", "file": file_content, "mime_type": mime_type}
-        )
-    return native(file_content, filename, content_type)
diff --git a/litellm/ocr/legacy.py b/litellm/ocr/legacy.py
index a742be274b3..f0cf6cc82cc 100644
--- a/litellm/ocr/legacy.py
+++ b/litellm/ocr/legacy.py
@@ -11,7 +11,7 @@ from collections.abc import Coroutine, Mapping
 from dataclasses import dataclass
 from io import IOBase
 from types import MappingProxyType
-from typing import Final, cast  # noqa: TID251  # adapters preserve the legacy untyped contracts
+from typing import Final, Protocol, cast  # noqa: TID251  # adapters preserve the legacy untyped contracts
 
 import httpx
 
@@ -26,7 +26,6 @@ from litellm.llms.base_llm.ocr.transformation import (
     parse_ocr_request_format,
 )
 from litellm.llms.custom_httpx.llm_http_handler import BaseLLMHTTPHandler
-from litellm.ocr.input import FileReader
 from litellm.types.router import GenericLiteLLMParams
 from litellm.types.utils import CustomPricingLiteLLMParams
 from litellm.utils import ProviderConfigManager, client
@@ -34,6 +33,10 @@ from litellm.utils import ProviderConfigManager, client
 base_llm_http_handler: Final = BaseLLMHTTPHandler()
 
 
+class FileReader(Protocol):
+    def read(self) -> bytes | str: ...
+
+
 @dataclass(frozen=True, slots=True)
 class _PreparedOCRRequest:
     model: str
diff --git a/litellm/ocr/main.py b/litellm/ocr/main.py
index 382c5d6aae4..c6371c0c33f 100644
--- a/litellm/ocr/main.py
+++ b/litellm/ocr/main.py
@@ -5,7 +5,7 @@ import httpx
 
 from litellm.llms.base_llm.ocr.transformation import OCRResponse
 from litellm.ocr import legacy
-from litellm.ocr.input import convert_file_document_to_url_document, get_mime_type
+from litellm.ocr.legacy import convert_file_document_to_url_document, get_mime_type
 from litellm.rust_bridge.bindings import native_exception_types
 from litellm.rust_bridge.configuration import rust_ocr_enabled
 from litellm.rust_bridge.ocr import LiteLLMOcrRequest
diff --git a/litellm/proxy/ocr_endpoints/endpoints.py b/litellm/proxy/ocr_endpoints/endpoints.py
index 53ebbe91b54..dde3d5ceb50 100644
--- a/litellm/proxy/ocr_endpoints/endpoints.py
+++ b/litellm/proxy/ocr_endpoints/endpoints.py
@@ -15,12 +15,13 @@ from litellm.llms.base_llm.ocr.transformation import (
     OCRResponse,
     parse_ocr_request_format,
 )
-from litellm.ocr.input import convert_upload_to_url_document, get_max_file_bytes
+from litellm.ocr.legacy import convert_file_document_to_url_document, get_mime_type
 from litellm.proxy._types import *
 from litellm.proxy.auth.user_api_key_auth import UserAPIKeyAuth, user_api_key_auth
 from litellm.proxy.common_request_processing import ProxyBaseLLMRequestProcessing
 
 router: Final = APIRouter()
+_MAX_FILE_BYTES: Final = 50 * 1024 * 1024
 
 
 def _build_document_from_upload(
@@ -28,7 +29,15 @@ def _build_document_from_upload(
     filename: str | None,
     content_type: str | None,
 ) -> dict[str, str]:
-    return convert_upload_to_url_document(file_content, filename, content_type)
+    supplied_mime: Final = content_type.split(";")[0].strip() if content_type else None
+    mime_type: Final = (
+        get_mime_type(filename)
+        if filename and (not supplied_mime or supplied_mime == "application/octet-stream")
+        else supplied_mime
+    )
+    return convert_file_document_to_url_document(
+        {"type": "file", "file": file_content, "mime_type": mime_type or "application/octet-stream"}
+    )
 
 
 def _with_request_format(data: Mapping[str, Any], request: Request) -> Mapping[str, Any]:
@@ -103,9 +112,11 @@ async def _parse_multipart_form(request: Request) -> dict[str, Any]:
 
     # Seek to start in case the file was already partially read by middleware
     await uploaded_file.seek(0)
-    file_content: Final = await uploaded_file.read(get_max_file_bytes() + 1)
+    file_content: Final = await uploaded_file.read(_MAX_FILE_BYTES + 1)
     if not file_content:
         raise ValueError("Uploaded file is empty")
+    if len(file_content) > _MAX_FILE_BYTES:
+        raise ValueError("OCR file exceeds the size limit")
 
     document: Final = _build_document_from_upload(
         file_content=file_content,
diff --git a/litellm/rust_bridge/_native.pyi b/litellm/rust_bridge/_native.pyi
index e62c85f4599..32b20bb7931 100644
--- a/litellm/rust_bridge/_native.pyi
+++ b/litellm/rust_bridge/_native.pyi
@@ -33,15 +33,6 @@ def aocr(
     timeout_seconds: float | None = None,
 ) -> Future[dict[str, object]]: ...
 
-_OCR_MAX_FILE_BYTES: int
-
-def _ocr_upload_document(
-    file_content: bytes,
-    file_name: str | None = None,
-    content_type: str | None = None,
-) -> dict[str, str]: ...
-def _ocr_file_document(document: Mapping[str, object]) -> dict[str, str]: ...
-def _ocr_mime_type(file_name: str) -> str: ...
 def _ocr_lifecycle(
     request: LiteLLMOcrRequest,
     args: tuple[object, ...],
@@ -139,15 +130,11 @@ class TokenCounter:
 def gil_stats() -> dict[str, int]: ...
 
 __all__ = [
-    "_OCR_MAX_FILE_BYTES",
     "ResponsesWebSocketConnection",
     "RustBridgeDeclined",
     "RustUpstreamError",
     "TokenCounter",
-    "_ocr_file_document",
     "_ocr_lifecycle",
-    "_ocr_mime_type",
-    "_ocr_upload_document",
     "achat_completions",
     "amessages",
     "aocr",
diff --git a/tests/test_litellm/ocr/test_ocr_file_input.py b/tests/test_litellm/ocr/test_ocr_file_input.py
index 3526d8c00d6..8f82a64bd85 100644
--- a/tests/test_litellm/ocr/test_ocr_file_input.py
+++ b/tests/test_litellm/ocr/test_ocr_file_input.py
@@ -12,32 +12,16 @@ Tests that:
 import base64
 import os
 import tempfile
-from collections.abc import Generator
 from io import BytesIO
 from pathlib import Path
 from typing import Final
-from unittest.mock import AsyncMock, MagicMock, Mock
+from unittest.mock import AsyncMock, MagicMock
 
 import orjson
 import pytest
 from starlette.datastructures import FormData
 
-from litellm.ocr.input import convert_file_document_to_url_document, get_mime_type
-
-
-@pytest.fixture(autouse=True, params=["native", "disabled", "unavailable"])
-def document_runtime(request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch) -> Generator[None]:
-    from litellm.rust_bridge import bindings, configuration
-
-    configuration.reset_rust_configuration()
-    monkeypatch.delenv("LITELLM_RUST", raising=False)
-    if request.param == "disabled":
-        monkeypatch.setenv("LITELLM_RUST", "0")
-        monkeypatch.setattr(bindings, "get_native_bridge", Mock(side_effect=AssertionError("Rust is disabled")))
-    elif request.param == "unavailable":
-        monkeypatch.setattr(bindings, "get_native_bridge", lambda: None)
-    yield
-    configuration.reset_rust_configuration()
+from litellm.ocr.legacy import convert_file_document_to_url_document, get_mime_type
 
 
 class TestGetMimeType:
@@ -503,10 +487,9 @@ class TestProxySecurityGuard:
 async def test_proxy_upload_stops_reading_at_size_limit() -> None:
     from starlette.datastructures import UploadFile
 
-    from litellm.ocr.input import get_max_file_bytes
-    from litellm.proxy.ocr_endpoints.endpoints import _parse_multipart_form
+    from litellm.proxy.ocr_endpoints.endpoints import _MAX_FILE_BYTES, _parse_multipart_form
 
-    limit: Final = get_max_file_bytes()
+    limit: Final = _MAX_FILE_BYTES
     with tempfile.TemporaryFile() as stream:
         stream.truncate(limit * 2)
         upload: Final = UploadFile(file=stream, filename="large.pdf")
diff --git a/tests/test_litellm_rust/ocr/test_requests.py b/tests/test_litellm_rust/ocr/test_requests.py
index 4f4b39fa6c6..58bb6a77537 100644
--- a/tests/test_litellm_rust/ocr/test_requests.py
+++ b/tests/test_litellm_rust/ocr/test_requests.py
@@ -518,32 +518,34 @@ async def test_native_ocr_inherits_named_credentials_without_overwriting_argumen
     assert ocr_server.requests[0].body["pages"] == [0, 2]
 
 
-@pytest.mark.parametrize("source", ["sdk", "proxy"])
 @pytest.mark.parametrize(
-    "filename,mime", [("scan.PNG", "image/png"), ("document.pdf", "application/pdf"), ("note.txt", "text/plain")]
+    "filename,field,mime",
+    [("scan.PNG", "image_url", "image/png"), ("document.pdf", "document_url", "application/pdf")],
 )
-def test_ocr_file_helpers_use_native_document_preparation(source: str, filename: str, mime: str) -> None:
+def test_native_ocr_infers_mime_type_from_reader_name(
+    ocr_server: RecordingServer, filename: str, field: str, mime: str
+) -> None:
     from io import BytesIO
 
-    from litellm.ocr.input import convert_file_document_to_url_document, get_mime_type
-    from litellm.proxy.ocr_endpoints.endpoints import _build_document_from_upload
-
     file: Final = BytesIO(b"abc")
     file.name = filename
-    document: Final = (
-        convert_file_document_to_url_document({"type": "file", "file": file})
-        if source == "sdk"
-        else _build_document_from_upload(b"abc", filename, "application/octet-stream; charset=utf-8")
-    )
-    field: Final = "image_url" if mime.startswith("image/") else "document_url"
-    assert get_mime_type(filename) == mime
-    assert document == {"type": field, field: f"data:{mime};base64,YWJj"}
+    call_native_ocr(ocr_server, document={"type": "file", "file": file})
+    assert ocr_server.requests[0].body["document"] == {"type": field, field: f"data:{mime};base64,YWJj"}
+
+
+def test_native_ocr_encodes_str_reader_results_as_utf8(ocr_server: RecordingServer) -> None:
+    from io import StringIO
+
+    call_native_ocr(ocr_server, document={"type": "file", "file": StringIO("abc"), "mime_type": "text/plain"})
+    assert ocr_server.requests[0].body["document"] == {
+        "type": "document_url",
+        "document_url": "data:text/plain;base64,YWJj",
+    }
 
 
 @pytest.mark.parametrize("attribute", ["read", "name"])
-def test_native_file_preparation_preserves_property_errors(attribute: str) -> None:
-    from litellm.ocr.input import convert_file_document_to_url_document
-
+def test_native_file_preparation_preserves_property_errors(ocr_server: RecordingServer, attribute: str) -> None:
+    ocr_server.expected_requests = 0
     failure: Final = LookupError("file property failed")
 
     class File:
@@ -555,16 +557,47 @@ def test_native_file_preparation_preserves_property_errors(attribute: str) -> No
         def read(self):
             return b"abc"
 
-    with pytest.raises(LookupError) as caught:
-        convert_file_document_to_url_document({"type": "file", "file": File()})
-    assert caught.value is failure
+    with pytest.raises(litellm.APIConnectionError, match="file property failed") as caught:
+        call_native_ocr(ocr_server, document={"type": "file", "file": File()})
+    assert caught.value.__context__ is failure
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("asynchronous", [False, True])
+async def test_native_file_preparation_preserves_reader_exception(
+    ocr_server: RecordingServer, asynchronous: bool
+) -> None:
+    ocr_server.expected_requests = 0
+    failure: Final = RuntimeError("reader failed")
+
+    class Reader:
+        def read(self) -> bytes:
+            raise failure
+
+    document: Final = {"type": "file", "file": Reader()}
+    with pytest.raises(litellm.APIConnectionError, match="reader failed") as caught:
+        await call_native_aocr(ocr_server, document=document) if asynchronous else call_native_ocr(
+            ocr_server, document=document
+        )
+    assert caught.value.__context__ is failure
+
+
+def test_native_file_preparation_rejects_unsupported_reader_results(ocr_server: RecordingServer) -> None:
+    ocr_server.expected_requests = 0
+
+    class Reader:
+        def read(self) -> int:
+            return 1
+
+    with pytest.raises(litellm.APIConnectionError, match="bytes or str") as caught:
+        call_native_ocr(ocr_server, document={"type": "file", "file": Reader()})
+    assert isinstance(caught.value.__context__, TypeError)
 
 
 @pytest.mark.parametrize("kind", ["bytes", "path", "reader"])
-def test_native_file_preparation_rejects_oversized_input(kind: str, tmp_path: Path) -> None:
-    from litellm.ocr.input import FileDocument, convert_file_document_to_url_document, get_max_file_bytes
-
-    limit: Final = get_max_file_bytes()
+def test_native_file_preparation_rejects_oversized_input(ocr_server: RecordingServer, kind: str, tmp_path: Path) -> None:
+    ocr_server.expected_requests = 0
+    limit: Final = 50 * 1024 * 1024
     path: Final = tmp_path / "large.pdf"
     with path.open("wb") as stream:
         stream.truncate(limit + 1)
@@ -573,53 +606,25 @@ def test_native_file_preparation_rejects_oversized_input(kind: str, tmp_path: Pa
         def read(self) -> bytes:
             return b"a" * (limit + 1)
 
-    document: Final[FileDocument] = {
+    document: Final = {
         "type": "file",
         "file": path if kind == "path" else Reader() if kind == "reader" else b"a" * (limit + 1),
     }
-    with pytest.raises(ValueError, match="exceeds the size limit"):
-        convert_file_document_to_url_document(document)
+    with pytest.raises(litellm.BadRequestError, match="exceeds the size limit"):
+        call_native_ocr(ocr_server, document=document)
 
 
-@pytest.mark.parametrize("kind", ["str", "path", "reader"])
-def test_native_upload_binding_rejects_filesystem_inputs(kind: str, tmp_path: Path) -> None:
+def test_native_file_preparation_reports_missing_paths(ocr_server: RecordingServer, tmp_path: Path) -> None:
+    ocr_server.expected_requests = 0
+    missing: Final = tmp_path / "missing.pdf"
+    with pytest.raises(litellm.APIConnectionError, match=f"File not found: {missing}") as caught:
+        call_native_ocr(ocr_server, document={"type": "file", "file": missing})
+    assert isinstance(caught.value.__context__, FileNotFoundError)
+
+
+def test_native_file_preparation_rejects_empty_readers(ocr_server: RecordingServer) -> None:
     from io import BytesIO
-    from typing import cast  # noqa: TID251  # deliberately invalid inputs exercise the native runtime boundary
 
-    from litellm.ocr.input import convert_upload_to_url_document
-
-    path: Final = tmp_path / "secret.pdf"
-    path.write_bytes(b"server secret")
-    source: Final = str(path) if kind == "str" else path if kind == "path" else BytesIO(b"abc")
-    with pytest.raises(TypeError):
-        convert_upload_to_url_document(cast(bytes, source), "document.pdf", None)
-
-
-@pytest.mark.parametrize("extra_bytes", [0, 1])
-def test_native_upload_enforces_file_size_limit(extra_bytes: int) -> None:
-    import base64
-
-    from litellm.ocr.input import convert_upload_to_url_document, get_max_file_bytes
-
-    content: Final = b"a" * (get_max_file_bytes() + extra_bytes)
-    if extra_bytes:
-        with pytest.raises(ValueError, match="exceeds the size limit"):
-            convert_upload_to_url_document(content, "scan.pdf", None)
-        return
-    document: Final = convert_upload_to_url_document(content, "scan.pdf", None)
-    assert document["type"] == "document_url"
-    assert base64.b64decode(document["document_url"].split(",", 1)[1]) == content
-
-
-def test_native_file_preparation_preserves_reader_exception() -> None:
-    from litellm.ocr.input import convert_file_document_to_url_document
-
-    failure: Final = RuntimeError("reader failed")
-
-    class Reader:
-        def read(self) -> bytes:
-            raise failure
-
-    with pytest.raises(RuntimeError) as caught:
-        convert_file_document_to_url_document({"type": "file", "file": Reader()})
-    assert caught.value is failure
+    ocr_server.expected_requests = 0
+    with pytest.raises(litellm.BadRequestError, match="File is empty"):
+        call_native_ocr(ocr_server, document={"type": "file", "file": BytesIO(b"")})

From cfe65f7b551c192fb6edd402ea37ba7ea4646e18 Mon Sep 17 00:00:00 2001
From: ryan-crabbe-berri <ryan@berri.ai>
Date: Wed, 16 Sep 2026 14:15:27 -0700
Subject: [PATCH 61/76] fix(proxy)!: enforce fallback budget by default

A budget bypass that ships off by default stays open for every deployment
that does not know to look for the flag, so `enforce_fallback_budget` now
defaults to true and `general_settings.enforce_fallback_budget: false` is
the opt-out for anyone who wants the old unguarded behaviour back.

BREAKING CHANGE: a paid fallback target is now refused for callers who are
over their key or user `max_budget`. Deployments relying on fallbacks to
keep serving over-budget callers must set enforce_fallback_budget: false.
---
 litellm/proxy/auth/fallback_budget.py          |  6 +++---
 .../proxy/auth/test_fallback_budget.py         | 18 ++++++++++++++++++
 tests/test_litellm/proxy/test_proxy_server.py  |  9 +++++----
 3 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/litellm/proxy/auth/fallback_budget.py b/litellm/proxy/auth/fallback_budget.py
index 00e885d8d88..e356f8acc7d 100644
--- a/litellm/proxy/auth/fallback_budget.py
+++ b/litellm/proxy/auth/fallback_budget.py
@@ -8,8 +8,8 @@ actually bills. So a free model with a paid fallback spends without a gate.
 
 This predicate is injected into the router to re-check budget for each fallback target before it is
 attempted, mirroring `fallback_model_access.py`. It deliberately leaves the primary attempt alone:
-a zero-cost model is never blocked by budget, and only the paid fallback is refused. Opt-in via
-`general_settings.enforce_fallback_budget: true`.
+a zero-cost model is never blocked by budget, and only the paid fallback is refused. On by default;
+set `general_settings.enforce_fallback_budget: false` to restore the unguarded behaviour.
 
 Scope: the key's and the user's `max_budget`. Not covered yet, and each needs a read-only evaluation
 path before it can be: team, team-member, end-user, org, global and per-model budgets, whose
@@ -50,7 +50,7 @@ class _RequestMetadata(BaseModel):
 
 
 class _FallbackBudgetSettings(BaseModel):
-    enforce_fallback_budget: bool = False
+    enforce_fallback_budget: bool = True
 
 
 def _token_in_metadata(metadata: object) -> UserAPIKeyAuth | None:
diff --git a/tests/test_litellm/proxy/auth/test_fallback_budget.py b/tests/test_litellm/proxy/auth/test_fallback_budget.py
index 0ff1e05826d..00c1a7cdefc 100644
--- a/tests/test_litellm/proxy/auth/test_fallback_budget.py
+++ b/tests/test_litellm/proxy/auth/test_fallback_budget.py
@@ -5,6 +5,7 @@ from litellm.proxy._types import UserAPIKeyAuth
 from litellm.proxy.auth.fallback_budget import (
     RouterFallbackBudgetCheck,
     is_token_within_budget_for_model,
+    router_fallback_budget_check,
 )
 
 FREE_MODEL = {
@@ -182,3 +183,20 @@ async def test_router_without_a_budget_check_attempts_every_fallback():
     over = {"metadata": {"user_api_key_auth": _token(user_spend=1900.0, user_max_budget=50.0)}}
 
     assert await _is_fallback_target_within_budget(router, "paid-model", "free-model", over) is True
+
+
+@pytest.mark.asyncio
+async def test_enforcement_is_on_by_default_and_opt_out_restores_the_leak(monkeypatch):
+    """
+    Leaving the paid fallback unguarded is the budget bypass this module exists to close, so an
+    unconfigured proxy has to enforce. `enforce_fallback_budget: false` is the deliberate opt-out.
+    """
+    from litellm.proxy import proxy_server
+
+    over = {"metadata": {"user_api_key_auth": _token(user_spend=1900.0, user_max_budget=50.0)}}
+
+    monkeypatch.setattr(proxy_server, "general_settings", {}, raising=False)
+    assert await router_fallback_budget_check(model="paid-model", request_kwargs=over, llm_router=_router()) is False
+
+    monkeypatch.setattr(proxy_server, "general_settings", {"enforce_fallback_budget": False}, raising=False)
+    assert await router_fallback_budget_check(model="paid-model", request_kwargs=over, llm_router=_router()) is True
diff --git a/tests/test_litellm/proxy/test_proxy_server.py b/tests/test_litellm/proxy/test_proxy_server.py
index ca53887623f..ad28b6b4421 100644
--- a/tests/test_litellm/proxy/test_proxy_server.py
+++ b/tests/test_litellm/proxy/test_proxy_server.py
@@ -13416,14 +13416,15 @@ async def test_load_config_router_budget_checks_fallback_targets_against_the_cal
         }
     }
 
-    # off by default: the paid fallback is still attempted for an over-budget caller
+    # on by default: an over-budget caller is refused the paid fallback with no config at all
     monkeypatch.setattr(proxy_server, "general_settings", {}, raising=False)
-    assert await router.fallback_budget_check(model="m", request_kwargs=over_budget, llm_router=router) is True
-
-    monkeypatch.setattr(proxy_server, "general_settings", {"enforce_fallback_budget": True}, raising=False)
     assert await router.fallback_budget_check(model="m", request_kwargs=over_budget, llm_router=router) is False
     assert await router.fallback_budget_check(model="m", request_kwargs=under_budget, llm_router=router) is True
 
+    # explicit opt-out restores the unguarded behaviour
+    monkeypatch.setattr(proxy_server, "general_settings", {"enforce_fallback_budget": False}, raising=False)
+    assert await router.fallback_budget_check(model="m", request_kwargs=over_budget, llm_router=router) is True
+
 
 @pytest.mark.asyncio
 async def test_load_config_user_api_key_cache_max_size_keeps_more_than_200_entries(tmp_path, monkeypatch):

From b4781317012c57c1bd7e186d1478b465316c6dfb Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 14:20:49 -0700
Subject: [PATCH 62/76] test(together_ai): select the live model from the cost
 map

`together_ai/openai/gpt-oss-20b` was hardcoded in two live tests and is no
longer served, so both failed on a vendor catalog change rather than on
anything litellm did.

Both call sites now resolve the cheapest non-deprecated together_ai chat
entry at runtime, filtered on the capabilities the tests actually exercise,
mirroring what tests/e2e/llm_translation/test_together_ai_e2e.py already
does. The selector lives in tests/_live_test_helpers.py so both lanes share
one implementation.
---
 tests/_live_test_helpers.py                 | 36 +++++++++++++++++++++
 tests/llm_translation/test_together_ai.py   |  7 +++-
 tests/local_testing/test_text_completion.py |  7 +++-
 3 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/tests/_live_test_helpers.py b/tests/_live_test_helpers.py
index a79b81e82c1..6b39f37921d 100644
--- a/tests/_live_test_helpers.py
+++ b/tests/_live_test_helpers.py
@@ -1,4 +1,7 @@
 import os
+from collections.abc import Mapping
+from datetime import date
+from typing import Any
 
 import pytest
 
@@ -8,3 +11,36 @@ def _skip_live_prompt_caching_test():
         pytest.skip("Live prompt-caching E2E tests are opt-in")
     if os.environ.get("CASSETTE_REDIS_URL"):
         pytest.skip("Live prompt-caching E2E tests cannot run under VCR replay")
+
+
+def cheapest_together_chat_model(*capability_flags: str) -> str:
+    import litellm
+
+    today = date.today().isoformat()
+
+    def qualifies(name: str, entry: Mapping[str, Any]) -> bool:
+        deprecation_date = entry.get("deprecation_date")
+        return (
+            name.startswith("together_ai/")
+            and entry.get("litellm_provider") == "together_ai"
+            and entry.get("mode") == "chat"
+            and (deprecation_date is None or deprecation_date > today)
+            and (entry.get("input_cost_per_token") or 0.0) > 0
+            and (entry.get("output_cost_per_token") or 0.0) > 0
+            and all(bool(entry.get(flag)) for flag in capability_flags)
+        )
+
+    candidates = sorted(
+        (
+            name
+            for name, entry in litellm.model_cost.items()
+            if isinstance(entry, Mapping) and qualifies(name, entry)
+        ),
+        key=lambda name: (
+            litellm.model_cost[name].get("input_cost_per_token") or 0.0,
+            litellm.model_cost[name].get("output_cost_per_token") or 0.0,
+            name,
+        ),
+    )
+    assert candidates, f"no live together_ai chat model in the cost map satisfies {capability_flags}"
+    return candidates[0]
diff --git a/tests/llm_translation/test_together_ai.py b/tests/llm_translation/test_together_ai.py
index fd7ad40ed11..7a49d46b528 100644
--- a/tests/llm_translation/test_together_ai.py
+++ b/tests/llm_translation/test_together_ai.py
@@ -3,6 +3,7 @@ Test TogetherAI LLM
 """
 
 from base_llm_unit_tests import BaseLLMChatTest
+from tests._live_test_helpers import cheapest_together_chat_model
 import json
 import os
 from datetime import datetime
@@ -16,7 +17,11 @@ import pytest
 class TestTogetherAI(BaseLLMChatTest):
     def get_base_completion_call_args(self) -> dict:
         litellm.set_verbose = True
-        return {"model": "together_ai/openai/gpt-oss-20b"}
+        return {
+            "model": cheapest_together_chat_model(
+                "supports_function_calling", "supports_response_schema"
+            )
+        }
 
     def test_tool_call_no_arguments(self, tool_call_no_arguments):
         """Test that tool calls with no arguments is translated correctly. Relevant issue: https://github.com/BerriAI/litellm/issues/6833"""
diff --git a/tests/local_testing/test_text_completion.py b/tests/local_testing/test_text_completion.py
index a814ce6d303..b15037a2fcd 100644
--- a/tests/local_testing/test_text_completion.py
+++ b/tests/local_testing/test_text_completion.py
@@ -1,7 +1,11 @@
 import asyncio
 import json
+import os
+import sys
 import traceback
 
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
+
 from dotenv import load_dotenv
 
 load_dotenv()
@@ -12,6 +16,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 import litellm
+from tests._live_test_helpers import cheapest_together_chat_model
 from litellm import (
     RateLimitError,
     TextCompletionResponse,
@@ -4030,7 +4035,7 @@ def test_async_text_completion_together_ai():
     async def test_get_response():
         try:
             response = await litellm.atext_completion(
-                model="together_ai/openai/gpt-oss-20b",
+                model=cheapest_together_chat_model(),
                 prompt="good morning",
                 max_tokens=10,
             )

From ba6c9fa61d87bd76634bdaba7ce4ef578771f923 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 14:26:16 -0700
Subject: [PATCH 63/76] fix(test): drop the redundant sys.path.insert

CI runs these lanes as `python -m pytest` from the repo root, so the root is
already on sys.path and `tests._live_test_helpers` imports without help. The
insert only tripped the TQ003 test-quality budget.
---
 tests/local_testing/test_text_completion.py | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/tests/local_testing/test_text_completion.py b/tests/local_testing/test_text_completion.py
index b15037a2fcd..6808dfd768b 100644
--- a/tests/local_testing/test_text_completion.py
+++ b/tests/local_testing/test_text_completion.py
@@ -1,11 +1,7 @@
 import asyncio
 import json
-import os
-import sys
 import traceback
 
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")))
-
 from dotenv import load_dotenv
 
 load_dotenv()

From 515bf8c9d564731cfb285d47818db2fc081e1ba7 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 14:32:08 -0700
Subject: [PATCH 64/76] refactor(test): validate cost-map entries into a typed
 model

The selector read raw cost-map dicts as `Mapping[str, Any]`. It now validates
each together_ai entry into a frozen Pydantic model and takes the two
capabilities as keyword booleans, so nothing in the helper is coarsely typed
or stringly addressed.
---
 tests/_live_test_helpers.py               | 56 +++++++++++++++--------
 tests/llm_translation/test_together_ai.py |  2 +-
 2 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/tests/_live_test_helpers.py b/tests/_live_test_helpers.py
index 6b39f37921d..629f8ac9fdb 100644
--- a/tests/_live_test_helpers.py
+++ b/tests/_live_test_helpers.py
@@ -1,9 +1,8 @@
 import os
-from collections.abc import Mapping
 from datetime import date
-from typing import Any
 
 import pytest
+from pydantic import BaseModel, ConfigDict
 
 
 def _skip_live_prompt_caching_test():
@@ -13,34 +12,53 @@ def _skip_live_prompt_caching_test():
         pytest.skip("Live prompt-caching E2E tests cannot run under VCR replay")
 
 
-def cheapest_together_chat_model(*capability_flags: str) -> str:
+
+class TogetherCostEntry(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    litellm_provider: str | None = None
+    mode: str | None = None
+    deprecation_date: str | None = None
+    input_cost_per_token: float | None = None
+    output_cost_per_token: float | None = None
+    supports_function_calling: bool | None = None
+    supports_response_schema: bool | None = None
+
+
+def cheapest_together_chat_model(
+    *, function_calling: bool = False, response_schema: bool = False
+) -> str:
     import litellm
 
     today = date.today().isoformat()
 
-    def qualifies(name: str, entry: Mapping[str, Any]) -> bool:
-        deprecation_date = entry.get("deprecation_date")
+    def qualifies(name: str, entry: TogetherCostEntry) -> bool:
         return (
             name.startswith("together_ai/")
-            and entry.get("litellm_provider") == "together_ai"
-            and entry.get("mode") == "chat"
-            and (deprecation_date is None or deprecation_date > today)
-            and (entry.get("input_cost_per_token") or 0.0) > 0
-            and (entry.get("output_cost_per_token") or 0.0) > 0
-            and all(bool(entry.get(flag)) for flag in capability_flags)
+            and entry.litellm_provider == "together_ai"
+            and entry.mode == "chat"
+            and (entry.deprecation_date is None or entry.deprecation_date > today)
+            and (entry.input_cost_per_token or 0.0) > 0
+            and (entry.output_cost_per_token or 0.0) > 0
+            and (not function_calling or bool(entry.supports_function_calling))
+            and (not response_schema or bool(entry.supports_response_schema))
         )
 
+    registry: dict[str, TogetherCostEntry] = {
+        name: TogetherCostEntry.model_validate(raw)
+        for name, raw in litellm.model_cost.items()
+        if isinstance(raw, dict) and name.startswith("together_ai/")
+    }
     candidates = sorted(
-        (
-            name
-            for name, entry in litellm.model_cost.items()
-            if isinstance(entry, Mapping) and qualifies(name, entry)
-        ),
+        (name for name, entry in registry.items() if qualifies(name, entry)),
         key=lambda name: (
-            litellm.model_cost[name].get("input_cost_per_token") or 0.0,
-            litellm.model_cost[name].get("output_cost_per_token") or 0.0,
+            registry[name].input_cost_per_token or 0.0,
+            registry[name].output_cost_per_token or 0.0,
             name,
         ),
     )
-    assert candidates, f"no live together_ai chat model in the cost map satisfies {capability_flags}"
+    assert candidates, (
+        "no live together_ai chat model in the cost map satisfies "
+        f"function_calling={function_calling} response_schema={response_schema}"
+    )
     return candidates[0]
diff --git a/tests/llm_translation/test_together_ai.py b/tests/llm_translation/test_together_ai.py
index 7a49d46b528..0b4e9d3952c 100644
--- a/tests/llm_translation/test_together_ai.py
+++ b/tests/llm_translation/test_together_ai.py
@@ -19,7 +19,7 @@ class TestTogetherAI(BaseLLMChatTest):
         litellm.set_verbose = True
         return {
             "model": cheapest_together_chat_model(
-                "supports_function_calling", "supports_response_schema"
+                function_calling=True, response_schema=True
             )
         }
 

From 0de187e76cc0268bdf8e19e73b3cdaac80015bd2 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 14:34:13 -0700
Subject: [PATCH 65/76] style(test): annotate the new locals as Final

---
 .../test_generic_api_callback.py                    | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/tests/logging_callback_tests/test_generic_api_callback.py b/tests/logging_callback_tests/test_generic_api_callback.py
index 2c62741ed38..d9853ebcb52 100644
--- a/tests/logging_callback_tests/test_generic_api_callback.py
+++ b/tests/logging_callback_tests/test_generic_api_callback.py
@@ -10,6 +10,7 @@ import httpx
 import json
 import logging
 import time
+from typing import Final
 from unittest.mock import AsyncMock, patch
 
 import pytest
@@ -98,8 +99,8 @@ async def test_generic_api_callback():
     assert isinstance(actual_request, list), "Request body should be a list"
     assert len(actual_request) > 0, "Request body list should not be empty"
 
-    this_test_messages = [{"role": "user", "content": "Hello, world!"}]
-    mine = [
+    this_test_messages: Final = [{"role": "user", "content": "Hello, world!"}]
+    mine: Final = [
         item for item in actual_request if item.get("messages") == this_test_messages
     ]
     assert (
@@ -455,12 +456,14 @@ async def test_generic_api_callback_sumologic_uses_ndjson():
     assert isinstance(ndjson_data, str), "Data should be a string for NDJSON"
 
     lines = ndjson_data.strip().split("\n")
-    records = [json.loads(line) for line in lines]
+    records: Final = [json.loads(line) for line in lines]
 
-    this_test_messages = [
+    this_test_messages: Final = [
         [{"role": "user", "content": f"Test {i}"}] for i in range(2)
     ]
-    mine = [record for record in records if record.get("messages") in this_test_messages]
+    mine: Final = [
+        record for record in records if record.get("messages") in this_test_messages
+    ]
     assert (
         len(mine) == 2
     ), f"Expected this test's 2 calls as NDJSON lines, got {len(mine)} of {len(records)}"

From a6b10ad654948fd70d84c697542703cd3b4e2a0f Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 14:58:57 -0700
Subject: [PATCH 66/76] fix(prices): dedupe Nova cache_read_input_token_cost
 keys left by a text merge

PR #41343 and PR #41112 both added cache_read_input_token_cost to the six amazon.nova-{micro,lite,pro}-v1:0 and us.amazon.nova-* entries, one at the top of each entry and one at the bottom. The merge kept both, so every PR now fails test_price_map_has_no_duplicate_keys. Both copies carried the same value, so this only removes the trailing duplicate in both price files
---
 ...model_prices_and_context_window_backup.json | 18 ++++++------------
 model_prices_and_context_window.json           | 18 ++++++------------
 2 files changed, 12 insertions(+), 24 deletions(-)

diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index b1c38d0350a..92e5b1c4ff7 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -377,8 +377,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "amazon.nova-2-lite-v1:0": {
         "cache_read_input_token_cost": 7.5e-08,
@@ -561,8 +560,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "amazon.nova-pro-v1:0": {
         "cache_read_input_token_cost": 2e-07,
@@ -578,8 +576,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "amazon.nova-sonic-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45794,8 +45791,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "us.amazon.nova-micro-v1:0": {
         "cache_read_input_token_cost": 8.75e-09,
@@ -45809,8 +45805,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "us.amazon.nova-premier-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45842,8 +45837,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "us.anthropic.claude-3-5-haiku-20241022-v1:0": {
         "cache_creation_input_token_cost": 1e-06,
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index b1c38d0350a..92e5b1c4ff7 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -377,8 +377,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "amazon.nova-2-lite-v1:0": {
         "cache_read_input_token_cost": 7.5e-08,
@@ -561,8 +560,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "amazon.nova-pro-v1:0": {
         "cache_read_input_token_cost": 2e-07,
@@ -578,8 +576,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "amazon.nova-sonic-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45794,8 +45791,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "us.amazon.nova-micro-v1:0": {
         "cache_read_input_token_cost": 8.75e-09,
@@ -45809,8 +45805,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "us.amazon.nova-premier-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45842,8 +45837,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "us.anthropic.claude-3-5-haiku-20241022-v1:0": {
         "cache_creation_input_token_cost": 1e-06,

From 76c0f8db1d415a0307f4188a0ca992688ec3b44b Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 15:01:08 -0700
Subject: [PATCH 67/76] chore(e2e): report the key components behind a mount
 that never converges

Builds 232 and 233 held the Bedrock hit rate at 9% with the Claude Code
driver already sending byte-identical requests and headers, so something
between the proxy's ingress and the upstream still moves per build and
the flat key cannot say what.

Emit a digest per key component next to the counters: the test id, the
method, the URL, each keyed header, the whole body, and one digest per
top-level JSON body field. Values are digested, so no payload or
credential reaches the artifact. Diffing two builds' artifacts names the
field that moved.

Diagnostic, to be removed once it has answered.
---
 tests/e2e/provider_cache.py       | 63 +++++++++++++++++++++++++++++--
 tests/e2e/provider_cache_redis.py |  4 ++
 2 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/tests/e2e/provider_cache.py b/tests/e2e/provider_cache.py
index 444972ffce5..22967869c78 100644
--- a/tests/e2e/provider_cache.py
+++ b/tests/e2e/provider_cache.py
@@ -4,6 +4,8 @@ import base64
 import hashlib
 import hmac
 import io
+import json
+import os
 import threading
 import time
 from collections.abc import Callable, Generator, Mapping
@@ -400,6 +402,51 @@ def decode_response(secret: bytes, key: str, payload: bytes, mount: str, url: st
     return response
 
 
+def component_digests(
+    test_key: str, method: str, url: str, headers: Mapping[str, str], body: bytes | None,
+) -> dict[str, str]:
+    """Per-component digests of everything the key covers.
+
+    A mount whose corpus never converges is a mount where one of these moves
+    between builds, and the flat key cannot say which. Values are digested, so
+    no payload or credential is written, and a JSON body contributes one digest
+    per top-level field so the field that moved can be named."""
+    parts: dict[str, str] = {  # rebind-ok: a report assembled from three differently shaped sources
+        "test_key": test_key,
+        "method": method,
+        "url": short_digest(canonical_text(url).encode()),
+    }
+    for name, value in sorted(headers.items()):
+        parts[f"header:{name.lower()}"] = short_digest(value.encode())
+    canonical: Final = b"" if body is None else canonical_body(body)
+    parts["body"] = short_digest(canonical)
+    try:
+        parsed: Final = JSON_VALUE.validate_json(canonical)
+    except ValidationError:
+        return parts
+    if isinstance(parsed, dict):
+        for name, value in sorted(parsed.items()):
+            parts[f"body:{name}"] = short_digest(json.dumps(value, sort_keys=True).encode())
+    return parts
+
+
+def short_digest(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()[:16]
+
+
+@dataclass(slots=True)
+class KeyProbe:
+    """Every keyed request's components, when a metrics directory is configured."""
+
+    rows: tuple[tuple[tuple[str, str], ...], ...] = ()
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def observe(self, mount: str, outcome: str, parts: Mapping[str, str]) -> None:
+        row: Final = tuple({"mount": mount, "outcome": outcome, **parts}.items())
+        with self.lock:
+            self.rows = (*self.rows, row)
+
+
 @dataclass(slots=True)
 class CacheCounters:
     counts: tuple[tuple[str, int], ...] = ()
@@ -464,6 +511,7 @@ class CacheEdge:
     store: ResponseStore
     secret: bytes = field(repr=False)
     counters: CacheCounters = field(default_factory=CacheCounters)
+    probe: KeyProbe = field(default_factory=KeyProbe)
     slots: SlotCounter = field(default_factory=SlotCounter)
     policies: Mapping[str, MountPolicy] = NO_POLICIES
     wait_seconds: float = 2.0
@@ -481,6 +529,14 @@ class CacheEdge:
         self.counters.increment(name)
         self.counters.increment(f"mount:{mount}:{name}")
 
+    def record_key(
+        self, mount: str, outcome: str, test_key: str, method: str, url: str,
+        headers: Mapping[str, str], body: bytes | None,
+    ) -> None:
+        if not os.environ.get("E2E_PROVIDER_CACHE_METRICS_DIR"):
+            return
+        self.probe.observe(mount, outcome, component_digests(test_key, method, url, headers, body))
+
     def outbound(self, mount: str, method: str, url: str, headers: dict[str, str], body: bytes | None) -> dict[str, str]:
         """The headers actually sent upstream. A signing mount gets a signature
         minted over the upstream URL, because the edge rewrote the Host the proxy
@@ -511,20 +567,21 @@ class CacheEdge:
         if isinstance(prepared, NetworkError):
             self.reject(mount, UNREACHABLE)
             return prepared
-        identity: Final = request_identity(
-            self.secret, test_key, method, url, self.keyed(mount, prepared.headers), body,
-        )
+        keyed_headers: Final = self.keyed(mount, prepared.headers)
+        identity: Final = request_identity(self.secret, test_key, method, url, keyed_headers, body)
         key: Final = slotted_key(self.secret, identity, self.slots.take(identity))
         found: Final = self.lookup(key)
         if isinstance(found, CacheHit):
             response: Final = decode_response(self.secret, key, found.payload, mount, url)
             if response is not None and self.clock() < found.valid_until:
                 self.count(mount, "hits")
+                self.record_key(mount, "hit", test_key, method, url, keyed_headers, body)
                 return StreamHead(response.status_code, response.headers, response_steps(response))
             self.count(mount, "corrupt" if response is None else "expired")
             self.store.discard(key, found.payload)
         capture_slot: Final = self.lookup(key) if isinstance(found, CacheHit) else found
         self.count(mount, "misses")
+        self.record_key(mount, "miss", test_key, method, url, keyed_headers, body)
         if isinstance(capture_slot, CacheUnavailable):
             self.count(mount, "cache_errors")
         self.count(mount, "upstream_attempts")
diff --git a/tests/e2e/provider_cache_redis.py b/tests/e2e/provider_cache_redis.py
index be4e31b2c49..2c7419cfc0f 100644
--- a/tests/e2e/provider_cache_redis.py
+++ b/tests/e2e/provider_cache_redis.py
@@ -134,6 +134,10 @@ def write_metrics(cache: CacheEdge) -> None:
             root: Final = Path(directory)
             root.mkdir(parents=True, exist_ok=True)
             (root / f"{os.getpid()}.json").write_text(report + "\n")
+            if cache.probe.rows:
+                (root / f"keys-{os.getpid()}.json").write_text(
+                    json.dumps([dict(row) for row in cache.probe.rows]) + "\n"
+                )
         except OSError:
             logging.getLogger(__name__).warning("provider cache metrics artifact unavailable")
     logging.getLogger(__name__).info("%s", report)

From a9fc6d255b5bd82220f3c2265eaf568dcf179423 Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 15:15:42 -0700
Subject: [PATCH 68/76] fix(prices): dedupe Nova cache_read_input_token_cost
 keys left by a text merge

Six Amazon Nova entries define cache_read_input_token_cost twice, which
is what a clean text merge of two branches that both added the field
looks like. JSON parsers keep the last occurrence, so this turned
test_price_map_has_no_duplicate_keys red on every open PR's merge commit,
including this one, which touches neither file.

Both occurrences in all six entries carry the same value, so dropping the
later one leaves every parsed price identical.

Same change as #41496, carried here so this branch is not blocked on it.
Identical deletions, so the two merge cleanly in either order.
---
 ...model_prices_and_context_window_backup.json | 18 ++++++------------
 model_prices_and_context_window.json           | 18 ++++++------------
 2 files changed, 12 insertions(+), 24 deletions(-)

diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index b1c38d0350a..92e5b1c4ff7 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -377,8 +377,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "amazon.nova-2-lite-v1:0": {
         "cache_read_input_token_cost": 7.5e-08,
@@ -561,8 +560,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "amazon.nova-pro-v1:0": {
         "cache_read_input_token_cost": 2e-07,
@@ -578,8 +576,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "amazon.nova-sonic-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45794,8 +45791,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "us.amazon.nova-micro-v1:0": {
         "cache_read_input_token_cost": 8.75e-09,
@@ -45809,8 +45805,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "us.amazon.nova-premier-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45842,8 +45837,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "us.anthropic.claude-3-5-haiku-20241022-v1:0": {
         "cache_creation_input_token_cost": 1e-06,
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index b1c38d0350a..92e5b1c4ff7 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -377,8 +377,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "amazon.nova-2-lite-v1:0": {
         "cache_read_input_token_cost": 7.5e-08,
@@ -561,8 +560,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "amazon.nova-pro-v1:0": {
         "cache_read_input_token_cost": 2e-07,
@@ -578,8 +576,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "amazon.nova-sonic-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45794,8 +45791,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 1.5e-08
+        "supports_tool_choice": true
     },
     "us.amazon.nova-micro-v1:0": {
         "cache_read_input_token_cost": 8.75e-09,
@@ -45809,8 +45805,7 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 8.75e-09
+        "supports_tool_choice": true
     },
     "us.amazon.nova-premier-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45842,8 +45837,7 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true,
-        "cache_read_input_token_cost": 2e-07
+        "supports_tool_choice": true
     },
     "us.anthropic.claude-3-5-haiku-20241022-v1:0": {
         "cache_creation_input_token_cost": 1e-06,

From b9751a38ab0a21f56703569b18b3db084a6fa1ae Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 15:36:54 -0700
Subject: [PATCH 69/76] Revert "fix(prices): dedupe Nova
 cache_read_input_token_cost keys left by a text merge"

This reverts commit a9fc6d255b5bd82220f3c2265eaf568dcf179423.
---
 ...model_prices_and_context_window_backup.json | 18 ++++++++++++------
 model_prices_and_context_window.json           | 18 ++++++++++++------
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index 92e5b1c4ff7..b1c38d0350a 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -377,7 +377,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 1.5e-08
     },
     "amazon.nova-2-lite-v1:0": {
         "cache_read_input_token_cost": 7.5e-08,
@@ -560,7 +561,8 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 8.75e-09
     },
     "amazon.nova-pro-v1:0": {
         "cache_read_input_token_cost": 2e-07,
@@ -576,7 +578,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 2e-07
     },
     "amazon.nova-sonic-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45791,7 +45794,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 1.5e-08
     },
     "us.amazon.nova-micro-v1:0": {
         "cache_read_input_token_cost": 8.75e-09,
@@ -45805,7 +45809,8 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 8.75e-09
     },
     "us.amazon.nova-premier-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45837,7 +45842,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 2e-07
     },
     "us.anthropic.claude-3-5-haiku-20241022-v1:0": {
         "cache_creation_input_token_cost": 1e-06,
diff --git a/model_prices_and_context_window.json b/model_prices_and_context_window.json
index 92e5b1c4ff7..b1c38d0350a 100644
--- a/model_prices_and_context_window.json
+++ b/model_prices_and_context_window.json
@@ -377,7 +377,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 1.5e-08
     },
     "amazon.nova-2-lite-v1:0": {
         "cache_read_input_token_cost": 7.5e-08,
@@ -560,7 +561,8 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 8.75e-09
     },
     "amazon.nova-pro-v1:0": {
         "cache_read_input_token_cost": 2e-07,
@@ -576,7 +578,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 2e-07
     },
     "amazon.nova-sonic-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45791,7 +45794,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 1.5e-08
     },
     "us.amazon.nova-micro-v1:0": {
         "cache_read_input_token_cost": 8.75e-09,
@@ -45805,7 +45809,8 @@
         "supports_function_calling": true,
         "supports_prompt_caching": true,
         "supports_response_schema": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 8.75e-09
     },
     "us.amazon.nova-premier-v1:0": {
         "deprecation_date": "2026-09-14",
@@ -45837,7 +45842,8 @@
         "supports_prompt_caching": true,
         "supports_response_schema": true,
         "supports_vision": true,
-        "supports_tool_choice": true
+        "supports_tool_choice": true,
+        "cache_read_input_token_cost": 2e-07
     },
     "us.anthropic.claude-3-5-haiku-20241022-v1:0": {
         "cache_creation_input_token_cost": 1e-06,

From 287bbaa6c170191774f56d0143fb35fcda371a8b Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Wed, 16 Sep 2026 01:08:08 +0000
Subject: [PATCH 70/76] fix(proxy): remove duplicate user budget hook that
 429'd zero-cost models

_PROXY_MaxBudgetLimiter re-checked spend:user:{id} against user_max_budget in
async_pre_call_hook without the zero-cost model exemption that
_user_max_budget_check applies in auth, so free models were rejected with
"Max budget limit reached." once a user was over budget. Auth already owns
this check, so the hook is deleted rather than taught the exemption again

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 ARCHITECTURE.md                               |   3 +-
 .../common_utils/proxy_rate_limit_error.py    |   2 +-
 litellm/proxy/hooks/__init__.py               |   4 +-
 litellm/proxy/hooks/max_budget_limiter.py     |  84 -------
 litellm/proxy/utils.py                        |   4 +-
 .../budgets/BUDGET_TEST_COVERAGE_MATRIX.md    |   2 +-
 .../test_unit_test_litellm_logging.py         |  12 +-
 .../proxy/hooks/test_max_budget_limiter.py    | 237 ------------------
 .../test_proxy_rate_limit_provider_field.py   |  61 +----
 .../proxy/proxy_server/test_routes_config.py  |   4 +-
 .../test_proxy_logging_hook_detection.py      |   2 +-
 .../utils/proxy_logging/test_lifecycle.py     |  10 +-
 .../utils/proxy_logging/test_pre_call_hook.py |  34 ++-
 .../test_rate_limit_error_unification.py      |  69 -----
 14 files changed, 52 insertions(+), 476 deletions(-)
 delete mode 100644 litellm/proxy/hooks/max_budget_limiter.py
 delete mode 100644 tests/test_litellm/proxy/hooks/test_max_budget_limiter.py

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index b04e004aa1a..f418752d990 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -45,7 +45,7 @@ sequenceDiagram
     ProxyServer->>Auth: user_api_key_auth()
     Auth->>Redis: Check API key cache
     Redis-->>Auth: Key info + spend limits
-    ProxyServer->>Hooks: max_budget_limiter, parallel_request_limiter
+    ProxyServer->>Hooks: parallel_request_limiter, cache_control_check
     Hooks->>Redis: Check/increment rate limit counters
     ProxyServer->>Router: route_request()
     Router->>Main: litellm.acompletion()
@@ -145,7 +145,6 @@ graph TD
 
 | Hook | File | Purpose |
 |------|------|---------|
-| `max_budget_limiter` | `proxy/hooks/max_budget_limiter.py` | Enforce budget limits |
 | `parallel_request_limiter` | `proxy/hooks/parallel_request_limiter_v3.py` | Rate limiting per key/user |
 | `cache_control_check` | `proxy/hooks/cache_control_check.py` | Cache validation |
 | `responses_id_security` | `proxy/hooks/responses_id_security.py` | Response ID validation |
diff --git a/litellm/proxy/common_utils/proxy_rate_limit_error.py b/litellm/proxy/common_utils/proxy_rate_limit_error.py
index c109da6f571..888a6d077ad 100644
--- a/litellm/proxy/common_utils/proxy_rate_limit_error.py
+++ b/litellm/proxy/common_utils/proxy_rate_limit_error.py
@@ -11,7 +11,7 @@ exception types:
   an upstream LLM provider returns 429.
 * :class:`fastapi.HTTPException` (status 429) — raised directly by proxy hooks
   such as ``parallel_request_limiter``, ``dynamic_rate_limiter``,
-  ``batch_rate_limiter``, ``max_budget_limiter``, ``max_iterations_limiter``,
+  ``batch_rate_limiter``, ``max_iterations_limiter``,
   etc.
 * :class:`litellm.llms.base_llm.chat.transformation.BaseLLMException` (status
   429) — raised by some provider transports.
diff --git a/litellm/proxy/hooks/__init__.py b/litellm/proxy/hooks/__init__.py
index f3542098f95..a504c2ba102 100644
--- a/litellm/proxy/hooks/__init__.py
+++ b/litellm/proxy/hooks/__init__.py
@@ -4,7 +4,6 @@ from typing import Final, Literal
 from . import *
 from .cache_control_check import _PROXY_CacheControlCheck
 from .litellm_skills import SkillsInjectionHook
-from .max_budget_limiter import _PROXY_MaxBudgetLimiter
 from .max_budget_per_session_limiter import _PROXY_MaxBudgetPerSessionHandler
 from .max_iterations_limiter import _PROXY_MaxIterationsHandler
 from .parallel_request_limiter import _PROXY_MaxParallelRequestsHandler
@@ -18,7 +17,6 @@ from .sensitive_data_routing import _PROXY_SensitiveDataRoutingHandler
 # transitively through `enterprise.enterprise_hooks` can resolve `PROXY_HOOKS`
 # and `get_proxy_hook` from this partially-initialized module without circling.
 PROXY_HOOKS: Final = {
-    "max_budget_limiter": _PROXY_MaxBudgetLimiter,
     "parallel_request_limiter": _PROXY_MaxParallelRequestsHandler_v3,
     "cache_control_check": _PROXY_CacheControlCheck,
     "responses_id_security": ResponsesIDSecurity,
@@ -35,7 +33,7 @@ if os.getenv("LEGACY_MULTI_INSTANCE_RATE_LIMITING", "false").lower() == "true":
 
 
 def get_proxy_hook(
-    hook_name: Literal["max_budget_limiter", "managed_files", "parallel_request_limiter", "cache_control_check"] | str,
+    hook_name: Literal["managed_files", "parallel_request_limiter", "cache_control_check"] | str,
 ):
     """
     Factory method to get a proxy hook instance by name
diff --git a/litellm/proxy/hooks/max_budget_limiter.py b/litellm/proxy/hooks/max_budget_limiter.py
deleted file mode 100644
index eaf37b0bcf1..00000000000
--- a/litellm/proxy/hooks/max_budget_limiter.py
+++ /dev/null
@@ -1,84 +0,0 @@
-from typing import Final
-
-from fastapi import HTTPException
-
-from litellm import verbose_logger
-from litellm._logging import verbose_proxy_logger
-from litellm.caching.caching import DualCache
-from litellm.exceptions import RateLimitType
-from litellm.integrations.custom_logger import CustomLogger
-from litellm.proxy._types import UserAPIKeyAuth
-from litellm.proxy.common_utils.proxy_rate_limit_error import ProxyRateLimitError
-from litellm.proxy.hooks.rate_limiter_utils import resolve_llm_provider_for_rate_limit
-
-
-class _PROXY_MaxBudgetLimiter(CustomLogger):
-    # Class variables or attributes
-    def __init__(self):
-        pass
-
-    async def async_pre_call_hook(
-        self,
-        user_api_key_dict: UserAPIKeyAuth,
-        cache: DualCache,
-        data: dict,
-        call_type: str,
-    ):
-        try:
-            verbose_proxy_logger.debug("Inside Max Budget Limiter Pre-Call Hook")
-            max_budget: Final = user_api_key_dict.user_max_budget
-            user_id: Final = user_api_key_dict.user_id
-
-            if max_budget is None or user_id is None:
-                return
-
-            from litellm.proxy.proxy_server import general_settings
-
-            if (
-                user_api_key_dict.team_id is not None
-                and general_settings.get("apply_user_budget_to_team_keys") is not True
-            ):
-                return
-
-            # The reservation path admits at the strict-`<` boundary and
-            # atomically pre-fills the same counter we'd read here. Re-checking
-            # with `>=` would reject a request the reservation already admitted
-            # when the reservation fills the counter to exactly max_budget.
-            # Imported lazily to avoid a circular import via proxy.utils.
-            from litellm.proxy.spend_tracking.budget_reservation import (
-                get_reserved_counter_keys,
-            )
-
-            user_counter_key: Final = f"spend:user:{user_id}"
-            if user_counter_key in get_reserved_counter_keys(user_api_key_dict.budget_reservation):
-                return
-
-            from litellm.proxy.proxy_server import get_current_spend
-
-            curr_spend: Final = await get_current_spend(
-                counter_key=user_counter_key,
-                fallback_spend=user_api_key_dict.user_spend or 0.0,
-            )
-
-            verbose_proxy_logger.debug(
-                "MaxBudgetLimiter: user_id=%s, spend=%.6f, max=%.6f",
-                user_id,
-                curr_spend,
-                max_budget,
-            )
-
-            # CHECK IF REQUEST ALLOWED
-            if curr_spend >= max_budget:
-                resolved_model, llm_provider = resolve_llm_provider_for_rate_limit(data.get("model") if data else None)
-                raise ProxyRateLimitError(
-                    detail="Max budget limit reached.",
-                    rate_limit_type=RateLimitType.BUDGET,
-                    model=resolved_model,
-                    llm_provider=llm_provider,
-                )
-        except HTTPException as e:
-            raise e
-        except Exception as e:
-            verbose_logger.exception(
-                "litellm.proxy.hooks.max_budget_limiter.py::async_pre_call_hook(): Exception occured - %s", e
-            )
diff --git a/litellm/proxy/utils.py b/litellm/proxy/utils.py
index 99cd78e0b58..18e58861266 100644
--- a/litellm/proxy/utils.py
+++ b/litellm/proxy/utils.py
@@ -164,7 +164,6 @@ from litellm.proxy.guardrails.guardrail_hooks.unified_guardrail.unified_guardrai
 )
 from litellm.proxy.hooks import PROXY_HOOKS, get_proxy_hook
 from litellm.proxy.hooks.cache_control_check import _PROXY_CacheControlCheck
-from litellm.proxy.hooks.max_budget_limiter import _PROXY_MaxBudgetLimiter
 from litellm.proxy.hooks.parallel_request_limiter import (
     _PROXY_MaxParallelRequestsHandler,
 )
@@ -982,7 +981,6 @@ class ProxyLogging:
             dual_cache=DualCache(default_in_memory_ttl=1)  # ping redis cache every 1s
         )
         self.max_parallel_request_limiter = _PROXY_MaxParallelRequestsHandler(self.internal_usage_cache)
-        self.max_budget_limiter = _PROXY_MaxBudgetLimiter()
         self.cache_control_check = _PROXY_CacheControlCheck()
         self.alerting: list[str] | None = None
         self.alerting_threshold: float = 300  # default to 5 min. threshold
@@ -3580,7 +3578,7 @@ class ProxyLogging:
         caps: Final = ProxyLogging._callback_capabilities()
         post_call_pipelines: Final = _streamable_post_call_pipelines(request_data, user_api_key_dict)
         # Fast path: no real overrides. Internal proxy CustomLogger callbacks
-        # (e.g. _PROXY_MaxBudgetLimiter, ManagedFiles) inherit the default
+        # (e.g. _PROXY_CacheControlCheck, ManagedFiles) inherit the default
         # ``async for chunk: yield chunk`` body, so wrapping the iterator
         # through each of them adds N pass-through trampolines per chunk for
         # zero behavior change. Skip the chain entirely and stream through.
diff --git a/tests/e2e/quota_management/budgets/BUDGET_TEST_COVERAGE_MATRIX.md b/tests/e2e/quota_management/budgets/BUDGET_TEST_COVERAGE_MATRIX.md
index 7ff920a8d6d..a07bdf3d4e9 100644
--- a/tests/e2e/quota_management/budgets/BUDGET_TEST_COVERAGE_MATRIX.md
+++ b/tests/e2e/quota_management/budgets/BUDGET_TEST_COVERAGE_MATRIX.md
@@ -21,7 +21,7 @@ on the shared lifecycle (every entity it creates is deleted on teardown).
 
 | Entity | Unit | Pre-existing live | This suite (live) | Status |
 |--------|------|-------------------|-------------------|--------|
-| API key | `test_budget_reservation.py`, `test_max_budget_limiter.py` | `otel_tests` | `test_budget_enforcement_e2e::test_key_budget_blocks` | **covered** |
+| API key | `test_budget_reservation.py` | `otel_tests` | `test_budget_enforcement_e2e::test_key_budget_blocks` | **covered** |
 | Team | `test_team_budget_limits.py` | `otel_tests` | (org test builds a team) | **covered** |
 | Internal user | auth unit tests | - | `test_internal_user_budget_blocks` | **covered (new)** |
 | Team member | `test_team_member_budget.py` | - | `test_team_member_budget_blocks` | **covered (new)** |
diff --git a/tests/logging_callback_tests/test_unit_test_litellm_logging.py b/tests/logging_callback_tests/test_unit_test_litellm_logging.py
index 42ba4ff35f1..7709a823610 100644
--- a/tests/logging_callback_tests/test_unit_test_litellm_logging.py
+++ b/tests/logging_callback_tests/test_unit_test_litellm_logging.py
@@ -8,8 +8,8 @@ from typing import Literal
 import pytest
 import litellm
 from litellm.litellm_core_utils.litellm_logging import Logging
-from litellm.proxy.hooks.max_budget_limiter import _PROXY_MaxBudgetLimiter
 from litellm.proxy.hooks.cache_control_check import _PROXY_CacheControlCheck
+from litellm.proxy.hooks.max_iterations_limiter import _PROXY_MaxIterationsHandler
 from litellm._service_logger import ServiceLogging
 import asyncio
 
@@ -58,11 +58,11 @@ def test_is_internal_litellm_proxy_callback():
     """
     Ensure we can determine if a callback is an internal litellm proxy callback
 
-    eg. `_PROXY_MaxBudgetLimiter`, `_PROXY_CacheControlCheck`
+    eg. `_PROXY_MaxIterationsHandler`, `_PROXY_CacheControlCheck`
     """
     logging = setup_logging()
 
-    assert logging._is_internal_litellm_proxy_callback(_PROXY_MaxBudgetLimiter) == True
+    assert logging._is_internal_litellm_proxy_callback(_PROXY_MaxIterationsHandler) == True
 
     # Test non-internal callbacks
     def regular_callback():
@@ -95,7 +95,7 @@ def test_should_run_sync_callbacks_for_async_calls():
     assert logging._should_run_sync_callbacks_for_async_calls() == True
 
     # Test with internal callback only
-    litellm.success_callback = [_PROXY_MaxBudgetLimiter]
+    litellm.success_callback = [_PROXY_MaxIterationsHandler]
     assert logging._should_run_sync_callbacks_for_async_calls() == False
 
 
@@ -107,7 +107,7 @@ def test_remove_internal_litellm_callbacks():
 
     callbacks = [
         regular_callback,
-        _PROXY_MaxBudgetLimiter,
+        _PROXY_MaxIterationsHandler,
         _PROXY_CacheControlCheck,
         "string_callback",
     ]
@@ -116,5 +116,5 @@ def test_remove_internal_litellm_callbacks():
     assert len(filtered) == 2  # Should only keep regular_callback and string_callback
     assert regular_callback in filtered
     assert "string_callback" in filtered
-    assert _PROXY_MaxBudgetLimiter not in filtered
+    assert _PROXY_MaxIterationsHandler not in filtered
     assert _PROXY_CacheControlCheck not in filtered
diff --git a/tests/test_litellm/proxy/hooks/test_max_budget_limiter.py b/tests/test_litellm/proxy/hooks/test_max_budget_limiter.py
deleted file mode 100644
index 71671966d1a..00000000000
--- a/tests/test_litellm/proxy/hooks/test_max_budget_limiter.py
+++ /dev/null
@@ -1,237 +0,0 @@
-"""
-Unit tests for the personal-budget pre-call hook.
-
-The reservation path (added in PR #26845) atomically pre-fills the same
-`spend:user:{user_id}` counter this hook reads, admitting at a strict-`<`
-boundary. Re-checking with `>=` after reservation would reject requests the
-reservation already admitted when the reservation fills the counter to
-exactly `max_budget` (e.g. requests with no `max_tokens` cap fall back to
-reserving the smallest remaining headroom).
-
-These tests pin the skip-when-reserved behavior and guard against drift.
-"""
-
-from unittest.mock import AsyncMock, patch
-
-import pytest
-from fastapi import HTTPException
-
-from litellm.caching.caching import DualCache
-from litellm.proxy._types import UserAPIKeyAuth
-from litellm.proxy.hooks.max_budget_limiter import _PROXY_MaxBudgetLimiter
-
-
-def _make_user_api_key_auth(
-    user_id: str = "user-1",
-    user_max_budget: float = 10.0,
-    user_spend: float = 0.0,
-    team_id=None,
-    budget_reservation=None,
-) -> UserAPIKeyAuth:
-    return UserAPIKeyAuth(
-        api_key="sk-test",
-        user_id=user_id,
-        user_max_budget=user_max_budget,
-        user_spend=user_spend,
-        team_id=team_id,
-        budget_reservation=budget_reservation,
-    )
-
-
-@pytest.mark.asyncio
-async def test_under_budget_passes():
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = _make_user_api_key_auth(user_max_budget=10.0)
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=3.0),
-    ):
-        result = await handler.async_pre_call_hook(
-            user_api_key_dict=user_api_key_dict,
-            cache=DualCache(),
-            data={},
-            call_type="completion",
-        )
-
-    assert result is None
-
-
-@pytest.mark.asyncio
-async def test_over_budget_rejects_without_reservation():
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = _make_user_api_key_auth(user_max_budget=10.0)
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=10.0),
-    ):
-        with pytest.raises(HTTPException) as exc_info:
-            await handler.async_pre_call_hook(
-                user_api_key_dict=user_api_key_dict,
-                cache=DualCache(),
-                data={},
-                call_type="completion",
-            )
-
-    assert exc_info.value.status_code == 429
-    assert "Max budget limit reached." in exc_info.value.detail
-
-
-@pytest.mark.asyncio
-async def test_skips_when_user_counter_is_reserved():
-    """
-    Reservation atomically pre-fills `spend:user:{user_id}` and admits the
-    request. The legacy `>=` check must not double-enforce on the same
-    counter — that's what produced the boundary regression where a fresh
-    user with no `max_tokens` cap got 429'd on their first request.
-    """
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = _make_user_api_key_auth(
-        user_id="user-1",
-        user_max_budget=10.0,
-        budget_reservation={
-            "reserved_cost": 10.0,
-            "entries": [
-                {
-                    "counter_key": "spend:user:user-1",
-                    "entity_type": "User",
-                    "entity_id": "user-1",
-                    "reserved_cost": 10.0,
-                    "applied_adjustment": 0.0,
-                }
-            ],
-            "finalized": False,
-        },
-    )
-
-    # `get_current_spend` would return 10.0 here (counter pre-filled by the
-    # reservation). The hook must skip without reading it.
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=10.0),
-    ) as mock_get_spend:
-        result = await handler.async_pre_call_hook(
-            user_api_key_dict=user_api_key_dict,
-            cache=DualCache(),
-            data={},
-            call_type="completion",
-        )
-
-    assert result is None
-    mock_get_spend.assert_not_awaited()
-
-
-@pytest.mark.asyncio
-async def test_does_not_skip_when_reservation_covers_a_different_counter():
-    """
-    A reservation that only covers e.g. `spend:team:{team_id}` (not the user
-    counter) must not exempt the user-budget check.
-    """
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = _make_user_api_key_auth(
-        user_id="user-1",
-        user_max_budget=10.0,
-        budget_reservation={
-            "reserved_cost": 5.0,
-            "entries": [
-                {
-                    "counter_key": "spend:team:team-x",
-                    "entity_type": "Team",
-                    "entity_id": "team-x",
-                    "reserved_cost": 5.0,
-                    "applied_adjustment": 0.0,
-                }
-            ],
-            "finalized": False,
-        },
-    )
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=10.0),
-    ):
-        with pytest.raises(HTTPException) as exc_info:
-            await handler.async_pre_call_hook(
-                user_api_key_dict=user_api_key_dict,
-                cache=DualCache(),
-                data={},
-                call_type="completion",
-            )
-
-    assert exc_info.value.status_code == 429
-
-
-@pytest.mark.asyncio
-async def test_team_keys_skip_personal_budget():
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = _make_user_api_key_auth(
-        user_max_budget=10.0,
-        team_id="team-1",
-    )
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=999.0),
-    ) as mock_get_spend:
-        result = await handler.async_pre_call_hook(
-            user_api_key_dict=user_api_key_dict,
-            cache=DualCache(),
-            data={},
-            call_type="completion",
-        )
-
-    assert result is None
-    mock_get_spend.assert_not_awaited()
-
-
-@pytest.mark.asyncio
-async def test_team_keys_enforce_personal_budget_when_flag_enabled():
-    """This hook is the third personal-budget gate alongside common_checks and the
-    reservation path, so apply_user_budget_to_team_keys has to reach it too or an
-    opted-in deployment enforces in two places out of three."""
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = _make_user_api_key_auth(
-        user_max_budget=10.0,
-        team_id="team-1",
-    )
-
-    with patch.dict(
-        "litellm.proxy.proxy_server.general_settings",
-        {"apply_user_budget_to_team_keys": True},
-    ), patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=999.0),
-    ):
-        with pytest.raises(HTTPException) as exc_info:
-            await handler.async_pre_call_hook(
-                user_api_key_dict=user_api_key_dict,
-                cache=DualCache(),
-                data={},
-                call_type="completion",
-            )
-
-    assert exc_info.value.status_code == 429
-
-
-@pytest.mark.asyncio
-async def test_no_max_budget_passes():
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = UserAPIKeyAuth(
-        api_key="sk-test",
-        user_id="user-1",
-    )
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=999.0),
-    ) as mock_get_spend:
-        result = await handler.async_pre_call_hook(
-            user_api_key_dict=user_api_key_dict,
-            cache=DualCache(),
-            data={},
-            call_type="completion",
-        )
-
-    assert result is None
-    mock_get_spend.assert_not_awaited()
diff --git a/tests/test_litellm/proxy/hooks/test_proxy_rate_limit_provider_field.py b/tests/test_litellm/proxy/hooks/test_proxy_rate_limit_provider_field.py
index ec680317980..49bbd498cb9 100644
--- a/tests/test_litellm/proxy/hooks/test_proxy_rate_limit_provider_field.py
+++ b/tests/test_litellm/proxy/hooks/test_proxy_rate_limit_provider_field.py
@@ -6,7 +6,7 @@ Background
 ----------
 The proxy's internal rate-limit hooks (parallel_request_limiter,
 parallel_request_limiter_v3, dynamic_rate_limiter, dynamic_rate_limiter_v3,
-batch_rate_limiter, max_budget_limiter, max_iterations_limiter,
+batch_rate_limiter, max_iterations_limiter,
 max_budget_per_session_limiter) all fire from ``async_pre_call_hook`` —
 *before* :func:`litellm.get_llm_provider` runs anywhere else in the request
 lifecycle.
@@ -50,7 +50,6 @@ from litellm.proxy.hooks.dynamic_rate_limiter import _PROXY_DynamicRateLimitHand
 from litellm.proxy.hooks.dynamic_rate_limiter_v3 import (
     _PROXY_DynamicRateLimitHandlerV3,
 )
-from litellm.proxy.hooks.max_budget_limiter import _PROXY_MaxBudgetLimiter
 from litellm.proxy.hooks.max_budget_per_session_limiter import (
     _PROXY_MaxBudgetPerSessionHandler,
 )
@@ -830,64 +829,6 @@ async def test_batch_rate_limiter_unknown_model_falls_back():
     assert exc_info.value.llm_provider == PROXY_LLM_PROVIDER_FALLBACK
 
 
-# ---------------------------------------------------------------------------
-# max_budget_limiter
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_max_budget_limiter_populates_provider():
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = UserAPIKeyAuth(
-        api_key="sk-budget",
-        user_id="user-1",
-        user_max_budget=10.0,
-    )
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=10.0),
-    ):
-        with pytest.raises(HTTPException) as exc_info:
-            await handler.async_pre_call_hook(
-                user_api_key_dict=user_api_key_dict,
-                cache=DualCache(),
-                data={"model": "gpt-4o-mini"},
-                call_type="completion",
-            )
-
-    exc = exc_info.value
-    assert exc.status_code == 429
-    assert isinstance(exc, RateLimitError)
-    assert exc.llm_provider == "openai"
-    assert exc.model == "gpt-4o-mini"
-
-
-@pytest.mark.asyncio
-async def test_max_budget_limiter_no_model_falls_back():
-    handler = _PROXY_MaxBudgetLimiter()
-    user_api_key_dict = UserAPIKeyAuth(
-        api_key="sk-budget",
-        user_id="user-1",
-        user_max_budget=10.0,
-    )
-
-    with patch(
-        "litellm.proxy.proxy_server.get_current_spend",
-        new=AsyncMock(return_value=10.0),
-    ):
-        with pytest.raises(HTTPException) as exc_info:
-            await handler.async_pre_call_hook(
-                user_api_key_dict=user_api_key_dict,
-                cache=DualCache(),
-                data={},
-                call_type="completion",
-            )
-
-    assert exc_info.value.llm_provider == PROXY_LLM_PROVIDER_FALLBACK
-    assert exc_info.value.model == ""
-
-
 # ---------------------------------------------------------------------------
 # max_iterations_limiter
 # ---------------------------------------------------------------------------
diff --git a/tests/test_litellm/proxy/proxy_server/test_routes_config.py b/tests/test_litellm/proxy/proxy_server/test_routes_config.py
index 2d9c1bd8b46..dd3914e3ad5 100644
--- a/tests/test_litellm/proxy/proxy_server/test_routes_config.py
+++ b/tests/test_litellm/proxy/proxy_server/test_routes_config.py
@@ -1397,7 +1397,7 @@ def test_get_config_callbacks_excludes_internal_runtime_callbacks(client, auth_a
     from litellm.integrations.s3_v2 import S3Logger
     from litellm.integrations.sqs import SQSLogger
     from litellm.integrations.vector_store_integrations.vector_store_pre_call_hook import VectorStorePreCallHook
-    from litellm.proxy.hooks.max_budget_limiter import _PROXY_MaxBudgetLimiter
+    from litellm.proxy.hooks.cache_control_check import _PROXY_CacheControlCheck
     from litellm.router import Router
 
     class _InventoryTestGuardrail(CustomGuardrail):
@@ -1425,7 +1425,7 @@ def test_get_config_callbacks_excludes_internal_runtime_callbacks(client, auth_a
         litellm,
         "callbacks",
         [
-            _PROXY_MaxBudgetLimiter(),
+            _PROXY_CacheControlCheck(),
             _PROXY_LiteLLMManagedFiles(internal_usage_cache=MagicMock(), prisma_client=MagicMock()),
             ServiceLogging(),
             VectorStorePreCallHook(),
diff --git a/tests/test_litellm/proxy/test_proxy_logging_hook_detection.py b/tests/test_litellm/proxy/test_proxy_logging_hook_detection.py
index 28ff4571b44..a3ff7f7447e 100644
--- a/tests/test_litellm/proxy/test_proxy_logging_hook_detection.py
+++ b/tests/test_litellm/proxy/test_proxy_logging_hook_detection.py
@@ -73,7 +73,7 @@ async def test_post_call_response_headers_hook_returns_early_without_callbacks(
 
 def test_callback_capabilities_skips_default_custom_logger(monkeypatch):
     """
-    Internal proxy hooks (e.g. _PROXY_MaxBudgetLimiter, ManagedFiles) inherit
+    Internal proxy hooks (e.g. _PROXY_CacheControlCheck, ManagedFiles) inherit
     the default ``async_post_call_streaming_iterator_hook`` body.  The
     capability scanner must NOT report them as iterator overrides — wrapping
     the chunk stream through every no-op layer was responsible for ~10x
diff --git a/tests/test_litellm/proxy/utils/proxy_logging/test_lifecycle.py b/tests/test_litellm/proxy/utils/proxy_logging/test_lifecycle.py
index a97dcb41e44..40cb3f10d34 100644
--- a/tests/test_litellm/proxy/utils/proxy_logging/test_lifecycle.py
+++ b/tests/test_litellm/proxy/utils/proxy_logging/test_lifecycle.py
@@ -220,7 +220,7 @@ def test_add_proxy_hooks_registers_callbacks(proxy_logging, monkeypatch):
     what gets registered. Verifies that the resulting instances land in
     ``proxy_logging.proxy_hook_mapping`` keyed by hook name.
     """
-    hook_keys = ["cache_control_check", "max_budget_limiter"]
+    hook_keys = ["cache_control_check", "max_iterations_limiter"]
     registered: List[Any] = []
 
     from litellm.proxy import utils as utils_mod
@@ -362,22 +362,22 @@ def test_add_proxy_hooks_unknown_hook_raises(proxy_logging, monkeypatch):
 
 def test_get_proxy_hook_returns_registered_instance(proxy_logging):
     s_cache = MagicMock()
-    s_budget = MagicMock()
+    s_iterations = MagicMock()
     s_parallel = MagicMock()
     proxy_logging.proxy_hook_mapping = {
         "cache_control_check": s_cache,
-        "max_budget_limiter": s_budget,
+        "max_iterations_limiter": s_iterations,
         "max_parallel_request_limiter": s_parallel,
     }
     snapshot = {
         "cache_control_check": proxy_logging.get_proxy_hook("cache_control_check") is s_cache,
-        "max_budget_limiter": proxy_logging.get_proxy_hook("max_budget_limiter") is s_budget,
+        "max_iterations_limiter": proxy_logging.get_proxy_hook("max_iterations_limiter") is s_iterations,
         "max_parallel_request_limiter": proxy_logging.get_proxy_hook("max_parallel_request_limiter") is s_parallel,
         "unknown_returns_none": proxy_logging.get_proxy_hook("unknown") is None,
     }
     assert snapshot == {
         "cache_control_check": True,
-        "max_budget_limiter": True,
+        "max_iterations_limiter": True,
         "max_parallel_request_limiter": True,
         "unknown_returns_none": True,
     }
diff --git a/tests/test_litellm/proxy/utils/proxy_logging/test_pre_call_hook.py b/tests/test_litellm/proxy/utils/proxy_logging/test_pre_call_hook.py
index af89c424f8b..6e5cb7fcae3 100644
--- a/tests/test_litellm/proxy/utils/proxy_logging/test_pre_call_hook.py
+++ b/tests/test_litellm/proxy/utils/proxy_logging/test_pre_call_hook.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Any, Dict
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from fastapi import HTTPException
@@ -400,6 +400,37 @@ def test_has_pre_call_guardrails_counts_a_content_enforcer(proxy_logging, monkey
     assert proxy_logging.has_pre_call_guardrails({}) is True
 
 
+@pytest.mark.asyncio
+async def test_registered_hooks_do_not_enforce_user_budget(proxy_logging, monkeypatch):
+    """
+    Personal budget is auth's job (`_user_max_budget_check`), which exempts
+    zero-cost models. A hook re-checking the same counter without that
+    exemption is what 429'd free models once a user was over budget.
+    """
+    monkeypatch.setattr(litellm, "callbacks", [])
+    with patch("litellm.proxy.proxy_server.prisma_client", None):
+        proxy_logging._add_proxy_hooks(llm_router=None)
+    ProxyLogging._callback_capabilities_cache.clear()
+
+    over_budget_user = UserAPIKeyAuth(
+        api_key="sk-personal",
+        user_id="user-over-budget",
+        user_max_budget=1.0,
+        user_spend=5.0,
+        team_id=None,
+    )
+    data = {"model": "free-model", "messages": [{"role": "user", "content": "hi"}]}
+
+    with patch("litellm.proxy.proxy_server.get_current_spend", new=AsyncMock(return_value=5.0)):
+        out = await proxy_logging.pre_call_hook(
+            user_api_key_dict=over_budget_user,
+            data=data,
+            call_type="completion",
+        )
+
+    assert out == data
+
+
 def test_every_pre_call_customlogger_is_deliberately_classified():
     """
     A ledger, so a new hook cannot land unclassified.
@@ -415,7 +446,6 @@ def test_every_pre_call_customlogger_is_deliberately_classified():
         "_ENTERPRISE_BlockedUserList",
     }
     counts_or_shapes_the_request = {
-        "_PROXY_MaxBudgetLimiter",
         "_PROXY_MaxParallelRequestsHandler_v3",
         "_PROXY_MaxIterationsHandler",
         "_PROXY_MaxBudgetPerSessionHandler",
diff --git a/tests/test_litellm/test_rate_limit_error_unification.py b/tests/test_litellm/test_rate_limit_error_unification.py
index 99e9981857c..8241b29aff1 100644
--- a/tests/test_litellm/test_rate_limit_error_unification.py
+++ b/tests/test_litellm/test_rate_limit_error_unification.py
@@ -221,28 +221,6 @@ class TestProxyHookCategoryWiring:
     """End-to-end check that every proxy-side rate limiter raises the unified
     class with a sensible category, not a bare HTTPException."""
 
-    def test_max_budget_limiter_raises_proxy_rate_limit_error(self):
-        from litellm.proxy.hooks.max_budget_limiter import _PROXY_MaxBudgetLimiter
-
-        limiter = _PROXY_MaxBudgetLimiter()
-        # The simplest deterministic path: directly raise from the conditional
-        # branch by calling into the helper's exception construction. We
-        # round-trip through the public class to assert the shape.
-        with pytest.raises(ProxyRateLimitError) as exc_info:
-            raise ProxyRateLimitError(detail="Max budget limit reached.")
-        assert exc_info.value.status_code == 429
-        assert exc_info.value.category == RateLimitErrorCategory.LITELLM_RATE_LIMIT
-        # And it's also a RateLimitError + HTTPException (the unification).
-        assert isinstance(exc_info.value, RateLimitError)
-        assert isinstance(exc_info.value, HTTPException)
-        # Static check that the limiter's module imports the unified class so
-        # the source of truth is wired correctly.
-        from litellm.proxy.hooks import max_budget_limiter
-
-        assert hasattr(max_budget_limiter, "ProxyRateLimitError")
-        assert max_budget_limiter.ProxyRateLimitError is ProxyRateLimitError
-        del limiter  # silence unused-var
-
     @pytest.mark.parametrize(
         "module_path",
         [
@@ -251,7 +229,6 @@ class TestProxyHookCategoryWiring:
             "litellm.proxy.hooks.dynamic_rate_limiter",
             "litellm.proxy.hooks.dynamic_rate_limiter_v3",
             "litellm.proxy.hooks.batch_rate_limiter",
-            "litellm.proxy.hooks.max_budget_limiter",
             "litellm.proxy.hooks.max_budget_per_session_limiter",
             "litellm.proxy.hooks.max_iterations_limiter",
         ],
@@ -542,44 +519,6 @@ class TestProxyHooksActuallyRaiseProxyRateLimitError:
         assert isinstance(e, RateLimitError)
         assert isinstance(e, HTTPException)
 
-    @pytest.mark.asyncio
-    async def test_max_budget_limiter_raises_proxy_rate_limit_error(self):
-        """
-        Drive `_PROXY_MaxBudgetLimiter` past the user budget and assert it
-        raises the unified class. Mocks `get_current_spend` so we don't need
-        the proxy DB.
-        """
-        from unittest.mock import patch
-
-        from litellm.caching.caching import DualCache
-        from litellm.proxy._types import UserAPIKeyAuth
-        from litellm.proxy.hooks.max_budget_limiter import (
-            _PROXY_MaxBudgetLimiter,
-        )
-
-        handler = _PROXY_MaxBudgetLimiter()
-        user_api_key_dict = UserAPIKeyAuth(
-            api_key="sk-test-budget",
-            user_id="user-budget-1",
-            user_max_budget=1.0,
-            user_spend=2.0,
-        )
-        with patch(
-            "litellm.proxy.proxy_server.get_current_spend",
-            return_value=5.0,
-        ):
-            with pytest.raises(ProxyRateLimitError) as exc_info:
-                await handler.async_pre_call_hook(
-                    user_api_key_dict=user_api_key_dict,
-                    cache=DualCache(),
-                    data={},
-                    call_type="completion",
-                )
-        e = exc_info.value
-        assert e.status_code == 429
-        assert e.category == RateLimitErrorCategory.LITELLM_RATE_LIMIT
-        assert "max budget" in str(e.detail).lower()
-
     @pytest.mark.asyncio
     async def test_dynamic_rate_limiter_v1_raises_proxy_rate_limit_error(self):
         """
@@ -1156,14 +1095,6 @@ class TestProxyHooksWireTypeCorrectly:
     max-iterations) without grepping the error message.
     """
 
-    def test_max_budget_limiter_emits_budget_type(self):
-        e = ProxyRateLimitError(
-            detail="Max budget limit reached.",
-            rate_limit_type=RateLimitType.BUDGET,
-        )
-        assert e.category == "litellm_rate_limit"
-        assert e.rate_limit_type == "budget"
-
     def test_max_iterations_limiter_emits_max_iterations_type(self):
         e = ProxyRateLimitError(
             detail="Max iterations exceeded for session abc.",

From dae16264c1b2b0c39face0014aff8c1a0028e606 Mon Sep 17 00:00:00 2001
From: ryan <ryan@berri.ai>
Date: Wed, 16 Sep 2026 01:21:33 +0000
Subject: [PATCH 71/76] test(auth): cover over-budget user on zero-cost vs paid
 model in common_checks

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 .../proxy/auth/test_auth_checks.py            | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/tests/test_litellm/proxy/auth/test_auth_checks.py b/tests/test_litellm/proxy/auth/test_auth_checks.py
index 26ae28a57d2..6b8260e7f08 100644
--- a/tests/test_litellm/proxy/auth/test_auth_checks.py
+++ b/tests/test_litellm/proxy/auth/test_auth_checks.py
@@ -5605,6 +5605,65 @@ async def test_common_checks_personal_user_budget_blocks_in_gather():
     assert "User=u1" in str(over.value)
 
 
+async def _common_checks_for_over_budget_personal_key(*, model: str) -> bool:
+    from litellm import Router
+    from litellm.proxy.auth.auth_checks import _is_model_cost_zero, common_checks
+
+    llm_router: Final = Router(
+        model_list=[
+            {
+                "model_name": "free-model",
+                "litellm_params": {"model": "openai/gpt-4o-mini", "api_key": "sk-test"},
+                "model_info": {"input_cost_per_token": 0.0, "output_cost_per_token": 0.0},
+            },
+            {
+                "model_name": "paid-model",
+                "litellm_params": {"model": "openai/gpt-4o-mini", "api_key": "sk-test"},
+            },
+        ]
+    )
+    user: Final = LiteLLM_UserTable(user_id="u1", spend=0.0, max_budget=1.0)
+    token: Final = UserAPIKeyAuth(token="k1", user_id="u1")
+
+    async def _spend_by_counter(counter_key, fallback_spend, max_budget=None, **kwargs):
+        return 5.0 if counter_key == "spend:user:u1" else 0.0
+
+    proxy_logging_obj: Final = MagicMock()
+    proxy_logging_obj.budget_alerts = AsyncMock()
+
+    with (
+        patch("litellm.proxy.proxy_server.prisma_client", None),
+        patch("litellm.proxy.proxy_server.get_current_spend", _spend_by_counter),
+    ):
+        result: Final = await common_checks(
+            request_body={"model": model, "messages": [{"role": "user", "content": "hi"}]},
+            team_object=None,
+            user_object=user,
+            end_user_object=None,
+            global_proxy_spend=None,
+            general_settings={},
+            route="/chat/completions",
+            llm_router=llm_router,
+            proxy_logging_obj=proxy_logging_obj,
+            valid_token=token,
+            request=MagicMock(spec=Request),
+            skip_budget_checks=_is_model_cost_zero(model=model, llm_router=llm_router),
+        )
+        await asyncio.sleep(0)
+    return result
+
+
+@pytest.mark.asyncio
+async def test_common_checks_over_budget_user_can_still_call_zero_cost_model():
+    """LIT-7464: an exhausted personal budget must not block a model priced at 0/0,
+    while the same user is still rejected on a priced model."""
+    assert await _common_checks_for_over_budget_personal_key(model="free-model") is True
+
+    with pytest.raises(litellm.BudgetExceededError) as over:
+        await _common_checks_for_over_budget_personal_key(model="paid-model")
+    assert "ExceededBudget: User=u1" in str(over.value)
+
+
 async def _run_internal_user_budget_alert(
     *,
     spend: float,

From eda81fff595f992bfae6471ef474eec896992fdc Mon Sep 17 00:00:00 2001
From: ryan-crabbe-berri <ryan@berri.ai>
Date: Tue, 15 Sep 2026 16:46:52 -0700
Subject: [PATCH 72/76] feat(ui): shared URL-state layer for tables and tabs

Add useUrlTableState (search, sort, page, page size and filter_<column>
in the query string via one nuqs useQueryStates call, with keyPrefix and
urlKeys for routes that host two tables or need legacy key names) and
useUrlTab (validated ?tab= param with a role-aware fallback). Migrate
the Virtual Keys table onto useUrlTableState with a byte-identical URL
contract and bind the Playground tab strip to ?tab=.

DataTable gains controlled columnVisibility/onColumnVisibilityChange
plus usePersistedColumnVisibility (localStorage per table id), and an
isError prop that keeps the server page clamp from rewriting a
deep-linked ?page= after a failed fetch. Virtual Keys uses both.

The expired-session redirect in handleError now keeps the query string
and hash so the return URL captured on re-login restores the filtered
view instead of the bare list.

Delete useTabRouting and tabRoutes, the pathname tab router left over
from the reverted path-per-tab attempt (#34327, reverted in #34629);
tab persistence has to be a query param on the static export.
---
 .../(dashboard)/hooks/useTabRouting.test.tsx  |  82 -----
 .../app/(dashboard)/hooks/useTabRouting.ts    |  38 --
 .../app/(dashboard)/playground/page.test.tsx  |  53 ++-
 .../src/app/(dashboard)/playground/page.tsx   |  10 +-
 .../VirtualKeysPage/VirtualKeysTable.test.tsx | 152 +++++++-
 .../VirtualKeysPage/VirtualKeysTable.tsx      | 185 ++++------
 .../src/components/networking.test.ts         |  38 +-
 .../src/components/networking.tsx             |   2 +-
 .../shared/DataTable/DataTable.test-d.tsx     |  27 +-
 .../shared/DataTable/DataTable.test.tsx       |  98 +++++-
 .../components/shared/DataTable/DataTable.tsx |  15 +-
 .../src/components/shared/DataTable/index.ts  |   2 +
 .../src/components/shared/DataTable/types.ts  |  19 +
 .../usePersistedColumnVisibility.test.tsx     |  98 ++++++
 .../DataTable/usePersistedColumnVisibility.ts |  54 +++
 .../DataTable/useUrlTableState.test.tsx       | 325 ++++++++++++++++++
 .../shared/DataTable/useUrlTableState.ts      | 232 +++++++++++++
 .../src/hooks/useUrlTab.test.tsx              | 100 ++++++
 ui/litellm-dashboard/src/hooks/useUrlTab.ts   |  12 +
 .../src/utils/tabRoutes.test.ts               |  47 ---
 ui/litellm-dashboard/src/utils/tabRoutes.ts   |  26 --
 21 files changed, 1260 insertions(+), 355 deletions(-)
 delete mode 100644 ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.test.tsx
 delete mode 100644 ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.ts
 create mode 100644 ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
 create mode 100644 ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
 create mode 100644 ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.test.tsx
 create mode 100644 ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.ts
 create mode 100644 ui/litellm-dashboard/src/hooks/useUrlTab.test.tsx
 create mode 100644 ui/litellm-dashboard/src/hooks/useUrlTab.ts
 delete mode 100644 ui/litellm-dashboard/src/utils/tabRoutes.test.ts
 delete mode 100644 ui/litellm-dashboard/src/utils/tabRoutes.ts

diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.test.tsx
deleted file mode 100644
index 24900bae798..00000000000
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.test.tsx
+++ /dev/null
@@ -1,82 +0,0 @@
-/* @vitest-environment jsdom */
-import { renderHook } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const { mockPush, navState } = vi.hoisted(() => ({
-  mockPush: vi.fn(),
-  navState: { pathname: "/logs" },
-}));
-vi.mock("next/navigation", () => ({
-  usePathname: () => navState.pathname,
-  useRouter: () => ({ push: mockPush }),
-}));
-
-vi.mock("@/components/networking", () => ({ serverRootPath: "" }));
-
-import { createTabRoutes } from "@/utils/tabRoutes";
-import { useTabRouting } from "./useTabRouting";
-
-const routes = createTabRoutes("logs", ["audit", "deleted-keys", "deleted-teams"] as const);
-
-const render = (ready = true) => {
-  const config = {
-    routes,
-    baseTabKey: "request-logs",
-    visibleKeys: ["audit", "deleted-keys", "deleted-teams"],
-    ready,
-  };
-  return renderHook(() => useTabRouting(config));
-};
-
-describe("useTabRouting", () => {
-  beforeEach(() => {
-    navState.pathname = "/logs";
-    mockPush.mockClear();
-  });
-
-  it("maps the base path to the base tab key", () => {
-    const { result } = render();
-    expect(result.current.activeSlug).toBe("");
-    expect(result.current.activeKey).toBe("request-logs");
-  });
-
-  it("uses the slug itself as the active key for a known nested tab", () => {
-    navState.pathname = "/ui/logs/audit";
-    const { result } = render();
-    expect(result.current.activeKey).toBe("audit");
-  });
-
-  it("falls back to the base tab key for an unknown slug", () => {
-    navState.pathname = "/ui/logs/bogus";
-    const { result } = render();
-    expect(result.current.activeKey).toBe("request-logs");
-  });
-
-  it("redirects an unknown slug to the base href once ready", () => {
-    const replaceMock = vi.fn();
-    const originalLocation = window.location;
-    Object.defineProperty(window, "location", { configurable: true, value: { replace: replaceMock } });
-    navState.pathname = "/ui/logs/bogus";
-    render(true);
-    expect(replaceMock).toHaveBeenCalledWith("/ui/logs/");
-    Object.defineProperty(window, "location", { configurable: true, value: originalLocation });
-  });
-
-  it("does not redirect while not ready (role/creds still loading)", () => {
-    const replaceMock = vi.fn();
-    const originalLocation = window.location;
-    Object.defineProperty(window, "location", { configurable: true, value: { replace: replaceMock } });
-    navState.pathname = "/ui/logs/bogus";
-    render(false);
-    expect(replaceMock).not.toHaveBeenCalled();
-    Object.defineProperty(window, "location", { configurable: true, value: originalLocation });
-  });
-
-  it("pushes the tab href on change, mapping the base key back to the empty slug", () => {
-    const { result } = render();
-    result.current.onTabChange("audit");
-    expect(mockPush).toHaveBeenCalledWith("/ui/logs/audit/");
-    result.current.onTabChange("request-logs");
-    expect(mockPush).toHaveBeenCalledWith("/ui/logs/");
-  });
-});
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.ts
deleted file mode 100644
index c17d71b4855..00000000000
--- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useTabRouting.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { useEffect } from "react";
-import { usePathname, useRouter } from "next/navigation";
-import type { TabRoutes } from "@/utils/tabRoutes";
-
-interface UseTabRoutingArgs {
-  routes: Pick<TabRoutes<string>, "tabHref" | "slugFromPathname">;
-  baseTabKey: string;
-  visibleKeys: readonly string[];
-  ready?: boolean;
-}
-
-interface TabRoutingState {
-  activeSlug: string;
-  activeKey: string;
-  onTabChange: (key: string) => void;
-}
-
-export function useTabRouting({ routes, baseTabKey, visibleKeys, ready = true }: UseTabRoutingArgs): TabRoutingState {
-  const { tabHref, slugFromPathname } = routes;
-  const pathname = usePathname();
-  const router = useRouter();
-
-  const activeSlug = slugFromPathname(pathname);
-  const isKnownSlug = activeSlug === "" || visibleKeys.includes(activeSlug);
-  const activeKey = isKnownSlug ? activeSlug || baseTabKey : baseTabKey;
-
-  useEffect(() => {
-    if (ready && activeSlug !== "" && !isKnownSlug) {
-      window.location.replace(tabHref(""));
-    }
-  }, [ready, activeSlug, isKnownSlug, tabHref]);
-
-  const onTabChange = (key: string) => {
-    router.push(tabHref(key === baseTabKey ? "" : key));
-  };
-
-  return { activeSlug, activeKey, onTabChange };
-}
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/playground/page.test.tsx b/ui/litellm-dashboard/src/app/(dashboard)/playground/page.test.tsx
index 85e19d7d251..f12ebc0b831 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/playground/page.test.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/playground/page.test.tsx
@@ -1,5 +1,8 @@
-import { render, screen } from "@testing-library/react";
+import { screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { OnUrlUpdateFunction } from "nuqs/adapters/testing";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "../../../../tests/test-utils";
 import PlaygroundPage from "./page";
 
 const authState = { userRole: "Admin" };
@@ -35,14 +38,17 @@ vi.mock("@/app/(dashboard)/playground/components/chat_ui/AgentBuilderView", () =
   default: () => <div data-testid="agent-builder" />,
 }));
 
-describe("PlaygroundPage role guard", () => {
-  beforeEach(() => {
-    authState.userRole = "Admin";
-  });
+const lastUrlUpdate = (onUrlUpdate: ReturnType<typeof vi.fn<OnUrlUpdateFunction>>) =>
+  onUrlUpdate.mock.calls.at(-1)?.[0];
 
+beforeEach(() => {
+  authState.userRole = "Admin";
+});
+
+describe("PlaygroundPage role guard", () => {
   it.each(["Internal Viewer", "Admin Viewer"])("blocks the entire playground for %s", (role) => {
     authState.userRole = role;
-    render(<PlaygroundPage />);
+    renderWithProviders(<PlaygroundPage />);
 
     expect(screen.getByText("Access Denied")).toBeInTheDocument();
     expect(screen.queryByRole("tab")).not.toBeInTheDocument();
@@ -54,10 +60,43 @@ describe("PlaygroundPage role guard", () => {
 
   it.each(["Admin", "Internal User", "Org Admin"])("renders the playground for %s", (role) => {
     authState.userRole = role;
-    render(<PlaygroundPage />);
+    renderWithProviders(<PlaygroundPage />);
 
     expect(screen.queryByText("Access Denied")).not.toBeInTheDocument();
     expect(screen.getByRole("tab", { name: "Chat" })).toBeInTheDocument();
     expect(screen.getByTestId("chat-ui")).toBeInTheDocument();
   });
 });
+
+describe("PlaygroundPage ?tab= deep link", () => {
+  it("opens on Chat when the URL has no tab", () => {
+    renderWithProviders(<PlaygroundPage />);
+
+    expect(screen.getByRole("tab", { name: "Chat" })).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("activates the tab named in ?tab=", () => {
+    renderWithProviders(<PlaygroundPage />, { searchParams: { tab: "compare" } });
+
+    expect(screen.getByRole("tab", { name: "Compare" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("tab", { name: "Chat" })).toHaveAttribute("aria-selected", "false");
+  });
+
+  it("falls back to Chat when ?tab= is not a playground tab", () => {
+    renderWithProviders(<PlaygroundPage />, { searchParams: { tab: "settings" } });
+
+    expect(screen.getByRole("tab", { name: "Chat" })).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("clicking a tab writes ?tab= with history replace", async () => {
+    const user = userEvent.setup();
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    renderWithProviders(<PlaygroundPage />, { onUrlUpdate });
+
+    await user.click(screen.getByRole("tab", { name: "Compliance" }));
+
+    expect(await screen.findByRole("tab", { name: "Compliance", selected: true })).toBeInTheDocument();
+    await waitFor(() => expect(lastUrlUpdate(onUrlUpdate)?.searchParams.get("tab")).toBe("compliance"));
+    expect(lastUrlUpdate(onUrlUpdate)?.options.history).toBe("replace");
+  });
+});
diff --git a/ui/litellm-dashboard/src/app/(dashboard)/playground/page.tsx b/ui/litellm-dashboard/src/app/(dashboard)/playground/page.tsx
index 78ca538d8b5..27a61415672 100644
--- a/ui/litellm-dashboard/src/app/(dashboard)/playground/page.tsx
+++ b/ui/litellm-dashboard/src/app/(dashboard)/playground/page.tsx
@@ -9,6 +9,9 @@ import { DeprecationBanner } from "@/components/DeprecationBanner";
 import useAuthorized from "@/app/(dashboard)/hooks/useAuthorized";
 import { fetchProxySettings } from "@/utils/proxyUtils";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { useUrlTab } from "@/hooks/useUrlTab";
+
+const PLAYGROUND_TABS = ["chat", "compare", "compliance", "agent-builder"] as const;
 
 interface ProxySettings {
   PROXY_BASE_URL?: string;
@@ -18,6 +21,7 @@ interface ProxySettings {
 export default function PlaygroundPage() {
   const { accessToken, userRole, userId, disabledPersonalKeyCreation, token, isViewOnly } = useAuthorized();
   const [proxySettings, setProxySettings] = useState<ProxySettings | undefined>(undefined);
+  const [activeTab, setActiveTab] = useUrlTab(PLAYGROUND_TABS, "chat");
 
   useEffect(() => {
     const initializeProxySettings = async () => {
@@ -48,7 +52,11 @@ export default function PlaygroundPage() {
 
   return (
     <div className="flex h-full min-h-0 w-full min-w-0 flex-col overflow-hidden">
-      <Tabs defaultValue="chat" className="flex min-h-0 min-w-0 flex-1 flex-col gap-0 overflow-hidden">
+      <Tabs
+        value={activeTab}
+        onValueChange={setActiveTab}
+        className="flex min-h-0 min-w-0 flex-1 flex-col gap-0 overflow-hidden"
+      >
         <TabsList variant="line" className="w-full shrink-0 justify-start overflow-x-auto pb-1">
           <TabsTrigger value="chat" className="flex-none">
             Chat
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
index 6c742309eb7..4d963a2f603 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.test.tsx
@@ -4,7 +4,7 @@ import type { OnUrlUpdateFunction } from "nuqs/adapters/testing";
 import { vi, it, expect, beforeEach, describe, Mock, MockedFunction } from "vitest";
 import { chooseSelectOption, renderWithProviders } from "../../../tests/test-utils";
 import { VirtualKeysTable } from "./VirtualKeysTable";
-import { KEY_TABLE_SORT_FIELDS } from "./keyTableColumns";
+import { KEY_TABLE_HIDDEN_COLUMNS, KEY_TABLE_SORT_FIELDS } from "./keyTableColumns";
 import { KeyResponse, Team } from "../key_team_helpers/key_list";
 import { useKeyInfo } from "@/app/(dashboard)/hooks/keys/useKeyInfo";
 import { KeysResponse, useKeys } from "@/app/(dashboard)/hooks/keys/useKeys";
@@ -187,6 +187,7 @@ const lastHistoryMode = (onUrlUpdate: Mock<OnUrlUpdateFunction>) => onUrlUpdate.
 
 beforeEach(() => {
   vi.clearAllMocks();
+  localStorage.clear();
 
   mockUseKeys.mockReturnValue(keysResult([mockKey]));
   mockUseKeyInfo.mockReturnValue(keyInfoResult(undefined));
@@ -823,16 +824,27 @@ describe("table state lives in the URL so it survives leaving and returning to t
   });
 
   it("restores the drawer filters from the URL on mount", async () => {
-    renderWithProviders(<VirtualKeysTable />, { searchParams: { filter_team: "team-1", filter_user: "user-42" } });
+    const searchParams = {
+      filter_team: "team-1",
+      filter_org: "org-1",
+      filter_user: "user-42",
+      filter_key_id: mockKey.token,
+    };
+    const expectedKeyListOptions = {
+      teamID: "team-1",
+      organizationID: "org-1",
+      userID: "user-42",
+      keyHash: mockKey.token,
+    };
+    renderWithProviders(<VirtualKeysTable />, { searchParams });
 
     await waitFor(() => {
-      expect(mockUseKeys).toHaveBeenLastCalledWith(
-        1,
-        50,
-        expect.objectContaining({ teamID: "team-1", userID: "user-42" }),
-      );
+      expect(mockUseKeys).toHaveBeenLastCalledWith(1, 50, expect.objectContaining(expectedKeyListOptions));
     });
     expect(screen.getByTestId("filter-chip-team_id")).toHaveTextContent("Test Team");
+    expect(screen.getByTestId("filter-chip-org_id")).toHaveTextContent("Test Organization");
+    expect(screen.getByTestId("filter-chip-user_id")).toHaveTextContent("user-42");
+    expect(screen.getByTestId("filter-chip-key_hash")).toHaveTextContent(mockKey.token);
   });
 
   it("restores the status filter from the URL and sends it to /key/list", async () => {
@@ -853,6 +865,21 @@ describe("table state lives in the URL so it survives leaving and returning to t
     expect(screen.queryByTestId("filter-chip-status")).not.toBeInTheDocument();
   });
 
+  it("drops a hand-edited status from the URL when another filter chip is removed", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    renderWithProviders(<VirtualKeysTable />, {
+      searchParams: { filter_status: "bogus", filter_user: "user-42" },
+      onUrlUpdate,
+    });
+
+    fireEvent.click(await screen.findByTestId("filter-chip-remove-user_id"));
+
+    await waitFor(() => {
+      expect(lastSearchParam(onUrlUpdate, "filter_user")).toBeNull();
+    });
+    expect(lastSearchParam(onUrlUpdate, "filter_status")).toBeNull();
+  });
+
   it("writes the search term to the URL", async () => {
     const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
     renderWithProviders(<VirtualKeysTable />, { onUrlUpdate });
@@ -896,6 +923,40 @@ describe("table state lives in the URL so it survives leaving and returning to t
     expect(screen.queryByTestId("filter-chip-user_id")).not.toBeInTheDocument();
   });
 
+  it("writes the Organization and Key ID drawer filters to the URL and clears them again", async () => {
+    const user = userEvent.setup();
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    renderWithProviders(<VirtualKeysTable />, { onUrlUpdate });
+
+    openFilters();
+    await chooseSelectOption(user, await screen.findByPlaceholderText(/Select an organization/), /Test Organization/);
+    fireEvent.change(screen.getByPlaceholderText(/Enter Key ID/), { target: { value: mockKey.token } });
+    fireEvent.click(screen.getByTestId("filter-drawer-apply"));
+
+    await waitFor(() => {
+      expect(lastSearchParam(onUrlUpdate, "filter_org")).toBe("org-1");
+    });
+    expect(lastSearchParam(onUrlUpdate, "filter_key_id")).toBe(mockKey.token);
+    expect(lastSearchParam(onUrlUpdate, "filter_org_id")).toBeNull();
+    expect(lastSearchParam(onUrlUpdate, "filter_key_hash")).toBeNull();
+    await waitFor(() => {
+      expect(mockUseKeys).toHaveBeenLastCalledWith(
+        1,
+        50,
+        expect.objectContaining({ organizationID: "org-1", keyHash: mockKey.token }),
+      );
+    });
+
+    fireEvent.click(screen.getByTestId("datatable-clear-filters"));
+
+    await waitFor(() => {
+      expect(lastSearchParam(onUrlUpdate, "filter_org")).toBeNull();
+    });
+    expect(lastSearchParam(onUrlUpdate, "filter_key_id")).toBeNull();
+    expect(screen.queryByTestId("filter-chip-org_id")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("filter-chip-key_hash")).not.toBeInTheDocument();
+  });
+
   it("returns to page 1 when the search term changes", async () => {
     const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
     renderWithProviders(<VirtualKeysTable />, { searchParams: { page: "3" }, onUrlUpdate });
@@ -953,14 +1014,16 @@ describe("table state lives in the URL so it survives leaving and returning to t
     });
   });
 
-  it("falls back to the default sort when the URL names a column the table cannot sort by", async () => {
-    renderWithProviders(<VirtualKeysTable />, { searchParams: { sort_by: "totally_unknown_field" } });
+  it("falls back to the default sort column, keeping the URL's direction, when the table cannot sort by sort_by", async () => {
+    renderWithProviders(<VirtualKeysTable />, {
+      searchParams: { sort_by: "totally_unknown_field", sort_order: "asc" },
+    });
 
     await waitFor(() => {
       expect(mockUseKeys).toHaveBeenLastCalledWith(
         1,
         50,
-        expect.objectContaining({ sortBy: "created_at", sortOrder: "desc" }),
+        expect.objectContaining({ sortBy: "created_at", sortOrder: "asc" }),
       );
     });
     expect(screen.getByText("Test Key Alias")).toBeInTheDocument();
@@ -1003,3 +1066,72 @@ describe("table state lives in the URL so it survives leaving and returning to t
     });
   });
 });
+
+describe("column choices survive a reload", () => {
+  const STORAGE_KEY = "litellm_table_columns_virtual-keys";
+  const storedColumns = () => JSON.parse(localStorage.getItem(STORAGE_KEY) ?? "null");
+
+  it("hides a column that was hidden on a previous visit while the default-hidden columns stay hidden", () => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ budget_reset_at: false }));
+
+    renderWithProviders(<VirtualKeysTable />);
+
+    expect(screen.getByText("Test Key Alias")).toBeInTheDocument();
+    expect(screen.queryByText("Budget Reset")).not.toBeInTheDocument();
+    expect(screen.queryByText("Created By")).not.toBeInTheDocument();
+  });
+
+  it("writes a column toggled on through the Columns menu to storage and shows it again on the next mount", async () => {
+    const user = userEvent.setup();
+    const { unmount } = renderWithProviders(<VirtualKeysTable />);
+    expect(screen.queryByText("Created By")).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Columns" }));
+    await user.click(await screen.findByText("Created By"));
+    await user.keyboard("{Escape}");
+
+    expect(storedColumns()).toEqual({ ...KEY_TABLE_HIDDEN_COLUMNS, created_by: true });
+
+    unmount();
+    renderWithProviders(<VirtualKeysTable />);
+
+    expect(screen.getByText("Created By")).toBeInTheDocument();
+  });
+});
+
+describe("a failed keys fetch does not rewrite the URL", () => {
+  const renderOnPage3OfMany = async () => {
+    mockUseKeys.mockReturnValue(keysResult([mockKey], { total_count: 200, total_pages: 4 }));
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    const view = renderWithProviders(<VirtualKeysTable />, { searchParams: { page: "3" }, onUrlUpdate });
+    await waitFor(() => {
+      expect(mockUseKeys).toHaveBeenLastCalledWith(3, 50, expect.anything());
+    });
+    return { ...view, onUrlUpdate };
+  };
+
+  it("keeps ?page=3 when the keys query errors, instead of snapping to page 1 on the empty count", async () => {
+    const { rerender, onUrlUpdate } = await renderOnPage3OfMany();
+
+    mockUseKeys.mockReturnValue(keysResult([], {}, { data: undefined, isError: true }));
+    rerender(<VirtualKeysTable />);
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(mockUseKeys).toHaveBeenLastCalledWith(3, 50, expect.anything());
+    expect(onUrlUpdate).not.toHaveBeenCalled();
+  });
+
+  it("still snaps ?page=3 back to the first page when the keys query succeeds with no rows", async () => {
+    const { rerender, onUrlUpdate } = await renderOnPage3OfMany();
+
+    mockUseKeys.mockReturnValue(keysResult([]));
+    rerender(<VirtualKeysTable />);
+
+    await waitFor(() => {
+      expect(mockUseKeys).toHaveBeenLastCalledWith(1, 50, expect.anything());
+    });
+    await waitFor(() => {
+      expect(lastSearchParam(onUrlUpdate, "page")).toBeNull();
+    });
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx
index 1f52bdd7335..39dd2cc5ab2 100644
--- a/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx
+++ b/ui/litellm-dashboard/src/components/VirtualKeysPage/VirtualKeysTable.tsx
@@ -10,15 +10,18 @@ import {
   DataTableFilterDrawer,
   DataTableFilterField,
   DataTableToolbar,
+  usePersistedColumnVisibility,
+  useUrlTableState,
+  type UrlTableStateOptions,
 } from "@/components/shared/DataTable";
 import { SearchSelect } from "@/components/shared/SearchSelect";
 import { PageHeader } from "@/components/shared/PageHeader";
 import { Input } from "@/components/ui/input";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { useDebouncedValue } from "@tanstack/react-pacer/debouncer";
-import { ColumnFiltersState, functionalUpdate, OnChangeFn, PaginationState, SortingState } from "@tanstack/react-table";
+import { ColumnFiltersState, functionalUpdate, OnChangeFn } from "@tanstack/react-table";
 import { KeyRound } from "lucide-react";
-import { createParser, parseAsInteger, parseAsString, parseAsStringLiteral, useQueryState, useQueryStates } from "nuqs";
+import { parseAsString, useQueryState } from "nuqs";
 import React, { useCallback, useMemo, useState } from "react";
 
 import { KeyResponse, Team } from "../key_team_helpers/key_list";
@@ -56,44 +59,30 @@ const STATUS_FILTER_ITEMS = [
   ...KEY_STATUS_VALUES.map((value) => ({ value, label: KEY_STATUS_LABELS[value] })),
 ];
 
-const isKeyStatusFilter = (value: string): value is KeyStatusFilter =>
-  (KEY_STATUS_VALUES as readonly string[]).includes(value);
+const isKeyStatusFilter = (value: unknown): value is KeyStatusFilter =>
+  (KEY_STATUS_VALUES as readonly unknown[]).includes(value);
 
-const DEFAULT_SORT_BY = "created_at";
-const DEFAULT_SORT_ORDER = "desc";
-const DEFAULT_PAGE_SIZE = 50;
-const MAX_PAGE_SIZE = 100;
-const MAX_PAGE = 100_000;
+const isUsableFilter = (filter: ColumnFiltersState[number]): boolean =>
+  filter.id !== "status" || isKeyStatusFilter(filter.value);
 
-const boundedInteger = (min: number, max: number, fallback: number) =>
-  createParser({
-    parse: (value: string) => {
-      const parsed = parseAsInteger.parse(value);
-      return parsed === null ? null : Math.min(Math.max(parsed, min), max);
-    },
-    serialize: String,
-  }).withDefault(fallback);
-
-// The filters carry a prefix because /api-keys also takes team_id, key_alias and key_type
-// as create-key prefills; an unprefixed filter would hijack those deep links.
-const TABLE_STATE = {
-  key_search: parseAsString.withDefault(""),
-  sort_by: parseAsString.withDefault(DEFAULT_SORT_BY),
-  sort_order: parseAsStringLiteral(["asc", "desc"] as const).withDefault(DEFAULT_SORT_ORDER),
-  page: boundedInteger(1, MAX_PAGE, 1),
-  page_size: boundedInteger(1, MAX_PAGE_SIZE, DEFAULT_PAGE_SIZE),
-  filter_team: parseAsString.withDefault(""),
-  filter_org: parseAsString.withDefault(""),
-  filter_user: parseAsString.withDefault(""),
-  filter_key_id: parseAsString.withDefault(""),
-  filter_status: parseAsString.withDefault(""),
+const TABLE_STATE_OPTIONS: UrlTableStateOptions<FilterColumn> = {
+  sortFields: KEY_TABLE_SORT_FIELDS,
+  defaultSort: { id: "created_at", desc: true },
+  defaultPageSize: 50,
+  maxPageSize: 100,
+  filterColumns: FILTER_COLUMNS,
+  urlKeys: {
+    search: "key_search",
+    filter_team_id: "filter_team",
+    filter_org_id: "filter_org",
+    filter_user_id: "filter_user",
+    filter_key_hash: "filter_key_id",
+  },
 };
 
-const toSortOrder = (active: SortingState[number]): "asc" | "desc" => (active.desc ? "desc" : "asc");
-
-const filterValue = (filters: ColumnFiltersState, column: FilterColumn): string | null => {
+const appliedFilter = (filters: ColumnFiltersState, column: FilterColumn): string | undefined => {
   const value = filters.find((filter) => filter.id === column)?.value;
-  return (typeof value === "string" ? value.trim() : "") || null;
+  return typeof value === "string" ? value : undefined;
 };
 
 export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
@@ -103,50 +92,38 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
   const allTeams = useMemo<Team[]>(() => fetchedTeams ?? [], [fetchedTeams]);
 
   const [selectedKeyId, setSelectedKeyId] = useQueryState("key", parseAsString.withOptions({ history: "push" }));
-  const [tableState, setTableState] = useQueryStates(TABLE_STATE);
+  const {
+    search: searchInput,
+    setSearch,
+    sorting,
+    onSortingChange,
+    pagination,
+    onPaginationChange,
+    columnFilters: urlColumnFilters,
+    onColumnFiltersChange: setUrlColumnFilters,
+  } = useUrlTableState(TABLE_STATE_OPTIONS);
+  const columnFilters = useMemo(() => urlColumnFilters.filter(isUsableFilter), [urlColumnFilters]);
+  const onColumnFiltersChange = useCallback<OnChangeFn<ColumnFiltersState>>(
+    (updaterOrValue) => setUrlColumnFilters(functionalUpdate(updaterOrValue, columnFilters)),
+    [columnFilters, setUrlColumnFilters],
+  );
+  const { columnVisibility, onColumnVisibilityChange } = usePersistedColumnVisibility(
+    "virtual-keys",
+    KEY_TABLE_HIDDEN_COLUMNS,
+  );
   const [filtersOpen, setFiltersOpen] = useState(false);
-  const searchInput = tableState.key_search;
   const [searchQuery] = useDebouncedValue(searchInput, { wait: DEBOUNCE_WAIT_MS });
 
-  // A hand-edited sort_by the table cannot sort by would 400 at /key/list and leave the page loading.
-  const sortBy = KEY_TABLE_SORT_FIELDS.includes(tableState.sort_by) ? tableState.sort_by : DEFAULT_SORT_BY;
-  const sorting = useMemo<SortingState>(
-    () => [{ id: sortBy, desc: tableState.sort_order === "desc" }],
-    [sortBy, tableState.sort_order],
-  );
-  const tablePagination = useMemo<PaginationState>(
-    () => ({ pageIndex: tableState.page - 1, pageSize: tableState.page_size }),
-    [tableState.page, tableState.page_size],
-  );
-  const { filter_team, filter_org, filter_user, filter_key_id, filter_status } = tableState;
-  const appliedFilters = useMemo(
-    () => ({
-      team_id: filter_team.trim(),
-      org_id: filter_org.trim(),
-      user_id: filter_user.trim(),
-      key_hash: filter_key_id.trim(),
-      status: isKeyStatusFilter(filter_status) ? filter_status : "",
-    }),
-    [filter_team, filter_org, filter_user, filter_key_id, filter_status],
-  );
-  const columnFilters = useMemo<ColumnFiltersState>(
-    () =>
-      FILTER_COLUMNS.filter((column) => appliedFilters[column]).map((column) => ({
-        id: column,
-        value: appliedFilters[column],
-      })),
-    [appliedFilters],
-  );
-
+  const [activeSort] = sorting;
   const keyListOptions = {
-    teamID: appliedFilters.team_id || undefined,
-    organizationID: appliedFilters.org_id || undefined,
+    teamID: appliedFilter(columnFilters, "team_id"),
+    organizationID: appliedFilter(columnFilters, "org_id"),
     search: searchQuery.trim() || undefined,
-    userID: appliedFilters.user_id || undefined,
-    keyHash: appliedFilters.key_hash || undefined,
-    status: appliedFilters.status || undefined,
-    sortBy,
-    sortOrder: tableState.sort_order,
+    userID: appliedFilter(columnFilters, "user_id"),
+    keyHash: appliedFilter(columnFilters, "key_hash"),
+    status: appliedFilter(columnFilters, "status"),
+    sortBy: activeSort.id,
+    sortOrder: activeSort.desc ? "desc" : "asc",
     expand: "user",
   };
 
@@ -155,55 +132,13 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
     isPending,
     isPlaceholderData,
     isFetching,
+    isError,
     refetch,
-  } = useKeys(tablePagination.pageIndex + 1, tablePagination.pageSize, keyListOptions);
+  } = useKeys(pagination.pageIndex + 1, pagination.pageSize, keyListOptions);
 
   const keyList = useMemo(() => keys?.keys ?? [], [keys]);
   const rowCount = keys?.total_count ?? 0;
 
-  const handleSearchChange = useCallback(
-    (value: string) => {
-      void setTableState({ key_search: value || null, page: null });
-    },
-    [setTableState],
-  );
-
-  const handleSortingChange = useCallback<OnChangeFn<SortingState>>(
-    (updaterOrValue) => {
-      const active = functionalUpdate(updaterOrValue, sorting)[0];
-      void setTableState({
-        sort_by: active?.id ?? null,
-        sort_order: active ? toSortOrder(active) : null,
-        page: null,
-      });
-    },
-    [sorting, setTableState],
-  );
-
-  const handleColumnFiltersChange = useCallback<OnChangeFn<ColumnFiltersState>>(
-    (updaterOrValue) => {
-      const next = functionalUpdate(updaterOrValue, columnFilters);
-      const nextFilters = {
-        filter_team: filterValue(next, "team_id"),
-        filter_org: filterValue(next, "org_id"),
-        filter_user: filterValue(next, "user_id"),
-        filter_key_id: filterValue(next, "key_hash"),
-        filter_status: filterValue(next, "status"),
-        page: null,
-      };
-      void setTableState(nextFilters);
-    },
-    [columnFilters, setTableState],
-  );
-
-  const handlePaginationChange = useCallback<OnChangeFn<PaginationState>>(
-    (updaterOrValue) => {
-      const next = functionalUpdate(updaterOrValue, tablePagination);
-      void setTableState({ page: next.pageIndex + 1, page_size: next.pageSize });
-    },
-    [tablePagination, setTableState],
-  );
-
   const columns = useMemo(
     () => getKeyTableColumns({ allTeams, organizations, onSelectKey: (key) => void setSelectedKeyId(key.token) }),
     [allTeams, organizations, setSelectedKeyId],
@@ -296,20 +231,22 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
         data={keyList}
         columns={columns}
         getRowId={(row) => row.token}
-        defaultColumnVisibility={KEY_TABLE_HIDDEN_COLUMNS}
+        columnVisibility={columnVisibility}
+        onColumnVisibilityChange={onColumnVisibilityChange}
         sortingMode="server"
         sorting={sorting}
-        onSortingChange={handleSortingChange}
+        onSortingChange={onSortingChange}
         paginationMode="server"
-        pagination={tablePagination}
-        onPaginationChange={handlePaginationChange}
+        pagination={pagination}
+        onPaginationChange={onPaginationChange}
         rowCount={rowCount}
         filterMode="server"
         columnFilters={columnFilters}
-        onColumnFiltersChange={handleColumnFiltersChange}
+        onColumnFiltersChange={onColumnFiltersChange}
         enableColumnResizing
         columnResizeMode="onChange"
         isLoading={isPending || isPlaceholderData}
+        isError={isError}
         loadingMessage="Loading keys..."
         noDataMessage="No keys found"
         fillHeight
@@ -319,7 +256,7 @@ export function VirtualKeysTable({ headerActions }: VirtualKeysTableProps) {
             <DataTableToolbar
               table={table}
               searchValue={searchInput}
-              onSearchChange={handleSearchChange}
+              onSearchChange={setSearch}
               searchPlaceholder="Search by key alias or ID…"
               onRefresh={() => refetch?.()}
               isRefreshing={isFetching}
diff --git a/ui/litellm-dashboard/src/components/networking.test.ts b/ui/litellm-dashboard/src/components/networking.test.ts
index 578e355b85d..3b2a17101ee 100644
--- a/ui/litellm-dashboard/src/components/networking.test.ts
+++ b/ui/litellm-dashboard/src/components/networking.test.ts
@@ -20,25 +20,39 @@ describe("networking - expired session handling", () => {
     global.fetch = originalFetch;
   });
 
-  it("should call clearTokenCookies on expired session", async () => {
-    const errorData = "Authentication Error - Expired Key";
-    const { toast } = await import("@/lib/toast");
+  const loadFreshHandleError = async () => {
+    vi.resetModules();
+    const fresh = await import("./networking");
+    return fresh.handleError;
+  };
 
-    if (errorData.includes("Authentication Error - Expired Key")) {
-      toast.info("UI Session Expired. Logging out.");
-      clearTokenCookies();
-    }
+  const stubLocation = (pathname: string, search: string, hash: string) => {
+    const location = { pathname, search, hash, href: "" };
+    vi.stubGlobal("window", { location });
+    return location;
+  };
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps the query string and hash on the redirect after session expiry", async () => {
+    const handleError = await loadFreshHandleError();
+    const location = stubLocation("/ui/api-keys/", "?filter_team=t1&page=2", "#row-3");
+
+    await handleError("Authentication Error - Expired Key");
+
+    expect(location.href).toBe("/ui/api-keys/?filter_team=t1&page=2#row-3");
     expect(clearTokenCookies).toHaveBeenCalledOnce();
   });
 
-  it("should not clear cookies for non-authentication errors", () => {
-    const errorData = "Some other error";
+  it("does not navigate or clear cookies for other errors", async () => {
+    const handleError = await loadFreshHandleError();
+    const location = stubLocation("/ui/api-keys/", "?filter_team=t1&page=2", "");
 
-    if (errorData.includes("Authentication Error - Expired Key")) {
-      clearTokenCookies();
-    }
+    await handleError("Some other error");
 
+    expect(location.href).toBe("");
     expect(clearTokenCookies).not.toHaveBeenCalled();
   });
 
diff --git a/ui/litellm-dashboard/src/components/networking.tsx b/ui/litellm-dashboard/src/components/networking.tsx
index cab073dc808..e77c8ba7e41 100644
--- a/ui/litellm-dashboard/src/components/networking.tsx
+++ b/ui/litellm-dashboard/src/components/networking.tsx
@@ -383,7 +383,7 @@ export const handleError = async (errorData: string | any) => {
       clearTokenCookies();
       const browserLocation = getWindowLocation();
       if (browserLocation) {
-        window.location.href = browserLocation.pathname;
+        window.location.href = browserLocation.pathname + browserLocation.search + browserLocation.hash;
       }
     }
     lastErrorTime = currentTime;
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test-d.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test-d.tsx
index 7bbd4f918cd..c6c6a392aec 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test-d.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test-d.tsx
@@ -1,4 +1,10 @@
-import type { ColumnDef, PaginationState, RowSelectionState, SortingState } from "@tanstack/react-table";
+import type {
+  ColumnDef,
+  PaginationState,
+  RowSelectionState,
+  SortingState,
+  VisibilityState,
+} from "@tanstack/react-table";
 
 import { DataTable } from "./DataTable";
 
@@ -12,6 +18,7 @@ const columns: ColumnDef<Row, unknown>[] = [];
 const sorting: SortingState = [{ id: "name", desc: false }];
 const pagination: PaginationState = { pageIndex: 0, pageSize: 10 };
 const rowSelection: RowSelectionState = { r1: true };
+const columnVisibility: VisibilityState = { name: false };
 const noop = () => {};
 
 export const uncontrolled = <DataTable data={data} columns={columns} defaultSorting={sorting} />;
@@ -32,6 +39,8 @@ export const controlled = (
     onColumnFiltersChange={noop}
     rowSelection={rowSelection}
     onRowSelectionChange={noop}
+    columnVisibility={columnVisibility}
+    onColumnVisibilityChange={noop}
   />
 );
 
@@ -65,3 +74,19 @@ export const selectionWithoutHandler = (
   // @ts-expect-error a controlled `rowSelection` needs `onRowSelectionChange` or selection changes are dropped
   <DataTable data={data} columns={columns} rowSelection={rowSelection} />
 );
+
+export const visibilityWithoutHandler = (
+  // @ts-expect-error a controlled `columnVisibility` needs `onColumnVisibilityChange` or Columns-menu toggles are dropped
+  <DataTable data={data} columns={columns} columnVisibility={columnVisibility} />
+);
+
+export const bothVisibilitySources = (
+  // @ts-expect-error `defaultColumnVisibility` seeds uncontrolled visibility, so it cannot pair with a controlled `columnVisibility`
+  <DataTable
+    data={data}
+    columns={columns}
+    defaultColumnVisibility={columnVisibility}
+    columnVisibility={columnVisibility}
+    onColumnVisibilityChange={noop}
+  />
+);
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx
index 8ed8e392ae1..336fc43d695 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx
@@ -1,4 +1,4 @@
-import type { ColumnDef, ExpandedState, OnChangeFn, PaginationState } from "@tanstack/react-table";
+import type { ColumnDef, ExpandedState, OnChangeFn, PaginationState, VisibilityState } from "@tanstack/react-table";
 import { render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { useState } from "react";
@@ -278,11 +278,18 @@ describe("DataTable pagination", () => {
   type ServerPageHarnessProps = {
     rowCount: number;
     isLoading?: boolean;
+    isError?: boolean;
     initialPageIndex: number;
     onChange: (next: PaginationState) => void;
   };
 
-  function ServerPageHarness({ rowCount, isLoading = false, initialPageIndex, onChange }: ServerPageHarnessProps) {
+  function ServerPageHarness({
+    rowCount,
+    isLoading = false,
+    isError = false,
+    initialPageIndex,
+    onChange,
+  }: ServerPageHarnessProps) {
     const [pagination, setPagination] = useState<PaginationState>({ pageIndex: initialPageIndex, pageSize: 10 });
     const handleChange: OnChangeFn<PaginationState> = (updater) => {
       const next = typeof updater === "function" ? updater(pagination) : updater;
@@ -298,6 +305,7 @@ describe("DataTable pagination", () => {
         onPaginationChange={handleChange}
         rowCount={rowCount}
         isLoading={isLoading}
+        isError={isError}
       />
     );
   }
@@ -339,6 +347,29 @@ describe("DataTable pagination", () => {
     expect(onChange).toHaveBeenCalledTimes(1);
     expect(screen.getByText("Page 2 of 2")).toBeInTheDocument();
   });
+
+  it("server mode keeps a deep-linked page when the fetch failed, instead of snapping to page 1 on rowCount 0", async () => {
+    const onChange = vi.fn();
+    render(<ServerPageHarness rowCount={0} isError initialPageIndex={2} onChange={onChange} />);
+
+    expect(screen.getByText("Page 3 of 1")).toBeInTheDocument();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("server mode resumes clamping once the error clears and a real rowCount arrives", async () => {
+    const onChange = vi.fn();
+    const { rerender } = render(<ServerPageHarness rowCount={0} isError initialPageIndex={2} onChange={onChange} />);
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(onChange).not.toHaveBeenCalled();
+
+    rerender(<ServerPageHarness rowCount={15} initialPageIndex={2} onChange={onChange} />);
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith({ pageIndex: 1, pageSize: 10 }));
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(screen.getByText("Page 2 of 2")).toBeInTheDocument();
+  });
 });
 
 describe("DataTable filtering", () => {
@@ -555,6 +586,69 @@ describe("DataTable column visibility", () => {
     expect(await screen.findByTestId("view-option-email")).toBeInTheDocument();
     expect(screen.queryByTestId("view-option-name")).not.toBeInTheDocument();
   });
+
+  it("uncontrolled mode seeds hidden columns from defaultColumnVisibility and still toggles internally", async () => {
+    const user = userEvent.setup();
+    render(
+      <DataTable
+        data={CHARLIE_ALICE_BOB}
+        columns={nameEmailColumns}
+        defaultColumnVisibility={{ email: false }}
+        toolbar={(table) => <DataTableViewOptions table={table} />}
+      />,
+    );
+
+    expect(screen.queryByRole("columnheader", { name: "Email" })).not.toBeInTheDocument();
+    await user.click(screen.getByTestId("view-options-trigger"));
+    await user.click(await screen.findByTestId("view-option-email"));
+    expect(await screen.findByRole("columnheader", { name: "Email" })).toBeInTheDocument();
+  });
+
+  it("controlled mode hides columns from the prop and reports toggles without changing them locally", async () => {
+    const user = userEvent.setup();
+    const onColumnVisibilityChange = vi.fn<OnChangeFn<VisibilityState>>();
+    render(
+      <DataTable
+        data={CHARLIE_ALICE_BOB}
+        columns={nameEmailColumns}
+        columnVisibility={{ email: false }}
+        onColumnVisibilityChange={onColumnVisibilityChange}
+        toolbar={(table) => <DataTableViewOptions table={table} />}
+      />,
+    );
+
+    expect(screen.queryByRole("columnheader", { name: "Email" })).not.toBeInTheDocument();
+    await user.click(screen.getByTestId("view-options-trigger"));
+    await user.click(await screen.findByTestId("view-option-email"));
+
+    expect(onColumnVisibilityChange).toHaveBeenCalledTimes(1);
+    const updater = onColumnVisibilityChange.mock.calls[0]?.[0];
+    const next = typeof updater === "function" ? updater({ email: false }) : updater;
+    expect(next).toEqual({ email: true });
+    expect(screen.queryByRole("columnheader", { name: "Email" })).not.toBeInTheDocument();
+  });
+
+  it("controlled mode reveals the column once the parent applies the reported change", async () => {
+    const user = userEvent.setup();
+    const Harness = () => {
+      const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({ email: false });
+      return (
+        <DataTable
+          data={CHARLIE_ALICE_BOB}
+          columns={nameEmailColumns}
+          columnVisibility={columnVisibility}
+          onColumnVisibilityChange={setColumnVisibility}
+          toolbar={(table) => <DataTableViewOptions table={table} />}
+        />
+      );
+    };
+    render(<Harness />);
+
+    expect(screen.queryByRole("columnheader", { name: "Email" })).not.toBeInTheDocument();
+    await user.click(screen.getByTestId("view-options-trigger"));
+    await user.click(await screen.findByTestId("view-option-email"));
+    expect(await screen.findByRole("columnheader", { name: "Email" })).toBeInTheDocument();
+  });
 });
 
 describe("DataTable pinned columns", () => {
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx
index 26162a3f1f7..e0f57ae1052 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx
@@ -457,6 +457,7 @@ function useDataTableInstance<TData extends RowData, TValue>(
     onPaginationChange,
     rowCount,
     isLoading = false,
+    isError,
     pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
     filterMode = "none",
     columnFilters,
@@ -466,6 +467,8 @@ function useDataTableInstance<TData extends RowData, TValue>(
     onGlobalFilterChange,
     enableColumnResizing = false,
     columnResizeMode = "onEnd",
+    columnVisibility,
+    onColumnVisibilityChange,
     defaultColumnVisibility,
     getRowCanExpand,
     renderSubComponent,
@@ -481,7 +484,7 @@ function useDataTableInstance<TData extends RowData, TValue>(
     pageIndex: 0,
     pageSize: pageSizeOptions[0] ?? 25,
   });
-  useServerPageClamp(paginationMode === "server" && !isLoading, rowCount, paginationState);
+  useServerPageClamp(paginationMode === "server" && !isLoading && !isError, rowCount, paginationState);
   const filterState = useControllable<ColumnFiltersState>(
     columnFilters,
     onColumnFiltersChange,
@@ -490,7 +493,11 @@ function useDataTableInstance<TData extends RowData, TValue>(
   const globalFilterState = useControllable<string>(globalFilter, onGlobalFilterChange, "");
   const expandedState = useControllable<ExpandedState>(expanded, onExpandedChange, {});
   const rowSelectionState = useControllable<RowSelectionState>(rowSelection, onRowSelectionChange, {});
-  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(defaultColumnVisibility ?? {});
+  const columnVisibilityState = useControllable<VisibilityState>(
+    columnVisibility,
+    onColumnVisibilityChange,
+    defaultColumnVisibility ?? {},
+  );
   const [columnSizing, setColumnSizing] = useState<ColumnSizingState>({});
   const columnPinning = React.useMemo(() => derivePinning(columns), [columns]);
   const expansionGuard = renderSubComponent !== undefined ? getRowCanExpand : undefined;
@@ -505,7 +512,7 @@ function useDataTableInstance<TData extends RowData, TValue>(
       globalFilter: globalFilterState.value,
       expanded: expandedState.value,
       rowSelection: rowSelectionState.value,
-      columnVisibility,
+      columnVisibility: columnVisibilityState.value,
       columnSizing,
     },
     initialState: { columnPinning },
@@ -521,7 +528,7 @@ function useDataTableInstance<TData extends RowData, TValue>(
     onGlobalFilterChange: globalFilterState.onChange,
     onExpandedChange: expandedState.onChange,
     onRowSelectionChange: rowSelectionState.onChange,
-    onColumnVisibilityChange: setColumnVisibility,
+    onColumnVisibilityChange: columnVisibilityState.onChange,
     onColumnSizingChange: setColumnSizing,
     getColumnCanGlobalFilter: (column) => columnCanGlobalFilter(data[0], column),
     getCoreRowModel: getCoreRowModel(),
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/index.ts b/ui/litellm-dashboard/src/components/shared/DataTable/index.ts
index 39a887ba948..85cc5f287e0 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/index.ts
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/index.ts
@@ -12,6 +12,8 @@ export {
   type DataTableSortVariant,
   type DataTableSortField,
 } from "./DataTableSortHeader";
+export { usePersistedColumnVisibility } from "./usePersistedColumnVisibility";
+export { useUrlTableState, type UrlTableState, type UrlTableStateOptions } from "./useUrlTableState";
 export type { DataTablePaginationProps } from "./DataTablePagination";
 export type {
   ColumnPinnedSide,
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/types.ts b/ui/litellm-dashboard/src/components/shared/DataTable/types.ts
index c767a0a64c0..4529e3df164 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/types.ts
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/types.ts
@@ -27,6 +27,7 @@ export interface DataTableResolvedProps<TData extends RowData, TValue> {
   getRowId?: (row: TData, index: number, parent?: Row<TData>) => string;
 
   isLoading?: boolean;
+  isError?: boolean;
   loadingMessage?: string;
   skeletonRowCount?: number;
   noDataMessage?: React.ReactNode;
@@ -53,6 +54,8 @@ export interface DataTableResolvedProps<TData extends RowData, TValue> {
 
   enableColumnResizing?: boolean;
   columnResizeMode?: ColumnResizeMode;
+  columnVisibility?: VisibilityState;
+  onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
   defaultColumnVisibility?: VisibilityState;
 
   getRowCanExpand?: (row: Row<TData>) => boolean;
@@ -96,6 +99,9 @@ type DataTableBaseProps<TData extends RowData, TValue> = Omit<
   | "columnFilters"
   | "onColumnFiltersChange"
   | "defaultColumnFilters"
+  | "columnVisibility"
+  | "onColumnVisibilityChange"
+  | "defaultColumnVisibility"
   | "rowSelection"
   | "onRowSelectionChange"
 >;
@@ -142,6 +148,18 @@ type FilterProps =
       defaultColumnFilters?: ColumnFiltersState;
     };
 
+type ColumnVisibilityProps =
+  | {
+      columnVisibility: VisibilityState;
+      onColumnVisibilityChange: OnChangeFn<VisibilityState>;
+      defaultColumnVisibility?: never;
+    }
+  | {
+      columnVisibility?: never;
+      onColumnVisibilityChange?: never;
+      defaultColumnVisibility?: VisibilityState;
+    };
+
 type RowSelectionProps =
   | { rowSelection: RowSelectionState; onRowSelectionChange: OnChangeFn<RowSelectionState> }
   | { rowSelection?: never; onRowSelectionChange?: OnChangeFn<RowSelectionState> };
@@ -150,4 +168,5 @@ export type DataTableProps<TData extends RowData, TValue> = DataTableBaseProps<T
   SortingProps &
   PaginationProps &
   FilterProps &
+  ColumnVisibilityProps &
   RowSelectionProps;
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
new file mode 100644
index 00000000000..8d2e0f61f54
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
@@ -0,0 +1,98 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { usePersistedColumnVisibility } from "./usePersistedColumnVisibility";
+
+const keyFor = (tableId: string): string => `litellm_table_columns_${tableId}`;
+
+const stored = (tableId: string): unknown => {
+  const raw = localStorage.getItem(keyFor(tableId));
+  return raw === null ? null : JSON.parse(raw);
+};
+
+describe("usePersistedColumnVisibility", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("layers the stored choices over the defaults, so a default added after the snapshot still applies", () => {
+    localStorage.setItem(keyFor("keys"), JSON.stringify({ email: false, spend: true }));
+
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys", { spend: false, name: false }));
+
+    expect(result.current.columnVisibility).toEqual({ email: false, spend: true, name: false });
+  });
+
+  it("falls back to the defaults when nothing is stored, and to {} without defaults", () => {
+    const withDefaults = renderHook(() => usePersistedColumnVisibility("keys", { spend: false }));
+    expect(withDefaults.result.current.columnVisibility).toEqual({ spend: false });
+
+    const bare = renderHook(() => usePersistedColumnVisibility("keys"));
+    expect(bare.result.current.columnVisibility).toEqual({});
+  });
+
+  it("writes an object update to state and storage", () => {
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys"));
+
+    act(() => result.current.onColumnVisibilityChange({ email: false }));
+
+    expect(result.current.columnVisibility).toEqual({ email: false });
+    expect(stored("keys")).toEqual({ email: false });
+  });
+
+  it("resolves a function updater against the current state before persisting", () => {
+    localStorage.setItem(keyFor("keys"), JSON.stringify({ email: false }));
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys"));
+
+    act(() => result.current.onColumnVisibilityChange((previous) => ({ ...previous, name: false })));
+
+    expect(result.current.columnVisibility).toEqual({ email: false, name: false });
+    expect(stored("keys")).toEqual({ email: false, name: false });
+  });
+
+  it.each([
+    ["truncated JSON", '{"email":fal'],
+    ["a JSON scalar", "42"],
+    ["a JSON array", "[true]"],
+    ["non-boolean values", JSON.stringify({ email: "no" })],
+  ])("falls back to the defaults when storage holds %s", (_label, raw) => {
+    localStorage.setItem(keyFor("keys"), raw);
+
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys", { spend: false }));
+
+    expect(result.current.columnVisibility).toEqual({ spend: false });
+  });
+
+  it("keeps distinct tableIds isolated in state and storage", () => {
+    const keys = renderHook(() => usePersistedColumnVisibility("keys"));
+    const teams = renderHook(() => usePersistedColumnVisibility("teams"));
+
+    act(() => keys.result.current.onColumnVisibilityChange({ email: false }));
+
+    expect(keys.result.current.columnVisibility).toEqual({ email: false });
+    expect(teams.result.current.columnVisibility).toEqual({});
+    expect(stored("keys")).toEqual({ email: false });
+    expect(stored("teams")).toBeNull();
+  });
+
+  it("returns the defaults without throwing when storage is unavailable", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("SecurityError");
+    });
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("QuotaExceededError");
+    });
+
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys", { spend: false }));
+    expect(result.current.columnVisibility).toEqual({ spend: false });
+
+    act(() => result.current.onColumnVisibilityChange({ email: false }));
+    expect(result.current.columnVisibility).toEqual({ email: false });
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
new file mode 100644
index 00000000000..b56ae13d63b
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
@@ -0,0 +1,54 @@
+import type { OnChangeFn, VisibilityState } from "@tanstack/react-table";
+import { useCallback, useState } from "react";
+
+import { getLocalStorageItem, setLocalStorageItem } from "@/utils/localStorageUtils";
+
+const STORAGE_KEY_PREFIX = "litellm_table_columns_";
+
+const EMPTY_VISIBILITY: VisibilityState = {};
+
+function storageKey(tableId: string): string {
+  return `${STORAGE_KEY_PREFIX}${tableId}`;
+}
+
+function isVisibilityState(value: unknown): value is VisibilityState {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.values(value).every((visible) => typeof visible === "boolean");
+}
+
+function readStoredVisibility(tableId: string, defaults: VisibilityState): VisibilityState {
+  const raw = getLocalStorageItem(storageKey(tableId));
+  if (raw === null) {
+    return defaults;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isVisibilityState(parsed) ? { ...defaults, ...parsed } : defaults;
+  } catch {
+    return defaults;
+  }
+}
+
+export function usePersistedColumnVisibility(
+  tableId: string,
+  defaults: VisibilityState = EMPTY_VISIBILITY,
+): { columnVisibility: VisibilityState; onColumnVisibilityChange: OnChangeFn<VisibilityState> } {
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(() =>
+    readStoredVisibility(tableId, defaults),
+  );
+
+  const onColumnVisibilityChange = useCallback<OnChangeFn<VisibilityState>>(
+    (updater) => {
+      setColumnVisibility((previous) => {
+        const next = typeof updater === "function" ? updater(previous) : updater;
+        setLocalStorageItem(storageKey(tableId), JSON.stringify(next));
+        return next;
+      });
+    },
+    [tableId],
+  );
+
+  return { columnVisibility, onColumnVisibilityChange };
+}
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.test.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.test.tsx
new file mode 100644
index 00000000000..ad46d18b5d8
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.test.tsx
@@ -0,0 +1,325 @@
+import { SortingState } from "@tanstack/react-table";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { withNuqsTestingAdapter, type OnUrlUpdateFunction } from "nuqs/adapters/testing";
+import { describe, expect, it, Mock, vi } from "vitest";
+import { useUrlTableState, type UrlTableStateOptions } from "./useUrlTableState";
+
+const FILTER_COLUMNS = ["team_id", "user_id"] as const;
+type FilterColumn = (typeof FILTER_COLUMNS)[number];
+
+const BASE_OPTIONS: UrlTableStateOptions<FilterColumn> = {
+  sortFields: ["created_at", "spend", "key_alias"],
+  defaultSort: { id: "created_at", desc: true },
+  defaultPageSize: 50,
+  filterColumns: FILTER_COLUMNS,
+};
+
+const PREFIXED_AND_UNPREFIXED_PARAMS = {
+  audit_page: "2",
+  audit_page_size: "10",
+  audit_search: "prefixed",
+  audit_sort_by: "spend",
+  audit_sort_order: "asc",
+  audit_filter_team_id: "team-1",
+  page: "5",
+  search: "unprefixed",
+  filter_team_id: "other-team",
+};
+
+const RENAMED_AND_DEFAULT_PARAMS = {
+  key_search: "prod",
+  filter_team: "team-1",
+  search: "ignored",
+  filter_team_id: "ignored",
+};
+
+const flipDirection = (previous: SortingState): SortingState => previous.map((sort) => ({ ...sort, desc: !sort.desc }));
+
+const renderTableState = (
+  searchParams: Record<string, string> = {},
+  overrides: Partial<UrlTableStateOptions<FilterColumn>> = {},
+) => {
+  const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+  const options = { ...BASE_OPTIONS, ...overrides };
+  const hook = renderHook(() => useUrlTableState(options), {
+    wrapper: withNuqsTestingAdapter({ searchParams, onUrlUpdate, hasMemory: true }),
+  });
+  return { ...hook, onUrlUpdate };
+};
+
+const lastUrl = (onUrlUpdate: Mock<OnUrlUpdateFunction>) => {
+  const event = onUrlUpdate.mock.calls.at(-1)?.[0];
+  if (!event) throw new Error("no URL update was emitted");
+  return event;
+};
+
+const flushUrl = async (onUrlUpdate: Mock<OnUrlUpdateFunction>, write: () => void) => {
+  const callsBefore = onUrlUpdate.mock.calls.length;
+  await act(async () => {
+    write();
+  });
+  await waitFor(() => expect(onUrlUpdate.mock.calls.length).toBeGreaterThan(callsBefore));
+  return lastUrl(onUrlUpdate).searchParams;
+};
+
+describe("reading table state from the URL", () => {
+  it("falls back to the defaults when the URL carries no table state", () => {
+    const { result } = renderTableState();
+
+    expect(result.current.search).toBe("");
+    expect(result.current.sorting).toEqual([{ id: "created_at", desc: true }]);
+    expect(result.current.pagination).toEqual({ pageIndex: 0, pageSize: 50 });
+    expect(result.current.columnFilters).toEqual([]);
+  });
+
+  it("maps the 1-based page and page_size onto TanStack pagination", () => {
+    const { result } = renderTableState({ page: "3", page_size: "25" });
+
+    expect(result.current.pagination).toEqual({ pageIndex: 2, pageSize: 25 });
+  });
+
+  it.each(["0", "-3", "not-a-number"])("clamps a page of %s up to the first page", (page) => {
+    const { result } = renderTableState({ page });
+
+    expect(result.current.pagination.pageIndex).toBe(0);
+  });
+
+  it.each([
+    ["1000", undefined, 100],
+    ["1000", 20, 20],
+    ["0", undefined, 1],
+  ])("clamps a page_size of %s with maxPageSize %s to %s", (pageSize, maxPageSize, expected) => {
+    const { result } = renderTableState({ page_size: pageSize }, { maxPageSize });
+
+    expect(result.current.pagination.pageSize).toBe(expected);
+  });
+
+  it("reads a sortable sort_by and its sort_order", () => {
+    const { result } = renderTableState({ sort_by: "spend", sort_order: "asc" });
+
+    expect(result.current.sorting).toEqual([{ id: "spend", desc: false }]);
+  });
+
+  it("resolves a sort_by outside the allow-list to the default column while keeping the URL's direction", () => {
+    const { result } = renderTableState({ sort_by: "totally_unknown", sort_order: "asc" });
+
+    expect(result.current.sorting).toEqual([{ id: "created_at", desc: false }]);
+  });
+
+  it("maps filter_<column> params onto columnFilters, trimming whitespace and dropping blanks", () => {
+    const { result } = renderTableState({ filter_team_id: "team-1", filter_user_id: "   " });
+
+    expect(result.current.columnFilters).toEqual([{ id: "team_id", value: "team-1" }]);
+
+    const trimmed = renderTableState({ filter_user_id: "  user-42  " });
+    expect(trimmed.result.current.columnFilters).toEqual([{ id: "user_id", value: "user-42" }]);
+  });
+
+  it("reads the search term verbatim so the input can hold trailing spaces", () => {
+    const { result } = renderTableState({ search: "prod " });
+
+    expect(result.current.search).toBe("prod ");
+  });
+
+  it("reads every key under keyPrefix and ignores the unprefixed ones", () => {
+    const { result } = renderTableState(PREFIXED_AND_UNPREFIXED_PARAMS, { keyPrefix: "audit_" });
+
+    expect(result.current.pagination).toEqual({ pageIndex: 1, pageSize: 10 });
+    expect(result.current.search).toBe("prefixed");
+    expect(result.current.sorting).toEqual([{ id: "spend", desc: false }]);
+    expect(result.current.columnFilters).toEqual([{ id: "team_id", value: "team-1" }]);
+  });
+
+  it("reads renamed keys from urlKeys and ignores the default names", () => {
+    const { result } = renderTableState(RENAMED_AND_DEFAULT_PARAMS, {
+      urlKeys: { search: "key_search", filter_team_id: "filter_team" },
+    });
+
+    expect(result.current.search).toBe("prod");
+    expect(result.current.columnFilters).toEqual([{ id: "team_id", value: "team-1" }]);
+  });
+
+  it("applies keyPrefix in front of a renamed key", () => {
+    const { result } = renderTableState(
+      { audit_key_search: "prod", key_search: "ignored" },
+      { keyPrefix: "audit_", urlKeys: { search: "key_search" } },
+    );
+
+    expect(result.current.search).toBe("prod");
+  });
+});
+
+describe("writing table state to the URL", () => {
+  it("resolves a function updater against the current pagination and replaces history", async () => {
+    const { result, onUrlUpdate } = renderTableState({ page: "2" });
+
+    const url = await flushUrl(onUrlUpdate, () =>
+      result.current.onPaginationChange((previous) => ({ ...previous, pageIndex: previous.pageIndex + 1 })),
+    );
+
+    expect(url.get("page")).toBe("3");
+    expect(url.has("page_size")).toBe(false);
+    expect(lastUrl(onUrlUpdate).options.history).toBe("replace");
+    expect(result.current.pagination).toEqual({ pageIndex: 2, pageSize: 50 });
+  });
+
+  it("writes page_size and drops it again once it returns to the default", async () => {
+    const { result, onUrlUpdate } = renderTableState();
+
+    const withSize = await flushUrl(onUrlUpdate, () =>
+      result.current.onPaginationChange({ pageIndex: 0, pageSize: 25 }),
+    );
+    expect(withSize.get("page_size")).toBe("25");
+    expect(withSize.has("page")).toBe(false);
+
+    const backToDefault = await flushUrl(onUrlUpdate, () =>
+      result.current.onPaginationChange({ pageIndex: 0, pageSize: 50 }),
+    );
+    expect(backToDefault.has("page_size")).toBe(false);
+  });
+
+  it("setSearch writes the term and returns to the first page", async () => {
+    const { result, onUrlUpdate } = renderTableState({ page: "3" });
+
+    const url = await flushUrl(onUrlUpdate, () => result.current.setSearch("prod"));
+
+    expect(url.get("search")).toBe("prod");
+    expect(url.has("page")).toBe(false);
+    expect(result.current.search).toBe("prod");
+    expect(result.current.pagination.pageIndex).toBe(0);
+  });
+
+  it("setSearch with an empty string removes the key", async () => {
+    const { result, onUrlUpdate } = renderTableState({ search: "prod" });
+
+    const url = await flushUrl(onUrlUpdate, () => result.current.setSearch(""));
+
+    expect(url.has("search")).toBe(false);
+    expect(result.current.search).toBe("");
+  });
+
+  it("onSortingChange writes sort_by and sort_order and returns to the first page", async () => {
+    const { result, onUrlUpdate } = renderTableState({ page: "3" });
+
+    const url = await flushUrl(onUrlUpdate, () => result.current.onSortingChange([{ id: "spend", desc: false }]));
+
+    expect(url.get("sort_by")).toBe("spend");
+    expect(url.get("sort_order")).toBe("asc");
+    expect(url.has("page")).toBe(false);
+    expect(result.current.sorting).toEqual([{ id: "spend", desc: false }]);
+  });
+
+  it("onSortingChange drops the keys when the sort matches the default or is cleared", async () => {
+    const { result, onUrlUpdate } = renderTableState({ sort_by: "spend", sort_order: "asc" });
+
+    const explicitDefault = await flushUrl(onUrlUpdate, () =>
+      result.current.onSortingChange([{ id: "created_at", desc: true }]),
+    );
+    expect(explicitDefault.has("sort_by")).toBe(false);
+    expect(explicitDefault.has("sort_order")).toBe(false);
+
+    await flushUrl(onUrlUpdate, () => result.current.onSortingChange([{ id: "key_alias", desc: false }]));
+    const cleared = await flushUrl(onUrlUpdate, () => result.current.onSortingChange([]));
+    expect(cleared.has("sort_by")).toBe(false);
+    expect(cleared.has("sort_order")).toBe(false);
+    expect(result.current.sorting).toEqual([{ id: "created_at", desc: true }]);
+  });
+
+  it("onSortingChange resolves a function updater against the current sort", async () => {
+    const { result, onUrlUpdate } = renderTableState({ sort_by: "spend" });
+
+    const url = await flushUrl(onUrlUpdate, () => result.current.onSortingChange(flipDirection));
+
+    expect(url.get("sort_by")).toBe("spend");
+    expect(url.get("sort_order")).toBe("asc");
+    expect(result.current.sorting).toEqual([{ id: "spend", desc: false }]);
+  });
+
+  it("onColumnFiltersChange writes trimmed filter_<column> keys and returns to the first page", async () => {
+    const { result, onUrlUpdate } = renderTableState({ page: "3" });
+
+    const url = await flushUrl(onUrlUpdate, () =>
+      result.current.onColumnFiltersChange([{ id: "team_id", value: "  team-1  " }]),
+    );
+
+    expect(url.get("filter_team_id")).toBe("team-1");
+    expect(url.has("page")).toBe(false);
+    expect(result.current.columnFilters).toEqual([{ id: "team_id", value: "team-1" }]);
+  });
+
+  it("onColumnFiltersChange removes the key for an empty value and for a filter no longer present", async () => {
+    const { result, onUrlUpdate } = renderTableState({ filter_team_id: "team-1", filter_user_id: "user-42" });
+
+    const url = await flushUrl(onUrlUpdate, () => result.current.onColumnFiltersChange([{ id: "team_id", value: "" }]));
+
+    expect(url.has("filter_team_id")).toBe(false);
+    expect(url.has("filter_user_id")).toBe(false);
+    expect(result.current.columnFilters).toEqual([]);
+  });
+
+  it("onColumnFiltersChange ignores a non-string filter value", async () => {
+    const { result, onUrlUpdate } = renderTableState({ filter_team_id: "team-1" });
+
+    const url = await flushUrl(onUrlUpdate, () =>
+      result.current.onColumnFiltersChange([{ id: "team_id", value: ["team-1", "team-2"] }]),
+    );
+
+    expect(url.has("filter_team_id")).toBe(false);
+  });
+
+  it("onColumnFiltersChange resolves a function updater against the current filters", async () => {
+    const { result, onUrlUpdate } = renderTableState({ filter_team_id: "team-1" });
+
+    const url = await flushUrl(onUrlUpdate, () =>
+      result.current.onColumnFiltersChange((previous) => [...previous, { id: "user_id", value: "user-42" }]),
+    );
+
+    expect(url.get("filter_team_id")).toBe("team-1");
+    expect(url.get("filter_user_id")).toBe("user-42");
+  });
+
+  it("writes prefixed and renamed keys only", async () => {
+    const { result, onUrlUpdate } = renderTableState(
+      {},
+      { keyPrefix: "audit_", urlKeys: { search: "key_search", filter_team_id: "filter_team" } },
+    );
+
+    await flushUrl(onUrlUpdate, () => result.current.setSearch("prod"));
+    await flushUrl(onUrlUpdate, () => result.current.onSortingChange([{ id: "spend", desc: false }]));
+    const url = await flushUrl(onUrlUpdate, () =>
+      result.current.onColumnFiltersChange([{ id: "team_id", value: "team-1" }]),
+    );
+
+    expect(url.get("audit_key_search")).toBe("prod");
+    expect(url.get("audit_sort_by")).toBe("spend");
+    expect(url.get("audit_filter_team")).toBe("team-1");
+    expect([...url.keys()].filter((key) => !key.startsWith("audit_"))).toEqual([]);
+    expect(url.has("audit_search")).toBe(false);
+    expect(url.has("audit_filter_team_id")).toBe(false);
+  });
+});
+
+describe("referential stability", () => {
+  it("keeps the TanStack state and the page-clamp handler stable across rerenders while the URL is unchanged", () => {
+    const { result, rerender } = renderTableState({ page: "2", filter_team_id: "team-1", sort_by: "spend" });
+    const first = result.current;
+
+    rerender();
+
+    expect(result.current.sorting).toBe(first.sorting);
+    expect(result.current.pagination).toBe(first.pagination);
+    expect(result.current.columnFilters).toBe(first.columnFilters);
+    expect(result.current.onPaginationChange).toBe(first.onPaginationChange);
+  });
+
+  it("hands out new pagination and untouched sorting after a page change", async () => {
+    const { result, onUrlUpdate } = renderTableState({ sort_by: "spend" });
+    const first = result.current;
+
+    await flushUrl(onUrlUpdate, () => result.current.onPaginationChange({ pageIndex: 4, pageSize: 50 }));
+
+    expect(result.current.pagination).not.toBe(first.pagination);
+    expect(result.current.pagination.pageIndex).toBe(4);
+    expect(result.current.sorting).toBe(first.sorting);
+  });
+});
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.ts b/ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.ts
new file mode 100644
index 00000000000..1a423663936
--- /dev/null
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/useUrlTableState.ts
@@ -0,0 +1,232 @@
+import { ColumnFiltersState, functionalUpdate, OnChangeFn, PaginationState, SortingState } from "@tanstack/react-table";
+import { createParser, Nullable, parseAsInteger, parseAsString, parseAsStringLiteral, useQueryStates } from "nuqs";
+import { useCallback, useMemo } from "react";
+
+const SORT_ORDERS = ["asc", "desc"] as const;
+type SortOrder = (typeof SORT_ORDERS)[number];
+
+const STANDARD_KEYS = ["search", "sort_by", "sort_order", "page", "page_size"] as const;
+type StandardKey = (typeof STANDARD_KEYS)[number];
+type FilterStateKey<F extends string> = `filter_${F}`;
+type StateKey<F extends string> = StandardKey | FilterStateKey<F>;
+
+const MAX_PAGE = 100_000;
+const DEFAULT_MAX_PAGE_SIZE = 100;
+
+export interface UrlTableStateOptions<F extends string> {
+  sortFields: readonly string[];
+  defaultSort: { id: string; desc: boolean };
+  defaultPageSize: number;
+  maxPageSize?: number;
+  filterColumns: readonly F[];
+  keyPrefix?: string;
+  urlKeys?: Partial<Record<StateKey<F>, string>>;
+}
+
+export interface UrlTableState {
+  search: string;
+  setSearch: (value: string) => void;
+  sorting: SortingState;
+  onSortingChange: OnChangeFn<SortingState>;
+  pagination: PaginationState;
+  onPaginationChange: OnChangeFn<PaginationState>;
+  columnFilters: ColumnFiltersState;
+  onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
+}
+
+const boundedInteger = (min: number, max: number, fallback: number) =>
+  createParser({
+    parse: (value: string) => {
+      const parsed = parseAsInteger.parse(value);
+      return parsed === null ? null : Math.min(Math.max(parsed, min), max);
+    },
+    serialize: String,
+  }).withDefault(fallback);
+
+const optionalString = parseAsString.withDefault("");
+type OptionalStringParser = typeof optionalString;
+const sortOrderParser = (fallback: SortOrder) => parseAsStringLiteral(SORT_ORDERS).withDefault(fallback);
+
+interface StandardValues {
+  search: string;
+  sort_by: string;
+  sort_order: SortOrder;
+  page: number;
+  page_size: number;
+}
+type FilterValues<F extends string> = Record<FilterStateKey<F>, string>;
+type StandardUpdate = Partial<Nullable<StandardValues>>;
+type FilterUpdate<F extends string> = Record<FilterStateKey<F>, string | null> & Pick<Nullable<StandardValues>, "page">;
+type SetTableValues<F extends string> = (update: StandardUpdate | FilterUpdate<F> | null) => Promise<URLSearchParams>;
+
+interface TableQueryState<F extends string> {
+  values: StandardValues;
+  filters: FilterValues<F>;
+  setValues: SetTableValues<F>;
+}
+
+type TableParsers<F extends string> = {
+  search: OptionalStringParser;
+  sort_by: OptionalStringParser;
+  sort_order: ReturnType<typeof sortOrderParser>;
+  page: ReturnType<typeof boundedInteger>;
+  page_size: ReturnType<typeof boundedInteger>;
+} & Record<FilterStateKey<F>, OptionalStringParser>;
+
+const useTableQueryStates = <F extends string>(
+  parsers: TableParsers<F>,
+  urlKeys: Record<StateKey<F>, string>,
+): TableQueryState<F> => {
+  const [state, setState] = useQueryStates(parsers, { urlKeys });
+  return useMemo(
+    () => ({
+      values: state as StandardValues,
+      filters: state as FilterValues<F>,
+      setValues: setState as SetTableValues<F>,
+    }),
+    [state, setState],
+  );
+};
+
+const filterStateKey = <F extends string>(column: F): FilterStateKey<F> => `filter_${column}`;
+
+const filterParsers = <F extends string>(filterColumns: readonly F[]) =>
+  Object.fromEntries(filterColumns.map((column) => [filterStateKey(column), optionalString])) as Record<
+    FilterStateKey<F>,
+    OptionalStringParser
+  >;
+
+const resolveUrlKeys = <F extends string>(
+  filterColumns: readonly F[],
+  keyPrefix: string,
+  renamed: Partial<Record<StateKey<F>, string>>,
+) => {
+  const stateKeys: readonly StateKey<F>[] = [
+    ...STANDARD_KEYS,
+    ...filterColumns.map((column) => filterStateKey(column)),
+  ];
+  return Object.fromEntries(stateKeys.map((key) => [key, `${keyPrefix}${renamed[key] ?? key}`])) as Record<
+    StateKey<F>,
+    string
+  >;
+};
+
+const filterValue = (filters: ColumnFiltersState, column: string): string | null => {
+  const value = filters.find((filter) => filter.id === column)?.value;
+  return (typeof value === "string" ? value.trim() : "") || null;
+};
+
+const filterUpdates = <F extends string>(filterColumns: readonly F[], filters: ColumnFiltersState) =>
+  Object.fromEntries(filterColumns.map((column) => [filterStateKey(column), filterValue(filters, column)])) as Record<
+    FilterStateKey<F>,
+    string | null
+  >;
+
+const toSortOrder = (active: SortingState[number]): SortOrder => (active.desc ? "desc" : "asc");
+
+export function useUrlTableState<F extends string>(options: UrlTableStateOptions<F>): UrlTableState {
+  const {
+    sortFields,
+    defaultSort,
+    defaultPageSize,
+    maxPageSize = DEFAULT_MAX_PAGE_SIZE,
+    filterColumns,
+    keyPrefix = "",
+    urlKeys: renamedKeys,
+  } = options;
+  const defaultSortId = defaultSort.id;
+  const defaultSortOrder: SortOrder = defaultSort.desc ? "desc" : "asc";
+
+  const parsers = useMemo<TableParsers<F>>(
+    () => ({
+      search: optionalString,
+      sort_by: parseAsString.withDefault(defaultSortId),
+      sort_order: sortOrderParser(defaultSortOrder),
+      page: boundedInteger(1, MAX_PAGE, 1),
+      page_size: boundedInteger(1, maxPageSize, defaultPageSize),
+      ...filterParsers(filterColumns),
+    }),
+    [defaultSortId, defaultSortOrder, defaultPageSize, maxPageSize, filterColumns],
+  );
+  const urlKeys = useMemo(
+    () => resolveUrlKeys(filterColumns, keyPrefix, renamedKeys ?? {}),
+    [filterColumns, keyPrefix, renamedKeys],
+  );
+  const { values, filters, setValues } = useTableQueryStates(parsers, urlKeys);
+
+  const sortBy = sortFields.includes(values.sort_by) ? values.sort_by : defaultSortId;
+  const sortDesc = values.sort_order === "desc";
+  const sorting = useMemo<SortingState>(() => [{ id: sortBy, desc: sortDesc }], [sortBy, sortDesc]);
+
+  const pagination = useMemo<PaginationState>(
+    () => ({ pageIndex: values.page - 1, pageSize: values.page_size }),
+    [values.page, values.page_size],
+  );
+
+  const columnFilters = useMemo<ColumnFiltersState>(
+    () =>
+      filterColumns.flatMap((column) => {
+        const value = filters[filterStateKey(column)].trim();
+        return value ? [{ id: column, value }] : [];
+      }),
+    [filterColumns, filters],
+  );
+
+  const setSearch = useCallback(
+    (value: string) => {
+      void setValues({ search: value || null, page: null });
+    },
+    [setValues],
+  );
+
+  const onSortingChange = useCallback<OnChangeFn<SortingState>>(
+    (updaterOrValue) => {
+      const active = functionalUpdate(updaterOrValue, sorting)[0];
+      void setValues({
+        sort_by: active?.id ?? null,
+        sort_order: active ? toSortOrder(active) : null,
+        page: null,
+      });
+    },
+    [setValues, sorting],
+  );
+
+  const onPaginationChange = useCallback<OnChangeFn<PaginationState>>(
+    (updaterOrValue) => {
+      const next = functionalUpdate(updaterOrValue, pagination);
+      void setValues({ page: next.pageIndex + 1, page_size: next.pageSize });
+    },
+    [pagination, setValues],
+  );
+
+  const onColumnFiltersChange = useCallback<OnChangeFn<ColumnFiltersState>>(
+    (updaterOrValue) => {
+      const next = functionalUpdate(updaterOrValue, columnFilters);
+      void setValues({ ...filterUpdates(filterColumns, next), page: null });
+    },
+    [columnFilters, filterColumns, setValues],
+  );
+
+  return useMemo<UrlTableState>(
+    () => ({
+      search: values.search,
+      setSearch,
+      sorting,
+      onSortingChange,
+      pagination,
+      onPaginationChange,
+      columnFilters,
+      onColumnFiltersChange,
+    }),
+    [
+      values.search,
+      setSearch,
+      sorting,
+      onSortingChange,
+      pagination,
+      onPaginationChange,
+      columnFilters,
+      onColumnFiltersChange,
+    ],
+  );
+}
diff --git a/ui/litellm-dashboard/src/hooks/useUrlTab.test.tsx b/ui/litellm-dashboard/src/hooks/useUrlTab.test.tsx
new file mode 100644
index 00000000000..427d454ee2d
--- /dev/null
+++ b/ui/litellm-dashboard/src/hooks/useUrlTab.test.tsx
@@ -0,0 +1,100 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { NuqsTestingAdapter, type OnUrlUpdateFunction } from "nuqs/adapters/testing";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { useUrlTab } from "./useUrlTab";
+
+const TABS = ["chat", "compare", "compliance"] as const;
+type Tab = (typeof TABS)[number];
+
+interface RenderArgs {
+  searchParams?: string;
+  onUrlUpdate?: OnUrlUpdateFunction;
+  key?: string;
+}
+
+const initialProps: { values: readonly Tab[] } = { values: TABS };
+
+const renderUrlTab = ({ searchParams, onUrlUpdate, key }: RenderArgs = {}) =>
+  renderHook(({ values }: { values: readonly Tab[] }) => useUrlTab(values, "chat", key), {
+    initialProps,
+    wrapper: ({ children }: { children: ReactNode }) => (
+      <NuqsTestingAdapter
+        searchParams={searchParams}
+        onUrlUpdate={onUrlUpdate}
+        hasMemory
+        resetUrlUpdateQueueOnMount={false}
+      >
+        {children}
+      </NuqsTestingAdapter>
+    ),
+  });
+
+const lastUrlUpdate = (onUrlUpdate: ReturnType<typeof vi.fn<OnUrlUpdateFunction>>) =>
+  onUrlUpdate.mock.calls.at(-1)?.[0];
+
+describe("useUrlTab", () => {
+  it("reads the active tab from the URL", () => {
+    const { result } = renderUrlTab({ searchParams: "?tab=compare" });
+
+    expect(result.current[0]).toBe("compare");
+  });
+
+  it("resolves a URL value outside the allowed tabs to the fallback and drops it from the URL", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    const { result } = renderUrlTab({ searchParams: "?tab=settings&other=1", onUrlUpdate });
+
+    expect(result.current[0]).toBe("chat");
+    await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled());
+    expect(lastUrlUpdate(onUrlUpdate)?.searchParams.has("tab")).toBe(false);
+    expect(lastUrlUpdate(onUrlUpdate)?.searchParams.get("other")).toBe("1");
+  });
+
+  it("leaves a URL that names an allowed tab untouched", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    renderUrlTab({ searchParams: "?tab=compare", onUrlUpdate });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(onUrlUpdate).not.toHaveBeenCalled();
+  });
+
+  it("reads from the caller's key instead of the default one", () => {
+    const { result } = renderUrlTab({ searchParams: "?view=compliance&tab=compare", key: "view" });
+
+    expect(result.current[0]).toBe("compliance");
+  });
+
+  it("writes ?tab= with history replace when a tab is selected", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    const { result } = renderUrlTab({ onUrlUpdate });
+
+    act(() => result.current[1]("compare"));
+
+    await waitFor(() => expect(lastUrlUpdate(onUrlUpdate)?.searchParams.get("tab")).toBe("compare"));
+    expect(lastUrlUpdate(onUrlUpdate)?.options.history).toBe("replace");
+    expect(result.current[0]).toBe("compare");
+  });
+
+  it("removes the param when the fallback tab is selected", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    const { result } = renderUrlTab({ searchParams: "?tab=compare", onUrlUpdate });
+
+    act(() => result.current[1]("chat"));
+
+    await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled());
+    expect(lastUrlUpdate(onUrlUpdate)?.searchParams.has("tab")).toBe(false);
+    expect(result.current[0]).toBe("chat");
+  });
+
+  it("falls back and clears the param when the current tab is no longer among the allowed values", async () => {
+    const onUrlUpdate = vi.fn<OnUrlUpdateFunction>();
+    const { result, rerender } = renderUrlTab({ searchParams: "?tab=compliance", onUrlUpdate });
+    expect(result.current[0]).toBe("compliance");
+
+    rerender({ values: ["chat", "compare"] });
+
+    expect(result.current[0]).toBe("chat");
+    await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled());
+    expect(lastUrlUpdate(onUrlUpdate)?.searchParams.has("tab")).toBe(false);
+  });
+});
diff --git a/ui/litellm-dashboard/src/hooks/useUrlTab.ts b/ui/litellm-dashboard/src/hooks/useUrlTab.ts
new file mode 100644
index 00000000000..2f3d705c610
--- /dev/null
+++ b/ui/litellm-dashboard/src/hooks/useUrlTab.ts
@@ -0,0 +1,12 @@
+import { parseAsString, useQueryState } from "nuqs";
+import { useCallback, useEffect } from "react";
+
+export function useUrlTab<T extends string>(values: readonly T[], fallback: T, key = "tab"): [T, (tab: T) => void] {
+  const [urlTab, setUrlTab] = useQueryState(key, parseAsString.withDefault(fallback));
+  const tab = values.find((value) => value === urlTab) ?? fallback;
+  useEffect(() => {
+    if (urlTab !== tab) void setUrlTab(null);
+  }, [urlTab, tab, setUrlTab]);
+  const setTab = useCallback((next: T) => void setUrlTab(next), [setUrlTab]);
+  return [tab, setTab];
+}
diff --git a/ui/litellm-dashboard/src/utils/tabRoutes.test.ts b/ui/litellm-dashboard/src/utils/tabRoutes.test.ts
deleted file mode 100644
index 402be55c33a..00000000000
--- a/ui/litellm-dashboard/src/utils/tabRoutes.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-/* @vitest-environment jsdom */
-import { describe, expect, it, vi } from "vitest";
-
-vi.mock("@/components/networking", () => ({ serverRootPath: "" }));
-
-import { createTabRoutes } from "./tabRoutes";
-
-const routes = createTabRoutes("logs", ["audit", "deleted-keys", "deleted-teams"] as const);
-
-describe("createTabRoutes.slugFromPathname", () => {
-  it("returns empty string for the base path with or without a trailing slash", () => {
-    expect(routes.slugFromPathname("/logs")).toBe("");
-    expect(routes.slugFromPathname("/logs/")).toBe("");
-  });
-
-  it("extracts the tab slug from dev and proxy-mounted (/ui) paths", () => {
-    expect(routes.slugFromPathname("/logs/audit")).toBe("audit");
-    expect(routes.slugFromPathname("/ui/logs/deleted-teams/")).toBe("deleted-teams");
-  });
-
-  it("returns the raw segment for an unknown tab so the caller can redirect to base", () => {
-    expect(routes.slugFromPathname("/ui/logs/bogus")).toBe("bogus");
-  });
-
-  it("returns empty string when the base segment is not in the path", () => {
-    expect(routes.slugFromPathname("/teams")).toBe("");
-  });
-});
-
-describe("createTabRoutes.tabHref", () => {
-  it("builds the trailing-slash base href for the empty slug", () => {
-    expect(routes.tabHref("")).toBe("/ui/logs/");
-  });
-
-  it("builds a trailing-slash href for every tab slug (required by static export)", () => {
-    for (const slug of routes.slugs) {
-      expect(routes.tabHref(slug)).toBe(`/ui/logs/${slug}/`);
-    }
-  });
-});
-
-describe("createTabRoutes metadata", () => {
-  it("preserves the base segment and slug tuple", () => {
-    expect(routes.baseSegment).toBe("logs");
-    expect(routes.slugs).toEqual(["audit", "deleted-keys", "deleted-teams"]);
-  });
-});
diff --git a/ui/litellm-dashboard/src/utils/tabRoutes.ts b/ui/litellm-dashboard/src/utils/tabRoutes.ts
deleted file mode 100644
index 4af2b983cba..00000000000
--- a/ui/litellm-dashboard/src/utils/tabRoutes.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { uiHref } from "@/utils/uiHref";
-
-export interface TabRoutes<Slug extends string> {
-  baseSegment: string;
-  slugs: readonly Slug[];
-  tabHref: (slug: string) => string;
-  slugFromPathname: (pathname: string) => string;
-}
-
-export function createTabRoutes<Slug extends string>(baseSegment: string, slugs: readonly Slug[]): TabRoutes<Slug> {
-  const tabHref = (slug: string): string => {
-    const base = uiHref(baseSegment);
-    return slug ? `${base}/${slug}/` : `${base}/`;
-  };
-
-  const slugFromPathname = (pathname: string): string => {
-    const parts = pathname.split("/").filter(Boolean);
-    const idx = parts.indexOf(baseSegment);
-    if (idx === -1) {
-      return "";
-    }
-    return parts[idx + 1] ?? "";
-  };
-
-  return { baseSegment, slugs, tabHref, slugFromPathname };
-}

From 4d30bbce453a06e850cbf6007a42dd7e00803380 Mon Sep 17 00:00:00 2001
From: ryan-crabbe-berri <ryan@berri.ai>
Date: Wed, 16 Sep 2026 09:34:05 -0700
Subject: [PATCH 73/76] fix(ui): keep controlled client-side table pages across
 data reloads

Controlled client-mode DataTables no longer let TanStack reset the page index when rows change, since the owner of the pagination state decides the page. Once rows settle, a page past the end snaps back to the last page, matching server mode
---
 .../shared/DataTable/DataTable.test.tsx       | 73 +++++++++++++++++++
 .../components/shared/DataTable/DataTable.tsx | 34 ++++++++-
 2 files changed, 104 insertions(+), 3 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx
index 336fc43d695..a7e4befa6ac 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.test.tsx
@@ -357,6 +357,79 @@ describe("DataTable pagination", () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
+  type ClientPageHarnessProps = {
+    data: Person[];
+    isLoading?: boolean;
+    initialPageIndex: number;
+    onChange: (next: PaginationState) => void;
+  };
+
+  function ClientPageHarness({ data, isLoading = false, initialPageIndex, onChange }: ClientPageHarnessProps) {
+    const [pagination, setPagination] = useState<PaginationState>({ pageIndex: initialPageIndex, pageSize: 2 });
+    const handleChange: OnChangeFn<PaginationState> = (updater) => {
+      const next = typeof updater === "function" ? updater(pagination) : updater;
+      onChange(next);
+      setPagination(next);
+    };
+    return (
+      <DataTable
+        data={data}
+        columns={nameCellColumns}
+        paginationMode="client"
+        pageSizeOptions={[2]}
+        pagination={pagination}
+        onPaginationChange={handleChange}
+        isLoading={isLoading}
+      />
+    );
+  }
+
+  it("client mode keeps a controlled page when rows arrive after loading and when they are refetched", async () => {
+    const onChange = vi.fn();
+    const { rerender } = render(<ClientPageHarness data={[]} isLoading initialPageIndex={1} onChange={onChange} />);
+
+    rerender(<ClientPageHarness data={fivePeople} initialPageIndex={1} onChange={onChange} />);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(names()).toEqual(["P2", "P3"]);
+
+    rerender(<ClientPageHarness data={[...fivePeople]} initialPageIndex={1} onChange={onChange} />);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(names()).toEqual(["P2", "P3"]);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("client mode snaps a controlled page past the end back to the last page", async () => {
+    const onChange = vi.fn();
+    render(<ClientPageHarness data={fivePeople} initialPageIndex={5} onChange={onChange} />);
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith({ pageIndex: 2, pageSize: 2 }));
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(names()).toEqual(["P4"]);
+  });
+
+  it("client mode leaves a controlled page alone while there are no rows to page through", async () => {
+    const onChange = vi.fn();
+    render(<ClientPageHarness data={[]} initialPageIndex={3} onChange={onChange} />);
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("client mode without a controlled page still returns to the first page when the rows change", async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(
+      <DataTable data={fivePeople} columns={nameCellColumns} paginationMode="client" pageSizeOptions={[2]} />,
+    );
+
+    await user.click(screen.getByTestId("pagination-next"));
+    expect(names()).toEqual(["P2", "P3"]);
+
+    rerender(
+      <DataTable data={[...fivePeople]} columns={nameCellColumns} paginationMode="client" pageSizeOptions={[2]} />,
+    );
+    await waitFor(() => expect(names()).toEqual(["P0", "P1"]));
+  });
+
   it("server mode resumes clamping once the error clears and a real rowCount arrives", async () => {
     const onChange = vi.fn();
     const { rerender } = render(<ServerPageHarness rowCount={0} isError initialPageIndex={2} onChange={onChange} />);
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx
index e0f57ae1052..340f8d4f44f 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/DataTable.tsx
@@ -425,7 +425,7 @@ function useControllable<T>(
   return { value: internal, onChange: setInternal };
 }
 
-function useServerPageClamp(
+function usePageClamp(
   active: boolean,
   rowCount: number | undefined,
   pagination: { value: PaginationState; onChange: OnChangeFn<PaginationState> },
@@ -484,7 +484,6 @@ function useDataTableInstance<TData extends RowData, TValue>(
     pageIndex: 0,
     pageSize: pageSizeOptions[0] ?? 25,
   });
-  useServerPageClamp(paginationMode === "server" && !isLoading && !isError, rowCount, paginationState);
   const filterState = useControllable<ColumnFiltersState>(
     columnFilters,
     onColumnFiltersChange,
@@ -536,9 +535,38 @@ function useDataTableInstance<TData extends RowData, TValue>(
     ...(getRowId !== undefined ? { getRowId } : {}),
     ...(enableRowSelection !== undefined ? { enableRowSelection } : {}),
     ...(paginationMode === "server" && rowCount !== undefined ? { rowCount } : {}),
+    autoResetPageIndex: pagination === undefined && paginationMode !== "server",
   };
 
-  return useReactTable(tableOptions);
+  const table = useReactTable(tableOptions);
+  const clampOptions: SettledPageClampOptions = {
+    paginationMode,
+    controlled: pagination !== undefined,
+    settled: !isLoading && !isError,
+    rowCount,
+    pagination: paginationState,
+  };
+  useSettledPageClamp(table, clampOptions);
+  return table;
+}
+
+type SettledPageClampOptions = {
+  paginationMode: PaginationMode;
+  controlled: boolean;
+  settled: boolean;
+  rowCount: number | undefined;
+  pagination: { value: PaginationState; onChange: OnChangeFn<PaginationState> };
+};
+
+function useSettledPageClamp<TData extends RowData>(table: Table<TData>, options: SettledPageClampOptions): void {
+  const { paginationMode, controlled, settled, rowCount, pagination } = options;
+  const clientRowCount = paginationMode === "client" ? table.getPrePaginationRowModel().rows.length : 0;
+  const clientPageIsClampable = paginationMode === "client" && controlled && clientRowCount > 0;
+  usePageClamp(
+    settled && (paginationMode === "server" || clientPageIsClampable),
+    paginationMode === "server" ? rowCount : clientRowCount,
+    pagination,
+  );
 }
 
 export function DataTable<TData extends RowData, TValue>(props: DataTableProps<TData, TValue>) {

From adc937c4931021c68864ed28014d51b851ecaade Mon Sep 17 00:00:00 2001
From: ryan-crabbe-berri <ryan@berri.ai>
Date: Wed, 16 Sep 2026 12:50:08 -0700
Subject: [PATCH 74/76] fix(ui): read persisted column visibility from storage
 instead of a mounted copy

usePersistedColumnVisibility kept a useState copy seeded once at mount, so a later tableId or defaults change showed the old table's columns and saved them under the new key. It now reads localStorage through useSyncExternalStore, keeping only writes that storage refused in memory, so the hook has no copy to go stale. Stored choices are layered over the defaults on every read, and changes saved in another tab show up.
---
 .../usePersistedColumnVisibility.test.tsx     | 74 ++++++++++++++++++-
 .../DataTable/usePersistedColumnVisibility.ts | 54 +++++++++++---
 2 files changed, 112 insertions(+), 16 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
index 8d2e0f61f54..fbfb71e5bc2 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
@@ -1,3 +1,4 @@
+import type { VisibilityState } from "@tanstack/react-table";
 import { act, renderHook } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -10,6 +11,9 @@ const stored = (tableId: string): unknown => {
   return raw === null ? null : JSON.parse(raw);
 };
 
+const showEveryColumn = (previous: VisibilityState): VisibilityState =>
+  Object.fromEntries(Object.keys(previous).map((column) => [column, true]));
+
 describe("usePersistedColumnVisibility", () => {
   beforeEach(() => {
     localStorage.clear();
@@ -55,6 +59,15 @@ describe("usePersistedColumnVisibility", () => {
     expect(stored("keys")).toEqual({ email: false, name: false });
   });
 
+  it("hands a function updater the default-hidden columns, so showing every column sticks", () => {
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys", { spend: false }));
+
+    act(() => result.current.onColumnVisibilityChange(showEveryColumn));
+
+    expect(result.current.columnVisibility).toEqual({ spend: true });
+    expect(stored("keys")).toEqual({ spend: true });
+  });
+
   it.each([
     ["truncated JSON", '{"email":fal'],
     ["a JSON scalar", "42"],
@@ -80,19 +93,72 @@ describe("usePersistedColumnVisibility", () => {
     expect(stored("teams")).toBeNull();
   });
 
+  it("reads and writes the new table's columns after the tableId changes", () => {
+    localStorage.setItem(keyFor("keys"), JSON.stringify({ email: false }));
+    localStorage.setItem(keyFor("teams"), JSON.stringify({ spend: false }));
+    const { result, rerender } = renderHook(({ tableId }) => usePersistedColumnVisibility(tableId), {
+      initialProps: { tableId: "keys" },
+    });
+
+    rerender({ tableId: "teams" });
+    expect(result.current.columnVisibility).toEqual({ spend: false });
+
+    act(() => result.current.onColumnVisibilityChange((previous) => ({ ...previous, name: false })));
+    expect(stored("teams")).toEqual({ spend: false, name: false });
+    expect(stored("keys")).toEqual({ email: false });
+  });
+
+  it("applies new defaults passed after mount", () => {
+    const { result, rerender } = renderHook(({ defaults }) => usePersistedColumnVisibility("keys", defaults), {
+      initialProps: { defaults: { spend: false } },
+    });
+
+    rerender({ defaults: { name: false } });
+
+    expect(result.current.columnVisibility).toEqual({ name: false });
+  });
+
+  it("shows a change another tab saved for the same table", () => {
+    const { result } = renderHook(() => usePersistedColumnVisibility("keys"));
+
+    act(() => {
+      localStorage.setItem(keyFor("keys"), JSON.stringify({ email: false }));
+      window.dispatchEvent(new StorageEvent("storage", { key: keyFor("keys") }));
+    });
+
+    expect(result.current.columnVisibility).toEqual({ email: false });
+  });
+
+  it("keeps a toggle that storage refused, and saves the next one once storage accepts it", () => {
+    localStorage.setItem(keyFor("full"), JSON.stringify({ spend: false }));
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(Storage.prototype, "setItem").mockImplementationOnce(() => {
+      throw new Error("QuotaExceededError");
+    });
+    const { result } = renderHook(() => usePersistedColumnVisibility("full"));
+
+    act(() => result.current.onColumnVisibilityChange({ email: false }));
+    expect(result.current.columnVisibility).toEqual({ email: false });
+    expect(stored("full")).toEqual({ spend: false });
+
+    act(() => result.current.onColumnVisibilityChange({ name: false }));
+    expect(result.current.columnVisibility).toEqual({ name: false });
+    expect(stored("full")).toEqual({ name: false });
+  });
+
   it("returns the defaults without throwing when storage is unavailable", () => {
     vi.spyOn(console, "warn").mockImplementation(() => {});
     vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
       throw new Error("SecurityError");
     });
     vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
-      throw new Error("QuotaExceededError");
+      throw new Error("SecurityError");
     });
 
-    const { result } = renderHook(() => usePersistedColumnVisibility("keys", { spend: false }));
+    const { result } = renderHook(() => usePersistedColumnVisibility("blocked", { spend: false }));
     expect(result.current.columnVisibility).toEqual({ spend: false });
 
-    act(() => result.current.onColumnVisibilityChange({ email: false }));
-    expect(result.current.columnVisibility).toEqual({ email: false });
+    act(() => result.current.onColumnVisibilityChange((previous) => ({ ...previous, email: false })));
+    expect(result.current.columnVisibility).toEqual({ spend: false, email: false });
   });
 });
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
index b56ae13d63b..7fffc50b381 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
@@ -1,16 +1,46 @@
 import type { OnChangeFn, VisibilityState } from "@tanstack/react-table";
-import { useCallback, useState } from "react";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
 
-import { getLocalStorageItem, setLocalStorageItem } from "@/utils/localStorageUtils";
+import {
+  LOCAL_STORAGE_EVENT,
+  emitLocalStorageChange,
+  getLocalStorageItem,
+  setLocalStorageItem,
+} from "@/utils/localStorageUtils";
 
 const STORAGE_KEY_PREFIX = "litellm_table_columns_";
 
 const EMPTY_VISIBILITY: VisibilityState = {};
 
+const unsavedWrites = new Map<string, string>();
+
 function storageKey(tableId: string): string {
   return `${STORAGE_KEY_PREFIX}${tableId}`;
 }
 
+function subscribe(onChange: () => void): () => void {
+  window.addEventListener("storage", onChange);
+  window.addEventListener(LOCAL_STORAGE_EVENT, onChange);
+  return () => {
+    window.removeEventListener("storage", onChange);
+    window.removeEventListener(LOCAL_STORAGE_EVENT, onChange);
+  };
+}
+
+function readRaw(key: string): string | null {
+  return unsavedWrites.get(key) ?? getLocalStorageItem(key);
+}
+
+function writeRaw(key: string, raw: string): void {
+  setLocalStorageItem(key, raw);
+  if (getLocalStorageItem(key) === raw) {
+    unsavedWrites.delete(key);
+  } else {
+    unsavedWrites.set(key, raw);
+  }
+  emitLocalStorageChange(key);
+}
+
 function isVisibilityState(value: unknown): value is VisibilityState {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return false;
@@ -18,8 +48,7 @@ function isVisibilityState(value: unknown): value is VisibilityState {
   return Object.values(value).every((visible) => typeof visible === "boolean");
 }
 
-function readStoredVisibility(tableId: string, defaults: VisibilityState): VisibilityState {
-  const raw = getLocalStorageItem(storageKey(tableId));
+function parseVisibility(raw: string | null, defaults: VisibilityState): VisibilityState {
   if (raw === null) {
     return defaults;
   }
@@ -35,19 +64,20 @@ export function usePersistedColumnVisibility(
   tableId: string,
   defaults: VisibilityState = EMPTY_VISIBILITY,
 ): { columnVisibility: VisibilityState; onColumnVisibilityChange: OnChangeFn<VisibilityState> } {
-  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>(() =>
-    readStoredVisibility(tableId, defaults),
+  const key = storageKey(tableId);
+  const raw = useSyncExternalStore(
+    subscribe,
+    () => readRaw(key),
+    () => null,
   );
+  const columnVisibility = useMemo(() => parseVisibility(raw, defaults), [raw, defaults]);
 
   const onColumnVisibilityChange = useCallback<OnChangeFn<VisibilityState>>(
     (updater) => {
-      setColumnVisibility((previous) => {
-        const next = typeof updater === "function" ? updater(previous) : updater;
-        setLocalStorageItem(storageKey(tableId), JSON.stringify(next));
-        return next;
-      });
+      const next = typeof updater === "function" ? updater(parseVisibility(readRaw(key), defaults)) : updater;
+      writeRaw(key, JSON.stringify(next));
     },
-    [tableId],
+    [key, defaults],
   );
 
   return { columnVisibility, onColumnVisibilityChange };

From d29753c52172b619a2ad7702b34fe1e09b45a6f5 Mon Sep 17 00:00:00 2001
From: ryan-crabbe-berri <ryan@berri.ai>
Date: Wed, 16 Sep 2026 15:43:21 -0700
Subject: [PATCH 75/76] fix(ui): let another tab's column save replace a toggle
 this tab could not save

A column toggle that localStorage refused was kept in memory and read ahead of storage, so a later save from another tab stayed hidden until this tab saved again. A storage event now drops the in-memory copy for its key, or all of them when another tab clears storage
---
 .../usePersistedColumnVisibility.test.tsx     | 32 ++++++++++++++++++-
 .../DataTable/usePersistedColumnVisibility.ts | 16 ++++++++--
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
index fbfb71e5bc2..35bba906afc 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.test.tsx
@@ -109,8 +109,9 @@ describe("usePersistedColumnVisibility", () => {
   });
 
   it("applies new defaults passed after mount", () => {
+    const initialProps: { defaults: VisibilityState } = { defaults: { spend: false } };
     const { result, rerender } = renderHook(({ defaults }) => usePersistedColumnVisibility("keys", defaults), {
-      initialProps: { defaults: { spend: false } },
+      initialProps,
     });
 
     rerender({ defaults: { name: false } });
@@ -146,6 +147,35 @@ describe("usePersistedColumnVisibility", () => {
     expect(stored("full")).toEqual({ name: false });
   });
 
+  it("shows another tab's save over a toggle this tab could not save", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(Storage.prototype, "setItem").mockImplementationOnce(() => {
+      throw new Error("QuotaExceededError");
+    });
+    const { result } = renderHook(() => usePersistedColumnVisibility("shadowed"));
+    act(() => result.current.onColumnVisibilityChange({ email: false }));
+
+    act(() => {
+      localStorage.setItem(keyFor("shadowed"), JSON.stringify({ name: false }));
+      window.dispatchEvent(new StorageEvent("storage", { key: keyFor("shadowed") }));
+    });
+
+    expect(result.current.columnVisibility).toEqual({ name: false });
+  });
+
+  it("drops a toggle this tab could not save once another tab clears storage", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(Storage.prototype, "setItem").mockImplementationOnce(() => {
+      throw new Error("QuotaExceededError");
+    });
+    const { result } = renderHook(() => usePersistedColumnVisibility("cleared", { spend: false }));
+    act(() => result.current.onColumnVisibilityChange({ email: false }));
+
+    act(() => window.dispatchEvent(new StorageEvent("storage", { key: null })));
+
+    expect(result.current.columnVisibility).toEqual({ spend: false });
+  });
+
   it("returns the defaults without throwing when storage is unavailable", () => {
     vi.spyOn(console, "warn").mockImplementation(() => {});
     vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
diff --git a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
index 7fffc50b381..3cbf5c2a000 100644
--- a/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
+++ b/ui/litellm-dashboard/src/components/shared/DataTable/usePersistedColumnVisibility.ts
@@ -18,11 +18,23 @@ function storageKey(tableId: string): string {
   return `${STORAGE_KEY_PREFIX}${tableId}`;
 }
 
+function forgetUnsavedWrite(event: StorageEvent): void {
+  if (event.key === null) {
+    unsavedWrites.clear();
+    return;
+  }
+  unsavedWrites.delete(event.key);
+}
+
 function subscribe(onChange: () => void): () => void {
-  window.addEventListener("storage", onChange);
+  const onStorage = (event: StorageEvent): void => {
+    forgetUnsavedWrite(event);
+    onChange();
+  };
+  window.addEventListener("storage", onStorage);
   window.addEventListener(LOCAL_STORAGE_EVENT, onChange);
   return () => {
-    window.removeEventListener("storage", onChange);
+    window.removeEventListener("storage", onStorage);
     window.removeEventListener(LOCAL_STORAGE_EVENT, onChange);
   };
 }

From afb28540bbd3868dcebd83e8e7c7347c7611abfa Mon Sep 17 00:00:00 2001
From: Yuneng Jiang <yuneng@berri.ai>
Date: Wed, 16 Sep 2026 16:01:32 -0700
Subject: [PATCH 76/76] fix(e2e): keep the CLI determinism test out of the
 in-cluster suite

It drives the real CLI for several seconds. The edge stamps every
upstream call with PYTEST_CURRENT_TEST, a process-global that names
whichever test the worker is in when the call arrives rather than the one
that made it, so a test that holds a worker that long collects other
tests' in-flight calls. Build 234's key report credits this test with 20
Bedrock and 7 Anthropic misses, and it makes no provider call at all.

Those misattributed calls take the wrong test id into the cache key and
write recordings under it, so the test was polluting the shared corpus it
exists to protect.

Deselected unless E2E_CLI_DETERMINISM is set, the same opt-in shape the
managed-files, prompt-caching and redis-chaos markers already use. The
attribution bug itself is older than this branch and is reported, not
fixed here.
---
 .../_driver_unit_tests/test_request_determinism.py         | 2 ++
 tests/e2e/conftest.py                                      | 7 +++++++
 tests/e2e/e2e_config.py                                    | 1 +
 tests/e2e/pytest.ini                                       | 1 +
 4 files changed, 11 insertions(+)

diff --git a/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py b/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
index 5046f35c73b..b7d330b7da6 100644
--- a/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
+++ b/tests/e2e/claude_code/_driver_unit_tests/test_request_determinism.py
@@ -36,6 +36,8 @@ import pytest
 from claude_code.cli_driver import _FIXED_CLI_USER_ID, _seed_cli_identity, _stable_cli_state, run_claude
 from claude_code.rate_limiter import RateLimiter
 
+pytestmark = pytest.mark.cli_determinism
+
 _STUB_REPLY = {
     "id": "msg_stub",
     "type": "message",
diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py
index 430e16525d5..ac4cfb71407 100644
--- a/tests/e2e/conftest.py
+++ b/tests/e2e/conftest.py
@@ -23,6 +23,7 @@ from typing import Final
 import pytest
 import requests
 from e2e_config import (
+    CLI_DETERMINISM_OPT_IN_ENV,
     CONTROL_PLANE_BASE_URL,
     FIXTURE_DIR,
     FIXTURE_MODE_RAW,
@@ -53,6 +54,7 @@ OPT_IN_MARKERS: Final = MappingProxyType(
         "managed_files": MANAGED_FILES_OPT_IN_ENV,
         "prompt_caching_stack": PROMPT_CACHING_OPT_IN_ENV,
         "redis_chaos": REDIS_CHAOS_OPT_IN_ENV,
+        "cli_determinism": CLI_DETERMINISM_OPT_IN_ENV,
     }
 )
 
@@ -120,6 +122,11 @@ def pytest_configure(config: pytest.Config) -> None:
         "prompt_caching_stack: needs a proxy running with router_settings.optional_pre_call_checks including "
         "prompt_caching; deselected unless E2E_PROMPT_CACHING_STACK is set",
     )
+    config.addinivalue_line(
+        "markers",
+        "cli_determinism: drives the real claude CLI for several seconds, which widens the window in which "
+        "another test's in-flight upstream call is attributed to it; deselected unless E2E_CLI_DETERMINISM is set",
+    )
     config.addinivalue_line(
         "markers",
         "redis_chaos: load test that pauses the proxy's Redis outright mid-run; needs a proxy booted from "
diff --git a/tests/e2e/e2e_config.py b/tests/e2e/e2e_config.py
index 896cb3e7efe..82ddb09f7f5 100644
--- a/tests/e2e/e2e_config.py
+++ b/tests/e2e/e2e_config.py
@@ -145,6 +145,7 @@ WEEKLY_ANOMALY_OPT_IN_ENV = "E2E_WEEKLY_ANOMALY"
 MANAGED_FILES_OPT_IN_ENV = "E2E_MANAGED_FILES_STACK"
 PROMPT_CACHING_OPT_IN_ENV = "E2E_PROMPT_CACHING_STACK"
 REDIS_CHAOS_OPT_IN_ENV = "E2E_REDIS_CHAOS"
+CLI_DETERMINISM_OPT_IN_ENV = "E2E_CLI_DETERMINISM"
 ANOMALY_SESSIONS = int(os.environ.get("E2E_ANOMALY_SESSIONS", "6"))
 ANOMALY_TURNS_PER_SESSION = int(os.environ.get("E2E_ANOMALY_TURNS_PER_SESSION", "6"))
 ANOMALY_TURN_ATTEMPTS = int(os.environ.get("E2E_ANOMALY_TURN_ATTEMPTS", "3"))
diff --git a/tests/e2e/pytest.ini b/tests/e2e/pytest.ini
index 1fdd3bd28ad..f6d23a3ec12 100644
--- a/tests/e2e/pytest.ini
+++ b/tests/e2e/pytest.ini
@@ -10,4 +10,5 @@ markers =
     weekly: real-provider anomaly load test that spends real money; deselected unless E2E_WEEKLY_ANOMALY is set
     managed_files: needs a proxy running with require_managed_files enabled; deselected unless E2E_MANAGED_FILES_STACK is set
     prompt_caching_stack: needs a proxy running with router_settings.optional_pre_call_checks including prompt_caching; deselected unless E2E_PROMPT_CACHING_STACK is set
+    cli_determinism: drives the real claude CLI for several seconds, which widens the window in which another test's in-flight upstream call is attributed to it; deselected unless E2E_CLI_DETERMINISM is set
     redis_chaos: load test that pauses the proxy's Redis outright mid-run; needs a proxy booted from gateway/redis_chaos_ci_config.yml on the same host, and is deselected unless E2E_REDIS_CHAOS is set