Merge pull request #31186 from Bytechoreographer/litellm_model_list_deterministic_order

fix(proxy): load DB models in a deterministic order

.circleci/requirements.txt

@@ -1,21 +0,0 @@
-# used by CI/CD testing
-openai==1.100.1
-python-dotenv
-tiktoken
-importlib_metadata
-cohere
-redis==5.2.1
-redisvl==0.4.1
-anthropic
-orjson==3.10.15 # fast /embedding responses
-pydantic==2.12.5
-google-cloud-aiplatform==1.133.0
-google-cloud-iam==2.19.1
-fastapi-sso==0.16.0 
-uvloop==0.21.0
-mcp==1.26.0    # for MCP server
-semantic_router==0.1.10 # for auto-routing with litellm
-fastuuid==0.14.0
-responses==0.25.7  # for proxy client tests
-pytest-retry==1.6.3  # for automatic test retries
-litellm-proxy-extras  # for prisma migrations

.devcontainer/post-create.sh

@@ -1,17 +1,17 @@
 #!/usr/bin/env bash
 set -e
 
-echo "[post-create] Installing poetry via pip"
-python -m pip install --upgrade pip
-python -m pip install poetry
+echo "[post-create] Installing uv"
+curl -LsSf https://astral.sh/uv/0.10.9/install.sh | env UV_NO_MODIFY_PATH=1 sh
+export PATH="$HOME/.local/bin:$PATH"
 
-echo "[post-create] Installing Python dependencies (poetry)"
-poetry install --with dev --extras proxy
+echo "[post-create] Installing Python dependencies (uv)"
+uv sync --frozen --group proxy-dev --extra proxy
 
 echo "[post-create] Generating Prisma client"
-poetry run prisma generate
+uv run --no-sync prisma generate
 
 echo "[post-create] Installing npm dependencies"
 cd ui/litellm-dashboard && npm ci
 
-echo "[post-create] Done"
+echo "[post-create] Done"

.git-blame-ignore-revs

@@ -8,3 +8,6 @@
 
 # Update pydantic code to fix warnings (GH-3600)
 876840e9957bc7e9f7d6a2b58c4d7c53dad16481
+
+# style(ui): run prettier --write across the dashboard (#29622)
+7edf3a9cb55548b143df1692f4ed7c4681d7fcf7

.gitattributes

@@ -1 +1,2 @@
-*.ipynb linguist-vendored
+*.ipynb linguist-vendored
+ui/litellm-dashboard/src/lib/http/schema.d.ts linguist-generated

.gitguardian.yaml

@@ -37,7 +37,7 @@ secret:
     - "docs/**"
     - "**/*.md"
     - "**/*.lock"
-    - "poetry.lock"
+    - "uv.lock"
     - "package-lock.json"
 
   # Ignore security incidents with the SHA256 of the occurrence (false positives)

.githooks/commit-msg

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# commit-msg — enforce Conventional Commits 1.0.0
+#   https://www.conventionalcommits.org/en/v1.0.0/
+#
+# Subject format:  <type>(<scope>)!: <description>
+#   - <type> must be one of the angular types (feat, fix, ...)
+#   - (<scope>) is optional
+#   - !       is optional and marks a breaking change
+#   - <description> is mandatory and must be non-empty
+#
+# Bypass: commit with --no-verify.
+# Merge, revert, fixup!, squash!, and amend! messages are passed through.
+
+set -eu
+
+COMMIT_MSG_FILE="${1:-}"
+if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then
+    echo "commit-msg: missing commit message file" >&2
+    exit 1
+fi
+
+# First non-comment, non-empty line is the subject.
+subject=""
+while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+        ''|'#'*) continue ;;
+    esac
+    subject="$line"
+    break
+done < "$COMMIT_MSG_FILE"
+
+if [ -z "$subject" ]; then
+    echo "commit-msg: empty commit message" >&2
+    exit 1
+fi
+
+# Pass-through commits generated by git itself.
+case "$subject" in
+    "Merge "*|"Revert \""*|"fixup! "*|"squash! "*|"amend! "*)
+        exit 0
+        ;;
+esac
+
+ALLOWED_TYPES="feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert"
+# Description must not start with an uppercase letter — kept in sync with the
+# subjectPattern in .github/workflows/conventional-commits.yml so the local
+# hook is the strictly tighter of the two gates. (Without this guard, a commit
+# like "feat: Add thing" passes locally but fails the PR-title CI check.)
+PATTERN="^(${ALLOWED_TYPES})(\([^)]+\))?!?: [^A-Z].*"
+
+if printf '%s' "$subject" | grep -Eq "$PATTERN"; then
+    exit 0
+fi
+
+cat >&2 <<EOF
+✗ Commit message does not follow Conventional Commits.
+
+  Got:      $subject
+
+  Expected: <type>(<scope>)!: <description>
+            (description must start with a lowercase letter)
+
+  Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+  Examples:
+    feat(router): add weighted round-robin strategy
+    fix(bedrock): decouple STS region from aws_region_name
+    chore(deps): bump black to 26.3.1
+    refactor!: drop Python 3.8 support
+
+See https://www.conventionalcommits.org/en/v1.0.0/
+
+To bypass (use sparingly): git commit --no-verify
+EOF
+exit 1

.githooks/pre-push

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+#
+# pre-push — enforce Conventional Branches
+#   https://conventional-branch.github.io/
+#
+# Branch format:  <type>/<description>
+#   <type> must be one of: feature, bugfix, hotfix, release, chore
+#
+# Protected branches (always allowed):
+#   - main
+#   - litellm_internal_staging
+#   - dependabot/*
+#   - gh-readonly-queue/*
+#
+# Tag pushes and branch deletions are skipped.
+# Bypass: git push --no-verify.
+
+set -eu
+
+ZERO_OID="0000000000000000000000000000000000000000"
+ZERO_OID_SHA256="0000000000000000000000000000000000000000000000000000000000000000"
+ALLOWED_TYPES="feature|bugfix|hotfix|release|chore"
+BRANCH_PATTERN="^(${ALLOWED_TYPES})/.+"
+
+PROTECTED_NAMES="main litellm_internal_staging"
+PROTECTED_PREFIXES="dependabot/ gh-readonly-queue/"
+
+is_protected() {
+    branch="$1"
+    for name in $PROTECTED_NAMES; do
+        if [ "$branch" = "$name" ]; then
+            return 0
+        fi
+    done
+    for prefix in $PROTECTED_PREFIXES; do
+        case "$branch" in "$prefix"*) return 0 ;; esac
+    done
+    return 1
+}
+
+invalid=""
+
+while read -r local_ref local_oid remote_ref remote_oid; do
+    # Branch deletion (no local commit being pushed).
+    if [ "$local_oid" = "$ZERO_OID" ] || [ "$local_oid" = "$ZERO_OID_SHA256" ]; then
+        continue
+    fi
+
+    # Only validate branch pushes; ignore tags and other ref namespaces.
+    case "$remote_ref" in
+        refs/heads/*) ;;
+        *) continue ;;
+    esac
+
+    branch="${remote_ref#refs/heads/}"
+
+    if is_protected "$branch"; then
+        continue
+    fi
+
+    if ! printf '%s' "$branch" | grep -Eq "$BRANCH_PATTERN"; then
+        invalid="$invalid $branch"
+    fi
+done
+
+if [ -n "$invalid" ]; then
+    cat >&2 <<EOF
+✗ Branch name does not follow Conventional Branches.
+
+  Invalid:$invalid
+
+  Expected: <type>/<description>
+
+  Allowed types: feature, bugfix, hotfix, release, chore
+  Examples:
+    feature/weighted-round-robin
+    bugfix/streaming-empty-chunks
+    chore/bump-deps
+    hotfix/auth-bypass
+
+  Protected (always allowed): main, litellm_internal_staging,
+  dependabot/*, gh-readonly-queue/*.
+
+See https://conventional-branch.github.io/
+
+Rename with: git branch -m <new-name>
+To bypass (use sparingly): git push --no-verify
+EOF
+    exit 1
+fi
+
+exit 0

.github/actions/helm-oci-chart-releaser/action.yml

@@ -1,94 +0,0 @@
-name: Helm OCI Chart Releaser
-description: Push Helm charts to OCI-based (Docker) registries
-author: sergeyshaykhullin
-branding:
-  color: yellow
-  icon: upload-cloud
-inputs:
-  name:
-    required: true
-    description: Chart name
-  repository:
-    required: true
-    description: Chart repository name
-  tag:
-    required: true
-    description: Chart version
-  app_version:
-    required: true
-    description: App version
-  path:
-    required: false
-    description: Chart path (Default 'charts/{name}')
-  registry:
-    required: true
-    description: OCI registry
-  registry_username:
-    required: true
-    description: OCI registry username
-  registry_password:
-    required: true
-    description: OCI registry password
-  update_dependencies:
-    required: false
-    default: 'false'
-    description: Update chart dependencies before packaging (Default 'false')
-outputs:
-  image:
-    value: ${{ steps.output.outputs.image }}
-    description: Chart image (Default '{registry}/{repository}/{image}:{tag}')
-runs:
-  using: composite
-  steps:
-    - name: Helm | Setup
-      uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
-      with:
-        version: v3.20.0
-
-    - name: Helm | Login
-      shell: bash
-      env:
-        REGISTRY_PASSWORD: ${{ inputs.registry_password }}
-        REGISTRY_USERNAME: ${{ inputs.registry_username }}
-        REGISTRY: ${{ inputs.registry }}
-      run: echo "$REGISTRY_PASSWORD" | helm registry login -u "$REGISTRY_USERNAME" --password-stdin "$REGISTRY"
-
-    - name: Helm | Dependency
-      if: inputs.update_dependencies == 'true'
-      shell: bash
-      env:
-        CHART_PATH: ${{ inputs.path == null && format('{0}/{1}', 'charts', inputs.name) || inputs.path }}
-      run: helm dependency update "$CHART_PATH"
-
-    - name: Helm | Package
-      shell: bash
-      env:
-        CHART_PATH: ${{ inputs.path == null && format('{0}/{1}', 'charts', inputs.name) || inputs.path }}
-        TAG: ${{ inputs.tag }}
-        APP_VERSION: ${{ inputs.app_version }}
-      run: helm package "$CHART_PATH" --version "$TAG" --app-version "$APP_VERSION"
-
-    - name: Helm | Push
-      shell: bash
-      env:
-        NAME: ${{ inputs.name }}
-        TAG: ${{ inputs.tag }}
-        REGISTRY: ${{ inputs.registry }}
-        REPOSITORY: ${{ inputs.repository }}
-      run: helm push "${NAME}-${TAG}.tgz" "oci://${REGISTRY}/${REPOSITORY}"
-
-    - name: Helm | Logout
-      shell: bash
-      env:
-        REGISTRY: ${{ inputs.registry }}
-      run: helm registry logout "$REGISTRY"
-
-    - name: Helm | Output
-      id: output
-      shell: bash
-      env:
-        REGISTRY: ${{ inputs.registry }}
-        REPOSITORY: ${{ inputs.repository }}
-        NAME: ${{ inputs.name }}
-        TAG: ${{ inputs.tag }}
-      run: echo "image=${REGISTRY}/${REPOSITORY}/${NAME}:${TAG}" >> $GITHUB_OUTPUT

.github/pull_request_template.md

@@ -2,13 +2,17 @@
 
 <!-- e.g. "Fixes #000" -->
 
+## 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 -->
+
 ## Pre-Submission checklist
 
 **Please complete all items before asking a LiteLLM maintainer to review your PR**
 
-- [ ] I have Added testing in the [`tests/test_litellm/`](https://github.com/BerriAI/litellm/tree/main/tests/test_litellm) directory, **Adding at least 1 test is a hard requirement** - [see details](https://docs.litellm.ai/docs/extras/contributing_code)
+- [ ] I have added meaningful tests
 - [ ] My PR passes all unit tests on [`make test-unit`](https://docs.litellm.ai/docs/extras/contributing_code)
-- [ ] My PR's scope is as isolated as possible, it only solves 1 specific problem
+- [ ] My PR's scope is as isolated as possible; it only solves 1 specific problem
 - [ ] I have requested a Greptile review by commenting `@greptileai` and received a **Confidence Score of at least 4/5** before requesting a maintainer review
 
 ## Delays in PR merge?
@@ -32,6 +36,13 @@ If you're seeing a delay in your PR being merged, ping the LiteLLM Team on [Slac
 - [ ] **Merge / cherry-pick CI run**  
        Links:
 
+## Screenshots / Proof of Fix
+
+<!-- Include screenshots, screen recordings, or log output demonstrating that your changes work as expected.
+     For bug fixes: show reproduction before the fix and passing behavior after.
+     For new features: show the feature working end-to-end.
+     For UI changes: include before/after screenshots. -->
+
 ## Type
 
 <!-- Select the type of Pull Request -->

.github/scripts/_agent_shin_actions.py

@@ -0,0 +1,50 @@
+"""Dry-run wrapper(s) around Agent Shin GitHub mutations.
+
+The rollout scripts currently need only one mutation wrapped, so this module
+exposes a single ``maybe_post_comment`` helper. It takes a ``dry_run: bool``
+keyword argument and the body is intentionally trivial:
+
+    if dry_run:
+        print(...)        # log what we would do, return
+        return
+    real_mutation(...)    # otherwise, actually do it
+
+That shape means a dry-run preview differs from the real run in exactly one
+line per side effect: the call site. So when you `python3 script.py` locally
+without ``--close``, you can be confident the actions printed are the ones the
+GitHub Action would have performed (modulo ordering on retry/error paths,
+which are deliberately simple). Any further mutation a rollout script needs
+should get the same ``maybe_*`` treatment instead of calling the raw
+``triage_with_llm`` mutation directly.
+
+Importing from this module pulls in the real mutation from ``triage_with_llm``
+— call sites in the rollout scripts should NEVER import ``post_comment``
+directly; that would skip the dry-run gate and is the bug class this module
+exists to prevent.
+"""
+
+from __future__ import annotations
+
+import sys
+import textwrap
+
+# Import the module itself rather than the bare names so monkeypatching
+# `triage_with_llm.post_comment` (or any of the other mutations) in tests is
+# reflected here — `from triage_with_llm import post_comment` would bind the
+# original function to a local name and bypass the patch, defeating the whole
+# point of these wrappers.
+import triage_with_llm
+
+
+def _log(line: str) -> None:
+    """Print a single dry-run line to stdout (one log statement per side effect)."""
+    print(line, file=sys.stdout, flush=True)
+
+
+def maybe_post_comment(repo: str, number: int, body: str, *, dry_run: bool) -> None:
+    """Post a comment on ``repo#number`` — or, in dry-run, log what we would post."""
+    if dry_run:
+        _log(f"[DRY RUN] comment {repo}#{number}:")
+        _log(textwrap.indent(body, "    "))
+        return
+    triage_with_llm.post_comment(repo, number, body)

.github/scripts/agent_shin_shared.py

@@ -0,0 +1,211 @@
+"""Constants and helpers shared by Agent Shin's triage scripts.
+
+Both `triage_with_llm.py` (the LLM-judge entrypoint) and
+`close_low_quality_prs.py` (the daily Greptile-score sweep) need to
+agree on the same notions of:
+
+  * What counts as a Greptile-authored review comment
+    (``GREPTILE_BOT_LOGINS``) and how to extract a confidence score from
+    its body (``SCORE_PATTERN`` / :func:`extract_greptile_score`).
+  * How long the 2-hour grace window is (``GRACE_PERIOD_SECONDS``) and
+    the HTML marker stamped into a grace-warning comment so the *other*
+    script can see "Agent Shin already warned" and behave accordingly
+    (``GRACE_COMMENT_MARKER``).
+  * Who Agent Shin is on GitHub (``AGENT_SHIN_DEFAULT_BOT_LOGIN``).
+  * How GitHub-style ISO-8601 timestamps round-trip into timezone-aware
+    :class:`datetime.datetime` (:func:`parse_iso8601`).
+
+Keeping these in one module means a future change (new Greptile output
+format, a longer grace window, a new allowlisted account) is a single edit
+instead of two — the original split version had to call out in comments
+that the two copies "must stay in sync" precisely because nothing
+enforced it.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import re
+import subprocess
+from typing import Iterable
+
+GREPTILE_BOT_LOGINS = frozenset({"greptile-apps", "greptile-apps[bot]"})
+
+SCORE_PATTERN = re.compile(
+    r"confidence\s*score\s*[:\-]?\s*(\d+)\s*/\s*5",
+    re.IGNORECASE,
+)
+
+GRACE_COMMENT_MARKER = "<!-- agent-shin:grace-warning -->"
+
+# Hidden HTML marker stamped on every Agent Shin auto-close comment (the LLM
+# judge's grace/review-gate close and the daily Greptile sweep's close).
+# `was_closed_by_agent_shin` requires this marker — not just the closing actor —
+# before `@agent-shin reconsider` may reopen, because the `github-actions[bot]`
+# identity is shared with every other workflow in the repo and is not unique to
+# Agent Shin. Both close paths must stamp it or the reconsider path silently
+# rejects the contributor.
+AGENT_SHIN_CLOSE_MARKER = "<!-- agent-shin:closed -->"
+
+# 2 hours between the grace warning and the auto-close. Short enough to
+# dogfood the "fix it before it closes" loop in one sitting; bump back up
+# (e.g. 86400 for a day) for the public rollout.
+GRACE_PERIOD_SECONDS = 7200
+
+AGENT_SHIN_DEFAULT_BOT_LOGIN = "github-actions[bot]"
+
+
+def _logins(*names: str) -> frozenset[str]:
+    """Build a login set normalized for case-insensitive membership checks.
+
+    Callers compare via ``login.lower() in <set>``, so the stored values
+    must be lowercase. Normalizing here lets the literals keep each
+    account's canonical GitHub casing (e.g. ``SwiftWinds``) for
+    readability without breaking the lookup.
+    """
+    return frozenset(name.lower() for name in names)
+
+
+# Dogfood rollout gate. While this set is non-empty, Agent Shin acts ONLY on
+# PRs/issues authored by these logins and skips everyone else. For an
+# allowlisted author the usual internal/external classification is bypassed, so
+# an internal account (e.g. a maintainer's own work login) still gets triaged
+# while the bot is being tested on a small set of accounts. Empty the set to
+# lift the restriction and restore full triage for the public rollout. Logins
+# are compared case-insensitively.
+ALLOWLIST_LOGINS = _logins("mateo-berri", "SwiftWinds")
+
+# `gh {pr,issue} list` has no "fetch everything" flag — `--limit` is the only
+# control and it defaults to 30. Pass a ceiling far above any realistic open
+# backlog (low thousands today) so gh paginates the API until the queue is
+# exhausted rather than silently truncating. The bulk sweeps MUST see the whole
+# backlog: gh lists newest-first, so a low cap drops the *oldest* PRs/issues —
+# exactly the stale ones a low-quality sweep is meant to catch.
+GH_LIST_ALL_LIMIT = 100_000
+
+
+def extract_greptile_score(comments: Iterable[dict]) -> tuple[int, dict] | None:
+    """Return (score, comment) for the most recent Greptile-authored comment
+    that contains a "Confidence Score: X/5". Returns None if no such comment.
+
+    "Most recent" is determined by the comment's `updated_at` (falling back to
+    `created_at`), so re-reviews override earlier passes.
+    """
+    candidates: list[tuple[str, int, dict]] = []
+    for comment in comments:
+        user = (comment.get("user") or {}).get("login", "")
+        if user not in GREPTILE_BOT_LOGINS:
+            continue
+        body = comment.get("body") or ""
+        match = SCORE_PATTERN.search(body)
+        if not match:
+            continue
+        score = int(match.group(1))
+        timestamp = comment.get("updated_at") or comment.get("created_at") or ""
+        candidates.append((timestamp, score, comment))
+
+    if not candidates:
+        return None
+
+    candidates.sort(key=lambda triple: triple[0])
+    _, score, comment = candidates[-1]
+    return score, comment
+
+
+def parse_iso8601(value: str) -> dt.datetime:
+    """Parse a GitHub ISO-8601 timestamp into a timezone-aware datetime."""
+    return dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def gh(*args: str) -> str:
+    """Run a `gh` CLI command and return stdout. Raises on non-zero exit.
+
+    Shared by both Agent Shin entrypoints so a future change here
+    (timeout handling, logging, retry on transient failures) only needs
+    to be made once.
+    """
+    result = subprocess.run(
+        ["gh", *args],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout
+
+
+def list_open_items(kind: str, *, repo: str | None, fields: str) -> list[dict]:
+    """Return EVERY open PR (``kind="pr"``) or issue (``kind="issue"``) in ``repo``.
+
+    Wraps ``gh {pr,issue} list`` with ``--limit GH_LIST_ALL_LIMIT`` so the full
+    backlog is fetched instead of the default 30 (or any other arbitrary cap).
+    Both bulk sweeps — the daily Greptile closer and the one-shot rollout
+    heads-up — rely on this seeing the whole queue, including the oldest items.
+
+    ``fields`` is the comma-separated ``--json`` field list the caller needs
+    (e.g. ``"number"`` for the rollout, the full set for the closer).
+    """
+    if kind not in ("pr", "issue"):
+        raise ValueError(f"kind must be 'pr' or 'issue', got {kind!r}")
+    repo_args = ["--repo", repo] if repo else []
+    raw = gh(
+        kind,
+        "list",
+        "--state",
+        "open",
+        "--limit",
+        str(GH_LIST_ALL_LIMIT),
+        "--json",
+        fields,
+        *repo_args,
+    )
+    return json.loads(raw)
+
+
+def seconds_since_latest_marker_comment(
+    comments: Iterable[dict],
+    *,
+    marker: str,
+    bot_login: str | None = None,
+    now: dt.datetime | None = None,
+) -> float | None:
+    """Return seconds since the bot's most recent comment containing ``marker``.
+
+    Filters comments by author so a contributor who quotes the HTML
+    marker (e.g. via GitHub's "Quote reply" feature, which preserves
+    HTML comments in the raw markdown of the quoted text) is not
+    mistaken for a bot warning — that would silently reset cooldown
+    timers and suppress legitimate notifications.
+
+    ``bot_login`` defaults to the `AGENT_SHIN_BOT_LOGIN` env override or
+    ``AGENT_SHIN_DEFAULT_BOT_LOGIN`` so callers normally don't need to
+    pass it. ``now`` is injectable for tests / callers (like the daily
+    sweep) that want every age calculation pinned to one snapshot.
+    """
+    expected_login = (
+        bot_login
+        or os.environ.get("AGENT_SHIN_BOT_LOGIN")
+        or AGENT_SHIN_DEFAULT_BOT_LOGIN
+    ).lower()
+    latest: dt.datetime | None = None
+    for comment in comments:
+        author = ((comment.get("user") or {}).get("login") or "").lower()
+        if author != expected_login:
+            continue
+        body = comment.get("body") or ""
+        if marker not in body:
+            continue
+        created = comment.get("created_at")
+        if not created:
+            continue
+        try:
+            ts = parse_iso8601(created)
+        except ValueError:
+            continue
+        if latest is None or ts > latest:
+            latest = ts
+    if latest is None:
+        return None
+    reference = now if now is not None else dt.datetime.now(dt.timezone.utc)
+    return (reference - latest).total_seconds()

.github/scripts/close_duplicate_issues.py

@@ -42,7 +42,9 @@ def gh(*args: str) -> str:
 def fetch_open_issues(repo: str | None) -> list[dict]:
     """Fetch all open issues (excluding PRs) via gh api --paginate."""
     if repo:
-        endpoint = f"repos/{repo}/issues?state=open&per_page=100&sort=created&direction=asc"
+        endpoint = (
+            f"repos/{repo}/issues?state=open&per_page=100&sort=created&direction=asc"
+        )
     else:
         endpoint = "repos/{owner}/{repo}/issues?state=open&per_page=100&sort=created&direction=asc"
     cmd = ["api", "--paginate", endpoint]
@@ -71,7 +73,9 @@ def close_as_duplicate(
     repo_args = ["--repo", repo] if repo else []
 
     if dry_run:
-        print(f"  [DRY RUN] Would close #{issue_number} as duplicate of #{duplicate_of}")
+        print(
+            f"  [DRY RUN] Would close #{issue_number} as duplicate of #{duplicate_of}"
+        )
         return
 
     # Add comment
@@ -115,7 +119,9 @@ def find_duplicate(
     return None
 
 
-def scan_all(issues: list[dict], threshold: float, repo: str | None, dry_run: bool) -> int:
+def scan_all(
+    issues: list[dict], threshold: float, repo: str | None, dry_run: bool
+) -> int:
     """Compare every issue against all older issues. Returns count of duplicates found."""
     # Sort oldest first
     issues.sort(key=lambda i: i["number"])
@@ -144,7 +150,11 @@ def scan_all(issues: list[dict], threshold: float, repo: str | None, dry_run: bo
 
 
 def check_single(
-    issue_number: int, issues: list[dict], threshold: float, repo: str | None, dry_run: bool
+    issue_number: int,
+    issues: list[dict],
+    threshold: float,
+    repo: str | None,
+    dry_run: bool,
 ) -> bool:
     """Check a single issue against all older open issues. Returns True if duplicate found."""
     target = None
@@ -178,13 +188,23 @@ def check_single(
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(description="Detect and close duplicate GitHub issues")
+    parser = argparse.ArgumentParser(
+        description="Detect and close duplicate GitHub issues"
+    )
     mode = parser.add_mutually_exclusive_group(required=True)
     mode.add_argument("--scan", action="store_true", help="Scan all open issues")
     mode.add_argument("--issue-number", type=int, help="Check a single issue number")
-    parser.add_argument("--threshold", type=float, default=0.85, help="Similarity threshold (0-1)")
-    parser.add_argument("--close", action="store_true", help="Actually close duplicates (default is dry-run)")
-    parser.add_argument("--repo", type=str, help="Repository (owner/repo). Auto-detected if omitted.")
+    parser.add_argument(
+        "--threshold", type=float, default=0.85, help="Similarity threshold (0-1)"
+    )
+    parser.add_argument(
+        "--close",
+        action="store_true",
+        help="Actually close duplicates (default is dry-run)",
+    )
+    parser.add_argument(
+        "--repo", type=str, help="Repository (owner/repo). Auto-detected if omitted."
+    )
     args = parser.parse_args()
 
     dry_run = not args.close
@@ -200,7 +220,9 @@ def main() -> None:
         count = scan_all(issues, args.threshold, args.repo, dry_run)
         print(f"\nTotal duplicates {'found' if dry_run else 'closed'}: {count}")
     else:
-        found = check_single(args.issue_number, issues, args.threshold, args.repo, dry_run)
+        found = check_single(
+            args.issue_number, issues, args.threshold, args.repo, dry_run
+        )
         sys.exit(0 if found else 0)  # Always exit 0; finding no dup is not an error
 
 

.github/scripts/close_low_quality_prs.py

@@ -0,0 +1,573 @@
+#!/usr/bin/env python3
+"""
+Auto-close low-quality pull requests.
+
+Closes open PRs (including drafts, regardless of age) that satisfy ALL of:
+  1. Have a Greptile (`greptile-apps`) review comment whose latest
+     "Confidence Score: X/5" is below the configured threshold (default: 4).
+  2. Are authored by an external OSS contributor (internal BerriAI
+     contributors are exempt).
+  3. Do not carry an opt-out label (default: "do not close").
+
+`--min-age-days` is retained as an opt-in safety net for one-off backfill
+runs (default: 0). The team's intent is that the count of open PRs equals
+the count of PRs internal collaborators need to action on, so neither age
+nor draft status acts as a free pass.
+
+For each match, the script posts an explanatory comment and closes the PR.
+Because OSS contributors *cannot* reopen a PR closed by the bot/maintainer
+(GitHub limitation), the close-comment instructs them to push their fixes
+and **open a fresh PR**, or to comment `@agent-shin reconsider` on the
+closed PR to have the LLM judge re-evaluate (and reopen on pass).
+
+Requires the `gh` CLI to be authenticated.
+
+Usage examples:
+    # Dry run (default) - prints what would be closed
+    python3 close_low_quality_prs.py
+
+    # Actually close matching PRs
+    python3 close_low_quality_prs.py --close
+
+    # Restrict to PRs at least N days old (one-off backfill safety net)
+    python3 close_low_quality_prs.py --min-age-days 7 --min-score 4 --close
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import subprocess
+import sys
+from typing import Iterable
+
+# Add this script's directory to `sys.path` so the sibling
+# `agent_shin_shared` module is importable when the script is invoked
+# directly (e.g. `python3 .github/scripts/close_low_quality_prs.py ...`).
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from agent_shin_shared import (  # noqa: E402  -- sys.path adjusted above
+    AGENT_SHIN_CLOSE_MARKER,
+    ALLOWLIST_LOGINS,
+    GRACE_COMMENT_MARKER,
+    GRACE_PERIOD_SECONDS,
+    GREPTILE_BOT_LOGINS,
+    SCORE_PATTERN,
+    extract_greptile_score,
+    gh,
+    list_open_items,
+    parse_iso8601,
+    seconds_since_latest_marker_comment,
+)
+
+# `GREPTILE_BOT_LOGINS` and `SCORE_PATTERN` (Greptile's GitHub App login
+# variants and the "Confidence Score: X/5" regex) are imported from
+# `agent_shin_shared` so the LLM judge in `triage_with_llm.py` and this
+# daily Greptile sweep read the score through the same set of logins
+# and the same regex.
+
+# `author_association` values for internal BerriAI contributors who should be
+# exempt from auto-triage.
+INTERNAL_AUTHOR_ASSOCIATIONS = frozenset({"OWNER", "MEMBER", "COLLABORATOR"})
+
+# Default labels that exempt a PR from auto-close. Defined at module scope (not
+# as a mutable argparse default) so that `--optout-label foo` REPLACES the
+# defaults instead of appending to them — the argparse `action="append"` +
+# `default=[...]` combination silently mutates the shared default list.
+DEFAULT_OPTOUT_LABELS = ("do not close", "keep open", "wip")
+
+# `GRACE_COMMENT_MARKER` (HTML marker appended to grace-period warning
+# comments — used by either script to recognize that a warning was
+# already posted) and `GRACE_PERIOD_SECONDS` (length of the grace
+# period between the warning and the actual auto-close, 2 hours) are
+# imported from `agent_shin_shared` so the Agent Shin LLM judge and
+# this daily Greptile sweep agree on the same marker and duration.
+
+
+def fetch_open_prs(repo: str | None) -> list[dict]:
+    """Fetch all open PRs (number, createdAt, isDraft, labels, author).
+
+    Includes drafts: `gh pr list --state open` returns both ready-for-review
+    and draft PRs by default. This is the desired behavior — drafts are not
+    a free pass; the internal-collaborator open-PR queue should reflect every
+    PR that needs human attention regardless of draft status.
+    """
+    fields = "number,title,createdAt,isDraft,labels,author,url"
+    return list_open_items("pr", repo=repo, fields=fields)
+
+
+def fetch_pr_author_association(pr_number: int, repo: str | None) -> str:
+    """Return the GitHub `author_association` for a PR, uppercase.
+
+    Values: OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR,
+    FIRST_TIMER, MANNEQUIN, NONE. Returns "" on lookup failure.
+    """
+    endpoint = (
+        f"repos/{repo}/pulls/{pr_number}"
+        if repo
+        else f"repos/{{owner}}/{{repo}}/pulls/{pr_number}"
+    )
+    try:
+        data = json.loads(gh("api", endpoint))
+    except subprocess.CalledProcessError:
+        return ""
+    return (data.get("author_association") or "").upper()
+
+
+def is_external_pr_author(pr: dict, repo: str | None) -> bool:
+    """Return True if the PR author is an external OSS contributor.
+
+    Internal = `OWNER` / `MEMBER` / `COLLABORATOR` association, or a bot login.
+    """
+    login = ((pr.get("author") or {}).get("login") or "").lower()
+    if login.endswith("[bot]") or login in {"dependabot", "github-actions"}:
+        return False
+    association = fetch_pr_author_association(pr["number"], repo)
+    # Fail-safe: if the API lookup failed (empty string), treat the author as
+    # internal so we don't auto-close their PR. Auto-close is destructive, so
+    # an unknown association should never make a PR eligible for closing.
+    if not association or association in INTERNAL_AUTHOR_ASSOCIATIONS:
+        return False
+    return True
+
+
+def fetch_pr_comments(pr_number: int, repo: str | None) -> list[dict]:
+    """Fetch issue-level comments on a PR (where Greptile posts its summary)."""
+    endpoint = (
+        f"repos/{repo}/issues/{pr_number}/comments?per_page=100"
+        if repo
+        else f"repos/{{owner}}/{{repo}}/issues/{pr_number}/comments?per_page=100"
+    )
+    raw = gh("api", "--paginate", endpoint)
+    comments: list[dict] = []
+    for line in raw.strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            # A malformed line should not blow up the whole sweep. Skip and
+            # carry on so the remaining PRs in this run still get evaluated.
+            continue
+        if isinstance(parsed, list):
+            comments.extend(parsed)
+        else:
+            comments.append(parsed)
+    return comments
+
+
+def has_optout_label(pr: dict, optout_labels: set[str]) -> bool:
+    labels = {label.get("name", "").lower() for label in pr.get("labels", [])}
+    return bool(labels & {lbl.lower() for lbl in optout_labels})
+
+
+def seconds_since_last_grace_warning(
+    comments: Iterable[dict],
+    *,
+    bot_login: str | None = None,
+    now: dt.datetime | None = None,
+) -> float | None:
+    """Return seconds since the bot's most recent grace-period warning, or
+    None if no such warning has ever been posted on this PR.
+
+    Thin wrapper over
+    `agent_shin_shared.seconds_since_latest_marker_comment` — the
+    centralized helper handles the bot-author filter, marker match,
+    timestamp parsing, and `now` injection. Keeping this wrapper
+    preserves the closer's "already-fetched comments + injectable now"
+    interface so callers (and tests) don't need to change.
+    """
+    return seconds_since_latest_marker_comment(
+        comments,
+        marker=GRACE_COMMENT_MARKER,
+        bot_login=bot_login,
+        now=now,
+    )
+
+
+def format_grace_warning_comment(score: int, threshold: int) -> str:
+    """Comment posted on the FIRST low-Greptile-score detection — gives
+    the contributor a 2-hour grace window before the auto-close fires on
+    the next daily cron run.
+
+    Mirrors `format_grace_warning_pr_comment` in
+    `triage_with_llm.py` in spirit (2-hour grace + escape hatches), but
+    framed around Greptile's confidence score instead of the LLM judge's
+    rubric since the close trigger here is the Greptile signal.
+    """
+    return (
+        "🚅 Hi, thanks for the PR! I'm **Agent Shin**, the automated triage bot for this "
+        "repository.\n"
+        "\n"
+        "Heads up: Greptile's most recent review scored this PR "
+        f"**{score}/5**, below our merge bar of **{threshold}/5**.\n"
+        "\n"
+        "If the score isn't lifted in the next **2 hours**, I'll auto-close this PR. That's "
+        "**not** us saying the change isn't worthwhile. We want the open-PR list to mirror "
+        "what a maintainer can act on *right now*, so contributors like you don't get lost in "
+        "a backlog. Take your time; everything below still works after the close.\n"
+        "\n"
+        "**During the grace period:** push fixes that address Greptile's feedback, then comment "
+        "`@greptileai` to request a fresh review. If "
+        f"the new score is **{threshold}/5 or higher**, the PR stays open and no further "
+        "action is needed on your side.\n"
+        "\n"
+        "**If the PR does get auto-closed in 2 hours, you still have an easy recovery path:**\n"
+        "\n"
+        "- Comment `@greptileai` to request a fresh review. **This still works even after "
+        f"the PR is closed**, and a score of {threshold}/5 or higher is one of the signals "
+        "that lifts the PR back into the review queue. A low Greptile score isn't a blocker.\n"
+        "- Comment `@agent-shin reconsider` after pushing fixes; I'll re-run the rubric and "
+        "reopen the PR if both gates (description rubric + Greptile score) now pass.\n"
+        "\n"
+        f"{GRACE_COMMENT_MARKER}"
+    )
+
+
+def post_grace_warning(
+    pr: dict,
+    score: int,
+    threshold: int,
+    repo: str | None,
+    dry_run: bool,
+) -> None:
+    """Post the 2-hour grace-period warning comment on `pr`.
+
+    The warning carries `GRACE_COMMENT_MARKER` so subsequent runs can
+    detect that the contributor has already been told about the
+    pending close. Does NOT close the PR — the close happens on the
+    next eligible run after `GRACE_PERIOD_SECONDS` elapses (handled
+    by `close_pr`).
+    """
+    pr_number = pr["number"]
+    repo_args = ["--repo", repo] if repo else []
+
+    if dry_run:
+        print(
+            f"  [DRY RUN] Would post grace warning to PR #{pr_number} "
+            f"(greptile={score}/5): {pr['title']}"
+        )
+        return
+
+    comment_body = format_grace_warning_comment(score, threshold)
+    gh("pr", "comment", str(pr_number), "--body", comment_body, *repo_args)
+    print(f"  Posted grace warning on PR #{pr_number} (greptile={score}/5)")
+
+
+def format_close_comment(score: int, threshold: int) -> str:
+    """Comment posted when a low-Greptile-score PR is auto-closed.
+
+    Carries `AGENT_SHIN_CLOSE_MARKER` so the `@agent-shin reconsider` path
+    (guarded by `was_closed_by_agent_shin`) recognizes this as an Agent Shin
+    close and is allowed to reopen the PR once it passes again; without the
+    marker that recovery path the comment advertises silently rejects the
+    contributor.
+    """
+    score_sentence = (
+        f"Greptile's most recent review scored this PR **{score}/5**, below "
+        f"our merge bar of **{threshold}/5**, and the 2-hour grace period since "
+        "the warning has elapsed.\n\n"
+    )
+    return (
+        f"Closing as part of automated PR triage.\n\n"
+        f"{score_sentence}"
+        "We close low-confidence PRs aggressively to keep the review queue "
+        "manageable for maintainers and contributors alike. **This is not a "
+        "rejection of the idea.** To bring this back:\n\n"
+        "1. Push the fixes that address Greptile's feedback (continue using "
+        "your existing branch is fine).\n"
+        "2. **Open a new PR** with the updated branch. Greptile will review "
+        "it again, and if it scores "
+        f"**{threshold}/5 or higher** a maintainer will take another look.\n\n"
+        "_Why open a new PR instead of reopening this one?_ GitHub does not "
+        "let external contributors reopen a PR that was closed by a bot or "
+        "maintainer, so a fresh PR is the most reliable path forward. If you "
+        "would prefer this exact PR re-evaluated, comment "
+        "`@agent-shin reconsider` once you've pushed the fixes; Agent Shin "
+        "will re-run triage and reopen this PR if it now meets the bar. "
+        "You can also comment `@greptileai` to request a fresh Greptile "
+        "review; that works **even after the PR is closed**.\n\n"
+        "Thanks for contributing to LiteLLM. We know auto-closures can sting; "
+        "the goal is to keep the project healthy, not to dismiss your work."
+        f"\n\n{AGENT_SHIN_CLOSE_MARKER}"
+    )
+
+
+def close_pr(
+    pr: dict,
+    score: int,
+    threshold: int,
+    age_days: int,
+    repo: str | None,
+    dry_run: bool,
+    label: str | None,
+) -> None:
+    """Post the explanatory comment and close the PR."""
+    pr_number = pr["number"]
+    repo_args = ["--repo", repo] if repo else []
+
+    if dry_run:
+        print(
+            f"  [DRY RUN] Would close PR #{pr_number} "
+            f"(age={age_days}d, greptile={score}/5): {pr['title']}"
+        )
+        return
+
+    comment_body = format_close_comment(score, threshold)
+    gh("pr", "comment", str(pr_number), "--body", comment_body, *repo_args)
+
+    if label:
+        try:
+            gh("pr", "edit", str(pr_number), "--add-label", label, *repo_args)
+        except subprocess.CalledProcessError as exc:
+            stderr = (exc.stderr or "").strip()
+            print(f"  warn: failed to add label '{label}' to #{pr_number}: {stderr}")
+
+    gh("pr", "close", str(pr_number), *repo_args)
+    print(f"  Closed PR #{pr_number} (greptile={score}/5, age={age_days}d)")
+
+
+def evaluate_pr(
+    pr: dict,
+    now: dt.datetime,
+    min_age_days: int,
+    min_score: int,
+    repo: str | None,
+    optout_labels: set[str],
+    allowlist: frozenset[str] = ALLOWLIST_LOGINS,
+) -> tuple[str, int | None, int | None]:
+    """Decide what to do with `pr` on this triage run.
+
+    Returns (action, score_or_none, age_days_or_none) where action is one of:
+        "skip-too-young", "skip-optout-label", "skip-not-allowlisted",
+        "skip-internal", "skip-no-greptile-score", "skip-score-ok",
+        "warn-grace", "skip-in-grace-period", or "close".
+
+    Drafts are NOT skipped — the goal is "open PR count == PRs internal
+    collaborators need to action on", and a draft that Greptile scored <4/5
+    is still in that queue. Authors can opt out via the `wip` label (see
+    `DEFAULT_OPTOUT_LABELS`) if they need to keep a long-lived draft open.
+
+    Grace-period semantics: the first time a PR fails the rubric, the
+    action is `warn-grace` — the caller should post a warning comment but
+    NOT close the PR. On a subsequent run, if the warning is still less
+    than `GRACE_PERIOD_SECONDS` old AND the PR still fails, the action is
+    `skip-in-grace-period`. Once the warning ages out and the rubric is
+    still failing, the action is `close`.
+    """
+    if has_optout_label(pr, optout_labels):
+        return ("skip-optout-label", None, None)
+
+    created = parse_iso8601(pr["createdAt"])
+    age_days = (now - created).days
+    # `min_age_days` defaults to 0 (close as soon as Greptile scores low).
+    # Set a positive value via --min-age-days for one-off backfill runs that
+    # want to skip very-young PRs.
+    if min_age_days > 0 and age_days < min_age_days:
+        return ("skip-too-young", None, age_days)
+
+    # While the allowlist is active it is the sole author gate: only those
+    # logins are acted on and the external-only restriction is bypassed for
+    # them. Otherwise auto-close only external OSS contributors — internal
+    # contributors (BerriAI org members) handle their own backlog.
+    login = ((pr.get("author") or {}).get("login") or "").lower()
+    if allowlist:
+        if login not in allowlist:
+            return ("skip-not-allowlisted", None, age_days)
+    elif not is_external_pr_author(pr, repo):
+        return ("skip-internal", None, age_days)
+
+    comments = fetch_pr_comments(pr["number"], repo)
+    extraction = extract_greptile_score(comments)
+    if extraction is None:
+        return ("skip-no-greptile-score", None, age_days)
+
+    score, _ = extraction
+    if score >= min_score:
+        return ("skip-score-ok", score, age_days)
+
+    grace_age = seconds_since_last_grace_warning(comments, now=now)
+    if grace_age is None:
+        return ("warn-grace", score, age_days)
+    if grace_age < GRACE_PERIOD_SECONDS:
+        return ("skip-in-grace-period", score, age_days)
+
+    return ("close", score, age_days)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--repo",
+        type=str,
+        default=None,
+        help="Repository (owner/repo). Auto-detected if omitted.",
+    )
+    parser.add_argument(
+        "--min-age-days",
+        type=int,
+        default=0,
+        help=(
+            "Minimum age (in days) before a PR is eligible. Default 0 = "
+            "close as soon as Greptile flags it. Set a positive value for "
+            "one-off backfill runs that want to spare very-young PRs."
+        ),
+    )
+    parser.add_argument(
+        "--min-score",
+        type=int,
+        default=4,
+        choices=range(1, 6),
+        help="Greptile score below which a PR is closed (default: 4 -> closes <4/5).",
+    )
+    parser.add_argument(
+        "--optout-label",
+        action="append",
+        default=None,
+        help=(
+            "Label(s) that exempt a PR from auto-close. Repeat to add more. "
+            "Case-insensitive. When omitted, defaults to "
+            f"{list(DEFAULT_OPTOUT_LABELS)!r}; passing this flag REPLACES the "
+            "defaults (argparse `append` with a mutable default would append "
+            "instead, which we explicitly avoid)."
+        ),
+    )
+    parser.add_argument(
+        "--close-label",
+        type=str,
+        default=None,
+        help=(
+            "Optional label to add to PRs that get auto-closed "
+            "(e.g. 'auto-closed-low-quality'). Must already exist on the repo."
+        ),
+    )
+    parser.add_argument(
+        "--close",
+        action="store_true",
+        help="Actually close matching PRs (default is dry-run).",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Maximum number of PRs to close in one run (safety net).",
+    )
+    args = parser.parse_args()
+
+    dry_run = not args.close
+    if dry_run:
+        print("=== DRY RUN MODE (pass --close to actually close PRs) ===\n")
+
+    print("Fetching open PRs...")
+    prs = fetch_open_prs(args.repo)
+    print(f"Found {len(prs)} open PRs.\n")
+
+    now = dt.datetime.now(dt.timezone.utc)
+    optout_labels = set(args.optout_label or DEFAULT_OPTOUT_LABELS)
+
+    closed = 0
+    summary = {
+        "close": 0,
+        "warn-grace": 0,
+        "skip-in-grace-period": 0,
+        "skip-too-young": 0,
+        "skip-optout-label": 0,
+        "skip-not-allowlisted": 0,
+        "skip-internal": 0,
+        "skip-no-greptile-score": 0,
+        "skip-score-ok": 0,
+    }
+
+    # `warned` tracks grace-warning comments posted in this run so the
+    # `--limit` safety net bounds *all* destructive write actions, not
+    # just closures. Without this cap, a backlog of PRs failing the
+    # threshold simultaneously could flood contributors with comments.
+    warned = 0
+    for pr in sorted(prs, key=lambda p: p["createdAt"]):
+        try:
+            action, score, age_days = evaluate_pr(
+                pr,
+                now,
+                args.min_age_days,
+                args.min_score,
+                args.repo,
+                optout_labels,
+            )
+            summary[action] = summary.get(action, 0) + 1
+
+            if action == "warn-grace":
+                assert score is not None
+                print(
+                    f"#{pr['number']}: \"{pr['title']}\" "
+                    f"(age={age_days}d, greptile={score}/5) -> warn-grace"
+                )
+                post_grace_warning(
+                    pr,
+                    score=score,
+                    threshold=args.min_score,
+                    repo=args.repo,
+                    dry_run=dry_run,
+                )
+                if not dry_run:
+                    warned += 1
+                    if args.limit is not None and (warned + closed) >= args.limit:
+                        print(
+                            f"\nReached --limit={args.limit} "
+                            f"(closed={closed}, warned={warned}); stopping."
+                        )
+                        break
+                continue
+
+            if action != "close":
+                continue
+
+            assert score is not None and age_days is not None
+            print(
+                f"#{pr['number']}: \"{pr['title']}\" "
+                f"(age={age_days}d, greptile={score}/5) -> close"
+            )
+            close_pr(
+                pr,
+                score=score,
+                threshold=args.min_score,
+                age_days=age_days,
+                repo=args.repo,
+                dry_run=dry_run,
+                label=args.close_label,
+            )
+
+            if not dry_run:
+                closed += 1
+                if args.limit is not None and (warned + closed) >= args.limit:
+                    print(
+                        f"\nReached --limit={args.limit} "
+                        f"(closed={closed}, warned={warned}); stopping."
+                    )
+                    break
+        except Exception as exc:  # noqa: BLE001 - per-PR errors don't abort the sweep
+            summary["error"] = summary.get("error", 0) + 1
+            print(
+                f"!! PR #{pr.get('number')}: {exc}",
+                file=sys.stderr,
+            )
+            continue
+
+    print("\n=== Summary ===")
+    for key, value in summary.items():
+        print(f"  {key:28s} {value}")
+    if dry_run:
+        print(f"\nTotal would close: {summary['close']}")
+    else:
+        print(f"\nTotal closed: {closed}")
+    print(
+        f"Total {'would warn (grace)' if dry_run else 'warned (grace)'}: "
+        f"{summary['warn-grace']}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/scan_keywords.py

@@ -67,14 +67,13 @@ def send_webhook(webhook_url: str, payload: dict) -> None:
 def _excerpt(text: str, max_len: int = 400) -> str:
     if not text:
         return ""
-    
+
     # Keep original formatting
     if len(text) <= max_len:
         return text
     return text[: max_len - 1] + "…"
 
 
-
 def main() -> int:
     event = read_event_payload()
     if not event:
@@ -87,8 +86,19 @@ def main() -> int:
 
     # Keywords from env or defaults
     keywords_env = os.environ.get("KEYWORDS", "")
-    default_keywords = ["azure", "openai", "bedrock", "vertexai", "vertex ai", "anthropic"]
-    keywords = [k.strip() for k in keywords_env.split(",")] if keywords_env else default_keywords
+    default_keywords = [
+        "azure",
+        "openai",
+        "bedrock",
+        "vertexai",
+        "vertex ai",
+        "anthropic",
+    ]
+    keywords = (
+        [k.strip() for k in keywords_env.split(",")]
+        if keywords_env
+        else default_keywords
+    )
 
     matches = detect_keywords(combined_text, keywords)
     found = bool(matches)
@@ -129,5 +139,3 @@ def main() -> int:
 
 if __name__ == "__main__":
     raise SystemExit(main())
-
-

.github/scripts/triage-requirements.txt

@@ -0,0 +1,282 @@
+# Hash-pinned dependency set for the Agent Shin triage scripts.
+# Installed in privileged triage workflows, so every package is pinned to an
+# exact version with SHA-256 hashes and installed with pip --require-hashes.
+#
+# Regenerate after bumping openai:
+#   echo 'openai==<version>' \
+#     | uv pip compile - --generate-hashes --python-version 3.12 \
+#       --no-annotate --no-header -o .github/scripts/triage-requirements.txt
+
+annotated-types==0.7.0 \
+    --hash=sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53 \
+    --hash=sha256:aff07c09a53a08bc8cfccb9c85b05f1aa9a2a6f23728d790723543408344ce89
+anyio==4.14.0 \
+    --hash=sha256:b47c1f9ccf73e67021df785332508f99379c68fa7d0684e8e3492cb1d4b23f89 \
+    --hash=sha256:dd9b7a2a9799ed6552fde617b2c5df02b7fdd7d88392fc48101e51bae46164d9
+certifi==2026.6.17 \
+    --hash=sha256:024c88eeec92ca068db80f02b8b07c9cef7b9fe261d1d535abfd5abd6f6af432 \
+    --hash=sha256:2227dcbaafe0d2f59279d1762ddddc37783ed4354594f194ffc31d20f41fc3db
+distro==1.9.0 \
+    --hash=sha256:2fa77c6fd8940f116ee1d6b94a2f90b13b5ea8d019b98bc8bafdcabcdd9bdbed \
+    --hash=sha256:7bffd925d65168f85027d8da9af6bddab658135b840670a223589bc0c8ef02b2
+h11==0.16.0 \
+    --hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \
+    --hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86
+httpcore==1.0.9 \
+    --hash=sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55 \
+    --hash=sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8
+httpx==0.28.1 \
+    --hash=sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc \
+    --hash=sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad
+idna==3.18 \
+    --hash=sha256:7f952cbe720b688055e3f87de14f5c3e5fdaa8bc3928985c4077ca689de849a2 \
+    --hash=sha256:ffb385a7e039654cef1ab9ef32c6fafe283c0c0467bba1d9029738ce4a14a848
+jiter==0.15.0 \
+    --hash=sha256:01a8222cf05ab1128e239421156c207949808acaaea2bdfd33130ae666786e86 \
+    --hash=sha256:032396229564bca02440396bd327710719f724f5e7b7e9f7a8eb3faa4a2c2281 \
+    --hash=sha256:04b400bbf8c9efb03d9bdd976475c919c1d85593b04b9fff7ae234065daf87ae \
+    --hash=sha256:05906b93d72f03339e6bb7cf8dc10ebda64a0266126eed6beba79e20abcf5fd4 \
+    --hash=sha256:066f8f33f18b2419cd8213b2436fa7fbc9c499f315971cfa3ce1f9820c001b1b \
+    --hash=sha256:0ab068bce62a45aa3e7367eceaffb5dde60b7eb853be8dece45132e3d0ff4879 \
+    --hash=sha256:0be6f5ad41a809f303f416d17cec92a7a725902fb9b4f3de3d19362ac0ef8554 \
+    --hash=sha256:0e90a1c315a0226ec822d973817967f9223b7701546c8c2a7913e7ab0926294d \
+    --hash=sha256:0f862193b8696249d22ec433e85fd2ab0ad9596bc3e45e6c0bc55e8aeba97be2 \
+    --hash=sha256:1303d4d68a9b051ea90502402063ecf3807da00ad2affa19ca1ae3b90b3c5f67 \
+    --hash=sha256:144f8e72cb53dab146347b91cceac01f5481237f2b93b4a339a1ee8f8878b67c \
+    --hash=sha256:182226cbc930c9fab81bc2e41a4da672f89539906dadb05e75670ac07b94f71f \
+    --hash=sha256:1c11465f97e2abf45a014b83b730222f8f1c5335e802c7055a67d50de6f1f4e3 \
+    --hash=sha256:1c15024a3d892223b18f597c86d59387249dc396590844ce6b9f6131d1093bae \
+    --hash=sha256:1d54fb5b31dea401a41af3f8a7d2512e9b6a6a005491e6166c7e4ffab9639a9c \
+    --hash=sha256:25ffbe229aa8cd98c28879d8aa1a6e34ae77992ab984a65fba800859dab16269 \
+    --hash=sha256:2a77aadd57cac1682e4401a72724d2796d89a4ba129b1a5812aa94ee480826eb \
+    --hash=sha256:2ae901f3a55bfafdde31d289590fa25e3245735a2b1e8c7cc15871710a002871 \
+    --hash=sha256:2b0074e2f56eb2dacca1689760fd2852a068f85a0547a157b82cb4cafeb6768b \
+    --hash=sha256:2c8aea7781d2a372227871de4e1a1332aa96f5a89fd76c5e835dafdbad102887 \
+    --hash=sha256:2c9cb907439d20bd0c7d7565ca01ee52234203208433749bae5b516907526928 \
+    --hash=sha256:2fb6a5d26af81fc0f00f9360a891e05cf755e149bba391c4d563adc54812973d \
+    --hash=sha256:2fd73e3da91a0a722d67165e849ce2cdc10de0e0d48738c142be8c6c5f310f4c \
+    --hash=sha256:30ce1a5d16b5641dc935d50ef775af6a0871e3d14ab05d6fc54dff371b78e558 \
+    --hash=sha256:30ce785d2adb8e32c3f7741442370a74834ec4c01f3c48f0750227a0b4ef27d6 \
+    --hash=sha256:30f2218e6a9e5c18bc10fe6d41ac189c442c88eacf11bad9f28ef95a9bef00e6 \
+    --hash=sha256:351a341c2105aa430b7047e30f1bf7975f6313b00165d3fc07be2edaf741f279 \
+    --hash=sha256:37a10c377ce3a4a85f4a67f28b7afe093154cde77eaf248a72e856aa08b4d865 \
+    --hash=sha256:392b8ab019e5502d08aff85c6272209c24bc2cbe706ea82a56368f524236614a \
+    --hash=sha256:3e4540b8e74e4268811ac05db226a6a128ff572e7e0ce3f1163b693cadb184cd \
+    --hash=sha256:40b2c7e92c44a84d748d21706c68dc6ff8161d80b59c99d774721a0d2317d7c7 \
+    --hash=sha256:411fa4dfa5a7ae3d11491027ffb9beadec3996010a986862db70d91abba1c750 \
+    --hash=sha256:4251acc80e2b7c9b7b8823456ea0fceeb0734dac2df7636d3c711b38476b5a76 \
+    --hash=sha256:42bfb257930800cf43e7c62c832402c704ab60797c992faf88d20e903eac8f32 \
+    --hash=sha256:4363818355dbc70ae1a8e9eaba9de350d93ede4ff6992b8f8eb8cbb6e5122d42 \
+    --hash=sha256:4ab395feec8d249ec4044e228e98a7033f043426a265df439dc3698823f0a4e4 \
+    --hash=sha256:50164d7610c00e7cd913a873fce30b6beeebf4b37e53983e33f22de4c900f6b8 \
+    --hash=sha256:50e51156192722a9c58db112837d3f8ef96fb3c5ecc14e95f409134b08b158ec \
+    --hash=sha256:510c8b3c17a0ed9ac69850c0438dada3c9b82d9c4d589fcb62002a5a9cf3a866 \
+    --hash=sha256:5157de9f76eb4bc5ea74a1219366a25f945ad305641d74e04f59c54087091aa9 \
+    --hash=sha256:54d5d6090cdc1b7c9e780dfb04949a990adb1e301a2fc0bbcee7de4638d33f9a \
+    --hash=sha256:553fcac2ef2cb990877f9fc0833b8b629a3e6a5670b6b5fd58219b41a653ddc4 \
+    --hash=sha256:5607e6013ed7e6b0ec9661e467b7ffde0aa7ab36833a04850f26fcf88ed4845b \
+    --hash=sha256:5d6a60072b44c3c2b797a7ddcbcbbf2b34ea3cfd4721580fbfd2a09d9d9b84ba \
+    --hash=sha256:5f30bae8bc1c2d613e28e5af3e8cceb09b742f1c8a8a5f839fb67afaffc03b61 \
+    --hash=sha256:62ebd14e47e9aed9df4472afcb2663668ce4d74891cd54f86bf6e44029d6dc89 \
+    --hash=sha256:631f13a3d04e97d4e083993b10f4b99530e3a10d953e2eb5e196b7dc7f812ce0 \
+    --hash=sha256:6550fa135c7deb8ead6af49ed7ff648532ea8334a1447fe34a36315ef79c5c29 \
+    --hash=sha256:66b1880df2d01e206e8339769d1c7c1753bcb653efd6289e203f6f24ebada0c0 \
+    --hash=sha256:6eac374c5c975709b69c10f09afd199df74150172156ad10c8d4fd785b7da995 \
+    --hash=sha256:71683c38c825452999b5717fcae07ea708e8c93003e808be4319c1b02e3d176e \
+    --hash=sha256:7553333dd0930c104a5a0db8df72bf7219fe663d731383b576bb6ed6351c984d \
+    --hash=sha256:75e8a04e91432dde9f1838373cf93d23726c79d3e908d319acf0e796f85592e7 \
+    --hash=sha256:773b6eb282ce11ee19f05f6b2d4404fa308e5bbd353b0b80a0262caad6db2cd7 \
+    --hash=sha256:774f93f65031856bf14ad9f59bdcab8b8cad501e5ceabd51ba3525f76937a25b \
+    --hash=sha256:7c468136b8bd6bb18c8786e4236a1fa27362f24cb23450ba0cb204ab379b8e6f \
+    --hash=sha256:7ce8902f939970048b233087082e7bb829db29375811c7ad50687b8624c6fd08 \
+    --hash=sha256:7d3d6683288c11cbab50e865f2e2f13950179aa45410e30b2cfbd3fb7b0177bf \
+    --hash=sha256:7f6163c0f10b055245f814dcc59f4818da60dfe72f3e72ab89fc24b6bd5e9c52 \
+    --hash=sha256:8020c99ec13a7db2b6f96cbe82ef4721c88b426a4892f27478044af0284615ef \
+    --hash=sha256:813dfbb17d65328bf86e5f0905dd277ba2265d3ca20556e86c0c7035b7182e5a \
+    --hash=sha256:860a74063284a2ae9bfedd694f299cc2c68e2696c5f3d440cc9d18bb81b9dd04 \
+    --hash=sha256:8c9004af7c8d67cce7f1aae1026fb55607f4aa600710d08ede3a3ce4aeefe7e0 \
+    --hash=sha256:8d2c0c44d569ce0f2850f5c926f8caeb5f245fbc84475aeb36efccc2103e6dbd \
+    --hash=sha256:8f7e9bc0f1135039b22ee6eab588d42df1ce55842b30740a352885eb267bd941 \
+    --hash=sha256:90c5db5527c221249a876160663ab891ace358c17f7b9c93ec1478b7f0550e5c \
+    --hash=sha256:9100ddbec09741cc66feb0fc6773f8bdbd0e3c345689368f260082ff85dcc0cd \
+    --hash=sha256:913d02d29c9606643418d9ccfc3b72492ab25a6bf7889934e09a3490f8d3438b \
+    --hash=sha256:980c256edb05b78a111b99c4de3b1d32e31634b867fd1fc2cf726e7b7bba9854 \
+    --hash=sha256:9f924585cdacf631cd382b657966847bb537bf9ed0a6f9b991da5f05a631480f \
+    --hash=sha256:a254e10b593624d230c365b6d616b22ca0ad65e63a16e6631c2b3466022e6ba8 \
+    --hash=sha256:a2a438005b6f22d0273413484d6094d7c2c5d10ec1b3a3bf128e0d1d3ba53258 \
+    --hash=sha256:a97261f1fccb8e50ecd2890a96e46efdc3f57c80a197324c6777827231eca712 \
+    --hash=sha256:ab596fa3837e91e7e6a31b5f639988bfc6a35d1f915ac3932d946062219d588f \
+    --hash=sha256:abbf258599526ad0326fe51e252e24f2bd6f24f1852681b4b78feda3808f1d18 \
+    --hash=sha256:ac0d9ddea4350974be7a221fc25895f251a8fee748c889bdced2141c0fec1a49 \
+    --hash=sha256:acf4ee4d1fc55917239fe72972fb292dd773055d05eb040d36f4326e02cc2c0e \
+    --hash=sha256:ae1b0d82ac2d987f9ea512b1c9adfcc71a28de3dea3a6039b54d76cffda9901e \
+    --hash=sha256:b15741f501469009ae0ae90b7147958a664a7dede40aa7ff174a8a4645f546d0 \
+    --hash=sha256:b15d3ec9b0449c40e85319bdb4caa8b77ab526e74f5532ed94bec15e2f66822c \
+    --hash=sha256:b3b3b775e33d3bfaec9899edc526ae97b0da0bf9d071a46124ba419149a414f8 \
+    --hash=sha256:b6c0ffae686c39bf3737be60793783267628783ea42545632c10b291105aee45 \
+    --hash=sha256:c210f8b35dc6f30aafd4b4365ca89b9d1189f21ab49b8e68fa6322a847aef138 \
+    --hash=sha256:c2f6bb8b5216ab9e7873bc08b5d7bef2b8abbb578a3069bf1cd14a45d71d771d \
+    --hash=sha256:c60e71b6d10cfc284c9bf36bd885e8d44c46f688ce50aa91b5edd90181dea687 \
+    --hash=sha256:c6694a173ecabc12eb60efbc0b474464ead1951ff65cd8b1e72100715c64512b \
+    --hash=sha256:c77496cb10bd7549690fbbab3e5ec05857b83e49276f4a9423a766ddd2afcd4c \
+    --hash=sha256:c84c1b7be454b0c16f8499b4ebfbfd82ea5cca6527cceefcbbc06a7557b5ed2e \
+    --hash=sha256:cc0bc345cf2df9d1c00ac443f50d543c1ccfa8b0422cb85b1ab70d681c0b255b \
+    --hash=sha256:ceb8fc27d38793f9c97149be8302720c5b22e5c195a37bf2c45dc36c4600a512 \
+    --hash=sha256:cf4bd113a69c0a740e27cb962ce10630c36d2b8f59d759a651b955ee9d18a823 \
+    --hash=sha256:d1aa62e277fc1cbd80e6deacae6f4d983b41b3d7728e0645c5d741a6149bba45 \
+    --hash=sha256:d1e7b1776f0797956c509e123d0952d10d293a9492dea9f288ab9570ec01d1a5 \
+    --hash=sha256:d636d5095155afd364247f65070fab7beda13498d7ff4de331046e704ab9657f \
+    --hash=sha256:d726e3ceeb337191324b49de298142f27c3ad10886341555d1d5315b5f252c6a \
+    --hash=sha256:d72d8af5c1013656a8870c866660627d1a75bc185814ee022c8533caa1de88ae \
+    --hash=sha256:d8d2955167274e15d79a7a020afdd9b39c990eb80b2d89fca695d92dcfdd38ec \
+    --hash=sha256:d92a5cd21fdb083931d546c207aa29633787c5dc5b02daab2d32b843f88a2c53 \
+    --hash=sha256:e58585a58209d72691ce2d62a9147445f5a87beb0bde97fde284c96ae392a3d1 \
+    --hash=sha256:e7196e56f1cd69af1dbb07dff02dcfb260a50b45a82d409d92a06fedb32473b5 \
+    --hash=sha256:eda3071db3346334beae1360b46da4606da57bf3528c167b3c38533afaf9f2c5 \
+    --hash=sha256:edebcf7d1f601199084bb6e844d7dc67e03e04f6ac786b0332d616635c4ff7a4 \
+    --hash=sha256:ef1fd24d9413f6209e00d3d5a453e67acfe004a25cc6c8e8484faed4311ab9e8 \
+    --hash=sha256:f0b271b462769543716f92d3a4f90527df6ef5ed05ee95ec4137f513e21e1b77 \
+    --hash=sha256:f18f85e4218d1b40f000f42a92239a7a61a902cd42c65e6c360dbd17dcb20894 \
+    --hash=sha256:f1e1754960f38ec40613a07e5e372df67acb3b890fb383b6fb3de3e49ddbf3c7 \
+    --hash=sha256:f2143ab06181d2b029eedcb6af3cebe95f11bbac62441781860f98ee9330a6a6 \
+    --hash=sha256:f3d37768fce7f88dd2a8c6091f2325dea27d30d30d5c6e7a1c0f0af77723b708 \
+    --hash=sha256:fa248c9eb220197d363f688818dac2fd4b2f0cd7d843ca7105d652034823427d
+openai==2.33.0 \
+    --hash=sha256:03ac37d70e8c9e3a8124214e3afa785e2cbc12e627fbd98177a086ef2fd87ad5 \
+    --hash=sha256:f850c435e2a4685bba3295bd54912dd26315d9c1b7733068186134d6e0599f9a
+pydantic==2.13.4 \
+    --hash=sha256:45a282cde31d808236fd7ea9d919b128653c8b38b393d1c4ab335c62924d9aba \
+    --hash=sha256:c40756b57adaa8b1efeeced5c196f3f3b7c435f90e84ea7f443901bec8099ef6
+pydantic-core==2.46.4 \
+    --hash=sha256:00c603d540afdd6b80eb39f078f33ebd46211f02f33e34a32d9f053bba711de0 \
+    --hash=sha256:0186750b482eefa11d7f435892b09c5c606193ef3375bcf94aa00ae6bfb66262 \
+    --hash=sha256:041bde0a48fd37cf71cab1c9d56d3e8625a3793fef1f7dd232b3ff37e978ecda \
+    --hash=sha256:0c563b08bca408dc7f65f700633d8442fffb2421fc47b8101377e9fd65051ff0 \
+    --hash=sha256:0cbe8b01f948de4286c74cdd6c667aceb38f5c1e26f0693b3983d9d74887c65e \
+    --hash=sha256:0ce40cd7b21210e99342afafbd4d0f76d784eb5b1d60f3bdc566be4983c6c73b \
+    --hash=sha256:0e96592440881c74a213e5ad528e2b24d3d4f940de2766bed9010ab1d9e51594 \
+    --hash=sha256:10e17cbb10a330363733efc4d7c4d0dd827ac0909b8f6a6542298fed1ea62f29 \
+    --hash=sha256:133878133d271ade3d41d1bfb2a45ec38dbdbda40bc065921c6b04e4630127e2 \
+    --hash=sha256:14d4edf427bdcf950a8a02d7cb44a08614388dd6e1bdcbf4f67504fa7887da9c \
+    --hash=sha256:14f4c5d6db102bd796a627bbb3a17b4cf4574b9ae861d8b7c9a9661c6dd3362d \
+    --hash=sha256:17299feefe090f2caa5b8e37222bb5f663e4935a8bfa6931d4102e5df1a9f398 \
+    --hash=sha256:184c081504d17f1c1066e430e117142b2c77d9448a97f7b65c6ac9fd9aee238d \
+    --hash=sha256:18e5ceec2ab67e6d5f1a9085e5a24c9c4e2ac4545730bfe668680bca05e555f3 \
+    --hash=sha256:19e51f073cd3df251856a8a4189fbdf1de4012c3ebacfb1884f94f1eb406079f \
+    --hash=sha256:1a7dd0b3ee80d90150e3495a3a13ac34dbcbfd4f012996a6a1d8900e91b5c0fb \
+    --hash=sha256:1d8ba486450b14f3b1d63bc521d410ec7565e52f887b9fb671791886436a42f7 \
+    --hash=sha256:2108ba5c1c1eca18030634489dc544844144ee36357f2f9f780b93e7ddbb44b5 \
+    --hash=sha256:228ee9bae8bef5b1e97ec58302f80357c37199e0d0a99174e138d28e6957b9d9 \
+    --hash=sha256:23ace664830ee0bfe014a0c7bc248b1f7f25ed7ad103852c317624a1083af462 \
+    --hash=sha256:2412e734dcb48da14d4e4006b82b46b74f2518b8a26ee7e58c6844a6cd6d03c4 \
+    --hash=sha256:29c61fc04a3d840155ff08e475a04809278972fe6aef51e2720554e96367e34b \
+    --hash=sha256:2f84c03c8607173d16b5a854ec68a2f9079ae03237a54fb506d13af47e1d018d \
+    --hash=sha256:3009f12e4e90b7f88b4f9adb1b0c4a3d58fe7820f3238c190047209d148026df \
+    --hash=sha256:3245406455a5d98187ec35530fd772b1d799b26667980872c8d4614991e2c4a2 \
+    --hash=sha256:3447661d99f75a3683a4cf5c87da72f2161964611864dbbeac7fbb118bb4bfc0 \
+    --hash=sha256:372429a130e469c9cd698925ce5fc50940b7a1336b0d82038e63d5bbc4edc519 \
+    --hash=sha256:395aebd9183f9d112f569aeb5b2214d1a10a33bec8456447f7fbdfa51d38d4cd \
+    --hash=sha256:3a233125ac121aa3ffba9a2b59edfc4a985a76092dc8279586ab4b71390875e7 \
+    --hash=sha256:3be77f45df024d789a672ae34f8b06fb346c4f9f46ea714956660ea4862e89ac \
+    --hash=sha256:3bf92c5d0e00fefaab325a4d27828fe6b6e2a21848686b5b60d2d9eeb09d76c6 \
+    --hash=sha256:3ecbc122d18468d06ca279dc26a8c2e2d5acb10943bb35e36ae92096dc3b5565 \
+    --hash=sha256:3fb702cd90b0446a3a1c5e470bfa0dd23c0233b676a9099ddcc964fa6ca13898 \
+    --hash=sha256:428e04521a40150c85216fc8b85e8d39fece235a9cf5e383761238c7fa9b96fb \
+    --hash=sha256:432c179df7874eeb73307aad2df0755e1ae0efa61ff0ea89b93e194411ae3928 \
+    --hash=sha256:4a05d69cba51d852c5c3e92758653245a50c0b646ced0cf05bd793ed592839d6 \
+    --hash=sha256:4c63ebc82684aa89d9a3bcbd13d515b3be44250dc68dd3bd81526c1cb31286c3 \
+    --hash=sha256:4fc73cb559bdb54b1134a706a2802a4cddd27a0633f5abb7e53056268751ac6a \
+    --hash=sha256:4fcbe087dbc2068af7eda3aa87634eba216dbda64d1ae73c8684b621d33f6596 \
+    --hash=sha256:56cb4851bcaf3d117eddcef4fe66afd750a50274b0da8e22be256d10e5611987 \
+    --hash=sha256:5855698a4856556d86e8e6cd8434bc3ac0314ee8e12089ae0e143f64c6256e4e \
+    --hash=sha256:5a4330cdbc57162e4b3aa303f588ba752257694c9c9be3e7ebb11b4aca659b5d \
+    --hash=sha256:5b712b53160b79a5850310b912a5ef8e57e56947c8ad690c227f5c9d7e561712 \
+    --hash=sha256:5d5902252db0d3cedf8d4a1bc68f70eeb430f7e4c7104c8c476753519b423008 \
+    --hash=sha256:617d7e2ca7dcb8c5cf6bcb8c59b8832c94b36196bbf1cbd1bfb56ed341905edd \
+    --hash=sha256:62f875393d7f270851f20523dd2e29f082bcc82292d66db2b64ea71f64b6e1c1 \
+    --hash=sha256:633147d34cf4550417f12e2b1a0383973bdf5cdfde212cb09e9a581cf10820be \
+    --hash=sha256:66ce7632c22d837c95301830e111ad0128a32b8207533b60896a96c4915192ea \
+    --hash=sha256:6b3ace8194b0e5204818c92802dcdca7fc6d88aabbb799d7c795540d9cd6d292 \
+    --hash=sha256:6f2eeda33a839975441c86a4119e1383c50b47faf0cbb5176985565c6bb02c33 \
+    --hash=sha256:7027560ee92211647d0d34e3f7cd6f50da56399d26a9c8ad0da286d3869a53f3 \
+    --hash=sha256:7283d57845ecf5a163403eb0702dfc220cc4fbdd18919cb5ccea4f95ee1cdab4 \
+    --hash=sha256:7a5f930472650a82629163023e630d160863fce524c616f4e5186e5de9d9a49b \
+    --hash=sha256:7bfb192b3f4b9e8a89b6277b6ce787564f62cfd272055f6e685726b111dc7826 \
+    --hash=sha256:811ff8e9c313ab425368bcbb36e5c4ebd7108c2bbf4e4089cfbb0b01eff63fac \
+    --hash=sha256:8233f2947cf85404441fd7e0085f53b10c93e0ee78611099b5c7237e36aacbf7 \
+    --hash=sha256:82cf5301172168103724d49a1444d3378cb20cdee30b116a1bd6031236298a5d \
+    --hash=sha256:8358a950c8909158e3df31538a7e4edc2d7265a7c54b47f0864d9e5bae9dcebf \
+    --hash=sha256:85bb3611ff1802f3ee7fdd7dbff26b56f343fb432d57a4728fdd49b6ef35e2f4 \
+    --hash=sha256:86e1a4418c6cd97d60c95c71164158eaf7324fae7b0923264016baa993eba6fc \
+    --hash=sha256:8b9bab013d1c7a79d3501ff86d0bc9c31bf587db4551677b96bec07df78c6b15 \
+    --hash=sha256:8c5dac79fa1614d1e06ca695109c6105923bd9c7d1d6c918d4e637b7e6b32fd3 \
+    --hash=sha256:8d0820e8192167f80d88d64038e609c31452eeca865b4e1d9950a27a4609b00b \
+    --hash=sha256:8daafc69c93ee8a0204506a3b6b30f586ef54028f52aeeeb5c4cfc5184fd5914 \
+    --hash=sha256:9037063db01f09b09e237c282b6792bd4da634b5402c4e7f0c61effed7701a04 \
+    --hash=sha256:905a0ed8ea6f2d61c1738835f99b699348d7857379083e5fc497fa0c967a407c \
+    --hash=sha256:90884113d8b48f760e9587002789ddd741e76ab9f89518cd1e43b1f1a52ec44b \
+    --hash=sha256:91a06d2e259ecfbd8c901d70c3c507900458498142b3026a296b7de4d1322cc9 \
+    --hash=sha256:926c9541b14b12b1681dca8a0b75feb510b06c6341b70a8e500c2fdcff837cce \
+    --hash=sha256:9401557acd873c3a7f3eb9383edef8ac4968f9510e340f4808d427e75667e7b4 \
+    --hash=sha256:9551187363ffc0de2a00b2e47c25aeaeb1020b69b668762966df15fc5659dd5a \
+    --hash=sha256:962ccbab7b642487b1d8b7df90ef677e03134cf1fd8880bf698649b22a69371f \
+    --hash=sha256:97e7cf2be5c77b7d1a9713a05605d49460d02c6078d38d8bef3cbe323c548424 \
+    --hash=sha256:9aa768456404a8bf48a4406685ac2bec8e72b62c69313734fa3b73cf33b3a894 \
+    --hash=sha256:9bc519fbf2b7578398853d815009ae5e4d4603d12f4e3f91da8c06852d3da3e9 \
+    --hash=sha256:9d56801be94b86a9da183e5f3766e6310752b99ff647e38b09a9500d88e46e76 \
+    --hash=sha256:9f444c499b3eefd3a92e348059471ea0c3a6e303d9c1cec09fa748fd9f895201 \
+    --hash=sha256:9fa8ae11da9e2b3126c6426f147e0fba88d96d65921799bb30c6abd1cb2c97fb \
+    --hash=sha256:a0f62d0a58f4e7da165457e995725421e0064f2255d8eccebc49f41bbc23b109 \
+    --hash=sha256:a396dcc17e5a0b164dbe026896245a4fa9ff402edca1dff0be3d53a517f74de4 \
+    --hash=sha256:aaa2a54443eff1950ba5ddc6b6ccda0d9c84a364276a62f969bdf2a390650848 \
+    --hash=sha256:ad785e92e6dc634c21555edc8bd6b64957ab844541bcb96a1366c202951ae526 \
+    --hash=sha256:af8244b2bef6aaad6d92cda81372de7f8c8d36c9f0c3ea36e827c60e7d9467a0 \
+    --hash=sha256:b078afbc25f3a1436c7a1d2cd3e322497ee99615ba97c563566fdf46aff1ee01 \
+    --hash=sha256:b2f69dec1725e79a012d920df1707de5caf7ed5e08f3be4435e25803efc47458 \
+    --hash=sha256:b8458003118a712e66286df6a707db01c52c0f52f7db8e4a38f0da1d3b94fc4e \
+    --hash=sha256:bb63e0198ca18aad131c089b9204c23079c3afa95487e561f4c522d519e55aba \
+    --hash=sha256:bfec22eab3c8cc2ceec0248aec886624116dc079afa027ecc8ad4a7e62010f8a \
+    --hash=sha256:c1747f85cee84c26985853c6f3d9bd3e75da5212912443fa111c113b9c246f39 \
+    --hash=sha256:c1b3f518abeca3aa13c712fd202306e145abf59a18b094a6bafb2d2bbf59192c \
+    --hash=sha256:c50f2528cf200c5eed56faf3f4e22fcd5f38c157a8b78576e6ba3168ec35f000 \
+    --hash=sha256:c68fcd102d71ea85c5b2dfac3f4f8476eff42a9e078fd5faefff6d145063536b \
+    --hash=sha256:c7a7bd4e39e8e4c12c39cd480356842b6a8a06e41b23a55a5e3e191718838ddf \
+    --hash=sha256:c94f0688e7b8d0a67abf40e57a7eaaecd17cc9586706a31b76c031f63df052b4 \
+    --hash=sha256:cbaf13819775b7f769bf4a1f066cb6df7a28d4480081a589828ef190226881cd \
+    --hash=sha256:cd2213145bcc2ba85884d0ac63d222fece9209678f77b9b4d76f054c561adb28 \
+    --hash=sha256:ce5c1d2a8b27468f433ca974829c44060b8097eedc39933e3c206a90ee49c4a9 \
+    --hash=sha256:d396ec2b979760aaf3218e76c24e65bd0aca24983298653b3a9d7a45f9e47b30 \
+    --hash=sha256:d51026d73fcfd93610abc7b27789c26b313920fcfb20e27462d74a7f8b06e983 \
+    --hash=sha256:d80ee3d731373b24cebbc10d689ca4ee1875caf0d5703a245db18efd4dd37fc1 \
+    --hash=sha256:d995260fdf4e1db774581b4900e0f832abe3c7c84996726bbc161b19c8f29e76 \
+    --hash=sha256:da4b951fe36dc7c3a1ccb4e3cd1747c3542b8c9ceede8fc86cae054e764485f5 \
+    --hash=sha256:daa27d92c36f24388fe3ad306b174781c747627f134452e4f128ea00ce1fe8c4 \
+    --hash=sha256:db06ffe51636ffe9ca531fe9023dd64bdd794be8754cb5df57c5498ae5b518a7 \
+    --hash=sha256:e0d65b8c354be7fb5f720c3caa8bc940bc2d20ce749c8e06135f07f8ed95dd7c \
+    --hash=sha256:e68b7a074f65a2fd746c52a7ce6142ab7006074ac269ace0c25cd8ba171f8066 \
+    --hash=sha256:e739fee756ba1010f8bcccb534252e85a35fe45ae92c295a06059ce58b74ccd3 \
+    --hash=sha256:e846ae7835bf0703ae43f534ab79a867146dadd59dc9ca5c8b53d5c8f7c9ef02 \
+    --hash=sha256:e9c26f834c65f5752f3f06cb08cb86a913ceb7274d0db6e267808a708b46bc89 \
+    --hash=sha256:ea793e075b70290d89d8142074262885d3f7da19634845135751bd6344f73b50 \
+    --hash=sha256:f027324c56cd5406ca49c124b0db10e56c69064fec039acc571c29020cc87c76 \
+    --hash=sha256:f13a646d65d09fbf1bc6b3a9635d30095c8e7e5cc419ff35ecc563c5fd04cd49 \
+    --hash=sha256:f47286a97f0bc9b8859519809077b91b2cefe4ae47fcbf5e466a009c1c5d742b \
+    --hash=sha256:f747929cf940cddb5b3668a390056ddd5ba2e5010615ea2dcf4f9c4f3ab8791d \
+    --hash=sha256:f99626688942fb746e545232e7726926f3be91b5975f8b55327665fafda991c7 \
+    --hash=sha256:f9fa868638bf362d3d138ea55829cefb3d5f4b0d7f142234382a15e2485dbec4 \
+    --hash=sha256:fbdb89b3e1c94a30cc5edfce477c6e6a5dc4d8f84665b455c27582f211a1c72c \
+    --hash=sha256:fc010ab034c8c7452522748bf937df58020d256ccae0874463d1f4d01758af8e \
+    --hash=sha256:fc3e9034a63de20e15e8ade85358bc6efc614008cab72898b4b4952bea0509ff \
+    --hash=sha256:fd8b3d9fd264be37976686c7f65cd52a83f5e84f4bfd2adf9c1d469676bbb6ae
+sniffio==1.3.1 \
+    --hash=sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2 \
+    --hash=sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc
+tqdm==4.68.3 \
+    --hash=sha256:00dfa48452b6b6cfae3dd9885636c23d3422d1ec97c66d96818cbd5e0821d482 \
+    --hash=sha256:39832cc2def2789a6f29df83f172db7416cea70052c0907a57801c5f2fdccb03
+typing-extensions==4.15.0 \
+    --hash=sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466 \
+    --hash=sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548
+typing-inspection==0.4.2 \
+    --hash=sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7 \
+    --hash=sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464

.github/scripts/triage_rollout_heads_up.py

@@ -0,0 +1,557 @@
+#!/usr/bin/env python3
+"""One-shot 7-day heads-up sweep for the Agent Shin rollout.
+
+Posts a friendly "the OSS triage bot kicks in next Monday" comment on every
+open external PR/issue that currently *would* fail the new rubric — i.e.,
+every PR/issue Agent Shin would close once the rollout completes. The point
+is to give contributors a full week to fix their description before the bot
+ever takes a destructive action, so nobody is surprised by an auto-close.
+
+The script is designed to run **exactly once** at rollout, fired by a manual
+``workflow_dispatch`` (``dry_run=false``) on the heads-up workflow. Re-runs
+are safe: every comment is stamped with the hidden ``HEADS_UP_MARKER`` and
+PRs/issues that already carry the marker are skipped.
+
+Dry-run vs. real run
+--------------------
+Defaults to dry-run. Passing ``--close`` flips into real mode. Every GitHub
+mutation goes through ``_agent_shin_actions``, which has a one-line
+``if dry_run: log else: do_it`` per call, so the only difference between a
+dry-run preview and the real run is the call site that actually hits the
+GitHub API.
+
+Local preview::
+
+    python3 .github/scripts/triage_rollout_heads_up.py --repo BerriAI/litellm
+
+Real run (the manual rollout dispatch uses this)::
+
+    python3 .github/scripts/triage_rollout_heads_up.py --repo BerriAI/litellm --close
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+# Make the sibling triage_with_llm + _agent_shin_actions importable when this
+# script is invoked directly (the GitHub workflow does `python3 .github/scripts/...`).
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from _agent_shin_actions import maybe_post_comment  # noqa: E402
+from agent_shin_shared import (  # noqa: E402
+    AGENT_SHIN_DEFAULT_BOT_LOGIN,
+    ALLOWLIST_LOGINS,
+    list_open_items,
+)
+from triage_with_llm import (  # noqa: E402
+    DEFAULT_MODEL,
+    call_llm_judge,
+    fetch_issue,
+    fetch_pr,
+    gh,
+    is_internal_contributor,
+    review_gate,
+    triage,
+)
+
+# Hidden marker so re-runs skip PRs/issues we've already notified. Distinct from
+# the within-grace / ready / regressed markers so it can't be confused with the
+# steady-state lifecycle comments.
+HEADS_UP_MARKER = "<!-- agent-shin:rollout-heads-up -->"
+
+# Placeholder until the litellm-docs PR ships. The rollout blog post explains
+# the new rubric, the 7-day grace, and how to recover after an auto-close.
+# TODO(docs): replace with the canonical URL once the litellm-docs PR merges.
+ROLLOUT_BLOG_URL = "https://docs.litellm.ai/docs/agent_shin_triage_rollout"
+
+# Default cutoff is one week from "now". Computed at runtime so the wording
+# stays correct even if the rollout is merged later than planned. The user can
+# override with --close-on YYYY-MM-DD when running the script manually.
+DEFAULT_GRACE_DAYS = 7
+
+# The daily auto-close sweeps (close_low_quality_prs.yml at 09:00 UTC and
+# review_gate.yml at 09:30 UTC) are what actually close a still-failing item,
+# so the deadline we promise contributors has to name that wall-clock moment.
+ACTIVATION_TIME_UTC = "09:00 UTC"
+
+
+def _format_cutoff(cutoff: dt.date) -> str:
+    """Human-readable, timezone-explicit cutoff, e.g. ``Monday, June 1, 2026
+    (09:00 UTC)`` — the moment a still-failing PR/issue gets closed."""
+    return (
+        f"{cutoff.strftime('%A, %B')} {cutoff.day}, {cutoff.year} "
+        f"({ACTIVATION_TIME_UTC})"
+    )
+
+
+def _rubric_section_pr() -> str:
+    return (
+        "**Going forward, every external PR needs ONE of:**\n"
+        "\n"
+        "- A linked GitHub issue using a closing keyword: "
+        "`Fixes #1234`, `Closes #1234`, or `Resolves #1234`, OR\n"
+        "- All three of: a clear **problem description**, **expected vs. "
+        "actual behavior**, and **end-to-end QA proof** (at least one of a "
+        "short screen recording / video, before/after screenshots, or the "
+        "exact commands you ran with their real output; mocked or stubbed "
+        "runs don't count).\n"
+        "\n"
+        "PRs also need a **Greptile confidence score of 4/5 or higher** before "
+        "the bot will tag them `ready for review`. You can `@greptileai` to "
+        "request a fresh review at any time, including after the PR is closed."
+    )
+
+
+def _rubric_section_issue() -> str:
+    return (
+        "**Going forward, every external issue needs:**\n"
+        "\n"
+        "- For **bug reports**: end-to-end evidence of the bug (at least one "
+        "of a screen recording / video, a screenshot, or the exact commands "
+        "you ran with their real output / traceback) plus expected vs. actual "
+        "behavior. Written steps with no run output don't count, and mocked "
+        "or stubbed runs don't count.\n"
+        "- For **feature requests**: a clear description of the proposed "
+        "feature plus a use case + concrete example (config, API call, UI "
+        "flow, or scenario showing what's blocked today)."
+    )
+
+
+def _description_only_note(kind: str) -> str:
+    noun = "PR" if kind == "pr" else "issue"
+    return (
+        f"⚠️ **The requirements must live in the {noun} *description*, not in "
+        "comments.** Some PRs/issues collect 100+ comments from humans and "
+        "bots; reading the entire thread on every triage run would balloon "
+        "GitHub API usage (we'd start getting 429'd) and blow out the LLM "
+        "judge's context. The bot only reads the description, so anything "
+        "you add as a comment will be invisible to it."
+    )
+
+
+def _missing_section(verdict: dict, greptile_score: int | None) -> str:
+    """Bullet list of what's currently missing on this PR/issue.
+
+    Combines the LLM judge's `missing` list (rubric items) with a Greptile
+    shortfall (for PRs) so the contributor sees one list of things to fix.
+    """
+    missing = list(verdict.get("missing") or [])
+    if greptile_score is not None and greptile_score < 4:
+        missing.insert(
+            0,
+            f"Greptile's most recent review scored this PR {greptile_score}/5 "
+            "(below the 4/5 bar Agent Shin will require).",
+        )
+    if not missing:
+        return (
+            "_The bot couldn't articulate a specific missing piece; see the "
+            "rubric link above and double-check the description includes all "
+            "of it before the rollout._"
+        )
+    bullets = "\n".join(f"- {m}" for m in missing)
+    return f"**What this one is currently missing:**\n\n{bullets}"
+
+
+def _recovery_section(kind: str) -> str:
+    if kind == "pr":
+        return (
+            "**If the bot closes this PR after the rollout:** update the "
+            "description with the missing pieces, then either open a fresh "
+            "PR or comment `@agent-shin reconsider` on the closed PR. If "
+            "Greptile re-scores you at 4/5 or higher I'll reopen and tag "
+            "the PR `ready for review`. (`@greptileai` works on closed PRs "
+            "too; a fresh review is one of the signals that lifts you back "
+            "into the queue.) This is **not** us losing interest in your "
+            "change; far from it. We just need open PRs to be a list of "
+            "things a maintainer can act on, so we can get to yours faster."
+        )
+    return (
+        "**If the bot closes this issue after the rollout:** edit the issue "
+        "description to add the missing pieces, then comment `@agent-shin "
+        "reconsider` on the closed issue. I'll re-evaluate and, if the rubric "
+        "is met, reopen it. (GitHub doesn't let external authors reopen an "
+        "issue a maintainer or bot closed, so the comment is the reliable "
+        "path.) This is **not** us saying the bug isn't real or the request "
+        "isn't useful; it's so the remaining open issues are a list of things "
+        "a maintainer can act on."
+    )
+
+
+def format_heads_up_comment(
+    *, kind: str, verdict: dict, greptile_score: int | None, cutoff: dt.date
+) -> str:
+    """Compose the friendly 7-day heads-up comment posted on a failing PR/issue."""
+    noun = "PR" if kind == "pr" else "issue"
+    rubric = _rubric_section_pr() if kind == "pr" else _rubric_section_issue()
+    cutoff_str = _format_cutoff(cutoff)
+    explanation = (verdict.get("explanation") or "").strip()
+    explanation_block = (
+        f"> _(The judge's note for this one: {explanation})_\n\n" if explanation else ""
+    )
+
+    return (
+        "🚅 **Heads-up: we're turning on the OSS triage bot in "
+        f"{DEFAULT_GRACE_DAYS} days, on {cutoff_str}.**\n"
+        "\n"
+        "We're rolling out **Agent Shin**, an LLM-as-judge triage bot for "
+        f"external {noun}s. Once it's live, the bot reads each open "
+        f"{noun}'s description, scores it against a small rubric, and "
+        f"auto-closes any {noun} that's missing the basics, with a single "
+        f"comment explaining what's missing and how to recover. Full "
+        f"context: [Agent Shin rollout blog post]({ROLLOUT_BLOG_URL}).\n"
+        "\n"
+        f"{rubric}\n"
+        "\n"
+        f"{_description_only_note(kind)}\n"
+        "\n"
+        f"{_missing_section(verdict, greptile_score)}\n"
+        "\n"
+        f"{explanation_block}"
+        "**Timeline (you have a week):**\n"
+        "\n"
+        f"- We turn the bot on in {DEFAULT_GRACE_DAYS} days, on "
+        f"**{cutoff_str}**. You have until then to update this {noun}'s "
+        "description with the missing pieces above.\n"
+        f"- If this {noun} still fails the rubric at **{cutoff_str}**, "
+        "we'll close it.\n"
+        f"- From then on the bot runs daily, and every {noun} that fails "
+        "the rubric gets a **2-hour lifetime**: one warning comment, then "
+        "auto-close 2 hours later.\n"
+        "\n"
+        f"{_recovery_section(kind)}\n"
+        "\n"
+        f"{HEADS_UP_MARKER}"
+    )
+
+
+def _list_open_numbers(repo: str, kind: str) -> list[int]:
+    """Return every open PR or issue number in ``repo``.
+
+    Delegates to ``list_open_items`` so the full backlog is fetched (no cap)
+    and the `gh {pr,issue} list` invocation stays in one shared place. ``gh
+    issue list`` would include PRs, but ``list_open_items`` uses the dedicated
+    command per kind, so the two never mix.
+    """
+    return [
+        item["number"] for item in list_open_items(kind, repo=repo, fields="number")
+    ]
+
+
+def _has_heads_up_marker(item: dict) -> bool:
+    """Cheap fast-path: check the PR/issue body itself for the marker.
+
+    The marker is appended to the *comment* we post, not the body, so this
+    will only fire if the body literally contains the marker text. We still
+    do the comment-marker check separately below; this body check just lets
+    us short-circuit for PRs/issues that quote the marker for any reason.
+    """
+    body = item.get("body") or ""
+    return HEADS_UP_MARKER in body
+
+
+def _comments_have_marker(repo: str, number: int) -> bool:
+    """True if the bot already posted a comment carrying the marker.
+
+    Used for idempotency: a re-run skips items the previous run notified.
+    Filters by author (matching the sibling marker-checks in
+    ``triage_with_llm._has_marker`` and
+    ``agent_shin_shared.seconds_since_latest_marker_comment``) so a
+    contributor who quotes the heads-up via GitHub's "Quote reply" — which
+    preserves HTML comments in the raw markdown — can't trick the
+    idempotency check into silently skipping a real heads-up.
+
+    Comments live on the unified issues endpoint regardless of whether the
+    item is a PR or an issue, so no ``kind`` argument is required here.
+    """
+    expected_login = (
+        os.environ.get("AGENT_SHIN_BOT_LOGIN") or AGENT_SHIN_DEFAULT_BOT_LOGIN
+    ).lower()
+    raw = gh(
+        "api",
+        "--paginate",
+        f"repos/{repo}/issues/{number}/comments?per_page=100",
+    )
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        comments = payload if isinstance(payload, list) else [payload]
+        for comment in comments:
+            author = ((comment.get("user") or {}).get("login") or "").lower()
+            if author != expected_login:
+                continue
+            if HEADS_UP_MARKER in (comment.get("body") or ""):
+                return True
+    return False
+
+
+def _evaluate_pr(*, repo: str, number: int, model: str, judge: Any = None) -> dict:
+    """Run the future PR rubric (review_gate) in dry-run and return the result."""
+    return review_gate(
+        repo=repo,
+        number=number,
+        close=False,  # we only want the verdict, never act here
+        model=model,
+        judge=judge,
+    )
+
+
+def _evaluate_issue(*, repo: str, number: int, model: str, judge: Any = None) -> dict:
+    """Run the future issue rubric (triage kind='issue') in dry-run."""
+    return triage(
+        repo=repo,
+        kind="issue",
+        number=number,
+        close=False,
+        model=model,
+        judge=judge,
+    )
+
+
+def _would_be_closed(kind: str, result: dict) -> bool:
+    """True if the future triage would auto-close this PR/issue based on the
+    rubric (regardless of grace-period gating).
+
+    For PRs we trust ``review_gate``'s ``passing`` field — it combines the LLM
+    verdict and the Greptile score. For issues we read the LLM verdict
+    directly. Both fields are ``None``/missing on skip paths
+    (skip-internal-author, skip-llm-error, etc.) where the future bot would
+    NOT close the item — those return False.
+    """
+    if kind == "pr":
+        passing = result.get("passing")
+        if passing is None:
+            return False  # skipped — nothing for the heads-up to warn about
+        return passing is False
+    verdict = result.get("verdict") or {}
+    return (verdict.get("verdict") or "").lower() == "fail"
+
+
+def _process_one(
+    *,
+    repo: str,
+    kind: str,
+    number: int,
+    model: str,
+    cutoff: dt.date,
+    dry_run: bool,
+    judge: Any = None,
+    skip_marker_check: bool = False,
+    allowlist: frozenset[str] = ALLOWLIST_LOGINS,
+) -> dict:
+    """Evaluate one PR/issue and post a heads-up if it would be auto-closed.
+
+    Returns a per-item dict for the summary table.
+    """
+    base = {"kind": kind, "number": number}
+    fetcher = fetch_pr if kind == "pr" else fetch_issue
+    item = fetcher(repo, number)
+
+    if (item.get("state") or "") != "open":
+        return {**base, "action": "skip-not-open"}
+    if allowlist:
+        login = (item.get("user") or {}).get("login") or ""
+        if login.lower() not in allowlist:
+            return {**base, "action": "skip-not-allowlisted"}
+    elif is_internal_contributor(item):
+        return {**base, "action": "skip-internal-author"}
+    if not skip_marker_check and _has_heads_up_marker(item):
+        return {**base, "action": "skip-already-marked-in-body"}
+    if not skip_marker_check and _comments_have_marker(repo, number):
+        return {**base, "action": "skip-already-notified"}
+
+    if kind == "pr":
+        result = _evaluate_pr(repo=repo, number=number, model=model, judge=judge)
+    else:
+        result = _evaluate_issue(repo=repo, number=number, model=model, judge=judge)
+
+    if not _would_be_closed(kind, result):
+        return {**base, "action": "skip-passing", "evaluator": result.get("action")}
+
+    verdict = result.get("verdict") or {}
+    greptile_score = result.get("greptile_score") if kind == "pr" else None
+    comment = format_heads_up_comment(
+        kind=kind, verdict=verdict, greptile_score=greptile_score, cutoff=cutoff
+    )
+    maybe_post_comment(repo, number, comment, dry_run=dry_run)
+    return {
+        **base,
+        "action": "heads-up-posted" if not dry_run else "would-post-heads-up",
+        "verdict": (verdict.get("verdict") or "").lower(),
+        "greptile_score": greptile_score,
+    }
+
+
+def _print_summary(results: list[dict]) -> None:
+    """Tally per-action counts so a dry-run preview tells you at a glance how
+    many comments the real run would post."""
+    counts: dict[str, int] = {}
+    for r in results:
+        counts[r["action"]] = counts.get(r["action"], 0) + 1
+    print("\n=== rollout heads-up summary ===")
+    for action in sorted(counts):
+        print(f"  {action:35s} {counts[action]}")
+    print(f"  total                                {len(results)}")
+
+
+def run(
+    *,
+    repo: str,
+    close: bool,
+    cutoff: dt.date,
+    model: str,
+    kinds: tuple[str, ...] = ("pr", "issue"),
+    judge: Any = None,
+    only_numbers: dict[str, list[int]] | None = None,
+    skip_marker_check: bool = False,
+) -> list[dict]:
+    """Sweep ``repo`` and post heads-up comments. Returns the per-item results."""
+    dry_run = not close
+    if dry_run:
+        print(
+            f"[DRY RUN] sweeping {repo}; --close not passed, no comments will be posted."
+        )
+    else:
+        print(f"[REAL RUN] sweeping {repo}; comments WILL be posted.")
+    print(f"Cutoff date in comment body: {cutoff.isoformat()}")
+
+    results: list[dict] = []
+    for kind in kinds:
+        if only_numbers and kind in only_numbers:
+            numbers = list(only_numbers[kind])
+        else:
+            numbers = _list_open_numbers(repo, kind)
+        print(f"\n--- {kind}s: {len(numbers)} open ---")
+        for n in numbers:
+            try:
+                result = _process_one(
+                    repo=repo,
+                    kind=kind,
+                    number=n,
+                    model=model,
+                    cutoff=cutoff,
+                    dry_run=dry_run,
+                    judge=judge,
+                    skip_marker_check=skip_marker_check,
+                )
+            except (
+                Exception
+            ) as exc:  # noqa: BLE001 - per-item errors don't abort the sweep
+                result = {
+                    "kind": kind,
+                    "number": n,
+                    "action": "error",
+                    "error": str(exc),
+                }
+                print(f"!! {kind}#{n}: {exc}", file=sys.stderr)
+            print(f"  {kind}#{n}: {result['action']}")
+            results.append(result)
+    _print_summary(results)
+    return results
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", required=True, help="owner/repo")
+    parser.add_argument(
+        "--close",
+        action="store_true",
+        help=(
+            "Actually post comments. Without this flag the script is in "
+            "dry-run mode and only logs what it would do."
+        ),
+    )
+    parser.add_argument(
+        "--close-on",
+        type=dt.date.fromisoformat,
+        default=None,
+        help=(
+            "Cutoff date shown in the heads-up comment as the rollout date "
+            f"(default: today + {DEFAULT_GRACE_DAYS} days)."
+        ),
+    )
+    parser.add_argument(
+        "--model",
+        default=os.environ.get("TRIAGE_MODEL") or DEFAULT_MODEL,
+        help=f"Model for the rubric LLM judge (default: {DEFAULT_MODEL}).",
+    )
+    parser.add_argument(
+        "--kind",
+        choices=("pr", "issue", "both"),
+        default="both",
+        help="Restrict the sweep to PRs or issues only (default: both).",
+    )
+    parser.add_argument(
+        "--only-pr",
+        type=int,
+        action="append",
+        default=[],
+        help="Limit the PR sweep to these PR numbers (repeat for several).",
+    )
+    parser.add_argument(
+        "--only-issue",
+        type=int,
+        action="append",
+        default=[],
+        help="Limit the issue sweep to these issue numbers (repeat for several).",
+    )
+    parser.add_argument(
+        "--ignore-existing-marker",
+        action="store_true",
+        help=(
+            "Re-post on PRs/issues that already carry the heads-up marker. "
+            "Useful for testing the comment wording on a known PR."
+        ),
+    )
+    args = parser.parse_args()
+
+    cutoff = args.close_on or (
+        dt.datetime.now(dt.timezone.utc).date() + dt.timedelta(days=DEFAULT_GRACE_DAYS)
+    )
+
+    kinds: tuple[str, ...]
+    if args.kind == "pr":
+        kinds = ("pr",)
+    elif args.kind == "issue":
+        kinds = ("issue",)
+    else:
+        kinds = ("pr", "issue")
+
+    only: dict[str, list[int]] = {}
+    if args.only_pr:
+        only["pr"] = args.only_pr
+    if args.only_issue:
+        only["issue"] = args.only_issue
+
+    # The script must NOT hit the LLM in dry-run if no key is set — we still
+    # want a useful preview that says "skip-no-llm-key" for items that would
+    # have been judged. Production runs require OPENAI_API_KEY.
+    if args.close and not os.environ.get("OPENAI_API_KEY"):
+        parser.error("OPENAI_API_KEY must be set for --close (real-run) mode.")
+
+    run(
+        repo=args.repo,
+        close=args.close,
+        cutoff=cutoff,
+        model=args.model,
+        kinds=kinds,
+        only_numbers=only or None,
+        skip_marker_check=args.ignore_existing_marker,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/README.md

@@ -1,35 +0,0 @@
-# Simple PyPI Publishing
-
-A GitHub workflow to manually publish LiteLLM packages to PyPI with a specified version.
-
-## How to Use
-
-1. Go to the **Actions** tab in the GitHub repository
-2. Select **Simple PyPI Publish** from the workflow list
-3. Click **Run workflow**
-4. Enter the version to publish (e.g., `1.74.10`)
-
-## What the Workflow Does
-
-1. **Updates** the version in `pyproject.toml`
-2. **Copies** the model prices backup file
-3. **Builds** the Python package
-4. **Publishes** to PyPI
-
-## Prerequisites
-
-Make sure the following secret is configured in the repository:
-- `PYPI_PUBLISH_PASSWORD`: PyPI API token for authentication
-
-## Example Usage
-
-- Version: `1.74.11` → Publishes as v1.74.11
-- Version: `1.74.10-hotfix1` → Publishes as v1.74.10-hotfix1
-
-## Features
-
-- ✅ Manual trigger with version input
-- ✅ Automatic version updates in `pyproject.toml`
-- ✅ Repository safety check (only runs on official repo)
-- ✅ Clean package building and publishing
-- ✅ Success confirmation with PyPI package link 

.github/workflows/_test-unit-base.yml

@@ -27,6 +27,11 @@ on:
         required: false
         type: number
         default: 10
+      dist:
+        description: "pytest-xdist distribution mode (loadscope|load|worksteal|loadfile|no)"
+        required: false
+        type: string
+        default: "loadscope"
       artifact-name:
         description: "Unique name for the coverage artifact (must be unique per run)"
         required: true
@@ -51,37 +56,30 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
 
-      - name: Cache Poetry dependencies
+      - name: Cache uv dependencies
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
-            ~/.cache/pypoetry
-            ~/.cache/pip
+            ~/.cache/uv
             .venv
-          key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
           restore-keys: |
-            ${{ runner.os }}-poetry-
+            ${{ runner.os }}-uv-
 
       - name: Install dependencies
         run: |
-          poetry config virtualenvs.in-project true
-          poetry install --with dev,proxy-dev --extras "proxy semantic-router"
-          poetry run pip install google-genai==1.22.0 \
-            google-cloud-aiplatform==1.115.0 fastapi-offline==1.7.3 python-multipart==0.0.22 openapi-core==0.23.0
-
-      - name: Setup litellm-enterprise
-        run: |
-          poetry run pip install --force-reinstall --no-deps -e enterprise/
+          uv sync --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router
 
       - name: Generate Prisma client
         env:
           PRISMA_BINARY_CACHE_DIR: ${{ runner.temp }}/prisma-cache
         run: |
-          poetry run pip install nodejs-wheel-binaries==24.13.1
-          poetry run prisma generate --schema litellm/proxy/schema.prisma
+          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
 
       - name: Run tests
         env:
@@ -89,18 +87,31 @@ jobs:
           MAX_FAILURES: ${{ inputs.max-failures }}
           WORKERS: ${{ inputs.workers }}
           RERUNS: ${{ inputs.reruns }}
+          DIST: ${{ inputs.dist }}
         run: |
-          poetry run pytest ${TEST_PATH:?} \
-            --tb=short -vv \
-            --maxfail="${MAX_FAILURES}" \
-            -n "${WORKERS}" \
-            --reruns "${RERUNS}" \
-            --reruns-delay 1 \
-            --dist=loadscope \
-            --durations=20 \
-            --cov=litellm \
-            --cov-report=xml:coverage.xml \
-            --cov-config=pyproject.toml
+          if [ "${WORKERS}" = "0" ]; then
+            uv run --no-sync pytest ${TEST_PATH:?} \
+              --tb=short -vv \
+              --maxfail="${MAX_FAILURES}" \
+              --reruns "${RERUNS}" \
+              --reruns-delay 1 \
+              --durations=20 \
+              --cov=./litellm \
+              --cov-report=xml:coverage.xml \
+              --cov-config=pyproject.toml
+          else
+            uv run --no-sync pytest ${TEST_PATH:?} \
+              --tb=short -vv \
+              --maxfail="${MAX_FAILURES}" \
+              -n "${WORKERS}" \
+              --reruns "${RERUNS}" \
+              --reruns-delay 1 \
+              --dist="${DIST}" \
+              --durations=20 \
+              --cov=./litellm \
+              --cov-report=xml:coverage.xml \
+              --cov-config=pyproject.toml
+          fi
 
       - name: Save coverage report
         if: always()
@@ -139,4 +150,5 @@ jobs:
           use_oidc: true
           directory: coverage-reports
           root_dir: ${{ github.workspace }}
+          flags: ${{ inputs.artifact-name }}
           fail_ci_if_error: false

.github/workflows/_test-unit-services-base.yml

@@ -1,214 +0,0 @@
-name: _Unit Test Services Base (Reusable)
-
-on:
-  workflow_call:
-    inputs:
-      test-path:
-        description: "Pytest path(s) to run"
-        required: true
-        type: string
-      workers:
-        description: "Number of pytest-xdist workers (0 = no parallelism)"
-        required: false
-        type: number
-        default: 2
-      reruns:
-        description: "Number of reruns for flaky tests"
-        required: false
-        type: number
-        default: 2
-      timeout-minutes:
-        description: "Job timeout in minutes"
-        required: false
-        type: number
-        default: 20
-      max-failures:
-        description: "Stop after this many failures"
-        required: false
-        type: number
-        default: 10
-      enable-redis:
-        description: "Pass Redis Cloud credentials to tests via REDIS_HOST/PORT/PASSWORD env vars"
-        required: false
-        type: boolean
-        default: false
-      enable-postgres:
-        description: "Start a local Postgres service container and run Prisma migrations"
-        required: false
-        type: boolean
-        default: false
-      artifact-name:
-        description: "Unique name for the coverage artifact (must be unique per run)"
-        required: false
-        type: string
-        default: "run"
-    secrets:
-      REDIS_HOST:
-        required: false
-      REDIS_PORT:
-        required: false
-      REDIS_PASSWORD:
-        required: false
-      DATABASE_URL:
-        required: false
-      POSTGRES_USER:
-        required: false
-      POSTGRES_PASSWORD:
-        required: false
-
-permissions:
-  contents: read
-
-jobs:
-  run:
-    name: Run tests
-    runs-on: ubuntu-latest
-    timeout-minutes: ${{ inputs.timeout-minutes }}
-    # Environment is derived from the enable-* flags, not caller-controllable.
-    # This prevents callers from passing arbitrary environment names to bypass secret scoping.
-    # Note: Postgres service container always starts (GHA limitation), so any Redis job
-    # also needs Postgres secrets → uses integration-redis-postgres, not integration-redis.
-    environment: >-
-      ${{
-        inputs.enable-redis && 'integration-redis-postgres' ||
-        inputs.enable-postgres && 'integration-postgres' ||
-        ''
-      }}
-
-    services:
-      postgres:
-        image: postgres@sha256:705a5d5b5836f3fcba0d02c4d281e6a7dd9ed2dd4078640f08a1e1e9896e097d # postgres:14
-        env:
-          POSTGRES_USER: ${{ secrets.POSTGRES_USER }}
-          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
-          POSTGRES_DB: litellm_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
-
-      - name: Cache Poetry dependencies
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-        with:
-          path: |
-            ~/.cache/pypoetry
-            ~/.cache/pip
-            .venv
-          key: ${{ runner.os }}-poetry-services-${{ hashFiles('poetry.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-poetry-services-
-
-      - name: Install dependencies
-        run: |
-          poetry config virtualenvs.in-project true
-          poetry install --with dev,proxy-dev --extras "proxy semantic-router"
-          poetry run pip install google-genai==1.22.0 \
-            google-cloud-aiplatform==1.115.0 fastapi-offline==1.7.3 python-multipart==0.0.22 openapi-core==0.23.0
-
-      - name: Setup litellm-enterprise
-        run: |
-          poetry run pip install --force-reinstall --no-deps -e enterprise/
-
-      - name: Generate Prisma client
-        env:
-          PRISMA_BINARY_CACHE_DIR: ${{ runner.temp }}/prisma-cache
-        run: |
-          poetry run pip install nodejs-wheel-binaries==24.13.1
-          poetry run prisma generate --schema litellm/proxy/schema.prisma
-
-      - name: Run Prisma migrations
-        if: ${{ inputs.enable-postgres }}
-        env:
-          DATABASE_URL: ${{ secrets.DATABASE_URL }}
-        run: |
-          poetry run prisma db push --schema litellm/proxy/schema.prisma --accept-data-loss
-
-      - name: Run tests
-        env:
-          TEST_PATH: ${{ inputs.test-path }}
-          MAX_FAILURES: ${{ inputs.max-failures }}
-          WORKERS: ${{ inputs.workers }}
-          RERUNS: ${{ inputs.reruns }}
-          DATABASE_URL: ${{ inputs.enable-postgres && secrets.DATABASE_URL || '' }}
-          REDIS_HOST: ${{ inputs.enable-redis && secrets.REDIS_HOST || '' }}
-          REDIS_PORT: ${{ inputs.enable-redis && secrets.REDIS_PORT || '' }}
-          REDIS_PASSWORD: ${{ inputs.enable-redis && secrets.REDIS_PASSWORD || '' }}
-        run: |
-          if [ "${WORKERS}" = "0" ]; then
-            poetry run pytest ${TEST_PATH:?} \
-              --tb=short -vv \
-              --maxfail="${MAX_FAILURES}" \
-              --reruns "${RERUNS}" \
-              --reruns-delay 1 \
-              --durations=20 \
-              --cov=litellm \
-              --cov-report=xml:coverage.xml \
-              --cov-config=pyproject.toml
-          else
-            poetry run pytest ${TEST_PATH:?} \
-              --tb=short -vv \
-              --maxfail="${MAX_FAILURES}" \
-              -n "${WORKERS}" \
-              --reruns "${RERUNS}" \
-              --reruns-delay 1 \
-              --dist=loadscope \
-              --durations=20 \
-              --cov=litellm \
-              --cov-report=xml:coverage.xml \
-              --cov-config=pyproject.toml
-          fi
-
-      - name: Save coverage report
-        if: always()
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        with:
-          name: coverage-${{ inputs.artifact-name }}-${{ github.run_id }}-${{ github.run_attempt }}
-          path: coverage.xml
-          retention-days: 1
-
-  upload-coverage:
-    name: Upload coverage to Codecov
-    needs: run
-    if: always()
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-      pull-requests: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Download coverage report
-        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
-        with:
-          pattern: coverage-${{ inputs.artifact-name }}-${{ github.run_id }}-${{ github.run_attempt }}
-          path: coverage-reports
-          merge-multiple: true
-
-      - name: Upload to Codecov
-        uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5.5.4
-        with:
-          use_oidc: true
-          directory: coverage-reports
-          root_dir: ${{ github.workspace }}
-          fail_ci_if_error: false

.github/workflows/auto_update_price_and_context_window.yml

@@ -17,12 +17,13 @@ jobs:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           persist-credentials: false
-      - name: Install Dependencies
-        run: |
-          pip install 'aiohttp==3.13.3'
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
       - name: Update JSON Data
         run: |
-          python ".github/workflows/auto_update_price_and_context_window_file.py"
+          uv run --frozen --with 'aiohttp==3.13.3' python ".github/workflows/auto_update_price_and_context_window_file.py"
       - name: Create Pull Request
         run: |
           git add model_prices_and_context_window.json 

.github/workflows/check-ui-api-types.yml

@@ -0,0 +1,84 @@
+name: Check UI API Types Sync
+
+on:
+  pull_request:
+    paths:
+      - "litellm/proxy/**"
+      - "litellm/types/**"
+      - "ui/litellm-dashboard/src/lib/http/schema.d.ts"
+      - "ui/litellm-dashboard/scripts/gen-api-types.mjs"
+      - "ui/litellm-dashboard/package.json"
+      - "ui/litellm-dashboard/package-lock.json"
+      - ".github/workflows/check-ui-api-types.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  check-sync:
+    name: Verify schema.d.ts matches the proxy OpenAPI spec
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
+
+      - name: Cache uv dependencies
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install backend dependencies
+        run: uv sync --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router
+
+      - 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: Set up Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: ui/litellm-dashboard/package-lock.json
+
+      - name: Install dashboard dependencies
+        working-directory: ui/litellm-dashboard
+        run: npm ci
+
+      - name: Regenerate types from the live spec
+        working-directory: ui/litellm-dashboard
+        env:
+          LITELLM_PYTHON: "uv run --no-sync python"
+        run: npm run gen:api
+
+      - name: Fail if types are stale
+        run: |
+          if ! git diff --exit-code -- ui/litellm-dashboard/src/lib/http/schema.d.ts; then
+            echo "::error file=ui/litellm-dashboard/src/lib/http/schema.d.ts::Generated API types are out of sync with the proxy OpenAPI spec."
+            echo ""
+            echo "A backend route or model changed without regenerating the dashboard types."
+            echo "To fix, run from ui/litellm-dashboard:"
+            echo "  npm run gen:api"
+            echo "then commit the updated src/lib/http/schema.d.ts."
+            exit 1
+          fi
+          echo "schema.d.ts is in sync with the proxy OpenAPI spec."

.github/workflows/check_duplicate_issues.yml

@@ -39,7 +39,7 @@ jobs:
         if: github.event.action == 'opened'
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Auto-close if high-confidence duplicate
         if: github.event.action == 'opened'

.github/workflows/close_low_quality_prs.yml

@@ -0,0 +1,92 @@
+name: Close Low-Quality PRs
+
+# Auto-close any open PR (including drafts, regardless of age) authored by an
+# external OSS contributor that Greptile reviewed with a confidence score
+# below 4/5. Closures are explained in a comment that tells the contributor
+# to push fixes and open a fresh PR (since OSS authors cannot reopen a PR
+# closed by a bot/maintainer) or comment `@agent-shin reconsider` to have
+# Agent Shin re-evaluate.
+#
+# Manual one-off run:
+#   gh workflow run "Close Low-Quality PRs" -f close=true
+#
+# Dry-run preview (no PRs are touched):
+#   gh workflow run "Close Low-Quality PRs" -f close=false
+
+on:
+  schedule:
+    # Daily at 09:00 UTC. Pairs well with the stale-issue workflow at midnight.
+    - cron: "0 9 * * *"
+  workflow_dispatch:
+    inputs:
+      close:
+        description: "Actually close matching PRs (false = dry run)."
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "true"
+          - "false"
+      min_age_days:
+        description: "Minimum PR age in days (default 0 = no age filter)."
+        required: false
+        default: "0"
+      min_score:
+        description: "Greptile score below which a PR is closed (1-5)."
+        required: false
+        default: "4"
+      limit:
+        description: "Maximum number of PRs to close in a single run."
+        required: false
+        default: "25"
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  close-low-quality-prs:
+    if: github.repository == 'BerriAI/litellm'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout triage script
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          sparse-checkout: .github/scripts
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Run low-quality PR closer
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Scheduled runs are ALWAYS dry-run, even when AGENT_SHIN_ENABLED is
+          # "true", so the team can QA the closer's verdicts in step summaries
+          # before any contributor sees a PR closed. Real closures only happen
+          # on manual workflow_dispatch with close=true (and the variable set).
+          CLOSE_FLAG: ${{ github.event.inputs.close || 'false' }}
+          AGENT_SHIN_ENABLED: ${{ vars.AGENT_SHIN_ENABLED }}
+          MIN_AGE_DAYS: ${{ github.event.inputs.min_age_days || '0' }}
+          MIN_SCORE: ${{ github.event.inputs.min_score || '4' }}
+          LIMIT: ${{ github.event.inputs.limit || '25' }}
+        run: |
+          set -euo pipefail
+          ARGS=(
+            --repo "${{ github.repository }}"
+            --min-age-days "${MIN_AGE_DAYS}"
+            --min-score "${MIN_SCORE}"
+            --limit "${LIMIT}"
+          )
+          if [ "${AGENT_SHIN_ENABLED:-false}" != "true" ]; then
+            echo "::notice::AGENT_SHIN_ENABLED is not 'true' -> forcing dry-run regardless of close input."
+          elif [ "${GITHUB_EVENT_NAME:-}" = "workflow_dispatch" ] && [ "${CLOSE_FLAG}" = "true" ]; then
+            ARGS+=(--close)
+            echo "::notice::Running in close-on-fail mode."
+          else
+            echo "::notice::AGENT_SHIN_ENABLED is true but this trigger is dry-run (scheduled event or close=false)."
+          fi
+          python3 .github/scripts/close_low_quality_prs.py "${ARGS[@]}"

.github/workflows/codeql.yml

@@ -43,13 +43,41 @@ jobs:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3
+        uses: github/codeql-action/init@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3.34.1
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
           config-file: ./.github/codeql/codeql-config.yml
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3
+        uses: github/codeql-action/analyze@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3.34.1
         with:
           category: "/language:${{ matrix.language }}"
+          output: sarif-results
+          upload: failure-only
+
+      # py/weak-sensitive-data-hashing (CWE-328) fires on the OCI signing call at
+      # litellm/llms/oci/common_utils.py, which hashes the HTTP request body to
+      # produce the x-content-sha256 header required by the OCI HTTP signing spec —
+      # a content-integrity hash, not a password or secret hash. SHA-256 is mandated
+      # by Oracle for this header; see
+      # https://docs.oracle.com/en-us/iaas/Content/API/Concepts/signingrequests.htm
+      # The `usedforsecurity=False` flag on the hashlib.sha256 call already declares
+      # non-security intent, but CodeQL's taint flow still re-fires when callers
+      # further up the stack are modified. The suppression is scoped to this one
+      # file/rule pair via SARIF post-filtering so every other callsite of
+      # py/weak-sensitive-data-hashing in the repository continues to be analyzed.
+      - name: Filter SARIF (OCI sha256)
+        if: matrix.language == 'python'
+        uses: advanced-security/filter-sarif@2da736ff05ef065cb2894ac6892e47b5eac2c3c0 # v1.1
+        with:
+          patterns: |
+            -litellm/llms/oci/common_utils.py:py/weak-sensitive-data-hashing
+          input: sarif-results/python.sarif
+          output: sarif-results/python.sarif
+
+      - name: Upload SARIF
+        uses: github/codeql-action/upload-sarif@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3.34.1
+        with:
+          sarif_file: sarif-results
+          category: "/language:${{ matrix.language }}"

.github/workflows/codspeed.yml

@@ -34,13 +34,21 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install dependencies
-        run: |
-          pip install -e "."
-          pip install pytest pytest-codspeed==4.3.0
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
 
       - name: Run benchmarks
         uses: CodSpeedHQ/action@1c8ae4843586d3ba879736b7f6b7b0c990757fab # v4.12.1
         with:
           mode: simulation
-          run: pytest tests/benchmarks/ --codspeed
+          run: >
+            env PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
+            uv run --frozen --no-default-groups
+            --with pytest==8.3.5
+            --with pytest-codspeed==4.3.0
+            pytest
+            -p pytest_codspeed.plugin
+            tests/benchmarks/
+            --codspeed

.github/workflows/conventional-commits.yml

@@ -0,0 +1,46 @@
+name: Conventional PR Title
+
+# Squash-merge replaces the merge commit subject with the PR title, so
+# enforcing Conventional Commits at the PR-title level is what actually gates
+# the commits that land on the default branch. The local commit-msg hook
+# (.githooks/commit-msg) is a best-effort assist; this workflow is the gate.
+#
+# See https://www.conventionalcommits.org/en/v1.0.0/
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize, labeled, unlabeled]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint-pr-title:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check title against Conventional Commits
+        uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Must mirror the type list in .githooks/commit-msg.
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject "{subject}" must start with a lowercase character.
+          # Allow merges/reverts that GitHub generates automatically.
+          ignoreLabels: |
+            ignore-semantic-pull-request

.github/workflows/create-release-branch.yml

@@ -0,0 +1,90 @@
+name: Create Release Branch
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag (e.g. 1.84.0, 1.84.0rc1, 1.84.0.dev42, 1.84.0.post1; legacy v1.83.10-stable still accepted) — branch will be named release/<tag>"
+        required: true
+        type: string
+      commit_hash:
+        description: "Full 40-char commit SHA the branch should point to"
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      tag:
+        description: "Release tag (e.g. 1.84.0, 1.84.0rc1, 1.84.0.dev42, 1.84.0.post1; legacy v1.83.10-stable still accepted)"
+        required: true
+        type: string
+      commit_hash:
+        description: "Full 40-char commit SHA the branch should point to"
+        required: true
+        type: string
+
+permissions: {}
+
+jobs:
+  create-branch:
+    name: Create Release Branch
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Validate inputs
+        env:
+          TAG: ${{ inputs.tag }}
+          COMMIT_HASH: ${{ inputs.commit_hash }}
+        run: |
+          if ! echo "${COMMIT_HASH}" | grep -qE '^[0-9a-f]{40}$'; then
+            echo "::error::commit_hash must be a full 40-character commit SHA"
+            exit 1
+          fi
+          if ! echo "${TAG}" | grep -qE '^v?[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::tag must start with X.Y.Z (optional leading v), e.g. 1.84.0, 1.84.0rc1, 1.84.0.dev42, or v1.83.10-stable"
+            exit 1
+          fi
+
+      - name: Create release branch
+        env:
+          TAG: ${{ inputs.tag }}
+          COMMIT_HASH: ${{ inputs.commit_hash }}
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const tag = process.env.TAG;
+            const commitHash = process.env.COMMIT_HASH;
+            const branchName = `release/${tag}`;
+
+            await github.rest.git.createRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: `refs/heads/${branchName}`,
+              sha: commitHash,
+            });
+            core.info(`Created branch ${branchName} at ${commitHash}`);
+
+      - name: Create stable line branch
+        env:
+          TAG: ${{ inputs.tag }}
+          COMMIT_HASH: ${{ inputs.commit_hash }}
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const tag = process.env.TAG;
+            const commitHash = process.env.COMMIT_HASH;
+
+            const match = tag.match(/^v?(\d+)\.(\d+)\.0$/);
+            if (!match) {
+              core.info(`Tag ${tag} is not the X.Y.0 stable opener; skipping stable line branch`);
+              return;
+            }
+            const lineBranch = `stable/${match[1]}.${match[2]}.x`;
+
+            await github.rest.git.createRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: `refs/heads/${lineBranch}`,
+              sha: commitHash,
+            });
+            core.info(`Created branch ${lineBranch} at ${commitHash}`);

.github/workflows/create-release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag (e.g. v1.83.0-stable)"
+        description: "Release tag (e.g. 1.84.0, 1.84.0rc1, 1.84.0.dev42, 1.84.0-dev.2, 1.84.0.post1; legacy v1.83.10-stable still accepted)"
         required: true
         type: string
       commit_hash:
@@ -30,8 +30,8 @@ jobs:
             echo "::error::commit_hash must be a full 40-character commit SHA"
             exit 1
           fi
-          if ! echo "${TAG}" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+'; then
-            echo "::error::tag must start with vX.Y.Z"
+          if ! echo "${TAG}" | grep -qE '^v?[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::tag must start with X.Y.Z (optional leading v), e.g. 1.84.0, 1.84.0rc1, 1.84.0.dev42, or v1.83.10-stable"
             exit 1
           fi
 
@@ -45,10 +45,47 @@ jobs:
             const tag = process.env.TAG;
             const commitHash = process.env.COMMIT_HASH;
 
+            // Mark RC / dev / nightly / alpha / beta tags as GitHub pre-releases.
+            // Accept both PEP 440 (`.dev`) and SemVer (`-dev`) separators so tags
+            // like `1.84.0.dev2` and `1.84.0-dev.2` are both detected.
+            // PEP 440 post-releases (e.g. `1.84.0.post1`) and legacy `-stable[.patch.N]`
+            // are stable maintenance releases, not pre-releases.
+            const isPrerelease = /(?:rc|nightly|alpha|beta|[-.]dev)/i.test(tag);
+
+            // A stable release should only claim the repo "latest" badge when its
+            // version is >= the current latest. Otherwise a backport (e.g. 1.84.6)
+            // would steal "latest" from a newer line (e.g. 1.88.1).
+            const versionKey = (rawTag) => {
+              const m = String(rawTag).match(/^v?(\d+)\.(\d+)\.(\d+)/);
+              if (!m) return null;
+              const maintenance = String(rawTag).match(/(?:\.post|\.patch\.)(\d+)/i);
+              return [Number(m[1]), Number(m[2]), Number(m[3]), maintenance ? Number(maintenance[1]) : 0];
+            };
+            const isAtLeast = (a, b) => {
+              for (let i = 0; i < a.length; i++) {
+                if (a[i] !== b[i]) return a[i] > b[i];
+              }
+              return true;
+            };
+
             const cosignSection = [
               `## Verify Docker Image Signature`,
               ``,
-              `All LiteLLM Docker images are signed with [cosign](https://docs.sigstore.dev/cosign/overview/). To verify the integrity of an image before deploying:`,
+              `All LiteLLM Docker images are signed with [cosign](https://docs.sigstore.dev/cosign/overview/). Every release is signed with the same key introduced in [commit \`0112e53\`](https://github.com/BerriAI/litellm/commit/0112e53046018d726492c814b3644b7d376029d0).`,
+              ``,
+              `**Verify using the pinned commit hash (recommended):**`,
+              ``,
+              `A commit hash is cryptographically immutable, so this is the strongest way to ensure you are using the original signing key:`,
+              ``,
+              '```bash',
+              `cosign verify \\`,
+              `  --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \\`,
+              `  ghcr.io/berriai/litellm:${tag}`,
+              '```',
+              ``,
+              `**Verify using the release tag (convenience):**`,
+              ``,
+              `Tags are protected in this repository and resolve to the same key. This option is easier to read but relies on tag protection rules:`,
               ``,
               '```bash',
               `cosign verify \\`,
@@ -69,13 +106,29 @@ jobs:
             ].join('\n');
 
             try {
+              let makeLatest = "false";
+              const newVersion = versionKey(tag);
+              if (!isPrerelease && newVersion) {
+                let latestVersion = null;
+                try {
+                  const latest = await github.rest.repos.getLatestRelease({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                  });
+                  latestVersion = versionKey(latest.data.tag_name);
+                } catch (error) {
+                  if (error.status !== 404) throw error;
+                }
+                makeLatest = (!latestVersion || isAtLeast(newVersion, latestVersion)) ? "true" : "false";
+              }
+
               const response = await github.rest.repos.createRelease({
                 draft: true,
                 generate_release_notes: true,
                 target_commitish: commitHash,
                 name: tag,
                 owner: context.repo.owner,
-                prerelease: false,
+                prerelease: isPrerelease,
                 repo: context.repo.repo,
                 tag_name: tag,
               });
@@ -87,7 +140,19 @@ jobs:
                 release_id: response.data.id,
                 body: updatedBody,
                 draft: false,
+                make_latest: makeLatest,
               });
+
             } catch (error) {
               core.setFailed(error.message);
             }
+
+  create-branch:
+    name: Create Release Branch
+    needs: release
+    permissions:
+      contents: write
+    uses: ./.github/workflows/create-release-branch.yml
+    with:
+      tag: ${{ inputs.tag }}
+      commit_hash: ${{ inputs.commit_hash }}

.github/workflows/create_daily_oss_agent_shin_branch.yml

@@ -0,0 +1,47 @@
+name: Create Daily oss-agent-shin Branch
+
+on:
+  schedule:
+    - cron: "0 0 * * *" # Runs every day at midnight UTC
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  create-oss-agent-shin-branch:
+    if: github.repository == 'BerriAI/litellm'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Create daily oss-agent-shin branch
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Configure Git user
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Generate branch name with MM_DD_YYYY format
+          BRANCH_NAME="litellm_oss_agent_shin_$(date +'%m_%d_%Y')"
+          echo "Creating branch: $BRANCH_NAME"
+
+          # Fetch all branches
+          git fetch --all
+
+          # Check if the branch already exists
+          if git show-ref --verify --quiet refs/remotes/origin/$BRANCH_NAME; then
+            echo "Branch $BRANCH_NAME already exists. Skipping creation."
+          else
+            echo "Creating new branch: $BRANCH_NAME"
+            # Create the new branch from main
+            git checkout -b $BRANCH_NAME origin/main
+            # Push the new branch
+            git push origin $BRANCH_NAME
+            echo "Successfully created and pushed branch: $BRANCH_NAME"
+          fi

.github/workflows/guard-fork-dependencies.yml

@@ -0,0 +1,140 @@
+name: Guard fork dependency changes
+
+on:
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
+    paths:
+      - "uv.lock"
+      - "pyproject.toml"
+      - "litellm-proxy-extras/pyproject.toml"
+      - "enterprise/pyproject.toml"
+
+permissions: {}
+
+jobs:
+  guard:
+    name: Block fork dependency changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    if: github.event.pull_request.head.repo.full_name != github.repository
+    steps:
+      - name: Checkout base branch
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          ref: ${{ github.base_ref }}
+          persist-credentials: false
+          path: base
+
+      - name: Checkout PR head (read-only)
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+          path: pr
+
+      - name: Reject uv.lock changes
+        run: |
+          if ! diff -q base/uv.lock pr/uv.lock >/dev/null 2>&1; then
+            echo "::error::Fork PRs must not modify uv.lock. Dependency lockfile changes must come from a branch in the canonical repository."
+            exit 1
+          fi
+          echo "uv.lock is unchanged."
+
+      - name: Reject new dependencies in pyproject.toml files
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # Write the checker script to a temp file to avoid shell quoting issues.
+          cat > /tmp/extract_deps.py << 'SCRIPT'
+          import re
+          import sys
+          import tomllib
+
+
+          def normalize(name: str) -> str:
+              return re.sub(r"[-_.]+", "-", name).lower()
+
+
+          def extract_dep_names(path: str) -> set[str]:
+              with open(path, "rb") as f:
+                  data = tomllib.load(f)
+
+              deps: set[str] = set()
+              pep508 = re.compile(r"^([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)")
+
+              # [project].dependencies
+              for spec in data.get("project", {}).get("dependencies", []):
+                  m = pep508.match(spec)
+                  if m:
+                      deps.add(normalize(m.group(1)))
+
+              # [project.optional-dependencies]
+              for group in data.get("project", {}).get("optional-dependencies", {}).values():
+                  for spec in group:
+                      m = pep508.match(spec)
+                      if m:
+                          deps.add(normalize(m.group(1)))
+
+              # [dependency-groups]
+              for group in data.get("dependency-groups", {}).values():
+                  for item in group:
+                      if isinstance(item, str):
+                          m = pep508.match(item)
+                          if m:
+                              deps.add(normalize(m.group(1)))
+
+              return deps
+
+
+          if __name__ == "__main__":
+              for name in sorted(extract_dep_names(sys.argv[1])):
+                  print(name)
+          SCRIPT
+
+          had_error=0
+
+          check_deps() {
+            local base_file="$1"
+            local pr_file="$2"
+            local label="$3"
+
+            if [ ! -f "$base_file" ] && [ ! -f "$pr_file" ]; then
+              return 0
+            fi
+
+            if [ ! -f "$base_file" ] && [ -f "$pr_file" ]; then
+              echo "::error::Fork PR introduces a new $label that does not exist on the base branch."
+              return 1
+            fi
+
+            base_deps=$(python3 /tmp/extract_deps.py "$base_file")
+            pr_deps=$(python3 /tmp/extract_deps.py "$pr_file")
+
+            new_deps=$(comm -13 <(echo "$base_deps") <(echo "$pr_deps"))
+
+            if [ -n "$new_deps" ]; then
+              echo "::error::Fork PR adds new dependencies in $label: $(echo $new_deps | tr '\n' ', ')"
+              echo "New packages detected:"
+              echo "$new_deps"
+              return 1
+            fi
+
+            echo "$label: no new dependencies."
+            return 0
+          }
+
+          check_deps base/pyproject.toml pr/pyproject.toml "pyproject.toml" || had_error=1
+          check_deps base/litellm-proxy-extras/pyproject.toml pr/litellm-proxy-extras/pyproject.toml "litellm-proxy-extras/pyproject.toml" || had_error=1
+          check_deps base/enterprise/pyproject.toml pr/enterprise/pyproject.toml "enterprise/pyproject.toml" || had_error=1
+
+          if [ "$had_error" -ne 0 ]; then
+            echo ""
+            echo "::error::Fork PRs must not add new dependencies. Please open an issue or coordinate with a maintainer to update dependencies from within the canonical repository."
+            exit 1
+          fi
+
+          echo "All pyproject.toml files passed dependency check."

.github/workflows/guard-main-branch.yml

@@ -0,0 +1,42 @@
+name: Guard main branch
+
+on:
+  pull_request:
+    branches:
+      - main
+  merge_group:
+
+permissions: {}
+
+# DO NOT RENAME the job's `name:` — it is referenced by GitHub branch
+# protection as a required status check on `main`. Renaming silently
+# breaks the gate.
+jobs:
+  guard:
+    name: Verify PR source branch
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Reject merge_group events
+        if: github.event_name == 'merge_group'
+        run: |
+          echo "::error::Merge queue is not supported for main. Disable merge queue or update this guard."
+          exit 1
+      - name: Check head branch name
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          BASE_REPO: ${{ github.repository }}
+        run: |
+          echo "PR head repo: $HEAD_REPO"
+          echo "PR head branch: $HEAD_REF"
+          if [ "$HEAD_REPO" != "$BASE_REPO" ]; then
+            echo "::error::PRs to main must originate from the canonical repository ($BASE_REPO), not a fork ($HEAD_REPO). External contributors should open PRs against the 'litellm_oss_branch' branch instead."
+            exit 1
+          fi
+          if [ "$HEAD_REF" = "litellm_internal_staging" ] || [[ "$HEAD_REF" == litellm_hotfix_?* ]]; then
+            echo "Allowed source branch."
+            exit 0
+          fi
+          echo "::error::PRs to main must originate from 'litellm_internal_staging' or a 'litellm_hotfix_*' branch. Got: '$HEAD_REF'. If this is a contribution, retarget the PR against 'litellm_oss_branch' instead."
+          exit 1

.github/workflows/llm-translation-testing.yml

@@ -1,93 +0,0 @@
-name: LLM Translation Tests
-
-on:
-  workflow_dispatch:
-    inputs:
-      release_candidate_tag:
-        description: "Release candidate tag/version"
-        required: true
-        type: string
-  push:
-    tags:
-      - "v*-rc*" # Triggers on release candidate tags like v1.0.0-rc1
-
-permissions:
-  contents: read
-
-jobs:
-  run-llm-translation-tests:
-    runs-on: ubuntu-latest
-    timeout-minutes: 90
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-          ref: ${{ github.event.inputs.release_candidate_tag || github.ref }}
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.11"
-
-      - name: Install Poetry
-        run: |
-          pip install 'poetry==2.3.2'
-          poetry config virtualenvs.create true
-          poetry config virtualenvs.in-project true
-
-      - name: Restore Poetry dependencies cache
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.0.0
-        with:
-          path: |
-            ~/.cache/pypoetry
-            .venv
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-poetry-
-
-      - name: Install dependencies
-        run: |
-          poetry install --with dev
-          poetry run pip install 'pytest-xdist==3.8.0' 'pytest-timeout==2.4.0'
-
-      - name: Create test results directory
-        run: mkdir -p test-results
-
-      - name: Run LLM Translation Tests
-        env:
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
-          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
-          AZURE_API_KEY: ${{ secrets.AZURE_API_KEY }}
-          AZURE_API_BASE: ${{ secrets.AZURE_API_BASE }}
-          AZURE_API_VERSION: ${{ secrets.AZURE_API_VERSION }}
-          RC_TAG: ${{ github.event.inputs.release_candidate_tag || github.ref_name }}
-          COMMIT_SHA: ${{ github.sha }}
-        run: |
-          python .github/workflows/run_llm_translation_tests.py \
-            --tag "$RC_TAG" \
-            --commit "$COMMIT_SHA" \
-            || true  # Continue even if tests fail
-
-      - name: Display test summary
-        if: always()
-        run: |
-          if [ -f "test-results/llm_translation_report.md" ]; then
-            echo "Test report generated successfully!"
-            echo "Artifact will contain:"
-            echo "- test-results/junit.xml (JUnit XML results)"
-            echo "- test-results/llm_translation_report.md (Beautiful markdown report)"
-          else
-            echo "Warning: Test report was not generated"
-          fi
-
-      - name: Upload test artifacts
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        if: always()
-        with:
-          name: LLM-Translation-Artifact-${{ github.event.inputs.release_candidate_tag || github.ref_name }}
-          path: test-results/
-          retention-days: 30

.github/workflows/mutation-test.yml

@@ -0,0 +1,131 @@
+name: "Mutation Test (manual)"
+
+# Manually-triggered mutation testing. Runs mutmut against the scope
+# configured in [tool.mutmut] in pyproject.toml (currently the
+# litellm/proxy/management_endpoints/ folder). Intended cadence is roughly
+# weekly — clicked from the Actions tab when someone wants a fresh report.
+#
+# Uploads a structured `mutation-report.md` (Meta ACH-style: original +
+# mutated function with `# MUTANT START`/`# MUTANT END` delimiters + the
+# existing tests + a task instruction) as a workflow artifact. Failures
+# do not block anything because nothing depends on this workflow.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mutation-test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  mutation:
+    name: Run mutmut
+    runs-on: ubuntu-latest
+    # Whole-folder mutation against ~15 files / ~7.5k LOC can take hours.
+    # 350 minutes is just under the GitHub-hosted job cap of 360 minutes.
+    timeout-minutes: 350
+
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
+
+      - name: Cache uv dependencies
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router
+
+      - 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
+
+      # mutmut 3.x runs tests inside a `mutants/` sandbox where it injects
+      # mutation trampolines. uv installs the project as editable by default,
+      # which puts the original source dir on sys.path via a .pth file and
+      # shadows the sandbox copy — so tests would never exercise the mutated
+      # code. Reinstalling non-editable removes the .pth shadow.
+      - name: Reinstall litellm non-editable (so mutants/ is not shadowed)
+        run: |
+          uv pip uninstall litellm
+          uv pip install . --no-deps
+
+      # pytest-retry's pytest_configure hook crashes with
+      # `INTERNALERROR: no option named 'filtered_exceptions'` when invoked
+      # via mutmut's in-process pytest.main() call. The entry-point name
+      # doesn't normalize cleanly with `-p no:<name>`, so just remove the
+      # package outright. Reruns are wrong for mutation testing anyway —
+      # rerunning a "failed" mutant test would mask which mutants are killed.
+      - name: Remove pytest plugins that conflict with mutmut
+        run: |
+          uv pip uninstall pytest-retry || true
+
+      - name: Run mutmut
+        env:
+          # Make the mutants/ sandbox win over site-packages on sys.path so the
+          # trampolined files are imported instead of the installed copy.
+          PYTHONPATH: ${{ github.workspace }}/mutants
+        run: |
+          set -o pipefail
+          mkdir -p mutants
+          uv run --no-sync --with mutmut==3.5.0 mutmut run 2>&1 | tee mutmut-run.log
+
+      # Generate the structured report. The script embeds the enclosing
+      # function source for each survivor (via Python AST) and includes the
+      # existing test files, so an LLM agent has enough context to write
+      # killing tests without further file lookups. Modeled on Meta's ACH
+      # prompt template (arXiv 2501.12862).
+      - name: Generate detailed mutation report
+        if: always()
+        run: |
+          set +e
+          uv run --no-sync --with mutmut==3.5.0 mutmut export-cicd-stats > /dev/null 2>&1
+          uv run --no-sync --with mutmut==3.5.0 mutmut results > mutmut-results.txt 2>&1
+          uv run --no-sync python scripts/mutation_report.py
+          # The full report can be very long for big test files; the run-page
+          # summary cuts off at 1 MB. Append the head of the report (summary
+          # + survivor list) and link out to the artifact for the full body.
+          {
+            head -c 900000 mutation-report.md
+            echo ""
+            echo ""
+            echo "_Full report (with embedded function bodies and test files) is in the workflow artifact._"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload mutmut artifacts
+        if: always()
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
+        with:
+          name: mutmut-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            mutation-report.md
+            mutmut-results.txt
+            mutmut-run.log
+            mutants/mutmut-stats.json
+            mutants/mutmut-cicd-stats.json
+            mutants/litellm/proxy/management_endpoints/**/*.py
+          if-no-files-found: warn
+          retention-days: 14

.github/workflows/osv-scan.yml

@@ -0,0 +1,44 @@
+name: OSV Scan
+
+on:
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
+  schedule:
+    - cron: "23 6 * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  osv-scan:
+    name: osv-scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Download osv-scanner v2.3.8
+        run: |
+          curl -fsSL --retry 3 -o "$RUNNER_TEMP/osv-scanner" \
+            https://github.com/google/osv-scanner/releases/download/v2.3.8/osv-scanner_linux_amd64
+          echo "bc98e15319ed0d515e3f9235287ba53cdc5535d576d24fd573978ecfe9ab92dc  $RUNNER_TEMP/osv-scanner" | sha256sum -c -
+          chmod +x "$RUNNER_TEMP/osv-scanner"
+
+      - name: Scan lockfiles
+        run: |
+          "$RUNNER_TEMP/osv-scanner" scan source \
+            --config osv-scanner.toml \
+            -L uv.lock \
+            -L ui/litellm-dashboard/package-lock.json

.github/workflows/publish_to_pypi.yml

@@ -1,136 +0,0 @@
-name: Publish to PyPI
-
-on:
-  workflow_dispatch:
-
-jobs:
-  preflight-checks:
-    name: Preflight Checks
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: read
-    # No environment — read-only checks, no approval needed
-    outputs:
-      needs_publish: ${{ steps.check-litellm.outputs.needs_publish }}
-      version: ${{ steps.check-litellm.outputs.version }}
-
-    steps:
-      - name: Checkout repo
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Check litellm version on PyPI
-        id: check-litellm
-        run: |
-          VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Checking if litellm $VERSION exists on PyPI..."
-
-          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/litellm/$VERSION/json")
-          if [ "$HTTP_STATUS" = "200" ]; then
-            echo "litellm $VERSION already exists on PyPI. Skipping publish."
-            echo "needs_publish=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "litellm $VERSION not found on PyPI. Publish needed."
-            echo "needs_publish=true" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Sanity check proxy-extras version
-        run: |
-          # Read pinned version from requirements.txt
-          REQ_VERSION=$(grep -oP 'litellm-proxy-extras==\K[0-9.]+' requirements.txt)
-          if [ -z "$REQ_VERSION" ]; then
-            echo "::error::Could not find litellm-proxy-extras version in requirements.txt"
-            exit 1
-          fi
-          echo "requirements.txt pins litellm-proxy-extras==$REQ_VERSION"
-
-          # Read pinned version from pyproject.toml dependency
-          PYPROJECT_VERSION=$(python3 -c "
-          import re
-          with open('pyproject.toml') as f:
-              content = f.read()
-          match = re.search(r'litellm-proxy-extras\s*=\s*\{version\s*=\s*\"([^\"]+)\"', content)
-          if match:
-              print(match.group(1).lstrip('^~>='))
-          else:
-              import sys
-              print('::error::Could not find litellm-proxy-extras dependency in pyproject.toml', file=sys.stderr)
-              sys.exit(1)
-          ")
-          echo "pyproject.toml pins litellm-proxy-extras version: $PYPROJECT_VERSION"
-
-          # Check that both pinned versions match
-          if [ "$REQ_VERSION" != "$PYPROJECT_VERSION" ]; then
-            echo "::error::Version mismatch: requirements.txt has $REQ_VERSION but pyproject.toml has $PYPROJECT_VERSION"
-            exit 1
-          fi
-
-          # Check that the pinned version exists on PyPI
-          echo "Checking if litellm-proxy-extras $REQ_VERSION exists on PyPI..."
-          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/litellm-proxy-extras/$REQ_VERSION/json")
-          if [ "$HTTP_STATUS" != "200" ]; then
-            echo "::error::litellm-proxy-extras $REQ_VERSION is not published on PyPI yet. Publish it before releasing litellm."
-            exit 1
-          fi
-          echo "litellm-proxy-extras $REQ_VERSION exists on PyPI. Sanity check passed."
-
-  publish-litellm:
-    name: Publish litellm to PyPI
-    needs: preflight-checks
-    if: needs.preflight-checks.outputs.needs_publish == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      id-token: write
-      contents: read
-    environment: pypi-publish
-
-    steps:
-      - name: Checkout repo
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Copy model prices backup
-        run: cp model_prices_and_context_window.json litellm/model_prices_and_context_window_backup.json
-
-      - name: Install build tools
-        run: python -m pip install --upgrade pip build==1.4.2
-
-      - name: Build package
-        run: |
-          rm -rf build dist
-          python -m build
-
-      - name: Verify build artifacts
-        env:
-          EXPECTED_VERSION: ${{ needs.preflight-checks.outputs.version }}
-        run: |
-          echo "Contents of dist/:"
-          ls -la dist/
-          # Ensure we have both sdist and wheel
-          ls dist/*.tar.gz
-          ls dist/*.whl
-          # Verify built version matches expected
-          ls dist/ | grep -q "litellm-${EXPECTED_VERSION}" || {
-            echo "::error::Built artifacts do not match expected version $EXPECTED_VERSION"
-            ls dist/
-            exit 1
-          }
-
-      - name: Validate package metadata
-        run: |
-          pip install twine==6.2.0
-          twine check dist/*
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

.github/workflows/read_pyproject_version.yml

@@ -1,28 +0,0 @@
-name: Read Version from pyproject.toml
-
-on:
-  push:
-    branches:
-      - main # Change this to the default branch of your repository
-
-permissions:
-  contents: read
-
-jobs:
-  read-version:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Read version from pyproject.toml
-        id: read-version
-        run: |
-          version=$(grep -m1 '^version' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
-          printf "LITELLM_VERSION=%s" "$version" >> $GITHUB_ENV
-
-      - name: Display version
-        run: echo "Current version is $LITELLM_VERSION"

.github/workflows/results_stats.csv

@@ -1,27 +0,0 @@
-Date,"Ben 
-Ashley",Tom Brooks,Jimmy Cooney,"Sue 
-Daniels",Berlinda Fong,Terry Jones,Angelina Little,Linda Smith
-10/1,FALSE,TRUE,TRUE,TRUE,TRUE,TRUE,FALSE,TRUE
-10/2,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/3,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/4,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/5,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/6,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/7,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/8,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/9,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/10,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/11,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/12,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/13,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/14,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/15,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/16,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/17,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/18,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/19,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/20,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/21,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/22,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-10/23,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE,FALSE
-Total,0,1,1,1,1,1,0,1

.github/workflows/run_llm_translation_tests.py

@@ -325,7 +325,7 @@ def run_tests(test_path: str = "tests/llm_translation/",
     
     # Run pytest
     cmd = [
-        "poetry", "run", "pytest", test_path,
+        "uv", "run", "--no-sync", "pytest", test_path,
         f"--junitxml={junit_xml}",
         "-v",
         "--tb=short",
@@ -335,7 +335,7 @@ def run_tests(test_path: str = "tests/llm_translation/",
     
     # Add timeout if pytest-timeout is installed
     try:
-        subprocess.run(["poetry", "run", "python", "-c", "import pytest_timeout"], 
+        subprocess.run(["uv", "run", "--no-sync", "python", "-c", "import pytest_timeout"], 
                       capture_output=True, check=True)
         cmd.extend(["--timeout=300"])
     except:
@@ -436,4 +436,4 @@ if __name__ == "__main__":
         commit=args.commit
     )
     
-    sys.exit(exit_code)
+    sys.exit(exit_code)

.github/workflows/run_observatory_tests.yml

@@ -1,229 +0,0 @@
-name: Run Observatory Tests
-on:
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: "Docker image tag to test (e.g. v1.61.0.rc1)"
-        required: true
-        type: string
-      commit_hash:
-        description: "Commit hash (defaults to HEAD of current branch)"
-        required: false
-        type: string
-  workflow_call:
-    inputs:
-      tag:
-        description: "Docker image tag to test"
-        required: true
-        type: string
-      commit_hash:
-        description: "Commit hash of the release"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-
-env:
-  LITELLM_MASTER_KEY: ${{ secrets.LITELLM_MASTER_KEY_STAGING }}
-
-jobs:
-  observatory-tests:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Validate tag input
-        env:
-          TAG: ${{ inputs.tag }}
-        run: |
-          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
-            echo "Invalid tag format: $TAG (expected vX.Y.Z...)"
-            exit 1
-          fi
-
-      - name: Start LiteLLM container
-        env:
-          TAG: ${{ inputs.tag }}
-          AZURE_API_KEY: ${{ secrets.AZURE_API_KEY }}
-          AZURE_API_BASE: ${{ secrets.AZURE_API_BASE }}
-          WORKSPACE: ${{ github.workspace }}
-        run: |
-          docker run -d \
-            --name litellm-rc \
-            -p 4000:4000 \
-            -v "${WORKSPACE}/.github/observatory/litellm_config.yaml:/app/config.yaml" \
-            -e LITELLM_MASTER_KEY="${LITELLM_MASTER_KEY}" \
-            -e AZURE_API_KEY="${AZURE_API_KEY}" \
-            -e AZURE_API_BASE="${AZURE_API_BASE}" \
-            "litellm/litellm:${TAG}" \
-            --config /app/config.yaml --port 4000
-
-      - name: Wait for LiteLLM health check
-        run: |
-          echo "Waiting for LiteLLM to be ready..."
-          for i in $(seq 1 30); do
-            if curl -s -f http://localhost:4000/health/liveliness > /dev/null 2>&1; then
-              echo "LiteLLM is healthy"
-              exit 0
-            fi
-            echo "Attempt $i/30 - not ready yet, waiting 10s..."
-            sleep 10
-          done
-          echo "LiteLLM failed to start within 5 minutes"
-          docker logs litellm-rc
-          exit 1
-
-      - name: Start cloudflared tunnel
-        run: |
-          # Install cloudflared (pinned version + checksum)
-          curl -sL https://github.com/cloudflare/cloudflared/releases/download/2025.2.1/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
-          echo "afdfadd1ef552e66bffc35246fe30a9bd578356d2d386de95585ccfc432472b8  /usr/local/bin/cloudflared" | sha256sum -c -
-          chmod +x /usr/local/bin/cloudflared
-
-          # Start a quick tunnel (no account needed) and capture the URL
-          cloudflared tunnel --url http://localhost:4000 --no-autoupdate > /tmp/cloudflared.log 2>&1 &
-          CLOUDFLARED_PID=$!
-          echo "CLOUDFLARED_PID=$CLOUDFLARED_PID" >> $GITHUB_ENV
-
-          # Wait for tunnel URL to appear in logs
-          echo "Waiting for tunnel URL..."
-          for i in $(seq 1 30); do
-            TUNNEL_URL=$(grep -oP 'https://[a-z0-9-]+\.trycloudflare\.com' /tmp/cloudflared.log | head -1 || true)
-            if [ -n "$TUNNEL_URL" ]; then
-              echo "Tunnel URL: $TUNNEL_URL"
-              echo "TUNNEL_URL=$TUNNEL_URL" >> $GITHUB_ENV
-              exit 0
-            fi
-            sleep 2
-          done
-          echo "Failed to get tunnel URL"
-          cat /tmp/cloudflared.log
-          exit 1
-
-      - name: Verify tunnel connectivity
-        run: |
-          echo "Testing tunnel at ${TUNNEL_URL}..."
-          # Quick tunnels need time for DNS propagation; retry to avoid
-          # transient NXDOMAIN (curl exit code 6) on first attempt.
-          for i in $(seq 1 10); do
-            if curl -sf "${TUNNEL_URL}/health/liveliness" > /dev/null 2>&1; then
-              echo "Tunnel is working (attempt $i)"
-              exit 0
-            fi
-            echo "Attempt $i/10 - tunnel not routable yet, waiting 5s..."
-            sleep 5
-          done
-          echo "Tunnel failed to become reachable after 50s"
-          cat /tmp/cloudflared.log
-          exit 1
-
-      - name: Trigger observatory test run
-        id: trigger
-        env:
-          OBSERVATORY_URL: ${{ secrets.OBSERVATORY_URL }}
-          OBSERVATORY_API_KEY: ${{ secrets.OBSERVATORY_API_KEY }}
-        run: |
-          PAYLOAD=$(jq -n \
-            --arg url "${TUNNEL_URL}" \
-            --arg key "${LITELLM_MASTER_KEY}" \
-            '{
-              deployment_url: $url,
-              api_key: $key,
-              test_suite: "TestOAIAzureRelease",
-              models: ["gpt-4o-mini", "gpt-4o"]
-            }')
-          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "${OBSERVATORY_URL}/run-test" \
-            -H "Content-Type: application/json" \
-            -H "X-LiteLLM-Observatory-API-Key: ${OBSERVATORY_API_KEY}" \
-            -d "$PAYLOAD")
-          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
-          BODY=$(echo "$RESPONSE" | head -n -1)
-          echo "Response ($HTTP_CODE): $BODY"
-          if [ "$HTTP_CODE" -ge 400 ]; then
-            echo "Failed to trigger test run"
-            exit 1
-          fi
-
-          # Extract request_id for polling this specific run
-          REQUEST_ID=$(echo "$BODY" | jq -r '.results.request_id')
-          if [ -z "$REQUEST_ID" ] || [ "$REQUEST_ID" = "null" ]; then
-            echo "Failed to extract request_id from response"
-            exit 1
-          fi
-          echo "Request ID: $REQUEST_ID"
-          echo "request_id=$REQUEST_ID" >> $GITHUB_OUTPUT
-
-      - name: Poll for test completion
-        id: poll
-        env:
-          OBSERVATORY_URL: ${{ secrets.OBSERVATORY_URL }}
-          OBSERVATORY_API_KEY: ${{ secrets.OBSERVATORY_API_KEY }}
-          REQUEST_ID: ${{ steps.trigger.outputs.request_id }}
-        run: |
-          TIMEOUT=900  # 15 minutes
-          INTERVAL=30
-          ELAPSED=0
-          while [ $ELAPSED -lt $TIMEOUT ]; do
-            STATUS=$(curl -s "${OBSERVATORY_URL}/run-status/${REQUEST_ID}" \
-              -H "X-LiteLLM-Observatory-API-Key: ${OBSERVATORY_API_KEY}")
-            RUN_STATUS=$(echo "$STATUS" | jq -r '.status')
-            echo "Run status (${ELAPSED}s elapsed): $RUN_STATUS"
-
-            if [ "$RUN_STATUS" = "completed" ] || [ "$RUN_STATUS" = "failed" ]; then
-              echo "Test finished with status: $RUN_STATUS"
-              echo "$STATUS" > /tmp/observatory_result.json
-              exit 0
-            fi
-
-            sleep $INTERVAL
-            ELAPSED=$((ELAPSED + INTERVAL))
-          done
-          echo "Timed out waiting for test to complete after ${TIMEOUT}s"
-          exit 1
-
-      - name: Verify test results
-        run: |
-          RESULT=$(cat /tmp/observatory_result.json)
-          echo "Full result: $RESULT"
-
-          STATUS=$(echo "$RESULT" | jq -r '.status')
-          TEST_PASSED=$(echo "$RESULT" | jq -r '.result.test_passed // false')
-          FAILURE_RATE=$(echo "$RESULT" | jq -r '.result.failure_rate // "N/A"')
-          ERROR=$(echo "$RESULT" | jq -r '.error // empty')
-
-          echo "Status: $STATUS"
-          echo "Test passed: $TEST_PASSED"
-          echo "Failure rate: $FAILURE_RATE"
-
-          if [ -n "$ERROR" ]; then
-            echo "Error: $ERROR"
-          fi
-
-          if [ "$STATUS" = "failed" ]; then
-            echo "Test run failed"
-            exit 1
-          fi
-
-          if [ "$TEST_PASSED" != "true" ]; then
-            echo "Tests did not pass (failure rate: $FAILURE_RATE)"
-            exit 1
-          fi
-
-          echo "All tests passed!"
-
-      - name: Print LiteLLM logs on failure
-        if: failure()
-        run: |
-          docker logs litellm-rc 2>/dev/null || true
-          cat /tmp/cloudflared.log 2>/dev/null || true
-
-      - name: Cleanup
-        if: always()
-        run: |
-          kill "$CLOUDFLARED_PID" 2>/dev/null || true
-          docker rm -f litellm-rc 2>/dev/null || true

.github/workflows/scan_duplicate_issues.yml

@@ -1,48 +0,0 @@
-name: Scan Duplicate Issues (One-Time)
-
-on:
-  workflow_dispatch:
-    inputs:
-      threshold:
-        description: "Similarity threshold (0-1)"
-        required: false
-        default: "0.85"
-      close:
-        description: "Actually close duplicates (false = dry run)"
-        required: false
-        type: boolean
-        default: false
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      contents: read
-    steps:
-      - name: Checkout scripts
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          sparse-checkout: .github/scripts
-          persist-credentials: false
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.13"
-
-      - name: Scan for duplicate issues
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          INPUT_THRESHOLD: ${{ inputs.threshold }}
-          INPUT_CLOSE: ${{ inputs.close }}
-        run: |
-          CLOSE_FLAG=""
-          if [ "$INPUT_CLOSE" = "true" ]; then
-            CLOSE_FLAG="--close"
-          fi
-          python3 .github/scripts/close_duplicate_issues.py \
-            --scan \
-            --repo ${{ github.repository }} \
-            --threshold "$INPUT_THRESHOLD" \
-            $CLOSE_FLAG

.github/workflows/test-code-quality.yml

@@ -0,0 +1,128 @@
+name: Code Quality Checks
+
+on:
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  code-quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Checkout litellm-docs into docs/my-website (for documentation_tests)
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          repository: BerriAI/litellm-docs
+          path: docs/my-website
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
+
+      - name: Cache uv dependencies
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups --all-extras
+
+      - name: check_licenses
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_licenses.py
+
+      - name: check_provider_folders_documented
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_provider_folders_documented.py
+
+      - name: router_code_coverage
+        run: uv run --no-sync python ./tests/code_coverage_tests/router_code_coverage.py
+
+      - name: test_chat_completion_imports
+        run: uv run --no-sync python ./tests/code_coverage_tests/test_chat_completion_imports.py
+
+      - name: info_log_check
+        run: uv run --no-sync python ./tests/code_coverage_tests/info_log_check.py
+
+      - name: check_guardrail_apply_decorator
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_guardrail_apply_decorator.py
+
+      - name: test_ban_set_verbose
+        run: uv run --no-sync python ./tests/code_coverage_tests/test_ban_set_verbose.py
+
+      - name: code_qa_check_tests
+        run: uv run --no-sync python ./tests/code_coverage_tests/code_qa_check_tests.py
+
+      - name: check_get_model_cost_key_performance
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_get_model_cost_key_performance.py
+
+      - name: test_proxy_types_import
+        run: uv run --no-sync python ./tests/code_coverage_tests/test_proxy_types_import.py
+
+      - name: callback_manager_test
+        run: uv run --no-sync python ./tests/code_coverage_tests/callback_manager_test.py
+
+      - name: recursive_detector
+        run: uv run --no-sync python ./tests/code_coverage_tests/recursive_detector.py
+
+      - name: test_router_strategy_async
+        run: uv run --no-sync python ./tests/code_coverage_tests/test_router_strategy_async.py
+
+      - name: litellm_logging_code_coverage
+        run: uv run --no-sync python ./tests/code_coverage_tests/litellm_logging_code_coverage.py
+
+      - name: ensure_async_clients_test
+        run: uv run --no-sync python ./tests/code_coverage_tests/ensure_async_clients_test.py
+
+      - name: enforce_llms_folder_style
+        run: uv run --no-sync python ./tests/code_coverage_tests/enforce_llms_folder_style.py
+
+      - name: prevent_key_leaks_in_exceptions
+        run: uv run --no-sync python ./tests/code_coverage_tests/prevent_key_leaks_in_exceptions.py
+
+      - name: check_unsafe_enterprise_import
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_unsafe_enterprise_import.py
+
+      - name: ban_copy_deepcopy_kwargs
+        run: uv run --no-sync python ./tests/code_coverage_tests/ban_copy_deepcopy_kwargs.py
+
+      - name: check_fastuuid_usage
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_fastuuid_usage.py
+
+      - name: memory_test
+        run: uv run --no-sync python ./tests/code_coverage_tests/memory_test.py
+
+      - name: documentation_test_env_keys
+        run: uv run --no-sync python ./tests/documentation_tests/test_env_keys.py
+
+      - name: documentation_test_router_settings
+        run: uv run --no-sync python ./tests/documentation_tests/test_router_settings.py
+
+      - name: documentation_test_api_docs
+        run: uv run --no-sync python ./tests/documentation_tests/test_api_docs.py

.github/workflows/test-linting.yml

@@ -2,7 +2,11 @@ name: LiteLLM Linting
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read
@@ -10,11 +14,15 @@ permissions:
 jobs:
   lint:
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 15
 
     steps:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        # Check out the PR head, not the default refs/pull/N/merge: the merge ref
+        # folds in newer base commits, which the diff-based gates (ruff delta,
+        # Any-discipline) would otherwise blame on this branch.
         with:
+          ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0
           clean: true
           persist-credentials: false
@@ -24,26 +32,28 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
 
       - name: Clean Python cache
         run: |
           find . -type d -name "__pycache__" -exec rm -rf {} + || true
           find . -name "*.pyc" -delete || true
 
-      - name: Check poetry.lock is up to date
+      - name: Check uv.lock is up to date
         run: |
-          poetry check --lock || (echo "❌ poetry.lock is out of sync with pyproject.toml. Run 'poetry lock' locally and commit the result." && exit 1)
+          uv lock --check || (echo "❌ uv.lock is out of sync with pyproject.toml. Run 'uv lock' locally and commit the result." && exit 1)
 
       - name: Install dependencies
         run: |
-          poetry install --with dev
+          uv sync --frozen
 
       - name: Check Black formatting
         run: |
           cd litellm
-          poetry run black --check --exclude '/enterprise/' .
+          uv run --no-sync black --check --exclude '/enterprise/' .
           cd ..
 
       - name: Debug - Check file state
@@ -58,28 +68,67 @@ jobs:
       - name: Run Ruff linting
         run: |
           cd litellm
-          poetry run ruff check .
+          uv run --no-sync ruff check .
           cd ..
 
+      - name: Check strict-rule budget (delta vs base)
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          uv run --no-sync python scripts/ruff_strict_gate.py --base "$BASE_SHA"
+
+      - name: Check type-discipline budget (mutable collections / casts / type guards / kwargs / unexplained suppressions, delta vs base)
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          uv run --no-sync python scripts/type_discipline_gate.py --base "$BASE_SHA"
+
       - name: Print OpenAI version
         run: |
-          poetry run python -c "import openai; print(f'OpenAI version: {openai.__version__}')"
+          uv run --no-sync python -c "import openai; print(f'OpenAI version: {openai.__version__}')"
 
-      - name: Run MyPy type checking
+      - name: Check basedpyright budget (delta vs base)
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
         run: |
-          cd litellm
-          poetry run mypy . 
-          cd ..
+          (uv run --no-sync basedpyright --outputjson || true) | uv run --no-sync python scripts/type_check_gate.py --base "$BASE_SHA"
 
       - name: Check for circular imports
         run: |
           cd litellm
-          poetry run python ../tests/documentation_tests/test_circular_imports.py
+          uv run --no-sync python ../tests/documentation_tests/test_circular_imports.py
           cd ..
 
       - name: Check import safety
         run: |
-          poetry run python -c "from litellm import *" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)
+          uv run --no-sync python -c "from litellm import *" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)
+
+  # Intentionally NON-GATING. This job turns red when a *-budget.json ceiling is
+  # raised (or a rule/budget is dropped) so a loosening is obvious in review, but it
+  # must be kept OUT of the branch-protection required-checks list so a justified
+  # bump can still be merged by a human who has seen and accepted the red.
+  budget-ratchet:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Ratchet check (budgets may only decrease; non-gating)
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          python scripts/budget_ratchet_check.py --base "$BASE_SHA"
 
   secret-scan:
     runs-on: ubuntu-latest
@@ -98,18 +147,21 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
+
       - name: Run secret scan test
         run: |
-          pip install 'pytest==9.0.2'
-          pytest tests/litellm/test_no_hardcoded_secrets.py -v
+          uv run --frozen --with 'pytest==9.0.2' pytest tests/litellm/test_no_hardcoded_secrets.py -v
 
       - name: Run ggshield secret scan
         env:
           GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}
         run: |
           if [ -n "$GITGUARDIAN_API_KEY" ]; then
-            pip install 'ggshield==1.48.0'
-            ggshield secret scan repo .
+            uv tool run --from 'ggshield==1.48.0' ggshield secret scan repo .
           else
             echo "GITGUARDIAN_API_KEY not set, skipping ggshield scan"
           fi

.github/workflows/test-litellm-ui-build.yml

@@ -4,7 +4,11 @@ permissions:
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 jobs:
   build-ui:
@@ -21,7 +25,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           node-version: "20"
           cache: "npm"
@@ -32,3 +36,79 @@ jobs:
 
       - name: Build
         run: npm run build
+
+  frontend-lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    defaults:
+      run:
+        working-directory: ui/litellm-dashboard
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Collect changed files
+        id: changed
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          : > "$RUNNER_TEMP/prettier_files.txt"
+          : > "$RUNNER_TEMP/eslint_files.txt"
+          while IFS= read -r f; do
+            [ -f "$f" ] || continue
+            case "$f" in
+              *.js | *.jsx | *.ts | *.tsx | *.mjs | *.cjs)
+                printf '%s\n' "$f" >> "$RUNNER_TEMP/prettier_files.txt"
+                printf '%s\n' "$f" >> "$RUNNER_TEMP/eslint_files.txt" ;;
+              *.json | *.css | *.scss | *.md | *.mdx | *.yml | *.yaml | *.html)
+                printf '%s\n' "$f" >> "$RUNNER_TEMP/prettier_files.txt" ;;
+            esac
+          done < <(git diff --name-only --diff-filter=ACMR --relative "$BASE_SHA"...HEAD -- .)
+          if [ -s "$RUNNER_TEMP/prettier_files.txt" ] || [ -s "$RUNNER_TEMP/eslint_files.txt" ]; then
+            echo "has_files=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_files=false" >> "$GITHUB_OUTPUT"
+            echo "No lintable UI files changed in this PR; nothing to check."
+          fi
+
+      - name: Setup Node.js
+        if: steps.changed.outputs.has_files == 'true'
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: ui/litellm-dashboard/package-lock.json
+
+      - name: Install dependencies
+        if: steps.changed.outputs.has_files == 'true'
+        run: npm ci
+
+      - name: Lint changed files (prettier + eslint)
+        if: steps.changed.outputs.has_files == 'true'
+        run: |
+          prettier_files=()
+          eslint_files=()
+          while IFS= read -r f; do prettier_files+=("$f"); done < "$RUNNER_TEMP/prettier_files.txt"
+          while IFS= read -r f; do eslint_files+=("$f"); done < "$RUNNER_TEMP/eslint_files.txt"
+          status=0
+          if [ ${#prettier_files[@]} -gt 0 ]; then
+            echo "::group::Prettier (${#prettier_files[@]} files)"
+            npx prettier --check "${prettier_files[@]}" || { status=1; echo "::error::Unformatted files. Fix with: npm run format"; }
+            echo "::endgroup::"
+          fi
+          if [ ${#eslint_files[@]} -gt 0 ]; then
+            echo "::group::ESLint (${#eslint_files[@]} files)"
+            npx eslint --no-warn-ignored --pass-on-unpruned-suppressions "${eslint_files[@]}" || status=1
+            echo "::endgroup::"
+          fi
+          exit $status
+
+      - name: Check lint budgets
+        if: ${{ !cancelled() && steps.changed.outputs.has_files == 'true' }}
+        run: |
+          npx eslint . -f json -o "$RUNNER_TEMP/lint-report.json" || true
+          node scripts/check-lint-budgets.mjs "$RUNNER_TEMP/lint-report.json" eslint-budgets.json

.github/workflows/test-litellm.yml

@@ -1,53 +0,0 @@
-name: LiteLLM Mock Tests (folder - tests/test_litellm)
-
-# DEPRECATED: This workflow is replaced by test-litellm-matrix.yml which runs
-# the same tests in parallel across 10 jobs for faster CI times.
-# Kept for manual debugging only.
-on:
-  workflow_dispatch: # Manual trigger only
-  # pull_request:
-  #   branches: [ main ]
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 25
-
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Thank You Message
-        run: |
-          echo "### 🙏 Thank you for contributing to LiteLLM!" >> $GITHUB_STEP_SUMMARY
-          echo "Your PR is being tested now. We appreciate your help in making LiteLLM better!" >> $GITHUB_STEP_SUMMARY
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
-
-      - name: Install dependencies
-        run: |
-          poetry lock
-          poetry install --with dev,proxy-dev --extras "proxy semantic-router"
-          poetry run pip install "pytest-retry==1.6.3"
-          poetry run pip install 'pytest-xdist==3.8.0'
-          poetry run pip install "google-genai==1.22.0"
-          poetry run pip install "google-cloud-aiplatform==1.115.0"
-          poetry run pip install "fastapi-offline==1.7.3"
-          poetry run pip install "python-multipart==0.0.22"
-          poetry run pip install "openapi-core==0.23.0"
-      - name: Setup litellm-enterprise as local package
-        run: |
-          poetry run pip install --force-reinstall --no-deps -e enterprise/
-      - name: Run tests
-        run: |
-          poetry run pytest tests/test_litellm --tb=short -vv --maxfail=10 -n 4 --durations=50

.github/workflows/test-mcp.yml

@@ -2,7 +2,11 @@ name: LiteLLM MCP Tests (folder - tests/mcp_tests)
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read
@@ -27,26 +31,16 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
 
       - name: Install dependencies
         run: |
-          poetry lock
-          poetry install --with dev,proxy-dev --extras "proxy semantic-router"
-          poetry run pip install "pytest==7.3.1"
-          poetry run pip install "pytest-retry==1.6.3"
-          poetry run pip install "pytest-cov==5.0.0"
-          poetry run pip install "pytest-asyncio==0.21.1"
-          poetry run pip install "respx==0.22.0"
-          poetry run pip install "pydantic==2.11.0"
-          poetry run pip install "mcp==1.25.0"
-          poetry run pip install 'pytest-xdist==3.8.0'
-
-      - name: Setup litellm-enterprise as local package
-        run: |
-          poetry run pip install --force-reinstall --no-deps -e enterprise/
+          uv lock --check
+          uv sync --frozen --group proxy-dev --extra proxy --extra semantic-router
 
       - name: Run MCP tests
         run: |
-          poetry run pytest tests/mcp_tests -x -vv -n 4 --cov=litellm --cov-report=xml --durations=5
+          uv run --no-sync pytest tests/mcp_tests -x -vv -n 4 --cov=./litellm --cov-report=xml --durations=5

.github/workflows/test-model-map.yaml

@@ -2,7 +2,11 @@ name: Validate model_prices_and_context_window.json
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-rust.yml

@@ -0,0 +1,65 @@
+name: LiteLLM Rust
+
+on:
+  push:
+    paths:
+      - "litellm-rust/**"
+      - ".github/workflows/test-rust.yml"
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
+    paths:
+      - "litellm-rust/**"
+      - ".github/workflows/test-rust.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rust-checks:
+    name: rustfmt, clippy, test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: litellm-rust
+    env:
+      CARGO_TERM_COLOR: always
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Rust
+        run: |
+          rustup toolchain install stable --profile minimal --component clippy,rustfmt
+          rustup default stable
+
+      - name: Cache Cargo registry and target
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            litellm-rust/target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('litellm-rust/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Check Rust formatting
+        run: cargo fmt --check
+
+      - name: Run Clippy
+        run: cargo clippy --workspace --all-targets --locked -- -D warnings
+
+      - name: Run Rust tests
+        run: cargo test --workspace --locked

.github/workflows/test-semgrep.yml

@@ -0,0 +1,39 @@
+name: Semgrep
+
+on:
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  semgrep:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
+
+      - name: Run Semgrep (custom rules)
+        run: uv tool run --from 'semgrep==1.157.0' semgrep scan --config .semgrep/rules . --error

.github/workflows/test-unit-caching-redis.yml

@@ -1,41 +0,0 @@
-name: "Unit Tests: Caching (Redis)"
-
-# Uses cloud Redis credentials — only runs on trusted branches, not PRs.
-# This prevents external PRs from accessing Redis credentials.
-on:
-  push:
-    branches: [main, "litellm_*"]
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  caching-redis:
-    uses: ./.github/workflows/_test-unit-services-base.yml
-    with:
-      # Redis-only tests that do NOT require provider API keys.
-      # Tests needing API keys (test_caching.py, test_caching_ssl.py, test_prometheus_service.py,
-      # test_router_caching.py) are in Phase 3 integration workflows.
-      test-path: >-
-        tests/local_testing/test_dual_cache.py
-        tests/local_testing/test_redis_batch_optimizations.py
-        tests/local_testing/test_router_utils.py
-      workers: 2
-      reruns: 2
-      timeout-minutes: 20
-      enable-redis: true
-      enable-postgres: false
-      artifact-name: caching-redis
-    secrets:
-      REDIS_HOST: ${{ secrets.REDIS_HOST }}
-      REDIS_PORT: ${{ secrets.REDIS_PORT }}
-      REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD }}
-      DATABASE_URL: ${{ secrets.DATABASE_URL }}
-      POSTGRES_USER: ${{ secrets.POSTGRES_USER }}
-      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}

.github/workflows/test-unit-core-utils.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Core Utilities"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-documentation.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Documentation Validation"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read
@@ -21,47 +25,47 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Checkout litellm-docs into docs/my-website (for documentation_tests)
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          repository: BerriAI/litellm-docs
+          path: docs/my-website
+          persist-credentials: false
+
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
 
-      - name: Cache Poetry dependencies
+      - name: Cache uv dependencies
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
-            ~/.cache/pypoetry
-            ~/.cache/pip
+            ~/.cache/uv
             .venv
-          key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
           restore-keys: |
-            ${{ runner.os }}-poetry-
+            ${{ runner.os }}-uv-
 
       - name: Install dependencies
         run: |
-          poetry config virtualenvs.in-project true
-          poetry install --with dev,proxy-dev --extras "proxy semantic-router"
-          poetry run pip install google-genai==1.22.0 \
-            google-cloud-aiplatform==1.115.0 fastapi-offline==1.7.3 python-multipart==0.0.22 openapi-core==0.23.0
-
-      - name: Setup litellm-enterprise
-        run: |
-          poetry run pip install --force-reinstall --no-deps -e enterprise/
+          uv sync --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router
 
       - name: Generate Prisma client
         env:
           PRISMA_BINARY_CACHE_DIR: ${{ runner.temp }}/prisma-cache
         run: |
-          poetry run pip install nodejs-wheel-binaries==24.13.1
-          poetry run prisma generate --schema litellm/proxy/schema.prisma
+          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
 
       # Run the same documentation tests that CircleCI ran (as direct Python scripts)
       - name: Run documentation validation tests
         run: |
-          poetry run python ./tests/documentation_tests/test_env_keys.py
-          poetry run python ./tests/documentation_tests/test_router_settings.py
-          poetry run python ./tests/documentation_tests/test_api_docs.py
-          poetry run python ./tests/documentation_tests/test_circular_imports.py
+          uv run --no-sync python ./tests/documentation_tests/test_env_keys.py
+          uv run --no-sync python ./tests/documentation_tests/test_router_settings.py
+          uv run --no-sync python ./tests/documentation_tests/test_api_docs.py
+          uv run --no-sync python ./tests/documentation_tests/test_circular_imports.py

.github/workflows/test-unit-enterprise-routing.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Enterprise, Google GenAI & Routing"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-integrations.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Integrations (Callbacks & Logging)"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-llm-providers.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: LLM Provider Transformations"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-misc.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: MCP, Secrets, Containers & Misc"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read
@@ -24,9 +28,13 @@ jobs:
         tests/test_litellm/completion_extras
         tests/test_litellm/containers
         tests/test_litellm/experimental_mcp_client
+        tests/test_litellm/models
+        tests/test_litellm/repositories
         tests/test_litellm/images
         tests/test_litellm/interactions
+        tests/test_litellm/ocr
         tests/test_litellm/passthrough
+        tests/test_litellm/sandbox
         tests/test_litellm/vector_stores
         tests/test_litellm/test_*.py
       workers: 2

.github/workflows/test-unit-proxy-auth.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Proxy Auth & Key Management"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-proxy-db.yml

@@ -1,9 +1,10 @@
 name: "Unit Tests: Proxy DB Operations"
 
-# Uses DATABASE_URL secret — only runs on trusted branches, not PRs.
 on:
-  push:
-    branches: [main, "litellm_*"]
+  pull_request:
+    branches:
+      - main
+      - litellm_internal_staging
 
 permissions:
   contents: read
@@ -12,8 +13,71 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# Semantic matrix: each shard groups tests by concern (auth, server, logging, …)
+# rather than alphabetical letter ranges. Adding a new test file means adding it
+# to whichever group it belongs to, not reshuffling slices.
+#
+# Design targets:
+#   * Every shard runs in <= 7 minutes of wall-clock on the default runner.
+#     Most of a shard's time is pytest plugin load + xdist worker imports +
+#     pytest-cov instrumentation, not the tests themselves. Keeping per-shard
+#     work low and matching worker count to runner cores is what controls it.
+#   * workers: 4 matches the 4-core ubuntu-latest runner. -n 8 on 4 cores
+#     oversubscribes 2x and workers fight for CPU during their cold-start
+#     imports (measured ~441% CPU for -n 8 locally, i.e. ~55% effective).
+#   * test_key_generate_prisma.py stays serial (workers=0) — it has event-loop
+#     conflicts with the logging worker when run in parallel.
+#   * test_proxy_utils.py runs as a single shard with --dist=worksteal so
+#     xdist balances its 188 parametrized cases across workers instead of
+#     pinning the whole file to one worker (the default --dist=loadscope
+#     behavior for single-file targets).
 jobs:
+  # Fast guard — fails the workflow if a test_*.py file under
+  # tests/proxy_unit_tests/ is not referenced by any matrix entry below.
+  # The semantic-shard design (no catch-all "remaining" bucket) relies on
+  # every test file being explicitly assigned; this guard prevents a new
+  # file from silently dropping out of CI.
+  assert-shard-coverage:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+      - name: Assert every test_*.py is in a matrix shard
+        run: |
+          python3 - <<'PY'
+          import pathlib, sys, yaml
+          wf = yaml.safe_load(open(".github/workflows/test-unit-proxy-db.yml"))
+          matrix = wf["jobs"]["proxy-db"]["strategy"]["matrix"]["include"]
+          referenced = set()
+          for entry in matrix:
+              for token in entry["test-path"].split():
+                  if token.startswith("tests/proxy_unit_tests/"):
+                      referenced.add(pathlib.PurePosixPath(token).name)
+          actual = {p.name for p in pathlib.Path("tests/proxy_unit_tests").iterdir()
+                    if p.name.startswith("test_") and (p.suffix == ".py" or p.is_dir())
+                    and p.name != "test_configs"}
+          orphans = sorted(actual - referenced)
+          if orphans:
+              print("ERROR: the following files/dirs under tests/proxy_unit_tests/")
+              print("       are not assigned to any shard in test-unit-proxy-db.yml:")
+              for o in orphans:
+                  print(f"  - {o}")
+              print()
+              print("Add each to whichever semantic shard it belongs to.")
+              sys.exit(1)
+          print(f"OK: all {len(actual)} files assigned to a shard.")
+          PY
+
   proxy-db:
+    needs: assert-shard-coverage
+    # Display only the semantic shard name in the checks UI instead of GHA's
+    # default "proxy-db (key-generation, tests/proxy_unit_tests/…, 0, loadscope, 20)"
+    # which includes every matrix field and gets truncated past the test-path.
+    name: ${{ matrix.test-group }}
     permissions:
       contents: read
       id-token: write
@@ -22,29 +86,143 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # Key generation tests must NOT run in parallel (event loop conflicts with logging worker)
+          # Must run serially — event-loop conflict with the logging worker.
           - test-group: key-generation
             test-path: "tests/proxy_unit_tests/test_key_generate_prisma.py"
             workers: 0
-            timeout: 30
+            dist: loadscope
+            timeout: 20
+
+          # ---- auth: split into 2 shards ----
           - test-group: auth-checks
-            test-path: "tests/proxy_unit_tests/test_auth_checks.py tests/proxy_unit_tests/test_user_api_key_auth.py"
-            workers: 8
-            timeout: 20
-          - test-group: remaining
-            test-path: "tests/proxy_unit_tests --ignore=tests/proxy_unit_tests/test_key_generate_prisma.py --ignore=tests/proxy_unit_tests/test_auth_checks.py --ignore=tests/proxy_unit_tests/test_user_api_key_auth.py"
-            workers: 8
-            timeout: 20
-    uses: ./.github/workflows/_test-unit-services-base.yml
+            test-path: >-
+              tests/proxy_unit_tests/test_auth_checks.py
+              tests/proxy_unit_tests/test_user_api_key_auth.py
+              tests/proxy_unit_tests/test_deprecated_key_grace_period.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+          - test-group: jwt-and-keys
+            test-path: >-
+              tests/proxy_unit_tests/test_jwt.py
+              tests/proxy_unit_tests/test_jwt_key_mapping.py
+              tests/proxy_unit_tests/test_proxy_custom_auth.py
+              tests/proxy_unit_tests/test_key_generate_dynamodb.py
+              tests/proxy_unit_tests/test_deployed_proxy_keygen.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+
+          # ---- test_proxy_utils.py, single shard, worksteal distribution ----
+          - test-group: proxy-utils
+            test-path: "tests/proxy_unit_tests/test_proxy_utils.py"
+            workers: 4
+            dist: worksteal
+            timeout: 15
+
+          # ---- proxy server: split into 2 shards ----
+          - test-group: proxy-server-core
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_server.py
+              tests/proxy_unit_tests/test_proxy_server_keys.py
+              tests/proxy_unit_tests/test_proxy_server_caching.py
+              tests/proxy_unit_tests/test_proxy_server_langfuse.py
+              tests/proxy_unit_tests/test_proxy_server_spend.py
+              tests/proxy_unit_tests/test_aproxy_startup.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+          - test-group: proxy-runtime
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_config_unit_test.py
+              tests/proxy_unit_tests/test_proxy_routes.py
+              tests/proxy_unit_tests/test_proxy_gunicorn.py
+              tests/proxy_unit_tests/test_server_root_path.py
+              tests/proxy_unit_tests/test_proxy_pass_user_config.py
+              tests/proxy_unit_tests/test_proxy_token_counter.py
+              tests/proxy_unit_tests/test_request_size_limit_middleware.py
+              tests/proxy_unit_tests/test_multipart_bypass_repro.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+
+          # ---- logging: split into 2 shards ----
+          - test-group: custom-logging
+            test-path: >-
+              tests/proxy_unit_tests/test_custom_callback_input.py
+              tests/proxy_unit_tests/test_custom_logger_s3_gcs.py
+              tests/proxy_unit_tests/test_proxy_custom_logger.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+          - test-group: logging-misc
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_reject_logging.py
+              tests/proxy_unit_tests/test_audit_logs_proxy.py
+              tests/proxy_unit_tests/test_search_api_logging.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+
+          - test-group: db-and-spend
+            test-path: >-
+              tests/proxy_unit_tests/test_prisma_client_backoff_retry.py
+              tests/proxy_unit_tests/test_db_schema_changes.py
+              tests/proxy_unit_tests/test_e2e_pod_lock_manager.py
+              tests/proxy_unit_tests/test_skills_db.py
+              tests/proxy_unit_tests/test_update_daily_tag_spend.py
+              tests/proxy_unit_tests/test_update_spend.py
+              tests/proxy_unit_tests/test_proxy_encrypt_decrypt.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+
+          # ---- guardrails + budget + hooks: split into 2 ----
+          - test-group: guardrails-hooks
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_setting_guardrails.py
+              tests/proxy_unit_tests/test_banned_keyword_list.py
+              tests/proxy_unit_tests/test_unit_test_proxy_hooks.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+          - test-group: budgets
+            test-path: >-
+              tests/proxy_unit_tests/test_default_end_user_budget_simple.py
+              tests/proxy_unit_tests/test_unit_test_max_model_budget_limiter.py
+              tests/proxy_unit_tests/test_zero_cost_model_budget_bypass.py
+            workers: 4
+            dist: loadscope
+            timeout: 15
+
+          - test-group: endpoints-and-responses
+            test-path: >-
+              tests/proxy_unit_tests/test_blog_posts_endpoint.py
+              tests/proxy_unit_tests/test_models_fallback_endpoint.py
+              tests/proxy_unit_tests/test_google_endpoint_routing.py
+              tests/proxy_unit_tests/test_google_gemini_proxy_request.py
+              tests/proxy_unit_tests/test_gemini_agents_endpoints.py
+              tests/proxy_unit_tests/test_get_favicon.py
+              tests/proxy_unit_tests/test_get_image.py
+              tests/proxy_unit_tests/test_reducto_ocr_route.py
+              tests/proxy_unit_tests/test_ui_path_detection.py
+              tests/proxy_unit_tests/test_prompt_test_endpoint.py
+              tests/proxy_unit_tests/test_check_batch_cost.py
+              tests/proxy_unit_tests/test_check_responses_cost.py
+              tests/proxy_unit_tests/test_response_polling_handler.py
+              tests/proxy_unit_tests/test_response_polling_pre_call_checks.py
+              tests/proxy_unit_tests/test_realtime_cache.py
+              tests/proxy_unit_tests/test_proxy_exception_mapping.py
+              tests/proxy_unit_tests/test_custom_tokenizer_bug.py
+              tests/proxy_unit_tests/test_model_response_typing
+            workers: 4
+            dist: loadscope
+            timeout: 15
+    uses: ./.github/workflows/_test-unit-base.yml
     with:
       test-path: ${{ matrix.test-path }}
       workers: ${{ matrix.workers }}
       reruns: 2
       timeout-minutes: ${{ matrix.timeout }}
-      enable-redis: false
-      enable-postgres: true
+      dist: ${{ matrix.dist }}
       artifact-name: proxy-db-${{ matrix.test-group }}
-    secrets:
-      DATABASE_URL: ${{ secrets.DATABASE_URL }}
-      POSTGRES_USER: ${{ secrets.POSTGRES_USER }}
-      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}

.github/workflows/test-unit-proxy-endpoints.yml

@@ -2,12 +2,15 @@ name: "Unit Tests: Proxy API Endpoints"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
+  workflow_dispatch:
 
 permissions:
   contents: read
-  id-token: write
-  pull-requests: write
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -15,6 +18,10 @@ concurrency:
 
 jobs:
   proxy-endpoints:
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
     uses: ./.github/workflows/_test-unit-base.yml
     with:
       test-path: >-
@@ -28,11 +35,33 @@ jobs:
         tests/test_litellm/proxy/image_endpoints
         tests/test_litellm/proxy/vector_store_endpoints
         tests/test_litellm/proxy/agent_endpoints
+        tests/test_litellm/proxy/a2a
         tests/test_litellm/proxy/discovery_endpoints
         tests/test_litellm/proxy/health_endpoints
+        tests/test_litellm/proxy/shutdown
         tests/test_litellm/proxy/public_endpoints
         tests/test_litellm/proxy/prompts
+        tests/test_litellm/proxy/rag_endpoints
+        tests/test_litellm/proxy/realtime_endpoints
         tests/test_litellm/proxy/ui_crud_endpoints
+        tests/test_litellm/proxy/utils
       workers: 2
       reruns: 2
       artifact-name: proxy-endpoints
+
+  # Behavior-pinning tests for litellm/proxy/proxy_server.py. Owns its
+  # own job (not a path on the proxy-endpoints job above) so its budget
+  # is independent and its coverage artifact is uploaded separately.
+  # See: https://www.notion.so/36c43b8acdab81ee845fd5365128a2fc
+  proxy-server:
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+    uses: ./.github/workflows/_test-unit-base.yml
+    with:
+      test-path: tests/test_litellm/proxy/proxy_server
+      workers: 4
+      reruns: 2
+      timeout-minutes: 60
+      artifact-name: proxy-server

.github/workflows/test-unit-proxy-infra.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Proxy Infrastructure"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-proxy-legacy.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Proxy Legacy Tests"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read
@@ -24,7 +28,7 @@ jobs:
           - name: "key-generation"
             path: "tests/proxy_unit_tests/test_[k-o]*.py"
           - name: "proxy-config"
-            path: "tests/proxy_unit_tests/test_prisma*.py tests/proxy_unit_tests/test_project*.py tests/proxy_unit_tests/test_prompt*.py tests/proxy_unit_tests/test_proxy_[c-r]*.py"
+            path: "tests/proxy_unit_tests/test_prisma*.py tests/proxy_unit_tests/test_prompt*.py tests/proxy_unit_tests/test_proxy_[c-r]*.py"
           - name: "proxy-server"
             path: "tests/proxy_unit_tests/test_proxy_server.py"
           - name: "proxy-server-extras"
@@ -50,43 +54,36 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install Poetry
-        run: pip install 'poetry==2.3.2'
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          version: "0.10.9"
 
-      - name: Cache Poetry dependencies
+      - name: Cache uv dependencies
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
-            ~/.cache/pypoetry
-            ~/.cache/pip
+            ~/.cache/uv
             .venv
-          key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
           restore-keys: |
-            ${{ runner.os }}-poetry-
+            ${{ runner.os }}-uv-
 
       - name: Install dependencies
         run: |
-          poetry config virtualenvs.in-project true
-          poetry install --with dev,proxy-dev --extras "proxy semantic-router"
-          poetry run pip install google-genai==1.22.0 \
-            google-cloud-aiplatform==1.115.0 fastapi-offline==1.7.3 python-multipart==0.0.22 openapi-core==0.23.0
-
-      - name: Setup litellm-enterprise
-        run: |
-          poetry run pip install --force-reinstall --no-deps -e enterprise/
+          uv sync --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router
 
       - name: Generate Prisma client
         env:
           PRISMA_BINARY_CACHE_DIR: ${{ runner.temp }}/prisma-cache
         run: |
-          poetry run pip install nodejs-wheel-binaries==24.13.1
-          poetry run prisma generate --schema litellm/proxy/schema.prisma
+          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
 
       - name: Run tests - ${{ matrix.test-group.name }}
         env:
           TEST_PATH: ${{ matrix.test-group.path }}
         run: |
-          poetry run pytest ${TEST_PATH} \
+          uv run --no-sync pytest ${TEST_PATH} \
             --tb=short -vv \
             --maxfail=10 \
             -n 2 \

.github/workflows/test-unit-responses-caching-types.yml

@@ -2,7 +2,11 @@ name: "Unit Tests: Responses, Caching & Types"
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 permissions:
   contents: read

.github/workflows/test-unit-security.yml

@@ -1,31 +0,0 @@
-name: "Unit Tests: Security"
-
-# Uses DATABASE_URL secret — only runs on trusted branches, not PRs.
-on:
-  push:
-    branches: [main, "litellm_*"]
-
-permissions:
-  contents: read
-  id-token: write
-  pull-requests: write
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  security:
-    uses: ./.github/workflows/_test-unit-services-base.yml
-    with:
-      test-path: "tests/proxy_security_tests/"
-      workers: 1
-      reruns: 2
-      timeout-minutes: 20
-      enable-redis: false
-      enable-postgres: true
-      artifact-name: security
-    secrets:
-      DATABASE_URL: ${{ secrets.DATABASE_URL }}
-      POSTGRES_USER: ${{ secrets.POSTGRES_USER }}
-      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}

.github/workflows/test_server_root_path.yml

@@ -4,12 +4,16 @@ permissions:
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - litellm_internal_staging
+      - litellm_oss_branch
+      - "litellm_**"
 
 jobs:
   test-server-root-path:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 30
 
     strategy:
       matrix:
@@ -21,18 +25,23 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Free up disk space
+        run: |
+          sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc /usr/local/share/boost
+          sudo apt-get clean
+          df -h /
+
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
 
       - name: Build Docker image
-        uses: docker/build-push-action@0adf9959216b96bec444f325f1e493d4aa344497 #v6.14
+        uses: docker/build-push-action@0adf9959216b96bec444f325f1e493d4aa344497 # v6.14.0
         with:
           context: .
           file: ./docker/Dockerfile.non_root
           tags: litellm-test:${{ github.sha }}
           load: true
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          push: false
 
       - name: Start LiteLLM container with SERVER_ROOT_PATH
         run: |
@@ -91,6 +100,31 @@ jobs:
           docker logs litellm-test
           exit 1
 
+      - name: Setup Node for Playwright
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "20"
+
+      - name: Install UI deps and Chromium
+        working-directory: ui/litellm-dashboard
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+
+      - name: Run SERVER_ROOT_PATH redirect e2e
+        working-directory: ui/litellm-dashboard
+        env:
+          SERVER_ROOT_PATH: ${{ matrix.root_path }}
+        run: npx playwright test --config=e2e_tests/serverRootPath.config.ts
+
+      - name: Upload Playwright artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: playwright-trace-${{ strategy.job-index }}
+          path: ui/litellm-dashboard/test-results/
+          retention-days: 7
+
       - name: Cleanup
         if: always()
         run: |

.github/workflows/triage_issue_with_llm.yml

@@ -0,0 +1,96 @@
+name: Agent Shin — Issue triage
+
+# LLM-as-judge triage for external GitHub issues.
+#
+# DRY-RUN BY DEFAULT. See .github/workflows/triage_pr_with_llm.yml for the
+# enablement procedure — same repo variable (`AGENT_SHIN_ENABLED=true`)
+# unlocks the PR and issue triage flows together.
+
+on:
+  issues:
+    types: [opened, reopened]
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: "Issue number to triage manually."
+        required: true
+      close:
+        description: "If true and AGENT_SHIN_ENABLED=true, actually close on fail."
+        required: false
+        default: "false"
+        type: choice
+        options:
+          - "true"
+          - "false"
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  triage:
+    if: github.repository == 'BerriAI/litellm'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout triage script
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          sparse-checkout: .github/scripts
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install LLM client
+        run: pip install --no-cache-dir --require-hashes -r .github/scripts/triage-requirements.txt
+
+      - name: Run Agent Shin
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Only expose the LLM key when the bot is enabled or a collaborator
+          # triggers it manually, so an external user can't force paid LLM
+          # calls by churning issues while the bot is still in dry-run.
+          # The Python script calls the LLM whenever this var is set
+          # (regardless of `--close`); stripping `--close` doesn't suppress
+          # the API call, only the destructive side effects.
+          OPENAI_API_KEY: ${{ (vars.AGENT_SHIN_ENABLED == 'true' || github.event_name == 'workflow_dispatch') && secrets.OPENAI_API_KEY || '' }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          TRIAGE_MODEL: ${{ vars.TRIAGE_MODEL }}
+          AGENT_SHIN_ENABLED: ${{ vars.AGENT_SHIN_ENABLED }}
+          DISPATCH_CLOSE: ${{ github.event.inputs.close }}
+          ISSUE_NUMBER: ${{ github.event.issue.number || github.event.inputs.issue_number }}
+        run: |
+          set -euo pipefail
+          ARGS=(--repo "${{ github.repository }}" --issue "${ISSUE_NUMBER}")
+          # Fail-safe gating: only the EXACT string "true" enables the
+          # destructive --close path. The workflow_dispatch input is a
+          # `choice` dropdown of "true"/"false" so the UI is constrained,
+          # but the API (`gh workflow run -f close=...`) accepts any
+          # string, and a `!= "false"` check would treat "True", "yes",
+          # "1", "TRUE", typos, and accidental whitespace as enabling
+          # closure. Mirror the Greptile closer's `= "true"` pattern.
+          if [ "${AGENT_SHIN_ENABLED:-false}" = "true" ] && [ "${DISPATCH_CLOSE:-false}" = "true" ]; then
+            ARGS+=(--close)
+            echo "::notice::Agent Shin is ENABLED and running in close-on-fail mode."
+          elif [ "${AGENT_SHIN_ENABLED:-false}" = "true" ]; then
+            echo "::notice::Agent Shin is ENABLED but this trigger is dry-run (workflow_dispatch close != 'true')."
+          else
+            echo "::notice::Agent Shin is in DRY-RUN mode (AGENT_SHIN_ENABLED is not 'true'). No comments will be posted; no issues will be closed."
+          fi
+          # Automatic `issues` events stay dry-run regardless until the team
+          # explicitly invokes workflow_dispatch with close=true.
+          if [ "${GITHUB_EVENT_NAME:-}" = "issues" ]; then
+            # filter out --close rather than substituting to "" (which would
+            # leave an empty positional arg that argparse rejects)
+            FILTERED=()
+            for arg in "${ARGS[@]}"; do
+              if [ "${arg}" != "--close" ]; then
+                FILTERED+=("${arg}")
+              fi
+            done
+            ARGS=("${FILTERED[@]}")
+            echo "::notice::issues trigger -> forcing dry-run."
+          fi
+          python3 .github/scripts/triage_with_llm.py "${ARGS[@]}"

.github/workflows/triage_reconsider.yml

@@ -0,0 +1,172 @@
+name: Agent Shin — reconsider
+
+# Comment-trigger workflow: when the PR/issue author (or an internal
+# collaborator) comments `@agent-shin reconsider` on a CLOSED PR/issue,
+# Agent Shin re-runs LLM-judge triage on the current title+body and:
+#
+#   - on PASS:  posts a "re-evaluated and reopened" comment + reopens.
+#   - on FAIL:  posts a "still missing X" comment and leaves it closed,
+#               so the contributor can iterate again.
+#
+# This exists because GitHub does NOT let an external (non-write-access)
+# OSS contributor reopen a PR/issue closed by a bot or maintainer. Without
+# this comment trigger, a contributor whose PR Agent Shin auto-closed
+# would have no path back into the review queue except opening a fresh PR
+# (which loses the original PR's history). The bot, on the other hand,
+# has write access via GH_TOKEN and can reopen on their behalf.
+#
+# DRY-RUN BY DEFAULT — gated on `vars.AGENT_SHIN_ENABLED == 'true'` just
+# like the other Agent Shin workflows. The workflow also gates on the
+# commenter being either the PR/issue author or an internal collaborator
+# (OWNER/MEMBER/COLLABORATOR) so random commenters cannot DOS the LLM
+# judge or force a reopen.
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  reconsider:
+    if: |
+      github.repository == 'BerriAI/litellm'
+      && contains(github.event.comment.body, '@agent-shin reconsider')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Authorize commenter
+        # Only the PR/issue author OR an internal collaborator may trigger
+        # a reconsider. Outside random commenters could otherwise spam the
+        # phrase to burn LLM budget or, if a fail-open bug were ever
+        # introduced, force a reopen on someone else's behalf.
+        #
+        # We expose the authorization decision as a step output and gate
+        # every subsequent (potentially destructive) step on it. A `run:`
+        # step with `exit 0` would NOT stop the job — only `if:` gating
+        # on a known-true output is safe here.
+        id: auth
+        env:
+          COMMENTER: ${{ github.event.comment.user.login }}
+          AUTHOR: ${{ github.event.issue.user.login }}
+          ASSOCIATION: ${{ github.event.comment.author_association }}
+        run: |
+          set -euo pipefail
+          if [ "${COMMENTER}" = "${AUTHOR}" ]; then
+            echo "::notice::Authorized: commenter is the PR/issue author."
+            echo "authorized=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          case "${ASSOCIATION}" in
+            OWNER|MEMBER|COLLABORATOR)
+              echo "::notice::Authorized: commenter is an internal collaborator (${ASSOCIATION})."
+              echo "authorized=true" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "::notice::Commenter '${COMMENTER}' (${ASSOCIATION}) is not authorized to trigger reconsider; skipping subsequent steps."
+              echo "authorized=false" >> "$GITHUB_OUTPUT"
+              ;;
+          esac
+
+      - name: React 👀 to acknowledge the reconsider
+        # Add an eyes reaction to the triggering comment the moment we accept
+        # it, so the contributor gets instant feedback that the bot saw their
+        # `@agent-shin reconsider` before the slower triage steps run. Gated on
+        # AGENT_SHIN_ENABLED so dry-run leaves no visible trace. Best-effort:
+        # a reactions API hiccup must never fail the actual reconsider.
+        if: steps.auth.outputs.authorized == 'true' && vars.AGENT_SHIN_ENABLED == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+        run: |
+          set -euo pipefail
+          gh api --method POST \
+            -H "Accept: application/vnd.github+json" \
+            "repos/${{ github.repository }}/issues/comments/${COMMENT_ID}/reactions" \
+            -f content=eyes \
+            || echo "::warning::failed to add 👀 reaction (non-fatal)"
+
+      - name: Checkout triage script
+        if: steps.auth.outputs.authorized == 'true'
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          sparse-checkout: .github/scripts
+          persist-credentials: false
+
+      - name: Set up Python
+        if: steps.auth.outputs.authorized == 'true'
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install LLM client
+        if: steps.auth.outputs.authorized == 'true'
+        run: pip install --no-cache-dir --require-hashes -r .github/scripts/triage-requirements.txt
+
+      - name: Run Agent Shin reconsider
+        if: steps.auth.outputs.authorized == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Only expose the LLM key when the bot is enabled, so a PR/issue
+          # author can't force paid LLM calls by spamming `@agent-shin
+          # reconsider` while the bot is still in dry-run. The Python script
+          # calls the LLM whenever this var is set (regardless of `--close`);
+          # stripping `--close` doesn't suppress the API call, only the
+          # destructive side effects. Mirror the gating used by every other
+          # Agent Shin workflow (triage_pr_with_llm.yml, review_gate.yml, ...).
+          OPENAI_API_KEY: ${{ vars.AGENT_SHIN_ENABLED == 'true' && secrets.OPENAI_API_KEY || '' }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          TRIAGE_MODEL: ${{ vars.TRIAGE_MODEL }}
+          AGENT_SHIN_ENABLED: ${{ vars.AGENT_SHIN_ENABLED }}
+          # `issue_comment` events fire for both issues and PR comments.
+          # `issue.pull_request` is set iff this is a PR comment, so we use
+          # its presence to decide whether to invoke `--pr N` or `--issue N`.
+          IS_PR: ${{ github.event.issue.pull_request != null }}
+          NUMBER: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+          if [ "${IS_PR}" = "true" ]; then
+            ARGS=(--repo "${{ github.repository }}" --pr "${NUMBER}" --reconsider)
+          else
+            ARGS=(--repo "${{ github.repository }}" --issue "${NUMBER}" --reconsider)
+          fi
+          # Reconsider's destructive actions (post comment + reopen) are
+          # gated on `--close`, mirroring the regular triage workflows.
+          # When AGENT_SHIN_ENABLED is not the EXACT string "true", we
+          # still run the script so its verdict + would-X action lands in
+          # the step summary for QA — but without `--close`, the script
+          # returns `would-reopen` / `would-reconsider-still-failing`
+          # instead of touching GitHub state.
+          #
+          # Use the positive `= "true"` gate (not `!= "true" -> exit`) so
+          # the workflow guardrails in
+          # tests/test_litellm/test_github_triage_workflows.py see the
+          # canonical fail-safe enable pattern. Unknown values like
+          # "True", "yes", "1", or typos fall through to the dry-run
+          # branch, which is the safe default.
+          if [ "${AGENT_SHIN_ENABLED:-false}" = "true" ]; then
+            ARGS+=(--close)
+            echo "::notice::Agent Shin reconsider ENABLED — running real triage (close=true)."
+          else
+            echo "::notice::AGENT_SHIN_ENABLED is not 'true' -> reconsider stays in dry-run (no comment, no reopen)."
+          fi
+          python3 .github/scripts/triage_with_llm.py "${ARGS[@]}"
+
+      - name: React 👍 when the reconsider finishes
+        # Once the reconsider run has completed successfully, add a thumbs-up so
+        # the contributor sees the bot is done (the 👀 stays, signalling
+        # seen -> handled). `success()` keeps this from firing if the run
+        # errored, and the AGENT_SHIN_ENABLED gate keeps dry-run inert.
+        if: success() && steps.auth.outputs.authorized == 'true' && vars.AGENT_SHIN_ENABLED == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+        run: |
+          set -euo pipefail
+          gh api --method POST \
+            -H "Accept: application/vnd.github+json" \
+            "repos/${{ github.repository }}/issues/comments/${COMMENT_ID}/reactions" \
+            -f content=+1 \
+            || echo "::warning::failed to add 👍 reaction (non-fatal)"

.github/workflows/triage_rollout_heads_up.yml

@@ -0,0 +1,92 @@
+name: Agent Shin — rollout heads-up (one-shot)
+
+# Fires the 7-day heads-up comment on every open external PR/issue that the
+# new triage bot would auto-close. The real sweep is a deliberate one-shot:
+# trigger it at rollout via a manual `workflow_dispatch` with `dry_run=false`.
+# The script is idempotent (skips items that already carry the
+# `<!-- agent-shin:rollout-heads-up -->` marker), so a re-run is harmless.
+#
+# The automatic push trigger runs DRY-RUN only, so merging the script to
+# `litellm_internal_staging` never posts a comment; it just confirms the
+# workflow is wired up. Posting real comments requires the manual dispatch,
+# which is also the only trigger that exposes `OPENAI_API_KEY`. The heads-up
+# is intentionally NOT gated on `AGENT_SHIN_ENABLED`: it has to warn
+# contributors while that flag is still off, ahead of the flip that turns on
+# auto-closing.
+#
+# The workflow is a thin shell over `.github/scripts/triage_rollout_heads_up.py`.
+# Dry-run vs. real run differ in EXACTLY one CLI flag (`--close`), added only
+# on a manual dispatch with `dry_run=false`.
+
+on:
+  push:
+    branches:
+      - litellm_internal_staging
+    paths:
+      # The presence of this script on staging IS the rollout merge marker.
+      # Editing the file later would re-fire the workflow; that's safe because
+      # the script skips PRs/issues that already have the heads-up marker.
+      - ".github/scripts/triage_rollout_heads_up.py"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run (true = preview only, false = actually post comments)."
+        required: false
+        default: "true"
+        type: choice
+        options:
+          - "true"
+          - "false"
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  heads-up:
+    if: github.repository == 'BerriAI/litellm'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout triage scripts
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          sparse-checkout: .github/scripts
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install LLM client
+        run: pip install --no-cache-dir --require-hashes -r .github/scripts/triage-requirements.txt
+
+      - name: Run heads-up sweep
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Only the manual dispatch (the real-run trigger) needs the LLM key.
+          # The automatic push trigger runs dry-run and never posts, so it gets
+          # no key. Mirrors the sibling triage workflows, which expose the key
+          # only on an enabled/dispatched run rather than unconditionally.
+          OPENAI_API_KEY: ${{ github.event_name == 'workflow_dispatch' && secrets.OPENAI_API_KEY || '' }}
+          OPENAI_BASE_URL: ${{ vars.OPENAI_BASE_URL }}
+          TRIAGE_MODEL: ${{ vars.TRIAGE_MODEL }}
+          # The real run is a deliberate manual dispatch with dry_run=false.
+          # Use the EXACT "false" comparison so any unexpected input value
+          # fail-closes to dry-run (mirrors the AGENT_SHIN_ENABLED pattern in
+          # the sibling workflows). The automatic push trigger always stays
+          # dry-run, so merging the script never posts.
+          DRY_RUN_INPUT: ${{ github.event.inputs.dry_run }}
+        run: |
+          set -euo pipefail
+          ARGS=(--repo "${{ github.repository }}")
+          if [ "${GITHUB_EVENT_NAME:-}" = "workflow_dispatch" ] && [ "${DRY_RUN_INPUT:-true}" = "false" ]; then
+            ARGS+=(--close)
+            echo "::notice::Manual rollout dispatch with dry_run=false -> heads-up comments WILL be posted."
+          elif [ "${GITHUB_EVENT_NAME:-}" = "workflow_dispatch" ]; then
+            echo "::notice::Manual dispatch in dry-run mode -> previewing only, no comments will be posted."
+          else
+            echo "::notice::Automatic push trigger -> dry-run preview only. Fire the real rollout sweep with a manual workflow_dispatch (dry_run=false)."
+          fi
+          python3 .github/scripts/triage_rollout_heads_up.py "${ARGS[@]}"

.github/workflows/update_release.py

@@ -1,54 +0,0 @@
-import os
-import requests
-from datetime import datetime
-
-# GitHub API endpoints
-GITHUB_API_URL = "https://api.github.com"
-REPO_OWNER = "BerriAI"
-REPO_NAME = "litellm"
-
-# GitHub personal access token (required for uploading release assets)
-GITHUB_ACCESS_TOKEN = os.environ.get("GITHUB_ACCESS_TOKEN")
-
-# Headers for GitHub API requests
-headers = {
-    "Accept": "application/vnd.github+json",
-    "Authorization": f"Bearer {GITHUB_ACCESS_TOKEN}",
-    "X-GitHub-Api-Version": "2022-11-28",
-}
-
-# Get the latest release
-releases_url = f"{GITHUB_API_URL}/repos/{REPO_OWNER}/{REPO_NAME}/releases/latest"
-response = requests.get(releases_url, headers=headers)
-latest_release = response.json()
-print("Latest release:", latest_release)
-
-# Upload an asset to the latest release
-upload_url = latest_release["upload_url"].split("{?")[0]
-asset_name = "results_stats.csv"
-asset_path = os.path.join(os.getcwd(), asset_name)
-print("upload_url:", upload_url)
-
-with open(asset_path, "rb") as asset_file:
-    asset_data = asset_file.read()
-
-upload_payload = {
-    "name": asset_name,
-    "label": "Load test results",
-    "created_at": datetime.utcnow().isoformat() + "Z",
-}
-
-upload_headers = headers.copy()
-upload_headers["Content-Type"] = "application/octet-stream"
-
-upload_response = requests.post(
-    upload_url,
-    headers=upload_headers,
-    data=asset_data,
-    params=upload_payload,
-)
-
-if upload_response.status_code == 201:
-    print(f"Asset '{asset_name}' uploaded successfully to the latest release.")
-else:
-    print(f"Failed to upload asset. Response: {upload_response.text}")

.github/workflows/zizmor.yml

@@ -2,9 +2,9 @@ name: GitHub Actions Security Analysis
 
 on:
   push:
-    branches: [main]
+    branches: [main, litellm_internal_staging]
   pull_request:
-    branches: [main]
+    branches: [main, litellm_internal_staging]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -18,9 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
-      security-events: write
       contents: read
-      actions: read
     steps:
       - name: Checkout repository
         uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
@@ -28,4 +26,9 @@ jobs:
           persist-credentials: false
 
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
+        uses: zizmorcore/zizmor-action@5f14fd08f7cf1cb1609c1e344975f152c7ee938d # v0.5.6
+        with:
+          version: "1.24.1"
+          min-severity: medium
+          advanced-security: false
+          annotations: true

.gitignore

@@ -28,6 +28,8 @@ litellm/tests/config_*.yaml
 litellm/tests/langfuse.log
 langfuse.log
 .langfuse.log
+.pin_list.txt
+.cov_new.xml
 litellm/tests/test_custom_logger.py
 litellm/tests/langfuse.log
 litellm/tests/dynamo*.log
@@ -72,7 +74,6 @@ tests/local_testing/log.txt
 .codegpt
 litellm/proxy/_new_new_secret_config.yaml
 litellm/proxy/custom_guardrail.py
-**/.mypy_cache/
 litellm/proxy/application.log
 tests/llm_translation/vertex_test_account.json
 tests/llm_translation/test_vertex_key.json
@@ -90,7 +91,6 @@ test.py
 litellm_config.yaml
 !.github/observatory/litellm_config.yaml
 .cursor
-.vscode/launch.json
 litellm/proxy/to_delete_loadtest_work/*
 update_model_cost_map.py
 tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py
@@ -100,4 +100,26 @@ STABILIZATION_TODO.md
 **/test-results
 **/playwright-report
 **/*.storageState.json
-**/coverage
+**/coverage
+test-config
+
+# ---------- Terraform ----------
+# Provider binaries + module cache — regenerated by `terraform init`.
+**/.terraform/
+# State files often contain secrets (DB passwords, API keys snapshotted from
+# data sources). Keep state in a remote backend, never in git.
+*.tfstate
+*.tfstate.*
+*.tfstate.backup
+# Plan files can also contain sensitive values (variables in plaintext).
+*.tfplan
+# User-specific variable inputs — example files (terraform.tfvars.example) are
+# tracked because they end in .example, which doesn't match the glob below.
+*.tfvars
+*.auto.tfvars
+crash.log
+crash.*.log
+# .terraform.lock.hcl is intentionally NOT ignored — it pins provider versions
+# and should be committed.
+.vscode
+.pin_list.txt

.npmrc

@@ -2,4 +2,4 @@
 # Packages needing lifecycle scripts: npm rebuild <pkg>
 ignore-scripts=true
 # Protects local npm install only — npm ci (used in CI) ignores this
-min-release-age=3d
+min-release-age=3

AGENTS.md

@@ -1,274 +1 @@
-# INSTRUCTIONS FOR LITELLM
-
-This document provides comprehensive instructions for AI agents working in the LiteLLM repository.
-
-## OVERVIEW
-
-LiteLLM is a unified interface for 100+ LLMs that:
-- Translates inputs to provider-specific completion, embedding, and image generation endpoints
-- Provides consistent OpenAI-format output across all providers
-- Includes retry/fallback logic across multiple deployments (Router)
-- Offers a proxy server (LLM Gateway) with budgets, rate limits, and authentication
-- Supports advanced features like function calling, streaming, caching, and observability
-
-## REPOSITORY STRUCTURE
-
-### Core Components
-- `litellm/` - Main library code
-  - `llms/` - Provider-specific implementations (OpenAI, Anthropic, Azure, etc.)
-  - `proxy/` - Proxy server implementation (LLM Gateway)
-  - `router_utils/` - Load balancing and fallback logic
-  - `types/` - Type definitions and schemas
-  - `integrations/` - Third-party integrations (observability, caching, etc.)
-
-### Key Directories
-- `tests/` - Comprehensive test suites
-- `docs/my-website/` - Documentation website
-- `ui/litellm-dashboard/` - Admin dashboard UI
-- `enterprise/` - Enterprise-specific features
-
-## DEVELOPMENT GUIDELINES
-
-### MAKING CODE CHANGES
-
-1. **Provider Implementations**: When adding/modifying LLM providers:
-   - Follow existing patterns in `litellm/llms/{provider}/`
-   - Implement proper transformation classes that inherit from `BaseConfig`
-   - Support both sync and async operations
-   - Handle streaming responses appropriately
-   - Include proper error handling with provider-specific exceptions
-
-2. **Type Safety**: 
-   - Use proper type hints throughout
-   - Update type definitions in `litellm/types/`
-   - Ensure compatibility with both Pydantic v1 and v2
-
-3. **Testing**:
-   - Add tests in appropriate `tests/` subdirectories
-   - Include both unit tests and integration tests
-   - Test provider-specific functionality thoroughly
-   - Consider adding load tests for performance-critical changes
-
-### MAKING CODE CHANGES FOR THE UI (IGNORE FOR BACKEND)
-
-1. **Tremor is DEPRECATED, do not use Tremor components in new features/changes**
-   - The only exception is the Tremor Table component and its required Tremor Table sub components.
-
-2. **Use Common Components as much as possible**:
-   - These are usually defined in the `common_components` directory
-   - Use these components as much as possible and avoid building new components unless needed
-
-3. **Testing**:
-   - The codebase uses **Vitest** and **React Testing Library**
-   - **Query Priority Order**: Use query methods in this order: `getByRole`, `getByLabelText`, `getByPlaceholderText`, `getByText`, `getByTestId`
-   - **Always use `screen`** instead of destructuring from `render()` (e.g., use `screen.getByText()` not `getByText`)
-   - **Wrap user interactions in `act()`**: Always wrap `fireEvent` calls with `act()` to ensure React state updates are properly handled
-   - **Use `query` methods for absence checks**: Use `queryBy*` methods (not `getBy*`) when expecting an element to NOT be present
-   - **Test names must start with "should"**: All test names should follow the pattern `it("should ...")`
-   - **Mock external dependencies**: Check `setupTests.ts` for global mocks and mock child components/networking calls as needed
-   - **Structure tests properly**:
-     - First test should verify the component renders successfully
-     - Subsequent tests should focus on functionality and user interactions
-     - Use `waitFor` for async operations that aren't already awaited
-   - **Avoid using `querySelector`**: Prefer React Testing Library queries over direct DOM manipulation
-
-### IMPORTANT PATTERNS
-
-1. **Function/Tool Calling**:
-   - LiteLLM standardizes tool calling across providers
-   - OpenAI format is the standard, with transformations for other providers
-   - See `litellm/llms/anthropic/chat/transformation.py` for complex tool handling
-
-2. **Streaming**:
-   - All providers should support streaming where possible
-   - Use consistent chunk formatting across providers
-   - Handle both sync and async streaming
-
-3. **Error Handling**:
-   - Use provider-specific exception classes
-   - Maintain consistent error formats across providers
-   - Include proper retry logic and fallback mechanisms
-
-4. **Configuration**:
-   - Support both environment variables and programmatic configuration
-   - Use `BaseConfig` classes for provider configurations
-   - Allow dynamic parameter passing
-
-## PROXY SERVER (LLM GATEWAY)
-
-The proxy server is a critical component that provides:
-- Authentication and authorization
-- Rate limiting and budget management
-- Load balancing across multiple models/deployments
-- Observability and logging
-- Admin dashboard UI
-- Enterprise features
-
-Key files:
-- `litellm/proxy/proxy_server.py` - Main server implementation
-- `litellm/proxy/auth/` - Authentication logic
-- `litellm/proxy/management_endpoints/` - Admin API endpoints
-
-**Database (proxy)**: Use Prisma model methods (`prisma_client.db.<model>.upsert`, `.find_many`, `.find_unique`, etc.), not raw SQL (`execute_raw`/`query_raw`). See COMMON PITFALLS for details.
-
-## MCP (MODEL CONTEXT PROTOCOL) SUPPORT
-
-LiteLLM supports MCP for agent workflows:
-- MCP server integration for tool calling
-- Transformation between OpenAI and MCP tool formats
-- Support for external MCP servers (Zapier, Jira, Linear, etc.)
-- See `litellm/experimental_mcp_client/` and `litellm/proxy/_experimental/mcp_server/`
-
-## RUNNING SCRIPTS
-
-Use `poetry run python script.py` to run Python scripts in the project environment (for non-test files).
-
-## GITHUB TEMPLATES
-
-When opening issues or pull requests, follow these templates:
-
-### Bug Reports (`.github/ISSUE_TEMPLATE/bug_report.yml`)
-- Describe what happened vs. expected behavior
-- Include relevant log output
-- Specify LiteLLM version
-- Indicate if you're part of an ML Ops team (helps with prioritization)
-
-### Feature Requests (`.github/ISSUE_TEMPLATE/feature_request.yml`)
-- Clearly describe the feature
-- Explain motivation and use case with concrete examples
-
-### Pull Requests (`.github/pull_request_template.md`)
-- Add at least 1 test in `tests/litellm/`
-- Ensure `make test-unit` passes
-
-
-## TESTING CONSIDERATIONS
-
-1. **Provider Tests**: Test against real provider APIs when possible
-2. **Proxy Tests**: Include authentication, rate limiting, and routing tests
-3. **Performance Tests**: Load testing for high-throughput scenarios
-4. **Integration Tests**: End-to-end workflows including tool calling
-
-## DOCUMENTATION
-
-- Keep documentation in sync with code changes
-- Update provider documentation when adding new providers
-- Include code examples for new features
-- Update changelog and release notes
-
-## SECURITY CONSIDERATIONS
-
-- Handle API keys securely
-- Validate all inputs, especially for proxy endpoints
-- Consider rate limiting and abuse prevention
-- Follow security best practices for authentication
-
-## ENTERPRISE FEATURES
-
-- Some features are enterprise-only
-- Check `enterprise/` directory for enterprise-specific code
-- Maintain compatibility between open-source and enterprise versions
-
-## COMMON PITFALLS TO AVOID
-
-1. **Breaking Changes**: LiteLLM has many users - avoid breaking existing APIs
-2. **Provider Specifics**: Each provider has unique quirks - handle them properly
-3. **Rate Limits**: Respect provider rate limits in tests
-4. **Memory Usage**: Be mindful of memory usage in streaming scenarios
-5. **Dependencies**: Keep dependencies minimal and well-justified
-6. **UI/Backend Contract Mismatch**: When adding a new entity type to the UI, always check whether the backend endpoint accepts a single value or an array. Match the UI control accordingly (single-select vs. multi-select) to avoid silently dropping user selections
-7. **Missing Tests for New Entity Types**: When adding a new entity type (e.g., in `EntityUsage`, `UsageViewSelect`), always add corresponding tests in the existing test files and update any icon/component mocks
-8. **Raw SQL in proxy DB code**: Do not use `execute_raw` or `query_raw` for proxy database access. Use Prisma model methods (e.g. `prisma_client.db.litellm_tooltable.upsert()`, `.find_many()`, `.find_unique()`) so behavior stays consistent with the schema, the client stays mockable in tests, and you avoid the pitfalls of hand-written SQL (parameter ordering, type casting, schema drift)
-
-8. **Do not hardcode model-specific flags**: Put model-specific capability flags in `model_prices_and_context_window.json` and read them via `get_model_info` (or existing helpers like `supports_reasoning`). This prevents users from needing to upgrade LiteLLM each time a new model supports a feature.
-
-   **Example of BAD** (hardcoded model checks):
-
-   ```python
-   @staticmethod
-   def _is_effort_supported_model(model: str) -> bool:
-       """Check if the model supports the output_config.effort parameter..."""
-       model_lower = model.lower()
-       if AnthropicConfig._is_claude_4_6_model(model):
-           return True
-       return any(
-           v in model_lower for v in ("opus-4-5", "opus_4_5", "opus-4.5", "opus_4.5")
-       )
-   ```
-
-   **Example of GOOD** (config-driven or helper that reads from config):
-
-   ```python
-   if (
-       "claude-3-7-sonnet" in model
-       or AnthropicConfig._is_claude_4_6_model(model)
-       or supports_reasoning(
-           model=model,
-           custom_llm_provider=self.custom_llm_provider,
-       )
-   ):
-       ...
-   ```
-
-   Using helpers like `supports_reasoning` (which read from `model_prices_and_context_window.json` / `get_model_info`) allows future model updates to "just work" without code changes.
-
-9. **Never close HTTP/SDK clients on cache eviction**: Do not add `close()`, `aclose()`, or `create_task(close_fn())` inside `LLMClientCache._remove_key()` or any cache eviction path. Evicted clients may still be held by in-flight requests; closing them causes `RuntimeError: Cannot send a request, as the client has been closed.` in production after the cache TTL (1 hour) expires. Connection cleanup is handled at shutdown by `close_litellm_async_clients()`. See PR #22247 for the full incident history.
-
-## HELPFUL RESOURCES
-
-- Main documentation: https://docs.litellm.ai/
-- Provider-specific docs in `docs/my-website/docs/providers/`
-- Admin UI for testing proxy features
-
-## WHEN IN DOUBT
-
-- Follow existing patterns in the codebase
-- Check similar provider implementations
-- Ensure comprehensive test coverage
-- Update documentation appropriately
-- Consider backward compatibility impact
-
-## Cursor Cloud specific instructions
-
-### Environment
-
-- Poetry is installed in `~/.local/bin`; the update script ensures it is on `PATH`.
-- Python 3.12, Node 22 are pre-installed.
-- The virtual environment lives under `~/.cache/pypoetry/virtualenvs/`.
-
-### Running the proxy server
-
-Start the proxy with a config file:
-
-```bash
-poetry run litellm --config dev_config.yaml --port 4000
-```
-
-The proxy takes ~15-20 seconds to fully start (it runs Prisma migrations on boot). Wait for `/health` to return before sending requests. Without a PostgreSQL `DATABASE_URL`, the proxy connects to a default Neon dev database embedded in the `litellm-proxy-extras` package.
-
-### Running tests
-
-See `CLAUDE.md` and the `Makefile` for standard commands. Key notes:
-
-- `psycopg-binary` must be installed (`poetry run pip install psycopg-binary`) because the pytest-postgresql plugin requires it and the lock file only includes `psycopg` (no binary).
-- `openapi-core` must be installed (`poetry run pip install openapi-core`) for the OpenAPI compliance tests in `tests/test_litellm/interactions/`.
-- The `--timeout` pytest flag is NOT available; don't pass it.
-- Unit tests: `poetry run pytest tests/test_litellm/ -x -vv -n 4`
-- **Before committing, always run `poetry run black .` to format your code.** Black formatting is enforced in CI.
-- If `poetry install` fails with "pyproject.toml changed significantly since poetry.lock was last generated", run `poetry lock` first to regenerate the lock file.
-
-### Lint
-
-```bash
-cd litellm && poetry run ruff check .
-```
-
-Ruff is the primary fast linter. For the full lint suite (including mypy, black, circular imports), run `make lint` per `CLAUDE.md`.
-
-### UI Dashboard development
-
-- The UI is at `ui/litellm-dashboard/`. Run `npm run dev` from that directory for the Next.js dev server on port 3000.
-- The proxy at port 4000 serves a **pre-built** static UI from `litellm/proxy/_experimental/out/`. After making UI code changes, you must run `npm run build` in the dashboard directory and copy the output: `cp -r ui/litellm-dashboard/out/* litellm/proxy/_experimental/out/` for the proxy to serve the updated UI.
-- SVGs used as provider logos (loaded via `<img>` tags) must NOT use `fill="currentColor"` — replace with an explicit color like `#000000` or use the `-color` variant from lobehub icons, since CSS color inheritance does not work inside `<img>` elements.
-- Provider logos live in `ui/litellm-dashboard/public/assets/logos/` (source) and `litellm/proxy/_experimental/out/assets/logos/` (pre-built). Both locations must have the file for it to work in dev and proxy-served modes.
-- UI Vitest tests: `cd ui/litellm-dashboard && npx vitest run`
+Read @CLAUDE.md for coding guidelines

ARCHITECTURE.md

@@ -240,6 +240,24 @@ graph LR
 7. `DBSpendUpdateWriter.update_database()` queues spend increments to Redis
 8. Background job `update_spend` flushes queued spend to PostgreSQL every 60s
 
+### Data Access Layer (Models & Repositories)
+
+Database entities and the operations on them live in two packages at the root of `litellm/` so both the gateway (`proxy/`) and the SDK can use them without importing proxy internals:
+
+- `litellm/models/` holds the canonical Pydantic definitions for every persisted entity (`LiteLLM_VerificationToken`, `LiteLLM_TeamTable`, `LiteLLM_UserTable`, etc.). `proxy/_types.py` re-exports these for backwards compatibility, so existing imports keep working.
+- `litellm/repositories/` holds the data-access layer. `BaseRepository[T]` provides the generic CRUD (`find_by_id`, `find_many`, `create`, `update`, `delete`, `count`, `exists`); entity repositories such as `VerificationTokenRepository`, `TeamRepository`, and `UserRepository` add domain-specific queries and writes on top of it.
+
+Conventions to follow when touching this layer:
+
+| Concern | How it's handled |
+|---------|------------------|
+| JSON columns | Prisma `Json` columns are stored as JSON strings. Repositories `json.dumps()` on write and `json.loads()` on read (see `_to_model` and the `_build_*_data` helpers). |
+| Archive-then-delete | `delete_team` / `delete_token` copy the row into the `LiteLLM_Deleted*` table and delete the original inside a single `prisma_client.db.tx()` transaction. Archive payloads are built explicitly so only columns that exist on the archive table are written. |
+| Column vs. field names | Where a model field differs from its DB column (for example `org_id` maps to the `organization_id` column), the repository translates in both directions rather than relying on Pydantic to guess. |
+| Array mutations | Adds use Prisma's atomic `push` (`add_member`, `add_admin`, `add_models`) to avoid read-modify-write races. Removals fall back to read-modify-write because Prisma has no atomic array remove. |
+
+To add a new entity, define the model under `litellm/models/`, re-export it from `proxy/_types.py` if existing code imports it from there, and add a repository under `litellm/repositories/` (subclass `BaseRepository` for plain CRUD, or add bespoke methods when the entity needs encryption, archiving, or atomic array updates). Mirror the tests in `tests/test_litellm/repositories/`.
+
 ---
 
 ## 2. SDK Request Flow

CLAUDE.md

@@ -1,165 +1,96 @@
-# CLAUDE.md
+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
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+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
 
-## Development Commands
+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
+- readable
+- easy to maintain/change
+- modern
 
-### Installation
-- `make install-dev` - Install core development dependencies
-- `make install-proxy-dev` - Install proxy development dependencies with full feature set
-- `make install-test-deps` - Install all test dependencies
+In that order of importance
 
-### Testing
-- `make test` - Run all tests
-- `make test-unit` - Run unit tests (tests/test_litellm) with 4 parallel workers
-- `make test-integration` - Run integration tests (excludes unit tests)
-- `pytest tests/` - Direct pytest execution
+When adding new features, add meaningful tests. Don't add tests that don't check anything substantial and is there just to make the code coverage pass. Yes, code coverage is important, but I'd rather have no signal whether the code is working than tests that don't fail when code is broken. The goal is to have tests that would fail before the feature was added/if the code was mutated in a way that breaks the feature and succeed only when the feature is fully working. I should run mutation testing and see > 90% kill rate
 
-### Code Quality
-- `make lint` - Run all linting (Ruff, MyPy, Black, circular imports, import safety)
-- `make format` - Apply Black code formatting
-- `make lint-ruff` - Run Ruff linting only
-- `make lint-mypy` - Run MyPy type checking only
-- **Before committing, always run `poetry run black .` to format your code.** Black formatting is enforced in CI.
+Same thing for bug fixes. The tests should make it so that this specific bug can never happen again without failing tests (i.e., regression)
 
-### Single Test Files
-- `poetry run pytest tests/path/to/test_file.py -v` - Run specific test file
-- `poetry run pytest tests/path/to/test_file.py::test_function -v` - Run specific test
+`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
 
-### Running Scripts
-- `poetry run python script.py` - Run Python scripts (use for non-test files)
+When creating PRs, don't set base to `main`. `litellm_internal_staging` serves that purpose
 
-### GitHub Issue & PR Templates
-When contributing to the project, use the appropriate templates:
+Always use @.github/pull_request_template.md as a guide for your PR body
 
-**Bug Reports** (`.github/ISSUE_TEMPLATE/bug_report.yml`):
-- Describe what happened vs. what you expected
-- Include relevant log output
-- Specify your LiteLLM version
+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
 
-**Feature Requests** (`.github/ISSUE_TEMPLATE/feature_request.yml`):
-- Describe the feature clearly
-- Explain the motivation and use case
+If you ever make public-facing PR descriptions, comments, issues, commit messages, etc., always follow these guidelines to sound less AI-y:
+- don't use emojis
+- don't use "—". Instead, reach for ";", ".", etc.
+- don't use the pattern "It's not X, it's Y", "You're not X, you're Y", etc.
+- don't use bulleted or numbered lists unless it would be nonsensical not to. Instead, prefer prose
+- don't add a trailing "." at the end of paragraphs (just like this file)
+- don't use →. Instead, prefer not to use arrows, and if need be, use -> instead
 
-**Pull Requests** (`.github/pull_request_template.md`):
-- Add at least 1 test in `tests/litellm/`
-- Ensure `make test-unit` passes
+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
 
-## Architecture Overview
+Run tests, format your code, and lint your code before each commit
 
-LiteLLM is a unified interface for 100+ LLM providers with two main components:
+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
 
-### Core Library (`litellm/`)
-- **Main entry point**: `litellm/main.py` - Contains core completion() function
-- **Provider implementations**: `litellm/llms/` - Each provider has its own subdirectory
-- **Router system**: `litellm/router.py` + `litellm/router_utils/` - Load balancing and fallback logic
-- **Type definitions**: `litellm/types/` - Pydantic models and type hints
-- **Integrations**: `litellm/integrations/` - Third-party observability, caching, logging
-- **Caching**: `litellm/caching/` - Multiple cache backends (Redis, in-memory, S3, etc.)
+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
 
-### Proxy Server (`litellm/proxy/`)
-- **Main server**: `proxy_server.py` - FastAPI application
-- **Authentication**: `auth/` - API key management, JWT, OAuth2
-- **Database**: `db/` - Prisma ORM with PostgreSQL/SQLite support
-- **Management endpoints**: `management_endpoints/` - Admin APIs for keys, teams, models
-- **Pass-through endpoints**: `pass_through_endpoints/` - Provider-specific API forwarding
-- **Guardrails**: `guardrails/` - Safety and content filtering hooks
-- **UI Dashboard**: Served from `_experimental/out/` (Next.js build)
+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
 
-## Key Patterns
+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)
 
-### Provider Implementation
-- Providers inherit from base classes in `litellm/llms/base.py`
-- Each provider has transformation functions for input/output formatting
-- Support both sync and async operations
-- Handle streaming responses and function calling
+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
 
-### Error Handling
-- Provider-specific exceptions mapped to OpenAI-compatible errors
-- Fallback logic handled by Router system
-- Comprehensive logging through `litellm/_logging.py`
+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
 
-### Configuration
-- YAML config files for proxy server (see `proxy/example_config_yaml/`)
-- Environment variables for API keys and settings
-- Database schema managed via Prisma (`proxy/schema.prisma`)
+Do not add `Co-Authored-By: Claude` or any Claude attribution to commit messages. Never use a `claude/` prefix or put a `/` in a branch name. Do not add "Generated with Claude Code" (or any similar attribution) to PR descriptions or comments. Do not create a new PR/branch off the existing PR to fix/add something that is related and could've just been committed directly to the existing PR's branch
 
-## Development Notes
+When working on a PR, keep the PR description in sync with new commits being made
 
-### Code Style
-- Uses Black formatter, Ruff linter, MyPy type checker
-- Pydantic v2 for data validation
-- Async/await patterns throughout
-- Type hints required for all public APIs
-- **Avoid imports within methods** — place all imports at the top of the file (module-level). Inline imports inside functions/methods make dependencies harder to trace and hurt readability. The only exception is avoiding circular imports where absolutely necessary.
-- **Use dict spread for immutable copies** — prefer `{**original, "key": new_value}` over `dict(obj)` + mutation. The spread produces the final dict in one step and makes intent clear.
-- **Guard at resolution time** — when resolving an optional value through a fallback chain (`a or b or ""`), raise immediately if the resolved result being empty is an error. Don't pass empty strings or sentinel values downstream for the callee to deal with.
-- **Extract complex comprehensions to named helpers** — a set/dict comprehension that calls into the DB or manager (e.g. "which of these server IDs are OAuth2?") belongs in a named helper function, not inline in the caller.
-- **FastAPI parameter declarations** — mark required query/form params with `= Query(...)` / `= Form(...)` explicitly when other params in the same handler are optional. Mixing `str` (required) with `Optional[str] = None` in the same signature causes silent 422s when the required param is missing.
+Monkeypatching attributes of a class to do testing is an anti-pattern. Prefer dependency-injecting things into classes. That way, at unit test time, you can pass a mocked dependency in
 
-### Testing Strategy
-- Unit tests in `tests/test_litellm/`
-- Integration tests for each provider in `tests/llm_translation/`
-- Proxy tests in `tests/proxy_unit_tests/`
-- Load tests in `tests/load_tests/`
-- **Always add tests when adding new entity types or features** — if the existing test file covers other entity types, add corresponding tests for the new one
-- **Keep monkeypatch stubs in sync with real signatures** — when a function gains a new optional parameter, update every `fake_*` / `stub_*` in tests that patch it to also accept that kwarg (even as `**kwargs`). Stale stubs fail with `unexpected keyword argument` and mask real bugs.
-- **Test all branches of name→ID resolution** — when adding server/resource lookup that resolves names to UUIDs, test: (1) name resolves and UUID is allowed, (2) name resolves but UUID is not allowed, (3) name does not resolve at all. The silent-fallback path is where access-control bugs hide.
+Do not put names of customers or customer company names in code, PRs, and issues. The codebase is public
 
-### UI / Backend Consistency
-- When wiring a new UI entity type to an existing backend endpoint, verify the backend API contract (single value vs. array, required vs. optional params) and ensure the UI controls match — e.g., use a single-select dropdown when the backend accepts a single value, not a multi-select
+CI supply-chain safety: Never pipe a remote script into a shell (`curl ... | bash`, `wget ... | sh`); download the artifact to a file, verify its SHA-256 checksum, then install. Pin every external tool to a specific version with a full URL (not `latest` or `stable`). Verify checksums for all downloaded binaries, using the provider's official `.sha256` / `.sha256sum` sidecar when available. These rules apply to every download in CI
 
-### MCP OAuth / OpenAPI Transport Mapping
-- `TRANSPORT.OPENAPI` is a UI-only concept. The backend only accepts `"http"`, `"sse"`, or `"stdio"`. Always map it to `"http"` before any API call (including pre-OAuth temp-session calls).
-- FastAPI validation errors return `detail` as an array of `{loc, msg, type}` objects. Error extractors must handle: array (map `.msg`), string, nested `{error: string}`, and fallback.
-- When an MCP server already has `authorization_url` stored, skip OAuth discovery (`_discovery_metadata`) — the server URL for OpenAPI MCPs is the spec file, not the API base, and fetching it causes timeouts.
-- `client_id` should be optional in the `/authorize` endpoint — if the server has a stored `client_id` in credentials, use that. Never require callers to re-supply it.
+Follow these coding conventions for new/updated code (a three-line fix in a legacy file shouldn't trigger huge drive-by refactors):
 
-### MCP Credential Storage
-- OAuth credentials and BYOK credentials share the `litellm_mcpusercredentials` table, distinguished by a `"type"` field in the JSON payload (`"oauth2"` vs plain string).
-- When deleting OAuth credentials, check type before deleting to avoid accidentally deleting a BYOK credential for the same `(user_id, server_id)` pair.
-- Always pass the raw `expires_at` timestamp to the client — never set it to `None` for expired credentials. Let the frontend compute the "Expired" display state from the timestamp.
-- Use `RecordNotFoundError` (not bare `except Exception`) when catching "already deleted" in credential delete endpoints.
+- Composition over inheritance
+- Never-nester: early returns over deep nesting
+- Don't throw; model failures as values (One function (e.g., raise_public) maps error union to existing public exception contracts via exhaustive match + assert_never)
+- No mutation; don't reassign variables, global or local. Instead of mutable lists and dicts, prefer tuples, frozen dataclasses (with slots=True), etc.
+- Use dependency injection
+- Fully typed; no `Any` or coarse types like `dict[str, Any]` or just `dict`. Every function parameter must be strongly typed
+- Use tagged unions + match
+- 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
 
-### Browser Storage Safety (UI)
-- Never write LiteLLM access tokens or API keys to `localStorage` — use `sessionStorage` only. `localStorage` survives browser close and is readable by any injected script (XSS).
-- Shared utility functions (e.g. `extractErrorMessage`) belong in `src/utils/` — never define them inline in hooks or duplicate them across files.
+Follow conventional commits for commit names and PR titles
 
-### Database Migrations
-- Prisma handles schema migrations
-- Migration files auto-generated with `prisma migrate dev`
-- Always test migrations against both PostgreSQL and SQLite
+## Think Before Coding
 
-### Proxy database access
-- **Do not write raw SQL** for proxy DB operations. Use Prisma model methods instead of `execute_raw` / `query_raw`.
-- Use the generated client: `prisma_client.db.<model>` (e.g. `litellm_tooltable`, `litellm_usertable`) with `.upsert()`, `.find_many()`, `.find_unique()`, `.update()`, `.update_many()` as appropriate. This avoids schema/client drift, keeps code testable with simple mocks, and matches patterns used in spend logs and other proxy code.
-- **No N+1 queries.** Never query the DB inside a loop. Batch-fetch with `{"in": ids}` and distribute in-memory.
-- **Batch writes.** Use `create_many`/`update_many`/`delete_many` instead of individual calls (these return counts only; `update_many`/`delete_many` no-op silently on missing rows). When multiple separate writes target the same table (e.g. in `batch_()`), order by primary key to avoid deadlocks.
-- **Push work to the DB.** Filter, sort, group, and aggregate in SQL, not Python. Verify Prisma generates the expected SQL — e.g. prefer `group_by` over `find_many(distinct=...)` which does client-side processing.
-- **Bound large result sets.** Prisma materializes full results in memory. For results over ~10 MB, paginate with `take`/`skip` or `cursor`/`take`, always with an explicit `order`. Prefer cursor-based pagination (`skip` is O(n)). Don't paginate naturally small result sets.
-- **Limit fetched columns on wide tables.** Use `select` to fetch only needed fields — returns a partial object, so downstream code must not access unselected fields.
-- **Check index coverage.** For new or modified queries, check `schema.prisma` for a supporting index. Prefer extending an existing index (e.g. `@@index([a])` → `@@index([a, b])`) over adding a new one, unless it's a `@@unique`. Only add indexes for large/frequent queries.
-- **Keep schema files in sync.** Apply schema changes to all `schema.prisma` copies (`schema.prisma`, `litellm/proxy/`, `litellm-proxy-extras/`, `litellm-js/spend-logs/` for SpendLogs) with a migration under `litellm-proxy-extras/litellm_proxy_extras/migrations/`.
+**Don't assume. Don't hide confusion. Surface tradeoffs**
 
-### Setup Wizard (`litellm/setup_wizard.py`)
-- The wizard is implemented as a single `SetupWizard` class with `@staticmethod` methods — keep it that way. No module-level functions except `run_setup_wizard()` (the public entrypoint) and pure helpers (color, ANSI).
-- Use `litellm.utils.check_valid_key(model, api_key)` for credential validation — never roll a custom completion call.
-- Do not hardcode provider env-key names or model lists that already exist in the codebase. Add a `test_model` field to each provider entry to drive `check_valid_key`; set it to `None` for providers that can't be validated with a single API key (Azure, Bedrock, Ollama).
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask
+- If multiple interpretations exist, present them. Don't pick silently
+- If a simpler approach exists, say so. Push back when warranted
+- If something is unclear, stop. Name what's confusing. Ask
 
-### Enterprise Features
-- Enterprise-specific code in `enterprise/` directory
-- Optional features enabled via environment variables
-- Separate licensing and authentication for enterprise features
+## Simplicity First
 
-### HTTP Client Cache Safety
-- **Never close HTTP/SDK clients on cache eviction.** `LLMClientCache._remove_key()` must not call `close()`/`aclose()` on evicted clients — they may still be used by in-flight requests. Doing so causes `RuntimeError: Cannot send a request, as the client has been closed.` after the 1-hour TTL expires. Cleanup happens at shutdown via `close_litellm_async_clients()`.
+**Minimum code that solves the problem. Nothing speculative**
 
-### Troubleshooting: DB schema out of sync after proxy restart
-`litellm-proxy-extras` runs `prisma migrate deploy` on startup using **its own** bundled migration files, which may lag behind schema changes in the current worktree. Symptoms: `Unknown column`, `Invalid prisma invocation`, or missing data on new fields.
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" or "configurability" that wasn't requested
+- No error handling for impossible scenarios
+- If you write 200 lines and it could be 50, rewrite it
 
-**Diagnose:** Run `\d "TableName"` in psql and compare against `schema.prisma` — missing columns confirm the issue.
-
-**Fix options:**
-1. **Create a Prisma migration** (permanent) — run `prisma migrate dev --name <description>` in the worktree. The generated file will be picked up by `prisma migrate deploy` on next startup.
-2. **Apply manually for local dev** — `psql -d litellm -c "ALTER TABLE ... ADD COLUMN IF NOT EXISTS ..."` after each proxy start. Fine for dev, not for production.
-3. **Update litellm-proxy-extras** — if the package is installed from PyPI, its migration directory must include the new file. Either update the package or run the migration manually until the next release ships it.
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify

CONTRIBUTING.md

@@ -38,18 +38,25 @@ Before contributing code to LiteLLM, you must sign our [Contributor License Agre
 git clone https://github.com/YOUR_USERNAME/litellm.git
 cd litellm
 
-# Create a new branch for your feature
-git checkout -b your-feature-branch
+# Create a new branch for your feature (see "Commit and Branch Conventions" below)
+git checkout -b feature/your-feature
 
 # Install development dependencies
 make install-dev
 
+# Install git hooks that enforce commit + branch conventions (one-time, opt-in)
+make install-hooks
+
 # Verify your setup works
 make help
 ```
 
 That's it! Your local development environment is ready.
 
+## Commit and Branch Conventions
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and branches follow [Conventional Branches](https://conventional-branch.github.io/). Run `make install-hooks` once per clone to enable the local git hooks that enforce these — see the [contributor docs](https://docs.litellm.ai/docs/extras/contributing_code#commit-and-branch-conventions) for the full type list, examples, the protected-branch bypass list, and how to opt out.
+
 ### 2. Development Workflow
 
 Here's the recommended workflow for making changes:
@@ -67,12 +74,12 @@ make lint
 # Run unit tests to ensure nothing is broken
 make test-unit
 
-# Commit your changes
+# Commit your changes (must follow Conventional Commits — see above)
 git add .
-git commit -m "Your descriptive commit message"
+git commit -m "feat(scope): your descriptive commit message"
 
-# Push and create a PR
-git push origin your-feature-branch
+# Push and create a PR (branch must follow Conventional Branches — see above)
+git push origin feature/your-feature
 ```
 
 ## Adding Testing
@@ -122,9 +129,17 @@ Run all unit tests (uses parallel execution for speed):
 make test-unit
 ```
 
+If you're running broader test suites, proxy tests, or anything that touches PostgreSQL-backed fixtures/plugins, install the full local test environment first:
+
+```bash
+make install-test-deps
+```
+
+This syncs the locked test environment used across the repo, including `psycopg` v3 plus `psycopg-binary` (used by `pytest-postgresql`), `psycopg2-binary` (used by some proxy E2E tests), and a generated Prisma client for DB-backed proxy tests, so pytest startup matches CI without manual package installs.
+
 Run specific test files:
 ```bash
-poetry run pytest tests/test_litellm/test_your_file.py -v
+uv run pytest tests/test_litellm/test_your_file.py -v
 ```
 
 ### Running Linting and Formatting Checks
@@ -139,7 +154,7 @@ Individual linting commands:
 ```bash
 make format-check       # Check Black formatting
 make lint-ruff          # Run Ruff linting
-make lint-mypy          # Run MyPy type checking
+make lint-basedpyright  # Run basedpyright type checking
 make check-circular-imports    # Check for circular imports
 make check-import-safety       # Check import safety
 ```
@@ -185,7 +200,7 @@ Run `make help` to see all available commands:
 make help                       # Show all available commands
 make install-dev               # Install development dependencies
 make install-proxy-dev         # Install proxy development dependencies
-make install-test-deps         # Install test dependencies (for running tests)
+make install-test-deps         # Install the full local test environment
 make format                    # Apply Black code formatting
 make format-check              # Check Black formatting (matches CI)
 make lint                      # Run all linting checks
@@ -201,7 +216,7 @@ LiteLLM follows the [Google Python Style Guide](https://google.github.io/stylegu
 Our automated quality checks include:
 - **Black** for consistent code formatting
 - **Ruff** for linting and code quality
-- **MyPy** for static type checking
+- **basedpyright** for static type checking
 - **Circular import detection**
 - **Import safety validation**
 
@@ -215,7 +230,7 @@ If `make lint` fails:
 
 1. **Formatting issues**: Run `make format` to auto-fix
 2. **Ruff issues**: Check the output and fix manually
-3. **MyPy issues**: Add proper type hints
+3. **basedpyright issues**: Add proper type hints
 4. **Circular imports**: Refactor import dependencies
 5. **Import safety**: Fix any unprotected imports
 
@@ -230,7 +245,7 @@ If `make test-unit` fails:
 
 ### 3. Common Development Tips
 
-- **Use type hints**: MyPy requires proper type annotations
+- **Use type hints**: basedpyright requires proper type annotations
 - **Write descriptive commit messages**: Help reviewers understand your changes
 - **Keep PRs focused**: One feature/fix per PR
 - **Test edge cases**: Don't just test the happy path
@@ -247,7 +262,7 @@ To run the proxy server locally:
 make install-proxy-dev
 
 # Start the proxy server
-poetry run litellm --config your_config.yaml
+uv run litellm --config your_config.yaml
 ```
 
 ### Docker Development
@@ -332,4 +347,4 @@ Looking for ideas? Check out:
 - 🧪 Test coverage improvements
 - 🔌 New LLM provider integrations
 
-Thank you for contributing to LiteLLM! 🚀 
+Thank you for contributing to LiteLLM! 🚀 

Dockerfile

@@ -1,142 +1,103 @@
 # Base image for building
-ARG LITELLM_BUILD_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:a5a619c1793039dcf92f02178f37c94bb3d6001403716da59d6092dfe8d9b502
+ARG LITELLM_BUILD_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:c61ac6919b811ea53c4782d69f1fe05218ba3c25d53f01b6ab7892e621bd4370
 
 # Runtime image
-ARG LITELLM_RUNTIME_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:a5a619c1793039dcf92f02178f37c94bb3d6001403716da59d6092dfe8d9b502
+ARG LITELLM_RUNTIME_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:c61ac6919b811ea53c4782d69f1fe05218ba3c25d53f01b6ab7892e621bd4370
+ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85ab0f263ef12f492d8476aa3a2e4e1e333f7d67fbdd923d00a506a516a
+
+FROM $UV_IMAGE AS uvbin
 
 # Builder stage
 FROM $LITELLM_BUILD_IMAGE AS builder
 
-# Set the working directory to /app
 WORKDIR /app
-
 USER root
 
-# Install build dependencies
-RUN apk add --no-cache bash gcc py3-pip python3 python3-dev openssl openssl-dev
+COPY --from=uvbin /uv /usr/local/bin/uv
+COPY --from=uvbin /uvx /usr/local/bin/uvx
 
-RUN python -m pip install build==1.4.2
+RUN apk add --no-cache \
+    bash \
+    gcc \
+    python3 \
+    python3-dev \
+    openssl \
+    openssl-dev \
+    nodejs \
+    npm \
+    libsndfile
 
-# Copy the current directory contents into the container at /app
+ENV UV_PROJECT_ENVIRONMENT=/app/.venv \
+    UV_LINK_MODE=copy \
+    PATH="/app/.venv/bin:${PATH}"
+
+# Copy dependency metadata first for layer caching
+COPY pyproject.toml uv.lock ./
+COPY enterprise/pyproject.toml enterprise/
+COPY litellm-proxy-extras/pyproject.toml litellm-proxy-extras/
+
+# Install third-party dependencies (cached unless pyproject.toml/uv.lock change)
+RUN uv sync --frozen --no-install-project --no-install-workspace --no-default-groups --no-editable \
+    --extra proxy \
+    --extra proxy-runtime \
+    --extra extra_proxy \
+    --extra semantic-router \
+    --python python3
+
+# Copy full source tree
 COPY . .
 
-# Build Admin UI
-# Convert Windows line endings to Unix and make executable
+# Build Admin UI before final sync
 RUN sed -i 's/\r$//' docker/build_admin_ui.sh && chmod +x docker/build_admin_ui.sh && ./docker/build_admin_ui.sh
 
-# Build the package
-RUN rm -rf dist/* && python -m build
+# Install project and workspace packages (fast - deps already cached)
+RUN uv sync --frozen --no-default-groups --no-editable \
+    --extra proxy \
+    --extra proxy-runtime \
+    --extra extra_proxy \
+    --extra semantic-router \
+    --python python3
 
-# There should be only one wheel file now, assume the build only creates one
-RUN ls -1 dist/*.whl | head -1
+RUN prisma generate --schema=./schema.prisma
 
-# Install the package
-RUN pip install dist/*.whl
-
-# install dependencies as wheels
-RUN pip wheel --no-cache-dir --wheel-dir=/wheels/ -r requirements.txt
-
-# ensure pyjwt is used, not jwt
-RUN pip uninstall jwt -y
-RUN pip uninstall PyJWT -y
-RUN pip install PyJWT==2.12.0 --no-cache-dir
+RUN sed -i 's/\r$//' docker/entrypoint.sh && chmod +x docker/entrypoint.sh && \
+    sed -i 's/\r$//' docker/prod_entrypoint.sh && chmod +x docker/prod_entrypoint.sh
 
 # Runtime stage
 FROM $LITELLM_RUNTIME_IMAGE AS runtime
 
-# Ensure runtime stage runs as root
 USER root
 
-# Install runtime dependencies (libsndfile needed for audio processing on ARM64)
-RUN apk add --no-cache bash openssl tzdata nodejs npm python3 py3-pip libsndfile && \
-    npm install -g npm@11.12.1 tar@7.5.11 glob@11.1.0 @isaacs/brace-expansion@5.0.1 minimatch@10.2.4 diff@8.0.3 && \
-    # SECURITY FIX: npm bundles tar, glob, and brace-expansion at multiple nested
-    # levels inside its dependency tree. `npm install -g <pkg>` only creates a
-    # SEPARATE global package, it does NOT replace npm's internal copies.
-    # We must find and replace EVERY copy inside npm's directory.
-    GLOBAL="$(npm root -g)" && \
-    find "$GLOBAL/npm" -type d -name "tar" -path "*/node_modules/tar" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/tar" "$d"; \
-    done && \
-    find "$GLOBAL/npm" -type d -name "glob" -path "*/node_modules/glob" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/glob" "$d"; \
-    done && \
-    find "$GLOBAL/npm" -type d -name "brace-expansion" -path "*/node_modules/@isaacs/brace-expansion" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/@isaacs/brace-expansion" "$d"; \
-    done && \
-    find "$GLOBAL/npm" -type d -name "minimatch" -path "*/node_modules/minimatch" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/minimatch" "$d"; \
-    done && \
-    find "$GLOBAL/npm" -type d -name "diff" -path "*/node_modules/diff" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/diff" "$d"; \
-    done && \
-    # SECURITY FIX: patch npm's own package.json metadata so scanners see the
-    # actual installed versions instead of the stale declared dependencies.
-    find /usr/local/lib /usr/lib -path "*/node_modules/npm/package.json" -exec \
-        sed -i 's/"tar": "\^7\.5\.[0-9]*"/"tar": "^7.5.10"/g; s/"minimatch": "\^10\.[0-9.]*"/"minimatch": "^10.2.4"/g' {} + 2>/dev/null && \
-    npm cache clean --force && \
-    # Remove the apk-tracked npm so its stale SBOM metadata (tar 7.5.9) is
-    # no longer visible to image scanners.  The globally installed npm@latest
-    # at /usr/local/lib/node_modules/npm/ remains fully functional.
-    { apk del --no-cache npm 2>/dev/null || true; }
+# node (without npm) is required by the prisma CLI at runtime
+RUN apk add --no-cache bash openssl tzdata nodejs python3 libsndfile
 
 WORKDIR /app
-# Copy the current directory contents into the container at /app
-COPY . .
-RUN ls -la /app
+ENV PATH="/app/.venv/bin:${PATH}"
 
-# Copy the built wheel from the builder stage to the runtime stage; assumes only one wheel file is present
-COPY --from=builder /app/dist/*.whl .
-COPY --from=builder /wheels/ /wheels/
+# Copy only what runtime needs. The application is installed inside the venv;
+# the rest of the builder's /app is source and build metadata that must not
+# ship (manifest-scanning tools attribute everything in it to this image).
+# entrypoint.sh invokes litellm/proxy/prisma_migration.py by source path.
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /app/docker /app/docker
+COPY --from=builder /app/schema.prisma /app/schema.prisma
+COPY --from=builder /app/litellm/proxy/prisma_migration.py /app/litellm/proxy/prisma_migration.py
+# enterprise/ is imported by source path at runtime (proxy_cli puts the
+# working directory on sys.path; litellm/proxy/hooks resolves
+# enterprise.enterprise_hooks from it)
+COPY --from=builder /app/enterprise /app/enterprise
+# Prisma binaries live in $HOME/.cache (default prisma-python location),
+# which is /root/.cache here. Copy only the Prisma subdirs — copying the
+# whole /root/.cache drags in the uv build cache (~660 MB, includes a
+# setuptools wheel that surfaces as a CVE finding even though it's not
+# on the runtime sys.path).
+COPY --from=builder /root/.cache/prisma /root/.cache/prisma
+COPY --from=builder /root/.cache/prisma-python /root/.cache/prisma-python
 
-# Install the built wheel using pip; again using a wildcard if it's the only file
-RUN pip install *.whl /wheels/* --no-index --find-links=/wheels/ --no-deps && rm -f *.whl && rm -rf /wheels
-
-# Replace the nodejs-wheel-binaries bundled node with the system node (fixes CVE-2025-55130)
-RUN NODEJS_WHEEL_NODE=$(find /usr/lib -path "*/nodejs_wheel/bin/node" 2>/dev/null) && \
-    if [ -n "$NODEJS_WHEEL_NODE" ]; then cp /usr/bin/node "$NODEJS_WHEEL_NODE"; fi
-
-# Remove test files and keys from dependencies
-RUN find /usr/lib -type f -path "*/tornado/test/*" -delete && \
-    find /usr/lib -type d -path "*/tornado/test" -delete
-
-# SECURITY FIX: nodejs-wheel-binaries (pip package used by Prisma) bundles a complete
-# npm with old vulnerable deps at /usr/lib/python3.*/site-packages/nodejs_wheel/.
-# Patch every copy of tar, glob, and brace-expansion inside that tree.
-RUN GLOBAL="$(npm root -g)" && \
-    [ -n "$GLOBAL" ] || { echo "ERROR: npm root -g returned empty; aborting"; exit 1; } && \
-    find /usr/lib -type d -name "tar" -path "*/node_modules/tar" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/tar" "$d"; \
-    done && \
-    find /usr/lib -type d -name "glob" -path "*/node_modules/glob" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/glob" "$d"; \
-    done && \
-    find /usr/lib -type d -name "brace-expansion" -path "*/node_modules/@isaacs/brace-expansion" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/@isaacs/brace-expansion" "$d"; \
-    done && \
-    find /usr/lib -type d -name "minimatch" -path "*/node_modules/minimatch" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/minimatch" "$d"; \
-    done && \
-    find /usr/lib -type d -name "diff" -path "*/node_modules/diff" | while read d; do \
-        rm -rf "$d" && cp -rL "$GLOBAL/diff" "$d"; \
-    done
-
-# Install semantic_router and aurelio-sdk using script
-# Convert Windows line endings to Unix and make executable
-RUN sed -i 's/\r$//' docker/install_auto_router.sh && chmod +x docker/install_auto_router.sh && ./docker/install_auto_router.sh
-
-# Generate prisma client using the correct schema
-RUN prisma generate --schema=./litellm/proxy/schema.prisma
-# Convert Windows line endings to Unix for entrypoint scripts
-RUN sed -i 's/\r$//' docker/entrypoint.sh && chmod +x docker/entrypoint.sh
-RUN sed -i 's/\r$//' docker/prod_entrypoint.sh && chmod +x docker/prod_entrypoint.sh
+RUN find /app/.venv -type f -path "*/tornado/test/*" -delete && \
+    find /app/.venv -type d -path "*/tornado/test" -delete
 
 EXPOSE 4000/tcp
 
-RUN apk add --no-cache supervisor
-COPY docker/supervisord.conf /etc/supervisord.conf
-
 ENTRYPOINT ["docker/prod_entrypoint.sh"]
-
-# Append "--detailed_debug" to the end of CMD to view detailed debug logs
 CMD ["--port", "4000"]

GEMINI.md

@@ -1,108 +1 @@
-# GEMINI.md
-
-This file provides guidance to Gemini when working with code in this repository.
-
-## Development Commands
-
-### Installation
-- `make install-dev` - Install core development dependencies
-- `make install-proxy-dev` - Install proxy development dependencies with full feature set
-- `make install-test-deps` - Install all test dependencies
-
-### Testing
-- `make test` - Run all tests
-- `make test-unit` - Run unit tests (tests/test_litellm) with 4 parallel workers
-- `make test-integration` - Run integration tests (excludes unit tests)
-- `pytest tests/` - Direct pytest execution
-
-### Code Quality
-- `make lint` - Run all linting (Ruff, MyPy, Black, circular imports, import safety)
-- `make format` - Apply Black code formatting
-- `make lint-ruff` - Run Ruff linting only
-- `make lint-mypy` - Run MyPy type checking only
-
-### Single Test Files
-- `poetry run pytest tests/path/to/test_file.py -v` - Run specific test file
-- `poetry run pytest tests/path/to/test_file.py::test_function -v` - Run specific test
-
-### Running Scripts
-- `poetry run python script.py` - Run Python scripts (use for non-test files)
-
-### GitHub Issue & PR Templates
-When contributing to the project, use the appropriate templates:
-
-**Bug Reports** (`.github/ISSUE_TEMPLATE/bug_report.yml`):
-- Describe what happened vs. what you expected
-- Include relevant log output
-- Specify your LiteLLM version
-
-**Feature Requests** (`.github/ISSUE_TEMPLATE/feature_request.yml`):
-- Describe the feature clearly
-- Explain the motivation and use case
-
-**Pull Requests** (`.github/pull_request_template.md`):
-- Add at least 1 test in `tests/litellm/`
-- Ensure `make test-unit` passes
-
-## Architecture Overview
-
-LiteLLM is a unified interface for 100+ LLM providers with two main components:
-
-### Core Library (`litellm/`)
-- **Main entry point**: `litellm/main.py` - Contains core completion() function
-- **Provider implementations**: `litellm/llms/` - Each provider has its own subdirectory
-- **Router system**: `litellm/router.py` + `litellm/router_utils/` - Load balancing and fallback logic
-- **Type definitions**: `litellm/types/` - Pydantic models and type hints
-- **Integrations**: `litellm/integrations/` - Third-party observability, caching, logging
-- **Caching**: `litellm/caching/` - Multiple cache backends (Redis, in-memory, S3, etc.)
-
-### Proxy Server (`litellm/proxy/`)
-- **Main server**: `proxy_server.py` - FastAPI application
-- **Authentication**: `auth/` - API key management, JWT, OAuth2
-- **Database**: `db/` - Prisma ORM with PostgreSQL/SQLite support
-- **Management endpoints**: `management_endpoints/` - Admin APIs for keys, teams, models
-- **Pass-through endpoints**: `pass_through_endpoints/` - Provider-specific API forwarding
-- **Guardrails**: `guardrails/` - Safety and content filtering hooks
-- **UI Dashboard**: Served from `_experimental/out/` (Next.js build)
-
-## Key Patterns
-
-### Provider Implementation
-- Providers inherit from base classes in `litellm/llms/base.py`
-- Each provider has transformation functions for input/output formatting
-- Support both sync and async operations
-- Handle streaming responses and function calling
-
-### Error Handling
-- Provider-specific exceptions mapped to OpenAI-compatible errors
-- Fallback logic handled by Router system
-- Comprehensive logging through `litellm/_logging.py`
-
-### Configuration
-- YAML config files for proxy server (see `proxy/example_config_yaml/`)
-- Environment variables for API keys and settings
-- Database schema managed via Prisma (`proxy/schema.prisma`)
-
-## Development Notes
-
-### Code Style
-- Uses Black formatter, Ruff linter, MyPy type checker
-- Pydantic v2 for data validation
-- Async/await patterns throughout
-- Type hints required for all public APIs
-
-### Testing Strategy
-- Unit tests in `tests/test_litellm/`
-- Integration tests for each provider in `tests/llm_translation/`
-- Proxy tests in `tests/proxy_unit_tests/`
-- Load tests in `tests/load_tests/`
-
-### Database Migrations
-- Prisma handles schema migrations
-- Migration files auto-generated with `prisma migrate dev`
-- Always test migrations against both PostgreSQL and SQLite
-
-### Enterprise Features
-- Enterprise-specific code in `enterprise/` directory
-- Optional features enabled via environment variables
-- Separate licensing and authentication for enterprise features
+Read @CLAUDE.md for coding guidelines

Makefile

@@ -5,7 +5,9 @@
 	test-unit-integrations test-unit-core-utils test-unit-other test-unit-root \
 	test-proxy-unit-a test-proxy-unit-b test-integration test-unit-helm \
 	info lint lint-dev format \
-	install-dev install-proxy-dev install-test-deps \
+	lint-basedpyright lint-basedpyright-budget-update \
+	lint-ruff-budget lint-ruff-budget-update lint-budget-update lint-gate \
+	install-dev install-proxy-dev install-test-deps install-hooks \
 	install-helm-unittest check-circular-imports check-import-safety
 
 # Default target
@@ -15,14 +17,20 @@ help:
 	@echo "  make install-proxy-dev  - Install proxy development dependencies"
 	@echo "  make install-dev-ci     - Install dev dependencies (CI-compatible, pins OpenAI)"
 	@echo "  make install-proxy-dev-ci - Install proxy dev dependencies (CI-compatible)"
-	@echo "  make install-test-deps  - Install test dependencies"
+	@echo "  make install-test-deps  - Install the full local test environment"
 	@echo "  make install-helm-unittest - Install helm unittest plugin"
+	@echo "  make install-hooks      - Install git hooks (Conventional Commits + Branches)"
 	@echo "  make format             - Apply Black code formatting"
 	@echo "  make format-check       - Check Black code formatting (matches CI)"
-	@echo "  make lint               - Run all linting (Ruff, MyPy, Black check, circular imports, import safety)"
+	@echo "  make lint               - Run all linting (Ruff, basedpyright, Black check, circular imports, import safety)"
 	@echo "  make lint-ruff          - Run Ruff linting only"
-	@echo "  make lint-mypy          - Run MyPy type checking only"
+	@echo "  make lint-basedpyright  - Run basedpyright strict, gated by per-rule error counts"
+	@echo "  make lint-basedpyright-budget-update - Re-capture the basedpyright per-rule budget (ratchet)"
 	@echo "  make lint-black         - Check Black formatting (matches CI)"
+	@echo "  make lint-ruff-budget - Gate the codebase total of each strict ruff rule against its ceiling"
+	@echo "  make lint-gate        - Strict ruff gate in CI-parity mode (fetches staging, simulates the merge)"
+	@echo "  make lint-ruff-budget-update - Re-capture per-rule baselines in ruff-strict-budget.json (ratchet)"
+	@echo "  make lint-budget-update - Re-capture all ratchet budgets (ruff + basedpyright)"
 	@echo "  make check-circular-imports - Check for circular imports"
 	@echo "  make check-import-safety - Check import safety"
 	@echo "  make test               - Run all tests"
@@ -40,49 +48,49 @@ help:
 	@echo "  make test-integration   - Run integration tests"
 	@echo "  make test-unit-helm     - Run helm unit tests"
 
-# Keep PIP simple for edge cases:
-PIP := $(shell command -v pip > /dev/null 2>&1 && echo "pip" || echo "python3 -m pip")
+UV := uv
+UV_RUN := $(UV) run --no-sync
 
 # Show info
 info:
-	@echo "PIP: $(PIP)"
+	@echo "UV: $(UV)"
 
 # Installation targets
 install-dev:
-	poetry install --with dev
+	$(UV) sync --frozen
 
 install-proxy-dev:
-	poetry install --with dev,proxy-dev --extras proxy
+	$(UV) sync --frozen --group proxy-dev --extra proxy
 
 # CI-compatible installations (matches GitHub workflows exactly)
 install-dev-ci:
-	$(PIP) install openai==2.8.0
-	poetry install --with dev
-	$(PIP) install openai==2.8.0
+	$(UV) sync --frozen
 
 install-proxy-dev-ci:
-	poetry install --with dev,proxy-dev --extras proxy
-	$(PIP) install openai==2.8.0
+	$(UV) sync --frozen --group proxy-dev --extra proxy
 
 install-test-deps: install-proxy-dev
-	poetry run $(PIP) install "pytest-retry==1.6.3"
-	poetry run $(PIP) install pytest-xdist
-	poetry run $(PIP) install openapi-core
-	cd enterprise && poetry run $(PIP) install -e . && cd ..
+	$(UV) sync --frozen --all-groups --all-extras
+	$(UV_RUN) prisma generate --schema litellm/proxy/schema.prisma
 
 install-helm-unittest:
 	helm plugin install https://github.com/helm-unittest/helm-unittest --version v0.4.4 || echo "ignore error if plugin exists"
 
+# Install git hooks that enforce Conventional Commits and Conventional Branches.
+# Opt-in: not chained into install-dev.
+install-hooks:
+	./scripts/install_git_hooks.sh
+
 # Formatting
 format: install-dev
-	cd litellm && poetry run black . && cd ..
+	cd litellm && $(UV_RUN) black . && cd ..
 
 format-check: install-dev
-	cd litellm && poetry run black --check . && cd ..
+	cd litellm && $(UV_RUN) black --check . && cd ..
 
 # Linting targets
 lint-ruff: install-dev
-	cd litellm && poetry run ruff check . && cd ..
+	cd litellm && $(UV_RUN) ruff check . && cd ..
 
 # faster linter for developing ...
 # inspiration from:
@@ -96,85 +104,103 @@ lint-format-changed: install-dev
 			$$start = $$1; $$count = $$2 || 1; $$end = $$start + $$count - 1; \
 			print "$$file:$$start:1-$$end:999\n"; \
 		}' | \
-	while read range; do \
-		file="$${range%%:*}"; \
-		lines="$${range#*:}"; \
-		echo "Formatting $$file (lines $$lines)"; \
-		poetry run ruff format --range "$$lines" "$$file"; \
-	done
+		while read range; do \
+			file="$${range%%:*}"; \
+			lines="$${range#*:}"; \
+			echo "Formatting $$file (lines $$lines)"; \
+			$(UV_RUN) ruff format --range "$$lines" "$$file"; \
+		done
 
 lint-ruff-dev: install-dev
 	@tmpfile=$$(mktemp /tmp/ruff-dev.XXXXXX) && \
 	cd litellm && \
-	(poetry run ruff check . --output-format=pylint || true) > "$$tmpfile" && \
-	poetry run diff-quality --violations=pylint "$$tmpfile" --compare-branch=origin/main && \
+	($(UV_RUN) ruff check . --output-format=pylint || true) > "$$tmpfile" && \
+	$(UV_RUN) diff-quality --violations=pylint "$$tmpfile" --compare-branch=origin/main && \
 	cd .. ; \
 	rm -f "$$tmpfile"
 
 lint-ruff-FULL-dev: install-dev
 	@files=$$(git diff --name-only origin/main -- '*.py'); \
-	if [ -n "$$files" ]; then echo "$$files" | xargs poetry run ruff check; \
+	if [ -n "$$files" ]; then echo "$$files" | xargs $(UV_RUN) ruff check; \
 	else echo "No changed .py files to check."; fi
 
-lint-mypy: install-dev
-	poetry run $(PIP) install types-requests types-setuptools types-redis types-PyYAML
-	cd litellm && poetry run mypy . --ignore-missing-imports && cd ..
+lint-basedpyright: install-dev
+	git fetch origin litellm_internal_staging
+	($(UV_RUN) basedpyright --outputjson || true) | $(UV_RUN) python scripts/type_check_gate.py --base origin/litellm_internal_staging
+
+lint-basedpyright-budget-update: install-dev
+	($(UV_RUN) basedpyright --outputjson || true) | $(UV_RUN) python scripts/type_check_gate.py --update
 
 lint-black: format-check
 
+lint-ruff-budget: install-dev
+	$(UV_RUN) python scripts/ruff_strict_gate.py
+
+# Strict gate, invoked the same way CI does in test-linting.yml so a local pass
+# means the CI check will pass too.
+lint-gate: install-dev
+	git fetch origin litellm_internal_staging
+	$(UV_RUN) python scripts/ruff_strict_gate.py --base origin/litellm_internal_staging
+
+lint-ruff-budget-update: install-dev
+	$(UV_RUN) python scripts/ruff_strict_gate.py --update
+
+# Ratchet all budgets in one shot (ruff strict + basedpyright)
+lint-budget-update: lint-ruff-budget-update lint-basedpyright-budget-update
+
 check-circular-imports: install-dev
-	cd litellm && poetry run python ../tests/documentation_tests/test_circular_imports.py && cd ..
+	cd litellm && $(UV_RUN) python ../tests/documentation_tests/test_circular_imports.py && cd ..
 
 check-import-safety: install-dev
-	@poetry run python -c "from litellm import *; print('[from litellm import *] OK! no issues!');" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)
+	@$(UV_RUN) python -c "from litellm import *; print('[from litellm import *] OK! no issues!');" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)
 
 # Combined linting (matches test-linting.yml workflow)
-lint: format-check lint-ruff lint-mypy check-circular-imports check-import-safety
+lint: format-check lint-ruff lint-basedpyright check-circular-imports check-import-safety lint-ruff-budget
 
 # Faster linting for local development (only checks changed code)
-lint-dev: lint-format-changed lint-mypy check-circular-imports check-import-safety
+lint-dev: lint-format-changed check-circular-imports check-import-safety
 
 # Testing targets
-test:
-	poetry run pytest tests/
+test: install-test-deps
+	$(UV_RUN) pytest tests/
 
 test-unit: install-test-deps
-	poetry run pytest tests/test_litellm -x -vv -n 4
+	$(UV_RUN) pytest tests/test_litellm -x -vv -n 4
 
 # Matrix test targets (matching CI workflow groups)
 test-unit-llms: install-test-deps
-	poetry run pytest tests/test_litellm/llms --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/llms --tb=short -vv -n 4 --durations=20
 
 test-unit-proxy-guardrails: install-test-deps
-	poetry run pytest tests/test_litellm/proxy/guardrails tests/test_litellm/proxy/management_endpoints tests/test_litellm/proxy/management_helpers --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/proxy/guardrails tests/test_litellm/proxy/management_endpoints tests/test_litellm/proxy/management_helpers --tb=short -vv -n 4 --durations=20
 
 test-unit-proxy-core: install-test-deps
-	poetry run pytest tests/test_litellm/proxy/auth tests/test_litellm/proxy/client tests/test_litellm/proxy/db tests/test_litellm/proxy/hooks tests/test_litellm/proxy/policy_engine --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/proxy/auth tests/test_litellm/proxy/client tests/test_litellm/proxy/db tests/test_litellm/proxy/hooks tests/test_litellm/proxy/policy_engine --tb=short -vv -n 4 --durations=20
 
 test-unit-proxy-misc: install-test-deps
-	poetry run pytest tests/test_litellm/proxy/_experimental tests/test_litellm/proxy/agent_endpoints tests/test_litellm/proxy/anthropic_endpoints tests/test_litellm/proxy/common_utils tests/test_litellm/proxy/discovery_endpoints tests/test_litellm/proxy/experimental tests/test_litellm/proxy/google_endpoints tests/test_litellm/proxy/health_endpoints tests/test_litellm/proxy/image_endpoints tests/test_litellm/proxy/middleware tests/test_litellm/proxy/openai_files_endpoint tests/test_litellm/proxy/pass_through_endpoints tests/test_litellm/proxy/prompts tests/test_litellm/proxy/public_endpoints tests/test_litellm/proxy/response_api_endpoints tests/test_litellm/proxy/spend_tracking tests/test_litellm/proxy/ui_crud_endpoints tests/test_litellm/proxy/vector_store_endpoints tests/test_litellm/proxy/test_*.py --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/proxy/_experimental tests/test_litellm/proxy/agent_endpoints tests/test_litellm/proxy/anthropic_endpoints tests/test_litellm/proxy/common_utils tests/test_litellm/proxy/discovery_endpoints tests/test_litellm/proxy/experimental tests/test_litellm/proxy/google_endpoints tests/test_litellm/proxy/health_endpoints tests/test_litellm/proxy/image_endpoints tests/test_litellm/proxy/middleware tests/test_litellm/proxy/openai_files_endpoint tests/test_litellm/proxy/pass_through_endpoints tests/test_litellm/proxy/prompts tests/test_litellm/proxy/public_endpoints tests/test_litellm/proxy/response_api_endpoints tests/test_litellm/proxy/shutdown tests/test_litellm/proxy/spend_tracking tests/test_litellm/proxy/ui_crud_endpoints tests/test_litellm/proxy/vector_store_endpoints tests/test_litellm/proxy/test_*.py --tb=short -vv -n 4 --durations=20
 
 test-unit-integrations: install-test-deps
-	poetry run pytest tests/test_litellm/integrations --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/integrations --tb=short -vv -n 4 --durations=20
 
 test-unit-core-utils: install-test-deps
-	poetry run pytest tests/test_litellm/litellm_core_utils --tb=short -vv -n 2 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/litellm_core_utils --tb=short -vv -n 2 --durations=20
 
 test-unit-other: install-test-deps
-	poetry run pytest tests/test_litellm/caching tests/test_litellm/responses tests/test_litellm/secret_managers tests/test_litellm/vector_stores tests/test_litellm/a2a_protocol tests/test_litellm/anthropic_interface tests/test_litellm/completion_extras tests/test_litellm/containers tests/test_litellm/enterprise tests/test_litellm/experimental_mcp_client tests/test_litellm/google_genai tests/test_litellm/images tests/test_litellm/interactions tests/test_litellm/passthrough tests/test_litellm/router_strategy tests/test_litellm/router_utils tests/test_litellm/types --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/caching tests/test_litellm/responses tests/test_litellm/secret_managers tests/test_litellm/vector_stores tests/test_litellm/a2a_protocol tests/test_litellm/anthropic_interface tests/test_litellm/completion_extras tests/test_litellm/containers tests/test_litellm/enterprise tests/test_litellm/experimental_mcp_client tests/test_litellm/google_genai tests/test_litellm/images tests/test_litellm/interactions tests/test_litellm/passthrough tests/test_litellm/router_strategy tests/test_litellm/router_utils tests/test_litellm/types --tb=short -vv -n 4 --durations=20
 
 test-unit-root: install-test-deps
-	poetry run pytest tests/test_litellm/test_*.py --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/test_litellm/test_*.py --tb=short -vv -n 4 --durations=20
 
 # Proxy unit tests (tests/proxy_unit_tests split alphabetically)
 test-proxy-unit-a: install-test-deps
-	poetry run pytest tests/proxy_unit_tests/test_[a-o]*.py --tb=short -vv -n 2 --durations=20
+	$(UV_RUN) pytest tests/proxy_unit_tests/test_[a-o]*.py --tb=short -vv -n 2 --durations=20
 
 test-proxy-unit-b: install-test-deps
-	poetry run pytest tests/proxy_unit_tests/test_[p-z]*.py --tb=short -vv -n 2 --durations=20
+	$(UV_RUN) pytest tests/proxy_unit_tests/test_[p-z]*.py --tb=short -vv -n 2 --durations=20
 
-test-integration:
-	poetry run pytest tests/ -k "not test_litellm"
+test-integration: install-test-deps
+	$(UV_RUN) pytest tests/ -k "not test_litellm"
 
 test-unit-helm: install-helm-unittest
 	helm unittest -f 'tests/*.yaml' deploy/charts/litellm-helm
@@ -188,6 +214,9 @@ test-llm-translation-single: install-test-deps
 	@echo "Running single LLM translation test file..."
 	@if [ -z "$(FILE)" ]; then echo "Usage: make test-llm-translation-single FILE=test_filename.py"; exit 1; fi
 	@mkdir -p test-results
-	poetry run pytest tests/llm_translation/$(FILE) \
+	$(UV_RUN) pytest tests/llm_translation/$(FILE) \
 		--junitxml=test-results/junit.xml \
 		-v --tb=short --maxfail=100 --timeout=300
+
+test-llm-translation-flush-vcr-cache:
+	$(UV_RUN) python tests/_flush_vcr_cache.py

README.md

@@ -6,13 +6,13 @@
         </p>
         <p align="center">Open Source AI Gateway for 100+ LLMs. Self-hosted. Enterprise-ready. Call any LLM in OpenAI format.</p>
         <p align="center">
-        <a href="https://render.com/deploy?repo=https://github.com/BerriAI/litellm" target="_blank" rel="nofollow"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render"></a>
-        <a href="https://railway.com/deploy/RhvhdC?referralCode=7mRv9K&utm_medium=integration&utm_source=template&utm_campaign=generic">
-          <img src="https://railway.com/button.svg" alt="Deploy on Railway">
-        </a>
+        <a href="https://render.com/deploy?repo=https://github.com/BerriAI/litellm" target="_blank" rel="nofollow"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" height="40"></a>
+        <a href="https://railway.com/deploy/RhvhdC?referralCode=7mRv9K&utm_medium=integration&utm_source=template&utm_campaign=generic"><img src="https://railway.com/button.svg" alt="Deploy on Railway" height="40"></a>
+        <a href="https://console.aws.amazon.com/cloudshell/home" target="_blank" rel="nofollow"><img src="./.github/deploy-on-aws.png" alt="Deploy on AWS" height="40"></a>
+        <a href="https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2FBerriAI%2Flitellm&cloudshell_workspace=terraform%2Flitellm%2Fgcp%2Fexamples%2Fdefault&cloudshell_tutorial=TUTORIAL.md&cloudshell_image=gcr.io/ds-artifacts-cloudshell/deploystack_custom_image&shellonly=true" target="_blank" rel="nofollow"><img src="./.github/deploy-on-gcp.png" alt="Deploy on GCP" height="40"></a>
         </p>
     </p>
-<h4 align="center"><a href="https://docs.litellm.ai/docs/simple_proxy" target="_blank">LiteLLM Proxy Server (AI Gateway)</a> | <a href="https://docs.litellm.ai/docs/enterprise#hosted-litellm-proxy" target="_blank"> Hosted Proxy</a> | <a href="https://litellm.ai/enterprise"target="_blank">Enterprise Tier</a> | <a href="https://litellm.ai/" target="_blank">Website</a></h4>
+<h4 align="center"><a href="https://docs.litellm.ai/docs/simple_proxy" target="_blank">LiteLLM Proxy Server (AI Gateway)</a> | <a href="https://docs.litellm.ai/docs/enterprise#hosted-litellm-proxy" target="_blank"> Hosted Proxy</a> | <a href="https://litellm.ai/enterprise"target="_blank">Enterprise Tier</a> | <a href="https://www.litellm.ai/ai-gateway" target="_blank">Website</a></h4>
 <h4 align="center">
     <a href="https://pypi.org/project/litellm/" target="_blank">
         <img src="https://img.shields.io/pypi/v/litellm.svg" alt="PyPI Version">
@@ -37,10 +37,47 @@
     </a>
 </h4>
 
-<img width="2688" height="1600" alt="Group 7154 (1)" src="https://github.com/user-attachments/assets/c5ee0412-6fb5-4fb6-ab5b-bafae4209ca6" />
+<img alt="LiteLLM AI Gateway" src="https://github.com/user-attachments/assets/c5ee0412-6fb5-4fb6-ab5b-bafae4209ca6" />
 
+---
 
-## Use LiteLLM for
+## What is LiteLLM
+
+LiteLLM is an open source AI Gateway that gives you a single, unified interface to call 100+ LLM providers — OpenAI, Anthropic, Gemini, Bedrock, Azure, and more — using the OpenAI format.
+
+Use it as a **Python SDK** for direct library integration, or deploy the **AI Gateway (Proxy Server)** as a centralized service for your team or organization.
+
+[**Jump to LiteLLM Proxy (LLM Gateway) Docs**](https://docs.litellm.ai/docs/simple_proxy) <br>
+[**Jump to Supported LLM Providers**](https://docs.litellm.ai/docs/providers)
+
+---
+
+## Why LiteLLM
+
+Managing LLM calls across providers gets complicated fast — different SDKs, auth patterns, request formats, and error types for every model. LiteLLM removes that friction:
+
+- **Unified API** — one interface for 100+ LLMs, no provider-specific SDK juggling
+- **Drop-in OpenAI compatibility** — swap providers without rewriting your code
+- **Production-ready gateway** — virtual keys, spend tracking, guardrails, load balancing, and an admin dashboard out of the box
+- **8ms P95 latency** at 1k RPS ([benchmarks](https://docs.litellm.ai/docs/benchmarks))
+
+### OSS Adopters
+
+<table>
+  <tr>
+    <td><img height="60" alt="Stripe" src="https://github.com/user-attachments/assets/f7296d4f-9fbd-460d-9d05-e4df31697c4b" /></td>
+    <td><img height="60" alt="image" src="https://github.com/user-attachments/assets/436fca71-988b-40bb-b5fe-8450c80fdbd0" /></td>
+    <td><img height="60" alt="Google ADK" src="https://github.com/user-attachments/assets/caf270a2-5aee-45c4-8222-41a2070c4f19" /></td>
+    <td><img height="60" alt="Greptile" src="https://github.com/user-attachments/assets/3db0ae72-0843-4005-a56d-bba1dde2193d" /></td>
+    <td><img height="60" alt="OpenHands" src="https://github.com/user-attachments/assets/a6150c4c-149e-4cae-888b-8b92be6e003f" /></td>
+    <td><h2>Netflix</h2></td>
+    <td><img height="60" alt="OpenAI Agents SDK" src="https://github.com/user-attachments/assets/c02f7be0-8c2e-4d27-aea7-7c024bfaebc0" /></td>
+  </tr>
+</table>
+
+---
+
+## Features
 
 <details open>
 <summary><b>LLMs</b> - Call 100+ LLMs (Python SDK + AI Gateway)</summary>
@@ -50,7 +87,7 @@
 ### Python SDK
 
 ```shell
-pip install litellm
+uv add litellm
 ```
 
 ```python
@@ -72,7 +109,7 @@ response = completion(model="anthropic/claude-sonnet-4-20250514", messages=[{"ro
 [**Getting Started - E2E Tutorial**](https://docs.litellm.ai/docs/proxy/docker_quick_start) - Setup virtual keys, make your first request
 
 ```shell
-pip install 'litellm[proxy]'
+uv tool install 'litellm[proxy]'
 litellm --model gpt-4o
 ```
 
@@ -223,63 +260,7 @@ curl -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
 
 </details>
 
----
-
-## How to use LiteLLM
-
-You can use LiteLLM through either the Proxy Server or Python SDK. Both gives you a unified interface to access multiple LLMs (100+ LLMs). Choose the option that best fits your needs:
-
-<table style={{width: '100%', tableLayout: 'fixed'}}>
-<thead>
-<tr>
-<th style={{width: '14%'}}></th>
-<th style={{width: '43%'}}><strong><a href="https://docs.litellm.ai/docs/simple_proxy">LiteLLM AI Gateway</a></strong></th>
-<th style={{width: '43%'}}><strong><a href="https://docs.litellm.ai/docs/">LiteLLM Python SDK</a></strong></th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td style={{width: '14%'}}><strong>Use Case</strong></td>
-<td style={{width: '43%'}}>Central service (LLM Gateway) to access multiple LLMs</td>
-<td style={{width: '43%'}}>Use LiteLLM directly in your Python code</td>
-</tr>
-<tr>
-<td style={{width: '14%'}}><strong>Who Uses It?</strong></td>
-<td style={{width: '43%'}}>Gen AI Enablement / ML Platform Teams</td>
-<td style={{width: '43%'}}>Developers building LLM projects</td>
-</tr>
-<tr>
-<td style={{width: '14%'}}><strong>Key Features</strong></td>
-<td style={{width: '43%'}}>Centralized API gateway with authentication and authorization, multi-tenant cost tracking and spend management per project/user, per-project customization (logging, guardrails, caching), virtual keys for secure access control, admin dashboard UI for monitoring and management</td>
-<td style={{width: '43%'}}>Direct Python library integration in your codebase, Router with retry/fallback logic across multiple deployments (e.g. Azure/OpenAI) - <a href="https://docs.litellm.ai/docs/routing">Router</a>, application-level load balancing and cost tracking, exception handling with OpenAI-compatible errors, observability callbacks (Lunary, MLflow, Langfuse, etc.)</td>
-</tr>
-</tbody>
-</table>
-
-LiteLLM Performance: **8ms P95 latency** at 1k RPS (See benchmarks [here](https://docs.litellm.ai/docs/benchmarks))
-
-[**Jump to LiteLLM Proxy (LLM Gateway) Docs**](https://docs.litellm.ai/docs/simple_proxy) <br>
-[**Jump to Supported LLM Providers**](https://docs.litellm.ai/docs/providers)
-
-**Stable Release:** Use docker images with the `-stable` tag. These have undergone 12 hour load tests, before being published. [More information about the release cycle here](https://docs.litellm.ai/docs/proxy/release_cycle)
-
-Support for more providers. Missing a provider or LLM Platform, raise a [feature request](https://github.com/BerriAI/litellm/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFeature%5D%3A+).
-
-## OSS Adopters 
-
-<table>
-  <tr>
-    <td><img height="60" alt="Stripe" src="https://github.com/user-attachments/assets/f7296d4f-9fbd-460d-9d05-e4df31697c4b" /></td>
-    <td><img height="60" alt="image" src="https://github.com/user-attachments/assets/436fca71-988b-40bb-b5fe-8450c80fdbd0" /></td>
-    <td><img height="60" alt="Google ADK" src="https://github.com/user-attachments/assets/caf270a2-5aee-45c4-8222-41a2070c4f19" /></td>
-    <td><img height="60" alt="Greptile" src="https://github.com/user-attachments/assets/0be4bd8a-7cfa-48d3-9090-f415fe948280" /></td>
-    <td><img height="60" alt="OpenHands" src="https://github.com/user-attachments/assets/a6150c4c-149e-4cae-888b-8b92be6e003f" /></td>
-    <td><h2>Netflix</h2></td>
-    <td><img height="60" alt="OpenAI Agents SDK" src="https://github.com/user-attachments/assets/c02f7be0-8c2e-4d27-aea7-7c024bfaebc0" /></td>
-  </tr>
-</table>
-
-## Supported Providers ([Website Supported Models](https://models.litellm.ai/) | [Docs](https://docs.litellm.ai/docs/providers))
+### Supported Providers ([Website Supported Models](https://models.litellm.ai/) | [Docs](https://docs.litellm.ai/docs/providers))
 
 | Provider                                                                            | `/chat/completions` | `/messages` | `/responses` | `/embeddings` | `/image/generations` | `/audio/transcriptions` | `/audio/speech` | `/moderations` | `/batches` | `/rerank` |
 |-------------------------------------------------------------------------------------|---------------------|-------------|--------------|---------------|----------------------|-------------------------|-----------------|----------------|-----------|-----------|
@@ -311,7 +292,7 @@ Support for more providers. Missing a provider or LLM Platform, raise a [feature
 | [CompactifAI (`compactifai`)](https://docs.litellm.ai/docs/providers/compactifai) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Custom (`custom`)](https://docs.litellm.ai/docs/providers/custom_llm_server) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Custom OpenAI (`custom_openai`)](https://docs.litellm.ai/docs/providers/openai_compatible) | ✅ | ✅ | ✅ |  |  | ✅ | ✅ | ✅ | ✅ |  |
-| [Dashscope (`dashscope`)](https://docs.litellm.ai/docs/providers/dashscope) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
+| [Dashscope (`dashscope`)](https://docs.litellm.ai/docs/providers/dashscope) | ✅ | ✅ | ✅ | ✅ |  |  |  |  |  | ✅ |
 | [Databricks (`databricks`)](https://docs.litellm.ai/docs/providers/databricks) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [DataRobot (`datarobot`)](https://docs.litellm.ai/docs/providers/datarobot) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Deepgram (`deepgram`)](https://docs.litellm.ai/docs/providers/deepgram) | ✅ | ✅ | ✅ |  |  | ✅ |  |  |  |  |
@@ -346,6 +327,7 @@ Support for more providers. Missing a provider or LLM Platform, raise a [feature
 | [Maritalk (`maritalk`)](https://docs.litellm.ai/docs/providers/maritalk) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Meta - Llama API (`meta_llama`)](https://docs.litellm.ai/docs/providers/meta_llama) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Mistral AI API (`mistral`)](https://docs.litellm.ai/docs/providers/mistral) | ✅ | ✅ | ✅ | ✅ |  |  |  |  |  |  |
+| [ModelScope (`modelscope`)](https://docs.litellm.ai/docs/providers/modelscope) | ✅ | ✅ | ✅ |  | ✅ |  |  |  |  |  |
 | [Moonshot (`moonshot`)](https://docs.litellm.ai/docs/providers/moonshot) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Morph (`morph`)](https://docs.litellm.ai/docs/providers/morph) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Nebius AI Studio (`nebius`)](https://docs.litellm.ai/docs/providers/nebius) | ✅ | ✅ | ✅ | ✅ |  |  |  |  |  |  |
@@ -363,6 +345,7 @@ Support for more providers. Missing a provider or LLM Platform, raise a [feature
 | [OVHCloud AI Endpoints (`ovhcloud`)](https://docs.litellm.ai/docs/providers/ovhcloud) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Perplexity AI (`perplexity`)](https://docs.litellm.ai/docs/providers/perplexity) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Petals (`petals`)](https://docs.litellm.ai/docs/providers/petals) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
+| [Pinstripes (`pinstripes`)](https://docs.litellm.ai/docs/providers/pinstripes) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Predibase (`predibase`)](https://docs.litellm.ai/docs/providers/predibase) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Recraft (`recraft`)](https://docs.litellm.ai/docs/providers/recraft) |  |  |  |  | ✅ |  |  |  |  |  |
 | [Replicate (`replicate`)](https://docs.litellm.ai/docs/providers/replicate) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
@@ -386,24 +369,223 @@ Support for more providers. Missing a provider or LLM Platform, raise a [feature
 
 [**Read the Docs**](https://docs.litellm.ai/docs/)
 
-## Run in Developer mode
-### Services
-1. Setup .env file in root
-2. Run dependant services `docker-compose up db prometheus`
+---
 
-### Backend
+## Get Started
+
+You can use LiteLLM through either the Proxy Server or Python SDK. Both give you a unified interface to access multiple LLMs (100+ LLMs). Choose the option that best fits your needs:
+
+<table style={{width: '100%', tableLayout: 'fixed'}}>
+<thead>
+<tr>
+<th style={{width: '14%'}}></th>
+<th style={{width: '43%'}}><strong><a href="https://docs.litellm.ai/docs/simple_proxy">LiteLLM AI Gateway</a></strong></th>
+<th style={{width: '43%'}}><strong><a href="https://docs.litellm.ai/docs/">LiteLLM Python SDK</a></strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style={{width: '14%'}}><strong>Use Case</strong></td>
+<td style={{width: '43%'}}>Central service (LLM Gateway) to access multiple LLMs</td>
+<td style={{width: '43%'}}>Use LiteLLM directly in your Python code</td>
+</tr>
+<tr>
+<td style={{width: '14%'}}><strong>Who Uses It?</strong></td>
+<td style={{width: '43%'}}>Gen AI Enablement / ML Platform Teams</td>
+<td style={{width: '43%'}}>Developers building LLM projects</td>
+</tr>
+<tr>
+<td style={{width: '14%'}}><strong>Key Features</strong></td>
+<td style={{width: '43%'}}>Centralized API gateway with authentication and authorization, multi-tenant cost tracking and spend management per project/user, per-project customization (logging, guardrails, caching), virtual keys for secure access control, admin dashboard UI for monitoring and management</td>
+<td style={{width: '43%'}}>Direct Python library integration in your codebase, Router with retry/fallback logic across multiple deployments (e.g. Azure/OpenAI) - <a href="https://docs.litellm.ai/docs/routing">Router</a>, application-level load balancing and cost tracking, exception handling with OpenAI-compatible errors, observability callbacks (Lunary, MLflow, Langfuse, etc.)</td>
+</tr>
+</tbody>
+</table>
+
+**Stable Release:** Use docker images with the `-stable` tag. These have undergone 12 hour load tests, before being published. [More information about the release cycle here](https://docs.litellm.ai/docs/proxy/release_cycle)
+
+Support for more providers. Missing a provider or LLM Platform, raise a [feature request](https://github.com/BerriAI/litellm/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BFeature%5D%3A+).
+
+### Deploy on AWS or GCP with Terraform
+
+Run the LiteLLM proxy as a production-ready componentized stack (gateway, backend, UI on separate services; managed Postgres + Redis + object store) using the published Terraform modules. Both modules are on the [public Terraform Registry](https://registry.terraform.io/namespaces/BerriAI) — no auth needed.
+
+#### AWS — ECS Fargate + Aurora + ElastiCache + ALB
+
+[![Launch in AWS CloudShell](https://img.shields.io/badge/Launch-AWS_CloudShell-FF9900?logo=amazon-aws&logoColor=white)](https://console.aws.amazon.com/cloudshell/home) — opens an in-browser shell, already authenticated to your AWS account. Once inside, run:
+
+```bash
+git clone https://github.com/BerriAI/litellm.git
+cd litellm/terraform/litellm/aws/examples/default
+cp terraform.tfvars.example terraform.tfvars   # edit region/tenant/env
+terraform init && terraform apply
+```
+
+[Module page →](https://registry.terraform.io/modules/BerriAI/litellm/aws/latest)
+
+Or call the module from your own root config:
+
+```hcl
+# main.tf
+terraform {
+  required_version = ">= 1.6.0"
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.60" }
+  }
+}
+
+provider "aws" {
+  region = "us-west-2"
+}
+
+module "litellm" {
+  source  = "BerriAI/litellm/aws"
+  version = "~> 1.89"
+
+  region = "us-west-2"
+  azs    = ["us-west-2a", "us-west-2b"]
+  tenant = "acme"
+  env    = "prod"
+
+  # Production: provide an ACM cert. Without one, set allow_plaintext_alb = true
+  # (dev/trial only).
+  # acm_certificate_arn = "arn:aws:acm:us-west-2:111122223333:certificate/..."
+  allow_plaintext_alb = true
+}
+
+output "litellm_url" {
+  value = module.litellm.alb_dns_name
+}
+```
+
+```bash
+terraform init
+terraform apply
+```
+
+Provider API keys live in AWS Secrets Manager; reference ARNs via `gateway_extra_secrets`. Full input list and architecture diagram on the [registry page](https://registry.terraform.io/modules/BerriAI/litellm/aws/latest?tab=inputs).
+
+#### GCP — Cloud Run + Cloud SQL + Memorystore + HTTPS LB
+
+[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.png)](https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2FBerriAI%2Flitellm&cloudshell_workspace=terraform%2Flitellm%2Fgcp%2Fexamples%2Fdefault&cloudshell_tutorial=TUTORIAL.md&cloudshell_image=gcr.io/ds-artifacts-cloudshell/deploystack_custom_image&shellonly=true)
+
+Real 1-click. Opens Cloud Shell, clones this repo, and walks you through `terraform apply` via a built-in [DeployStack tutorial](./terraform/litellm/gcp/examples/default/TUTORIAL.md) — pick the project, the tutorial sets up the Artifact Registry remote repo, writes `terraform.tfvars` from your answers, and runs apply.
+
+[Module page →](https://registry.terraform.io/modules/BerriAI/litellm/google/latest)
+
+To call the module from your own config instead, Cloud Run can't pull from `ghcr.io` directly, so first set up a one-time Artifact Registry remote repo backed by GHCR:
+
+```bash
+gcloud artifacts repositories create litellm \
+  --location=us-central1 \
+  --repository-format=docker \
+  --mode=remote-repository \
+  --remote-docker-repo=https://ghcr.io \
+  --project=my-gcp-project
+```
+
+Then:
+
+```hcl
+# main.tf
+terraform {
+  required_version = ">= 1.6.0"
+  required_providers {
+    google      = { source = "hashicorp/google",      version = "~> 6.10" }
+    google-beta = { source = "hashicorp/google-beta", version = "~> 6.10" }
+  }
+}
+
+provider "google"      { project = "my-gcp-project"; region = "us-central1" }
+provider "google-beta" { project = "my-gcp-project"; region = "us-central1" }
+
+module "litellm" {
+  source  = "BerriAI/litellm/google"
+  version = "~> 1.89"
+
+  project_id = "my-gcp-project"
+  region     = "us-central1"
+  tenant     = "acme"
+  env        = "prod"
+
+  # Replace my-gcp-project with your GCP project ID (same value as project_id above).
+  image_registry = "us-central1-docker.pkg.dev/my-gcp-project/litellm/berriai"
+
+  # Production: provide DNS already pointing at the LB IP for Google-managed certs.
+  # Without one, set allow_plaintext_lb = true (dev/trial only).
+  # lb_domains         = ["proxy.example.com"]
+  allow_plaintext_lb = true
+}
+
+output "litellm_url" {
+  value = module.litellm.load_balancer_url
+}
+```
+
+```bash
+terraform init
+terraform apply
+```
+
+Provider API keys live in Secret Manager; reference resource IDs (e.g. `projects/my-gcp-project/secrets/openai-api-key`) via `gateway_extra_secrets`. Full input list and architecture diagram on the [registry page](https://registry.terraform.io/modules/BerriAI/litellm/google/latest?tab=inputs).
+
+#### Both stacks include
+
+- The full componentized split (gateway / backend / UI as independent services)
+- Managed Postgres (writer + reader) and Redis
+- Versioned object store for proxy state + file uploads
+- An auto-generated `LITELLM_MASTER_KEY` in your cloud's secret manager
+- A one-off migration job that runs `prisma migrate deploy` before the proxy starts
+- The same `proxy_config` surface as the [Helm chart](./helm/litellm/) — pass YAML as a typed map
+
+The Terraform modules live at [`terraform/litellm/aws/`](./terraform/litellm/aws/) and [`terraform/litellm/gcp/`](./terraform/litellm/gcp/) in this repo; the registry entries are read-only mirrors updated on each release.
+
+### Run in Developer Mode
+#### Services
+1. Setup .env file in root
+2. Run dependent services `docker-compose up db prometheus`
+
+#### Backend
 1. (In root) create virtual environment `python -m venv .venv`
 2. Activate virtual environment `source .venv/bin/activate`
-3. Install dependencies `pip install -e ".[all]"`
-4. `pip install prisma`
+3. Install dependencies `uv sync --all-extras --group proxy-dev`
+4. `uv run prisma generate`
 5. `prisma generate`
 6. Start proxy backend `python litellm/proxy/proxy_cli.py`
 
-### Frontend
+#### Frontend
 1. Navigate to `ui/litellm-dashboard`
 2. Install dependencies `npm install`
 3. Run `npm run dev` to start the dashboard
 
+### Verify Docker Image Signatures
+
+All LiteLLM Docker images published to GHCR are signed with [cosign](https://docs.sigstore.dev/cosign/overview/). Every release is signed with the same key introduced in [commit `0112e53`](https://github.com/BerriAI/litellm/commit/0112e53046018d726492c814b3644b7d376029d0).
+
+**Verify using the pinned commit hash (recommended):**
+
+A commit hash is cryptographically immutable, so this is the strongest way to ensure you are using the original signing key:
+
+```bash
+cosign verify \
+  --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
+  ghcr.io/berriai/litellm:<release-tag>
+```
+
+**Verify using a release tag (convenience):**
+
+Tags are protected in this repository and resolve to the same key. This option is easier to read but relies on tag protection rules:
+
+```bash
+cosign verify \
+  --key https://raw.githubusercontent.com/BerriAI/litellm/<release-tag>/cosign.pub \
+  ghcr.io/berriai/litellm:<release-tag>
+```
+
+Replace `<release-tag>` with the version you are deploying (e.g. `v1.83.0-stable`).
+
+---
+
 # Enterprise
 For companies that need better security, user management and professional support
 
@@ -424,7 +606,7 @@ We welcome contributions to LiteLLM! Whether you're fixing bugs, adding features
 
 ## Quick Start for Contributors
 
-This requires poetry to be installed.
+This requires uv to be installed.
 
 ```bash
 git clone https://github.com/BerriAI/litellm.git
@@ -438,6 +620,8 @@ make format-check   # Check formatting only
 
 For detailed contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
+> **📖 Contributing to documentation?** The LiteLLM docs have moved to a separate repository: [BerriAI/litellm-docs](https://github.com/BerriAI/litellm-docs). Please open doc PRs there. Docs are served at [docs.litellm.ai](https://docs.litellm.ai).
+
 ## Code Quality / Linting
 
 LiteLLM follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html).
@@ -460,10 +644,6 @@ All these checks must pass before your PR can be merged.
 - [Community Slack 💭](https://www.litellm.ai/support)
 - Our emails ✉️ ishaan@berri.ai / krrish@berri.ai
 
-# Why did we build this
-
-- **Need for simplicity**: Our code started to get extremely complicated managing & translating calls between Azure, OpenAI and Cohere.
-
 # Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
@@ -478,4 +658,3 @@ All these checks must pass before your PR can be merged.
 <a href="https://github.com/BerriAI/litellm/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=BerriAI/litellm" />
 </a>
-

backend/Dockerfile

@@ -0,0 +1,97 @@
+ARG LITELLM_BUILD_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:c61ac6919b811ea53c4782d69f1fe05218ba3c25d53f01b6ab7892e621bd4370
+ARG LITELLM_RUNTIME_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:c61ac6919b811ea53c4782d69f1fe05218ba3c25d53f01b6ab7892e621bd4370
+ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85ab0f263ef12f492d8476aa3a2e4e1e333f7d67fbdd923d00a506a516a
+
+FROM $UV_IMAGE AS uvbin
+
+# ---------- Builder ----------
+FROM $LITELLM_BUILD_IMAGE AS builder
+
+WORKDIR /app
+USER root
+
+COPY --from=uvbin /uv /uvx /usr/local/bin/
+
+# nodejs/npm so `prisma generate` uses Wolfi's Node via PRISMA_USE_GLOBAL_NODE
+# instead of nodeenv downloading one whose dynamic deps may not be in Wolfi
+# (e.g. Node 26.2.0 needs libatomic). Retry for transient apk.cgr.dev flakes.
+RUN for i in 1 2 3; do \
+      apk add --no-cache bash gcc python3 python3-dev openssl openssl-dev libsndfile nodejs npm && break; \
+      [ $i = 3 ] && { echo "apk add failed after 3 retries" >&2; exit 1; }; \
+      sleep 5; \
+    done
+
+# UV_COMPILE_BYTECODE=1   precompiles .pyc at install time → faster cold start.
+# UV_LINK_MODE=copy       avoids hardlink warnings when uv installs from a
+#                         BuildKit cache mount (different filesystem).
+# UV_PYTHON_DOWNLOADS=0   force uv to use the apk-installed CPython instead of
+#                         silently pulling a managed interpreter.
+# PRISMA_USE_GLOBAL_NODE  explicit (matches default) so an env override can't
+#                         silently re-enable nodeenv's Node download.
+ENV UV_PROJECT_ENVIRONMENT=/app/.venv \
+    UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    UV_PYTHON_DOWNLOADS=0 \
+    PRISMA_USE_GLOBAL_NODE=true \
+    PATH="/app/.venv/bin:${PATH}"
+
+# Stage 1 — install dependencies only.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=enterprise/pyproject.toml,target=enterprise/pyproject.toml \
+    --mount=type=bind,source=litellm-proxy-extras/pyproject.toml,target=litellm-proxy-extras/pyproject.toml \
+    uv sync --frozen --no-install-project --no-install-workspace --no-default-groups --no-editable \
+        --extra proxy \
+        --extra proxy-runtime \
+        --extra extra_proxy \
+        --extra semantic-router \
+        --python python3
+
+# Stage 2 — copy source and install the project + workspace members.
+COPY . .
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-default-groups --no-editable \
+        --extra proxy \
+        --extra proxy-runtime \
+        --extra extra_proxy \
+        --extra semantic-router \
+        --python python3
+
+RUN mkdir -p /home/nonroot && \
+    HOME=/home/nonroot prisma generate --schema=./schema.prisma && \
+    chown -R nonroot:nonroot /home/nonroot/.cache
+
+# ---------- Runtime ----------
+FROM $LITELLM_RUNTIME_IMAGE AS runtime
+
+USER root
+
+RUN for i in 1 2 3; do \
+      apk add --no-cache bash openssl tzdata python3 libsndfile libatomic && break; \
+      [ $i = 3 ] && { echo "apk add failed after 3 retries" >&2; exit 1; }; \
+      sleep 5; \
+    done
+
+# wolfi-base ships an unprivileged `nonroot` account (UID/GID 65532) with
+# /home/nonroot. We run the backend as that user
+WORKDIR /app
+ENV HOME=/home/nonroot \
+    PATH="/app/.venv/bin:${PATH}" \
+    PYTHONPATH="/app" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+COPY --from=builder --chown=nonroot:nonroot /app /app
+COPY --from=builder --chown=nonroot:nonroot /home/nonroot/.cache /home/nonroot/.cache
+
+RUN find /app/.venv -type f -path "*/tornado/test/*" -delete && \
+    find /app/.venv -type d -path "*/tornado/test" -delete
+
+USER nonroot
+
+EXPOSE 4001/tcp
+
+ENTRYPOINT ["uvicorn", "backend.main:app"]
+CMD ["--host", "0.0.0.0", "--port", "4001"]

backend/main.py

@@ -0,0 +1,56 @@
+"""UI backend entrypoint.
+
+Reuses the existing FastAPI app from `litellm.proxy.proxy_server` and trims its
+route table to just the management/admin surface used by the dashboard. Purely
+additive — no existing module is modified.
+
+Run with:
+    uvicorn backend.main:app --host 0.0.0.0 --port 4001
+"""
+
+from contextlib import asynccontextmanager
+
+from fastapi.routing import Mount
+
+# See gateway/main.py for why we assemble DATABASE_URL(s) here before
+# importing proxy_server.
+from litellm.proxy.db.db_url_settings import DatabaseURLSettings
+
+DatabaseURLSettings.from_env().apply_to_env()
+
+from litellm.proxy.proxy_server import app
+
+from backend.routes.allowlist import (
+    BACKEND_EXACT_PATHS,
+    BACKEND_MOUNT_PATHS,
+    BACKEND_PATH_PREFIXES,
+)
+
+
+def _is_backend_route(route) -> bool:
+    """Keep the route on the backend if its path is in the management surface."""
+    path = getattr(route, "path", None)
+    if path is None:
+        return False
+    if isinstance(route, Mount):
+        # The dashboard UI static mounts are served by the dedicated UI container.
+        # Only Mounts in the backend allowlist (e.g. swagger docs) remain on backend.
+        return path in BACKEND_MOUNT_PATHS
+    if path in BACKEND_EXACT_PATHS:
+        return True
+    return any(path.startswith(prefix) for prefix in BACKEND_PATH_PREFIXES)
+
+
+# See gateway/main.py for why the trim runs inside the lifespan instead of at
+# module scope.
+_proxy_lifespan = app.router.lifespan_context
+
+
+@asynccontextmanager
+async def _backend_lifespan(app_):
+    async with _proxy_lifespan(app_):
+        app_.router.routes = [r for r in app_.router.routes if _is_backend_route(r)]
+        yield
+
+
+app.router.lifespan_context = _backend_lifespan

backend/routes/allowlist.py

@@ -0,0 +1,144 @@
+"""Path allowlist for the UI backend (control plane) component.
+
+The backend exposes management/admin endpoints consumed by the UI: keys, users,
+teams, orgs, customers, budgets, tags, workflows, model management, spend &
+analytics, settings (router/cache/cost-tracking/fallbacks), SSO/onboarding,
+audit logs, debug, enterprise admin, and UI bootstrap helpers (logo, favicon,
+.well-known config).
+
+Anything LLM data-plane is dropped — those run on the gateway component.
+"""
+
+BACKEND_PATH_PREFIXES: tuple[str, ...] = (
+    # Identity / access
+    "/key/",
+    "/v2/key/",
+    "/user/",
+    "/v2/user/",
+    "/team/",
+    "/v2/team/",
+    "/organization/",
+    "/customer/",
+    "/end_user/",
+    "/sso/",
+    "/login",
+    "/v2/login",
+    "/v3/login",
+    "/logout",
+    "/token",
+    "/onboarding/",
+    "/audit",
+    "/oauth/",
+    "/invitation/",
+    "/jwt/",
+    # Models & routing config
+    "/model/",
+    "/v1/model/info",
+    "/v2/model/",
+    "/model_group",
+    "/model_access_group/",
+    "/model_hub/",
+    "/v1/access_group",
+    "/access_group/",
+    "/router/",
+    "/router_settings",
+    "/adaptive_router/",
+    "/fallback",
+    "/fallbacks",
+    "/cache_settings",
+    "/cost_tracking",
+    "/cost/",
+    "/credentials",
+    "/credential",
+    "/provider/budgets",
+    # Tools / agents (registry & policy admin)
+    "/v1/tool/",
+    "/v1/agents",
+    # Guardrails admin
+    "/v2/guardrails/",
+    # MCP server admin + BYOK OAuth flow (UI-initiated) + dynamic per-server endpoints
+    "/v1/mcp/",
+    "/test/",
+    "/{mcp_server_name}/",
+    # Budgets / tags / workflows / memory mgmt
+    "/budget/",
+    "/tag/",
+    "/workflow/",
+    "/v1/workflows/",
+    "/project/",
+    "/memory/",
+    "/mcp/",
+    # Spend / analytics
+    "/spend/",
+    "/analytics/",
+    "/global/",
+    "/user_agent",
+    "/usage/",
+    "/daily/",
+    # CloudZero cost-export admin (init / settings / export / dry-run / delete)
+    "/cloudzero/",
+    # Caching admin
+    "/cache/",
+    "/caching/",
+    # Callbacks / hooks
+    "/active/callbacks",
+    "/callbacks",
+    "/team_callback",
+    # Alerting / email / IP allowlist
+    "/alerting/",
+    "/email/",
+    "/add/allowed_ip",
+    "/delete/allowed_ip",
+    "/get/",
+    # Enterprise admin
+    "/enterprise/",
+    # Debug / config / profiling
+    "/debug/",
+    "/config/",
+    "/memory-usage-in-mem-cache",
+    "/otel-spans",
+    "/lazy/",
+    "/in_product_nudges",
+    # Admin reload / schedule
+    "/reload/",
+    "/schedule/",
+    "/settings",
+    "/update/",
+    "/upload/",
+    # Dev / admin utilities
+    "/utils/",
+    # UI bootstrap helpers (assets the dashboard fetches)
+    "/get_logo_url",
+    "/get_image",
+    "/get_favicon",
+    "/.well-known/",
+    "/litellm/.well-known/",
+    "/ui_discovery/",
+    "/ui-config",
+    "/sso_settings",
+    "/public/",
+    "/robots.txt",
+    # Health (k8s probes)
+    "/health",
+    # Plugin system
+    "/api/plugins",
+    "/plugin-proxy/",
+)
+
+BACKEND_EXACT_PATHS: frozenset[str] = frozenset(
+    {
+        "/",
+        "/routes",
+        "/openapi.json",
+        "/docs",
+        "/docs/oauth2-redirect",
+        "/redoc",
+        "/fallback/login",
+    }
+)
+
+BACKEND_MOUNT_PATHS: frozenset[str] = frozenset(
+    {
+        "/swagger",  # API documentation static assets belong to the backend
+    }
+)

basedpyright-code-budget.json

@@ -0,0 +1,194 @@
+{
+  "reportAny": {
+    "baseline": 24989,
+    "slack": 2500
+  },
+  "reportArgumentType": {
+    "baseline": 1934,
+    "slack": 180
+  },
+  "reportAssignmentType": {
+    "baseline": 220,
+    "slack": 22
+  },
+  "reportAttributeAccessIssue": {
+    "baseline": 346,
+    "slack": 35
+  },
+  "reportCallIssue": {
+    "baseline": 87,
+    "slack": 10
+  },
+  "reportConstantRedefinition": {
+    "baseline": 39,
+    "slack": 4
+  },
+  "reportDeprecated": {
+    "baseline": 217,
+    "slack": 22
+  },
+  "reportDuplicateImport": {
+    "baseline": 28,
+    "slack": 3
+  },
+  "reportExplicitAny": {
+    "baseline": 6931,
+    "slack": 700
+  },
+  "reportFunctionMemberAccess": {
+    "baseline": 7,
+    "slack": 3
+  },
+  "reportGeneralTypeIssues": {
+    "baseline": 151,
+    "slack": 15
+  },
+  "reportIncompatibleMethodOverride": {
+    "baseline": 52,
+    "slack": 5
+  },
+  "reportIncompatibleVariableOverride": {
+    "baseline": 8,
+    "slack": 3
+  },
+  "reportInconsistentOverload": {
+    "baseline": 12,
+    "slack": 3
+  },
+  "reportIndexIssue": {
+    "baseline": 26,
+    "slack": 3
+  },
+  "reportInvalidTypeForm": {
+    "baseline": 23,
+    "slack": 3
+  },
+  "reportInvalidTypeVarUse": {
+    "baseline": 2,
+    "slack": 3
+  },
+  "reportMatchNotExhaustive": {
+    "baseline": 1,
+    "slack": 3
+  },
+  "reportMissingParameterType": {
+    "baseline": 3933,
+    "slack": 390
+  },
+  "reportMissingTypeArgument": {
+    "baseline": 10612,
+    "slack": 1000
+  },
+  "reportMissingTypeStubs": {
+    "baseline": 27,
+    "slack": 10
+  },
+  "reportOperatorIssue": {
+    "baseline": 6,
+    "slack": 3
+  },
+  "reportOptionalCall": {
+    "baseline": 4,
+    "slack": 3
+  },
+  "reportOptionalIterable": {
+    "baseline": 3,
+    "slack": 3
+  },
+  "reportOptionalMemberAccess": {
+    "baseline": 724,
+    "slack": 72
+  },
+  "reportOptionalOperand": {
+    "baseline": 3,
+    "slack": 3
+  },
+  "reportOptionalSubscript": {
+    "baseline": 11,
+    "slack": 3
+  },
+  "reportPossiblyUnboundVariable": {
+    "baseline": 52,
+    "slack": 10
+  },
+  "reportPrivateUsage": {
+    "baseline": 1625,
+    "slack": 160
+  },
+  "reportRedeclaration": {
+    "baseline": 8,
+    "slack": 3
+  },
+  "reportReturnType": {
+    "baseline": 126,
+    "slack": 100
+  },
+  "reportTypedDictNotRequiredAccess": {
+    "baseline": 20,
+    "slack": 3
+  },
+  "reportUndefinedVariable": {
+    "baseline": 2,
+    "slack": 3
+  },
+  "reportUnknownArgumentType": {
+    "baseline": 30603,
+    "slack": 3000
+  },
+  "reportUnknownLambdaType": {
+    "baseline": 75,
+    "slack": 10
+  },
+  "reportUnknownMemberType": {
+    "baseline": 27037,
+    "slack": 2500
+  },
+  "reportUnknownParameterType": {
+    "baseline": 13612,
+    "slack": 1000
+  },
+  "reportUnknownVariableType": {
+    "baseline": 21445,
+    "slack": 2000
+  },
+  "reportUnnecessaryCast": {
+    "baseline": 118,
+    "slack": 10
+  },
+  "reportUnnecessaryComparison": {
+    "baseline": 683,
+    "slack": 100
+  },
+  "reportUnnecessaryContains": {
+    "baseline": 4,
+    "slack": 3
+  },
+  "reportUnnecessaryIsInstance": {
+    "baseline": 808,
+    "slack": 80
+  },
+  "reportUntypedBaseClass": {
+    "baseline": 110,
+    "slack": 11
+  },
+  "reportUntypedFunctionDecorator": {
+    "baseline": 22,
+    "slack": 3
+  },
+  "reportUnusedClass": {
+    "baseline": 22,
+    "slack": 3
+  },
+  "reportUnusedFunction": {
+    "baseline": 137,
+    "slack": 10
+  },
+  "reportUnusedImport": {
+    "baseline": 670,
+    "slack": 50
+  },
+  "reportUnusedVariable": {
+    "baseline": 865,
+    "slack": 50
+  }
+}

ci_cd/run_migration.py

@@ -1,23 +1,234 @@
+import argparse
 import os
-import subprocess
-from pathlib import Path
-from datetime import datetime
-import testing.postgresql
+import re
 import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import testing.postgresql
 
 
-def create_migration(migration_name: str = None):
+DESTRUCTIVE_PATTERN = re.compile(r"\bDROP\s+(COLUMN|TABLE|INDEX)\b", re.IGNORECASE)
+DEFAULT_BASE_BRANCH = "litellm_internal_staging"
+
+
+def _find_destructive_statements(sql: str) -> list:
+    """Return SQL lines containing DROP COLUMN, DROP TABLE, or DROP INDEX."""
+    return [
+        line.strip() for line in sql.splitlines() if DESTRUCTIVE_PATTERN.search(line)
+    ]
+
+
+def _print_freshness_failure(
+    base_branch: str, reason: str, stderr_text: str = ""
+) -> None:
+    """Loudly refuse to run when the freshness check can't be completed."""
+    banner = "=" * 72
+    out = sys.stderr
+    print(banner, file=out)
+    print(f"  FRESHNESS CHECK FAILED — COULD NOT VERIFY origin/{base_branch}", file=out)
+    print(banner, file=out)
+    print("", file=out)
+    print(f"Reason: {reason}", file=out)
+    if stderr_text:
+        print("", file=out)
+        print("git stderr:", file=out)
+        for line in stderr_text.rstrip().splitlines():
+            print(f"    {line}", file=out)
+    print("", file=out)
+    print("Common causes:", file=out)
+    print("  - No network access (offline)", file=out)
+    print("  - 'origin' remote not configured, or base branch name is wrong", file=out)
+    print("  - Not a git repository", file=out)
+    print("", file=out)
+    print("Options:", file=out)
+    print(
+        f"  - Fix the above and re-run, OR pass --base-branch <name> if your", file=out
+    )
+    print(
+        f"    base branch is not '{base_branch}', OR pass --skip-freshness-check",
+        file=out,
+    )
+    print("    to bypass (only if you fully understand the risk).", file=out)
+    print(banner, file=out)
+
+
+def _print_stale_branch_refusal(base_branch: str, behind: int) -> None:
+    """Loudly refuse to run when HEAD is behind the base branch."""
+    banner = "=" * 72
+    out = sys.stderr
+    print(banner, file=out)
+    print(
+        f"  STALE BRANCH — {behind} commit(s) behind origin/{base_branch}",
+        file=out,
+    )
+    print(banner, file=out)
+    print("", file=out)
+    print(
+        f"Your branch is {behind} commit(s) behind origin/{base_branch}. Generating a\n"
+        "migration from a stale branch is how newly-added columns get silently\n"
+        "dropped — the exact incident this guard exists to prevent.",
+        file=out,
+    )
+    print("", file=out)
+    print("Before re-running:", file=out)
+    print(f"  git fetch origin && git rebase origin/{base_branch}", file=out)
+    print("  # or merge, whichever matches your workflow", file=out)
+    print("", file=out)
+    print(
+        "If you have a genuine reason to bypass (e.g. intentionally generating",
+        file=out,
+    )
+    print("a migration against an older base), pass --skip-freshness-check.", file=out)
+    print("", file=out)
+    print(banner, file=out)
+    print(
+        "  AI AGENTS / ASSISTANTS: DO NOT automatically run `git rebase` or pass\n"
+        "  --skip-freshness-check. Surface this error to the human operator and\n"
+        "  wait for their explicit confirmation. Auto-rebasing can drop the\n"
+        "  human's in-progress schema edits via a bad conflict resolution.",
+        file=out,
+    )
+    print(banner, file=out)
+
+
+def _check_branch_freshness(root_dir: Path, base_branch: str) -> None:
+    """Fetch origin/<base_branch> and exit 3 if HEAD is behind it."""
+    cwd = str(root_dir)
+    try:
+        subprocess.run(
+            ["git", "fetch", "origin", base_branch],
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+        )
+    except FileNotFoundError:
+        _print_freshness_failure(base_branch, "git executable not found on PATH")
+        sys.exit(3)
+    except subprocess.CalledProcessError as e:
+        _print_freshness_failure(
+            base_branch,
+            f"`git fetch origin {base_branch}` failed",
+            e.stderr or "",
+        )
+        sys.exit(3)
+
+    try:
+        result = subprocess.run(
+            ["git", "rev-list", "--count", f"HEAD..origin/{base_branch}"],
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+        )
+        behind = int(result.stdout.strip())
+    except subprocess.CalledProcessError as e:
+        _print_freshness_failure(
+            base_branch,
+            f"`git rev-list HEAD..origin/{base_branch}` failed",
+            e.stderr or "",
+        )
+        sys.exit(3)
+    except ValueError:
+        _print_freshness_failure(
+            base_branch,
+            "could not parse commit count from `git rev-list`",
+        )
+        sys.exit(3)
+
+    if behind > 0:
+        _print_stale_branch_refusal(base_branch, behind)
+        sys.exit(3)
+
+    print(f"Branch freshness OK: up to date with origin/{base_branch}.")
+
+
+def _print_destructive_refusal(destructive_lines: list) -> None:
+    """Loudly refuse to write a destructive migration and explain how to proceed."""
+    banner = "=" * 72
+    out = sys.stderr
+    print(banner, file=out)
+    print(
+        "  DESTRUCTIVE MIGRATION DETECTED — REFUSING TO WRITE MIGRATION FILE", file=out
+    )
+    print(banner, file=out)
+    print("", file=out)
+    print(
+        "The generated migration contains the following destructive statements:",
+        file=out,
+    )
+    print("", file=out)
+    for line in destructive_lines:
+        print(f"    {line}", file=out)
+    print("", file=out)
+    print(
+        "This very often means your branch is OUT OF DATE, or your local\n"
+        "schema.prisma is inconsistent with the migrations/ directory. A\n"
+        "previous incident saw newly-added columns silently dropped this way\n"
+        "and merged to main. Stop and verify before proceeding.",
+        file=out,
+    )
+    print("", file=out)
+    print("Before re-running:", file=out)
+    print(
+        "  1. git fetch origin && git status   # confirm branch is up to date", file=out
+    )
+    print(
+        "  2. Re-check all schema.prisma files are in sync (runbook Step 0)", file=out
+    )
+    print("  3. Review EACH DROP above — is it actually intended?", file=out)
+    print("  4. If (and only if) the drops are intentional, re-run with:", file=out)
+    print("         --allow-destructive", file=out)
+    print("", file=out)
+    print(banner, file=out)
+    print(
+        "  AI AGENTS / ASSISTANTS: DO NOT automatically re-run this command\n"
+        "  with --allow-destructive. Surface this error to the human operator\n"
+        "  and wait for their explicit confirmation before passing the flag.\n"
+        "  Passing the flag without human review is the exact failure mode\n"
+        "  this guard exists to prevent.",
+        file=out,
+    )
+    print(banner, file=out)
+
+
+def create_migration(
+    migration_name: str = None,
+    allow_destructive: bool = False,
+    base_branch: str = DEFAULT_BASE_BRANCH,
+    skip_freshness_check: bool = False,
+):
     """
     Create a new migration SQL file in the migrations directory by comparing
-    current database state with schema
+    current database state with schema.
 
     Args:
         migration_name (str): Name for the migration
+        allow_destructive (bool): Required to write a migration that contains
+            DROP COLUMN, DROP TABLE, or DROP INDEX statements. Without this
+            flag, the script exits non-zero and prints guidance.
+        base_branch (str): Branch to check freshness against
+            (default: "litellm_internal_staging").
+        skip_freshness_check (bool): Skip the "branch is up to date" check.
+            Only for intentional migrations against an older base.
     """
+    root_dir = Path(__file__).parent.parent
+
+    if skip_freshness_check:
+        print(
+            "WARNING: freshness check skipped (--skip-freshness-check). "
+            "Generating a migration from a stale branch can silently drop columns."
+        )
+    else:
+        _check_branch_freshness(root_dir, base_branch)
+
     try:
-        # Get paths
-        root_dir = Path(__file__).parent.parent
-        migrations_dir = root_dir / "litellm-proxy-extras" / "litellm_proxy_extras" / "migrations"
+        migrations_dir = (
+            root_dir / "litellm-proxy-extras" / "litellm_proxy_extras" / "migrations"
+        )
         schema_path = root_dir / "schema.prisma"
 
         # Create temporary PostgreSQL database
@@ -57,7 +268,27 @@ def create_migration(migration_name: str = None):
                     check=True,
                 )
 
-                if result.stdout.strip():
+                # Prisma emits the literal "-- This is an empty migration." when
+                # there's no real drift. Treat that as "no changes".
+                diff_sql = result.stdout
+                stripped = diff_sql.strip()
+                is_empty_diff = (
+                    not stripped or stripped == "-- This is an empty migration."
+                )
+
+                if not is_empty_diff:
+                    destructive_lines = _find_destructive_statements(diff_sql)
+                    if destructive_lines and not allow_destructive:
+                        _print_destructive_refusal(destructive_lines)
+                        sys.exit(2)
+                    if destructive_lines and allow_destructive:
+                        print(
+                            "WARNING: writing destructive migration "
+                            "(--allow-destructive passed). Statements:"
+                        )
+                        for line in destructive_lines:
+                            print(f"    {line}")
+
                     # Generate timestamp and create migration directory
                     timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
                     migration_name = migration_name or "unnamed_migration"
@@ -66,7 +297,7 @@ def create_migration(migration_name: str = None):
 
                     # Write the SQL to migration.sql
                     migration_file = migration_dir / "migration.sql"
-                    migration_file.write_text(result.stdout)
+                    migration_file.write_text(diff_sql)
 
                     print(f"Created migration in {migration_dir}")
                     return True
@@ -88,8 +319,48 @@ def create_migration(migration_name: str = None):
 
 
 if __name__ == "__main__":
-    # If running directly, can optionally pass migration name as argument
-    import sys
-
-    migration_name = sys.argv[1] if len(sys.argv) > 1 else None
-    create_migration(migration_name)
+    parser = argparse.ArgumentParser(
+        description=(
+            "Generate a Prisma migration by diffing the temp DB "
+            "(existing migrations applied) against schema.prisma."
+        )
+    )
+    parser.add_argument(
+        "migration_name",
+        nargs="?",
+        default=None,
+        help="Name for the migration (used in the generated directory name).",
+    )
+    parser.add_argument(
+        "--allow-destructive",
+        action="store_true",
+        help=(
+            "Required to write a migration that contains DROP COLUMN, "
+            "DROP TABLE, or DROP INDEX. Without this flag, destructive "
+            "diffs are refused."
+        ),
+    )
+    parser.add_argument(
+        "--base-branch",
+        default=DEFAULT_BASE_BRANCH,
+        help=(
+            f"Branch to check freshness against (default: {DEFAULT_BASE_BRANCH}). "
+            "The script fetches origin/<base-branch> and refuses to run if HEAD "
+            "is behind it."
+        ),
+    )
+    parser.add_argument(
+        "--skip-freshness-check",
+        action="store_true",
+        help=(
+            "Bypass the 'branch is up to date' check. Only for intentional "
+            "migrations against an older base. Pairs poorly with automation."
+        ),
+    )
+    args = parser.parse_args()
+    create_migration(
+        args.migration_name,
+        allow_destructive=args.allow_destructive,
+        base_branch=args.base_branch,
+        skip_freshness_check=args.skip_freshness_check,
+    )

codecov.yaml

@@ -1,3 +1,18 @@
+codecov:
+  require_ci_to_pass: false # post coverage status even if CI has unrelated failures
+  notify:
+    wait_for_ci: false # post as soon as expected uploads arrive, don't wait on CI
+
+# Uploads are flagged per workflow/shard (GHA) or "circleci". carryforward makes
+# a re-upload of a flag replace its prior session instead of accumulating a
+# conflicting one, and lets a commit reuse a flag from its parent when that flag
+# was not re-uploaded. Required because the same commit can receive the
+# push-triggered workflows more than once (re-runs / branches cut at the same
+# SHA); flagless overlapping sessions made Codecov drop the largest files.
+flag_management:
+  default_rules:
+    carryforward: true
+
 component_management:
   individual_components:
     - component_id: "Router"
@@ -20,6 +35,22 @@ component_management:
     - component_id: "Enterprise"
       paths:
         - "enterprise/**"
+    - component_id: "Batches"
+      paths:
+        - "*/proxy/batches_endpoints/**"
+        - "litellm/batches/**"
+        - "*/llms/*/batches/**"
+    - component_id: "Videos"
+      paths:
+        - "litellm/videos/**"
+        - "*/proxy/video_endpoints/**"
+        - "*/llms/*/videos/**"
+    - component_id: "Realtime"
+      paths:
+        - "litellm/realtime_api/**"
+        - "*/proxy/realtime_endpoints/**"
+        - "*/llms/*/realtime/**"
+        - "litellm/litellm_core_utils/realtime_streaming.py"
 comment:
   layout: "header, diff, flags, components"  # show component info in the PR comment
 
@@ -28,7 +59,7 @@ coverage:
     project:
       default:
         target: auto
-        threshold: 1% # at maximum allow project coverage to drop by 1%
+        threshold: 0% # do not allow project coverage to drop
     patch:
       default:
         target: auto

cookbook/anthropic_agent_sdk/agent_with_mcp.py

@@ -24,24 +24,26 @@ async def interactive_chat_with_mcp():
     Interactive CLI chat with the agent and MCP server
     """
     config = Config()
-    
+
     # Configure Anthropic SDK to point to LiteLLM gateway
     litellm_base_url = setup_litellm_env(config)
-    
+
     # Fetch available models from proxy
-    available_models = await fetch_available_models(litellm_base_url, config.LITELLM_API_KEY)
-    
+    available_models = await fetch_available_models(
+        litellm_base_url, config.LITELLM_API_KEY
+    )
+
     current_model = config.LITELLM_MODEL
-    
+
     # MCP server configuration
     mcp_server_url = f"{litellm_base_url}/mcp/deepwiki2"
     use_mcp = os.getenv("USE_MCP", "true").lower() == "true"
-    
+
     if not use_mcp:
         print("⚠️  MCP disabled via USE_MCP=false")
-    
+
     print_header(litellm_base_url, current_model, has_mcp=use_mcp)
-    
+
     while True:
         # Configure agent options
         if use_mcp:
@@ -58,7 +60,7 @@ async def interactive_chat_with_mcp():
                             "url": mcp_server_url,
                             "headers": {
                                 "Authorization": f"Bearer {config.LITELLM_API_KEY}"
-                            }
+                            },
                         }
                     },
                 )
@@ -78,12 +80,12 @@ async def interactive_chat_with_mcp():
                 model=current_model,
                 max_turns=50,
             )
-        
+
         # Create agent client
         try:
             async with ClaudeSDKClient(options=options) as client:
                 conversation_active = True
-                
+
                 while conversation_active:
                     # Get user input
                     try:
@@ -91,34 +93,36 @@ async def interactive_chat_with_mcp():
                     except (EOFError, KeyboardInterrupt):
                         print("\n\n👋 Goodbye!")
                         return
-                    
+
                     # Handle commands
-                    if user_input.lower() in ['quit', 'exit']:
+                    if user_input.lower() in ["quit", "exit"]:
                         print("\n👋 Goodbye!")
                         return
-                    
-                    if user_input.lower() == 'clear':
+
+                    if user_input.lower() == "clear":
                         print("\n🔄 Starting new conversation...\n")
                         conversation_active = False
                         continue
-                    
-                    if user_input.lower() == 'models':
+
+                    if user_input.lower() == "models":
                         handle_model_list(available_models, current_model)
                         continue
-                    
-                    if user_input.lower() == 'model':
-                        new_model, should_restart = handle_model_switch(available_models, current_model)
+
+                    if user_input.lower() == "model":
+                        new_model, should_restart = handle_model_switch(
+                            available_models, current_model
+                        )
                         if should_restart:
                             current_model = new_model
                             conversation_active = False
                         continue
-                    
+
                     if not user_input:
                         continue
-                    
+
                     # Stream response from agent
                     await stream_response(client, user_input)
-        
+
         except Exception as e:
             print(f"\n❌ Error creating agent client: {e}")
             print("This might be an MCP configuration issue. Try running without MCP:")

cookbook/anthropic_agent_sdk/common.py

@@ -8,13 +8,13 @@ import httpx
 
 class Config:
     """Configuration for LiteLLM Gateway connection"""
-    
+
     # LiteLLM proxy URL (default to local instance)
     LITELLM_PROXY_URL = os.getenv("LITELLM_PROXY_URL", "http://localhost:4000")
-    
+
     # LiteLLM API key (master key or virtual key)
     LITELLM_API_KEY = os.getenv("LITELLM_API_KEY", "sk-1234")
-    
+
     # Model name as configured in LiteLLM (e.g., "bedrock-claude-sonnet-4", "gpt-4", etc.)
     LITELLM_MODEL = os.getenv("LITELLM_MODEL", "bedrock-claude-sonnet-4.5")
 
@@ -28,7 +28,7 @@ async def fetch_available_models(base_url: str, api_key: str) -> list[str]:
             response = await client.get(
                 f"{base_url}/models",
                 headers={"Authorization": f"Bearer {api_key}"},
-                timeout=10.0
+                timeout=10.0,
             )
             response.raise_for_status()
             data = response.json()
@@ -50,7 +50,7 @@ def setup_litellm_env(config: Config):
     """
     Configure environment variables to point Agent SDK to LiteLLM
     """
-    litellm_base_url = config.LITELLM_PROXY_URL.rstrip('/')
+    litellm_base_url = config.LITELLM_PROXY_URL.rstrip("/")
     os.environ["ANTHROPIC_BASE_URL"] = litellm_base_url
     os.environ["ANTHROPIC_API_KEY"] = config.LITELLM_API_KEY
     return litellm_base_url
@@ -87,10 +87,12 @@ def handle_model_list(available_models: list[str], current_model: str):
         print(f"  {marker} {i}. {model}")
 
 
-def handle_model_switch(available_models: list[str], current_model: str) -> tuple[str, bool]:
+def handle_model_switch(
+    available_models: list[str], current_model: str
+) -> tuple[str, bool]:
     """
     Handle model switching
-    
+
     Returns:
         tuple: (new_model, should_restart_conversation)
     """
@@ -98,7 +100,7 @@ def handle_model_switch(available_models: list[str], current_model: str) -> tupl
     for i, model in enumerate(available_models, 1):
         marker = "✓" if model == current_model else " "
         print(f"  {marker} {i}. {model}")
-    
+
     try:
         choice = input("\nEnter number (or press Enter to cancel): ").strip()
         if choice:
@@ -112,7 +114,7 @@ def handle_model_switch(available_models: list[str], current_model: str) -> tupl
                 print("❌ Invalid choice")
     except (ValueError, IndexError):
         print("❌ Invalid input")
-    
+
     return current_model, False
 
 
@@ -120,41 +122,43 @@ async def stream_response(client, user_input: str):
     """
     Stream response from the agent
     """
-    print("\n🤖 Assistant: ", end='', flush=True)
-    
+    print("\n🤖 Assistant: ", end="", flush=True)
+
     try:
         await client.query(user_input)
-        
+
         # Show loading indicator
-        print("⏳ thinking...", end='', flush=True)
-        
+        print("⏳ thinking...", end="", flush=True)
+
         # Stream the response
         first_chunk = True
         async for msg in client.receive_response():
             # Clear loading indicator on first message
             if first_chunk:
-                print("\r🤖 Assistant: ", end='', flush=True)
+                print("\r🤖 Assistant: ", end="", flush=True)
                 first_chunk = False
-            
+
             # Handle different message types
-            if hasattr(msg, 'type'):
-                if msg.type == 'content_block_delta':
+            if hasattr(msg, "type"):
+                if msg.type == "content_block_delta":
                     # Streaming text delta
-                    if hasattr(msg, 'delta') and hasattr(msg.delta, 'text'):
-                        print(msg.delta.text, end='', flush=True)
-                elif msg.type == 'content_block_start':
+                    if hasattr(msg, "delta") and hasattr(msg.delta, "text"):
+                        print(msg.delta.text, end="", flush=True)
+                elif msg.type == "content_block_start":
                     # Start of content block
-                    if hasattr(msg, 'content_block') and hasattr(msg.content_block, 'text'):
-                        print(msg.content_block.text, end='', flush=True)
-            
+                    if hasattr(msg, "content_block") and hasattr(
+                        msg.content_block, "text"
+                    ):
+                        print(msg.content_block.text, end="", flush=True)
+
             # Fallback to original content handling
-            if hasattr(msg, 'content'):
+            if hasattr(msg, "content"):
                 for content_block in msg.content:
-                    if hasattr(content_block, 'text'):
-                        print(content_block.text, end='', flush=True)
-        
+                    if hasattr(content_block, "text"):
+                        print(content_block.text, end="", flush=True)
+
         print()  # New line after response
-        
+
     except Exception as e:
         print(f"\r\n❌ Error: {e}")
         print("Please check your LiteLLM gateway is running and configured correctly.")

cookbook/anthropic_agent_sdk/main.py

@@ -24,17 +24,19 @@ async def interactive_chat():
     Interactive CLI chat with the agent
     """
     config = Config()
-    
+
     # Configure Anthropic SDK to point to LiteLLM gateway
     litellm_base_url = setup_litellm_env(config)
-    
+
     # Fetch available models from proxy
-    available_models = await fetch_available_models(litellm_base_url, config.LITELLM_API_KEY)
-    
+    available_models = await fetch_available_models(
+        litellm_base_url, config.LITELLM_API_KEY
+    )
+
     current_model = config.LITELLM_MODEL
-    
+
     print_header(litellm_base_url, current_model)
-    
+
     while True:
         # Configure agent options for each conversation
         options = ClaudeAgentOptions(
@@ -42,11 +44,11 @@ async def interactive_chat():
             model=current_model,
             max_turns=50,
         )
-        
+
         # Create agent client
         async with ClaudeSDKClient(options=options) as client:
             conversation_active = True
-            
+
             while conversation_active:
                 # Get user input
                 try:
@@ -54,31 +56,33 @@ async def interactive_chat():
                 except (EOFError, KeyboardInterrupt):
                     print("\n\n👋 Goodbye!")
                     return
-                
+
                 # Handle commands
-                if user_input.lower() in ['quit', 'exit']:
+                if user_input.lower() in ["quit", "exit"]:
                     print("\n👋 Goodbye!")
                     return
-                
-                if user_input.lower() == 'clear':
+
+                if user_input.lower() == "clear":
                     print("\n🔄 Starting new conversation...\n")
                     conversation_active = False
                     continue
-                
-                if user_input.lower() == 'models':
+
+                if user_input.lower() == "models":
                     handle_model_list(available_models, current_model)
                     continue
-                
-                if user_input.lower() == 'model':
-                    new_model, should_restart = handle_model_switch(available_models, current_model)
+
+                if user_input.lower() == "model":
+                    new_model, should_restart = handle_model_switch(
+                        available_models, current_model
+                    )
                     if should_restart:
                         current_model = new_model
                         conversation_active = False
                     continue
-                
+
                 if not user_input:
                     continue
-                
+
                 # Stream response from agent
                 await stream_response(client, user_input)
 

cookbook/gollem_go_agent_framework/go.mod

@@ -1,5 +1,5 @@
 module github.com/BerriAI/litellm/cookbook/gollem_go_agent_framework
 
-go 1.25.1
+go 1.26.3
 
 require github.com/fugue-labs/gollem v0.1.0

cookbook/litellm-ollama-docker-image/requirements.txt

@@ -1 +1 @@
-litellm==1.61.15
+litellm==1.83.14

cookbook/litellm_proxy_server/batch_api/bedrock/bedrock.py

@@ -11,15 +11,15 @@ BEDROCK_BATCH_MODEL = "bedrock/batch-anthropic.claude-3-5-sonnet-20240620-v1:0"
 batch_input_file = client.files.create(
     file=open("./bedrock_batch_completions.jsonl", "rb"),
     purpose="batch",
-    extra_body={"target_model_names": BEDROCK_BATCH_MODEL}
+    extra_body={"target_model_names": BEDROCK_BATCH_MODEL},
 )
 print(batch_input_file)
 
 # Create batch
-batch = client.batches.create( 
+batch = client.batches.create(
     input_file_id=batch_input_file.id,
     endpoint="/v1/chat/completions",
     completion_window="24h",
     metadata={"description": "Test batch job"},
 )
-print(batch)
+print(batch)

cookbook/litellm_proxy_server/cli_token_usage.py

@@ -8,6 +8,7 @@ in your Python scripts after running `litellm-proxy login`.
 
 from textwrap import indent
 import litellm
+
 LITELLM_BASE_URL = "http://localhost:4000/"
 
 
@@ -15,38 +16,38 @@ def main():
     """Using CLI token with LiteLLM SDK"""
     print("🚀 Using CLI Token with LiteLLM SDK")
     print("=" * 40)
-    #litellm._turn_on_debug()
-    
+    # litellm._turn_on_debug()
+
     # Get the CLI token
     api_key = litellm.get_litellm_gateway_api_key()
-    
+
     if not api_key:
         print("❌ No CLI token found. Please run 'litellm-proxy login' first.")
         return
-    
+
     print("✅ Found CLI token.")
 
     available_models = litellm.get_valid_models(
         check_provider_endpoint=True,
         custom_llm_provider="litellm_proxy",
         api_key=api_key,
-        api_base=LITELLM_BASE_URL
+        api_base=LITELLM_BASE_URL,
     )
-    
+
     print("✅ Available models:")
     if available_models:
         for i, model in enumerate(available_models, 1):
             print(f"   {i:2d}. {model}")
     else:
         print("   No models available")
-    
+
     # Use with LiteLLM
     try:
         response = litellm.completion(
             model="litellm_proxy/gemini/gemini-2.5-flash",
             messages=[{"role": "user", "content": "Hello from CLI token!"}],
             api_key=api_key,
-            base_url=LITELLM_BASE_URL
+            base_url=LITELLM_BASE_URL,
         )
         print(f"✅ LLM Response: {response.model_dump_json(indent=4)}")
     except Exception as e:
@@ -55,7 +56,7 @@ def main():
 
 if __name__ == "__main__":
     main()
-    
+
     print("\n💡 Tips:")
     print("1. Run 'litellm-proxy login' to authenticate first")
     print("2. Replace 'https://your-proxy.com' with your actual proxy URL")