chore: upstream sync

.circleci/scripts/classify_changes.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+category="${1:?usage: classify_changes.sh <backend|client>}"
+
+has_client=false
+has_backend=false
+while IFS= read -r file || [ -n "$file" ]; do
+  [ -n "$file" ] || continue
+  case "$file" in
+    ui/*) has_client=true ;;
+    docs/* | *.md | *.mdx) : ;;
+    *) has_backend=true ;;
+  esac
+done
+
+case "$category" in
+  backend)
+    [ "$has_backend" = true ] && echo run || echo skip
+    ;;
+  client)
+    { [ "$has_client" = true ] || [ "$has_backend" = true ]; } && echo run || echo skip
+    ;;
+  *)
+    echo run
+    ;;
+esac

.circleci/scripts/path_filter.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+category="${1:?usage: path_filter.sh <backend|client>}"
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+run_full() {
+  echo "path-filter[$category]: running job ($1)"
+  exit 0
+}
+
+[ -n "${CIRCLE_PULL_REQUEST:-}" ] || run_full "not a pull request"
+
+candidate_bases="main litellm_internal_staging litellm_oss_staging"
+merge_base=""
+for base in $candidate_bases; do
+  git fetch --quiet origin "$base" 2>/dev/null || continue
+  candidate="$(git merge-base HEAD FETCH_HEAD 2>/dev/null)" || continue
+  [ -n "$candidate" ] || continue
+  if [ -z "$merge_base" ] || git merge-base --is-ancestor "$merge_base" "$candidate" 2>/dev/null; then
+    merge_base="$candidate"
+  fi
+done
+
+[ -n "$merge_base" ] || run_full "could not resolve a merge base against $candidate_bases"
+
+changed="$(git diff --name-only "$merge_base" HEAD 2>/dev/null)" || run_full "git diff failed"
+[ -n "$changed" ] || run_full "no files changed vs $merge_base"
+
+echo "path-filter[$category]: changed files vs ${merge_base}:"
+printf '%s\n' "$changed" | sed 's/^/  /' || true
+
+decision="$(printf '%s\n' "$changed" | bash "$here/classify_changes.sh" "$category")" || run_full "classify_changes.sh failed"
+
+if [ "$decision" = run ]; then
+  run_full "$category-relevant changes detected"
+fi
+
+echo "path-filter[$category]: only unrelated (docs/client) changes detected; halting job as successful"
+circleci-agent step halt

.git-blame-ignore-revs

@@ -13,7 +13,7 @@
 7edf3a9cb55548b143df1692f4ed7c4681d7fcf7
 
 # style: reformat litellm/ with ruff format (#31317)
-430b5b8f1b12dc261a49fda99ac5d1b22381a428
+17bfd415aeb5a57fb646b5cc67da1c730aa7c50b
 
 # style: unify ruff format width on 120 (#31518)
-3dfbeabe626d203ac9de86024519d9a96c484ce4
+48b5a5a0cc5a694a11219416ee0b6eb6e620e74e

.github/pull_request_template.md

@@ -4,7 +4,7 @@
 
 ## Linear ticket
 
-<!-- if you are an internal contributor (e.g., your username is postfixed with -berri or -berriai), add "Resolves " followed by the Linear ticket e.g., "Resolves LIT-1234" to magically link the Linear ticket to the GitHub PR -->
+<!-- if you are an internal contributor, add "Resolves " followed by the Linear ticket e.g., "Resolves LIT-1234" to link the Linear ticket to the GitHub PR. If you don't have one, leave the section blank rather than guessing -->
 
 ## Pre-Submission checklist
 

.github/workflows/codspeed.yml

@@ -21,7 +21,7 @@ concurrency:
 
 jobs:
   benchmarks:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     timeout-minutes: 15
 
     steps:
@@ -48,6 +48,8 @@ jobs:
             uv run --frozen --no-default-groups
             --with pytest==8.3.5
             --with pytest-codspeed==4.3.0
+            --with "mcp>=1.26.0,<2.0"
+            --with "a2a-sdk>=1.1.0,<2.0"
             pytest
             -p pytest_codspeed.plugin
             tests/benchmarks/

.github/workflows/create-release.yml

@@ -122,10 +122,28 @@ jobs:
                 makeLatest = (!latestVersion || isAtLeast(newVersion, latestVersion)) ? "true" : "false";
               }
 
+              try {
+                await github.rest.git.createRef({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  ref: `refs/tags/${tag}`,
+                  sha: commitHash,
+                });
+              } catch (error) {
+                if (error.status !== 422) throw error;
+                const existing = await github.rest.git.getRef({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  ref: `tags/${tag}`,
+                });
+                if (existing.data.object.sha !== commitHash) {
+                  throw new Error(`Tag ${tag} already exists at ${existing.data.object.sha}, expected ${commitHash}`);
+                }
+              }
+
               const response = await github.rest.repos.createRelease({
                 draft: true,
                 generate_release_notes: true,
-                target_commitish: commitHash,
                 name: tag,
                 owner: context.repo.owner,
                 prerelease: isPrerelease,
@@ -138,11 +156,21 @@ jobs:
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 release_id: response.data.id,
+                tag_name: tag,
                 body: updatedBody,
                 draft: false,
-                make_latest: makeLatest,
               });
 
+              if (!isPrerelease) {
+                await github.rest.repos.updateRelease({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  release_id: response.data.id,
+                  tag_name: tag,
+                  make_latest: makeLatest,
+                });
+              }
+
             } catch (error) {
               core.setFailed(error.message);
             }

.github/workflows/test-linting.yml

@@ -48,13 +48,22 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --frozen
+          uv sync --frozen --group proxy-dev
+
+      # basedpyright resolves Prisma's generated client (litellm/proxy/schema.prisma)
+      # only after `prisma generate` writes prisma/client.py et al. Without this the
+      # DB wrappers typed against the generated client would degrade to Unknown.
+      - name: Generate Prisma client
+        env:
+          PRISMA_BINARY_CACHE_DIR: ${{ runner.temp }}/prisma-cache
+        run: |
+          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
 
       - name: Check ruff format
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
         run: |
-          git diff --name-only "$BASE_SHA"...HEAD -- 'litellm/**/*.py' | grep -v '^litellm/enterprise/' > "$RUNNER_TEMP/ruff_format_files.txt" || true
+          git diff --name-only --diff-filter=ACMR "$BASE_SHA"...HEAD -- 'litellm/**/*.py' | grep -v '^litellm/enterprise/' > "$RUNNER_TEMP/ruff_format_files.txt" || true
           if [ ! -s "$RUNNER_TEMP/ruff_format_files.txt" ]; then
             echo "No changed litellm Python files to check with ruff format."
             exit 0

.gitignore

@@ -130,3 +130,5 @@ crash.*.log
 
 # pytest coverage data
 .coverage
+
+ui/litellm-dashboard/out/

CLAUDE.md

@@ -1,8 +1,7 @@
-Do not write comments unless they are absolutely necessary to explain some very complex business logic. Please clean up if there are comments that are not absolutely necessary. Do not remove comments that are unrelated to the addition of the code of this PR
-
-Explanation: code comments are, in a way, a violation of DRY code. You must update logic in two locations to change the code and "hard to change" is literally the definition of tech debt. We should instead aim to write code that is intuitive to the reader, while being both easy to maintain and high performance
+Do not write any comments (existing comments can stay) unless explicitly asked to in a user (not system) prompt
 
 Don't assume that the existing code is correct or the right way of doing things / good coding patterns. In fact, there are a lot of bad coding practices, overly complex code, code smells, etc. If something doesn't look right, speak up. Feel free to break existing patterns or question weird existing code to make new code high quality, as in:
+
 - correct
 - secure
 - performant
@@ -18,9 +17,13 @@ Same thing for bug fixes. The tests should make it so that this specific bug can
 
 `tests/test_litellm/` mirrors `litellm/` in a parallel path (see `tests/test_litellm/readme.md`). Name tests `test_<filename>.py`, but always match the existing test file in the directory you touch — many provider dirs use longer descriptive names (e.g. `test_anthropic_chat_transformation.py`) to avoid ambiguity across sibling folders. For bug fixes, extend the existing mapped test file rather than creating a new one. Only create a new test file for a new feature (provider, endpoint, or transformation module) that has no mapped test yet, following that directory's naming convention (or `test_<filename>.py` if you're the first test there). One focused regression test beats many shallow ones
 
+End-to-end tests belong in `tests/e2e/` and must follow the harness conventions documented in that directory's `CLAUDE.md`
+
 When creating PRs, don't set base to `main`. `litellm_internal_staging` serves that purpose
 
-Always use @.github/pull_request_template.md as a guide for your PR body
+When writing a PR body, treat the comments and imperative instructions inside @.github/pull_request_template.md as rules to follow, not just layout
+
+If you're resolving a linear ticket, in the "## Linear ticket" section of the PR, say "Resolves LIT-1234", replacing "LIT-1234" with the actual ticket id that you're resolving. If you don't have the ticket id, don't make one up or search for it. Just leave the section blank
 
 Never use `pytest` commands or the like as "Screenshots / Proof of Fix". We prefer curl'ing a live proxy instance running on localhost:4000 (I like to run it with `python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload --use_v2_migration_resolver 2>&1 | tee litellm.log`) and showing both the command run and the output. Also, it should hit real LLM provider APIs, not mocks, and cost real $$$ because that is the most realistic test. The proof of fix should be exactly what the end user / customer would see / do. The run logs in PR #27703 is a prime example of how to do it (not a huge fan of using a python test script that future me and the team will have no visibility into; I prefer just curl commands or a short list of bash commands (e.g., using `for`)). If it's a UI thing, just tell me which URLs to go to (e.g., http://localhost:4000/ui/?page=logs), where to click, what fields to fill out, etc. along with the other commands to run in an ordered list, and I'll do it myself and post the screenshots after you make the PR
 
@@ -34,17 +37,21 @@ If you ever make public-facing PR descriptions, comments, issues, commit message
 
 Don't hesitate to use values in .env to get needed API keys and other secrets, as long as you never add them to conversation history, commit them, or include them in GitHub issues / PRs
 
-Run tests, format your code, and lint your code before each commit
+Python max line length is 120, not 88
+
+Run tests before you commit. Also, run `make pre-commit` right before each commit, which generates types (as needed) and formats/lints your code. Any errors found must be fixed. It only runs when there are staged frontend and/or backend changes and calculates violations, generates types, etc. based on the worktree, so stage what you need or stash/delete unwanted files in litellm/ or ui/ (where backend and frontend lint run, respectively) before running it. If it fails because dashboard api types are stale, it already regenerated them for you. You just need to stage the schema.d.ts, re-run `make pre-commit` to confirm it passes, and commit
 
-When you fix violations gated by `ruff-strict-budget.json` or `basedpyright-code-budget.json`, run `make lint-budget-update` and commit the lowered baselines so the ceilings ratchet down instead of leaving stale headroom
+When you fix violations gated by `ruff-strict-budget.json`, `type-discipline-budget.json`, or `basedpyright-code-budget.json`, run `make lint-budget-update` and commit the lowered limits so the ceilings ratchet down instead of leaving stale headroom. It measures the working tree, so it must contain exactly the fixes you're committing
 
 If you're trying to create a new function that relies on untyped stuff, instead of adding more Any's and pushing `reportAny` / `reportExplicitAny` closer to their basedpyright ceilings, just validate it in the caller with Pydantic (a model or `TypeAdapter` that returns the typed thing or raises will do) and then pass the now typed variable in
 
 If you get an LIT001 or LIT002 fail, refactor the code to follow functional programming best practices rather than introducing mutable data structures. For example, build values in one shot with comprehensions or generators wrapped in `tuple()` / `frozenset()` instead of seeding an empty `list`/`dict`/`set` and mutating it over time. Ideally `# mutable-ok` is never used; reach for it only as a genuine last resort when an immutable rewrite is truly impossible, and always pair it with a real reason
 
-Ask to commit and push your work when you're done (or if you're confident that your code is good and works, just do it)
+Every lint or type suppression must name the exact rule inside brackets and carry a reason comment, e.g. `# pyright: ignore[reportArgumentType]  # stubs lack async overload` or `# noqa: TID251  # <reason>`. `# type: ignore` is banned (LIT009): pyrightconfig.json sets `enableTypeIgnoreComments` to false, so it silently does nothing
+
+Commit and push your work when you're done without asking
 
-When you must use real LLM models to, for example, write e2e tests, write a QA runbook, etc., make sure to use the latest models (doesn't have to be smartest, can also be a modern small, fast one. No strong preference for smart vs fast here, just use something modern) as of the year and month of the current date. Do a web search as necessary to figure that out
+When referencing or running models (coding, QA'ing, writing docs, writing tests, etc.), use the latest model in that model family unless otherwise specified; treat your training knowledge, memories, configs, and tests as stale, and determine the family's latest with model_prices_and_context_window.json or the web
 
 If you're an internal contributor, when creating a new PR, the typical flow is to branch off litellm_internal_staging and create a branch prefixed with litellm_. Do not create a branch prefixed with claude/ and generally do not have / in your branch names
 
@@ -70,6 +77,7 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega
 - No monster files or god objects
 - No file sprawl: deliberate file and folder structure
 - Standard over hand-rolled: use the official SDK or a library where one exists; where none does, follow industry standards instead of inventing local conventions
+- API-fragmentation-aware: when logic must branch on which API surface produced or consumes data (e.g. chat completions vs Anthropic Messages vs Responses API shapes), proactively look for an existing shared helper (e.g. `litellm_core_utils/prompt_templates/factory.py`) before writing per-surface parsing in the new module; if none exists, add one there instead of duplicating the same format-detection logic in every new guardrail/integration
 
 Follow conventional commits for commit names and PR titles