Merge main and address Wingback guardrail review feedback

Resolve merge conflicts (Wingback + Decision Model), forward proxy timeout,
drop duplicate apply_guardrail logging, add Guardrail Garden preset, revert
generic guardrail header denylist scope, and compress dashboard logo asset.

Co-authored-by: Cursor <cursoragent@cursor.com>

.circleci/scripts/classify_changes.sh

@@ -1,12 +1,11 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
-category="${1:?usage: classify_changes.sh <backend|client|ui|provider-harness|cost-map-only|mcp-dependencies|windows-release|redis-compat>}"
+category="${1:?usage: classify_changes.sh <backend|client|ui|cost-map-only|mcp-dependencies|windows-release|redis-compat>}"
 
 has_client=false
 has_backend=false
 has_ci=false
-has_provider_harness=false
 has_cost_map=false
 has_mcp_dependencies=false
 has_windows_release=false
@@ -15,7 +14,7 @@ outside_cost_map_set=false
 while IFS= read -r file || [ -n "$file" ]; do
   [ -n "$file" ] || continue
   case "$file" in
-    litellm/_redis.py | litellm/_redis_credential_provider.py | litellm/caching/redis_cache.py | litellm/caching/evicted_client_closer.py | tests/unit/test_redis.py | tests/local_testing/test_caching.py | tests/unit/caching/test_redis_connection_pool.py | tests/unit/caching/test_redis_cluster_cache.py | tests/unit/caching/test_evicted_client_closer.py | .circleci/config.yml | .circleci/scripts/classify_changes.sh | .circleci/scripts/path_filter.sh | pyproject.toml | uv.lock)
+    litellm/_redis.py | litellm/_redis_credential_provider.py | litellm/caching/redis_cache.py | litellm/caching/evicted_client_closer.py | tests/unit/test_redis.py | tests/integration/sdk/test_redis_cluster_iam_auth.py | tests/unit/caching/test_redis_connection_pool.py | tests/unit/caching/test_redis_cluster_cache.py | tests/unit/caching/test_evicted_client_closer.py | .circleci/config.yml | .circleci/scripts/classify_changes.sh | .circleci/scripts/path_filter.sh | pyproject.toml | uv.lock)
       has_redis_compat=true ;;
   esac
   case "$file" in
@@ -23,11 +22,6 @@ while IFS= read -r file || [ -n "$file" ]; do
     pyproject.toml | */pyproject.toml | uv.lock | uv.toml | .python-version | rust-toolchain.toml | litellm-rust/* | litellm/__init__.py | litellm/proxy/proxy_server.py | litellm/*mcp* | tests/*mcp* | litellm/integrations/arize/* | tests/base_sdk_tests/* | scripts/check_mcp_sdk_install.py | .github/workflows/test-mcp-dependency-resolution.yml | .github/actions/detect-changes/* | .github/actions/setup-uv-with-retries/* | .github/actions/cache-cargo-build/* | .github/scripts/detect_changes.sh | .github/scripts/uv_sync_with_retries.sh | .circleci/scripts/classify_changes.sh | tests/unit/test_circleci_path_filter.py | tests/unit/test_detect_changes.py)
       has_mcp_dependencies=true ;;
   esac
-  case "$file" in
-    tests/e2e/*/*.py | tests/e2e_harness/*/*.py) : ;;
-    tests/e2e/*.py | tests/e2e_harness/*.py | tests/code_coverage_tests/test_provider_cache.py | tests/code_coverage_tests/test_provider_replay_harness.py | tests/unit/test_circleci_path_filter.py | .circleci/* | pyproject.toml | uv.lock)
-      has_provider_harness=true ;;
-  esac
   case "$file" in
     litellm-rust/* | litellm/rust_bridge/* | rust-toolchain.toml | pyproject.toml | uv.lock | tests/windows_tests/* | .circleci/*)
       has_windows_release=true ;;
@@ -41,7 +35,7 @@ while IFS= read -r file || [ -n "$file" ]; do
   case "$file" in
     model_prices_and_context_window.json | litellm/model_prices_and_context_window_backup.json | model_prices_and_context_window.schema.json)
       has_cost_map=true ;;
-    tests/test_litellm/* | tests/proxy_unit_tests/* | tests/unit/proxy/*) : ;;
+    tests/unit/proxy/*) : ;;
     *) outside_cost_map_set=true ;;
   esac
 done
@@ -53,9 +47,6 @@ case "$category" in
   cost-map-only)
     { [ "$has_cost_map" = true ] && [ "$outside_cost_map_set" = false ]; } && echo run || echo skip
     ;;
-  provider-harness)
-    [ "$has_provider_harness" = true ] && echo run || echo skip
-    ;;
   windows-release)
     [ "$has_windows_release" = true ] && echo run || echo skip
     ;;

.circleci/scripts/path_filter.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
-category="${1:?usage: path_filter.sh <backend|client|provider-harness|redis-compat>}"
+category="${1:?usage: path_filter.sh <backend|client|redis-compat>}"
 here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 run_full() {

.circleci/scripts/run_integration.sh

@@ -128,12 +128,26 @@ fi
 sudo iptables -L integration_only -n -v -x > "$results/egress-guard.txt"
 awk '$3 == "REJECT" && $1 > 0 { rejected=1 } END { exit !rejected }' "$results/egress-guard.txt"
 
-setsid env -i PATH="$PATH" HOME="$HOME" PYTHONPATH="$PYTHONPATH" INTEGRATION_RUN_ID="$integration_identity" \
-  .venv/bin/python -m integration._support.upstream > "$results/upstream.log" 2>&1 &
-upstream_pid=$!
+isolated_workers=false
+if [ "$mode" = parity ]; then
+  export INTEGRATION_WORKERS=1
+else
+  case "$suite" in
+    management|accounting) export INTEGRATION_WORKERS=2; isolated_workers=true ;;
+    providers|extensions) export INTEGRATION_WORKERS=4; isolated_workers=true ;;
+  esac
+fi
+if [ "$isolated_workers" = false ]; then
+  setsid env -i PATH="$PATH" HOME="$HOME" PYTHONPATH="$PYTHONPATH" INTEGRATION_RUN_ID="$integration_identity" \
+    .venv/bin/python -m integration._support.upstream > "$results/upstream.log" 2>&1 &
+  upstream_pid=$!
+fi
 if [ "$suite" = cost ]; then
   export INTEGRATION_WORKERS=8
 fi
+if [ "$suite" = security ]; then
+  export INTEGRATION_WORKERS=4
+fi
 if [ "$suite" = mcp ]; then
   export INTEGRATION_WORKERS=4 INTEGRATION_COVERAGE=1
 fi
@@ -177,17 +191,22 @@ start_proxy() {
     > "$results/$log_name" 2>&1 &
   launched_pid=$!
 }
-start_proxy 4000 proxy.log
-proxy_pid="$launched_pid"
-.venv/bin/python .circleci/scripts/wait_integration_services.py
-curl --noproxy '*' -sSf -X POST "$INTEGRATION_PROXY_URL/config/update" \
-  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
-  -d '{"router_settings": {"num_retries": 0}}' > "$results/seed-router-settings.json"
-if [ "$suite" = management ] || [ "$suite" = mcp ]; then
+if { [ "$suite" = management ] || [ "$suite" = mcp ]; } && [ "$isolated_workers" = true ]; then
   export INTEGRATION_PEER_URL=http://127.0.0.1:4001
-  start_proxy 4001 peer.log
-  peer_pid="$launched_pid"
+fi
+if [ "$isolated_workers" = false ]; then
+  start_proxy 4000 proxy.log
+  proxy_pid="$launched_pid"
   .venv/bin/python .circleci/scripts/wait_integration_services.py
+  curl --noproxy '*' -sSf -X POST "$INTEGRATION_PROXY_URL/config/update" \
+    -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
+    -d '{"router_settings": {"num_retries": 0}}' > "$results/seed-router-settings.json"
+  if [ "$suite" = management ] || [ "$suite" = mcp ]; then
+    export INTEGRATION_PEER_URL=http://127.0.0.1:4001
+    start_proxy 4001 peer.log
+    peer_pid="$launched_pid"
+    .venv/bin/python .circleci/scripts/wait_integration_services.py
+  fi
 fi
 
 if [ "$suite" = providers ]; then
@@ -213,13 +232,11 @@ if [ "$suite" = browser ]; then
   exit 0
 fi
 
-node_files=()
+shard_arguments=()
 if [ "${CIRCLE_NODE_TOTAL:-1}" -gt 1 ]; then
-  split="$(.venv/bin/python tests/integration/run.py "$suite" --list \
-    | circleci tests split --split-by=timings --timings-type=filename)"
-  read -r -a node_files <<< "$(printf '%s' "$split" | tr '\n' ' ')"
-  test "${#node_files[@]}" -gt 0
-  printf '%s\n' "${node_files[@]}" > "$results/node-files.txt"
+  .venv/bin/python tests/integration/run.py "$suite" --list \
+    | circleci tests split --split-by=timings --timings-type=filename > "$results/node-files.txt"
+  shard_arguments=(--shard-files "$results/node-files.txt")
 fi
 
 env -i PATH="$PATH" HOME="$HOME" PYTHONPATH="$PYTHONPATH" \
@@ -232,11 +249,14 @@ env -i PATH="$PATH" HOME="$HOME" PYTHONPATH="$PYTHONPATH" \
   LITELLM_LICENSE="${LITELLM_LICENSE:-}" \
   INTEGRATION_SEED="$INTEGRATION_SEED" \
   INTEGRATION_ORDER_SEED="$INTEGRATION_ORDER_SEED" \
+  INTEGRATION_CASE_SHARDS="${CIRCLE_NODE_TOTAL:-1}" INTEGRATION_CASE_SHARD_INDEX="${CIRCLE_NODE_INDEX:-0}" \
   LITELLM_LOCAL_MODEL_COST_MAP=True AWS_EC2_METADATA_DISABLED=true DO_NOT_TRACK=1 \
   INTEGRATION_PROXY_DATABASE_URL="$INTEGRATION_PROXY_DATABASE_URL" \
   INTEGRATION_PROXY_READ_REPLICA_URL="$INTEGRATION_PROXY_READ_REPLICA_URL" \
   INTEGRATION_ROUTING="$INTEGRATION_ROUTING" \
-  .venv/bin/python tests/integration/run.py "$suite" --results "$results" "${node_files[@]}"
+  MCP_TEST_PEER_PYTHON="${MCP_TEST_PEER_PYTHON:-}" \
+  .venv/bin/python tests/integration/run.py "$suite" --results "$results" \
+  "${shard_arguments[@]}"
 
 if [ "${INTEGRATION_COVERAGE:-0}" = 1 ]; then
   for covered_pid in "$proxy_pid" "$peer_pid"; do

.circleci/scripts/run_migration_tests.py

@@ -10,7 +10,7 @@ from typing import Final
 from xml.etree import ElementTree
 
 SUITES: Final = {
-    "startup": (("test_startup.py",), 12),
+    "startup": (("test_startup.py",), 13),
     "recovery": (("test_recovery.py",), 15),
     "legacy": (("test_legacy.py", "test_pooling.py"), 11),
     "upgrade": (("test_upgrade.py", "test_rolling_upgrade.py"), 5),

.circleci/scripts/wait_integration_services.py

@@ -1,42 +1,31 @@
 import os
-import time
+from contextlib import ExitStack
 from typing import Final
 
 import httpx
+from integration._support.client import Gateway
+from integration._support.workers import wait_for_services
 from redis import Redis
 
 
 def main() -> None:
     primary: Final = os.environ["INTEGRATION_PROXY_URL"]
     peer: Final = os.environ.get("INTEGRATION_PEER_URL")
-    proxies: Final = (primary, peer) if peer else (primary,)
-    deadline: Final = time.monotonic() + 90
-    headers: Final = {"Authorization": f"Bearer {os.environ['INTEGRATION_MASTER_KEY']}"}
-    with httpx.Client(trust_env=False, timeout=2) as client, Redis(
-        host=os.environ["REDIS_HOST"], port=int(os.environ["REDIS_PORT"]), socket_timeout=2
-    ) as cache:
-        while True:
-            try:
-                ready: Final = (
-                    client.get(f"{os.environ['INTEGRATION_UPSTREAM_URL']}/health").status_code == 200
-                    and all(client.get(f"{url}/health/readiness").status_code == 200 for url in proxies)
-                )
-                if ready:
-                    for url in proxies:
-                        response: Final = client.get(f"{url}/cache/ping", headers=headers)
-                        response.raise_for_status()
-                        result: Final = response.json()
-                        assert result["status"] == "healthy", result
-                        assert result["cache_type"] == "redis", result
-                        assert result["ping_response"] is True, result
-                        assert result["set_cache_response"] == "success", result
-                    if cache.pubsub_numsub("litellm_proxy.auth_cache_invalidation")[0][1] >= len(proxies):
-                        return
-            except httpx.TransportError:
-                pass
-            if time.monotonic() >= deadline:
-                raise SystemExit("Integration services or auth-cache subscribers did not become ready")
-            time.sleep(0.2)
+    urls: Final = (primary, peer) if peer else (primary,)
+    upstream: Final = os.environ["INTEGRATION_UPSTREAM_URL"]
+    with ExitStack() as stack:
+        proxies: Final = tuple(
+            Gateway(
+                stack.enter_context(httpx.Client(base_url=url, trust_env=False, timeout=2)),
+                os.environ["INTEGRATION_MASTER_KEY"],
+                upstream,
+            )
+            for url in urls
+        )
+        cache: Final = stack.enter_context(
+            Redis(host=os.environ["REDIS_HOST"], port=int(os.environ["REDIS_PORT"]), socket_timeout=2)
+        )
+        wait_for_services(upstream, proxies, cache)
 
 
 if __name__ == "__main__":

.github/ci-coverage-allowlist.yml

@@ -18,32 +18,11 @@ test_paths:
     paths:
       - tests/rust-python-harness
   - reason: >-
-      Live-provider caching cases in tests/local_testing that remain outside CI. Jobs that
-      glob that directory either deselect them (local_testing_part1 and part2 carry `-k "... and
-      not caching and not cache"`) or keep only another keyword (langfuse, router, assistants).
-      Separately, the CircleCI redis-compat jobs select two IAM cluster authentication tests in
-      test_caching.py by node ID. It does not run that file's other tests.
-      The gap was eight files and 118 tests when measured 2026-08-20; the five keyless files now
-      run in the caching-local shard, leaving live cases in these three. Measured 2026-08-21 with no provider
-      credentials and no Redis: test_caching.py needs both (37 of 65 fail without them),
-      test_disk_cache_unit_tests.py needs OPENAI_API_KEY for 2 of its 4, and
-      test_gcs_cache_unit_tests.py needs GCS credentials for all 4. They want the keyless/live
-      split that porting tests/local_testing off CircleCI will force, not a job that is red by
-      construction
+      Owned by the open pull request that moves the Rust/Python parity checks (#45135). It ran in
+      the CircleCI build_and_test job that globbed tests/test_*.py, which this migration deletes,
+      and that pull request gives it a new home
     paths:
-      - tests/local_testing/test_caching.py
-      - tests/local_testing/test_disk_cache_unit_tests.py
-      - tests/local_testing/test_gcs_cache_unit_tests.py
-  - reason: >-
-      Mixed file that no job has ever run in full. Every CircleCI job that globs
-      tests/local_testing deselects it by name ("caching") or keeps only another keyword, so only
-      its router test ran, and that test now lives in tests/unit/router_utils/pre_call_checks.
-      Five of the seven left need ANTHROPIC_API_KEY or Vertex credentials. The other two,
-      test_litellm_anthropic_prompt_caching_tools and test_litellm_anthropic_prompt_caching_system,
-      are offline mocks that already fail on main against a stale expected request body; they need
-      that fixed before they can move to tests/unit
-    paths:
-      - tests/local_testing/test_anthropic_prompt_caching.py
+      - tests/test_rust_python_harness.py
   - reason: >-
       The end-to-end suite runs against a deployed proxy from its own in-cluster rig rather than
       from a pull request; it needs a live gateway and provider credentials no PR job holds
@@ -69,48 +48,6 @@ test_paths:
       choice it informed is settled
     paths:
       - tests/code_coverage_tests/test_aio_http_image_conversion.py
-  - reason: >-
-      No job invokes this suite and its files mix pure transformation tests with ones driving live
-      vendor vector stores, so assigning them needs a per-file decision
-    paths:
-      - tests/vector_store_tests/rag/test_rag_bedrock.py
-      - tests/vector_store_tests/rag/test_rag_openai.py
-      - tests/vector_store_tests/rag/test_rag_s3_vectors.py
-      - tests/vector_store_tests/rag/test_rag_vertex_ai.py
-      - tests/vector_store_tests/test_azure_ai_vector_store.py
-      - tests/vector_store_tests/test_azure_vector_store.py
-      - tests/vector_store_tests/test_bedrock_vector_store.py
-      - tests/vector_store_tests/test_gemini_vector_store.py
-      - tests/vector_store_tests/test_milvus_vector_store.py
-      - tests/vector_store_tests/test_openai_vector_store.py
-      - tests/vector_store_tests/test_ragflow_vector_store.py
-      - tests/vector_store_tests/test_s3_vectors_vector_store.py
-      - tests/vector_store_tests/test_vertex_ai_search_api_vector_store.py
-      - tests/vector_store_tests/test_vertex_ai_vector_store.py
-  - reason: >-
-      Throughput and memory-growth measurements whose runtime and variance make them unsuitable for
-      a per-pull-request job
-    paths:
-      - tests/load_tests/test_datadog_load_test.py
-      - tests/load_tests/test_langsmith_load_test.py
-      - tests/load_tests/test_linear_memory_growth.py
-      - tests/load_tests/test_memory_usage.py
-      - tests/load_tests/test_otel_load_test.py
-      - tests/load_tests/test_vertex_embeddings_load_test.py
-      - tests/load_tests/test_vertex_load_tests.py
-  - reason: >-
-      Env-gated saturation benchmark requires a live proxy and provider credentials, so it is run
-      locally rather than in pull-request jobs
-    paths:
-      - tests/load_tests/test_granian_admission_saturation.py
-  - reason: >-
-      A local-only agent rig: test_a2a_completion_bridge.py needs a LangGraph server on
-      localhost:2024 and test_a2a.py drives a live A2A endpoint, so neither can run in a
-      pull request job. Until 2026-08-20 the CircleCI agent job hid them behind a grep -v
-      that this census could not see; the glob now excludes them structurally and this entry
-      is the decision on the record. Revisit when the A2A bridge gets a recorded-wire fixture
-    paths:
-      - tests/agent_tests/local_only_agent_tests
   - reason: >-
       Third-party integration tests that skip themselves without OCI configuration or sandbox
       credentials, neither of which a pull request job holds

.github/scripts/assert_ci_coverage.py

@@ -9,6 +9,8 @@ import sys
 import warnings
 from collections.abc import Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass
+from functools import lru_cache
+from types import MappingProxyType
 from typing import Final
 
 import yaml
@@ -35,7 +37,6 @@ GLOB_CHARS = frozenset("*?")
 # tests has to be named by some shard or it runs nowhere. A child listed here is
 # itself decomposed one level deeper and is checked through its own entry.
 SHARDED_ROOTS: tuple[str, ...] = (
-    "tests/test_litellm",
     "tests/unit",
     "tests/unit/enterprise",
     "tests/unit/enterprise/enterprise_callbacks",
@@ -316,6 +317,7 @@ def _keyword_terms(
 def _slices() -> tuple[Slice, ...]:
     if not CIRCLECI_CONFIG.exists():
         return ()
+    test_files: Final = frozenset(_test_files())
     jobs: Final = yaml.safe_load(CIRCLECI_CONFIG.read_text()).get("jobs", {})
     return tuple(
         Slice(job=job, globs=globs, named=named, required=required, excluded=excluded, understood=understood)
@@ -323,7 +325,7 @@ def _slices() -> tuple[Slice, ...]:
         for text in ("\n".join(_strings(body)),)
         if "pytest" in text
         for globs in (tuple(GLOB_CALL_RE.findall(text)),)
-        for named in (frozenset(TEST_TOKEN_RE.findall(text)) & frozenset(_test_files()),)
+        for named in (frozenset(TEST_TOKEN_RE.findall(text)) & test_files,)
         for required, excluded, understood in (
             _keyword_terms(tuple(KEYWORD_RE.findall(text)), attributable=len(globs) < 2),
         )
@@ -363,6 +365,7 @@ def _workflow_named_tokens() -> frozenset[str]:
 
 
 def _deselected_everywhere(allowlist: Allowlist) -> tuple[Finding, ...]:
+    matchable_names: Final = lru_cache(maxsize=None)(_matchable_names)
     slices: Final = _slices()
     named_by_workflow: Final = _workflow_named_tokens()
     globbed: Final = tuple(
@@ -376,7 +379,7 @@ def _deselected_everywhere(allowlist: Allowlist) -> tuple[Finding, ...]:
         for path in globbed
         if not allowlist.covers_test(path)
         and not any(_token_covers(token, path) for token in named_by_workflow)
-        and not any(slice_.claims(path, _matchable_names(path)) for slice_ in slices)
+        and not any(slice_.claims(path, matchable_names(path)) for slice_ in slices)
     )
 
 

.github/workflows/deploy-dev-on-main.yml

@@ -0,0 +1,30 @@
+name: Deploy main to gateway-dev
+
+on:
+  push:
+    branches: [main]
+
+permissions: {}
+
+concurrency:
+  group: deploy-dev-dispatch
+  cancel-in-progress: true
+
+jobs:
+  dispatch:
+    if: github.repository == 'BerriAI/litellm'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2.2.2
+        id: token
+        with:
+          app-id: ${{ secrets.LITELLM_OPS_DISPATCH_APP_ID }}
+          private-key: ${{ secrets.LITELLM_OPS_DISPATCH_APP_PRIVATE_KEY }}
+          owner: BerriAI
+          repositories: litellm-ops
+          permission-actions: write
+      - name: Dispatch the litellm-ops dev deploy
+        env:
+          GH_TOKEN: ${{ steps.token.outputs.token }}
+        run: gh api --method POST repos/BerriAI/litellm-ops/actions/workflows/deploy-dev.yml/dispatches -f ref=main

.github/workflows/helm_unit_test.yml

@@ -1,60 +0,0 @@
-name: Helm unit test
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  unit-test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Check Lens Compose configuration
-        run: |
-          python3 -m unittest discover -s deploy/lens -p 'test_*.py'
-          python3 deploy/lens/configure.py --version 1.2.3 --env-file "$RUNNER_TEMP/lens.env"
-          docker compose --env-file "$RUNNER_TEMP/lens.env" -f deploy/lens/stack.yaml config --quiet
-
-      - name: Set up Helm 3.11.1
-        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
-        with:
-          version: "3.11.1"
-
-      - name: Download and verify Helm Unit Test Plugin
-        run: |
-          curl -fsSLo "$RUNNER_TEMP/helm-unittest.tgz" https://github.com/helm-unittest/helm-unittest/releases/download/v0.8.2/helm-unittest-linux-amd64-0.8.2.tgz
-          echo "56ab3091e6fa52a7c92ee951def9bed957f295d9ce98483aed404e748d7b3a94  $RUNNER_TEMP/helm-unittest.tgz" | sha256sum -c -
-
-      - name: Install Helm Unit Test Plugin
-        run: |
-          PLUGIN_DIR="$(helm env HELM_PLUGINS)/helm-unittest"
-          mkdir -p "$PLUGIN_DIR"
-          tar -xzf "$RUNNER_TEMP/helm-unittest.tgz" -C "$PLUGIN_DIR"
-          helm plugin list
-
-      - name: Run unit tests
-        run: |
-          for chart in helm/litellm-helm helm/litellm; do
-            declared="$(grep -h '^suite:' "$chart"/tests/*.yaml | wc -l | tr -d '[:space:]')"
-            output="$(mktemp)"
-            helm unittest -f 'tests/*.yaml' "$chart" | tee "$output"
-            executed="$(sed -n 's/^Test Suites:.*[[:space:]]\([0-9][0-9]*\) total$/\1/p' "$output")"
-            if [ "$declared" != "$executed" ]; then
-              echo "::error::$chart declares $declared test suites but helm-unittest ran $executed. Suites are being skipped silently, so their assertions never execute."
-              exit 1
-            fi
-            echo "$chart: all $declared declared test suites ran"
-          done

.github/workflows/image-scan.yml

@@ -17,10 +17,8 @@ on:
       - gateway/routes/allowlist.py
       - backend/Dockerfile
       - backend/main.py
-      - deploy/lens/**
       - litellm-rust/**
       - litellm/proxy/lens/**
-      - tests/e2e/migrations/lens_compose_smoke.sh
       - docker/component_entrypoint.sh
       - docker/entrypoint.sh
       - litellm/proxy/prisma_migration.py
@@ -29,7 +27,7 @@ on:
       - backend/routes/allowlist.py
       - pyproject.toml
       - litellm-proxy-extras/**
-      - tests/proxy_migration_tests/**
+      - tests/integration/database/image/**
       - uv.lock
       - ui/litellm-dashboard/package-lock.json
       - ui/Dockerfile
@@ -47,57 +45,6 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  lens-worker-image:
-    name: lens-worker-image (${{ matrix.arch }})
-    runs-on: ${{ matrix.runner }}
-    if: >-
-      github.event_name != 'pull_request' ||
-      github.event.pull_request.head.repo.full_name == github.repository
-    timeout-minutes: 45
-    permissions:
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - arch: amd64
-            runner: ubuntu-latest
-            grype_sha256: edda0968d8827daab01d32b3cd7de192ae0915005e7bbfcfef9e68e79bc43343
-          - arch: arm64
-            runner: ubuntu-24.04-arm
-            grype_sha256: 553e4c36d9d61349830ba6034d43b8700a7f10576d3e2f4981c0fd2b96086465
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-      - name: Build the release worker
-        env:
-          RELEASE_TAG: sha-${{ github.sha }}
-        run: docker build --build-arg LITELLM_RELEASE_TAG="${RELEASE_TAG}" -f deploy/lens/Dockerfile -t lens-worker-scan .
-      - name: Verify the standalone worker on a read-only filesystem
-        env:
-          RELEASE_TAG: sha-${{ github.sha }}
-        run: |
-          docker run --rm --network none --read-only --cap-drop ALL \
-            --tmpfs /tmp:rw,noexec,nosuid,size=1g --security-opt no-new-privileges \
-            lens-worker-scan --version | grep -F "litellm-lens $RELEASE_TAG protocol="
-      - name: Download Grype v0.114.0
-        env:
-          ARCH: ${{ matrix.arch }}
-          GRYPE_SHA256: ${{ matrix.grype_sha256 }}
-        run: |
-          curl -fsSL --retry 3 -o "$RUNNER_TEMP/grype.tar.gz" \
-            "https://github.com/anchore/grype/releases/download/v0.114.0/grype_0.114.0_linux_${ARCH}.tar.gz"
-          echo "${GRYPE_SHA256}  $RUNNER_TEMP/grype.tar.gz" | sha256sum -c -
-          tar xzf "$RUNNER_TEMP/grype.tar.gz" -C "$RUNNER_TEMP" grype
-          chmod +x "$RUNNER_TEMP/grype"
-      - name: Scan the worker for fixable HIGH/CRITICAL CVEs
-        env:
-          GRYPE_MATCH_PYTHON_USING_CPES: "true"
-        run: |
-          "$RUNNER_TEMP/grype" lens-worker-scan \
-            --config .grype.yaml --only-fixed --fail-on high --output table
-
   image-scan:
     name: image-scan
     runs-on: ubuntu-latest
@@ -145,7 +92,7 @@ jobs:
           LITELLM_ADMIN_MCP_SCHEMA_IMAGE: litellm-admin-mcp-schema:${{ github.sha }}
         run: |
           python -m pip install "pytest==9.0.3"
-          python -m pytest tests/proxy_migration_tests/test_offline_image_migration.py tests/proxy_migration_tests/test_image_bedrock_realtime_extra.py tests/proxy_migration_tests/test_image_admin_mcp.py -v
+          python -m pytest --noconftest tests/integration/database/image/test_offline_image_migration.py tests/integration/database/image/test_image_bedrock_realtime_extra.py tests/integration/database/image/test_image_admin_mcp.py -v
 
       # Scans the whole shipped artifact: OS/apk plus every language package
       # baked into the image, including ones no lockfile declares (e.g. prisma's
@@ -198,13 +145,8 @@ jobs:
           LITELLM_ADMIN_MCP_SCHEMA_IMAGE: litellm-admin-mcp-schema:${{ github.sha }}
         run: |
           python -m pip install "pytest==9.0.3"
-          python -m pytest tests/proxy_migration_tests/test_offline_image_migration.py tests/proxy_migration_tests/test_image_bedrock_realtime_extra.py tests/proxy_migration_tests/test_image_admin_mcp.py -v
+          python -m pytest --noconftest tests/integration/database/image/test_offline_image_migration.py tests/integration/database/image/test_image_bedrock_realtime_extra.py tests/integration/database/image/test_image_admin_mcp.py -v
 
-      - name: Verify the bundled Lens Compose installation and restart
-        if: matrix.dockerfile == 'Dockerfile'
-        env:
-          LITELLM_IMAGE: litellm-runtime-scan:${{ github.sha }}
-        run: bash tests/e2e/migrations/lens_compose_smoke.sh
 
   migrations-image:
     name: migrations-image
@@ -235,7 +177,7 @@ jobs:
           LITELLM_MIGRATION_SCRIPT: /app/run.py
         run: |
           python -m pip install "pytest==9.0.3"
-          python -m pytest tests/proxy_migration_tests/test_offline_image_migration.py -v
+          python -m pytest --noconftest tests/integration/database/image/test_offline_image_migration.py -v
 
   gateway-image:
     name: gateway-image
@@ -266,7 +208,7 @@ jobs:
           LITELLM_IMAGE_COMPONENT: gateway
         run: |
           python -m pip install "pytest==9.0.3"
-          python -m pytest tests/proxy_migration_tests/test_component_image_serves_offline.py tests/proxy_migration_tests/test_image_bedrock_realtime_extra.py tests/proxy_migration_tests/test_image_admin_mcp.py -v
+          python -m pytest --noconftest tests/integration/database/image/test_component_image_serves_offline.py tests/integration/database/image/test_image_bedrock_realtime_extra.py tests/integration/database/image/test_image_admin_mcp.py -v
 
   ui-image:
     name: ui-image
@@ -295,7 +237,7 @@ jobs:
           LITELLM_IMAGE: litellm-ui-scan:${{ github.sha }}
         run: |
           python -m pip install "pytest==9.0.3"
-          python -m pytest tests/proxy_migration_tests/test_ui_image_serves_offline.py -v
+          python -m pytest --noconftest tests/integration/database/image/test_ui_image_serves_offline.py -v
 
   backend-image:
     name: backend-image
@@ -330,4 +272,4 @@ jobs:
           LITELLM_IMAGE_COMPONENT: backend
         run: |
           python -m pip install "pytest==9.0.3"
-          python -m pytest tests/proxy_migration_tests/test_component_image_serves_offline.py tests/proxy_migration_tests/test_image_admin_mcp.py -v
+          python -m pytest --noconftest tests/integration/database/image/test_component_image_serves_offline.py tests/integration/database/image/test_image_admin_mcp.py -v

.github/workflows/lens-install-smoke.yml

@@ -2,6 +2,19 @@ name: Lens installation smoke
 
 on:
   workflow_dispatch:
+    inputs:
+      lens_image:
+        description: Verified baseline Lens image at ghcr.io/berriai/lens@sha256
+        required: true
+        type: string
+      lens_upgrade_image:
+        description: Compatible Lens upgrade image at ghcr.io/berriai/lens@sha256
+        required: true
+        type: string
+      gateway_baseline_ref:
+        description: Previously qualified gateway source commit, full SHA
+        required: true
+        type: string
 
 permissions:
   contents: read
@@ -28,27 +41,46 @@ jobs:
             dockerfile: migrations/Dockerfile
           - component: monolith
             dockerfile: Dockerfile
-          - component: worker
-            dockerfile: deploy/lens/Dockerfile
+          - component: gateway
+            dockerfile: gateway/Dockerfile
+            baseline: true
+          - component: backend
+            dockerfile: backend/Dockerfile
+            baseline: true
+          - component: monolith
+            dockerfile: Dockerfile
+            baseline: true
     env:
       COMPONENT: ${{ matrix.component }}
       DOCKERFILE: ${{ matrix.dockerfile }}
+      SOURCE_REF: ${{ matrix.baseline && inputs.gateway_baseline_ref || github.sha }}
+      IMAGE_TAG: ${{ matrix.baseline && 'v0.0.0-lens-ci-baseline' || 'v0.0.0-lens-ci' }}
+      CURRENT_REF: ${{ github.sha }}
     steps:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           persist-credentials: false
+          ref: ${{ env.SOURCE_REF }}
+      - name: Verify the selected source
+        shell: bash -euo pipefail {0}
+        run: |
+          [[ "$SOURCE_REF" =~ ^[0-9a-f]{40}$ ]]
+          test "$(git rev-parse HEAD)" = "$SOURCE_REF"
+          if [[ "$IMAGE_TAG" == v0.0.0-lens-ci-baseline ]]; then
+            test "$SOURCE_REF" != "$CURRENT_REF"
+          fi
       - name: Build the matching release image
         run: |
-          docker build --build-arg LITELLM_RELEASE_TAG=v0.0.0-lens-ci \
-            -f "$DOCKERFILE" -t "lens-ci-$COMPONENT:v0.0.0-lens-ci" .
+          docker build --build-arg "LITELLM_RELEASE_TAG=$IMAGE_TAG" \
+            -f "$DOCKERFILE" -t "lens-ci-$COMPONENT:$IMAGE_TAG" .
       - name: Save the matching release image
         run: |
-          docker save "lens-ci-$COMPONENT:v0.0.0-lens-ci" \
-            | gzip -1 > "$RUNNER_TEMP/lens-install-$COMPONENT.tar.gz"
+          docker save "lens-ci-$COMPONENT:$IMAGE_TAG" \
+            | gzip -1 > "$RUNNER_TEMP/lens-install-$COMPONENT-$IMAGE_TAG.tar.gz"
       - uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
         with:
-          name: lens-install-${{ matrix.component }}-${{ github.sha }}
-          path: ${{ runner.temp }}/lens-install-${{ matrix.component }}.tar.gz
+          name: lens-install-${{ matrix.component }}-${{ env.IMAGE_TAG }}-${{ github.sha }}
+          path: ${{ runner.temp }}/lens-install-${{ matrix.component }}-${{ env.IMAGE_TAG }}.tar.gz
           compression-level: 0
           retention-days: 3
           if-no-files-found: error
@@ -69,11 +101,37 @@ jobs:
           path: ${{ runner.temp }}/lens-install-images
       - name: Load the matching release images
         run: |
-          for component in gateway backend ui migrations monolith worker; do
-            archive="$RUNNER_TEMP/lens-install-images/lens-install-$component.tar.gz"
+          for archive in "$RUNNER_TEMP"/lens-install-images/lens-install-*.tar.gz; do
             gzip -dc "$archive" | docker load
             rm "$archive"
           done
+      - uses: sigstore/cosign-installer@3454372f43399081ed03b604cb2d021dabca52bb # v3.8.2
+        with:
+          cosign-release: v2.4.3
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ vars.LENS_READ_USER || github.actor }}
+          password: ${{ secrets.LENS_READ_TOKEN }}
+      - name: Verify independent Lens images before loading them
+        env:
+          LENS_IMAGE: ${{ inputs.lens_image }}
+          LENS_UPGRADE_IMAGE: ${{ inputs.lens_upgrade_image }}
+          LENS_PUBLIC_KEY: ${{ vars.LENS_COSIGN_PUBLIC_KEY }}
+          LENS_PUBLIC_KEY_SHA256: ${{ vars.LENS_COSIGN_PUBLIC_KEY_SHA256 }}
+        shell: bash -euo pipefail {0}
+        run: |
+          [[ "$LENS_PUBLIC_KEY_SHA256" =~ ^[0-9a-f]{64}$ ]]
+          printf '%s' "$LENS_PUBLIC_KEY" > "$RUNNER_TEMP/lens.pub"
+          echo "$LENS_PUBLIC_KEY_SHA256  $RUNNER_TEMP/lens.pub" | sha256sum --check
+          for image in "$LENS_IMAGE" "$LENS_UPGRADE_IMAGE"; do
+            [[ "$image" =~ ^ghcr.io/berriai/lens@sha256:[0-9a-f]{64}$ ]]
+            cosign verify --key "$RUNNER_TEMP/lens.pub" "$image" > /dev/null
+            cosign verify-attestation --key "$RUNNER_TEMP/lens.pub" --type spdxjson "$image" > /dev/null
+            docker pull "$image"
+          done
+          docker tag "$LENS_IMAGE" lens-ci-worker:baseline
+          docker tag "$LENS_UPGRADE_IMAGE" lens-ci-worker:upgrade
       - name: Install pinned Kubernetes test tools
         run: |
           curl --fail --location --output "$RUNNER_TEMP/kind" \

.github/workflows/lens-worker.yml

@@ -1,111 +0,0 @@
-name: Lens Worker Image
-
-on:
-  pull_request:
-    branches: [main, litellm_oss_branch, "litellm_**"]
-    paths:
-      - deploy/lens/**
-      - litellm-rust/**
-      - litellm/proxy/lens/**
-      - tests/proxy_behavior/lens/**
-      - .github/workflows/lens-worker.yml
-  push:
-    branches: [main]
-    paths:
-      - deploy/lens/**
-      - litellm-rust/**
-      - litellm/proxy/lens/**
-      - tests/proxy_behavior/lens/**
-      - .github/workflows/lens-worker.yml
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  lens-worker-image:
-    permissions:
-      contents: read
-      packages: write
-    runs-on: ${{ matrix.runner }}
-    timeout-minutes: 45
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - arch: amd64
-            runner: ubuntu-latest
-          - arch: arm64
-            runner: ubuntu-24.04-arm
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-      - name: Build native Lens service
-        env:
-          RELEASE_TAG: sha-${{ github.sha }}
-        run: docker build --build-arg LITELLM_RELEASE_TAG="$RELEASE_TAG" -f deploy/lens/Dockerfile -t lens-worker .
-      - name: Verify version and unprivileged runtime
-        env:
-          RELEASE_TAG: sha-${{ github.sha }}
-        run: bash deploy/lens/smoke.sh lens-worker "$RELEASE_TAG"
-      - name: Verify confined Python on the native architecture
-        env:
-          RELEASE_TAG: sha-${{ github.sha }}
-        run: |
-          docker build --target smoke --build-arg LITELLM_RELEASE_TAG="$RELEASE_TAG" -f deploy/lens/Dockerfile -t lens-smoke .
-          docker run --rm --network none --read-only --cap-drop ALL \
-            --tmpfs /tmp:rw,noexec,nosuid,size=1g --security-opt no-new-privileges lens-smoke
-      - name: Reject custom builds without a matching release tag
-        run: |
-          if docker build --progress plain -f deploy/lens/Dockerfile -t lens-worker:unversioned . > missing-tag.log 2>&1; then
-            echo "::error::An unversioned worker build unexpectedly succeeded"
-            exit 1
-          fi
-          grep -F 'LITELLM_RELEASE_TAG: Pass --build-arg LITELLM_RELEASE_TAG matching the gateway' missing-tag.log
-      - name: Publish development architecture
-        if: github.event_name != 'pull_request' && github.repository == 'BerriAI/litellm' && github.ref == 'refs/heads/main'
-        env:
-          REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          REGISTRY_USER: ${{ github.actor }}
-          IMAGE: ghcr.io/berriai/litellm-lens-worker-dev:sha-${{ github.sha }}-${{ matrix.arch }}
-          ARCH: ${{ matrix.arch }}
-        run: |
-          printf '%s' "$REGISTRY_TOKEN" | docker login ghcr.io -u "$REGISTRY_USER" --password-stdin
-          docker tag lens-worker "$IMAGE"
-          docker push "$IMAGE"
-          mkdir -p digests
-          docker inspect --format='{{index .RepoDigests 0}}' "$IMAGE" > "digests/$ARCH"
-      - uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        if: github.event_name != 'pull_request' && github.repository == 'BerriAI/litellm' && github.ref == 'refs/heads/main'
-        with:
-          name: lens-digest-${{ matrix.arch }}
-          path: digests/
-          retention-days: 1
-
-  publish:
-    name: Publish Lens development index
-    needs: lens-worker-image
-    if: github.event_name != 'pull_request' && github.repository == 'BerriAI/litellm' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    permissions:
-      packages: write
-    steps:
-      - uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
-        with:
-          pattern: lens-digest-*
-          merge-multiple: true
-          path: digests
-      - name: Publish both tested architectures
-        env:
-          REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          REGISTRY_USER: ${{ github.actor }}
-          IMAGE: ghcr.io/berriai/litellm-lens-worker-dev:sha-${{ github.sha }}
-        run: |
-          printf '%s' "$REGISTRY_TOKEN" | docker login ghcr.io -u "$REGISTRY_USER" --password-stdin
-          docker buildx imagetools create --tag "$IMAGE" "$(cat digests/amd64)" "$(cat digests/arm64)"
-          printf 'Lens worker image: `%s`\n' "$IMAGE" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/publish-lint-base-counts.yml

@@ -35,6 +35,8 @@ jobs:
             script: scripts/type_discipline_gate.py
           - checker: test-quality
             script: scripts/test_quality_gate.py
+          - checker: openapi-docs
+            script: scripts/openapi_docs_gate.py
           - checker: basedpyright
             script: scripts/type_check_gate.py
 
@@ -60,16 +62,24 @@ jobs:
         uses: ./.github/actions/cache-cargo-build
 
       - name: Cache Prisma binaries
-        if: matrix.checker == 'basedpyright'
+        if: matrix.checker == 'basedpyright' || matrix.checker == 'openapi-docs'
         uses: ./.github/actions/cache-prisma-binaries
 
-      # The three source scanners only need the pinned dev tools (ruff and the
+      # The source scanners only need the pinned dev tools (ruff and the
       # stdlib checkers), the same versions test-linting.yml's python job runs.
       - name: Install the dev tools
-        if: matrix.checker != 'basedpyright'
+        if: matrix.checker != 'basedpyright' && matrix.checker != 'openapi-docs'
         run: |
           uv sync --frozen --only-group dev --no-install-project
 
+      # The OpenAPI gate imports the proxy app, so it needs the same install the
+      # test-linting.yml python job uses, Prisma client included.
+      - name: Install the proxy
+        if: matrix.checker == 'openapi-docs'
+        run: |
+          uv sync --frozen --group proxy-dev --group e2e-dev --extra proxy
+          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
+
       - name: Emit ${{ matrix.checker }} counts for HEAD
         if: matrix.checker != 'basedpyright'
         run: |

.github/workflows/required-checks-legacy.yml

@@ -1,397 +0,0 @@
-name: Required checks (legacy)
-
-on:
-  pull_request:
-    branches:
-      - main
-      - "litellm_**"
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
-
-jobs:
-  lint:
-    name: lint
-    permissions:
-      contents: read
-      pull-requests: read
-      actions: read
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          fetch-depth: 1
-          clean: true
-          persist-credentials: false
-
-      - name: Detect relevant changes
-        id: changes
-        uses: ./.github/actions/detect-changes
-
-      - name: Fetch gate base (merge-base with target branch)
-        if: steps.changes.outputs.decision != 'skip'
-        env:
-          GH_TOKEN: ${{ github.token }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          retry() { "$@" || { sleep 15; "$@"; } || { sleep 30; "$@"; }; }
-          MERGE_BASE=$(retry gh api "repos/${{ github.repository }}/compare/${BASE_SHA}...${HEAD_SHA}?per_page=1" --jq '.merge_base_commit.sha')
-          test -n "$MERGE_BASE"
-          retry git fetch --no-tags --depth=1 origin "$MERGE_BASE"
-          echo "GATE_BASE_SHA=$MERGE_BASE" >> "$GITHUB_ENV"
-
-      - name: Set up Python
-        if: steps.changes.outputs.decision != 'skip'
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Set up uv
-        if: steps.changes.outputs.decision != 'skip'
-        uses: ./.github/actions/setup-uv-with-retries
-        with:
-          version: "0.10.9"
-
-      - name: Cache uv dependencies
-        if: steps.changes.outputs.decision != 'skip'
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-        with:
-          path: |
-            ~/.cache/uv
-            .venv
-          key: ${{ runner.os }}-uv-lint-${{ hashFiles('uv.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-uv-lint-
-
-      - name: Clean Python cache
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          find . -type d -name "__pycache__" -exec rm -rf {} + || true
-          find . -name "*.pyc" -delete || true
-
-      - name: Check uv.lock is up to date
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          uv lock --check || (echo "❌ uv.lock is out of sync with pyproject.toml. Run 'uv lock' locally and commit the result." && exit 1)
-
-      - name: Cache the Rust build
-        if: steps.changes.outputs.decision != 'skip'
-        uses: ./.github/actions/cache-cargo-build
-
-      - name: Install dependencies
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          uv sync --frozen --group proxy-dev --group e2e-dev
-
-      - name: Cache Prisma binaries
-        if: steps.changes.outputs.decision != 'skip'
-        uses: ./.github/actions/cache-prisma-binaries
-
-      - name: Generate Prisma client
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
-
-      - name: Check ruff format
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          git diff --name-only --diff-filter=ACMR "$GATE_BASE_SHA" HEAD -- ':(glob)litellm/**/*.py' | grep -v '^litellm/enterprise/' > "$RUNNER_TEMP/ruff_format_files.txt" || true
-          if [ ! -s "$RUNNER_TEMP/ruff_format_files.txt" ]; then
-            echo "No changed litellm Python files to check with ruff format."
-            exit 0
-          fi
-          xargs uv run --no-sync ruff format --check --exclude '/enterprise/' < "$RUNNER_TEMP/ruff_format_files.txt"
-
-      - name: Debug - Check file state
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          echo "Current branch:"
-          git branch --show-current
-          echo "Last 3 commits:"
-          git log --oneline -3
-          echo "File content around line 43:"
-          head -50 litellm/litellm_core_utils/custom_logger_registry.py | tail -10
-
-      - name: Check MCP operation boundary
-        if: steps.changes.outputs.decision != 'skip'
-        run: uv run --no-sync python scripts/check_mcp_operation_boundary.py
-
-      - name: Run Ruff linting
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          cd litellm
-          uv run --no-sync ruff check .
-          cd ..
-
-      - name: Run Ruff linting (test tree)
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          uv run --no-sync ruff check --config ruff-tests.toml tests
-
-      - name: Check strict ruff rules (delta vs merge-base counts)
-        if: steps.changes.outputs.decision != 'skip'
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          uv run --no-sync python scripts/ruff_strict_gate.py --base "$GATE_BASE_SHA"
-
-      - name: Check type discipline (mutable collections / casts / type guards / kwargs / unexplained suppressions, delta vs merge-base counts)
-        if: steps.changes.outputs.decision != 'skip'
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          uv run --no-sync python scripts/type_discipline_gate.py --base "$GATE_BASE_SHA"
-
-      - name: Check test quality (zero-assert / mock-echo tests, sys.path.insert, raw env writes, litellm global mutation, credential-gated skips, conftest snapshot inventory, delta vs merge-base counts)
-        if: steps.changes.outputs.decision != 'skip'
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          uv run --no-sync python scripts/test_quality_gate.py --base "$GATE_BASE_SHA"
-
-      - name: Print OpenAI version
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          uv run --no-sync python -c "import openai; print(f'OpenAI version: {openai.__version__}')"
-
-      - name: Check basedpyright (delta vs merge-base counts)
-        if: steps.changes.outputs.decision != 'skip'
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          uv run --no-sync python scripts/type_check_gate.py --base "$GATE_BASE_SHA"
-
-      - name: Check tests/e2e basedpyright (zero errors)
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          if git diff --name-only --diff-filter=ACMRD "$GATE_BASE_SHA" HEAD -- ':(glob)tests/e2e/**/*.py' ':(glob)tests/e2e_harness/**/*.py' pyrightconfig.json | grep -q .; then
-            uv run --no-sync basedpyright tests/e2e tests/e2e_harness
-          else
-            echo "No changed tests/e2e Python files; skipping."
-          fi
-
-      - name: Run the e2e harness tests
-        if: steps.changes.outputs.decision != 'skip'
-        env:
-          LITELLM_MASTER_KEY: sk-e2e-harness-tests-reach-no-proxy
-        run: |
-          if ! git diff --name-only --diff-filter=ACMRD "$GATE_BASE_SHA" HEAD -- tests/e2e tests/e2e_harness ':(exclude)tests/e2e/ui' pyproject.toml uv.lock .github/workflows/test-linting.yml | grep -q .; then
-            echo "No changed e2e harness files; skipping."
-            exit 0
-          fi
-          retry() { "$@" || { sleep 15; "$@"; } || { sleep 30; "$@"; }; }
-          CLAUDE_VERSION="$(retry uv run --no-sync python tests/e2e/claude_code/pr_gate_version_resolver.py)"
-          tests/e2e/claude_code/cron_vm/install_claude_code.sh "$CLAUDE_VERSION" "$RUNNER_TEMP/claude-cli"
-          PATH="$RUNNER_TEMP/claude-cli:$PATH" uv run --no-sync pytest -q tests/e2e_harness
-
-      - name: Check for circular imports
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          cd litellm
-          uv run --no-sync python ../tests/documentation_tests/test_circular_imports.py
-          cd ..
-
-      - name: Check import safety
-        if: steps.changes.outputs.decision != 'skip'
-        run: |
-          uv run --no-sync python -c "from litellm import *" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)
-
-  frontend-lint:
-    name: frontend-lint
-    permissions:
-      contents: read
-    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: 1
-          persist-credentials: false
-
-      - name: Collect changed files
-        id: changed
-        env:
-          GH_TOKEN: ${{ github.token }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          merge_base=$(gh api "repos/${{ github.repository }}/compare/${BASE_SHA}...${HEAD_SHA}?per_page=1" --jq '.merge_base_commit.sha')
-          test -n "$merge_base"
-          git fetch --no-tags --depth=1 origin "$merge_base" "$HEAD_SHA"
-          : > "$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 "$merge_base" "$HEAD_SHA" -- .)
-          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-file: ui/litellm-dashboard/.nvmrc
-          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
-
-      - name: Check for dead code (knip)
-        if: ${{ !cancelled() && steps.changed.outputs.has_files == 'true' }}
-        run: npm run knip:ci
-
-  assert-ci-coverage:
-    name: assert-ci-coverage
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-    timeout-minutes: 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: Assert every test file and Dockerfile is invoked by a job
-        run: |
-          python -m pip install "pyyaml==6.0.3"
-          python .github/scripts/assert_ci_coverage.py
-
-      - name: Assert no -k expression deselects a file from every job that globs it
-        run: python .github/scripts/assert_ci_coverage.py --slices
-
-      - name: Assert .github/workflows/ holds only workflows, correctly named
-        run: python .github/scripts/assert_workflow_dir_hygiene.py
-
-  dashboard-build:
-    name: Dashboard build
-    runs-on: ubuntu-24.04
-    timeout-minutes: 30
-    steps:
-      - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Build the dashboard stage
-        run: docker build --target ui-builder -f Dockerfile .
-
-  core-checks:
-    name: Core checks (Python ${{ matrix.python-version }})
-    runs-on: ubuntu-24.04
-    timeout-minutes: 30
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
-    env:
-      LITELLM_LOCAL_MODEL_COST_MAP: "True"
-    steps:
-      - name: Checkout
-        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: ${{ matrix.python-version }}
-
-      - name: Set up uv
-        uses: ./.github/actions/setup-uv-with-retries
-        with:
-          version: "0.10.9"
-
-      - name: Install dependencies
-        run: .github/scripts/uv_sync_with_retries.sh --frozen --extra proxy --extra cli --group dev --group proxy-dev --python ${{ matrix.python-version }}
-
-      - name: Create the loopback-only network namespace
-        run: |
-          sudo ip netns add smoke
-          sudo ip netns exec smoke ip link set lo up
-          cat > "${RUNNER_TEMP}/in-netns" <<'WRAP'
-          #!/usr/bin/env bash
-          set -euo pipefail
-          exec sudo --preserve-env=LITELLM_LOCAL_MODEL_COST_MAP ip netns exec smoke setpriv --reuid "$(id -u)" --regid "$(id -g)" --init-groups -- env HOME="${HOME}" PATH="${PATH}" "$@"
-          WRAP
-          chmod +x "${RUNNER_TEMP}/in-netns"
-          echo "IN_NETNS=${RUNNER_TEMP}/in-netns" >> "${GITHUB_ENV}"
-
-      - name: Verify namespace isolation
-        run: $IN_NETNS .venv/bin/python .github/scripts/run_merge_smoke.py verify-isolation
-
-      - name: Verify interpreter version
-        run: $IN_NETNS .venv/bin/python .github/scripts/run_merge_smoke.py interpreter --expect ${{ matrix.python-version }}
-
-      - name: Import and CLI checks
-        run: $IN_NETNS .venv/bin/python .github/scripts/run_merge_smoke.py cli
-
-      - name: Proxy startup check
-        run: $IN_NETNS .venv/bin/python .github/scripts/run_merge_smoke.py proxy-startup --diagnostics-dir "${RUNNER_TEMP}/smoke-diagnostics"
-
-      - name: Upload smoke diagnostics
-        if: always()
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        with:
-          name: merge-smoke-diagnostics-py${{ matrix.python-version }}
-          path: ${{ runner.temp }}/smoke-diagnostics
-          if-no-files-found: ignore
-
-      - name: Remove the network namespace
-        if: always()
-        run: sudo ip netns delete smoke

.github/workflows/test-linting.yml

@@ -22,6 +22,16 @@ jobs:
       actions: read
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    services:
+      redis:
+        image: redis@sha256:e2debfb7956fa12c7ddc79d7e645c8cf26b30c99a6e9161ea9bf4171e1668a5f
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
@@ -156,6 +166,14 @@ jobs:
         run: |
           uv run --no-sync python scripts/test_quality_gate.py --base "$GATE_BASE_SHA"
 
+      - name: Check OpenAPI docs (POST routes without a request schema, description or 200 schema, delta vs merge-base counts)
+        if: steps.changes.outputs.decision != 'skip'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          uv sync --frozen --group proxy-dev --group e2e-dev --extra proxy
+          uv run --no-sync python scripts/openapi_docs_gate.py --base "$GATE_BASE_SHA"
+
       - name: Print OpenAI version
         if: steps.changes.outputs.decision != 'skip'
         run: |
@@ -181,8 +199,9 @@ jobs:
         if: steps.changes.outputs.decision != 'skip'
         env:
           LITELLM_MASTER_KEY: sk-e2e-harness-tests-reach-no-proxy
+          E2E_CACHE_TEST_REDIS_URL: redis://127.0.0.1:6379/0
         run: |
-          if ! git diff --name-only --diff-filter=ACMRD "$GATE_BASE_SHA" HEAD -- tests/e2e tests/e2e_harness ':(exclude)tests/e2e/ui' pyproject.toml uv.lock .github/workflows/test-linting.yml | grep -q .; then
+          if ! git diff --name-only --diff-filter=ACMRD "$GATE_BASE_SHA" HEAD -- tests/e2e tests/e2e_harness ':(exclude)tests/e2e/ui' tests/code_coverage_tests/test_provider_replay_harness.py tests/code_coverage_tests/test_provider_cache.py pyproject.toml uv.lock .github/workflows/test-linting.yml | grep -q .; then
             echo "No changed e2e harness files; skipping."
             exit 0
           fi
@@ -190,6 +209,9 @@ jobs:
           CLAUDE_VERSION="$(retry uv run --no-sync python tests/e2e/claude_code/pr_gate_version_resolver.py)"
           tests/e2e/claude_code/cron_vm/install_claude_code.sh "$CLAUDE_VERSION" "$RUNNER_TEMP/claude-cli"
           PATH="$RUNNER_TEMP/claude-cli:$PATH" uv run --no-sync pytest -q tests/e2e_harness
+          uv run --no-sync pytest --tb=short -q --noconftest -o addopts= -o "pythonpath=tests/e2e tests/e2e_harness" -p no:rerunfailures \
+            tests/code_coverage_tests/test_provider_replay_harness.py \
+            tests/code_coverage_tests/test_provider_cache.py
 
       - name: Check for circular imports
         if: steps.changes.outputs.decision != 'skip'
@@ -593,6 +615,12 @@ jobs:
       - name: check_migrations_no_data_rewrites
         run: uv run --no-sync python ./tests/code_coverage_tests/check_migrations_no_data_rewrites.py
 
+      - name: check_greptile_files_json
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_greptile_files_json.py
+
+      - name: test_check_greptile_files_json
+        run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_check_greptile_files_json.py
+
       - name: check_no_publicly_known_master_key
         run: uv run --no-sync python ./tests/code_coverage_tests/check_no_publicly_known_master_key.py
 
@@ -639,9 +667,32 @@ jobs:
 
       - name: Assert .github/workflows/ holds only workflows, correctly named
         run: python .github/scripts/assert_workflow_dir_hygiene.py
+  semgrep:
+    name: semgrep
+    permissions:
+      contents: read
+    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: ./.github/actions/setup-uv-with-retries
+        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
   lint-passed:
     name: lint passed
-    needs: [python, secret-scan, ui, ui-api-types, code-quality, ci-coverage]
+    needs: [python, secret-scan, ui, ui-api-types, code-quality, ci-coverage, semgrep]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 2

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

@@ -1,40 +0,0 @@
-name: UI Build Check
-permissions:
-  contents: read
-  pull-requests: read
-
-on:
-  pull_request:
-    branches:
-      - main
-      - "litellm_**"
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  build-ui:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-
-      - name: Detect relevant changes
-        id: changes
-        uses: ./.github/actions/detect-changes
-        with:
-          category: ui
-
-      # Built through the image stage rather than the checkout, because the
-      # stage copies ui/litellm-dashboard/ alone: an import reaching above the
-      # dashboard root resolves in a checkout and fails in every image we ship.
-      # Dockerfile, docker/Dockerfile.non_root and ui/Dockerfile share this
-      # stage verbatim, so building one covers all three.
-      - name: Build the dashboard as the shipped images build it
-        if: steps.changes.outputs.decision != 'skip'
-        run: docker build --target ui-builder -f Dockerfile .

.github/workflows/test-merge-smoke.yml

@@ -91,9 +91,181 @@ jobs:
         if: always()
         run: sudo ip netns delete smoke
 
+  all-extras:
+    name: all-extras-py${{ matrix.python-version }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    env:
+      LITELLM_LOCAL_MODEL_COST_MAP: "True"
+    steps:
+      - name: Checkout
+        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: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: ./.github/actions/setup-uv-with-retries
+        with:
+          version: "0.10.9"
+
+      - name: Install every extra and dependency group
+        run: .github/scripts/uv_sync_with_retries.sh --frozen --all-groups --all-extras --python ${{ matrix.python-version }}
+
+      - name: Import the SDK, the proxy server and the enterprise package
+        run: .venv/bin/python -c "import litellm, litellm.proxy.proxy_server, litellm_enterprise"
+
+  windows-sdk:
+    name: windows-sdk
+    runs-on: windows-2025
+    timeout-minutes: 10
+    env:
+      LITELLM_LOCAL_MODEL_COST_MAP: "True"
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        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.11"
+
+      - name: Set up uv
+        uses: ./.github/actions/setup-uv-with-retries
+        with:
+          version: "0.10.9"
+
+      - name: Install dependencies
+        run: .github/scripts/uv_sync_with_retries.sh --frozen --no-install-workspace --group dev --python 3.11
+
+      - name: Run the Windows tests
+        run: uv run --no-sync python -m pytest --tb=short -v tests/windows_tests
+
+  proxy-build-from-pip:
+    name: proxy-build-from-pip
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    services:
+      postgres:
+        image: postgres:14@sha256:6a70deda415ec296f977890e11aba04a0db9f632a362e3fce45e845e3db74f26
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: circle_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 30
+    steps:
+      - name: Checkout
+        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: ./.github/actions/setup-uv-with-retries
+        with:
+          version: "0.10.9"
+
+      - name: Install the test client dependencies
+        run: .github/scripts/uv_sync_with_retries.sh --frozen --no-install-workspace --extra proxy --group dev --python 3.12
+
+      - name: Build the image from the published package
+        run: docker build -t litellm-build-from-pip:smoke -f docker/build_from_pip/Dockerfile.build_from_pip .
+
+      - name: Start the fake OpenAI endpoint
+        run: |
+          nohup .venv/bin/python tests/_fake_openai_endpoint_server.py --host 0.0.0.0 --port 8190 > "${RUNNER_TEMP}/fake-openai.log" 2>&1 &
+          for _ in $(seq 1 30); do
+            curl -sf http://localhost:8190/health > /dev/null && exit 0
+            sleep 1
+          done
+          cat "${RUNNER_TEMP}/fake-openai.log"
+          exit 1
+
+      - name: Generate a master key
+        run: |
+          key="sk-$(openssl rand -hex 16)"
+          echo "::add-mask::${key}"
+          echo "LITELLM_MASTER_KEY=${key}" >> "${GITHUB_ENV}"
+
+      - name: Start the proxy container
+        run: |
+          docker run -d \
+            -p 4000:4000 \
+            -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
+            -e LITELLM_MASTER_KEY \
+            -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
+            -e OTEL_EXPORTER=in_memory \
+            -e USE_DDTRACE=True \
+            -e GCS_FLUSH_INTERVAL=1 \
+            -e LITELLM_LOG=ERROR \
+            --add-host host.docker.internal:host-gateway \
+            --name litellm-build-from-pip \
+            -v "${GITHUB_WORKSPACE}/docker/build_from_pip/litellm_config.yaml:/app/config.yaml" \
+            litellm-build-from-pip:smoke \
+            --config /app/config.yaml \
+            --port 4000
+          for _ in $(seq 1 150); do
+            curl -sf --max-time 5 -o /dev/null http://localhost:4000 && exit 0
+            sleep 2
+          done
+          exit 1
+
+      - name: Run the startup tests
+        shell: bash
+        run: |
+          set -euo pipefail
+          base_url=http://localhost:4000
+          readiness_response="$(curl -sS --fail-with-body --write-out $'\n%{http_code}' "${base_url}/health/readiness")"
+          readiness_status="${readiness_response##*$'\n'}"
+          readiness_body="${readiness_response%$'\n'*}"
+          [[ "${readiness_status}" == "200" ]]
+          jq -e '.status == "healthy" or .status == "connected"' <<< "${readiness_body}" > /dev/null
+          liveness_status="$(curl -sS --fail-with-body --output /dev/null --write-out '%{http_code}' "${base_url}/health/liveness")"
+          [[ "${liveness_status}" == "200" ]]
+          completion_response="$(curl -sS --fail-with-body --write-out $'\n%{http_code}' \
+            --header "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
+            --header 'Content-Type: application/json' \
+            --data '{"model":"gpt-4","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}]}' \
+            "${base_url}/chat/completions")"
+          completion_status="${completion_response##*$'\n'}"
+          completion_body="${completion_response%$'\n'*}"
+          [[ "${completion_status}" == "200" ]]
+          jq -e '
+            (.choices | length) == 1 and
+            .choices[0].message.role == "assistant" and
+            .choices[0].message.content == "Hello! This is a mock response from the fake OpenAI endpoint."
+          ' <<< "${completion_body}" > /dev/null
+
+      - name: Show the proxy logs
+        if: always()
+        run: docker logs litellm-build-from-pip || true
+
   smoke-passed:
     name: smoke passed
-    needs: [dashboard-build, core-checks]
+    needs: [dashboard-build, core-checks, all-extras, windows-sdk, proxy-build-from-pip]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 2

.github/workflows/test-rust.yml

@@ -6,9 +6,9 @@ on:
       - "litellm-rust/**"
       - "litellm/rust_bridge/**"
       - "scripts/generate_trace_types.py"
-      - "scripts/generate_lens_contract.py"
-      - "litellm/proxy/lens/**"
       - "scripts/trace_codegen/**"
+      - "scripts/lens_assets/**"
+      - "litellm/tracing/**"
       - "tests/test_litellm_rust/**"
       - "litellm/integrations/custom_logger.py"
       - "litellm/litellm_core_utils/litellm_logging.py"
@@ -18,7 +18,6 @@ on:
       - "litellm/ocr/**"
       - "litellm/llms/base_llm/ocr/**"
       - "litellm/llms/custom_httpx/llm_http_handler.py"
-      - "tests/test_litellm/conftest.py"
       - "Makefile"
       - ".cargo/**"
       - "pyproject.toml"
@@ -37,9 +36,9 @@ on:
       - "litellm-rust/**"
       - "litellm/rust_bridge/**"
       - "scripts/generate_trace_types.py"
-      - "scripts/generate_lens_contract.py"
-      - "litellm/proxy/lens/**"
       - "scripts/trace_codegen/**"
+      - "scripts/lens_assets/**"
+      - "litellm/tracing/**"
       - "tests/test_litellm_rust/**"
       - "litellm/integrations/custom_logger.py"
       - "litellm/litellm_core_utils/litellm_logging.py"
@@ -49,7 +48,6 @@ on:
       - "litellm/ocr/**"
       - "litellm/llms/base_llm/ocr/**"
       - "litellm/llms/custom_httpx/llm_http_handler.py"
-      - "tests/test_litellm/conftest.py"
       - "Makefile"
       - ".cargo/**"
       - "pyproject.toml"
@@ -93,7 +91,7 @@ jobs:
           cache-on-failure: true
           save-if: ${{ github.ref == 'refs/heads/main' }}
 
-      - run: cargo clippy --workspace --all-targets --locked --features litellm-traces/schema,litellm-traces-clickhouse/schema -- -D warnings
+      - run: cargo clippy --workspace --all-targets --locked -- -D warnings
 
   rust-test:
     runs-on: ubuntu-latest
@@ -139,11 +137,7 @@ jobs:
         working-directory: .
         run: uv run scripts/generate_trace_types.py --check
 
-      - name: Check generated Lens contracts
-        working-directory: .
-        run: uv run scripts/generate_lens_contract.py --check
-
-      - run: cargo nextest run --workspace --locked --features litellm-traces/schema,litellm-traces-clickhouse/schema
+      - run: cargo nextest run --workspace --locked
 
       - run: cargo test --workspace --doc --locked
 

.github/workflows/test-semgrep.yml

@@ -1,37 +0,0 @@
-name: Semgrep
-
-on:
-  pull_request:
-    branches:
-      - main
-      - "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: ./.github/actions/setup-uv-with-retries
-        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.yml

@@ -140,6 +140,7 @@ jobs:
               tests/unit/batch_completion
               tests/unit/decisions
               tests/unit/litellm_core_utils
+              tests/unit/systemone
             python-version: "3.12"
             workers: 4
             reruns: 0
@@ -173,8 +174,6 @@ jobs:
 
           - shard: integrations
             test-path: |-
-              tests/test_litellm/integrations
-              tests/test_litellm/tracing
               tests/unit/integrations
             python-version: "3.12"
             workers: 4
@@ -214,7 +213,7 @@ jobs:
             job-timeout-minutes: 60
             dist: loadscope
 
-          - shard: llms-a-to-g
+          - shard: llms-providers
             test-path: |-
               tests/unit/llms/test_cache_control_and_reasoning.py
               tests/unit/llms/test_custom_llm.py
@@ -272,16 +271,6 @@ jobs:
               tests/unit/llms/github_copilot
               tests/unit/llms/gradient_ai
               tests/unit/llms/groq
-              --ignore=tests/unit/llms/base_llm/batches/base_batches_config_test.py
-            python-version: "3.12"
-            workers: 4
-            reruns: 0
-            timeout-minutes: 20
-            job-timeout-minutes: 60
-            dist: loadscope
-
-          - shard: llms-h-to-z
-            test-path: |-
               tests/unit/llms/heroku
               tests/unit/llms/hosted_vllm
               tests/unit/llms/huggingface
@@ -300,6 +289,8 @@ jobs:
               tests/unit/llms/lm_studio
               tests/unit/llms/manus
               tests/unit/llms/meta_llama
+              tests/unit/llms/microsoft_365_copilot
+              tests/unit/llms/milvus
               tests/unit/llms/minimax
               tests/unit/llms/mistral
               tests/unit/llms/modelscope
@@ -336,6 +327,7 @@ jobs:
               tests/unit/llms/sagemaker
               tests/unit/llms/sail
               tests/unit/llms/sambanova
+              tests/unit/llms/scaledown
               tests/unit/llms/sap
               tests/unit/llms/scaleway
               tests/unit/llms/searchapi
@@ -344,6 +336,7 @@ jobs:
               tests/unit/llms/snowflake
               tests/unit/llms/soniox
               tests/unit/llms/stability
+              tests/unit/llms/strands_decider
               tests/unit/llms/tavily
               tests/unit/llms/tencent
               tests/unit/llms/tinyfish
@@ -361,6 +354,7 @@ jobs:
               tests/unit/llms/xinference
               tests/unit/llms/you_com
               tests/unit/llms/zai
+              --ignore=tests/unit/llms/base_llm/batches/base_batches_config_test.py
             python-version: "3.12"
             workers: 4
             reruns: 0
@@ -381,7 +375,6 @@ jobs:
 
           - shard: root
             test-path: >-
-              tests/test_litellm/test_*.py
               tests/unit/test_*.py
             python-version: "3.12"
             workers: 4
@@ -400,16 +393,6 @@ jobs:
             job-timeout-minutes: 60
             dist: loadscope
 
-          - shard: router-unit-tests
-            test-path: >-
-              tests/router_unit_tests
-            python-version: "3.12"
-            workers: 0
-            reruns: 0
-            timeout-minutes: 10
-            job-timeout-minutes: 60
-            dist: loadscope
-
           - shard: endpoints
             test-path: >-
               tests/unit/a2a_protocol
@@ -454,9 +437,9 @@ jobs:
 
           - shard: enterprise-repositories-secrets
             test-path: >-
-              tests/proxy_behavior/lens/test_connection.py
               tests/unit/enterprise/enterprise_callbacks/test_callback_controls.py
               tests/unit/enterprise/enterprise_callbacks/test_llm_guard.py
+              tests/unit/enterprise/enterprise_callbacks/test_pagerduty_alerting.py
               tests/unit/enterprise/enterprise_callbacks/test_secret_detection.py
               tests/unit/integration_support
               tests/unit/models
@@ -780,7 +763,7 @@ jobs:
 
           - shard: proxy-server-core
             test-path: |-
-              tests/proxy_unit_tests/test_proxy_server_gemini_pass_through.py
+              tests/unit/proxy/pass_through_endpoints/test_llm_passthrough_endpoints.py
               tests/unit/proxy/test__lazy_features.py
               tests/unit/proxy/test_aproxy_startup.py
               tests/unit/proxy/test_proxy_server.py
@@ -821,7 +804,7 @@ jobs:
 
           - shard: custom-logging
             test-path: |-
-              tests/proxy_unit_tests/test_proxy_custom_logger.py
+              tests/unit/proxy/test_proxy_server_custom_logger.py
               tests/unit/proxy/test_custom_callback_input.py
               tests/unit/proxy/test_custom_logger_s3_gcs.py
             python-version: "3.12"
@@ -871,17 +854,6 @@ jobs:
             job-timeout-minutes: 60
             dist: loadscope
 
-          - shard: guardrails-tests
-            test-path: >-
-              tests/guardrails_tests
-              --deselect=tests/guardrails_tests/test_custom_guardrail.py::test_get_guardrail_dynamic_request_body_params
-            python-version: "3.12"
-            workers: 4
-            reruns: 2
-            timeout-minutes: 15
-            job-timeout-minutes: 60
-            dist: loadscope
-
           - shard: budgets
             test-path: |-
               tests/unit/proxy/auth/test_default_end_user_budget_simple.py
@@ -896,7 +868,7 @@ jobs:
 
           - shard: endpoints-and-responses
             test-path: |-
-              tests/proxy_unit_tests/test_proxy_exception_mapping.py
+              tests/unit/proxy/test_proxy_server_exception_mapping.py
               tests/unit/proxy/lens
               tests/unit/proxy/auth/test_models_fallback_endpoint.py
               tests/unit/proxy/common_utils/test_check_batch_cost.py
@@ -923,7 +895,7 @@ jobs:
 
           - shard: lens-python-310
             test-path: >-
-              tests/unit/proxy/lens/test_inference.py
+              tests/unit/proxy/lens
             python-version: "3.10"
             workers: 0
             reruns: 0
@@ -935,6 +907,7 @@ jobs:
         timeout-minutes: 3
         with:
           persist-credentials: false
+          fetch-depth: ${{ matrix.shard == 'db-and-spend' && '0' || '1' }}
 
       - name: Detect relevant changes
         id: changes
@@ -967,11 +940,13 @@ jobs:
         with:
           artifact: ${{ needs.rust-bridge.outputs.artifact }}
 
-      - name: Install dependencies
+      - name: Install dependencies and check schema
         if: steps.changes.outputs.decision != 'skip'
         timeout-minutes: 8
         env:
           RUST_BRIDGE_ARTIFACT: ${{ needs.rust-bridge.outputs.artifact }}
+          UNIT_SHARD: ${{ matrix.shard }}
+          SCHEMA_BASE_REF: origin/${{ github.event.repository.default_branch }}
         run: |
           diff -u model_prices_and_context_window.json litellm/model_prices_and_context_window_backup.json
           if [ -z "$RUST_BRIDGE_ARTIFACT" ]; then
@@ -983,6 +958,9 @@ jobs:
             uv run --no-sync python -c "import importlib.metadata; import litellm.rust_bridge._native; print(importlib.metadata.version('litellm'))"
           fi
           uv run --no-sync python -c 'import os, sys; print(sys.version); assert f"{sys.version_info.major}.{sys.version_info.minor}" == os.environ["UV_PYTHON"]'
+          if [ "$UNIT_SHARD" = "db-and-spend" ]; then
+            uv run --no-sync python scripts/check_schema_compatibility.py --base-ref "$SCHEMA_BASE_REF"
+          fi
 
       - name: Cache Prisma binaries
         if: steps.changes.outputs.decision != 'skip'
@@ -1235,6 +1213,117 @@ jobs:
           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
+  helm:
+    name: helm
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Helm 3.11.1
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
+        with:
+          version: "3.11.1"
+
+      - name: Download and verify Helm Unit Test Plugin
+        run: |
+          curl -fsSLo "$RUNNER_TEMP/helm-unittest.tgz" https://github.com/helm-unittest/helm-unittest/releases/download/v0.8.2/helm-unittest-linux-amd64-0.8.2.tgz
+          echo "56ab3091e6fa52a7c92ee951def9bed957f295d9ce98483aed404e748d7b3a94  $RUNNER_TEMP/helm-unittest.tgz" | sha256sum -c -
+
+      - name: Install Helm Unit Test Plugin
+        run: |
+          PLUGIN_DIR="$(helm env HELM_PLUGINS)/helm-unittest"
+          mkdir -p "$PLUGIN_DIR"
+          tar -xzf "$RUNNER_TEMP/helm-unittest.tgz" -C "$PLUGIN_DIR"
+          helm plugin list
+
+      - name: Run unit tests
+        run: |
+          for chart in helm/litellm-helm helm/litellm; do
+            declared="$(grep -h '^suite:' "$chart"/tests/*.yaml | wc -l | tr -d '[:space:]')"
+            output="$(mktemp)"
+            helm unittest -f 'tests/*.yaml' "$chart" | tee "$output"
+            executed="$(sed -n 's/^Test Suites:.*[[:space:]]\([0-9][0-9]*\) total$/\1/p' "$output")"
+            if [ "$declared" != "$executed" ]; then
+              echo "::error::$chart declares $declared test suites but helm-unittest ran $executed. Suites are being skipped silently, so their assertions never execute."
+              exit 1
+            fi
+            echo "$chart: all $declared declared test suites ran"
+          done
+  openai-sdk-compat:
+    name: OpenAI ${{ matrix.openai-version }} compatibility
+    permissions:
+      contents: read
+      pull-requests: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        openai-version: ["2.20.0", "3.0.0", "3.25.0"]
+    env:
+      LITELLM_LOCAL_MODEL_COST_MAP: "True"
+      PYTHONPATH: ${{ github.workspace }}
+      UV_PYTHON: "3.10"
+      OPENAI_VERSION: ${{ matrix.openai-version }}
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+
+      - name: Detect relevant changes
+        id: changes
+        timeout-minutes: 2
+        uses: ./.github/actions/detect-changes
+
+      - name: Set up Python
+        if: steps.changes.outputs.decision != 'skip'
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+
+      - name: Set up uv
+        if: steps.changes.outputs.decision != 'skip'
+        uses: ./.github/actions/setup-uv-with-retries
+        with:
+          version: "0.10.9"
+
+      - name: Install dependencies
+        if: steps.changes.outputs.decision != 'skip'
+        run: |
+          .github/scripts/uv_sync_with_retries.sh --frozen --group dev --group proxy-dev --extra proxy --no-install-workspace
+          uv pip install "openai==${OPENAI_VERSION:?}" --exclude-newer-package openai=2026-10-07T00:00:00Z
+          uv run --no-sync python -c 'import os, openai; assert openai.__version__ == os.environ["OPENAI_VERSION"], openai.__version__'
+
+      - name: Run OpenAI SDK compatibility tests
+        if: steps.changes.outputs.decision != 'skip'
+        run: |
+          uv run --no-sync pytest \
+            tests/unit/llms/openai/test_openai.py \
+            tests/unit/llms/openai/test_openai_common_utils.py \
+            tests/unit/llms/openai/test_openai_file_content_streaming.py \
+            tests/unit/test_openai_embedding_encoding_format_default.py \
+            tests/unit/llms/inception/test_inception_completion_transformation.py::test_inception_fim_targets_fim_endpoint \
+            tests/unit/llms/inception/test_inception_completion_transformation.py::test_inception_fim_async \
+            tests/unit/llms/azure/test_azure_exception_mapping.py \
+            tests/unit/test_completion_timeout_resolution.py \
+            tests/unit/types/test_router.py \
+            tests/unit/test_exception_header_preservation.py \
+            tests/unit/integrations/otel/test_otel_v2_sources_of_truth.py::test_speech_binary_response_still_streaming_reports_the_bytes_downloaded_so_far \
+            --tb=short -q
+
+      - name: Run workload identity tests with SDK 3
+        if: steps.changes.outputs.decision != 'skip' && startsWith(matrix.openai-version, '3.')
+        run: uv run --no-sync pytest tests/unit/llms/openai/test_openai_workload_identity.py --tb=short -q
+
+      - name: Check consumer types with the installed SDK
+        if: steps.changes.outputs.decision != 'skip'
+        run: uv run --no-sync basedpyright --pythonpath .venv/bin/python --project tests/typing/pyrightconfig.json
   coverage:
     name: coverage
     needs: unit
@@ -1283,7 +1372,7 @@ jobs:
   unit-passed:
     name: unit passed
     permissions: {}
-    needs: [rust-bridge, assert-shard-coverage, unit, ui-unit, docs]
+    needs: [rust-bridge, assert-shard-coverage, unit, ui-unit, docs, helm, openai-sdk-compat]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 2

.gitignore

@@ -154,3 +154,4 @@ coverage-rust.xml
 
 # make lens-dev worker token, generated config and logs
 .lens-dev/
+.mypy_cache/

.greptile/files.json

@@ -0,0 +1,655 @@
+{
+  "files": [
+    {
+      "path": "litellm/_v2/AGENTS.md",
+      "description": "Conventions for code under litellm/_v2/",
+      "scope": [
+        "litellm/_v2/**"
+      ]
+    },
+    {
+      "path": "litellm/_v2/cache/AGENTS.md",
+      "description": "Conventions for code under litellm/_v2/cache/",
+      "scope": [
+        "litellm/_v2/cache/**"
+      ]
+    },
+    {
+      "path": "litellm/proxy/_experimental/mcp_server/AGENTS.md",
+      "description": "Conventions for code under litellm/proxy/_experimental/mcp_server/",
+      "scope": [
+        "litellm/proxy/_experimental/mcp_server/**"
+      ]
+    },
+    {
+      "path": "litellm/rust_bridge/AGENTS.md",
+      "description": "Conventions for code under litellm/rust_bridge/",
+      "scope": [
+        "litellm/rust_bridge/**"
+      ]
+    },
+    {
+      "path": "litellm/rust_bridge/host/AGENTS.md",
+      "description": "Conventions for code under litellm/rust_bridge/host/",
+      "scope": [
+        "litellm/rust_bridge/host/**"
+      ]
+    },
+    {
+      "path": "litellm/tracing/AGENTS.md",
+      "description": "Conventions for code under litellm/tracing/",
+      "scope": [
+        "litellm/tracing/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/",
+      "scope": [
+        "litellm-rust/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/cache-response/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/cache-response/",
+      "scope": [
+        "litellm-rust/crates/cache-response/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/callbacks-legacy-python/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/callbacks-legacy-python/",
+      "scope": [
+        "litellm-rust/crates/callbacks-legacy-python/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/coroutine/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/coroutine/",
+      "scope": [
+        "litellm-rust/crates/coroutine/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/gateway/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/gateway/",
+      "scope": [
+        "litellm-rust/crates/gateway/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/gateway-auth/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/gateway-auth/",
+      "scope": [
+        "litellm-rust/crates/gateway-auth/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/gateway-inference/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/gateway-inference/",
+      "scope": [
+        "litellm-rust/crates/gateway-inference/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/gateway-mcp/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/gateway-mcp/",
+      "scope": [
+        "litellm-rust/crates/gateway-mcp/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/host/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/host/",
+      "scope": [
+        "litellm-rust/crates/host/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/host/src/machine/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/host/src/machine/",
+      "scope": [
+        "litellm-rust/crates/host/src/machine/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/host-http/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/host-http/",
+      "scope": [
+        "litellm-rust/crates/host-http/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/host-native/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/host-native/",
+      "scope": [
+        "litellm-rust/crates/host-native/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/host-python/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/host-python/",
+      "scope": [
+        "litellm-rust/crates/host-python/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/http/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/http/",
+      "scope": [
+        "litellm-rust/crates/http/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/inference/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/inference/",
+      "scope": [
+        "litellm-rust/crates/inference/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/inference-chat/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/inference-chat/",
+      "scope": [
+        "litellm-rust/crates/inference-chat/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/inference-messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/inference-messages/",
+      "scope": [
+        "litellm-rust/crates/inference-messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/inference-ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/inference-ocr/",
+      "scope": [
+        "litellm-rust/crates/inference-ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/inference-responses/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/inference-responses/",
+      "scope": [
+        "litellm-rust/crates/inference-responses/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/inference-transcription/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/inference-transcription/",
+      "scope": [
+        "litellm-rust/crates/inference-transcription/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/",
+      "scope": [
+        "litellm-rust/crates/llms/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/anthropic/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/anthropic/",
+      "scope": [
+        "litellm-rust/crates/llms/src/anthropic/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/anthropic/batches/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/anthropic/batches/",
+      "scope": [
+        "litellm-rust/crates/llms/src/anthropic/batches/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/anthropic/chat/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/anthropic/chat/",
+      "scope": [
+        "litellm-rust/crates/llms/src/anthropic/chat/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/anthropic/count_tokens/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/anthropic/count_tokens/",
+      "scope": [
+        "litellm-rust/crates/llms/src/anthropic/count_tokens/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/anthropic/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/anthropic/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/anthropic/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/aws_textract/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/aws_textract/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms/src/aws_textract/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/azure_ai/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/azure_ai/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/azure_ai/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/azure_ai/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/azure_ai/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms/src/azure_ai/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/base_llm/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/base_llm/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/base_llm/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/bedrock/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/bedrock/",
+      "scope": [
+        "litellm-rust/crates/llms/src/bedrock/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/bedrock/audio_transcription/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/bedrock/audio_transcription/",
+      "scope": [
+        "litellm-rust/crates/llms/src/bedrock/audio_transcription/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/bedrock/chat/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/bedrock/chat/",
+      "scope": [
+        "litellm-rust/crates/llms/src/bedrock/chat/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/bedrock/claude_platform/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/bedrock/claude_platform/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/bedrock/claude_platform/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/bedrock/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/bedrock/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/bedrock/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/bedrock_mantle/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/bedrock_mantle/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/bedrock_mantle/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/cohere/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/cohere/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms/src/cohere/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/deepseek/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/deepseek/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/deepseek/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/minimax/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/minimax/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/minimax/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/mistral/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/mistral/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms/src/mistral/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/openai/responses/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/openai/responses/",
+      "scope": [
+        "litellm-rust/crates/llms/src/openai/responses/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/openai_like/chat/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/openai_like/chat/",
+      "scope": [
+        "litellm-rust/crates/llms/src/openai_like/chat/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/openrouter/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/openrouter/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/openrouter/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/reducto/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/reducto/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms/src/reducto/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/tencent/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/tencent/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/tencent/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/vertex_ai/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/vertex_ai/messages/",
+      "scope": [
+        "litellm-rust/crates/llms/src/vertex_ai/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms/src/vertex_ai/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms/src/vertex_ai/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms/src/vertex_ai/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/",
+      "scope": [
+        "litellm-rust/crates/llms-types/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/formats/audio_transcription/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/formats/audio_transcription/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/formats/audio_transcription/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/formats/batches/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/formats/batches/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/formats/batches/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/formats/chat_completions/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/formats/chat_completions/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/formats/chat_completions/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/formats/messages/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/formats/messages/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/formats/messages/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/formats/ocr/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/formats/ocr/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/formats/ocr/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/formats/responses/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/formats/responses/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/formats/responses/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/providers/anthropic/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/providers/anthropic/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/providers/anthropic/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/providers/bedrock/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/providers/bedrock/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/providers/bedrock/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/providers/minimax/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/providers/minimax/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/providers/minimax/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/llms-types/src/providers/vertex_ai/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/llms-types/src/providers/vertex_ai/",
+      "scope": [
+        "litellm-rust/crates/llms-types/src/providers/vertex_ai/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/model-catalog/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/model-catalog/",
+      "scope": [
+        "litellm-rust/crates/model-catalog/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/python-bridge/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/python-bridge/",
+      "scope": [
+        "litellm-rust/crates/python-bridge/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/python-bridge/src/cache/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/python-bridge/src/cache/",
+      "scope": [
+        "litellm-rust/crates/python-bridge/src/cache/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/python-bridge/src/cache/native/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/python-bridge/src/cache/native/",
+      "scope": [
+        "litellm-rust/crates/python-bridge/src/cache/native/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/python-bridge/src/cache/python/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/python-bridge/src/cache/python/",
+      "scope": [
+        "litellm-rust/crates/python-bridge/src/cache/python/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/python-bridge/src/routes/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/python-bridge/src/routes/",
+      "scope": [
+        "litellm-rust/crates/python-bridge/src/routes/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/python-compat/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/python-compat/",
+      "scope": [
+        "litellm-rust/crates/python-compat/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/secrets-aws/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/secrets-aws/",
+      "scope": [
+        "litellm-rust/crates/secrets-aws/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/secrets-azure/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/secrets-azure/",
+      "scope": [
+        "litellm-rust/crates/secrets-azure/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/secrets-cyberark/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/secrets-cyberark/",
+      "scope": [
+        "litellm-rust/crates/secrets-cyberark/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/secrets-google/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/secrets-google/",
+      "scope": [
+        "litellm-rust/crates/secrets-google/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/secrets-hashicorp/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/secrets-hashicorp/",
+      "scope": [
+        "litellm-rust/crates/secrets-hashicorp/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/crates/storage-clickhouse/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/crates/storage-clickhouse/",
+      "scope": [
+        "litellm-rust/crates/storage-clickhouse/**"
+      ]
+    },
+    {
+      "path": "litellm-rust/docs/adrs/AGENTS.md",
+      "description": "Conventions for code under litellm-rust/docs/adrs/",
+      "scope": [
+        "litellm-rust/docs/adrs/**"
+      ]
+    },
+    {
+      "path": "tests/AGENTS.md",
+      "description": "Conventions for code under tests/",
+      "scope": [
+        "tests/**"
+      ]
+    },
+    {
+      "path": "tests/e2e/AGENTS.md",
+      "description": "Conventions for code under tests/e2e/",
+      "scope": [
+        "tests/e2e/**"
+      ]
+    },
+    {
+      "path": "tests/e2e_harness/AGENTS.md",
+      "description": "Conventions for code under tests/e2e_harness/",
+      "scope": [
+        "tests/e2e_harness/**"
+      ]
+    },
+    {
+      "path": "tests/integration/AGENTS.md",
+      "description": "Conventions for code under tests/integration/",
+      "scope": [
+        "tests/integration/**"
+      ]
+    },
+    {
+      "path": "tests/integration/translation/AGENTS.md",
+      "description": "Conventions for code under tests/integration/translation/",
+      "scope": [
+        "tests/integration/translation/**"
+      ]
+    },
+    {
+      "path": "tests/rust-python-harness/AGENTS.md",
+      "description": "Conventions for code under tests/rust-python-harness/",
+      "scope": [
+        "tests/rust-python-harness/**"
+      ]
+    },
+    {
+      "path": "tests/rust-python-harness/strategies/e2e_parity/AGENTS.md",
+      "description": "Conventions for code under tests/rust-python-harness/strategies/e2e_parity/",
+      "scope": [
+        "tests/rust-python-harness/strategies/e2e_parity/**"
+      ]
+    },
+    {
+      "path": "tests/rust-python-harness/strategies/trace_parity/AGENTS.md",
+      "description": "Conventions for code under tests/rust-python-harness/strategies/trace_parity/",
+      "scope": [
+        "tests/rust-python-harness/strategies/trace_parity/**"
+      ]
+    },
+    {
+      "path": "tests/rust-python-harness/strategies/unit_tests_parity/AGENTS.md",
+      "description": "Conventions for code under tests/rust-python-harness/strategies/unit_tests_parity/",
+      "scope": [
+        "tests/rust-python-harness/strategies/unit_tests_parity/**"
+      ]
+    },
+    {
+      "path": "tests/rust-python-harness/strategies/unit_tests_rust/AGENTS.md",
+      "description": "Conventions for code under tests/rust-python-harness/strategies/unit_tests_rust/",
+      "scope": [
+        "tests/rust-python-harness/strategies/unit_tests_rust/**"
+      ]
+    },
+    {
+      "path": "tests/test_litellm_rust/AGENTS.md",
+      "description": "Conventions for code under tests/test_litellm_rust/",
+      "scope": [
+        "tests/test_litellm_rust/**"
+      ]
+    },
+    {
+      "path": "tests/unit/AGENTS.md",
+      "description": "Conventions for code under tests/unit/",
+      "scope": [
+        "tests/unit/**"
+      ]
+    },
+    {
+      "path": "tests/unit/rust_bridge/AGENTS.md",
+      "description": "Conventions for code under tests/unit/rust_bridge/",
+      "scope": [
+        "tests/unit/rust_bridge/**"
+      ]
+    },
+    {
+      "path": "ui/litellm-dashboard/AGENTS.md",
+      "description": "Conventions for code under ui/litellm-dashboard/",
+      "scope": [
+        "ui/litellm-dashboard/**"
+      ]
+    },
+    {
+      "path": "ui/litellm-dashboard/src/components/chat/AGENTS.md",
+      "description": "Conventions for code under ui/litellm-dashboard/src/components/chat/",
+      "scope": [
+        "ui/litellm-dashboard/src/components/chat/**"
+      ]
+    }
+  ]
+}

AGENTS.md

@@ -25,7 +25,7 @@ Same thing for bug fixes. The tests should make it so that this specific bug can
 
 Never test structure of code only function of it
 
-A test must only fail when litellm code changes. Never pin facts we don't own (a vendor's price, a third party's field, an upstream default, today's date) as literals or as "X must be absent"; assert the invariant our code guarantees instead, e.g. two rows agree, a value is within range, a field is derived from another. If an outside fact is truly load-bearing, cite its source and date next to the assertion so a reader can tell stale from broken
+A test must only fail when litellm code changes. Never pin facts we don't own (a vendor's price, a third party's field, an upstream default, today's date) as literals or as "X must be absent". Assert the invariant our code guarantees instead, e.g. two rows agree, a value is within range, a field is derived from another. If an outside fact is truly load-bearing, cite its source and date next to the assertion so a reader can tell stale from broken
 
 `tests/unit/` mirrors `litellm/` in a parallel path (see `tests/unit/AGENTS.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
 
@@ -33,20 +33,20 @@ End-to-end tests belong in `tests/e2e/` and must follow the harness conventions
 
 When creating PRs, target the repository's current default branch for both internal and external / OSS contributions. Check it with `python3 scripts/default_branch.py --branch` instead of assuming a branch name or relying on cached `origin/HEAD`
 
-When writing a PR body, treat the comments and imperative instructions inside .github/pull_request_template.md as rules to follow, not just layout. Agent harnesses may strip HTML comments from copies of that file injected into context, so read .github/pull_request_template.md from disk before writing a PR body to make sure you see every comment rule. A section you have nothing to put in (Relevant issues, Affected release, Linear ticket, Caveats, QA runbook, and so on) is removed entirely, heading included, never left as an empty title
+When writing a PR body, treat the comments and imperative instructions inside .github/PULL_REQUEST_TEMPLATE/general.md as rules to follow, not just layout. Agent harnesses may strip HTML comments from copies of that file injected into context, so read .github/PULL_REQUEST_TEMPLATE/general.md from disk before writing a PR body to make sure you see every comment rule. A section you have nothing to put in (Relevant issues, Affected release, Linear ticket, Caveats, QA runbook, and so on) is removed entirely, heading included, never left as an empty title
 
 Same applies for filing bug reports and feature requests, with .github/ISSUE_TEMPLATE/bug_report.yml and .github/ISSUE_TEMPLATE/feature_request.yml, respectively
 
 If you're resolving a linear ticket, in the "## Linear ticket" section of the PR, say "Resolves LIT-1234", replacing "LIT-1234" with the actual ticket id that you're resolving. If you don't have the ticket id, don't make one up or search for it. Just drop the section
 
-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`; the Admin UI dev server is `npm run dev` in `ui/litellm-dashboard`, served on port 3000) 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, or the main use case runs through a headful agentic coding tool like Claude Code or Codex, drive that surface yourself and embed your own before and after screenshots of it in the PR (the Admin UI page, or what the coding tool shows), next to an ordered list of the URLs to go to (e.g., http://localhost:4000/ui/?page=logs), where to click, and what fields to fill out so a reviewer can reproduce it
+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`. The Admin UI dev server is `npm run dev` in `ui/litellm-dashboard`, served on port 3000) 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, or the main use case runs through a headful agentic coding tool like Claude Code or Codex, drive that surface yourself and embed your own before and after screenshots of it in the PR (the Admin UI page, or what the coding tool shows), next to an ordered list of the URLs to go to (e.g., http://localhost:4000/ui/?page=logs), where to click, and what fields to fill out so a reviewer can reproduce it
 
 If you ever write any human-facing text (pull requests, issues, commit messages, discussion posts, github comments, release notes, docs, etc.), always follow these guidelines to sound less AI-y:
 - don't use emojis
-- don't use "—". Instead, reach for ",", ".", conjunction words, ":", ";", etc. in descending order of preference: vary among them, weighted toward the front of the list, and skip "," where it would cause a comma splice or the sentence is getting long. Overusing any one of them, ";" especially, also feels AI-y. A word cap does not penalize you for adding more sentences: when writing under tight word budgets, prefer a period split or a conjunction over ";", and keep to at most one ";" per message
+- don't use "—". Don't use ";" or ":" unless it would be nonsensical not to. Instead, reach for ",", ".", conjunction words, etc. in descending order of preference: vary among them, weighted toward the front of the list, and skip "," where it would cause a comma splice or the sentence is getting long. Overusing any one of them also feels AI-y. A word cap does not penalize you for adding more sentences
 - don't use the pattern "It's not X, it's Y", "You're not X, you're Y", etc.
 - unless explicitly asked, 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). That means every paragraph, not just the last one (of the markdown file, PR description, GitHub comment, etc.). Rule of thumb: if you're adding new line(s) before the next sentence, don't add a "."
+- don't add a trailing "." at the end of paragraphs (just like this file). That means every paragraph, not just the last one (of the markdown file, PR description, GitHub comment, etc.). Rule of thumb: if you're adding new line(s) before the next sentence, don't add a ".". Exception is that docs (i.e., litellm-docs) should have trailing "."
 - don't use →. Instead, prefer not to use arrows, and if need be, use -> instead
 - use plain, simple, everyday engineering language: the common phrase engineers actually say over rare compact phrasing, in grammatically complete sentences. When explicitly asked to use bullets or ordered lists and structure legitimately helps the reader, prefer nested bullets (any depth is fine) over dense lines in a flat structure
 
@@ -54,21 +54,21 @@ Don't hesitate to use values in .env to get needed API keys and other secrets, a
 
 Python max line length is 120, not 88
 
-The four lint gates (`scripts/ruff_strict_gate.py`, `scripts/type_discipline_gate.py`, `scripts/test_quality_gate.py`, `scripts/type_check_gate.py`) compare each rule's codebase count on your branch against the count at its merge-base with the default branch, and a rule may not grow. There are no budget files to edit or ratchet: when a gate fails, fix the violations the branch introduced or remove at least as many of that rule elsewhere in the tree. The one exception is `reportAny` / `reportExplicitAny`, which share a fixed codebase-wide cap in `ANY_CAPS` in `scripts/type_check_gate.py` because Any spreads past the lines you touch. A branch may add Anys while the total stays under that cap. Only lower `ANY_CAPS`, and only in its own PR to the default branch, never raise it on a feature branch
+The five lint gates (`scripts/ruff_strict_gate.py`, `scripts/type_discipline_gate.py`, `scripts/test_quality_gate.py`, `scripts/openapi_docs_gate.py`, `scripts/type_check_gate.py`) compare each rule's codebase count on your branch against the count at its merge-base with the default branch, and a rule may not grow. There are no budget files to edit or ratchet: when a gate fails, fix the violations the branch introduced or remove at least as many of that rule elsewhere in the tree. The one exception is `reportAny` / `reportExplicitAny`, which share a fixed codebase-wide cap in `ANY_CAPS` in `scripts/type_check_gate.py` because Any spreads past the lines you touch. A branch may add Anys while the total stays under that cap. Only lower `ANY_CAPS`, and only in its own PR to the default branch, never raise it on a feature branch
 
 `make check` (f.k.a. `make pre-commit`, which still works identically as an alias) saves its complete output to a log file in .git (overwriting previous logs) and prints that path as its first and last output lines. To inspect a run, read or grep that log instead of re-running the multi-minute checks just to see a different slice
 
-`make check`, `make lint`, `scripts/pre_commit_lint.sh`, and the standalone lint gates (`scripts/ruff_strict_gate.py`, `scripts/type_discipline_gate.py`, `scripts/type_check_gate.py`) each hold one of 2 machine-wide slots, so when other sessions or worktrees on the same box are already running heavy work, yours prints "all N machine-wide slots are busy; queueing" and then stays quiet until a slot frees. Give the command a long timeout and let it wait rather than killing it, retrying it, or assuming it hung. Don't change the # of machine-wide slots or make it unlimited by setting `LITELLM_GATE_SLOTS=0`
+`make check`, `make lint`, `scripts/pre_commit_lint.sh`, and the standalone lint gates (`scripts/ruff_strict_gate.py`, `scripts/type_discipline_gate.py`, `scripts/type_check_gate.py`) each hold one of 2 machine-wide slots, so when other sessions or worktrees on the same box are already running heavy work, yours prints "all N machine-wide slots are busy" followed by "queueing" and then stays quiet until a slot frees. Give the command a long timeout and let it wait rather than killing it, retrying it, or assuming it hung. Don't change the # of machine-wide slots or make it unlimited by setting `LITELLM_GATE_SLOTS=0`
 
 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 cap in `ANY_CAPS`, just validate it in the caller with Pydantic (a model or `TypeAdapter` that returns the typed thing or raises will do) and then pass the now typed variable in
 
-If you get an LIT001 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()` / `MappingProxyType()` / `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
+If you get an LIT001 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()` / `MappingProxyType()` / `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
 
 Every lint or type suppression must name the exact rule inside brackets and carry a reason comment, e.g. `# pyright: ignore[reportArgumentType]  # stubs lack async overload` or `# noqa: TID251  # <reason>`. `# type: ignore` is banned (LIT009): pyrightconfig.json sets `enableTypeIgnoreComments` to false, so it silently does nothing
 
 Commit and push your work when you're done without asking
 
-When referencing or running models (coding, QA'ing, writing docs, writing tests, etc.), use the latest model in that model family unless otherwise specified; treat your training knowledge, memories, configs, and tests as stale, and determine the family's latest with model_prices_and_context_window.json or the web
+When referencing or running models (coding, QA'ing, writing docs, writing tests, etc.), use the latest model in that model family unless otherwise specified. Treat your training knowledge, memories, configs, and tests as stale, and determine the family's latest with model_prices_and_context_window.json or the web
 
 Always pull before starting any work. The checkout or worktree may be sitting on a stale branch
 
@@ -84,7 +84,7 @@ Monkeypatching attributes of a class to do testing is an anti-pattern. Prefer de
 
 Do not put names of customers or customer company names in code, PR descriptions, issue bodies, etc. This means never mention literally any company name. Especially if you're about to say a sentence mentioning that the reason the PR exists was a feature/model/bug fix/etc. requested by a company. That's the indication that you should replace that company name with "the customer". e.g. not "Model request from Acme (Pylon #1234)" but "Model request from a customer (Pylon #1234)". This is because the codebase is public. The only exception is for publicly known providers or vendors such as OpenAI, Anthropic, AWS Bedrock, etc. only IF we're adding support for that provider/vendor in general and NOT if that PR or whatnot was a request by one of them, and they're actually one of our customers.
 
-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
+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
 
 Prisma migrations apply synchronously at proxy boot, before it serves traffic, so a migration must only change schema, never rewrite rows. No `UPDATE`, `DELETE` or `MERGE`, and no `INSERT ... SELECT`: on a spend-log-sized table any of those is minutes of downtime plus a doubled heap that plain autovacuum won't give back. `tests/code_coverage_tests/check_migrations_no_data_rewrites.py` enforces this. When a rewrite is genuinely bounded and has to ship inside the migration, mark the statement `-- data-migration-ok: <what bounds it>`
 
@@ -92,19 +92,19 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega
 
 - 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), `MappingProxyType`, etc.
-  - Annotate every variable with `: Final` (LIT010). Unpacking and walrus targets cannot carry the annotation, so they are implicitly final. Don't rebind them. Never rebind or mutate function parameters (LIT011); `self`/`cls` attribute stores are the exception. If rebinding or in-place mutation is truly unavoidable, suppress with `# rebind-ok: <reason>`
+- 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), `MappingProxyType`, etc.
+  - Annotate every variable with `: Final` (LIT010). Unpacking and walrus targets cannot carry the annotation, so they are implicitly final. Don't rebind them. Never rebind or mutate function parameters (LIT011). `self`/`cls` attribute stores are the exception. If rebinding or in-place mutation is truly unavoidable, suppress with `# rebind-ok: <reason>`
   - Qualify every TypedDict field with `ReadOnly[...]` (LIT012), which nests freely with `Required` / `NotRequired` / `Annotated` in any order. If making the key writable is truly unavoidable, suppress with `# writable-ok: <reason>`
-  - Comprehensions take at most one `for` clause and one `if` clause (LIT014); split stacked clauses into a helper generator, a named intermediate, or a plain loop. Suppress with `# comprehension-ok: <reason>` only when unavoidable
+  - Comprehensions take at most one `for` clause and one `if` clause (LIT014). Split stacked clauses into a helper generator, a named intermediate, or a plain loop. Suppress with `# comprehension-ok: <reason>` only when unavoidable
   - Every pydantic model must be frozen (LIT015), set via `model_config = ConfigDict(frozen=True)`, a dict-literal `model_config`, an inner `class Config`, or the class keywords. Subclasses inherit it unless they override it. Replace in-place field writes with `model_copy(update=...)`. If making the model mutable is truly unavoidable, suppress with `# frozen-ok: <reason>` on the `class` line
 - Use dependency injection
-- Fully typed; no `Any` or coarse types like `dict[str, Any]` or just `dict`. Every function parameter must be strongly typed
+- 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
-- API-fragmentation-aware: when logic must branch on which API surface produced or consumes data (e.g. chat completions vs Anthropic Messages vs Responses API shapes), proactively look for an existing shared helper (e.g. `litellm_core_utils/prompt_templates/factory.py`) before writing per-surface parsing in the new module; if none exists, add one there instead of duplicating the same format-detection logic in every new guardrail/integration
+- Standard over hand-rolled: use the official SDK or a library where one exists. Where none does, follow industry standards instead of inventing local conventions
+- API-fragmentation-aware: when logic must branch on which API surface produced or consumes data (e.g. chat completions vs Anthropic Messages vs Responses API shapes), proactively look for an existing shared helper (e.g. `litellm_core_utils/prompt_templates/factory.py`) before writing per-surface parsing in the new module. If none exists, add one there instead of duplicating the same format-detection logic in every new guardrail/integration
 
 Follow conventional commits for commit names and PR titles
 
@@ -130,4 +130,4 @@ Before implementing:
 
 Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify
 
-Before requesting maintainer review, verify the current PR tip passes required CI and code coverage, meets Greptile confidence of at least 4/5, and has acceptable Veria and Bugbot reviews. Inspect warnings and findings, fix actionable issues, and rerun the affected checks and reviewers after changes. Record evidence for any false positive or unavailable review; never treat a pending or missing bot result as a pass. Do not lower coverage thresholds or raise `ANY_CAPS` to satisfy a check
+Before requesting maintainer review, verify the current PR tip passes required CI and code coverage, meets Greptile confidence of at least 4/5, and has acceptable Veria and Bugbot reviews. Inspect warnings and findings, fix actionable issues, and rerun the affected checks and reviewers after changes. Record evidence for any false positive or unavailable review. Never treat a pending or missing bot result as a pass. Do not lower coverage thresholds or raise `ANY_CAPS` to satisfy a check

Dockerfile

@@ -39,6 +39,7 @@ ENV NEXT_TELEMETRY_DISABLED=1 \
 WORKDIR /ui
 
 COPY ui/litellm-dashboard/package.json ui/litellm-dashboard/package-lock.json ./
+COPY ui/litellm-dashboard/vendor/ ./vendor/
 RUN --mount=type=cache,target=/root/.npm npm ci --prefer-offline
 
 COPY ui/litellm-dashboard/ ./

Makefile

@@ -4,10 +4,10 @@
 .PHONY: help test test-unit test-unit-llms test-unit-proxy-guardrails test-unit-proxy-core test-unit-proxy-misc test-unit-proxy-root \
 	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 \
-	test-rust-extension rust-sqlx-prepare lens-dev \
+	test-rust-extension rust-sqlx-prepare \
 	info lint lint-inner lint-dev lint-checks format \
 	lint-basedpyright lint-e2e-basedpyright lint-type-discipline \
-	lint-ruff-strict lint-gate lint-test-quality \
+	lint-ruff-strict lint-gate lint-test-quality lint-openapi-docs \
 	install-dev install-proxy-dev install-test-deps install-hooks \
 	install-helm-unittest check-circular-imports check-import-safety check check-inner pre-commit \
 	lint-install lint-fetch-base bootstrap
@@ -35,10 +35,11 @@ help:
 	@echo "  make lint-ruff-strict   - Gate each strict ruff rule's codebase total against its merge-base count"
 	@echo "  make lint-gate        - Strict ruff gate in CI-parity mode (fetches the default branch, simulates the merge)"
 	@echo "  make lint-test-quality  - Gate the test suite's TQ counts against their merge-base counts"
+	@echo "  make lint-openapi-docs  - Gate undocumented POST routes in the proxy OpenAPI document against their merge-base counts"
 	@echo "  make check-circular-imports - Check for circular imports"
 	@echo "  make check-import-safety - Check import safety"
 	@echo "  make test               - Run all tests"
-	@echo "  make test-unit          - Run unit tests (tests/unit and tests/test_litellm)"
+	@echo "  make test-unit          - Run unit tests (tests/unit)"
 	@echo "  make test-unit-llms     - Run LLM provider tests (~225 files)"
 	@echo "  make test-unit-proxy-guardrails - Run proxy guardrails+mgmt tests (~51 files)"
 	@echo "  make test-unit-proxy-core - Run proxy auth+client+db+hooks tests (~52 files)"
@@ -54,7 +55,6 @@ help:
 	@echo "  make test-unit-helm     - Run helm unit tests"
 	@echo "  make test-rust-extension - Build the Rust extension and run its public Python tests"
 	@echo "  make rust-sqlx-prepare  - Refresh litellm-rust/crates/db/.sqlx against a migrated Postgres container"
-	@echo "  make lens-dev           - Run proxy + Lens worker + hot-reload dashboard (ARGS=\"--seed large --seed-logs\", LENS_DEV_PROXY_PORT, LENS_DEV_UI_PORT)"
 	@echo ""
 	@echo "Heavy targets (check, lint) queue for LITELLM_GATE_SLOTS machine-wide"
 	@echo "slots (default 2; 0 disables) so parallel sessions don't thrash one machine."
@@ -220,6 +220,12 @@ lint-type-discipline: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 lint-test-quality: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 	$(UV_RUN) python scripts/test_quality_gate.py --base "$(BASE_REF)"
 
+# OpenAPI docs gate (POST routes without a request body schema, a description or a
+# 200 schema in app.openapi()), counted the same delta-vs-base way so a new endpoint
+# has to show up documented in Swagger UI.
+lint-openapi-docs: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
+	$(UV_RUN) python scripts/openapi_docs_gate.py --base "$(BASE_REF)"
+
 lint-format: format-check
 
 lint-ruff-strict: install-dev
@@ -251,7 +257,7 @@ lint-inner: lint-install
 	@base_ref=$$($(RESOLVE_BASE)) && \
 	$(MAKE) BASE_REF="$$base_ref" -j $(LINT_JOBS) $(LINT_OUTPUT_SYNC) LINT_DEP_INSTALL= LINT_E2E_DEP_INSTALL= LINT_DEP_BASE= lint-checks
 
-lint-checks: lint-format-check-changed lint-ruff lint-gate lint-type-discipline lint-test-quality lint-basedpyright lint-e2e-basedpyright check-circular-imports check-import-safety
+lint-checks: lint-format-check-changed lint-ruff lint-gate lint-type-discipline lint-test-quality lint-openapi-docs lint-basedpyright lint-e2e-basedpyright check-circular-imports check-import-safety
 
 # Faster linting for local development (only checks changed code)
 lint-dev: lint-format-changed check-circular-imports check-import-safety
@@ -290,14 +296,11 @@ test-rust-extension:
 rust-sqlx-prepare:
 	cd litellm-rust && cargo run -p litellm-db-testing --bin sqlx-prepare
 
-lens-dev:
-	./scripts/lens_dev.sh $(ARGS)
-
 test: install-test-deps
 	$(UV_RUN) pytest tests/
 
 test-unit: install-test-deps
-	$(UV_RUN) pytest tests/unit tests/test_litellm -x -vv -n 4
+	$(UV_RUN) pytest tests/unit -x -vv -n 4
 
 # Matrix test targets (matching CI workflow groups)
 test-unit-llms: install-test-deps
@@ -325,7 +328,7 @@ test-unit-other: install-test-deps
 	$(UV_RUN) pytest tests/unit/caching tests/unit/responses tests/unit/secret_managers tests/unit/vector_stores tests/unit/a2a_protocol tests/unit/completion_extras tests/unit/containers tests/unit/enterprise tests/unit/experimental_mcp_client tests/unit/google_genai tests/unit/images tests/unit/interactions tests/unit/router_strategy tests/unit/router_utils tests/unit/types --tb=short -vv -n 4 --durations=20
 
 test-unit-root: install-test-deps
-	$(UV_RUN) pytest tests/unit/test_*.py tests/test_litellm/test_*.py --tb=short -vv -n 4 --durations=20
+	$(UV_RUN) pytest tests/unit/test_*.py --tb=short -vv -n 4 --durations=20
 
 # Proxy unit tests (tests/unit/proxy split alphabetically)
 test-proxy-unit-a: install-test-deps
@@ -335,7 +338,7 @@ test-proxy-unit-b: install-test-deps
 	$(UV_RUN) pytest tests/unit/proxy/test_[p-z]*.py tests/unit/skills --tb=short -vv -n 2 --durations=20
 
 test-integration: install-test-deps
-	$(UV_RUN) pytest tests/ -k "not test_litellm"
+	$(UV_RUN) pytest tests/
 
 test-unit-helm: install-helm-unittest
 	helm unittest -f 'tests/*.yaml' helm/litellm-helm

README.md

@@ -407,6 +407,7 @@ Set `LITELLM_PROXY_API_BASE` and `LITELLM_PROXY_API_KEY` and every model call th
 | [Sagemaker Chat (`sagemaker_chat`)](https://docs.litellm.ai/docs/providers/aws_sagemaker) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Sail (`sail`)](https://docs.litellm.ai/docs/providers/sail) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Sambanova (`sambanova`)](https://docs.litellm.ai/docs/providers/sambanova) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
+| [ScaleDown (`scaledown`)](https://docs.litellm.ai/docs/providers/scaledown) | ✅ |  |  |  |  |  |  |  |  |  |
 | [Snowflake (`snowflake`)](https://docs.litellm.ai/docs/providers/snowflake) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Strands Decider (`strands_decider`)](https://docs.litellm.ai/docs/providers) |  |  |  |  |  |  |  |  |  |  |
 | [Text Completion Codestral (`text-completion-codestral`)](https://docs.litellm.ai/docs/providers/codestral) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |

backend/routes/allowlist.py

@@ -91,9 +91,10 @@ BACKEND_PATH_PREFIXES: tuple[str, ...] = (
     "/user_agent",
     "/usage/",
     "/daily/",
-    # Deployment-wide gateway request counts. Scoped to the analytics read rather
+    # Deployment-wide gateway request and error counts. Scoped to the analytics reads rather
     # than all of /gateway/, which stays free for data-plane routes.
     "/gateway/daily/",
+    "/gateway/errors/",
     # CloudZero cost-export admin (init / settings / export / dry-run / delete)
     "/cloudzero/",
     # Caching admin

ci_cd/cost_map_guard.py

@@ -14,8 +14,9 @@ import argparse
 import json
 import subprocess
 import sys
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
+from types import MappingProxyType
 from typing import Final
 
 from generate_model_prices_schema import SPECIAL_ROOT_KEYS, build_schema, render, validation_errors
@@ -25,6 +26,7 @@ BACKUP_PATH: Final = "litellm/model_prices_and_context_window_backup.json"
 SCHEMA_PATH: Final = "model_prices_and_context_window.schema.json"
 GUARDED_PATHS: Final = (COST_MAP_PATH, BACKUP_PATH, SCHEMA_PATH)
 BOT_BRANCH_PREFIX: Final = "litellm_cost_map_sync_"
+EVALUATION_OUTPUT_PRICE_SOURCES: Final[Mapping[str, str]] = MappingProxyType({})
 
 CostMap = dict[str, object]
 
@@ -51,7 +53,31 @@ def _rendered_schema(cost_map: CostMap) -> str:
         return str(error)
 
 
-def _file_failures(head: Snapshot, head_map: CostMap) -> tuple[str, ...]:
+def _evaluation_output_price_failure(
+    key: str, entry: object, evaluation_output_price_sources: Mapping[str, str]
+) -> str | None:
+    if not isinstance(entry, dict) or entry.get("mode") != "evaluation":
+        return None
+    output_cost: Final = entry.get("output_cost_per_token")
+    if (
+        not isinstance(output_cost, (int, float))
+        or isinstance(output_cost, bool)
+        or output_cost <= 0
+        or key in evaluation_output_price_sources
+    ):
+        return None
+    return (
+        f"{key}: mode evaluation rows bill input only; output_cost_per_token must be 0 unless the vendor "
+        "prices output tokens for this model (add the source to EVALUATION_OUTPUT_PRICE_SOURCES)"
+    )
+
+
+def _file_failures(
+    head: Snapshot,
+    head_map: CostMap,
+    *,
+    evaluation_output_price_sources: Mapping[str, str] = EVALUATION_OUTPUT_PRICE_SOURCES,
+) -> tuple[str, ...]:
     schema_text: Final = _rendered_schema(head_map)
     if not schema_text.startswith("{"):
         return (schema_text,)
@@ -75,6 +101,16 @@ def _file_failures(head: Snapshot, head_map: CostMap) -> tuple[str, ...]:
             f"{COST_MAP_PATH} does not validate against its schema: {error}"
             for error in validation_errors(head_map, json.loads(schema_text))[:20]
         ),
+        *(
+            failure
+            for key, entry in head_map.items()
+            if (
+                failure := _evaluation_output_price_failure(
+                    key, entry, evaluation_output_price_sources
+                )
+            )
+            is not None
+        ),
     )
 
 
@@ -121,13 +157,25 @@ def contract_for(bot: bool, changed_files: Sequence[str]) -> str:
     return "human PR, file checks only" if touches_cost_map(changed_files) else "human PR, cost map untouched"
 
 
-def guard_failures(base: Snapshot, head: Snapshot, changed_files: Sequence[str], bot: bool) -> tuple[str, ...]:
+def guard_failures(
+    base: Snapshot,
+    head: Snapshot,
+    changed_files: Sequence[str],
+    bot: bool,
+    *,
+    evaluation_output_price_sources: Mapping[str, str] = EVALUATION_OUTPUT_PRICE_SOURCES,
+) -> tuple[str, ...]:
     if not bot and not touches_cost_map(changed_files):
         return ()
     head_map: Final = _parse_object(head.cost_map, COST_MAP_PATH)
     if isinstance(head_map, str):
         return (head_map,)
-    return (*_file_failures(head, head_map), *(_bot_failures(base, head_map, changed_files) if bot else ()))
+    return (
+        *_file_failures(
+            head, head_map, evaluation_output_price_sources=evaluation_output_price_sources
+        ),
+        *(_bot_failures(base, head_map, changed_files) if bot else ()),
+    )
 
 
 def _git(*args: str) -> str | None:

codecov.yaml

@@ -71,6 +71,8 @@ flag_management:
       carryforward: false
     - name: lens-python-310
       carryforward: false
+    - name: lens-postgres
+      carryforward: false
     - name: proxy-db-key-generation
       carryforward: false
     - name: proxy-db-auth-checks

deploy/lens/Dockerfile

@@ -1,41 +0,0 @@
-ARG LITELLM_BUILD_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:1d95114038f76513a9ace6fca107d5582b08c65981f81f61cb56bf7fd2ef216d
-ARG LITELLM_RUNTIME_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:1d95114038f76513a9ace6fca107d5582b08c65981f81f61cb56bf7fd2ef216d
-
-FROM $LITELLM_BUILD_IMAGE AS builder
-RUN apk add --no-cache rust build-base cmake perl pkgconf openssl-dev libseccomp-dev python-3.13
-WORKDIR /src
-COPY .cargo/ .cargo/
-COPY litellm-rust/ litellm-rust/
-COPY litellm/proxy/lens/prompts/ litellm/proxy/lens/prompts/
-WORKDIR /src/litellm-rust
-ENV CARGO_PROFILE_RELEASE_DEBUG=0 CARGO_PROFILE_RELEASE_STRIP=symbols
-RUN cargo build --locked --release -p litellm-lens
-COPY deploy/lens/python_policy.c /tmp/python_policy.c
-RUN cc -std=c11 -D_GNU_SOURCE -O2 -Wall -Wextra -Werror /tmp/python_policy.c -lseccomp -o /tmp/python-policy && \
-    /tmp/python-policy /tmp/python.seccomp
-
-FROM builder AS test-builder
-RUN cargo test --locked --release -p litellm-lens --test sandbox --no-run --message-format=json > /tmp/test-artifacts.json && \
-    python3.13 -c 'import json, pathlib, shutil; rows = [json.loads(line) for line in pathlib.Path("/tmp/test-artifacts.json").read_text().splitlines()]; artifact, = [r["executable"] for r in rows if r.get("executable") and r["target"]["name"] == "sandbox"]; shutil.copyfile(artifact, "/tmp/lens-sandbox-tests")' && \
-    chmod 755 /tmp/lens-sandbox-tests
-
-FROM $LITELLM_RUNTIME_IMAGE AS service
-ARG LITELLM_RELEASE_TAG=""
-RUN : "${LITELLM_RELEASE_TAG:?Pass --build-arg LITELLM_RELEASE_TAG matching the gateway}"
-RUN apk add --no-cache python-3.13 setpriv libgcc libstdc++ openssl ca-certificates
-ENV LITELLM_RELEASE_TAG=${LITELLM_RELEASE_TAG} PYTHONDONTWRITEBYTECODE=1
-WORKDIR /app
-COPY --from=builder /src/litellm-rust/target/release/litellm-lens /usr/local/bin/litellm-lens
-COPY --from=builder /tmp/python.seccomp /app/lens/python.seccomp
-COPY deploy/lens/python_runtime.py /tmp/python_runtime.py
-RUN python3.13 -S /tmp/python_runtime.py /app/lens/python-runtime.json && rm /tmp/python_runtime.py
-USER 65532:65532
-EXPOSE 4318
-ENTRYPOINT ["/usr/local/bin/litellm-lens"]
-
-FROM service AS smoke
-COPY --from=test-builder /tmp/lens-sandbox-tests /usr/local/bin/lens-sandbox-tests
-ENTRYPOINT ["/usr/local/bin/lens-sandbox-tests"]
-CMD ["--ignored", "--nocapture", "--test-threads=1"]
-
-FROM service AS runtime

deploy/lens/Dockerfile.dockerignore

@@ -1,15 +0,0 @@
-**
-!deploy/
-!deploy/lens/
-!deploy/lens/python_policy.c
-!deploy/lens/python_runtime.py
-!litellm/
-!litellm/proxy/
-!litellm/proxy/lens/
-!litellm/proxy/lens/prompts/
-!litellm/proxy/lens/prompts/**
-!.cargo/
-!.cargo/**
-!litellm-rust/
-!litellm-rust/**
-litellm-rust/target/

deploy/lens/README.md

@@ -1,282 +0,0 @@
-# Lens service
-
-Lens records agent activity and investigates it in a separate Rust service. LiteLLM serves model requests, the dashboard, and investigation settings. Lens owns trace ingestion and ClickHouse access; PostgreSQL stays with LiteLLM
-
-Agent exporters send traces directly to Lens. LiteLLM sends its optional request logs through a bounded background queue. If Lens or ClickHouse is unavailable, model requests continue; traces can be delayed or dropped according to the exporter's retry policy. The gateway never waits for ClickHouse during startup or inference
-
-## New local installation
-
-Install Docker with Compose, Python 3.10 or later, and Git. Clone LiteLLM, select a published release that includes Lens, and start the existing Compose stack:
-
-```bash
-git clone https://github.com/BerriAI/litellm.git
-cd litellm
-python3 deploy/lens/configure.py --version <release-version>
-docker compose --env-file deploy/lens/.env -f deploy/lens/stack.yaml up -d --wait
-```
-
-The configuration command generates your keys and database passwords once, saves them in `deploy/lens/.env` with owner-only permissions, and preserves them on subsequent runs. Back up this file alongside your database volumes. Both images use the selected release; there is no local image build
-
-Open `http://localhost:4000/ui/` and sign in as `admin` using `LITELLM_MASTER_KEY` from the saved file. Open **Lens**, select your framework, generate a tracing key, and copy the displayed configuration. The trace endpoint is already filled in. Keep your agent's existing model credentials; the tracing key only authorizes trace uploads
-
-PostgreSQL and ClickHouse use persistent Docker volumes and have no host ports. The dashboard and trace listener bind to localhost. Use your normal TLS and ingress for a hosted deployment. Stop the stack with `docker compose --env-file deploy/lens/.env -f deploy/lens/stack.yaml down`; omit `-v` to retain data
-
-Under **Lens > Investigations > Connect worker**, choose an analysis model and monthly budget. The deployed service connects automatically after you save these settings. There is no worker command or second token to copy
-
-## Existing LiteLLM installation
-
-Keep your gateway, PostgreSQL database, deployment tool, and existing encryption keys. Deploy the matching Lens image, give it access to ClickHouse, and configure the service connection on LiteLLM
-
-| Variable | LiteLLM | Lens service |
-| --- | --- | --- |
-| `LITELLM_LENS_SERVICE_TOKEN` | Same private random secret, at least 32 characters | Same secret |
-| `LITELLM_LENS_URL` | Internal Lens URL, such as `http://lens-worker:4318` | Not needed |
-| `LITELLM_LENS_PUBLIC_URL` | Ingestion base URL reachable by your agents | Not needed |
-| `LITELLM_URL` | Not needed | LiteLLM URL reachable from Lens |
-| `CLICKHOUSE_URL` | Remove it from Lens tracing configuration | ClickHouse HTTP URL with credentials |
-| `CLICKHOUSE_DATABASE` | Not needed for Lens | Existing database name, defaults to `litellm` |
-| `AGENT_TRACING_RETENTION_DAYS` | Not needed for Lens | Retention for traces and Lens request logs, defaults to `14` |
-
-Remove the old `general_settings.tracing.store` configuration used for Lens from LiteLLM. Keep unrelated logging integrations and their configuration. Only Lens should reach its ClickHouse database. The shared service secret is an infrastructure credential: keep it out of browser code, agent exporters, screenshots, and public ingress headers
-
-Expose the Lens HTTP listener on port 4318 through TLS. Route `/lens-ingest` on your existing hostname directly to Lens at the load balancer, then set `LITELLM_LENS_PUBLIC_URL=https://<your-host>/lens-ingest`. The gateway must not proxy these uploads. Alternatively use a separate hostname and forward `/v1/` to Lens. Keep `/internal/` private; it requires the service secret
-
-### Standalone Docker or a container host
-
-Build from the same source commit and `LITELLM_RELEASE_TAG` as your running gateway:
-
-```bash
-export LITELLM_RELEASE_TAG='<gateway-release-identity>'
-export LENS_WORKER_IMAGE='<your-registry>/litellm-lens-worker:<image-tag>'
-docker build --build-arg LITELLM_RELEASE_TAG="$LITELLM_RELEASE_TAG" \
-  -f deploy/lens/Dockerfile -t "$LENS_WORKER_IMAGE" .
-```
-
-Publish that image to a registry your host can pull from. Prefer a digest reference for hosted deployments. Public development images use `ghcr.io/berriai/litellm-lens-worker-dev:sha-<full-commit>`; check that the exact image exists before selecting it. An arbitrary commit may not have a published image
-
-The image supports native amd64 and arm64. For worker-only Compose, use `deploy/lens/compose.yaml` with a private environment file containing `LENS_WORKER_IMAGE`, `LITELLM_URL`, `LITELLM_LENS_SERVICE_TOKEN`, and `CLICKHOUSE_URL`:
-
-```bash
-docker compose --env-file /path/to/private/lens.env \
-  -f deploy/lens/compose.yaml up -d
-```
-
-The Compose listener binds to localhost. Your reverse proxy must reach it. On Render, run Lens as a web service with the same environment and listener port 4318, not an outbound-only background worker. Use `/health/live` for process health and `/health/ready` to check storage and tracing credentials
-
-Lens does not need provider credentials, PostgreSQL credentials, a GPU, or the LiteLLM Python package. The image includes a small CPython runtime only for the investigator's confined calculation tool. Keep the shipped security settings, temporary filesystem, and resource limits
-
-### Kubernetes with Helm
-
-Both `helm/litellm` and `helm/litellm-helm` support Lens. Keep your existing chart, release name, namespace, and values. Add:
-
-```yaml
-lensWorker:
-  enabled: true
-```
-
-Then run your usual Helm deployment command using the matching published chart. The chart supplies the matching Lens image, generates the shared service secret, starts a single ClickHouse instance with a persistent volume, and connects the services. Your cluster needs a default storage class, or set `lensWorker.clickhouse.storageClassName`. Bundled storage defaults to 20 GiB; set `lensWorker.clickhouse.storage` before installation to choose another size
-
-When your chart manages an ingress with one hostname, the chart fills in the public tracing address and routes `/lens-ingest` directly to Lens. TLS is detected from `ingress.tls` or an ALB certificate annotation. With custom ingress, multiple hostnames, or TLS terminated elsewhere, set the address explicitly:
-
-```yaml
-lensWorker:
-  enabled: true
-  publicUrl: https://<your-litellm-host>/lens-ingest
-```
-
-For a dedicated trace hostname, configure `lensWorker.ingress.enabled`, `host`, `className`, and `tls`. Its hostname supplies the public address unless you override `publicUrl`. Internal Lens routes stay private
-
-To use an existing ClickHouse database and secrets managed by your platform, keep these overrides:
-
-```yaml
-lensWorker:
-  enabled: true
-  serviceTokenSecret:
-    name: litellm-lens-service
-    key: service-token
-  clickhouseSecret:
-    name: litellm-lens-clickhouse
-    key: url
-  clickhouseDatabase: litellm
-  retentionDays: 14
-```
-
-Supplying `clickhouseSecret.name` uses that database and disables bundled storage. Keep your database name and retention policy. For GitOps tools that render Helm without cluster access, supply both existing secrets so rendering cannot regenerate credentials
-
-Normal Helm upgrades reuse the generated credentials. Secrets are retained on uninstall, and the ClickHouse volume is retained by Kubernetes. Back them up together. Treat changing the database, storage class, or secret reference as an infrastructure change, not a routine version update
-
-After deployment, open **Lens**. If it was already open, click **Check setup**. The setup section moves to your framework and tracing key when Lens is reachable and storage is ready. Investigation setup asks for the analysis model and budget; the installed service connects automatically
-
-## Upgrade
-
-Upgrade LiteLLM and Lens from the same source commit and release identity. For a coordinated published release, use its matching worker version; `deploy/lens/stack.yaml` starts LiteLLM, Lens, PostgreSQL, and ClickHouse for new installations. Standalone images remain available. Publishing an image does not update running containers
-
-Keep the same databases, encryption keys, shared service secret, and public ingestion URL. Pause scheduled investigations and finish or cancel active runs, update both images through your usual deployment process, then check ingestion and run an investigation before resuming schedules. Do not run `docker compose down -v`
-
-## Development
-
-`make lens-dev` starts LiteLLM, Lens, and the hot-reload dashboard. Set `LENS_DEV_PROXY_PORT` and `LENS_DEV_UI_PORT` to change the local ports. For containers, pass the same release identity to both builds. Unversioned or incompatible workers are refused before claiming work
-
-## Configure a lens
-
-Choose agent runs, individual LLM requests, or both. The matching-activity preview updates as you choose an application (the recorded OpenTelemetry service.name) or, for request activity, a LiteLLM model group and add metadata conditions. It shows run names, timestamps, and trace IDs; open a run to inspect its original steps before starting analysis. Suggestions come from up to 100 recent executions and may not include every recorded attribute. You can enter other exact keys and values. Leave service and filters blank for all activity your account can access. Filters are exact key/value matches, combined with AND. Trace filters match span or resource attributes on the same span. Request filters match logged metadata, including caller metadata stored under `requester_metadata`; `tag=value` matches request tags. `swarm=research` works only if your instrumentation records that attribute
-
-Describe how the agent should behave and optionally add specific checks. Select the lookback window, team and metadata, then choose the percentage to review and an optional maximum. **100% with no maximum selects every matching run**. The preview pages through all matching activity and lets you select particular runs. Percentage sampling uses a stable hash order, rounds up, and applies the optional maximum after the percentage
-
-Choose your analysis model, parallelism and monthly budget. Parallelism controls simultaneous model calls, not the number of runs selected. New lenses run once by default. Turn on monitoring to repeat the same setup at a custom interval. **Run now** uses the same saved settings immediately, including the same lookback window and sampling. Each scan recalculates the window and reuses completed reviews when the selected trace content, expected behavior, enabled checks and analysis model are unchanged. Budget, name and schedule edits preserve reuse. Duplicate a lens when you want a separate investigation without changing an existing monitor
-
-Pausing stops future scheduled scans; cancel the active scan separately if needed. The worker polls every 2 to 15 seconds, backing off while idle; creating a lens or clicking Run now queues a scan, and due schedules are queued when the worker polls. Scans for the same lens never overlap, and its next interval starts after completion. Closing the browser does not stop the worker. A running scan retains its analysis settings and selected execution IDs across retries. Budget edits apply to subsequent model calls, including those in an active scan
-
-## Read the results
-
-Needs attention shows issues, highest priority first. Patterns contains useful trends and successful behavior that may not need a fix. Each finding starts with a short explanation and a next step when useful. Expand the limitations for uncertainty and counterexamples. Evidence is grouped by run and collapsed until you need it; each quote opens the original step
-
-Use the **Investigation run** selector or **History** to reopen previous results. Each run keeps its new or updated findings, settings, selected traces, coverage and cost. An unchanged rerun adds no findings; choose **All accumulated findings** to see saved findings across runs. The **Agent traces** tab lists the selected sample, including traces without an observed issue and traces with insufficient evidence. The tab is called **LLM requests** or **Traces and requests** for those activity types. Findings distinguish distinct affected traces from contributing investigation runs. Counterexamples remain visible as evidence without increasing the affected count. Merged finding links continue to resolve to the retained finding
-
-Enter an explanation under **What should Lens remember?** and choose **This is expected** to dismiss expected behavior, **Mark resolved** after fixing an issue, or **Reopen** to reopen a resolved issue. These actions save the feedback together with the status; typing feedback alone neither saves it nor resolves the finding. Feedback informs later analysis and reconciliation without invalidating completed reviews. It stays with the finding when evidence recurs, does not alter historical evidence, and does not exempt different problems
-
-## What a scan does
-
-The proxy selects executions received or updated within the configured lookback window, with a two-minute settling period. Older rows without receipt timestamps use execution end time. Overlapping scans do not increment a finding's occurrence count for the same execution ID
-
-A trace is spans sharing a trace ID within one team, not an automatically reconstructed conversation session. Requests are individual LLM calls. When both sources are enabled, requests correlated to a recorded span by response ID are excluded to reduce double counting
-
-The worker reads complete selected trace content to compute fingerprints before making paid model calls. Completed review checkpoints are reused only within the same lens when both the complete content and investigation criteria match. Criteria are the expected behavior, enabled check IDs and instructions, and analysis model. Lens fingerprints these values rather than using the time of an unrelated settings edit. Scope and sampling changes preserve matching reviews for traces selected again; duplicating a lens starts an independent set of reviews. Initial reviews are confined to their assigned trace and retain observations, cited excerpts and metadata. Reviewers use catalog, read, search and optional Python tools; Python receives selected evidence as streamed input. Pending observation batches are grouped in parallel and investigated against the original evidence, then reconciled with saved findings. A recurring cause extends its existing finding, preserving feedback, earlier evidence and contributing run history
-
-If every selected review is already incorporated into findings, the run completes with a reuse count, zero model calls and zero analysis cost, including when the monthly budget is exhausted. The run remains in history. A partially failed run preserves completed review checkpoints; pending grouping or investigation can still need paid model calls even when all selected trace reviews are reused. A trace without a complete matching checkpoint needs a review. Live progress distinguishes reviews eligible for reuse from reviews actually recorded; failed or cancelled runs report only the reuse they completed
-
-There is no fixed total run, span, candidate or investigation-turn cutoff. Agents can replace their active conversation with working notes. If a request exceeds the configured model's context window, the worker compacts the conversation automatically and resumes with references to its archived tool history. Original evidence remains accessible through the gateway while it is available and retained. Tool results and working notes remain accessible during the investigation; character ranges make even a single oversized result readable in pieces. A review reports an error if the task or its replacement notes cannot fit. Context windows, the configured budget, worker resources and recorded evidence still bound practical work. The investigator has no browsing, code-editing or production-action tools
-
-The live review drawer shows loading, trace review, parallel grouping, reconciliation and candidate investigation. It reports current model and tool operations, including context compaction, and retains tool-call counts on completed trace reviews. These counts describe attempted calls, not successful executions. This progress channel contains operation metadata, not Python code or tool output. Preliminary observations remain separate from final findings and their validated evidence
-
-Each model response must match its JSON schema. A malformed response gets one repair attempt through the same budget controls. A session review that remains invalid or cannot fit marks that execution unassessable while other reviews continue. Broken evidence pagination or missing content pages return tool errors so the agent can inspect narrower spans or other evidence. Unreadable citations receive repair feedback. Verified excerpts remain available without fetching their source again. The affected source counts as partial, including failures discovered during later investigations, while the reviewer owns its assessment. Findings are published only after comparison with each other and saved findings finishes. If analysis stops before that comparison completes, completed trace reviews and their evidence remain saved for reuse, and the run retains its assessments and error. A later run can retry grouping and investigation. Runs with useful completed assessments or reconciled findings show partial results; total failures are marked failed. Transport errors, cancellation and budget exhaustion stop further analysis. Both the worker and proxy validate quoted evidence against original content. Per-run issue assessments follow supporting citations, including evidence found by another run's reviewer; counterexamples do not mark a run affected. Findings retain exact quotes and open the source trace or request. Resolve a finding after a fix, or dismiss it with a reason. A resolved finding reopens when new execution IDs support the same pattern; dismissed findings remain dismissed
-
-Coverage distinguishes eligible, sampled, reviewed, partial, and unassessable executions. Findings describe observations in the sample, not population-wide success rates or proven causes. A root span does not prove that a trace contains every expected span. Long, missing, redacted, or expired content limits the conclusions
-
-## Operations and limits
-
-PostgreSQL stores configurations, findings and all scan history, returned in pages of 50 jobs. Workers claim jobs with optimistic concurrency and a five-minute lease, renewed every 30 seconds. A disconnected job can be reclaimed up to three times. Cancellation stops subsequent work; a model call already in flight may finish and incur cost
-
-Lens checks which selected traces have reusable reviews before requesting model budget. Reuse needs no model call or reservation. New trace reviews and unfinished grouping or investigation can incur cost
-
-Before each model call, Lens reserves a conservative allowance based on the input and permitted output. The summary separates settled monthly spend, unexpired reservations and available budget. With a $100 limit, $45 spent and $10 reserved, $45 is available for additional calls. Successful calls settle to recorded cost and release unused capacity. Failed or timed-out requests release their hold; abandoned holds expire after the proxy request timeout plus a grace period
-
-Calls wait when concurrent reservations temporarily hold the remaining capacity. Waiting and model execution share the proxy's request timeout. If one request's allowance exceeds the unspent monthly budget, the error reports what the request needs and what remains. Reduce the deployment's output allowance or increase the limit. Paid analysis stops when the monthly limit is spent; completed reviews can still be reused. The monthly budget renews on the UTC calendar month
-
-The assigned virtual key has independent budgets, model permissions and rate limits. Several investigations can share that key, so its limit can stop analysis even when one lens has budget left. Every worker needs a billing key assigned through worker setup or **Settings**. Analysis spend appears under that key in **Virtual Keys** and normal request logs, with Lens, run and worker IDs in request metadata. Analysis prompts and responses are redacted from spend logs; source traces and findings remain available through the administrator-only Lens API. Terminal budget, authentication or transport failures stop the scan after applicable retries and preserve completed checkpoints
-
-Lens requires ClickHouse for both sources. It does not reconstruct sessions from unrelated trace IDs, guarantee exhaustive reviews, or automatically fix agent code. Trace contents can change as late spans arrive, even though a job's selected IDs are fixed. Changed content requires a matching review before reuse. Findings should be reviewed by a person before acting on them
-
-
-## API access
-
-The UI and API use the same scan lifecycle. Authenticate with a proxy administrator credential for writes, or a proxy-admin viewer credential for reads. Worker credentials are only for worker operations
-
-```bash
-curl "$LITELLM_URL/lens" -H "Authorization: Bearer $LITELLM_API_KEY" \
-  -H 'Content-Type: application/json' -d '{
-    "name": "Research quality", "model": "your-model-alias",
-    "context": "Answer the requested question using cited, retrieved evidence.",
-    "source": "traces", "lookback_hours": 24,
-    "sample_percent": 100, "sample_size": null, "concurrency": 8,
-    "enabled": true, "interval_minutes": 1440, "monthly_budget": 50
-  }'
-
-curl "$LITELLM_URL/lens/$LENS_ID/runs" -X POST \
-  -H "Authorization: Bearer $LITELLM_API_KEY" -H 'Content-Type: application/json' -d '{}'
-
-curl "$LITELLM_URL/lens/$LENS_ID/runs?offset=0" -H "Authorization: Bearer $LITELLM_API_KEY"
-curl "$LITELLM_URL/lens/$LENS_ID/runs/$BATCH_ID" -H "Authorization: Bearer $LITELLM_API_KEY"
-```
-
-Creation queues the first batch. Posting to `/lens/{id}/runs` queues another, or returns the existing active batch. The run response contains its ID under `jobs[0].id`. Poll the batch URL for status, findings and assessments. List responses omit large result payloads; request a batch to retrieve them. Supply an optional complete `settings` object on the runs POST for a one-off override; the saved lens stays unchanged. Selection accepts `team_id`, exact `filters`, and opaque `execution_ids` returned by `/lens/preview/sample`. Preview accepts `offset` and `as_of` to keep the time window fixed while paging. Feedback uses `PATCH /lens/{id}/findings/{finding_id}` with `status` and `reason`
-
-## Local development
-
-`make lens-dev ARGS=--seed` starts the full dev stack. The live dashboard is at `http://localhost:3000/ui/lens/`, with login at `http://localhost:3000/ui/login/`. Next.js forwards API requests to the proxy on port 4000, so login and navigation stay in the live UI and edits hot-reload
-
-The default is Next.js dev with no production build (`LENS_DEV_BUILD_UI=0`). Set `LENS_DEV_BUILD_UI=1` when you also want a fresh static dashboard at `http://localhost:4000/ui/`. Build output goes to `.lens-dev/logs/ui-build.log`; a failed build stops startup. Both modes keep the live dashboard on port 3000. Startup checks the live login route before seeding and fails with the UI log path if Next.js exits. `LENS_DEV_STARTUP_TIMEOUT_SECONDS` controls startup readiness retries (default 300; `LENS_DEV_READINESS_REQUEST_TIMEOUT_SECONDS` caps each HTTP probe, default 5)
-
-For local fixture data, run `make lens-dev ARGS=--seed`. Use `make lens-dev ARGS="--seed large"` for 2,000 fixture copies spread over the last 24 hours, about 860,000 spans with linked request logs, plus three long sessions of roughly 1,150, 9,200 and 92,000 spans in a single trace for drawer paging and the oversized read path. Their trace IDs are printed at the end. To seed a running stack without restarting it, use `make lens-dev ARGS="--seed-only --seed large --copies 100"`. Every profile replays one copy of every checked-in capture through authenticated `/v1/traces`, including failures, retries, streaming and multiple agent frameworks, and verifies linked spend totals through the proxy. Large seeds then copy that first copy inside ClickHouse and PostgreSQL with `INSERT ... SELECT`, rewriting trace, span and call IDs so each copy keeps its own spend, and verify the last copy through the proxy
-
-Seeds append fresh IDs on every invocation and spread copies over recent timestamps. Restarts without `SEED` do not add data. Lens excludes activity received in the last two minutes, so wait two minutes after seeding before checking investigation previews. `LENS_DEV_SEED_COPIES` overrides total copies. Large seeds test data volume and pagination, rather than concurrent ingestion throughput or review accuracy. They can use substantial disk space; adjust `--copies` for your machine. Seeding expects the generated local tracing configuration. The old `run_tracing_proxy_local.sh --seed` command forwards to Lens dev, using its ports and saved master key
-
-The Rust receiver bounds each upload and its decompressed body to 16 MiB and permits two ingestion requests at once per replica. Exporters should split large batches and retry backpressure. `LENS_DEV_SEED_COPIES` and `LENS_DEV_SEED_TIMEOUT_SECONDS` control the seeder; the receiver's limits are compiled into the service
-
-## Quality evaluation
-
-Run the checked-in cases against a configured real model. Expected labels are used only for scoring, never passed to the model. Dev and held-out cases include missing outcomes, failed tools, recovery, handoffs, unsupported claims, repeated work, long evidence and prompt injection. The background option adds clean arithmetic traces to test rare-issue discovery at scale; those repeated synthetic cases do not establish accuracy on every production workload
-
-```bash
-cargo build --manifest-path litellm-rust/Cargo.toml -p litellm-lens --example worker_once --locked
-python -m tests.proxy_behavior.lens.evaluate --api-base "$LITELLM_URL" \
-  --model your-model-alias --split all --background 1000 --concurrency 16 \
-  --output /tmp/lens-quality.json
-```
-
-Set `LITELLM_API_KEY` privately. This makes paid model calls. Inspect missed and unexpected per-run labels, final findings and coverage; do not equate a passing dataset with guaranteed detection on arbitrary traces
-
-The default workspace retrieves trace content on demand. Python calls have temporary scratch space that is removed after execution. The Docker command supplies a writable temporary mount while keeping the application filesystem read-only
-
-To check that accepted behavior stays accepted without hiding new problems, run the evaluator with `--dataset tests/proxy_behavior/lens/feedback_cases.json`. Reports include elapsed time, model call count, reported cost when the proxy provides it, missed checks, unexpected checks, and inconclusive candidates
-
-## Release compatibility
-
-Gateway and worker builds carry the same `LITELLM_RELEASE_TAG`. A worker announces its release and protocol before claiming an investigation. A mismatch returns HTTP 409 with the required image, leaving queued investigations untouched
-
-PostgreSQL stores complete review checkpoints in `LiteLLM_LensReview`, alongside Lens records and run history. Schema migrations preserve saved investigations, findings, history, worker credentials and billing assignments without rewriting stored Lens records
-
-Drain active scans, stop workers, back up the database, and deploy all gateway replicas as a coordinated replacement or traffic cutover. Keep traffic paused until every gateway replica uses the selected build and its migrations have completed. Mixed gateway versions sharing Lens data are not supported because every replica must understand the stored records. Pausing workers alone does not prevent dashboard or API writes. Recreate workers with the matching image and their existing tokens, then resume traffic and schedules. Scanning waits until a compatible worker connects
-
-Use the shipped migration history for databases containing Lens data. The schema guard stops `--use_prisma_db_push` before changes if it detects Lens tables that require renaming; run the shipped rename migration against the configured schema before retrying. Fresh databases and databases with the current table names can use database push
-
-A rollback to a gateway that cannot read saved Lens records requires restoring a compatible database backup. Database push from such a build can also remove the review table. Test recovery on a separate database and account for all gateway data written after the backup
-
-The dashboard reads its image from the running gateway. `LENS_WORKER_IMAGE` overrides the registry/image for private deployments. Set an explicit `LENS_WORKER_IMAGE` for worker-only Compose. Verify that the image exists and matches the gateway before deploying it
-
-For source development, use `make lens-dev`, which gives the proxy and source worker the same commit identity. For custom containers, build both from the same checkout with `--build-arg LITELLM_RELEASE_TAG=sha-$(git rev-parse HEAD)` and set the proxy's `LENS_WORKER_IMAGE` to the worker image you built. An unlabelled custom build refuses worker setup and claims instead of guessing from the Python package version. Normal package-index installations use their installed release version
-
-The hourly development pipeline pins all component images to the same selected commit and publishes its chart only after every build and worker smoke test succeeds. The public commit-tagged worker workflow publishes to `ghcr.io/berriai/litellm-lens-worker-dev` on Lens-related changes, so an arbitrary `main` commit may require building your own pair; do not substitute the newest available worker
-
-
-## Worker dependencies
-
-The service builds from the workspace Cargo.lock with a pinned Rust toolchain and a digest-pinned Wolfi runtime. It has no Python package dependencies. CPython and libseccomp support the confined calculation tool. CI builds, runs, and scans native amd64 and arm64 images
-
-## Python analysis boundary
-
-The `python` tool runs ordinary CPython with the standard library in a fresh child process inside the existing worker container. It receives the selected evidence as `data` over stdin and has its own temporary working directory. It creates no additional container or service. Read and search tools remain available independently of Python
-
-The native worker image builds a syscall policy with libseccomp and includes the full `setpriv` launcher. Each child starts with no inherited worker secrets or open worker files, isolated Python startup, Landlock filesystem restrictions and a default-deny seccomp filter. It can read the Python runtime and its own scratch files. Worker source, installed worker packages, other jobs' files and `/proc` contents are unavailable. Network sockets, child processes, cross-process memory operations, signals to other processes and filesystem metadata mutation are denied, including calls made through `ctypes`. Some metadata inspection, such as `stat`, `access` and `readlink` of known paths, remains possible
-
-Python execution requires a native Linux worker with Landlock ABI 3 or later and seccomp filtering. Build the image for the host architecture. Missing policy files, an incompatible kernel, or an unsupported host such as a macOS source worker returns a clear tool error. There is no unrestricted execution fallback. Keep the container's non-root user, dropped capabilities, no-new-privileges setting, read-only root and writable temporary mount
-
-The worker permits two Python children at once across all investigations. Queued calls consume no child process or scratch directory; cancelling a queued call does not start it. Model, read and search concurrency are separate
-
-| Per-call resource | Default |
-| --- | --- |
-| Elapsed execution time | 60 seconds |
-| CPU time | 30 seconds |
-| Process address space | 512 MiB |
-| Captured stdout or stderr | 4 MiB per stream |
-| Individual scratch file size | 16 MiB |
-| Monitored scratch storage | 64 MiB |
-| Monitored scratch entries | 2,048 |
-| Scratch directory depth | 128 |
-| Open file descriptors | 64 |
-
-Evidence is streamed from gateway pages into the confined child without building another complete selection in worker memory. The child decodes the selected data under its memory limit before running the code. The execution wall clock starts after input delivery; gateway fetches keep their HTTP timeouts and remain cancellable. CPU, address-space and file-size limits apply during input decoding as well as computation. Scratch usage is monitored every 50 milliseconds, so a call can temporarily overshoot its scratch allowance. The worker's shared temporary mount supplies the hard aggregate storage ceiling, 1 GiB by default. Accounting includes unlinked open files and files retained only by memory mappings. A mapped scratch inode without an open descriptor or directory entry is conservatively charged at the individual file-size limit, which may overcount small files. Cancellation and limit failures kill and reap the child before removing its scratch directory
-
-Results include `stdout`, `stderr`, `exit_code`, `error` and `output_complete`. Nonzero interpreter exits, confinement failures and resource failures set `error` and `output_complete=false`. Available traceback output is retained. An output-size failure delivers no partial stdout/stderr; the agent can narrow its computation and retry. A successful result retains all captured output without truncation
-
-This is a process boundary sharing the worker's Linux kernel. The checked-in smoke test verifies useful Python operations, filesystem and process restrictions, raw syscall attempts, resource failures, mapping accounting, cleanup and cancellation in the actual image. Run it on the deployment's native architecture and kernel:
-
-```bash
-docker build --target smoke --build-arg LITELLM_RELEASE_TAG=lens-python-test \
-  -f deploy/lens/Dockerfile -t lens-worker:smoke .
-docker run --rm --read-only --cap-drop ALL \
-  --security-opt no-new-privileges --network none \
-  --tmpfs /tmp:rw,noexec,nosuid,size=1g lens-worker:smoke
-```
-
-The smoke target runs the Rust sandbox integration tests. The production image contains neither Cargo nor the test executable

deploy/lens/compose.build.yaml

@@ -1,8 +0,0 @@
-services:
-  lens-worker:
-    build:
-      context: ../..
-      dockerfile: deploy/lens/Dockerfile
-      args:
-        LITELLM_RELEASE_TAG: ${LITELLM_RELEASE_TAG:?Set the release tag used by the gateway}
-    image: litellm-lens-worker:local

deploy/lens/compose.yaml

@@ -1,21 +0,0 @@
-services:
-  lens-worker:
-    image: ${LENS_WORKER_IMAGE:-${LITELLM_VERSION:+ghcr.io/berriai/litellm-lens-worker:v}${LITELLM_VERSION:-}}
-    environment:
-      LITELLM_URL: ${LITELLM_URL:?Set the URL reachable from this container}
-      LENS_WORKER_TOKEN: ${LENS_WORKER_TOKEN:-}
-      LITELLM_LENS_SERVICE_TOKEN: ${LITELLM_LENS_SERVICE_TOKEN:?Set the same secret on LiteLLM and Lens}
-      CLICKHOUSE_URL: ${CLICKHOUSE_URL:?Set the ClickHouse URL reachable from Lens}
-      CLICKHOUSE_DATABASE: ${CLICKHOUSE_DATABASE:-litellm}
-      AGENT_TRACING_RETENTION_DAYS: ${AGENT_TRACING_RETENTION_DAYS:-14}
-    ports:
-      - "127.0.0.1:${LENS_PORT:-4318}:4318"
-    mem_limit: 2g
-    cpus: 2
-    pids_limit: 64
-    restart: unless-stopped
-    read_only: true
-    tmpfs:
-      - /tmp:rw,noexec,nosuid,size=${LENS_WORKER_TMP_SIZE:-1g}
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]

deploy/lens/config.yaml

@@ -1,7 +0,0 @@
-model_list: []
-
-general_settings:
-  master_key: os.environ/LITELLM_MASTER_KEY
-  tracing:
-    store:
-      type: lens

deploy/lens/configure.py

@@ -1,73 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import os
-import re
-import secrets
-import shlex
-import sys
-from pathlib import Path
-from typing import Final
-
-SECRET_NAMES: Final = (
-    "LITELLM_MASTER_KEY",
-    "LITELLM_SALT_KEY",
-    "LITELLM_LENS_SERVICE_TOKEN",
-    "POSTGRES_PASSWORD",
-    "CLICKHOUSE_PASSWORD",
-)
-
-
-def environment_content(path: Path) -> str:
-    if not path.exists():
-        return "".join(
-            f"{name}={'sk-' if name.endswith('KEY') else ''}{secrets.token_hex(32)}\n" for name in SECRET_NAMES
-        )
-    saved: Final = path.read_text().splitlines()
-    values: Final = dict(line.split("=", 1) for line in saved if "=" in line)
-    if any(not values.get(name) for name in SECRET_NAMES):
-        raise ValueError(f"{path} is incomplete. Restore your saved credentials before continuing")
-    return "\n".join(line for line in saved if not line.startswith("LITELLM_VERSION=")) + "\n"
-
-
-def configure(path: Path, version: str) -> None:
-    release: Final = version.removeprefix("v")
-    if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+(?:[-.][a-zA-Z0-9.-]+)?", release):
-        raise ValueError("Use a published release version, such as 1.82.0 or 1.82.0-nightly")
-    if path.is_symlink():
-        raise ValueError(f"Refusing to replace a symlink: {path}")
-    existing: Final = path.exists()
-    content: Final = environment_content(path)
-    temporary: Final = path.with_name(f".{path.name}.{secrets.token_hex(8)}")
-    descriptor: Final = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
-    try:
-        with os.fdopen(descriptor, "w") as output:
-            output.write(content + f"LITELLM_VERSION={release}\n")
-        if existing:
-            os.replace(temporary, path)
-        else:
-            os.link(temporary, path)
-    finally:
-        temporary.unlink(missing_ok=True)
-
-
-def main() -> None:
-    parser: Final = argparse.ArgumentParser(description="Create or update the configuration for the Lens Compose stack")
-    parser.add_argument("--version", required=True, help="Published LiteLLM release; Lens uses the matching version")
-    parser.add_argument("--env-file", type=Path, default=Path(__file__).with_name(".env"))
-    arguments: Final = parser.parse_args()
-    try:
-        configure(arguments.env_file, arguments.version)
-    except (OSError, ValueError) as error:
-        parser.exit(1, f"Could not configure Lens: {error}\n")
-    sys.stdout.write(
-        f"Saved {arguments.env_file}. Existing keys and database passwords are preserved\n"
-        f"Start with: docker compose --env-file {shlex.quote(str(arguments.env_file))} "
-        "-f deploy/lens/stack.yaml up -d --wait\n"
-        "Open http://localhost:4000/ui/ and sign in as admin with LITELLM_MASTER_KEY from the saved file\n"
-        "Back up this file with your database volumes. Do not commit it\n"
-    )
-
-
-if __name__ == "__main__":
-    main()

deploy/lens/python_policy.c

@@ -1,63 +0,0 @@
-#include <errno.h>
-#include <fcntl.h>
-#include <seccomp.h>
-#include <stdio.h>
-#include <sys/ioctl.h>
-#include <unistd.h>
-
-static int allow(scmp_filter_ctx policy, const char *name)
-{
-    int number = seccomp_syscall_resolve_name(name);
-    return number < 0 ? 0 : seccomp_rule_add(policy, SCMP_ACT_ALLOW, number, 0);
-}
-
-int main(int argc, char **argv)
-{
-    const char *calls[] = {
-        "read", "write", "readv", "writev", "pread64", "pwrite64", "close", "close_range",
-        "open", "openat", "openat2", "fstat", "stat", "lstat", "newfstatat", "statx",
-        "lseek", "getdents", "getdents64", "access", "faccessat", "faccessat2",
-        "readlink", "readlinkat", "getcwd", "chdir", "fchdir", "statfs", "fstatfs",
-        "mkdir", "mkdirat", "rmdir", "unlink", "unlinkat", "rename", "renameat", "renameat2",
-        "link", "linkat", "symlink", "symlinkat", "truncate", "ftruncate", "fsync", "fdatasync",
-        "mmap", "mmap2", "mprotect", "munmap", "mremap", "madvise", "brk",
-        "rt_sigaction", "rt_sigprocmask", "rt_sigreturn", "rt_sigsuspend", "rt_sigtimedwait", "sigaltstack",
-        "getpid", "getppid", "gettid", "getuid", "geteuid", "getgid", "getegid", "getgroups",
-        "clock_gettime", "clock_getres", "clock_nanosleep", "gettimeofday", "time", "nanosleep",
-        "futex", "futex_time64", "set_tid_address", "set_robust_list", "rseq", "arch_prctl",
-        "sched_getaffinity", "sched_yield", "getrandom", "getrlimit", "setrlimit", "getrusage", "umask",
-        "dup", "dup2", "dup3", "pipe", "pipe2", "poll", "ppoll", "select", "pselect6",
-        "epoll_create", "epoll_create1", "epoll_ctl", "epoll_wait", "epoll_pwait", "epoll_pwait2",
-        "capget", "capset", "prctl", "landlock_create_ruleset", "landlock_add_rule", "landlock_restrict_self",
-        "execve", "exit", "exit_group", "uname", "sysinfo", "restart_syscall"
-    };
-    const int commands[] = {F_DUPFD, F_DUPFD_CLOEXEC, F_GETFD, F_SETFD, F_GETFL, F_GETLK, F_SETLK, F_SETLKW};
-    if (argc != 2) {
-        fputs("Usage: python-policy OUTPUT\n", stderr);
-        return 1;
-    }
-    scmp_filter_ctx policy = seccomp_init(SCMP_ACT_ERRNO(EPERM));
-    if (!policy)
-        return 1;
-    int result = 0;
-    for (size_t i = 0; i < sizeof(calls) / sizeof(calls[0]); i++)
-        result |= allow(policy, calls[i]);
-    result |= seccomp_rule_add(policy, SCMP_ACT_ALLOW, SCMP_SYS(prlimit64), 1, SCMP_A0(SCMP_CMP_EQ, 0));
-    for (size_t i = 0; i < sizeof(commands) / sizeof(commands[0]); i++)
-        result |= seccomp_rule_add(policy, SCMP_ACT_ALLOW, SCMP_SYS(fcntl), 1, SCMP_A1(SCMP_CMP_EQ, commands[i]));
-    result |= seccomp_rule_add(policy, SCMP_ACT_ALLOW, SCMP_SYS(fcntl), 2,
-                              SCMP_A1(SCMP_CMP_EQ, F_SETFL), SCMP_A2(SCMP_CMP_MASKED_EQ, O_ASYNC, 0));
-    result |= seccomp_rule_add(policy, SCMP_ACT_ALLOW, SCMP_SYS(ioctl), 1, SCMP_A1(SCMP_CMP_EQ, FIOCLEX));
-    result |= seccomp_rule_add(policy, SCMP_ACT_ALLOW, SCMP_SYS(ioctl), 1, SCMP_A1(SCMP_CMP_EQ, FIONCLEX));
-    int output = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0444);
-    if (output < 0)
-        result = -1;
-    if (!result)
-        result = seccomp_export_bpf(policy, output);
-    if (output >= 0)
-        close(output);
-    seccomp_release(policy);
-    if (result)
-        fputs("Could not build the Python syscall policy\n", stderr);
-    return result ? 1 : 0;
-}

deploy/lens/python_runtime.py

@@ -1,41 +0,0 @@
-import json
-import subprocess
-import sys
-import sysconfig
-from itertools import chain
-from pathlib import Path
-from typing import Final
-
-
-def dependencies(path: Path, loader: Path) -> tuple[Path, ...]:
-    result: Final = subprocess.run((str(loader), "--list", str(path)), capture_output=True, text=True, check=True)
-    if "not found" in result.stdout:
-        raise RuntimeError(f"Missing Python runtime library: {path}")
-    words: Final = tuple(result.stdout.split())
-    return tuple(Path(word).resolve() for word in words if word.startswith("/"))
-
-
-def main() -> None:
-    stdlib: Final = Path(sysconfig.get_path("stdlib")).resolve()
-    executable: Final = Path(sys.executable).resolve()
-    loaders: Final = tuple(Path("/usr/lib").glob("ld-linux-*.so.*"))
-    if len(loaders) != 1:
-        raise RuntimeError("Expected one native glibc dynamic loader in the Lens worker image")
-    entries: Final = tuple(
-        path for path in stdlib.iterdir() if path.name not in ("site-packages", "dist-packages", "__pycache__")
-    )
-    extensions: Final = tuple((stdlib / "lib-dynload").glob("*.so"))
-    libraries: Final = frozenset(
-        chain.from_iterable(dependencies(binary, loaders[0]) for binary in (executable, *extensions))
-    )
-    manifest: Final = {
-        "executable": str(executable),
-        "directories": (str(stdlib),),
-        "read": tuple(sorted(str(path) for path in {*entries, *libraries})),
-        "execute": tuple(sorted(str(path) for path in (executable, *loaders))),
-    }
-    Path(sys.argv[1]).write_text(json.dumps(manifest), encoding="utf-8")
-
-
-if __name__ == "__main__":
-    main()

deploy/lens/smoke.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-image="${1:?pass the built image reference}"
-release="${2:?pass the expected release tag}"
-version="$(docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges "$image" --version)"
-test "$version" = "litellm-lens $release protocol=7"
-container="$(docker run -d --network none --read-only --cap-drop ALL \
-  --security-opt no-new-privileges --pids-limit 64 --memory 2g --cpus 2 \
-  --tmpfs /tmp:rw,noexec,nosuid,size=256m \
-  -e LITELLM_URL=http://127.0.0.1:1 \
-  -e CLICKHOUSE_URL=http://127.0.0.1:1 \
-  -e LITELLM_LENS_SERVICE_TOKEN=isolated-runtime-smoke-secret-32-characters \
-  "$image")"
-trap 'docker rm -f "$container" >/dev/null' EXIT
-test "$(docker exec "$container" id -u)" = 65532
-docker exec -i "$container" python3.13 -I -S - <<'PY'
-import time
-import urllib.error
-import urllib.request
-
-for attempt in range(50):
-    try:
-        with urllib.request.urlopen("http://127.0.0.1:4318/health/live", timeout=1) as response:
-            assert response.status == 200
-        break
-    except urllib.error.URLError:
-        if attempt == 49:
-            raise
-        time.sleep(0.1)
-
-for path, expected in (("health/ready", 503), ("internal/status", 401)):
-    try:
-        urllib.request.urlopen(f"http://127.0.0.1:4318/{path}", timeout=1)
-    except urllib.error.HTTPError as error:
-        assert error.code == expected, (path, error.code)
-    else:
-        raise AssertionError(f"{path} should return {expected}")
-print("Unprivileged Lens service remains live with unavailable dependencies")
-PY

deploy/lens/stack.yaml

@@ -1,100 +0,0 @@
-name: litellm-lens
-
-services:
-  litellm:
-    image: ghcr.io/berriai/litellm:${LITELLM_VERSION:?Set LITELLM_VERSION to a published release, without the v prefix}
-    entrypoint:
-      - python3
-      - -c
-      - |
-        import os, sys
-        from urllib.parse import quote
-        postgres_password = quote(os.environ["POSTGRES_PASSWORD"], safe="")
-        os.environ["DATABASE_URL"] = f"postgresql://litellm:{postgres_password}@db:5432/litellm"
-        os.execv("docker/prod_entrypoint.sh", ["docker/prod_entrypoint.sh", *sys.argv[1:]])
-    command: ["--config", "/app/lens-config.yaml", "--port", "4000"]
-    environment:
-      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?Set a strong master key}
-      LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?Set a permanent encryption key and keep it across upgrades}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set a permanent database password}
-      STORE_MODEL_IN_DB: "True"
-      LITELLM_LENS_URL: http://lens-worker:4318
-      LITELLM_LENS_PUBLIC_URL: ${LITELLM_LENS_PUBLIC_URL:-http://localhost:4318}
-      LITELLM_LENS_SERVICE_TOKEN: ${LITELLM_LENS_SERVICE_TOKEN:?Set the shared Lens service secret}
-      LENS_WORKER_IMAGE: ghcr.io/berriai/litellm-lens-worker:v${LITELLM_VERSION}
-    volumes:
-      - ./config.yaml:/app/lens-config.yaml:ro
-    ports:
-      - "127.0.0.1:${LITELLM_PORT:-4000}:4000"
-    networks: [proxy, database]
-    depends_on:
-      db:
-        condition: service_healthy
-    restart: unless-stopped
-
-  lens-worker:
-    image: ghcr.io/berriai/litellm-lens-worker:v${LITELLM_VERSION}
-    environment:
-      LITELLM_URL: http://litellm:4000
-      LENS_WORKER_TOKEN: ${LENS_WORKER_TOKEN:-}
-      LITELLM_LENS_SERVICE_TOKEN: ${LITELLM_LENS_SERVICE_TOKEN}
-      CLICKHOUSE_HOST: clickhouse
-      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:?Set a permanent ClickHouse password}
-      CLICKHOUSE_DATABASE: ${CLICKHOUSE_DATABASE:-litellm}
-      AGENT_TRACING_RETENTION_DAYS: ${AGENT_TRACING_RETENTION_DAYS:-14}
-    depends_on: [litellm]
-    networks: [proxy, storage]
-    ports:
-      - "127.0.0.1:${LENS_PORT:-4318}:4318"
-    mem_limit: 2g
-    cpus: 2
-    pids_limit: 64
-    restart: unless-stopped
-    read_only: true
-    tmpfs:
-      - /tmp:rw,noexec,nosuid,size=${LENS_WORKER_TMP_SIZE:-1g}
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-
-  db:
-    image: postgres:16
-    environment:
-      POSTGRES_DB: litellm
-      POSTGRES_USER: litellm
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-    networks: [database]
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
-      interval: 5s
-      timeout: 5s
-      retries: 20
-    restart: unless-stopped
-
-  clickhouse:
-    image: clickhouse/clickhouse-server:26.9.6.6
-    environment:
-      CLICKHOUSE_USER: default
-      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
-      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
-    volumes:
-      - clickhouse_data:/var/lib/clickhouse
-    healthcheck:
-      test: ["CMD", "clickhouse-client", "--user", "default", "--password", "${CLICKHOUSE_PASSWORD}", "--query", "SELECT 1"]
-      interval: 5s
-      timeout: 5s
-      retries: 20
-    restart: unless-stopped
-    networks: [storage]
-
-networks:
-  proxy:
-  database:
-    internal: true
-  storage:
-    internal: true
-
-volumes:
-  postgres_data:
-  clickhouse_data:

deploy/lens/test_configure.py

@@ -1,52 +0,0 @@
-import tempfile
-import unittest
-from pathlib import Path
-
-from configure import SECRET_NAMES, configure
-
-
-class ComposeConfigurationTests(unittest.TestCase):
-    def test_restart_and_upgrade_preserve_private_credentials_and_custom_settings(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            path = Path(directory) / ".env"
-            configure(path, "v1.2.3")
-            original = dict(line.split("=", 1) for line in path.read_text().splitlines())
-            self.assertEqual(path.stat().st_mode & 0o777, 0o600)
-            self.assertEqual(len({original[name] for name in SECRET_NAMES}), len(SECRET_NAMES))
-            self.assertTrue(all(len(original[name]) >= 64 for name in SECRET_NAMES))
-            with path.open("a") as output:
-                output.write("LITELLM_LENS_PUBLIC_URL=https://traces.example/prefix\n")
-            configure(path, "1.2.3")
-            configure(path, "v1.2.4-nightly")
-            updated = dict(line.split("=", 1) for line in path.read_text().splitlines())
-            self.assertEqual({name: updated[name] for name in SECRET_NAMES}, {name: original[name] for name in SECRET_NAMES})
-            self.assertEqual(updated["LITELLM_VERSION"], "1.2.4-nightly")
-            self.assertEqual(updated["LITELLM_LENS_PUBLIC_URL"], "https://traces.example/prefix")
-            self.assertEqual(path.stat().st_mode & 0o777, 0o600)
-
-    def test_incomplete_configuration_is_never_replaced_with_new_database_passwords(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            path = Path(directory) / ".env"
-            original = "POSTGRES_PASSWORD=existing\n"
-            path.write_text(original)
-            with self.assertRaisesRegex(ValueError, "incomplete"):
-                configure(path, "1.2.3")
-            self.assertEqual(path.read_text(), original)
-
-    def test_invalid_release_and_symlink_leave_existing_files_untouched(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            path = Path(directory) / ".env"
-            target = Path(directory) / "saved"
-            target.write_text("preserve")
-            path.symlink_to(target)
-            with self.assertRaisesRegex(ValueError, "symlink"):
-                configure(path, "1.2.3")
-            self.assertEqual(target.read_text(), "preserve")
-            path.unlink()
-            with self.assertRaisesRegex(ValueError, "published release"):
-                configure(path, "1.2.3\nPOSTGRES_PASSWORD=replaced")
-            self.assertFalse(path.exists())
-
-
-if __name__ == "__main__":
-    unittest.main()

docker/Dockerfile.database

@@ -39,6 +39,7 @@ ENV NEXT_TELEMETRY_DISABLED=1 \
 WORKDIR /ui
 
 COPY ui/litellm-dashboard/package.json ui/litellm-dashboard/package-lock.json ./
+COPY ui/litellm-dashboard/vendor/ ./vendor/
 RUN --mount=type=cache,target=/root/.npm npm ci --prefer-offline
 
 COPY ui/litellm-dashboard/ ./

docker/Dockerfile.non_root

@@ -37,6 +37,7 @@ ENV NEXT_TELEMETRY_DISABLED=1 \
 WORKDIR /ui
 
 COPY ui/litellm-dashboard/package.json ui/litellm-dashboard/package-lock.json ./
+COPY ui/litellm-dashboard/vendor/ ./vendor/
 RUN --mount=type=cache,target=/root/.npm npm ci --prefer-offline
 
 COPY ui/litellm-dashboard/ ./

docker/docker-compose.tracing.yml

@@ -13,11 +13,11 @@ services:
       LITELLM_SALT_KEY: sk-local-tracing-salt-key
       DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm
       STORE_MODEL_IN_DB: "True"
-      LITELLM_LENS_URL: http://lens-worker:4318
-      LITELLM_LENS_PUBLIC_URL: http://localhost:4318
+      LITELLM_LENS_URL: ${LITELLM_LENS_URL:?set the Lens URL reachable from the gateway container}
+      LITELLM_LENS_PUBLIC_URL: ${LITELLM_LENS_PUBLIC_URL:?set the Lens URL reachable from your browser and agents}
       LITELLM_LENS_SERVICE_TOKEN: ${LITELLM_LENS_SERVICE_TOKEN:?set LITELLM_LENS_SERVICE_TOKEN}
+      LENS_GATEWAY_SECRET: ${LENS_GATEWAY_SECRET:?set the same signing secret on Lens and the gateway}
       OPENAI_API_KEY: ${OPENAI_API_KEY:-}
-      LENS_WORKER_IMAGE: ${LENS_WORKER_IMAGE:-}
     volumes:
       - ./tracing-config.yaml:/app/tracing-config.yaml:ro
     ports:
@@ -26,29 +26,6 @@ services:
       db:
         condition: service_healthy
 
-  lens-worker:
-    build:
-      context: ..
-      dockerfile: deploy/lens/Dockerfile
-      args:
-        LITELLM_RELEASE_TAG: ${LITELLM_RELEASE_TAG:?set LITELLM_RELEASE_TAG to the source commit}
-    environment:
-      LITELLM_URL: http://litellm:4000
-      LITELLM_LENS_SERVICE_TOKEN: ${LITELLM_LENS_SERVICE_TOKEN:?set LITELLM_LENS_SERVICE_TOKEN}
-      CLICKHOUSE_URL: http://default:local-tracing@clickhouse:8123
-      CLICKHOUSE_DATABASE: litellm
-    ports:
-      - "127.0.0.1:4318:4318"
-    read_only: true
-    cap_drop: [ALL]
-    security_opt: [no-new-privileges:true]
-    tmpfs:
-      - /tmp:rw,noexec,nosuid,nodev,size=${LENS_WORKER_TMP_SIZE:-1g},mode=1777
-    mem_limit: 2g
-    cpus: 2
-    pids_limit: 64
-    restart: unless-stopped
-
   db:
     image: postgres:16
     environment:
@@ -65,22 +42,5 @@ services:
       timeout: 5s
       retries: 10
 
-  clickhouse:
-    image: clickhouse/clickhouse-server:26.9.6.6
-    environment:
-      CLICKHOUSE_USER: default
-      CLICKHOUSE_PASSWORD: local-tracing
-      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
-    volumes:
-      - clickhouse_data:/var/lib/clickhouse
-    ports:
-      - "127.0.0.1:18123:8123"
-    healthcheck:
-      test: ["CMD", "clickhouse-client", "--user", "default", "--password", "local-tracing", "--query", "SELECT 1"]
-      interval: 5s
-      timeout: 5s
-      retries: 20
-
 volumes:
   postgres_data:
-  clickhouse_data:

enterprise/litellm_enterprise/proxy/management_endpoints/project_endpoints.py

@@ -12,7 +12,7 @@ Endpoints for /project operations
 
 import json
 from collections.abc import Mapping, Sequence
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Final, cast
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import TypeAdapter
@@ -31,6 +31,7 @@ from litellm.proxy.management_helpers.utils import (
     management_endpoint_wrapper,
 )
 from litellm.proxy.utils import PrismaClient, handle_exception_on_proxy
+from litellm.repositories.base_repository import record_to_dict
 from litellm.repositories.budget_repository import BudgetRepository
 from litellm.repositories.object_permission_repository import ObjectPermissionRepository
 from litellm.repositories.prisma_protocols import TableActions
@@ -57,6 +58,15 @@ def _project_table(prisma_client: PrismaClient) -> TableActions["prisma_models.L
     return ProjectRepository(prisma_client).table
 
 
+def _writer_project_table(
+    prisma_client: PrismaClient,
+) -> TableActions["prisma_models.LiteLLM_ProjectTable"]:
+    return cast(  # cast-ok: writer_db exposes generated Prisma tables through a dynamic wrapper
+        "TableActions[prisma_models.LiteLLM_ProjectTable]",
+        prisma_client.writer_db.litellm_projecttable,
+    )
+
+
 def _verification_token_table(
     prisma_client: PrismaClient,
 ) -> TableActions["prisma_models.LiteLLM_VerificationToken"]:
@@ -824,6 +834,38 @@ async def update_project(
             **({"max_budget": None} if "max_budget" in data.model_fields_set and data.max_budget is None else {}),
         }
 
+        object_permission_data: Final = update_data.pop("object_permission", None)
+        object_permission_payload: Final = (
+            _OBJECT_PERMISSION_PAYLOAD.validate_python(object_permission_data) if object_permission_data else None
+        )
+
+        if data.team_id is not None:
+            current_project_record: Final = await _writer_project_table(prisma_client).find_unique(
+                where={"project_id": data.project_id}
+            )
+            current_project: Final = (
+                LiteLLM_ProjectTable.model_validate(record_to_dict(current_project_record))
+                if current_project_record is not None
+                else None
+            )
+            if current_project is not None and data.team_id != current_project.team_id:
+                mismatched_key_count: Final = await prisma_client.writer_db.litellm_verificationtoken.count(
+                    where={
+                        "project_id": data.project_id,
+                        "OR": [{"team_id": {"not": data.team_id}}, {"team_id": None}],
+                    }
+                )
+                if mismatched_key_count > 0:
+                    raise ProxyException(
+                        message=(
+                            f"Project {data.project_id} has {mismatched_key_count} key(s) that do not belong to "
+                            f"team {data.team_id}. Detach or delete them before moving the project."
+                        ),
+                        type="bad_request",
+                        code=400,
+                        param="team_id",
+                    )
+
         if budget_updates and existing_project.budget_id:
             # Update existing budget
             await _budget_table(prisma_client).update(
@@ -837,23 +879,17 @@ async def update_project(
             for field in budget_updates.keys():
                 update_data.pop(field, None)
 
-        # Handle object permissions
-        if "object_permission" in update_data:
-            object_permission_data = update_data.pop("object_permission")
-            if object_permission_data:
-                object_permission_payload: Final = _OBJECT_PERMISSION_PAYLOAD.validate_python(object_permission_data)
-                if existing_project.object_permission_id:
-                    # Update existing permission
-                    await _object_permission_table(prisma_client).update(
-                        where={"object_permission_id": existing_project.object_permission_id},
-                        data=object_permission_payload,
-                    )
-                else:
-                    # Create new permission
-                    created_permission: Final = await _object_permission_table(prisma_client).create(
-                        data=object_permission_payload,
-                    )
-                    update_data["object_permission_id"] = created_permission.object_permission_id
+        if object_permission_payload is not None:
+            if existing_project.object_permission_id:
+                await _object_permission_table(prisma_client).update(
+                    where={"object_permission_id": existing_project.object_permission_id},
+                    data=object_permission_payload,
+                )
+            else:
+                created_permission: Final = await _object_permission_table(prisma_client).create(
+                    data=object_permission_payload,
+                )
+                update_data["object_permission_id"] = created_permission.object_permission_id
 
         # Handle metadata fields
         for field in LiteLLM_ManagementEndpoint_MetadataFields:

helm/litellm-helm/Chart.lock

@@ -5,5 +5,8 @@ dependencies:
 - name: redis
   repository: oci://registry-1.docker.io/bitnamicharts
   version: 18.19.1
-digest: sha256:38962e231f6596b93f82a8412bbe4cf5de696caecf5775dfbbd163383eb1c009
-generated: "2026-07-28T10:21:22.511401-07:00"
+- name: lens
+  repository: oci://ghcr.io/berriai/charts
+  version: 0.1.0-dev.0
+digest: sha256:16b92c3d7fc74632e8aa11e602c136d273c774ed39b2fe970b80273e0570898b
+generated: '2026-10-09T04:18:10.643228000Z'

helm/litellm-helm/Chart.yaml

@@ -39,3 +39,6 @@ dependencies:
     version: "18.19.1"
     repository: oci://registry-1.docker.io/bitnamicharts
     condition: redis.enabled
+  - name: lens
+    version: 0.1.0-dev.0
+    repository: oci://ghcr.io/berriai/charts

helm/litellm-helm/README.md

@@ -225,3 +225,9 @@ At the time of writing, the Admin UI is unable to add models. This is because
 it would need to update the `config.yaml` file which is a exposed ConfigMap, and
 therefore, read-only. This is a limitation of this helm chart, not the Admin UI
 itself.
+
+## Connect Lens
+
+`lensWorker.mode` selects `disabled`, `bundled` or `external`. Bundled mode generates separate service and identity-signing credentials. External mode requires `lensWorker.gateway.secretName` and `lensWorker.serviceTokenSecret.name`; their keys default to `gateway-secret` and `service-token`. Provision distinct values matching the external Lens deployment
+
+Follow the [Lens Helm connection guide](https://github.com/BerriAI/lens/blob/main/helm/lens/README.md#connect-a-gateway) for complete values, verification, GitOps credential requirements and existing-data migration. Source-chart installation requires a built Lens image until the first signed Lens release is published

helm/litellm-helm/templates/_helpers.tpl

@@ -323,21 +323,7 @@ through an emptyDir. Empty when the sidecar is off or uses 127.0.0.1 TCP.
 {{- end -}}
 
 {{- define "litellm.lensWorker.image" -}}
-{{- if .Values.lensWorker.image.digest -}}
-{{- if not (regexMatch "^sha256:[0-9a-f]{64}$" .Values.lensWorker.image.digest) -}}
-{{- fail "lensWorker.image.digest must be sha256 followed by 64 lowercase hex characters" -}}
-{{- end -}}
-{{- printf "%s@%s" .Values.lensWorker.image.repository .Values.lensWorker.image.digest -}}
-{{- else -}}
-{{- $backendTag := .Values.image.tag | default .Chart.AppVersion -}}
-{{- $releaseTag := ternary (printf "v%s" $backendTag) $backendTag (regexMatch "^[0-9]" $backendTag) -}}
-{{- $tag := .Values.lensWorker.image.tag | default $releaseTag -}}
-{{- $repository := .Values.lensWorker.image.repository -}}
-{{- if and (hasPrefix "sha-" $tag) (eq $repository "ghcr.io/berriai/litellm-lens-worker") -}}
-{{- $repository = "ghcr.io/berriai/litellm-lens-worker-dev" -}}
-{{- end -}}
-{{- printf "%s:%s" $repository $tag -}}
-{{- end -}}
+{{- include "lens.image" (dict "Values" .Values.lensWorker "Chart" .Subcharts.lens.Chart) -}}
 {{- end -}}
 
 {{- define "litellm.gateway.collectorSocketDir" -}}
@@ -376,13 +362,19 @@ shutdown drain window.
 {{- .Values.lensWorker.serviceTokenSecret.name | default (printf "%s-lens-service" (include "litellm.fullname" .)) -}}
 {{- end -}}
 
+{{- define "litellm.lensWorker.gatewaySecretName" -}}
+{{- .Values.lensWorker.gateway.secretName | default (printf "%s-lens-gateway" (include "litellm.fullname" . | trunc 50 | trimSuffix "-")) -}}
+{{- end -}}
+
 {{- define "litellm.lensWorker.bundledClickhouse" -}}
-{{- if and .Values.lensWorker.enabled .Values.lensWorker.clickhouse.enabled (not .Values.lensWorker.clickhouseSecret.name) -}}true{{- end -}}
+{{- if and (eq (include "litellm.lens.mode" .) "bundled") .Values.lensWorker.clickhouse.enabled (not .Values.lensWorker.clickhouseSecret.name) -}}true{{- end -}}
 {{- end -}}
 
 {{- define "litellm.lensWorker.publicUrl" -}}
 {{- if .Values.lensWorker.publicUrl -}}
 {{- .Values.lensWorker.publicUrl -}}
+{{- else if eq (include "litellm.lens.mode" .) "external" -}}
+{{- fail "lensWorker.publicUrl is required for external Lens" -}}
 {{- else if .Values.lensWorker.ingress.enabled -}}
 {{- $tls := or (not (empty .Values.lensWorker.ingress.tls)) (hasKey .Values.lensWorker.ingress.annotations "alb.ingress.kubernetes.io/certificate-arn") -}}
 {{- printf "%s://%s" (ternary "https" "http" $tls) (required "lensWorker.ingress.host is required" .Values.lensWorker.ingress.host) -}}
@@ -398,3 +390,57 @@ shutdown drain window.
 {{- define "litellm.lensWorker.clickhouseName" -}}
 {{- printf "%s-lens-clickhouse" (include "litellm.fullname" . | trunc 47 | trimSuffix "-") -}}
 {{- end -}}
+
+{{- define "litellm.lensConnectionEnv" -}}
+{{- $mode := include "litellm.lens.mode" . -}}
+{{- if ne $mode "disabled" }}
+{{- if and (eq $mode "external") (not .Values.lensWorker.serviceTokenSecret.name) -}}
+{{- fail "lensWorker.serviceTokenSecret.name is required for external Lens" -}}
+{{- end }}
+{{- if and (eq $mode "external") (not .Values.lensWorker.gateway.secretName) -}}
+{{- fail "lensWorker.gateway.secretName is required for external Lens" -}}
+{{- end -}}
+- name: LITELLM_LENS_URL
+  value: {{ if eq $mode "external" }}{{ required "lensWorker.externalUrl is required for external Lens" .Values.lensWorker.externalUrl | quote }}{{ else }}{{ printf "http://%s-lens-worker:%v" (include "litellm.fullname" .) .Values.lensWorker.service.port | quote }}{{ end }}
+- name: LITELLM_LENS_PUBLIC_URL
+  value: {{ include "litellm.lensWorker.publicUrl" . | quote }}
+- name: LENS_GATEWAY_SECRET
+  valueFrom:
+    secretKeyRef:
+      name: {{ include "litellm.lensWorker.gatewaySecretName" . | quote }}
+      key: {{ .Values.lensWorker.gateway.secretKey | quote }}
+- name: LITELLM_LENS_SERVICE_TOKEN
+  valueFrom:
+    secretKeyRef:
+      name: {{ include "litellm.lensWorker.serviceTokenSecretName" . | quote }}
+      key: {{ .Values.lensWorker.serviceTokenSecret.key | quote }}
+{{- end }}
+{{- end -}}
+
+{{- define "litellm.lens.mode" -}}
+{{- $mode := .Values.lensWorker.mode | default (ternary "bundled" "disabled" .Values.lensWorker.enabled) -}}
+{{- if not (has $mode (list "bundled" "external" "disabled")) -}}
+{{- fail "lensWorker.mode must be bundled, external or disabled" -}}
+{{- end -}}
+{{- $mode -}}
+{{- end -}}
+
+{{- define "litellm.lens.render" -}}
+{{- $root := .root -}}
+{{- $values := mergeOverwrite (deepCopy $root.Subcharts.lens.Values) (deepCopy $root.Values.lensWorker) -}}
+{{- $_ := set $values "fullnameOverride" (printf "%s-lens-worker" (include "litellm.fullname" $root)) -}}
+{{- $_ := set $values "component" "lens-worker" -}}
+{{- $_ := set $values "nameOverride" (printf "%s-lens-worker" (include "litellm.name" $root | trunc 51 | trimSuffix "-")) -}}
+{{- $_ := set $values "imagePullSecrets" $root.Values.imagePullSecrets -}}
+{{- $_ := set $values.gateway "enabled" true -}}
+{{- $_ := set $values.gateway "generatedName" (include "litellm.lensWorker.gatewaySecretName" $root) -}}
+{{- $_ := set $values.clickhouse "nameOverride" (include "litellm.lensWorker.clickhouseName" $root) -}}
+{{- $_ := set $values.serviceTokenSecret "generatedName" (include "litellm.lensWorker.serviceTokenSecretName" $root) -}}
+{{- $_ := set $values "publicUrl" ($root.Values.lensWorker.standaloneUrl | default $root.Subcharts.lens.Values.publicUrl) -}}
+{{- if and (eq .resource "deployment") (or $root.Values.lensWorker.publicUrl $root.Values.lensWorker.ingress.enabled $root.Values.ingress.enabled) -}}
+{{- $ingestion := include "litellm.lensWorker.publicUrl" $root -}}
+{{- $_ := set $values "ingestionUrl" $ingestion -}}
+{{- $_ := set $values "publicUrl" ($root.Values.lensWorker.standaloneUrl | default (trimSuffix "/lens-ingest" $ingestion)) -}}
+{{- end -}}
+{{- include (printf "lens.%s" .resource) (dict "Values" $values "Release" $root.Release "Chart" $root.Subcharts.lens.Chart "Capabilities" $root.Capabilities) -}}
+{{- end -}}

helm/litellm-helm/templates/deployment.yaml

@@ -56,17 +56,7 @@ spec:
           image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           env:
-            {{- if .Values.lensWorker.enabled }}
-            - name: LITELLM_LENS_URL
-              value: {{ printf "http://%s-lens-worker:%v" (include "litellm.fullname" .) .Values.lensWorker.service.port | quote }}
-            - name: LITELLM_LENS_PUBLIC_URL
-              value: {{ include "litellm.lensWorker.publicUrl" . | quote }}
-            - name: LITELLM_LENS_SERVICE_TOKEN
-              valueFrom:
-                secretKeyRef:
-                  name: {{ include "litellm.lensWorker.serviceTokenSecretName" . | quote }}
-                  key: {{ .Values.lensWorker.serviceTokenSecret.key | quote }}
-            {{- end }}
+            {{- include "litellm.lensConnectionEnv" . | nindent 12 }}
             {{- include "litellm.proxyEnv" . | nindent 12 }}
             {{- if .Values.liteadmin.enabled }}
             - name: LITELLM_ADMIN_AGENT_URL

helm/litellm-helm/templates/ingress.yaml

@@ -1,6 +1,8 @@
 {{- if .Values.ingress.enabled -}}
 {{- $fullName := include "litellm.fullname" . -}}
 {{- $svcPort := .Values.service.port -}}
+{{- $lensMode := include "litellm.lens.mode" . -}}
+{{- $lensService := .Values.lensWorker.externalServiceName | default (printf "%s-lens-worker" $fullName) -}}
 {{- if and .Values.ingress.className (not (semverCompare ">=1.18-0" .Capabilities.KubeVersion.GitVersion)) }}
   {{- if not (hasKey .Values.ingress.annotations "kubernetes.io/ingress.class") }}
   {{- $_ := set .Values.ingress.annotations "kubernetes.io/ingress.class" .Values.ingress.className}}
@@ -44,17 +46,17 @@ spec:
     - host: {{ .host | quote }}
       http:
         paths:
-          {{- if $.Values.lensWorker.enabled }}
+          {{- if or (eq $lensMode "bundled") (and (eq $lensMode "external") $.Values.lensWorker.externalServiceName) }}
           - path: /lens-ingest
             pathType: Prefix
             backend:
               {{- if semverCompare ">=1.19-0" $.Capabilities.KubeVersion.GitVersion }}
               service:
-                name: {{ $fullName }}-lens-worker
+                name: {{ if eq $lensMode "external" }}{{ $lensService }}{{ else }}{{ $fullName }}-lens-worker{{ end }}
                 port:
                   number: {{ $.Values.lensWorker.service.port }}
               {{- else }}
-              serviceName: {{ $fullName }}-lens-worker
+              serviceName: {{ if eq $lensMode "external" }}{{ $lensService }}{{ else }}{{ $fullName }}-lens-worker{{ end }}
               servicePort: {{ $.Values.lensWorker.service.port }}
               {{- end }}
           {{- end }}

helm/litellm-helm/templates/lens/clickhouse.yaml

@@ -1,98 +1,3 @@
-{{- if include "litellm.lensWorker.bundledClickhouse" . }}
-{{- $name := include "litellm.lensWorker.clickhouseName" . }}
-apiVersion: v1
-kind: Service
-metadata:
-  name: {{ $name }}
-spec:
-  clusterIP: None
-  selector:
-    app.kubernetes.io/instance: {{ .Release.Name }}
-    app.kubernetes.io/component: lens-clickhouse
-  ports:
-    - name: http
-      port: 8123
-      targetPort: http
----
-apiVersion: apps/v1
-kind: StatefulSet
-metadata:
-  name: {{ $name }}
-spec:
-  serviceName: {{ $name }}
-  replicas: 1
-  selector:
-    matchLabels:
-      app.kubernetes.io/instance: {{ .Release.Name }}
-      app.kubernetes.io/component: lens-clickhouse
-  template:
-    metadata:
-      labels:
-        app.kubernetes.io/instance: {{ .Release.Name }}
-        app.kubernetes.io/component: lens-clickhouse
-    spec:
-      automountServiceAccountToken: false
-      {{- with .Values.imagePullSecrets }}
-      imagePullSecrets:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      securityContext:
-        runAsNonRoot: true
-        runAsUser: 101
-        runAsGroup: 101
-        fsGroup: 101
-        seccompProfile:
-          type: RuntimeDefault
-      containers:
-        - name: clickhouse
-          image: {{ .Values.lensWorker.clickhouse.image | quote }}
-          securityContext:
-            allowPrivilegeEscalation: false
-            capabilities:
-              drop: [ALL]
-          env:
-            - name: CLICKHOUSE_USER
-              value: default
-            - name: CLICKHOUSE_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: {{ $name }}
-                  key: password
-            - name: CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT
-              value: "1"
-          ports:
-            - name: http
-              containerPort: 8123
-          startupProbe:
-            httpGet:
-              path: /ping
-              port: http
-            periodSeconds: 5
-            timeoutSeconds: 3
-            failureThreshold: 60
-          readinessProbe:
-            httpGet:
-              path: /ping
-              port: http
-          livenessProbe:
-            httpGet:
-              path: /ping
-              port: http
-            timeoutSeconds: 3
-          resources:
-            {{- toYaml .Values.lensWorker.clickhouse.resources | nindent 12 }}
-          volumeMounts:
-            - name: data
-              mountPath: /var/lib/clickhouse
-  volumeClaimTemplates:
-    - metadata:
-        name: data
-      spec:
-        accessModes: [ReadWriteOnce]
-        {{- if ne .Values.lensWorker.clickhouse.storageClassName nil }}
-        storageClassName: {{ .Values.lensWorker.clickhouse.storageClassName | quote }}
-        {{- end }}
-        resources:
-          requests:
-            storage: {{ .Values.lensWorker.clickhouse.storage | quote }}
+{{- if eq (include "litellm.lens.mode" .) "bundled" }}
+{{ include "litellm.lens.render" (dict "root" . "resource" "clickhouse") }}
 {{- end }}