chore(databricks): resolve merge conflicts with main

.circleci/config.yml

@@ -38,7 +38,7 @@ commands:
     parameters:
       category:
         type: enum
-        enum: ["backend", "client", "provider-harness"]
+        enum: ["backend", "client", "provider-harness", "redis-compat"]
         default: "backend"
     steps:
       - run:
@@ -229,6 +229,19 @@ commands:
       - wait_for_service:
           url: tcp://localhost:6379
           timeout: "60"
+  install_codecov_cli:
+    steps:
+      - run:
+          name: Install Codecov CLI (pinned v11.3.1)
+          when: always
+          command: |
+            curl -sSLf -o /tmp/codecov https://cli.codecov.io/v11.3.1/linux/codecov
+            curl -sSLf -o /tmp/codecov.SHA256SUM https://cli.codecov.io/v11.3.1/linux/codecov.SHA256SUM
+            [ "$(cat /tmp/codecov.SHA256SUM)" = "ca1d64196d2d34771084afe76ea657d581bf628e31d993ff8e52ea09cc88a56d  codecov" ]
+            (cd /tmp && sha256sum -c codecov.SHA256SUM)
+            chmod +x /tmp/codecov
+            mkdir -p "$HOME/.local/bin"
+            mv /tmp/codecov "$HOME/.local/bin/codecov"
   start_openai_record_replay_proxy:
     description: "Start the record/replay proxy (tests/_openai_record_replay_proxy.py) on host port 8090 and wait until healthy. Models whose api_base points here replay recorded provider responses, so the E2E run neither pays for nor depends on the live provider. The default upstream is OpenAI; a non-OpenAI model must point its api_base at /__recorder_upstream/<host>/ so the recorder forwards there instead of defaulting to OpenAI. Run after uv deps are synced."
     steps:
@@ -511,7 +524,15 @@ jobs:
         auth:
           username: ${DOCKERHUB_USERNAME}
           password: ${DOCKERHUB_PASSWORD}
+      - &postgres16_sidecar
+        image: cimg/postgres:16.0@sha256:b125148bc76e8e8eee5eb3ad6020a3a14110a14e8192f1c645128afebe2e2f84
+        environment:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: litellm_test
     working_directory: ~/project
+    environment: &sidecar_database_url
+      DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/litellm_test"
     parallelism: 4
     steps:
       - checkout
@@ -532,6 +553,9 @@ jobs:
             - ~/.cache/uv
           key: v1-uv-cache-{{ checksum "uv.lock" }}
       - save_cargo_target
+      - wait_for_service:
+          url: tcp://localhost:5432
+          timeout: "60"
       - run:
           name: Run prisma ./docker/entrypoint.sh
           command: |
@@ -586,7 +610,9 @@ jobs:
   local_testing_part2:
     docker:
       - *python312_image
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
     parallelism: 4
     steps:
       - checkout
@@ -606,6 +632,9 @@ jobs:
           paths:
             - ~/.cache/uv
           key: v1-uv-cache-{{ checksum "uv.lock" }}
+      - wait_for_service:
+          url: tcp://localhost:5432
+          timeout: "60"
       - run:
           name: Run prisma ./docker/entrypoint.sh
           command: |
@@ -660,7 +689,9 @@ jobs:
   langfuse_logging_unit_tests:
     docker:
       - *python312_image
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
     resource_class: medium
 
     steps:
@@ -681,6 +712,9 @@ jobs:
           paths:
             - ~/.cache/uv
           key: v1-uv-cache-{{ checksum "uv.lock" }}
+      - wait_for_service:
+          url: tcp://localhost:5432
+          timeout: "60"
       - run:
           name: Run prisma ./docker/entrypoint.sh
           command: |
@@ -709,14 +743,9 @@ jobs:
   auth_ui_unit_tests:
     docker:
       - *python312_image
-      - image: cimg/postgres:16.0@sha256:b125148bc76e8e8eee5eb3ad6020a3a14110a14e8192f1c645128afebe2e2f84
-        environment:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: litellm_test
+      - *postgres16_sidecar
     working_directory: ~/project
-    environment:
-      DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/litellm_test"
+    environment: *sidecar_database_url
 
     steps:
       - checkout
@@ -879,40 +908,6 @@ jobs:
           paths:
             - router_unit_tests_coverage.xml
             - router_unit_tests_coverage
-  litellm_assistants_api_testing: # Runs all tests with the "assistants" keyword
-    docker:
-      - *python312_image
-    working_directory: ~/project
-    resource_class: medium
-
-    steps:
-      - checkout
-      - skip_if_unrelated_changes
-      - setup_google_dns
-      - install_uv
-      - install_rust
-      - run:
-          name: Install Dependencies
-          command: |
-            uv sync --frozen --all-groups --all-extras --python 3.12
-      # Run pytest and generate JUnit XML report
-      - setup_litellm_enterprise_pip
-      - run:
-          name: Run tests
-          command: |
-            mkdir -p test-results
-            TEST_FILES=$(circleci tests glob "tests/local_testing/**/test_*.py")
-            echo "$TEST_FILES" | circleci tests run \
-              --verbose \
-              --command="tr ' ' '\\n' | awk '/\\.py/ {print; next} {sub(/\\.[A-Z][^.]*$/, \"\"); gsub(/\\./, \"/\"); print \$0 \".py\"}' | xargs uv run --no-sync python -m pytest --tb=short \
-                -v \
-                --junitxml=test-results/junit.xml \
-                --durations=5 \
-                -k \"assistants\""
-          no_output_timeout: 15m
-      # Store test results
-      - store_test_results:
-          path: test-results
   llm_translation_testing:
     docker:
       - *python312_image
@@ -1008,49 +1003,6 @@ jobs:
           paths:
             - realtime_translation_coverage.xml
             - realtime_translation_coverage
-  agent_testing:
-    docker:
-      - *python312_image
-    working_directory: ~/project
-
-    steps:
-      - checkout
-      - skip_if_unrelated_changes
-      - setup_google_dns
-      - install_uv
-      - install_rust
-      - run:
-          name: Install Dependencies
-          command: |
-            uv sync --frozen --all-groups --all-extras --python 3.12
-      # Run pytest and generate JUnit XML report
-      - run:
-          name: Run tests
-          command: |
-            mkdir -p test-results
-            TEST_FILES=$(circleci tests glob "tests/agent_tests/test_*.py")
-            echo "$TEST_FILES" | circleci tests run \
-              --verbose \
-              --command="tr ' ' '\\n' | awk '/\\.py/ {print; next} {sub(/\\.[A-Z][^.]*$/, \"\"); gsub(/\\./, \"/\"); print \$0 \".py\"}' | xargs uv run --no-sync python -m pytest --tb=short \
-                -vv -s \
-                --cov=./litellm --cov=./enterprise/litellm_enterprise --cov-report=xml \
-                --junitxml=test-results/junit.xml \
-                --durations=5"
-          no_output_timeout: 15m
-      - run:
-          name: Rename the coverage files
-          command: |
-            mv coverage.xml agent_coverage.xml
-            mv .coverage agent_coverage
-
-      # Store test results
-      - store_test_results:
-          path: test-results
-      - persist_to_workspace:
-          root: .
-          paths:
-            - agent_coverage.xml
-            - agent_coverage
   guardrails_testing:
     docker:
       - *python312_image
@@ -1534,7 +1486,9 @@ jobs:
   installing_litellm_on_python:
     docker:
       - *python312_image
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
 
     steps:
       - checkout
@@ -1547,6 +1501,9 @@ jobs:
           command: |
             uv sync --frozen --all-groups --all-extras --python 3.12
       - setup_litellm_enterprise_pip
+      - wait_for_service:
+          url: tcp://localhost:5432
+          timeout: "60"
       - run:
           name: Run tests
           command: |
@@ -1558,7 +1515,9 @@ jobs:
         auth:
           username: ${DOCKERHUB_USERNAME}
           password: ${DOCKERHUB_PASSWORD}
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
     resource_class: medium
 
     steps:
@@ -1571,6 +1530,9 @@ jobs:
           name: Install Dependencies
           command: |
             uv sync --frozen --all-groups --all-extras --python 3.13
+      - wait_for_service:
+          url: tcp://localhost:5432
+          timeout: "60"
       - run:
           name: Run tests
           command: |
@@ -1579,14 +1541,9 @@ jobs:
   installing_litellm_on_python_v2_migration_resolver:
     docker:
       - *python312_image
-      - image: cimg/postgres:16.0@sha256:b125148bc76e8e8eee5eb3ad6020a3a14110a14e8192f1c645128afebe2e2f84
-        environment:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: litellm_test
+      - *postgres16_sidecar
     working_directory: ~/project
-    environment:
-      DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/litellm_test"
+    environment: *sidecar_database_url
 
     steps:
       - checkout
@@ -1693,6 +1650,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -1716,9 +1678,8 @@ jobs:
           command: |
             docker run -d \
               -p 4001:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL="postgresql://postgres:postgres@host.docker.internal:5432/litellm_test" \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               --name schema-seed \
               --add-host=host.docker.internal:host-gateway \
               -v $(pwd)/litellm/proxy/example_config_yaml/simple_config.yaml:/app/config.yaml \
@@ -1789,6 +1750,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - attach_workspace:
           at: ~/project
@@ -1812,9 +1778,8 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e USE_PRISMA_MIGRATE=True \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e AZURE_API_KEY=$AZURE_API_KEY \
@@ -1859,7 +1824,7 @@ jobs:
           name: Seed the routing strategy through /config/update
           command: |
             curl --noproxy '*' -sSf -X POST http://localhost:4000/config/update \
-              -H 'Authorization: Bearer sk-1234' -H 'Content-Type: application/json' \
+              -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
               -d '{"router_settings": {"routing_strategy": "usage-based-routing-v2"}}'
       - run:
           name: Run tests
@@ -1888,6 +1853,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -1909,9 +1879,8 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e AZURE_API_KEY=$AZURE_API_KEY \
               -e AZURE_API_BASE=$AZURE_API_BASE \
               -e AZURE_API_VERSION="2024-05-01-preview" \
@@ -1974,6 +1943,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -1999,12 +1973,11 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
               -e REDIS_HOST=$REDIS_HOST \
               -e REDIS_PASSWORD=$REDIS_PASSWORD \
               -e REDIS_PORT=$REDIS_PORT \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e OPENAI_API_KEY=$OPENAI_API_KEY \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e LITELLM_LICENSE=$LITELLM_LICENSE \
@@ -2060,12 +2033,11 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
               -e REDIS_HOST=$REDIS_HOST \
               -e REDIS_PASSWORD=$REDIS_PASSWORD \
               -e REDIS_PORT=$REDIS_PORT \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e OPENAI_API_KEY=$OPENAI_API_KEY \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e LITELLM_LICENSE="bad-license" \
@@ -2102,94 +2074,6 @@ jobs:
       # Store test results
       - store_test_results:
           path: test-results
-  proxy_spend_accuracy_tests:
-    machine:
-      image: ubuntu-2204:2024.04.1
-    resource_class: large
-    working_directory: ~/project
-    steps:
-      - checkout
-      - skip_if_unrelated_changes
-      - setup_google_dns
-      - install_uv
-      - install_rust
-      - run:
-          name: Install Dependencies
-          command: |
-            uv sync --frozen --all-groups --all-extras --python 3.12
-      - start_postgres
-      - start_redis
-      - start_fake_openai_endpoint
-      - attach_workspace:
-          at: ~/project
-      - run:
-          name: Load Docker Database Image
-          command: |
-            zstd -d litellm-docker-database.tar.zst --stdout | docker load
-            docker images | grep litellm-docker-database
-      - run:
-          name: Run Docker container
-          # Point the proxy at the job-local Redis (start_redis) instead of the
-          # shared remote Redis. The Redis transaction buffer uses a single
-          # global pod-lock key (cronjob_lock:db_spend_update_job) and a single
-          # global buffer list (litellm_spend_update_buffer); sharing those
-          # across concurrent CI pipelines causes spend flushes to stall or
-          # land in the wrong DB, which is what makes this test flaky.
-          command: |
-            docker run -d \
-              -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
-              -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
-              -e REDIS_HOST=host.docker.internal \
-              -e REDIS_PORT=6379 \
-              -e LITELLM_MASTER_KEY="sk-1234" \
-              -e OPENAI_API_KEY=$OPENAI_API_KEY \
-              -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
-              -e LITELLM_LICENSE=$LITELLM_LICENSE \
-              -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
-              -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
-              -e USE_DDTRACE=True \
-              -e DD_API_KEY=$DD_API_KEY \
-              -e DD_SITE=$DD_SITE \
-              -e AWS_REGION_NAME=$AWS_REGION_NAME \
-              -e PROXY_BATCH_WRITE_AT=2 \
-              -e LITELLM_LOG=ERROR \
-              --add-host host.docker.internal:host-gateway \
-              --name my-app \
-              -v $(pwd)/litellm/proxy/example_config_yaml/spend_tracking_config.yaml:/app/config.yaml \
-              litellm-docker-database:ci \
-              --config /app/config.yaml \
-              --port 4000
-      - run:
-          name: Start outputting logs
-          command: docker logs -f my-app
-          background: true
-      - wait_for_service:
-          url: http://localhost:4000
-          timeout: "300"
-      - run:
-          name: Run tests
-          command: |
-            mkdir -p test-results
-            TEST_FILES=$(circleci tests glob "tests/spend_tracking_tests/**/test_*.py")
-            echo "$TEST_FILES" | circleci tests run \
-              --verbose \
-              --command="tr ' ' '\\n' | awk '/\\.py/ {print; next} {sub(/\\.[A-Z][^.]*$/, \"\"); gsub(/\\./, \"/\"); print \$0 \".py\"}' | xargs uv run --no-sync python -m pytest --tb=short \
-                -vv \
-                --junitxml=test-results/junit.xml \
-                --durations=5"
-          no_output_timeout: 15m
-      - store_test_results:
-          path: test-results
-      - run:
-          name: Stop and remove first container
-          when: always
-          command: |
-            docker stop my-app
-            docker rm my-app
-            docker stop redis-cache
-            docker rm redis-cache
-
   proxy_multi_instance_tests:
     machine:
       image: ubuntu-2204:2024.04.1
@@ -2197,6 +2081,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -2221,12 +2110,11 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
               -e REDIS_HOST=$REDIS_HOST \
               -e REDIS_PASSWORD=$REDIS_PASSWORD \
               -e REDIS_PORT=$REDIS_PORT \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e LITELLM_LICENSE=$LITELLM_LICENSE \
               -e USE_DDTRACE=True \
@@ -2244,12 +2132,11 @@ jobs:
           command: |
             docker run -d \
               -p 4001:4001 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
               -e REDIS_HOST=$REDIS_HOST \
               -e REDIS_PASSWORD=$REDIS_PASSWORD \
               -e REDIS_PORT=$REDIS_PORT \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e LITELLM_LICENSE=$LITELLM_LICENSE \
               -e USE_DDTRACE=True \
@@ -2296,6 +2183,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -2322,10 +2214,9 @@ jobs:
             docker run -d \
               --restart on-failure \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
               -e STORE_MODEL_IN_DB="True" \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e TEAM_METADATA_VALIDATION_SERVICE_URL=http://host.docker.internal:9414/validate \
               -e LITELLM_LICENSE=$LITELLM_LICENSE \
@@ -2375,6 +2266,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       # Remove Docker CLI installation since it's already available in machine executor
@@ -2397,12 +2293,11 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
               -e REDIS_HOST=$REDIS_HOST \
               -e REDIS_PASSWORD=$REDIS_PASSWORD \
               -e REDIS_PORT=$REDIS_PORT \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e OPENAI_API_KEY=$OPENAI_API_KEY \
               -e FAKE_OPENAI_API_BASE=http://host.docker.internal:8190 \
               -e LITELLM_LICENSE=$LITELLM_LICENSE \
@@ -2459,6 +2354,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -2480,9 +2380,8 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e OPENAI_API_KEY=$OPENAI_API_KEY \
               -e GEMINI_API_KEY=$GEMINI_API_KEY \
               -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
@@ -2550,6 +2449,11 @@ jobs:
     working_directory: ~/project
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes
       - setup_google_dns
       - install_uv
@@ -2572,9 +2476,8 @@ jobs:
           command: |
             docker run -d \
               -p 4000:4000 \
-              -e LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY=true \
               -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/circle_test \
-              -e LITELLM_MASTER_KEY="sk-1234" \
+              -e LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" \
               -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
               -e RECORDER_ANTHROPIC_BASE_URL=http://host.docker.internal:8090/__recorder_upstream/api.anthropic.com \
               -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
@@ -2600,7 +2503,7 @@ jobs:
           command: |
             mkdir -p test-results
             export LITELLM_PROXY_URL="http://localhost:4000"
-            export LITELLM_API_KEY="sk-1234"
+            export LITELLM_API_KEY="$LITELLM_MASTER_KEY"
             TEST_FILES=$(circleci tests glob "tests/proxy_e2e_anthropic_messages_tests/**/test_*.py")
             echo "$TEST_FILES" | circleci tests run \
               --verbose \
@@ -2634,7 +2537,7 @@ jobs:
       - run:
           name: Combine Coverage
           command: |
-            uv tool run --from 'coverage[toml]==7.10.6' coverage combine realtime_translation_coverage ocr_coverage search_coverage logging_coverage audio_coverage local_testing_part1_coverage local_testing_part2_coverage pass_through_unit_tests_coverage batches_coverage guardrails_coverage agent_coverage google_generate_content_endpoint_coverage litellm_utils_coverage router_unit_tests_coverage auth_ui_unit_tests_coverage
+            uv tool run --from 'coverage[toml]==7.10.6' coverage combine realtime_translation_coverage ocr_coverage search_coverage logging_coverage audio_coverage local_testing_part1_coverage local_testing_part2_coverage pass_through_unit_tests_coverage batches_coverage guardrails_coverage google_generate_content_endpoint_coverage litellm_utils_coverage router_unit_tests_coverage auth_ui_unit_tests_coverage
             uv tool run --from 'coverage[toml]==7.10.6' coverage xml
       - codecov/upload:
           file: ./coverage.xml
@@ -2663,6 +2566,11 @@ jobs:
       PROXY_LOGOUT_URL: "https://www.example.com"
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes:
           category: client
       - setup_google_dns
@@ -2753,8 +2661,6 @@ jobs:
       - run:
           name: Start LiteLLM proxy
           environment:
-            LITELLM_MASTER_KEY: "sk-1234"
-            LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY: "true"
             MOCK_LLM_URL: "http://127.0.0.1:8090/v1"
             DISABLE_SCHEMA_UPDATE: "true"
             SERVER_ROOT_PATH: ""
@@ -2774,7 +2680,7 @@ jobs:
           name: Wait for proxy to be ready
           command: |
             for i in $(seq 1 60); do
-              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:4000/health -H "Authorization: Bearer sk-1234" 2>/dev/null || true)
+              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:4000/health -H "Authorization: Bearer $LITELLM_MASTER_KEY" 2>/dev/null || true)
               if [ "$HTTP_CODE" = "200" ]; then
                 echo "Proxy is ready"
                 exit 0
@@ -2821,6 +2727,11 @@ jobs:
       SERVER_ROOT_PATH: "/litellm"
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes:
           category: client
       - setup_google_dns
@@ -2897,8 +2808,6 @@ jobs:
       - run:
           name: Start LiteLLM proxy under a server root path
           environment:
-            LITELLM_MASTER_KEY: "sk-1234"
-            LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY: "true"
             MOCK_LLM_URL: "http://127.0.0.1:8090/v1"
             DISABLE_SCHEMA_UPDATE: "true"
           # Output flows to this step's own log, so a boot crash is visible here
@@ -2913,7 +2822,7 @@ jobs:
           name: Wait for prefixed proxy to be ready
           command: |
             for i in $(seq 1 60); do
-              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 -H "Authorization: Bearer sk-1234" http://127.0.0.1:4000/litellm/health 2>/dev/null || true)
+              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 -H "Authorization: Bearer $LITELLM_MASTER_KEY" http://127.0.0.1:4000/litellm/health 2>/dev/null || true)
               if [ "$HTTP_CODE" = "200" ]; then
                 echo "Prefixed proxy is ready"
                 exit 0
@@ -3006,6 +2915,11 @@ jobs:
       PYTHONPATH: tests/e2e
     steps:
       - checkout_migration_source
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - install_uv
       - install_rust
       - restore_cache:
@@ -3125,6 +3039,11 @@ jobs:
       E2E_FIXTURE_MODE: live
     steps:
       - checkout
+      - run:
+          name: Generate LiteLLM master key
+          command: |
+            key="$(openssl rand -hex 16)"
+            printf 'export LITELLM_MASTER_KEY=sk-%s\n' "$key" >> "$BASH_ENV"
       - skip_if_unrelated_changes:
           category: provider-harness
       - setup_litellm_test_deps
@@ -3134,10 +3053,10 @@ jobs:
           name: Test provider capture and replay harness
           command: |
             mkdir -p test-results/provider-replay-harness
-            uv run --no-sync pytest --tb=short -q --noconftest -o addopts= -o pythonpath=tests/e2e -p no:rerunfailures \
+            uv run --no-sync pytest --tb=short -q --noconftest -o addopts= -o "pythonpath=tests/e2e tests/e2e_harness" -p no:rerunfailures \
               --junitxml=test-results/provider-replay-harness/junit.xml \
-              tests/e2e/test_provider_edge.py tests/e2e/test_fixture_bundle.py \
-              tests/e2e/test_fixture_canonical.py tests/e2e/test_fixture_mode.py \
+              tests/e2e_harness/test_provider_edge.py tests/e2e_harness/test_fixture_bundle.py \
+              tests/e2e_harness/test_fixture_canonical.py tests/e2e_harness/test_fixture_mode.py \
               tests/code_coverage_tests/test_provider_replay_harness.py \
               tests/code_coverage_tests/test_provider_cache.py
       - store_test_results:
@@ -3154,9 +3073,13 @@ jobs:
       parallelism:
         type: integer
         default: 1
+      resource_class:
+        type: enum
+        enum: [large, xlarge]
+        default: large
     machine:
       image: ubuntu-2204:2024.04.1
-    resource_class: large
+    resource_class: << parameters.resource_class >>
     working_directory: ~/project
     parallelism: << parameters.parallelism >>
     steps:
@@ -3279,30 +3202,164 @@ jobs:
       - store_artifacts:
           path: test-results
 
-  unit:
+  postgres_suite:
+    parameters:
+      test_path:
+        type: string
+      seed:
+        type: boolean
+      coverage_flag:
+        type: string
+        default: ""
+      timeout_minutes:
+        type: integer
     machine:
       image: ubuntu-2204:2024.04.1
     resource_class: large
     working_directory: ~/project
-    parallelism: 4
+    environment:
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/litellm_test
     steps:
+      - checkout
+      - skip_if_unrelated_changes
+      - setup_litellm_test_deps
+      - start_postgres:
+          db_name: litellm_test
+          image: postgres:16@sha256:e17e86066e5ef83e0952a9347f5c792b7ece00972e2aa787a6986f471b3dd3d5
+      - run:
+          name: Generate Prisma client
+          command: uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
+      - when:
+          condition: << parameters.seed >>
+          steps:
+            - run:
+                name: Seed database schema
+                command: uv run --no-sync prisma db push --schema litellm/proxy/schema.prisma --accept-data-loss
+      - run:
+          name: Run << parameters.test_path >>
+          command: |
+            mkdir -p test-results
+            coverage_args=()
+            if [ -n "<< parameters.coverage_flag >>" ]; then
+              coverage_args=(--cov=./litellm --cov-report=xml:coverage.xml)
+            fi
+            timeout --signal=TERM << parameters.timeout_minutes >>m uv run --no-sync pytest \
+              << parameters.test_path >> -vv --tb=short --durations=10 -o junit_family=xunit1 \
+              --junitxml=test-results/junit.xml "${coverage_args[@]}"
+      - when:
+          condition: << parameters.coverage_flag >>
+          steps:
+            - install_codecov_cli
+            - run:
+                name: Upload coverage
+                when: always
+                command: |
+                  [ -f coverage.xml ] || { echo "no coverage.xml produced"; exit 1; }
+                  codecov upload-process --disable-search --fail-on-error -f coverage.xml \
+                    -F << parameters.coverage_flag >> -C "$CIRCLE_SHA1" \
+                    -n "<< parameters.coverage_flag >>-${CIRCLE_BUILD_NUM}" --git-service github
+      - store_test_results:
+          path: test-results
+      - store_artifacts:
+          path: test-results
+
+  mcp_integration:
+    machine:
+      image: ubuntu-2204:2024.04.1
+    resource_class: large
+    working_directory: ~/project
+    environment:
+      COVERAGE_CORE: sysmon
+      LITELLM_LOCAL_MODEL_COST_MAP: "True"
+    steps:
+      - checkout
+      - skip_if_unrelated_changes
       - setup_litellm_test_deps
       - run:
           name: Generate Prisma client
           command: uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
       - run:
-          name: Run unit tests
+          name: Install MCP SDK1 peer
           command: |
-            mkdir -p test-results/unit
-            shard="$(find tests/unit -name 'test_*.py' | sort | circleci tests split --split-by=timings --timings-type=filename)"
-            if [ -z "${shard}" ]; then echo "shard ${CIRCLE_NODE_INDEX} received no tests/unit files; nothing to run"; exit 0; fi
-            mapfile -t files < <(printf '%s\n' "${shard}")
-            set +e
-            LITELLM_LOCAL_MODEL_COST_MAP=True uv run --no-sync pytest "${files[@]}" -p no:rerunfailures -p no:pytest-retry --timeout=90 -n 4 --dist=loadscope --tb=short -o junit_family=xunit1 --junitxml=test-results/unit/junit.xml
-            status=$?
-            set -e
-            if [ "$status" -eq 5 ]; then echo "pytest collected no tests from tests/unit; passing"; exit 0; fi
-            exit "$status"
+            uv venv --python 3.12 .venv-mcp-peer
+            uv pip install --python .venv-mcp-peer 'mcp==1.28.1' 'langchain-mcp-adapters==0.2.1'
+            echo "export MCP_TEST_PEER_PYTHON=$PWD/.venv-mcp-peer/bin/python" >> "$BASH_ENV"
+      - run:
+          name: Run MCP integration tests
+          command: |
+            mkdir -p test-results
+            env -u OPENAI_API_KEY -u ANTHROPIC_API_KEY \
+              timeout --signal=TERM 20m uv run --no-sync pytest \
+              tests/mcp_tests tests/unit/experimental_mcp_client tests/unit/proxy/_experimental/mcp_server \
+              tests/unit/responses/mcp --tb=short -vv --maxfail=10 -n 2 --dist=loadscope --reruns 0 \
+              --reruns-delay 1 --timeout=120 --rerun-except "from pytest-timeout" --durations=20 \
+              --cov=./litellm --cov=./enterprise/litellm_enterprise --cov-report=xml:coverage.xml \
+              --cov-config=pyproject.toml -o junit_family=xunit1 --junitxml=test-results/junit.xml
+      - install_codecov_cli
+      - run:
+          name: Upload MCP integration coverage
+          when: always
+          command: |
+            [ -f coverage.xml ] || { echo "no coverage.xml produced"; exit 1; }
+            codecov upload-process --disable-search --fail-on-error -f coverage.xml \
+              -F mcp-integration -C "$CIRCLE_SHA1" \
+              -n "mcp-integration-${CIRCLE_BUILD_NUM}" --git-service github
+      - store_test_results:
+          path: test-results
+      - store_artifacts:
+          path: test-results
+
+  redis_compat:
+    parameters:
+      redis_py:
+        type: string
+    machine:
+      image: ubuntu-2204:2024.04.1
+    resource_class: large
+    working_directory: ~/project
+    steps:
+      - checkout
+      - skip_if_unrelated_changes:
+          category: redis-compat
+      - setup_litellm_test_deps
+      - run:
+          name: Pin redis-py version
+          command: |
+            uv pip install "redis==<< parameters.redis_py >>"
+            uv run --no-sync python -c "import redis; assert redis.__version__ == '<< parameters.redis_py >>', redis.__version__; print('redis-py', redis.__version__)"
+      - run:
+          name: Install redis-server 7.2.16
+          command: |
+            mkdir -p "$HOME/.local/bin"
+            cid="$(docker create redis:7.2.16@sha256:0637954999d01b7c9ce9167db2da50656e2590d3b884f1c600c5f63bb6e6773c)"
+            docker cp "${cid}":/usr/local/bin/redis-server "$HOME/.local/bin/redis-server"
+            docker rm "$cid"
+            redis-server --version | grep -q 'v=7.2.16'
+      - run:
+          name: Run Redis compatibility tests
+          command: |
+            mkdir -p test-results
+            env -u CASSETTE_REDIS_URL -u AZURE_CLIENT_ID -u AZURE_CLIENT_SECRET -u AZURE_TENANT_ID \
+              timeout --signal=TERM 15m uv run --no-sync pytest \
+              tests/unit/test_redis.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 \
+              tests/local_testing/test_caching.py::test_sync_cluster_authenticates_with_azure_credentials \
+              tests/local_testing/test_caching.py::test_sync_cluster_authenticates_with_gcp_credentials \
+              --tb=short -vv --reruns 2 --reruns-delay 1 --durations=20 --cov=./litellm \
+              --cov-report=xml:coverage.xml -o junit_family=xunit1 --junitxml=test-results/junit.xml
+      - when:
+          condition:
+            equal: ["5.3.1", << parameters.redis_py >>]
+          steps:
+            - install_codecov_cli
+            - run:
+                name: Upload Redis compatibility coverage
+                when: always
+                command: |
+                  [ -f coverage.xml ] || { echo "no coverage.xml produced"; exit 1; }
+                  codecov upload-process --disable-search --fail-on-error -f coverage.xml \
+                    -F redis-compat -C "$CIRCLE_SHA1" \
+                    -n "redis-compat-${CIRCLE_BUILD_NUM}" --git-service github
       - store_test_results:
           path: test-results
       - store_artifacts:
@@ -3365,7 +3422,11 @@ workflows:
           name: integration-<< matrix.suite >>
           matrix:
             parameters:
-              suite: [management, accounting, database, providers, mcp, sdk, cost, security, browser]
+              suite: [management, accounting, database, providers, sdk, cost, security, browser]
+      - integration_contracts:
+          name: integration-mcp
+          suite: mcp
+          resource_class: xlarge
       - integration_contracts:
           name: integration-extensions
           suite: extensions
@@ -3376,6 +3437,39 @@ workflows:
             parameters:
               suite: [management, database]
               mode: [replica]
+      - postgres_suite:
+          name: proxy-behavior
+          test_path: tests/proxy_behavior
+          seed: true
+          coverage_flag: lens-postgres
+          timeout_minutes: 25
+      - postgres_suite:
+          name: proxy-security
+          test_path: tests/proxy_security_tests
+          seed: true
+          timeout_minutes: 15
+      - postgres_suite:
+          name: schema-migration
+          test_path: tests/proxy_migration_tests
+          seed: false
+          timeout_minutes: 20
+      - postgres_suite:
+          name: roi-database
+          test_path: tests/integration/database/test_roi_observed.py
+          seed: false
+          coverage_flag: roi-postgres
+          timeout_minutes: 10
+      - mcp_integration:
+          name: mcp-integration
+      - redis_compat:
+          name: redis-compat-<< matrix.redis_py >>
+          matrix:
+            parameters:
+              redis_py:
+                - "5.3.1"
+                - "6.4.0"
+                - "7.4.1"
+                - "8.0.1"
   build_and_test:
     unless:
       or:
@@ -3385,13 +3479,11 @@ workflows:
     jobs:
       - using_litellm_on_windows
       - windows_release_wheel
-      - unit
       - provider_replay_harness
       - base_sdk_install
       - local_testing_part1
       - local_testing_part2
       - langfuse_logging_unit_tests
-      - litellm_assistants_api_testing
       - litellm_router_testing
       - litellm_router_unit_testing
       - auth_ui_unit_tests
@@ -3407,9 +3499,6 @@ workflows:
       - proxy_logging_guardrails_model_info_tests:
           requires:
             - build_docker_database_image
-      - proxy_spend_accuracy_tests:
-          requires:
-            - build_docker_database_image
       - proxy_multi_instance_tests:
           requires:
             - build_docker_database_image
@@ -3425,7 +3514,6 @@ workflows:
             - build_docker_database_image
       - llm_translation_testing
       - realtime_translation_testing
-      - agent_testing
       - guardrails_testing
       - google_generate_content_endpoint_testing
       - llm_responses_api_testing
@@ -3440,7 +3528,6 @@ workflows:
       - upload-coverage:
           requires:
             - realtime_translation_testing
-            - agent_testing
             - google_generate_content_endpoint_testing
             - guardrails_testing
             - ocr_testing
@@ -3454,7 +3541,6 @@ workflows:
             - langfuse_logging_unit_tests
             - local_testing_part1
             - local_testing_part2
-            - litellm_assistants_api_testing
             - litellm_router_unit_testing
             - auth_ui_unit_tests
       - db_migration_disable_update_check:

.circleci/scripts/classify_changes.sh

@@ -1,7 +1,7 @@
 #!/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>}"
+category="${1:?usage: classify_changes.sh <backend|client|ui|provider-harness|cost-map-only|mcp-dependencies|windows-release|redis-compat>}"
 
 has_client=false
 has_backend=false
@@ -10,17 +10,22 @@ has_provider_harness=false
 has_cost_map=false
 has_mcp_dependencies=false
 has_windows_release=false
+has_redis_compat=false
 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)
+      has_redis_compat=true ;;
+  esac
   case "$file" in
     *.md | *.mdx) : ;;
     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/*.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)
+    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
@@ -54,6 +59,9 @@ case "$category" in
   windows-release)
     [ "$has_windows_release" = true ] && echo run || echo skip
     ;;
+  redis-compat)
+    [ "$has_redis_compat" = true ] && echo run || echo skip
+    ;;
   backend)
     [ "$has_backend" = 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>}"
+category="${1:?usage: path_filter.sh <backend|client|provider-harness|redis-compat>}"
 here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 run_full() {

.circleci/scripts/run_integration.sh

@@ -72,7 +72,7 @@ export PATH="$PWD/.venv/bin:$PATH"
 export PYTHONPATH="$PWD:$PWD/tests:$PWD/tests/e2e"
 export DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:5432/circle_test"
 export REDIS_HOST=127.0.0.1 REDIS_PORT=6379
-export LITELLM_MASTER_KEY=sk-integration-master LITELLM_SALT_KEY=sk-integration-salt
+export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 16)" LITELLM_SALT_KEY=sk-integration-salt
 export LITELLM_MODE=PRODUCTION LITELLM_LOCAL_MODEL_COST_MAP=True
 export STORE_MODEL_IN_DB=True AWS_EC2_METADATA_DISABLED=true DO_NOT_TRACK=1
 export INTEGRATION_PROXY_URL=http://127.0.0.1:4000
@@ -169,11 +169,11 @@ start_proxy() {
     INTEGRATION_UPSTREAM_URL="$INTEGRATION_UPSTREAM_URL" \
     LITELLM_MASTER_KEY="$LITELLM_MASTER_KEY" LITELLM_SALT_KEY="$LITELLM_SALT_KEY" LITELLM_UI_PATH="$LITELLM_UI_PATH" PROXY_BASE_URL="http://127.0.0.1:$port" \
     LITELLM_LICENSE="${LITELLM_LICENSE:-}" \
-    LITELLM_MODE=PRODUCTION STORE_MODEL_IN_DB=True "${cost_map_env[@]}" \
+    LITELLM_MODE=PRODUCTION STORE_MODEL_IN_DB=True LITELLM_ENABLE_MCP_STDIO=true "${cost_map_env[@]}" \
     AWS_EC2_METADATA_DISABLED=true DO_NOT_TRACK=1 COVERAGE_FILE="$coverage_data" \
     "${proxy_command[@]}" --config tests/integration/proxy_config.yaml \
     --host 127.0.0.1 --port "$port" --num_workers 1 --telemetry False \
-    --use_prisma_db_push --enforce_prisma_migration_check \
+    --use_prisma_db_push \
     > "$results/$log_name" 2>&1 &
   launched_pid=$!
 }
@@ -193,10 +193,10 @@ fi
 if [ "$suite" = providers ]; then
   INTEGRATION_RUN_ID="$integration_identity" .venv/bin/python -m pytest --tb=short --noconftest -o addopts= \
     --strict-markers --strict-config -p no:pytest-retry -p no:rerunfailures --timeout=30 \
-    tests/e2e/test_provider_edge.py::TestReplayMode::test_content_drift_returns_the_miss_status_naming_both_keys \
-    tests/e2e/test_provider_edge.py::TestReplayMode::test_exhausted_key_returns_the_miss_status \
-    tests/e2e/test_provider_edge.py::TestReplayLeftover::test_partially_consumed_recording_names_the_leftover \
-    tests/e2e/test_provider_edge.py::TestStreamingFidelity::test_replay_of_a_stream_makes_no_provider_connection \
+    tests/e2e_harness/test_provider_edge.py::TestReplayMode::test_content_drift_returns_the_miss_status_naming_both_keys \
+    tests/e2e_harness/test_provider_edge.py::TestReplayMode::test_exhausted_key_returns_the_miss_status \
+    tests/e2e_harness/test_provider_edge.py::TestReplayLeftover::test_partially_consumed_recording_names_the_leftover \
+    tests/e2e_harness/test_provider_edge.py::TestStreamingFidelity::test_replay_of_a_stream_makes_no_provider_connection \
     --junitxml="$results/replay-controls.xml"
 fi
 

.circleci/scripts/unit_selection.sh

@@ -1,186 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-flag="${1:?usage: unit_selection.sh <codecov flag>}"
-
-legacy_flags=(
-  caching-local
-  core-utils
-  enterprise-package
-  enterprise-routing
-  integrations
-  llm-other-providers
-  llm-vertex-ai
-  mcp-integration
-  misc
-  proxy-db-auth-checks
-  proxy-db-budgets
-  proxy-db-custom-logging
-  proxy-db-db-and-spend
-  proxy-db-endpoints-and-responses
-  proxy-db-guardrails-hooks
-  proxy-db-jwt-and-keys
-  proxy-db-key-generation
-  proxy-db-logging-misc
-  proxy-db-proxy-runtime
-  proxy-db-proxy-server-core
-  proxy-db-proxy-utils
-  proxy-extras
-  proxy-infra
-  responses-caching-types
-)
-
-legacy_paths() {
-  case "$1" in
-    caching-local) echo tests/unit/caching ;;
-    core-utils) echo tests/unit/litellm_core_utils ;;
-    enterprise-package)
-      echo tests/unit/enterprise/integrations
-      echo tests/unit/enterprise/proxy/auth
-      echo tests/unit/enterprise/proxy/guardrails
-      echo tests/unit/enterprise/proxy/hooks
-      echo tests/unit/enterprise/proxy/management_endpoints
-      echo tests/unit/enterprise/proxy/test_audit_logging_endpoints.py
-      echo tests/unit/enterprise/enterprise_callbacks/test_prometheus_logging_callbacks.py ;;
-    enterprise-routing)
-      echo tests/unit/google_genai
-      echo tests/unit/router_strategy
-      echo tests/unit/router_utils
-      echo tests/unit/proxy/common_utils/test_cache_aware_routing.py
-      echo tests/unit/enterprise/enterprise_callbacks/send_emails
-      echo tests/unit/enterprise/proxy/test_afile_retrieve_returns_unified_id.py
-      echo tests/unit/enterprise/proxy/test_batch_retrieve_input_file_id.py
-      echo tests/unit/enterprise/proxy/test_batch_retrieve_registers_missing_output_file_id.py
-      echo tests/unit/enterprise/proxy/test_batch_retrieve_returns_unified_input_file_id.py
-      echo tests/unit/enterprise/proxy/test_batch_update_db_managed_output_file_id.py
-      echo tests/unit/enterprise/proxy/test_deleted_file_returns_403_not_404.py
-      echo tests/unit/enterprise/proxy/test_enterprise_routes.py
-      echo tests/unit/enterprise/proxy/test_file_deletion_blocking.py
-      echo tests/unit/enterprise/proxy/test_managed_files_access_check.py
-      echo tests/unit/enterprise/proxy/test_managed_files_hook.py ;;
-    integrations) echo tests/unit/integrations ;;
-    llm-other-providers) find tests/unit/llms -name 'test_*.py' -not -path 'tests/unit/llms/vertex_ai/*' ;;
-    llm-vertex-ai) echo tests/unit/llms/vertex_ai ;;
-    mcp-integration)
-      echo tests/unit/experimental_mcp_client
-      echo tests/unit/proxy/_experimental/mcp_server
-      echo tests/unit/responses/mcp
-      echo tests/mcp_tests/test_proxy_mcp_e2e.py ;;
-    misc)
-      find tests/unit -maxdepth 1 -name 'test_*.py'
-      echo tests/unit/test_router
-      echo tests/unit/a2a_protocol
-      echo tests/unit/batches
-      echo tests/unit/chat_completions
-      echo tests/unit/completion_extras
-      echo tests/unit/containers
-      echo tests/unit/embeddings
-      echo tests/unit/endpoints
-      echo tests/unit/files
-      echo tests/unit/harness
-      echo tests/unit/images
-      echo tests/unit/interactions
-      echo tests/unit/messages
-      echo tests/unit/rag
-      echo tests/unit/rerank_api
-      echo tests/unit/rust_bridge
-      echo tests/unit/secret_managers
-      echo tests/unit/vector_stores
-      echo tests/unit/videos ;;
-    proxy-db-auth-checks)
-      echo tests/unit/proxy/auth/test_auth_checks.py
-      echo tests/unit/proxy/auth/test_user_api_key_auth.py
-      echo tests/unit/proxy/test_credential_slot_registry.py
-      echo tests/unit/proxy/test_deprecated_key_grace_period.py ;;
-    proxy-db-budgets)
-      echo tests/unit/proxy/auth/test_default_end_user_budget_simple.py
-      echo tests/unit/proxy/hooks/test_unit_test_max_model_budget_limiter.py
-      echo tests/unit/proxy/test_zero_cost_model_budget_bypass.py ;;
-    proxy-db-custom-logging)
-      echo tests/unit/proxy/test_custom_callback_input.py
-      echo tests/unit/proxy/test_custom_logger_s3_gcs.py ;;
-    proxy-db-db-and-spend)
-      echo tests/unit/proxy/common_utils/test_proxy_encrypt_decrypt.py
-      echo tests/unit/proxy/db/db_transaction_queue/test_e2e_pod_lock_manager.py
-      echo tests/unit/proxy/db/test_update_daily_tag_spend.py
-      echo tests/unit/proxy/test_db_schema_changes.py
-      echo tests/unit/proxy/test_prisma_client_backoff_retry.py
-      echo tests/unit/proxy/test_update_spend.py
-      echo tests/unit/skills/test_skills_db.py ;;
-    proxy-db-endpoints-and-responses)
-      echo tests/unit/proxy/lens
-      echo tests/unit/proxy/auth/test_models_fallback_endpoint.py
-      echo tests/unit/proxy/common_utils/test_check_batch_cost.py
-      echo tests/unit/proxy/common_utils/test_check_responses_cost.py
-      echo tests/unit/proxy/common_utils/test_realtime_cache.py
-      echo tests/unit/proxy/google_endpoints/test_gemini_agents_endpoints.py
-      echo tests/unit/proxy/google_endpoints/test_google_endpoint_routing.py
-      echo tests/unit/proxy/google_endpoints/test_google_gemini_proxy_request.py
-      echo tests/unit/proxy/public_endpoints/test_blog_posts_endpoint.py
-      echo tests/unit/proxy/response_polling
-      echo tests/unit/proxy/test_custom_tokenizer_bug.py
-      echo tests/unit/proxy/test_get_favicon.py
-      echo tests/unit/proxy/test_get_image.py
-      echo tests/unit/proxy/test_prompt_test_endpoint.py
-      echo tests/unit/proxy/test_reducto_ocr_route.py
-      echo tests/unit/proxy/test_response_polling_pre_call_checks.py
-      echo tests/unit/proxy/test_ui_path_detection.py ;;
-    proxy-db-guardrails-hooks)
-      echo tests/unit/proxy/hooks/test_banned_keyword_list.py
-      echo tests/unit/proxy/test_proxy_setting_guardrails.py
-      echo tests/unit/proxy/test_unit_test_proxy_hooks.py ;;
-    proxy-db-jwt-and-keys)
-      echo tests/unit/proxy/auth/test_jwt.py
-      echo tests/unit/proxy/management_endpoints/test_jwt_key_mapping.py
-      echo tests/unit/proxy/test_proxy_custom_auth.py ;;
-    proxy-db-key-generation) echo tests/unit/proxy/management_endpoints/test_key_generate_prisma.py ;;
-    proxy-db-logging-misc)
-      echo tests/unit/proxy/management_helpers/test_audit_logs_proxy.py
-      echo tests/unit/proxy/spend_tracking/test_search_api_logging.py
-      echo tests/unit/proxy/test_proxy_reject_logging.py ;;
-    proxy-db-proxy-runtime)
-      echo tests/unit/proxy/auth/test_multipart_bypass_repro.py
-      echo tests/unit/proxy/auth/test_proxy_routes.py
-      echo tests/unit/proxy/middleware/test_request_size_limit_middleware.py
-      echo tests/unit/proxy/test_proxy_config_unit_test.py
-      echo tests/unit/proxy/test_proxy_token_counter.py
-      echo tests/unit/proxy/test_server_root_path.py ;;
-    proxy-db-proxy-server-core)
-      echo tests/unit/proxy/test__lazy_features.py
-      echo tests/unit/proxy/test_aproxy_startup.py
-      echo tests/unit/proxy/test_proxy_server.py ;;
-    proxy-db-proxy-utils) echo tests/unit/proxy/test_proxy_utils.py ;;
-    proxy-extras) echo tests/unit/litellm_proxy_extras ;;
-    proxy-infra)
-      echo tests/unit/gateway
-      echo tests/unit/proxy/management
-      echo tests/unit/proxy/management_endpoints/test_roi_calculator_endpoints.py
-      echo tests/unit/proxy/roi_calculator ;;
-    responses-caching-types)
-      find tests/unit/responses -name 'test_*.py' -not -path 'tests/unit/responses/mcp/*'
-      echo tests/unit/types ;;
-    *) echo "unit_selection.sh: unknown flag $1" >&2; exit 1 ;;
-  esac
-}
-
-expand() {
-  while read -r path; do
-    if [ -d "$path" ]; then
-      find "$path" -name 'test_*.py'
-    elif [ -f "$path" ]; then
-      echo "$path"
-    else
-      echo "unit_selection.sh: $path does not exist" >&2
-      exit 1
-    fi
-  done
-}
-
-if [ "$flag" = unit ]; then
-  comm -23 \
-    <(find tests/unit -name 'test_*.py' | sort) \
-    <(for legacy in "${legacy_flags[@]}"; do legacy_paths "$legacy"; done | expand | sort)
-  exit 0
-fi
-
-legacy_paths "$flag" | expand | sort

.circleci/tests.yml

@@ -1,416 +0,0 @@
-version: 2.1
-
-commands:
-  wait_for_service:
-    parameters:
-      url:
-        type: string
-      timeout:
-        type: string
-        default: "60"
-    steps:
-      - run:
-          name: "Wait for << parameters.url >>"
-          command: |
-            TIMEOUT=<< parameters.timeout >>
-            URL="<< parameters.url >>"
-            ELAPSED=0
-            echo "Waiting up to ${TIMEOUT}s for ${URL} ..."
-            if echo "$URL" | grep -q '^tcp://'; then
-              HOST=$(echo "$URL" | sed 's|tcp://||' | cut -d: -f1)
-              PORT=$(echo "$URL" | sed 's|tcp://||' | cut -d: -f2)
-              while ! bash -c "echo > /dev/tcp/$HOST/$PORT" 2>/dev/null; do
-                sleep 2; ELAPSED=$((ELAPSED+2))
-                if [ "$ELAPSED" -ge "$TIMEOUT" ]; then echo "Timed out"; exit 1; fi
-              done
-            else
-              while ! curl -sf --max-time 5 "$URL" > /dev/null 2>&1; do
-                sleep 2; ELAPSED=$((ELAPSED+2))
-                if [ "$ELAPSED" -ge "$TIMEOUT" ]; then echo "Timed out"; exit 1; fi
-              done
-            fi
-            echo "Service ready after ${ELAPSED}s"
-  install_uv:
-    steps:
-      - run:
-          name: Install uv (pinned 0.10.9)
-          command: |
-            curl -LsSf -o /tmp/uv-install.sh https://astral.sh/uv/0.10.9/install.sh
-            echo "7fc46e39cb97290b57169c0c813a17970585ac519139f19006453c99b5f2f45f  /tmp/uv-install.sh" | sha256sum -c -
-            env UV_NO_MODIFY_PATH=1 sh /tmp/uv-install.sh
-            rm -f /tmp/uv-install.sh
-            echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$BASH_ENV"
-            export PATH="$HOME/.local/bin:$PATH"
-  install_rust:
-    steps:
-      - run:
-          name: Install Rust (rustup 1.28.2, toolchain 1.98.0)
-          command: |
-            case "$(uname -m)" in
-              x86_64)
-                RUSTUP_TRIPLE=x86_64-unknown-linux-gnu
-                RUSTUP_SHA256=20a06e644b0d9bd2fbdbfd52d42540bdde820ea7df86e92e533c073da0cdd43c
-                ;;
-              aarch64)
-                RUSTUP_TRIPLE=aarch64-unknown-linux-gnu
-                RUSTUP_SHA256=e3853c5a252fca15252d07cb23a1bdd9377a8c6f3efa01531109281ae47f841c
-                ;;
-              *)
-                echo "install_rust: unsupported architecture $(uname -m)" >&2
-                exit 1
-                ;;
-            esac
-            curl -sSLf -o /tmp/rustup-init \
-              "https://static.rust-lang.org/rustup/archive/1.28.2/${RUSTUP_TRIPLE}/rustup-init"
-            echo "${RUSTUP_SHA256}  /tmp/rustup-init" | sha256sum -c -
-            chmod +x /tmp/rustup-init
-            /tmp/rustup-init -y --no-modify-path --profile minimal --default-toolchain 1.98.0
-            rm -f /tmp/rustup-init
-            echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> "$BASH_ENV"
-            export PATH="$HOME/.cargo/bin:$PATH"
-            rustc --version
-            cargo --version
-  install_codecov_cli:
-    steps:
-      - run:
-          name: Install Codecov CLI (pinned v11.3.1)
-          when: always
-          command: |
-            curl -sSLf -o /tmp/codecov https://cli.codecov.io/v11.3.1/linux/codecov
-            curl -sSLf -o /tmp/codecov.SHA256SUM https://cli.codecov.io/v11.3.1/linux/codecov.SHA256SUM
-            [ "$(cat /tmp/codecov.SHA256SUM)" = "ca1d64196d2d34771084afe76ea657d581bf628e31d993ff8e52ea09cc88a56d  codecov" ]
-            (cd /tmp && sha256sum -c codecov.SHA256SUM)
-            chmod +x /tmp/codecov
-            mkdir -p "$HOME/.local/bin"
-            mv /tmp/codecov "$HOME/.local/bin/codecov"
-  setup_litellm_enterprise_pip:
-    steps:
-      - run:
-          name: "Install local version of litellm-enterprise"
-          command: |
-            uv run --no-sync python -c "import litellm_enterprise; print('litellm-enterprise OK:', litellm_enterprise.__file__)"
-  setup_test_deps:
-    steps:
-      - install_uv
-      - install_rust
-      - restore_cache:
-          keys:
-            - v3-integration-uv-cache-{{ checksum "uv.lock" }}
-      - run:
-          name: Install Dependencies
-          command: |
-            uv sync --frozen --all-groups --all-extras --python 3.12
-      - setup_litellm_enterprise_pip
-      - save_cache:
-          paths:
-            - ~/.cache/uv
-          key: v3-integration-uv-cache-{{ checksum "uv.lock" }}
-      - run:
-          name: Generate Prisma client
-          command: uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
-  skip_unless_relevant:
-    parameters:
-      category:
-        type: string
-        default: backend
-      base_ref:
-        type: string
-        default: ""
-      pull_request_url:
-        type: string
-        default: ""
-    steps:
-      - run:
-          name: "Skip job when no << parameters.category >>-relevant files changed"
-          command: |
-            export CIRCLE_PULL_REQUEST="${CIRCLE_PULL_REQUEST:-<< parameters.pull_request_url >>}"
-            export PATH_FILTER_BASE_BRANCH="<< parameters.base_ref >>"
-            [ -n "$PATH_FILTER_BASE_BRANCH" ] || unset PATH_FILTER_BASE_BRANCH
-            bash .circleci/scripts/path_filter.sh << parameters.category >>
-  start_postgres:
-    parameters:
-      db_name:
-        type: string
-        default: circle_test
-      image:
-        type: string
-        default: postgres:14@sha256:6a70deda415ec296f977890e11aba04a0db9f632a362e3fce45e845e3db74f26
-    steps:
-      - run:
-          name: Start PostgreSQL
-          command: |
-            docker run -d \
-              --name postgres-db \
-              -e POSTGRES_USER=postgres \
-              -e POSTGRES_PASSWORD=postgres \
-              -e POSTGRES_DB=<< parameters.db_name >> \
-              -p 5432:5432 \
-              << parameters.image >>
-      - wait_for_service:
-          url: tcp://localhost:5432
-          timeout: "60"
-  start_redis:
-    steps:
-      - run:
-          name: Start Redis
-          command: |
-            docker run -d \
-              --name redis-cache \
-              -p 6379:6379 \
-              redis:7-alpine@sha256:7aec734b2bb298a1d769fd8729f13b8514a41bf90fcdd1f38ec52267fbaa8ee6
-      - wait_for_service:
-          url: tcp://localhost:6379
-          timeout: "60"
-
-jobs:
-  unit:
-    parameters:
-      flag:
-        type: string
-        default: unit
-      shards:
-        type: integer
-        default: 6
-      workers:
-        type: integer
-        default: 4
-      dist:
-        type: string
-        default: loadscope
-      base_ref:
-        type: string
-        default: ""
-      pull_request_url:
-        type: string
-        default: ""
-      legacy_mcp_peer:
-        type: boolean
-        default: false
-      reruns:
-        type: integer
-        default: 0
-    machine:
-      image: ubuntu-2204:2024.04.1
-    resource_class: large
-    working_directory: ~/project
-    parallelism: << parameters.shards >>
-    environment:
-      COVERAGE_CORE: sysmon
-      LITELLM_LOCAL_MODEL_COST_MAP: "True"
-    steps:
-      - checkout
-      - skip_unless_relevant:
-          base_ref: << parameters.base_ref >>
-          pull_request_url: << parameters.pull_request_url >>
-      - setup_test_deps
-      - when:
-          condition: << parameters.legacy_mcp_peer >>
-          steps:
-            - run:
-                name: Install MCP SDK1 peer
-                command: |
-                  uv venv --python 3.12 .venv-mcp-peer
-                  uv pip install --python .venv-mcp-peer 'mcp==1.28.1' 'langchain-mcp-adapters==0.2.1'
-                  echo "export MCP_TEST_PEER_PYTHON=$PWD/.venv-mcp-peer/bin/python" >> "$BASH_ENV"
-      - run:
-          name: "Run << parameters.flag >> shard"
-          no_output_timeout: 20m
-          command: |
-            mkdir -p test-results/<< parameters.flag >>
-            selection="$(bash .circleci/scripts/unit_selection.sh << parameters.flag >>)" || { echo "unit_selection.sh failed for << parameters.flag >>"; exit 1; }
-            [ -n "${selection}" ] || { echo "unit_selection.sh produced no files for << parameters.flag >>"; exit 1; }
-            shard="$(printf '%s\n' "${selection}" | circleci tests split --split-by=timings --timings-type=filename)" || { echo "circleci tests split failed for << parameters.flag >>"; exit 1; }
-            [ -n "${shard}" ] || { echo "shard ${CIRCLE_NODE_INDEX} received no << parameters.flag >> files; nothing to run"; exit 0; }
-            mapfile -t files < <(printf '%s\n' "${shard}")
-            xdist_args=()
-            if [ "<< parameters.workers >>" -gt 0 ]; then xdist_args=(-n << parameters.workers >> --dist=<< parameters.dist >>); fi
-            rerun_args=(-p no:rerunfailures)
-            if [ "<< parameters.reruns >>" -gt 0 ]; then rerun_args=(--reruns << parameters.reruns >> --reruns-delay 1 --rerun-except "from pytest-timeout"); fi
-            test_env=(PATH="$PATH" HOME="$HOME" CI=true COVERAGE_CORE="$COVERAGE_CORE" LITELLM_LOCAL_MODEL_COST_MAP="$LITELLM_LOCAL_MODEL_COST_MAP")
-            if [ -n "${MCP_TEST_PEER_PYTHON:-}" ]; then test_env+=(MCP_TEST_PEER_PYTHON="$MCP_TEST_PEER_PYTHON"); fi
-            set +e
-            env -i "${test_env[@]}" \
-              uv run --no-sync pytest "${files[@]}" "${rerun_args[@]}" -p no:pytest-retry --timeout=90 "${xdist_args[@]}" --tb=short --durations=20 -o junit_family=xunit1 --junitxml=test-results/<< parameters.flag >>/junit.xml --cov=./litellm --cov=./enterprise/litellm_enterprise --cov-report=xml:coverage.xml --cov-config=pyproject.toml
-            status=$?
-            set -e
-            if [ "$status" -eq 5 ]; then echo "pytest collected no tests from the shard; passing"; exit 0; fi
-            exit "$status"
-      - install_codecov_cli
-      - run:
-          name: Upload coverage
-          when: always
-          command: |
-            [ -f coverage.xml ] || { echo "no coverage.xml produced; skipping upload"; exit 0; }
-            codecov upload-process --disable-search -f coverage.xml -F << parameters.flag >> -C "$CIRCLE_SHA1" -n "<< parameters.flag >>-${CIRCLE_NODE_INDEX}-${CIRCLE_BUILD_NUM}" --git-service github
-      - store_test_results:
-          path: test-results
-      - store_artifacts:
-          path: test-results
-      - store_artifacts:
-          path: coverage.xml
-  documentation:
-    machine:
-      image: ubuntu-2204:2024.04.1
-    resource_class: large
-    working_directory: ~/project
-    steps:
-      - checkout
-      - setup_test_deps
-      - run:
-          name: Checkout litellm-docs
-          command: rm -rf docs/my-website && git clone --depth 1 https://github.com/BerriAI/litellm-docs.git docs/my-website
-      - run:
-          name: Run documentation validation
-          command: |
-            uv run --no-sync python ./tests/documentation_tests/test_env_keys.py
-            uv run --no-sync python ./tests/documentation_tests/test_router_settings.py
-            uv run --no-sync python ./tests/documentation_tests/test_api_docs.py
-            uv run --no-sync python ./tests/documentation_tests/test_circular_imports.py
-  integration:
-    parameters:
-      suite:
-        type: string
-      base_ref:
-        type: string
-        default: ""
-      pull_request_url:
-        type: string
-        default: ""
-    machine:
-      image: ubuntu-2204:2024.04.1
-    resource_class: large
-    working_directory: ~/project
-    steps:
-      - checkout
-      - skip_unless_relevant:
-          base_ref: << parameters.base_ref >>
-          pull_request_url: << parameters.pull_request_url >>
-      - setup_test_deps
-      - start_postgres:
-          image: postgres:16@sha256:e17e86066e5ef83e0952a9347f5c792b7ece00972e2aa787a6986f471b3dd3d5
-      - start_redis
-      - run:
-          name: Run owned integration contracts
-          command: env -i PATH="$PATH" HOME="$HOME" CIRCLE_SHA1="$CIRCLE_SHA1" CIRCLE_WORKFLOW_ID="$CIRCLE_WORKFLOW_ID" bash .circleci/scripts/run_integration.sh << parameters.suite >>
-          no_output_timeout: 15m
-      - run:
-          name: Stop owned database and Redis
-          when: always
-          command: |
-            mkdir -p test-results/integration-<< parameters.suite >>
-            docker logs postgres-db > test-results/integration-<< parameters.suite >>/postgres.log 2>&1 || true
-            docker logs redis-cache > test-results/integration-<< parameters.suite >>/redis.log 2>&1 || true
-            docker rm -f postgres-db redis-cache
-            test -z "$(docker ps -aq --filter name=postgres-db --filter name=redis-cache)"
-      - store_test_results:
-          path: test-results
-      - store_artifacts:
-          path: test-results
-
-workflows:
-  tests:
-    when: (pipeline.event.name == "push" and pipeline.git.branch == "main") or pipeline.event.name == "api" or (pipeline.event.name == "pull_request" and (pipeline.event.github.pull_request.base.ref == "main" or pipeline.event.github.pull_request.base.ref starts-with "litellm_"))
-    jobs:
-      - unit:
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-<< matrix.flag >>
-          shards: 1
-          workers: 2
-          reruns: 2
-          matrix:
-            parameters:
-              flag: [caching-local, proxy-extras, enterprise-routing]
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-mcp-integration
-          flag: mcp-integration
-          shards: 1
-          workers: 2
-          legacy_mcp_peer: true
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-<< matrix.flag >>
-          shards: 1
-          reruns: 2
-          matrix:
-            parameters:
-              flag:
-                - enterprise-package
-                - proxy-infra
-                - responses-caching-types
-                - proxy-db-auth-checks
-                - proxy-db-jwt-and-keys
-                - proxy-db-proxy-server-core
-                - proxy-db-proxy-runtime
-                - proxy-db-custom-logging
-                - proxy-db-logging-misc
-                - proxy-db-db-and-spend
-                - proxy-db-guardrails-hooks
-                - proxy-db-budgets
-                - proxy-db-endpoints-and-responses
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-llm-vertex-ai
-          flag: llm-vertex-ai
-          shards: 2
-          workers: 1
-          reruns: 2
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-llm-other-providers
-          flag: llm-other-providers
-          shards: 3
-          reruns: 2
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-core-utils
-          flag: core-utils
-          shards: 2
-          reruns: 1
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-integrations
-          flag: integrations
-          shards: 2
-          reruns: 3
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-misc
-          flag: misc
-          shards: 2
-          reruns: 2
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-proxy-db-proxy-utils
-          flag: proxy-db-proxy-utils
-          shards: 1
-          reruns: 2
-          dist: worksteal
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - unit:
-          name: unit-proxy-db-key-generation
-          flag: proxy-db-key-generation
-          shards: 1
-          workers: 0
-          reruns: 2
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>
-      - documentation
-      - integration:
-          name: integration-<< matrix.suite >>
-          matrix:
-            parameters:
-              suite: [sdk]
-          base_ref: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.base.ref or "" >>
-          pull_request_url: << pipeline.event.name == "pull_request" and pipeline.event.github.pull_request.url or "" >>

.gitguardian.yaml

@@ -84,10 +84,6 @@ secret:
     - name: Langfuse test credentials in test_completion
       match: c39310f68cc3d3e22f7b298bb6353c4f45759adcc37080d8b7f4e535d3cfd7f4
     
-    # Test password "sk-1234" in e2e test fixtures - test fixture, not a real secret
-    - name: Test password in e2e test fixtures
-      match: ce32b547202e209ec1dd50107b64be4cfcf2eb15c3b4f8e9dc611ef747af634f
-    
     # === Preventive patterns for test keys (pattern-based) ===
     
     # Test API keys (124 instances across 45 files)
@@ -108,4 +104,3 @@ secret:
 
     - name: Short fake sk keys (1–9 digits only)
       match: \bsk-\d{1,9}\b
-

.github/CODEOWNERS

@@ -1,2 +1,2 @@
-/model_prices_and_context_window.json @mateo-berri @ryan-crabbe-berri @kerry-berri
-/litellm/model_prices_and_context_window_backup.json @mateo-berri @ryan-crabbe-berri @kerry-berri
+/model_prices_and_context_window.json @mateo-berri @ryan-crabbe-berri @kerrylu-berri
+/litellm/model_prices_and_context_window_backup.json @mateo-berri @ryan-crabbe-berri @kerrylu-berri

.github/PULL_REQUEST_TEMPLATE/general.md

@@ -150,7 +150,7 @@ For each e2e test you added or changed, list the manual steps a reviewer can fol
 Example checklists:
 
 - tests/e2e/quota_management/ratelimit/test_rate_limit_e2e.py::TestKeyRateLimits::test_rpm_limit_blocks_over_limit - a key allowed 2 requests a minute serves exactly 2 and refuses the 3rd
-  - [ ] Generate a limited key: curl -X POST http://localhost:4000/key/generate -H "Authorization: Bearer sk-1234" -d '{"rpm_limit": 2}'
+  - [ ] Generate a limited key: curl -X POST http://localhost:4000/key/generate -H "Authorization: Bearer $LITELLM_MASTER_KEY" -d '{"rpm_limit": 2}'
   - [ ] Send three /v1/chat/completions requests with that key inside one minute
   - [ ] Expect the first two to return 200 and the third to return 429 naming the rpm limit
   - [ ] Sanity check: this test makes sense to add and is not hand-wavey (e.g., assert actual expected spend instead of just spend > 0) or potentially flaky
@@ -164,4 +164,3 @@ Example checklists:
 ## Final Attestation
 
 - [ ] The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR
-

.github/PULL_REQUEST_TEMPLATE/rust.md

@@ -0,0 +1 @@
+<!-- Write the final PR description as concise bullets only -->

.github/actions/rust-bridge/action.yml

@@ -0,0 +1,19 @@
+name: Set up the Rust bridge
+description: Select the shared Rust bridge artifact or the Cargo cache
+inputs:
+  artifact:
+    description: Rust bridge artifact name
+    required: false
+    default: ""
+runs:
+  using: composite
+  steps:
+    - name: Restore the Cargo build cache
+      if: inputs.artifact == ''
+      uses: ./.github/actions/cache-cargo-build
+    - name: Download the Rust bridge artifact
+      if: inputs.artifact != ''
+      uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e
+      with:
+        name: ${{ inputs.artifact }}
+        path: rust-bridge-dist

.github/ci-coverage-allowlist.yml

@@ -21,7 +21,7 @@ test_paths:
       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, test-redis-compat.yml selects two IAM cluster authentication tests in
+      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

.github/codeql/codeql-config.yml

@@ -1,8 +1,5 @@
 name: "LiteLLM CodeQL config"
 
-queries:
-  - uses: security-and-quality
-
 # Known OOM queries on large Python codebases:
 # CodeQL builds a full data flow graph in memory. These two queries trace
 # sensitive data through every log call / regex pattern, causing combinatorial
@@ -14,17 +11,6 @@ query-filters:
       id: py/clear-text-logging-sensitive-data  # CWE-312
   - exclude:
       id: py/polynomial-redos                   # CWE-730
-  # Import resolution confuses stdlib types with management_endpoints/types.py.
-  # The generic cycle query also reports intentional deferred imports.
-  - exclude:
-      id: py/cyclic-import
-  - exclude:
-      id: py/unsafe-cyclic-import
-  # Known false positives on live settings and Protocol placeholders.
-  - exclude:
-      id: py/unused-global-variable
-  - exclude:
-      id: py/ineffectual-statement
 
 paths-ignore:
   - tests

.github/e2e-stack/down.sh

@@ -1,17 +0,0 @@
-#!/usr/bin/env bash
-set -uo pipefail
-
-STACK_DIR="${E2E_STACK_DIR:-${RUNNER_TEMP:-/tmp}/litellm-e2e-stack}"
-
-for pid_file in "${STACK_DIR}"/pids/*.pid; do
-  [[ -f "${pid_file}" ]] || continue
-  pkill -TERM -P "$(cat "${pid_file}")" 2>/dev/null
-  kill -TERM "$(cat "${pid_file}")" 2>/dev/null
-  rm -f "${pid_file}"
-done
-
-for container in e2e-nginx e2e-keycloak e2e-valkey e2e-jaeger e2e-postgres; do
-  docker rm -f "${container}" >/dev/null 2>&1
-done
-
-exit 0

.github/e2e-stack/redact_output.py

@@ -1,83 +0,0 @@
-import argparse
-import os
-import sys
-from functools import reduce
-from pathlib import Path
-from typing import Final
-from xml.sax.saxutils import escape
-
-from pydantic import JsonValue, TypeAdapter, ValidationError
-from secrets_to_env import MIN_MASKED_LENGTH
-
-REDACTED: Final = "***"
-json_adapter: Final[TypeAdapter[JsonValue]] = TypeAdapter(JsonValue)
-
-
-def string_leaves(node: JsonValue) -> tuple[str, ...]:
-    match node:
-        case str():
-            return (node,)
-        case list():
-            return tuple(leaf for child in node for leaf in string_leaves(child))
-        case dict():
-            return tuple(leaf for child in node.values() for leaf in string_leaves(child))
-    return ()
-
-
-def field_lines(value: str) -> tuple[str, ...]:
-    try:
-        return tuple(line for leaf in string_leaves(json_adapter.validate_json(value)) for line in leaf.splitlines())
-    except ValidationError:
-        return ()
-
-
-def masked_values(values_files: tuple[Path, ...]) -> tuple[str, ...]:
-    values: Final = frozenset(
-        line.split("=", 1)[1].strip().strip("'")
-        for path in values_files
-        for line in path.read_text().splitlines()
-        if "=" in line
-    )
-    texts: Final = frozenset(text for value in values for text in (value, *field_lines(value)))
-    renderings: Final = frozenset(
-        rendering
-        for text in texts
-        if len(text) >= MIN_MASKED_LENGTH
-        for rendering in (text, escape(text), escape(text, {'"': """}))
-    )
-    return tuple(sorted(renderings, key=lambda rendering: (-len(rendering), rendering)))
-
-
-def redact(text: str, values: tuple[str, ...]) -> str:
-    return reduce(lambda redacted, value: redacted.replace(value, REDACTED), values, text)
-
-
-def write_redacted(source: Path, out_dir: Path, values: tuple[str, ...]) -> None:
-    target: Final = out_dir / source.name
-    with os.fdopen(os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600), "w") as handle:
-        _ = handle.write(redact(source.read_text(errors="replace"), values))
-
-
-def main() -> int:
-    parser: Final = argparse.ArgumentParser()
-    _ = parser.add_argument("--values", action="append", type=Path, required=True)
-    _ = parser.add_argument("--out", type=Path, required=True)
-    _ = parser.add_argument("files", nargs="*", type=Path)
-    args: Final = parser.parse_args()
-    values_files: Final = tuple(args.values)
-    out_dir: Final[Path] = args.out
-    sources: Final = tuple(args.files)
-    try:
-        values: Final = masked_values(values_files)
-        out_dir.mkdir(mode=0o700, exist_ok=True)
-        for source in sources:
-            write_redacted(source, out_dir, values)
-    except OSError as error:
-        _ = sys.stderr.write(f"could not redact {error.filename}\n")
-        return 1
-    _ = sys.stdout.write(f"redacted {len(sources)} file(s) into {out_dir}\n")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/e2e-stack/secrets_to_env.py

@@ -1,55 +0,0 @@
-import os
-import re
-import sys
-from pathlib import Path
-from typing import Final
-
-from pydantic import TypeAdapter, ValidationError
-
-secrets_adapter: Final[TypeAdapter[dict[str, str]]] = TypeAdapter(dict[str, str])
-ENV_NAME: Final = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
-MIN_MASKED_LENGTH: Final = 8
-ACTIONS_RUNNER_FLAG: Final = "GITHUB_ACTIONS"
-
-
-def main() -> int:
-    env_path: Final = Path(sys.argv[1])
-    try:
-        secrets: Final = {
-            key: value.rstrip("\r\n") for key, value in secrets_adapter.validate_json(sys.stdin.read()).items()
-        }
-    except (ValidationError, UnicodeError):
-        _ = sys.stderr.write("expected a JSON object containing string environment values\n")
-        return 1
-    unusable: Final = tuple(
-        key
-        for key, value in secrets.items()
-        if ENV_NAME.fullmatch(key) is None or any(char in value for char in "'\n\r\0")
-    )
-    if unusable:
-        _ = sys.stderr.write(
-            f"these names or values cannot be represented in both bash and dotenv: {' '.join(sorted(unusable))}\n"
-        )
-        return 1
-    if os.environ.get(ACTIONS_RUNNER_FLAG) == "true":
-        _ = sys.stdout.write(
-            "".join(
-                f"::add-mask::{value.replace('%', '%25')}\n"
-                for value in secrets.values()
-                if len(value) >= MIN_MASKED_LENGTH
-            )
-        )
-        sys.stdout.flush()
-    lines: Final = tuple(f"{key}='{value}'" for key, value in secrets.items() if value)
-    try:
-        with os.fdopen(os.open(env_path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW, 0o600), "w") as handle:
-            os.fchmod(handle.fileno(), 0o600)
-            _ = handle.write("\n".join(lines) + "\n")
-    except OSError:
-        _ = sys.stderr.write("could not write the environment file\n")
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/e2e-stack/select_tests.py

@@ -1,52 +0,0 @@
-import re
-import sys
-from typing import Final
-
-SELECTABLE: Final = re.compile(r"^tests/e2e/([A-Za-z0-9_.-]+/)*test_[A-Za-z0-9_.-]+\.py$")
-UNSUPPORTED: Final = re.compile(
-    r"^tests/e2e/(ui|claude_code|load|migrations)/"
-    r"|^tests/e2e/mcp/test_mcp_oauth_happy_path_e2e\.py$"
-    r"|^tests/e2e/llm_translation/realtime/test_realtime_pipecat_audio_e2e\.py$"
-    r"|^tests/e2e/batches/test_managed_files_enforcement_e2e\.py$"
-    r"|^tests/e2e/guardrails/test_presidio_masking_e2e\.py$"
-    r"|^tests/e2e/logging/test_otel_v2_langfuse_generation_output_e2e\.py$"
-    r"|^tests/e2e/logging/test_langsmith_batch_serialization_e2e\.py$"
-    r"|^tests/e2e/logging/test_s3_log_e2e\.py$"
-    r"|^tests/e2e/secret_manager/"
-)
-HARNESS: Final = re.compile(
-    r"^tests/e2e/[A-Za-z0-9_.-]+\.(py|ini)$"
-    r"|^tests/e2e/idp_realm\.json$"
-    r"|^tests/e2e/management/(management_client|jwt_actors|conftest)\.py$"
-    r"|^tests/e2e/coverage_registry/management_cases\.py$"
-    r"|^tests/e2e/gateway/"
-    r"|^\.github/e2e-stack/"
-    r"|^\.github/workflows/test-e2e-changed\.yml$"
-)
-UNEXPANDED: Final = re.compile(r"[*?\[]")
-
-
-def is_selectable(path: str) -> bool:
-    return SELECTABLE.match(path) is not None and UNSUPPORTED.match(path) is None
-
-
-def select(changed: tuple[str, ...], canary: tuple[str, ...]) -> tuple[str, ...]:
-    direct: Final = frozenset(path for path in changed if is_selectable(path))
-    harness_changed: Final = any(HARNESS.match(path) for path in changed)
-    canary_tests: Final = frozenset(path for path in canary if harness_changed and is_selectable(path))
-    return tuple(sorted(direct | canary_tests))
-
-
-def main() -> int:
-    canary: Final = tuple(sys.argv[1:])
-    unexpanded: Final = tuple(path for path in canary if UNEXPANDED.search(path))
-    if unexpanded:
-        _ = sys.stderr.write(f"the canary paths reached the selector unexpanded: {' '.join(unexpanded)}\n")
-        return 1
-    changed: Final = tuple(line.strip() for line in sys.stdin if line.strip())
-    _ = sys.stdout.write(" ".join(select(changed, canary)) + "\n")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

.github/e2e-stack/up.sh

@@ -1,231 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-umask 077
-
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-STACK_DIR="${E2E_STACK_DIR:-${RUNNER_TEMP:-/tmp}/litellm-e2e-stack}"
-CERTS_DIR="${STACK_DIR}/certs"
-LOGS_DIR="${STACK_DIR}/logs"
-PIDS_DIR="${STACK_DIR}/pids"
-
-POSTGRES_IMAGE="${E2E_POSTGRES_IMAGE:-postgres:16.6}"
-VALKEY_IMAGE="${E2E_VALKEY_IMAGE:-valkey/valkey:8.1.4@sha256:81db6d39e1bba3b3ff32bd3a1b19a6d69690f94a3954ec131277b9a26b95b3aa}"
-JAEGER_IMAGE="${E2E_JAEGER_IMAGE:-jaegertracing/jaeger:2.10.0}"
-NGINX_IMAGE="${E2E_NGINX_IMAGE:-nginx:1.29.1-alpine@sha256:42a516af16b852e33b7682d5ef8acbd5d13fe08fecadc7ed98605ba5e3b26ab8}"
-
-LB_PORT="${E2E_LB_PORT:-4000}"
-GATEWAY_PORT_1="${E2E_GATEWAY_PORT_1:-4010}"
-GATEWAY_PORT_2="${E2E_GATEWAY_PORT_2:-4011}"
-BACKEND_PORT="${E2E_BACKEND_PORT:-4001}"
-REDIS_PORT="${E2E_REDIS_PORT:-6379}"
-DATABASE_HOST="${E2E_DATABASE_HOST:-127.0.0.1}"
-DATABASE_PORT="${E2E_DATABASE_PORT:-5432}"
-DATABASE_USER="${E2E_DATABASE_USER:-litellm}"
-DATABASE_PASSWORD="${E2E_DATABASE_PASSWORD:-dbpassword9090}"
-DATABASE_NAME="${E2E_DATABASE_NAME:-litellm}"
-JAEGER_OTLP_PORT="${E2E_JAEGER_OTLP_PORT:-4318}"
-JAEGER_OTLP_TLS_PORT="${E2E_JAEGER_OTLP_TLS_PORT:-4319}"
-JAEGER_QUERY_PORT="${E2E_JAEGER_QUERY_PORT:-16686}"
-KEYCLOAK_PORT="${E2E_KEYCLOAK_PORT:-8081}"
-
-MASTER_KEY="${LITELLM_MASTER_KEY:-sk-e2e-$(openssl rand -hex 16)}"
-
-mkdir -p "${CERTS_DIR}" "${LOGS_DIR}" "${PIDS_DIR}"
-chmod 700 "${STACK_DIR}" "${LOGS_DIR}" "${PIDS_DIR}"
-chmod 755 "${CERTS_DIR}"
-
-log() { printf 'e2e-stack: %s\n' "$*"; }
-
-port_open() { (exec 3<>"/dev/tcp/127.0.0.1/$1") 2>/dev/null; }
-
-wait_for() {
-  local label="$1" check="$2" deadline=$((SECONDS + ${3:-120}))
-  until eval "${check}"; do
-    if ((SECONDS >= deadline)); then
-      log "timed out waiting for ${label}"
-      exit 1
-    fi
-    sleep 2
-  done
-  log "${label} is up"
-}
-
-if [[ -f "${REPO_ROOT}/tests/e2e/.env" ]]; then
-  set -a
-  source "${REPO_ROOT}/tests/e2e/.env"
-  set +a
-fi
-
-if [[ -z "${DD_API_KEY:-}" ]]; then
-  log "DD_API_KEY is empty; the gateway config enables the datadog callback, so put a Datadog API key in tests/e2e/.env"
-  exit 1
-fi
-export DD_SITE="${DD_SITE:-datadoghq.com}"
-
-if ! port_open "${DATABASE_PORT}"; then
-  docker run -d --name e2e-postgres -p "${DATABASE_PORT}:5432" \
-    -e "POSTGRES_USER=${DATABASE_USER}" -e "POSTGRES_PASSWORD=${DATABASE_PASSWORD}" -e "POSTGRES_DB=${DATABASE_NAME}" \
-    "${POSTGRES_IMAGE}" >/dev/null
-fi
-wait_for "postgres" "port_open ${DATABASE_PORT}"
-
-if ! port_open "${JAEGER_QUERY_PORT}"; then
-  docker run -d --name e2e-jaeger -p "${JAEGER_OTLP_PORT}:4318" -p "${JAEGER_QUERY_PORT}:16686" \
-    "${JAEGER_IMAGE}" >/dev/null
-fi
-wait_for "jaeger" "curl -fs http://127.0.0.1:${JAEGER_QUERY_PORT}/api/services >/dev/null"
-
-openssl genrsa -out "${CERTS_DIR}/ca.key" 2048 2>/dev/null
-openssl req -x509 -new -nodes -key "${CERTS_DIR}/ca.key" -sha256 -days 7 \
-  -subj "/CN=litellm-e2e-ca" \
-  -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign" \
-  -out "${CERTS_DIR}/ca.crt" 2>/dev/null
-openssl genrsa -out "${CERTS_DIR}/server.key" 2048 2>/dev/null
-openssl req -new -key "${CERTS_DIR}/server.key" -subj "/CN=localhost" -out "${CERTS_DIR}/server.csr" 2>/dev/null
-openssl x509 -req -in "${CERTS_DIR}/server.csr" -CA "${CERTS_DIR}/ca.crt" -CAkey "${CERTS_DIR}/ca.key" \
-  -CAcreateserial -days 7 -sha256 \
-  -extfile <(printf 'basicConstraints=CA:FALSE\nkeyUsage=critical,digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\nsubjectAltName=DNS:localhost,IP:127.0.0.1\n') \
-  -out "${CERTS_DIR}/server.crt" 2>/dev/null
-chmod 644 "${CERTS_DIR}"/*.key "${CERTS_DIR}"/*.crt
-
-CERTIFI_BUNDLE="$(cd "${REPO_ROOT}" && uv run --no-sync python -c 'import certifi; print(certifi.where())')"
-cat "${CERTIFI_BUNDLE}" "${CERTS_DIR}/ca.crt" > "${CERTS_DIR}/ca-bundle.pem"
-
-docker rm -f e2e-valkey >/dev/null 2>&1 || true
-docker run -d --name e2e-valkey -p "${REDIS_PORT}:${REDIS_PORT}" -v "${CERTS_DIR}:/certs:ro" \
-  "${VALKEY_IMAGE}" valkey-server \
-  --cluster-enabled yes --port 0 --tls-port "${REDIS_PORT}" \
-  --tls-cert-file /certs/server.crt --tls-key-file /certs/server.key --tls-ca-cert-file /certs/ca.crt \
-  --tls-auth-clients no --cluster-announce-ip 127.0.0.1 >/dev/null
-VALKEY_CLI="docker exec e2e-valkey valkey-cli --tls --cacert /certs/ca.crt -h 127.0.0.1 -p ${REDIS_PORT}"
-wait_for "valkey" "${VALKEY_CLI} ping 2>/dev/null | grep -q PONG"
-${VALKEY_CLI} cluster addslotsrange 0 16383 >/dev/null
-wait_for "valkey cluster" "${VALKEY_CLI} cluster info 2>/dev/null | grep -q cluster_state:ok"
-
-CONFIG_SOURCE="${REPO_ROOT}/tests/e2e/gateway/stage_mirror_ci_config.yml"
-CONFIG_PATH="${CONFIG_SOURCE}"
-if [[ "${REDIS_PORT}" != "6379" ]]; then
-  CONFIG_PATH="${STACK_DIR}/litellm-config.yml"
-  sed "s/port: 6379/port: ${REDIS_PORT}/" "${CONFIG_SOURCE}" > "${CONFIG_PATH}"
-fi
-
-SERVER_ENV=(
-  "LITELLM_MASTER_KEY=${MASTER_KEY}"
-  "DATABASE_HOST=${DATABASE_HOST}"
-  "DATABASE_PORT=${DATABASE_PORT}"
-  "DATABASE_USER=${DATABASE_USER}"
-  "DATABASE_PASSWORD=${DATABASE_PASSWORD}"
-  "DATABASE_NAME=${DATABASE_NAME}"
-  "DISABLE_SCHEMA_UPDATE=true"
-  "REDIS_HOST=127.0.0.1"
-  "REDIS_PORT=${REDIS_PORT}"
-  "REDIS_CLUSTER_NODES=[{\"host\":\"127.0.0.1\",\"port\":${REDIS_PORT}}]"
-  "CONFIG_FILE_PATH=${CONFIG_PATH}"
-  "STORE_MODEL_IN_DB=True"
-  "OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf"
-  "OTEL_EXPORTER_OTLP_ENDPOINT=https://127.0.0.1:${JAEGER_OTLP_TLS_PORT}"
-  "SSL_CERT_FILE=${CERTS_DIR}/ca-bundle.pem"
-  "PYTHONPATH=${REPO_ROOT}"
-  "JWT_PUBLIC_KEY_URL=http://127.0.0.1:${KEYCLOAK_PORT}/realms/litellm-e2e/protocol/openid-connect/certs"
-  "JWT_ISSUER=http://127.0.0.1:${KEYCLOAK_PORT}/realms/litellm-e2e"
-  "JWT_AUDIENCE=litellm-e2e"
-)
-if [[ -n "${VERTEXAI_CREDENTIALS:-}" ]]; then
-  printf '%s' "${VERTEXAI_CREDENTIALS}" > "${STACK_DIR}/vertex-adc.json"
-  SERVER_ENV+=("GOOGLE_APPLICATION_CREDENTIALS=${STACK_DIR}/vertex-adc.json")
-fi
-
-cd "${REPO_ROOT}"
-
-env "${SERVER_ENV[@]}" "E2E_KEYCLOAK_PORT=${KEYCLOAK_PORT}" bash .github/e2e-stack/start-idp.sh
-
-log "running migrations"
-env "${SERVER_ENV[@]}" uv run --no-sync python migrations/run.py >"${LOGS_DIR}/migrations.log" 2>&1
-
-start_server() {
-  local name="$1"; shift
-  env -u AWS_ROLE_NAME "${SERVER_ENV[@]}" "$@" >"${LOGS_DIR}/${name}.log" 2>&1 &
-  echo $! > "${PIDS_DIR}/${name}.pid"
-}
-
-if [[ "$(uname)" == "Linux" ]]; then
-  NGINX_UPSTREAM_HOST=127.0.0.1
-  NGINX_DOCKER_ARGS=(--network host)
-else
-  NGINX_UPSTREAM_HOST=host.docker.internal
-  NGINX_DOCKER_ARGS=(-p "${LB_PORT}:${LB_PORT}" -p "${JAEGER_OTLP_TLS_PORT}:${JAEGER_OTLP_TLS_PORT}")
-fi
-
-cat > "${STACK_DIR}/nginx.conf" <<EOF
-events {}
-http {
-  map \$http_upgrade \$connection_upgrade {
-    default upgrade;
-    '' close;
-  }
-  upstream litellm_gateways {
-    server ${NGINX_UPSTREAM_HOST}:${GATEWAY_PORT_1};
-    server ${NGINX_UPSTREAM_HOST}:${GATEWAY_PORT_2};
-  }
-  server {
-    listen ${LB_PORT};
-    client_max_body_size 100m;
-    location / {
-      proxy_pass http://litellm_gateways;
-      proxy_http_version 1.1;
-      proxy_set_header Host \$host;
-      proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
-      proxy_set_header X-Forwarded-Proto \$scheme;
-      proxy_set_header Upgrade \$http_upgrade;
-      proxy_set_header Connection \$connection_upgrade;
-      proxy_buffering off;
-      proxy_read_timeout 600s;
-      proxy_send_timeout 600s;
-    }
-  }
-  server {
-    listen ${JAEGER_OTLP_TLS_PORT} ssl;
-    ssl_certificate /certs/server.crt;
-    ssl_certificate_key /certs/server.key;
-    client_max_body_size 100m;
-    location / {
-      proxy_pass http://${NGINX_UPSTREAM_HOST}:${JAEGER_OTLP_PORT};
-    }
-  }
-}
-EOF
-
-docker rm -f e2e-nginx >/dev/null 2>&1 || true
-docker run -d --name e2e-nginx "${NGINX_DOCKER_ARGS[@]}" \
-  -v "${STACK_DIR}/nginx.conf:/etc/nginx/nginx.conf:ro" \
-  -v "${CERTS_DIR}:/certs:ro" "${NGINX_IMAGE}" >/dev/null
-
-wait_for "Jaeger OTLP TLS listener" \
-  "curl -sS --cacert ${CERTS_DIR}/ca.crt https://127.0.0.1:${JAEGER_OTLP_TLS_PORT}/ -o /dev/null -w '%{http_code}' | grep -qE '^[2345]'"
-
-start_server backend uv run --no-sync uvicorn backend.main:app --host 0.0.0.0 --port "${BACKEND_PORT}"
-start_server gateway-1 uv run --no-sync uvicorn gateway.main:app --workers 1 --host 0.0.0.0 --port "${GATEWAY_PORT_1}"
-start_server gateway-2 uv run --no-sync uvicorn gateway.main:app --workers 1 --host 0.0.0.0 --port "${GATEWAY_PORT_2}"
-
-wait_for "backend" "curl -fs http://127.0.0.1:${BACKEND_PORT}/health/liveliness >/dev/null" 300
-wait_for "gateway-1" "curl -fs http://127.0.0.1:${GATEWAY_PORT_1}/health/liveliness >/dev/null" 300
-wait_for "gateway-2" "curl -fs http://127.0.0.1:${GATEWAY_PORT_2}/health/liveliness >/dev/null" 300
-wait_for "load balancer" "curl -fs http://127.0.0.1:${LB_PORT}/health/liveliness >/dev/null" 60
-
-cat > "${STACK_DIR}/stack.env" <<EOF
-LITELLM_PROXY_URL=http://127.0.0.1:${LB_PORT}
-LITELLM_CONTROL_PLANE_URL=http://127.0.0.1:${BACKEND_PORT}
-LITELLM_PROXY_REPLICA_URLS=http://127.0.0.1:${GATEWAY_PORT_1},http://127.0.0.1:${GATEWAY_PORT_2}
-LITELLM_MASTER_KEY=${MASTER_KEY}
-REDIS_HOST=127.0.0.1
-REDIS_PORT=${REDIS_PORT}
-E2E_OTEL_QUERY_URL=http://127.0.0.1:${JAEGER_QUERY_PORT}
-E2E_OTEL_EXPORTER_ENDPOINT=https://127.0.0.1:${JAEGER_OTLP_TLS_PORT}
-E2E_KEYCLOAK_URL=http://127.0.0.1:${KEYCLOAK_PORT}
-E2E_KEYCLOAK_ADMIN_USER=admin
-E2E_KEYCLOAK_ADMIN_PASSWORD=e2e-ephemeral-idp-not-a-secret
-SSL_CERT_FILE=${CERTS_DIR}/ca-bundle.pem
-DATABASE_URL=postgresql://${DATABASE_USER}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}
-EOF
-
-log "stack is up; pytest env written to ${STACK_DIR}/stack.env"

.github/scripts/assert_ci_coverage.py

@@ -9,7 +9,6 @@ import sys
 import warnings
 from collections.abc import Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass
-from types import MappingProxyType
 from typing import Final
 
 import yaml
@@ -22,11 +21,12 @@ TESTS_ROOT = REPO_ROOT / "tests"
 
 ALLOWLIST_KEYS = frozenset({"description", "test_paths", "dockerfiles"})
 PATH_FILTER_KEYS = frozenset({"paths", "paths-ignore"})
-TEST_PATH_KEYS = frozenset({"test-path", "test-paths"})
+TEST_PATH_KEYS = frozenset({"test-path", "test-paths", "test_path"})
 DOCKERFILE_INPUT_KEYS = frozenset({"file", "dockerfile"})
 TEST_RUNNER_RE = re.compile(r"\bpytest\b|\bcircleci tests\b|\bhelm unittest\b|\bplaywright test\b|\bpython[0-9.]*\s")
 IMAGE_BUILD_RE = re.compile(r"\bdocker\s+(?:buildx\s+)?build\b")
 TEST_TOKEN_RE = re.compile(r"tests/[A-Za-z0-9_./*?-]+")
+IGNORE_ARG_RE: Final = re.compile(r"--ignore(?:-glob)?[= ](\S+)")
 DOCKERFILE_TOKEN_RE = re.compile(r"[A-Za-z0-9_./-]*Dockerfile[A-Za-z0-9_.-]*")
 COMMENT_RE = re.compile(r"^\s*#.*$", re.MULTILINE)
 GLOB_CHARS = frozenset("*?")
@@ -72,6 +72,17 @@ class Scalar:
     value: str
 
 
+@dataclass(frozen=True, slots=True)
+class Selection:
+    included: frozenset[str]
+    ignored: frozenset[str]
+
+    def covers(self, relative_path: str) -> bool:
+        return any(_token_covers(token, relative_path) for token in self.included) and not any(
+            _token_covers(token, relative_path) for token in self.ignored
+        )
+
+
 @dataclass(frozen=True, slots=True)
 class Finding:
     subject: str
@@ -111,57 +122,32 @@ def _uncommented(value: str) -> str:
     return COMMENT_RE.sub("", value)
 
 
-def _invoked_test_tokens(scalars: Iterable[Scalar]) -> frozenset[str]:
-    return frozenset(
-        match.group(0).rstrip("/")
+def _selection_for_scalar(scalar: Scalar) -> Selection:
+    text: Final = _uncommented(scalar.value)
+    ignored: Final = frozenset().union(
+        *(
+            frozenset(token.rstrip("/") for token in TEST_TOKEN_RE.findall(ignored_argument))
+            for ignored_argument in IGNORE_ARG_RE.findall(text)
+        )
+    )
+    included: Final = frozenset(
+        match.group(0).rstrip("/") for match in TEST_TOKEN_RE.finditer(IGNORE_ARG_RE.sub("", text))
+    )
+    return Selection(included=included, ignored=ignored)
+
+
+def _invoked_selections(scalars: Iterable[Scalar]) -> tuple[Selection, ...]:
+    selected_scalars: Final = tuple(
+        scalar
         for scalar in scalars
         if scalar.key in TEST_PATH_KEYS or TEST_RUNNER_RE.search(scalar.value)
-        for match in TEST_TOKEN_RE.finditer(_uncommented(scalar.value))
     )
+    selections: Final = tuple(_selection_for_scalar(scalar) for scalar in selected_scalars)
+    return tuple(selection for selection in selections if selection.included)
 
 
-SELECTION_ARM_RE = re.compile(r"(?ms)^\s*([A-Za-z0-9_|*-]+)\)\s*(.*?);;")
-
-
-def _unit_selection_arms(repo_root: pathlib.Path = REPO_ROOT) -> Mapping[str, frozenset[str]]:
-    script: Final = repo_root / ".circleci/scripts/unit_selection.sh"
-    if not script.is_file():
-        return MappingProxyType({})
-    text: Final = _uncommented(script.read_text())
-    return MappingProxyType(
-        {
-            label: frozenset(
-                match.group(0).rstrip("/") for match in TEST_TOKEN_RE.finditer(body)
-            )
-            for label, body in SELECTION_ARM_RE.findall(text)
-        }
-    )
-
-
-def _unit_selection_tokens(repo_root: pathlib.Path = REPO_ROOT) -> frozenset[str]:
-    return frozenset(
-        token for tokens in _unit_selection_arms(repo_root).values() for token in tokens
-    )
-
-
-def _wired_unit_flags(scalars: Iterable[Scalar]) -> frozenset[str]:
-    return frozenset(
-        scalar.value
-        for scalar in scalars
-        if scalar.key == "unit-flag" and "${{" not in scalar.value
-    )
-
-
-def _shard_tokens(
-    scalars: Iterable[Scalar], arms: Mapping[str, frozenset[str]]
-) -> frozenset[str]:
-    wired: Final = _wired_unit_flags(scalars)
-    return _invoked_test_tokens(scalars) | frozenset(
-        token
-        for label, tokens in arms.items()
-        if label in wired
-        for token in tokens
-    )
+def _invoked_test_tokens(scalars: Iterable[Scalar]) -> frozenset[str]:
+    return frozenset().union(*(selection.included for selection in _invoked_selections(scalars)))
 
 
 def _built_dockerfile_tokens(scalars: Iterable[Scalar]) -> frozenset[str]:
@@ -224,11 +210,12 @@ def _dockerfiles() -> tuple[str, ...]:
     )
 
 
-def _uncovered_tests(allowlist: Allowlist, tokens: frozenset[str]) -> tuple[Finding, ...]:
+def _uncovered_tests(allowlist: Allowlist, selections: tuple[Selection, ...]) -> tuple[Finding, ...]:
     uncovered = tuple(
         relative_path
         for relative_path in _test_files()
-        if not any(_token_covers(token, relative_path) for token in tokens) and not allowlist.covers_test(relative_path)
+        if not any(selection.covers(relative_path) for selection in selections)
+        and not allowlist.covers_test(relative_path)
     )
     directories = tuple(dict.fromkeys(path.rsplit("/", 1)[0] for path in uncovered))
     return tuple(
@@ -518,7 +505,7 @@ def _check_slices() -> int:
 
 
 def _check_shards() -> int:
-    findings = _unassigned_shard_children(_shard_tokens(_all_scalars(), _unit_selection_arms()))
+    findings = _unassigned_shard_children(_invoked_test_tokens(_all_scalars()))
     if findings:
         _report(
             "test directories and files that no shard claims",
@@ -544,23 +531,46 @@ def _integration_groups(runner: pathlib.Path) -> dict[str, tuple[str, ...]]:
     return {group: tuple(folders) for group, folders in ast.literal_eval(mapping).items()}
 
 
+def _integration_github_files(runner: pathlib.Path) -> frozenset[str]:
+    module: Final = ast.parse(runner.read_text())
+    literal: Final = next(
+        (
+            node.value
+            for node in module.body
+            if isinstance(node, ast.AnnAssign)
+            and isinstance(node.target, ast.Name)
+            and node.target.id == "GITHUB_FILES"
+        ),
+        None,
+    )
+    if literal is None:
+        return frozenset()
+    values: Final = literal.args[0] if isinstance(literal, ast.Call) else literal
+    return frozenset(ast.literal_eval(values))
+
+
 def _integration_ownership(repo_root: pathlib.Path = REPO_ROOT) -> tuple[frozenset[str], tuple[Finding, ...]]:
     runner: Final = repo_root / "tests/integration/run.py"
     if not runner.exists():
         return frozenset(), ()
     groups: Final = _integration_groups(runner)
+    github_files: Final = _integration_github_files(runner)
     integration_root: Final = repo_root / "tests/integration"
     paths: Final = frozenset(
         str(path.relative_to(repo_root))
         for folders in groups.values()
         for folder in folders
         for path in (integration_root / folder).rglob("test_*.py")
+        if str(path.relative_to(repo_root)) not in github_files
     )
     browser_manifest: Final = repo_root / "tests/e2e/ui/tests/integrationCritical/expected.json"
     browser_nodes: Final = json.loads(browser_manifest.read_text()) if browser_manifest.exists() else ()
     browser_paths: Final = frozenset(node.split("::", 1)[0] for node in browser_nodes)
     circle_path: Final = repo_root / ".circleci/config.yml"
     circle: Final = yaml.safe_load(circle_path.read_text()) if circle_path.exists() else {}
+    circle_test_path_tokens: Final = _invoked_test_tokens(
+        scalar for scalar in _scalars(circle, "config.yml") if scalar.key == "test_path"
+    )
     steps: Final = circle.get("jobs", {}).get("integration_contracts", {}).get("steps", ())
     invoked: Final = any(
         ".circleci/scripts/run_integration.sh" in scalar.value
@@ -595,10 +605,22 @@ def _integration_ownership(repo_root: pathlib.Path = REPO_ROOT) -> tuple[frozens
         for path in (repo_root / ".github/workflows").glob("*.y*ml")
         for scalar in _scalars(yaml.safe_load(path.read_text()), path.name)
     )
-    findings: Final = tuple(
-        Finding(path, "integration contract is also selected by GitHub Actions")
-        for path in paths
-        if any(_token_covers(token, path) for token in gha_tokens)
+    findings: Final = (
+        tuple(
+            Finding(path, "integration contract is also selected by GitHub Actions")
+            for path in paths
+            if any(_token_covers(token, path) for token in gha_tokens)
+        )
+        + tuple(
+            Finding(path, "GitHub-owned integration contract has no invoking job")
+            for path in sorted(github_files)
+            if not any(_token_covers(token, path) for token in gha_tokens | circle_test_path_tokens)
+        )
+        + tuple(
+            Finding(path, "GitHub-owned integration file is missing")
+            for path in sorted(github_files)
+            if not (repo_root / path).is_file()
+        )
     )
     browser_commands: Final = tuple(
         scalar.value
@@ -642,7 +664,7 @@ def _integration_ownership(repo_root: pathlib.Path = REPO_ROOT) -> tuple[frozens
         return frozenset(), findings + (
             Finding(str(runner.relative_to(repo_root)), "dedicated CircleCI runner is missing"),
         )
-    return paths | browser_paths, findings + group_findings + browser_findings + exclusion_findings
+    return paths | browser_paths | github_files, findings + group_findings + browser_findings + exclusion_findings
 
 
 def main() -> int:
@@ -656,7 +678,11 @@ def main() -> int:
 
     integration_paths, ownership_findings = _integration_ownership()
     test_findings = (
-        _uncovered_tests(allowlist, _invoked_test_tokens(scalars) | _unit_selection_tokens() | integration_paths)
+        _uncovered_tests(
+            allowlist,
+            _invoked_selections(scalars)
+            + (Selection(included=integration_paths, ignored=frozenset()),),
+        )
         + ownership_findings
     )
     dockerfile_findings = _uncovered_dockerfiles(allowlist, _built_dockerfile_tokens(scalars))

.github/scripts/verify_linux_native_wheel.py

@@ -214,7 +214,7 @@ def main(
     native_module: Final = load_native_module(native_path)
     native_module_loads: Final = native_module is not None
     panic_test_hook_absent: Final = native_module is not None and not hasattr(native_module, "_panic_for_test")
-    native_size_limit: Final = 45_000_000
+    native_size_limit: Final = 48_000_000
     native_size_within_limit: Final = native_member.file_size <= native_size_limit
     validations: Final = (
         (f"Python tag is {EXPECTED_PYTHON_TAG}", python_tag == EXPECTED_PYTHON_TAG),

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

@@ -3,6 +3,11 @@ name: _Unit Test Base (Reusable)
 on:
   workflow_call:
     inputs:
+      python-version:
+        description: "Python version used to install dependencies and run tests"
+        required: false
+        type: string
+        default: "3.12"
       test-path:
         description: >-
           Space-separated pytest paths to run. A path that no longer exists is
@@ -13,16 +18,6 @@ on:
           have its path existence-checked like any other token.
         required: true
         type: string
-      unit-flag:
-        description: >-
-          Codecov flag of the `.circleci/tests.yml` job that now owns part of
-          this shard. The shard also runs the files
-          `.circleci/scripts/unit_selection.sh` lists for the flag, on every
-          event, because the CircleCI pipeline is manual-only while the tests
-          migrate.
-        required: false
-        type: string
-        default: ""
       workers:
         description: "Number of pytest-xdist workers"
         required: false
@@ -79,17 +74,16 @@ on:
         description: "Unique name for the coverage artifact (must be unique per run)"
         required: true
         type: string
-      legacy-mcp-peer:
-        description: "Install the isolated SDK1 peer for MCP compatibility tests"
+      rust-bridge-artifact:
+        description: "Prebuilt editable Rust bridge artifact"
         required: false
-        type: boolean
-        default: false
-
+        type: string
+        default: ""
 permissions:
   contents: read
 
 env:
-  UV_PYTHON: "3.12"
+  UV_PYTHON: ${{ inputs.python-version }}
   LITELLM_LOCAL_MODEL_COST_MAP: "True"
 
 jobs:
@@ -134,25 +128,29 @@ jobs:
         timeout-minutes: 5
         uses: ./.github/actions/cache-uv-downloads
 
-      - name: Cache the Rust build
+      - name: Set up the Rust build
         if: steps.changes.outputs.decision != 'skip'
         timeout-minutes: 5
-        uses: ./.github/actions/cache-cargo-build
+        uses: ./.github/actions/rust-bridge
+        with:
+          artifact: ${{ inputs.rust-bridge-artifact }}
 
       - name: Install dependencies
         if: steps.changes.outputs.decision != 'skip'
         timeout-minutes: 8
         env:
-          LEGACY_MCP_PEER: ${{ inputs.legacy-mcp-peer }}
+          RUST_BRIDGE_ARTIFACT: ${{ inputs.rust-bridge-artifact }}
         run: |
           diff -u model_prices_and_context_window.json litellm/model_prices_and_context_window_backup.json
-          .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router --extra saml
-          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 [ "$LEGACY_MCP_PEER" = "true" ]; then
-            uv venv --python "${UV_PYTHON}" .venv-mcp-peer
-            uv pip install --python .venv-mcp-peer 'mcp==1.28.1' 'langchain-mcp-adapters==0.2.1'
-            echo "MCP_TEST_PEER_PYTHON=$GITHUB_WORKSPACE/.venv-mcp-peer/bin/python" >> "$GITHUB_ENV"
+          if [ -z "$RUST_BRIDGE_ARTIFACT" ]; then
+            .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router --extra saml --extra caching --extra extra_proxy --extra proxy-runtime --extra utils
+          else
+            .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra google --extra proxy --extra semantic-router --extra saml --extra caching --extra extra_proxy --extra proxy-runtime --extra utils --no-install-project
+            uv pip install --no-deps --python .venv/bin/python rust-bridge-dist/*.whl
+            cp rust-bridge-dist/litellm/rust_bridge/_native.abi3.so litellm/rust_bridge/_native.abi3.so
+            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"]'
 
       - name: Cache Prisma binaries
         if: steps.changes.outputs.decision != 'skip'
@@ -171,7 +169,6 @@ jobs:
         timeout-minutes: ${{ inputs.timeout-minutes }}
         env:
           TEST_PATH: ${{ inputs.test-path }}
-          UNIT_FLAG: ${{ inputs.unit-flag }}
           MAX_FAILURES: ${{ inputs.max-failures }}
           WORKERS: ${{ inputs.workers }}
           RERUNS: ${{ inputs.reruns }}
@@ -181,9 +178,6 @@ jobs:
         run: |
           echo "has-coverage=false" >> "$GITHUB_OUTPUT"
           selection="${TEST_PATH}"
-          if [ -n "${UNIT_FLAG}" ]; then
-            selection="${TEST_PATH} $(bash .circleci/scripts/unit_selection.sh "${UNIT_FLAG}" | tr '\n' ' ')"
-          fi
           if [ -z "${selection// /}" ]; then
             echo "shard selection is empty; nothing to run"
             exit 0

.github/workflows/codeql.yml

@@ -1,8 +1,6 @@
 name: "CodeQL"
 
 on:
-  push:
-    branches: [main]
   pull_request:
     branches: [main]
   schedule:
@@ -43,14 +41,15 @@ jobs:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3.34.1
+        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
           config-file: ./.github/codeql/codeql-config.yml
+          queries: ${{ github.event_name == 'pull_request' && '+security-extended' || '' }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3.34.1
+        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           category: "/language:${{ matrix.language }}"
           output: sarif-results
@@ -83,7 +82,7 @@ jobs:
           output: sarif-results/python.sarif
 
       - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@ebcb5b36ded6beda4ceefea6a8bc4cc885255bb3 # v3.34.1
+        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           sarif_file: sarif-results
           category: "/language:${{ matrix.language }}"

.github/workflows/helm_unit_test.yml

@@ -22,6 +22,12 @@ jobs:
         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:

.github/workflows/image-scan.yml

@@ -9,15 +9,25 @@ on:
     paths:
       - Dockerfile
       - docker/Dockerfile.non_root
+      - docker/Dockerfile.database
       - migrations/Dockerfile
       - migrations/run.py
       - gateway/Dockerfile
       - gateway/main.py
+      - 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
+      - litellm/proxy/admin_mcp.py
+      - litellm/proxy/proxy_server.py
+      - backend/routes/allowlist.py
+      - pyproject.toml
       - litellm-proxy-extras/**
       - tests/proxy_migration_tests/**
       - uv.lock
@@ -37,6 +47,57 @@ 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
@@ -65,6 +126,9 @@ jobs:
       - name: Build runtime image
         run: docker build -f docker/Dockerfile.non_root -t litellm-image-scan:${{ github.sha }} .
 
+      - name: Tag the cached builder for Admin MCP schema setup
+        run: docker build --target builder -f docker/Dockerfile.non_root -t litellm-admin-mcp-schema:${{ github.sha }} .
+
       # The prisma bake must migrate a fresh DB with no egress as an arbitrary
       # non-root uid (OpenShift restricted-v2 / air-gapped / readOnlyRootFilesystem).
       # `docker run` as the default uid with network hides a broken bake because
@@ -78,9 +142,10 @@ jobs:
       - name: Verify offline migration as a non-root uid
         env:
           LITELLM_IMAGE: litellm-image-scan:${{ github.sha }}
+          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 -v
+          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
 
       # Scans the whole shipped artifact: OS/apk plus every language package
       # baked into the image, including ones no lockfile declares (e.g. prisma's
@@ -99,21 +164,28 @@ jobs:
             --output table
 
   runtime-image:
-    name: runtime-image
+    name: runtime-image (${{ matrix.dockerfile }})
     runs-on: ubuntu-latest
     if: >-
       github.event_name != 'pull_request' ||
       github.event.pull_request.head.repo.full_name == github.repository
-    timeout-minutes: 30
+    timeout-minutes: 45
     permissions:
       contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        dockerfile: [Dockerfile, docker/Dockerfile.database]
     steps:
       - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
         with:
           persist-credentials: false
 
       - name: Build runtime image
-        run: docker build -f Dockerfile -t litellm-runtime-scan:${{ github.sha }} .
+        run: docker build --build-arg LITELLM_RELEASE_TAG=v0.0.0-lens-ci -f "${{ matrix.dockerfile }}" -t litellm-runtime-scan:${{ github.sha }} .
+
+      - name: Tag the cached builder for Admin MCP schema setup
+        run: docker build --target builder -f "${{ matrix.dockerfile }}" -t litellm-admin-mcp-schema:${{ github.sha }} .
 
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
@@ -123,9 +195,16 @@ jobs:
       - name: Verify offline migration as a non-root uid
         env:
           LITELLM_IMAGE: litellm-runtime-scan:${{ github.sha }}
+          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 -v
+          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
+
+      - 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
@@ -184,9 +263,10 @@ jobs:
         env:
           LITELLM_IMAGE: litellm-gateway-scan:${{ github.sha }}
           LITELLM_COMPONENT_PORT: "4000"
+          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 -v
+          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
 
   ui-image:
     name: ui-image
@@ -234,6 +314,9 @@ jobs:
       - name: Build backend image
         run: docker build -f backend/Dockerfile -t litellm-backend-scan:${{ github.sha }} .
 
+      - name: Tag the cached builder for Admin MCP schema setup
+        run: docker build --target builder -f backend/Dockerfile -t litellm-admin-mcp-schema:${{ github.sha }} .
+
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
@@ -242,7 +325,9 @@ jobs:
       - name: Verify the backend serves offline as a non-root uid
         env:
           LITELLM_IMAGE: litellm-backend-scan:${{ github.sha }}
+          LITELLM_ADMIN_MCP_SCHEMA_IMAGE: litellm-admin-mcp-schema:${{ github.sha }}
           LITELLM_COMPONENT_PORT: "4001"
+          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 -v
+          python -m pytest tests/proxy_migration_tests/test_component_image_serves_offline.py tests/proxy_migration_tests/test_image_admin_mcp.py -v

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

@@ -0,0 +1,94 @@
+name: Lens installation smoke
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lens-install-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-images:
+    runs-on: ubuntu-latest-16-cores
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - component: gateway
+            dockerfile: gateway/Dockerfile
+          - component: backend
+            dockerfile: backend/Dockerfile
+          - component: ui
+            dockerfile: ui/Dockerfile
+          - component: migrations
+            dockerfile: migrations/Dockerfile
+          - component: monolith
+            dockerfile: Dockerfile
+          - component: worker
+            dockerfile: deploy/lens/Dockerfile
+    env:
+      COMPONENT: ${{ matrix.component }}
+      DOCKERFILE: ${{ matrix.dockerfile }}
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+      - 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" .
+      - 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"
+      - 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
+          compression-level: 0
+          retention-days: 3
+          if-no-files-found: error
+          overwrite: true
+
+  helm-install:
+    needs: build-images
+    runs-on: ubuntu-latest-16-cores
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
+        with:
+          pattern: lens-install-*-${{ github.sha }}
+          merge-multiple: true
+          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"
+            gzip -dc "$archive" | docker load
+            rm "$archive"
+          done
+      - name: Install pinned Kubernetes test tools
+        run: |
+          curl --fail --location --output "$RUNNER_TEMP/kind" \
+            https://kind.sigs.k8s.io/dl/v0.27.0/kind-linux-amd64
+          echo "a6875aaea358acf0ac07786b1a6755d08fd640f4c79b7a2e46681cc13f49a04b  $RUNNER_TEMP/kind" | sha256sum --check
+          chmod +x "$RUNNER_TEMP/kind"
+          curl --fail --location --output "$RUNNER_TEMP/kubectl" \
+            https://dl.k8s.io/release/v1.32.2/bin/linux/amd64/kubectl
+          echo "4f6a959dcc5b702135f8354cc7109b542a2933c46b808b248a214c1f69f817ea  $RUNNER_TEMP/kubectl" | sha256sum --check
+          chmod +x "$RUNNER_TEMP/kubectl"
+          curl --fail --location --output "$RUNNER_TEMP/helm.tar.gz" \
+            https://get.helm.sh/helm-v3.19.0-linux-amd64.tar.gz
+          echo "a7f81ce08007091b86d8bd696eb4d86b8d0f2e1b9f6c714be62f82f96a594496  $RUNNER_TEMP/helm.tar.gz" | sha256sum --check
+          tar -xzf "$RUNNER_TEMP/helm.tar.gz" -C "$RUNNER_TEMP"
+          echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+          echo "$RUNNER_TEMP/linux-amd64" >> "$GITHUB_PATH"
+      - name: Install, ingest, upgrade, and restart both charts
+        run: bash tests/e2e/migrations/lens_helm_smoke.sh

.github/workflows/lens-worker.yml

@@ -5,13 +5,17 @@ on:
     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:
 
@@ -27,40 +31,81 @@ jobs:
     permissions:
       contents: read
       packages: write
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
+    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 Lens worker
-        run: docker build -f deploy/lens/Dockerfile -t lens-worker:${{ github.sha }} .
-      - name: Verify standalone imports with a read-only filesystem
-        run: |
-          docker run --rm --network none --read-only --cap-drop ALL --tmpfs /tmp:rw,noexec,nosuid,size=1g \
-            --security-opt no-new-privileges --entrypoint python \
-            lens-worker:${{ github.sha }} -c '
-          import os
-          import lens.worker
-          from lens.trace_store import trace_store
-          assert os.getuid() == 65532
-          with trace_store() as store:
-              assert store.count() == 0
-          '
-      - name: Verify recovery after temporary storage fills
+      - 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=64k --security-opt no-new-privileges \
-            -v "$PWD/tests/proxy_behavior/lens/worker_storage_smoke.py:/app/storage_smoke.py:ro" \
-            --entrypoint python lens-worker:${{ github.sha }} /app/storage_smoke.py
-      - name: Publish versioned Lens worker
-        if: github.event_name != 'pull_request' && github.repository == 'BerriAI/litellm'
+            --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:sha-${{ github.sha }}
+          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:${{ github.sha }} "$IMAGE"
+          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-basedpyright-base-counts.yml

@@ -1,65 +0,0 @@
-name: Publish basedpyright base counts
-
-# Every commit on main can become a future merge-base.
-# Publishing its per-rule basedpyright counts as an artifact lets
-# scripts/type_check_gate.py download them in seconds instead of paying a
-# 60-110s second basedpyright pass on every fresh worktree or moved merge-base.
-# No concurrency group on purpose: runs must never cancel each other, because
-# every sha's artifact matters (any of them can become a merge-base).
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-    inputs:
-      ref:
-        description: "Ref to compute and publish base counts for (defaults to the workflow run's commit)"
-        required: false
-
-permissions:
-  contents: read
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          ref: ${{ inputs.ref || github.sha }}
-          clean: true
-          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: Cache the Rust build
-        uses: ./.github/actions/cache-cargo-build
-
-      - name: Cache Prisma binaries
-        uses: ./.github/actions/cache-prisma-binaries
-
-      # The gate provisions its own measurement env (.venv-typecheck: a frozen
-      # uv sync of its canonical dependency groups plus a generated Prisma
-      # client), so no install step here can drift from what local runs measure.
-      - name: Emit basedpyright counts for HEAD
-        run: |
-          python scripts/type_check_gate.py --emit-counts-dir "$RUNNER_TEMP/basedpyright-counts"
-          counts_file=$(ls "$RUNNER_TEMP"/basedpyright-counts/basedpyright-counts-*.json)
-          echo "COUNTS_ARTIFACT_NAME=$(basename "$counts_file" .json)" >> "$GITHUB_ENV"
-
-      - name: Upload counts artifact
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        with:
-          name: ${{ env.COUNTS_ARTIFACT_NAME }}
-          path: ${{ runner.temp }}/basedpyright-counts/
-          if-no-files-found: error

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

@@ -0,0 +1,96 @@
+name: Publish lint base counts
+
+# Every commit on main can become a future merge-base.
+# Publishing its per-rule counts for each lint gate (strict ruff, type discipline,
+# test quality, basedpyright) as an artifact lets the gates download them through
+# scripts/lint_base_counts.py in seconds instead of scanning the merge-base tree in
+# a throwaway worktree on every fresh checkout or moved merge-base.
+# No concurrency group on purpose: runs must never cancel each other, because
+# every sha's artifact matters (any of them can become a merge-base).
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Ref to compute and publish base counts for (defaults to the workflow run's commit)"
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - checker: ruff-strict
+            script: scripts/ruff_strict_gate.py
+          - checker: type-discipline
+            script: scripts/type_discipline_gate.py
+          - checker: test-quality
+            script: scripts/test_quality_gate.py
+          - checker: basedpyright
+            script: scripts/type_check_gate.py
+
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+          clean: true
+          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: Cache the Rust build
+        if: matrix.checker == 'basedpyright'
+        uses: ./.github/actions/cache-cargo-build
+
+      - name: Cache Prisma binaries
+        if: matrix.checker == 'basedpyright'
+        uses: ./.github/actions/cache-prisma-binaries
+
+      # The three source scanners only need the pinned dev tools (ruff and the
+      # stdlib checkers), the same versions test-linting.yml's lint job runs.
+      - name: Install the dev tools
+        if: matrix.checker != 'basedpyright'
+        run: |
+          uv sync --frozen --only-group dev --no-install-project
+
+      - name: Emit ${{ matrix.checker }} counts for HEAD
+        if: matrix.checker != 'basedpyright'
+        run: |
+          uv run --no-sync python ${{ matrix.script }} --emit-counts-dir "$RUNNER_TEMP/lint-counts"
+
+      # The basedpyright gate provisions its own measurement env (.venv-typecheck:
+      # a frozen uv sync of its canonical dependency groups plus a generated Prisma
+      # client), so no install step here can drift from what local runs measure.
+      - name: Emit basedpyright counts for HEAD
+        if: matrix.checker == 'basedpyright'
+        run: |
+          python scripts/type_check_gate.py --emit-counts-dir "$RUNNER_TEMP/lint-counts"
+
+      - name: Name the counts artifact
+        run: |
+          counts_file=$(ls "$RUNNER_TEMP"/lint-counts/${{ matrix.checker }}-counts-*.json)
+          echo "COUNTS_ARTIFACT_NAME=$(basename "$counts_file" .json)" >> "$GITHUB_ENV"
+
+      - name: Upload counts artifact
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
+        with:
+          name: ${{ env.COUNTS_ARTIFACT_NAME }}
+          path: ${{ runner.temp }}/lint-counts/
+          if-no-files-found: error

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

@@ -95,7 +95,9 @@ jobs:
       - name: test_e2e_metadata
         env:
           PYTHONPATH: tests/e2e
-        run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_e2e_metadata.py tests/code_coverage_tests/test_e2e_junit_report.py
+        run: |
+          export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 16)"
+          uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_e2e_metadata.py tests/code_coverage_tests/test_e2e_junit_report.py
 
       - name: Check merge smoke harness
         run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_merge_smoke.py
@@ -163,6 +165,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_no_publicly_known_master_key
+        run: uv run --no-sync python ./tests/code_coverage_tests/check_no_publicly_known_master_key.py
+
+      - name: test_check_no_publicly_known_master_key
+        run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_check_no_publicly_known_master_key.py
+
       - name: check_unbounded_in_lists (fails on findings not in the baseline)
         run: uv run --no-sync python ./tests/code_coverage_tests/check_unbounded_in_lists.py
 

.github/workflows/test-e2e-changed.yml

@@ -1,264 +0,0 @@
-name: e2e-changed-tests
-
-on:
-  pull_request:
-
-concurrency:
-  group: e2e-changed-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-permissions: {}
-
-jobs:
-  detect:
-    name: Detect changed e2e tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      pull-requests: read
-    outputs:
-      tests: ${{ steps.changed.outputs.tests }}
-      any: ${{ steps.changed.outputs.any }}
-    steps:
-      - name: Checkout the selector and the canary suite
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          sparse-checkout: |
-            .github/e2e-stack
-            tests/e2e/access_control
-            tests/e2e/management/test_jwt_management_e2e.py
-            tests/e2e/other/test_jwt_auth_e2e.py
-          persist-credentials: false
-          ref: ${{ github.sha }}
-
-      - name: List the e2e test files this PR added or modified
-        id: changed
-        env:
-          GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          gh api "repos/${REPO}/pulls/${PR_NUMBER}" \
-            --jq 'select(.head.sha == env.HEAD_SHA and .changed_files < 3000) | .head.sha' \
-            | grep -Fxq "${HEAD_SHA}"
-          files="$(gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate \
-            --jq '.[] | select(.status != "removed") | .filename')"
-          gh api "repos/${REPO}/pulls/${PR_NUMBER}" --jq '.head.sha' | grep -Fxq "${HEAD_SHA}"
-          tests="$(printf '%s\n' "${files}" \
-            | python3 .github/e2e-stack/select_tests.py tests/e2e/access_control/test_*.py \
-                tests/e2e/management/test_jwt_management_e2e.py tests/e2e/other/test_jwt_auth_e2e.py)"
-          echo "tests=${tests}" >> "${GITHUB_OUTPUT}"
-          if [ -n "${tests}" ]; then
-            echo "any=true" >> "${GITHUB_OUTPUT}"
-            echo "selected e2e tests: ${tests}"
-          else
-            echo "any=false" >> "${GITHUB_OUTPUT}"
-            echo "no changed e2e test files supported by this stack; nothing to run"
-          fi
-
-  run:
-    name: Run changed e2e tests against the stage-mirror stack
-    needs: detect
-    if: needs.detect.outputs.any == 'true' && github.event.pull_request.head.repo.full_name == github.repository
-    runs-on: ubuntu-latest
-    timeout-minutes: 90
-    environment: e2e-changed
-    permissions:
-      contents: read
-      id-token: write
-    services:
-      postgres:
-        image: postgres:16.6
-        env:
-          POSTGRES_USER: litellm
-          POSTGRES_PASSWORD: dbpassword9090
-          POSTGRES_DB: litellm
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U litellm"
-          --health-interval 5s
-          --health-timeout 5s
-          --health-retries 10
-      jaeger:
-        image: jaegertracing/jaeger:2.10.0
-        ports:
-          - 4318:4318
-          - 16686:16686
-    steps:
-      - name: Validate configuration
-        env:
-          ROLE: ${{ vars.E2E_AWS_ROLE_TO_ASSUME }}
-        run: test -n "${ROLE}" || { echo "::error::Set repo variable E2E_AWS_ROLE_TO_ASSUME to an OIDC role with read access to the e2e secrets"; exit 1; }
-
-      - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          persist-credentials: false
-          ref: ${{ github.sha }}
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.13"
-
-      - name: Set up uv
-        uses: ./.github/actions/setup-uv-with-retries
-        with:
-          version: "0.10.9"
-
-      - name: Cache the Rust build
-        uses: ./.github/actions/cache-cargo-build
-
-      - name: Install dependencies
-        run: |
-          .github/scripts/uv_sync_with_retries.sh --frozen \
-            --extra proxy --extra proxy-runtime --extra extra_proxy \
-            --extra semantic-router --extra bedrock-realtime \
-            --group ci --group proxy-dev --group e2e-dev
-          uv pip install "pipecat-ai[openai]==1.4.0"
-
-      - name: Cache Prisma binaries
-        uses: ./.github/actions/cache-prisma-binaries
-
-      - name: Generate Prisma client
-        run: uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
-
-      - name: Install Playwright chromium
-        run: uv run --no-sync playwright install --with-deps chromium
-
-      - name: Configure AWS credentials
-        id: aws
-        uses: aws-actions/configure-aws-credentials@e7f100cf4c008499ea8adda475de1042d6975c7b # v6.2.0
-        with:
-          role-to-assume: ${{ vars.E2E_AWS_ROLE_TO_ASSUME }}
-          aws-region: us-east-1
-          role-session-name: litellm-e2e-changed-${{ github.run_id }}
-          role-duration-seconds: 900
-          output-env-credentials: false
-          output-credentials: true
-
-      - name: Fetch provider credentials from AWS Secrets Manager
-        env:
-          AWS_ACCESS_KEY_ID: ${{ steps.aws.outputs.aws-access-key-id }}
-          AWS_SECRET_ACCESS_KEY: ${{ steps.aws.outputs.aws-secret-access-key }}
-          AWS_SESSION_TOKEN: ${{ steps.aws.outputs.aws-session-token }}
-          AWS_DEFAULT_REGION: us-east-1
-        run: |
-          umask 077
-          aws secretsmanager get-secret-value --secret-id litellm-e2e-changed-provider-keys \
-            --query SecretString --output text \
-            | uv run --no-sync python .github/e2e-stack/secrets_to_env.py tests/e2e/.env
-          aws secretsmanager get-secret-value --secret-id litellm-e2e-changed-license \
-            --query SecretString --output text \
-            | jq -R -s '{"LITELLM_LICENSE": .}' \
-            | uv run --no-sync python .github/e2e-stack/secrets_to_env.py tests/e2e/.env
-
-      - name: Boot the stage-mirror stack
-        id: boot
-        run: |
-          umask 077
-          if ! bash .github/e2e-stack/up.sh > "${RUNNER_TEMP}/e2e-boot.log" 2>&1; then
-            echo "::error::stage-mirror stack failed to boot; raw logs are not published"
-            exit 1
-          fi
-
-      - name: Export stack environment
-        run: |
-          master_key="$(grep '^LITELLM_MASTER_KEY=' "${RUNNER_TEMP}/litellm-e2e-stack/stack.env" | cut -d= -f2-)"
-          echo "::add-mask::${master_key}"
-          cat "${RUNNER_TEMP}/litellm-e2e-stack/stack.env" >> "${GITHUB_ENV}"
-
-      - name: Run the selected tests three times
-        env:
-          TESTS: ${{ needs.detect.outputs.tests }}
-          E2E_FIXTURE_MODE: live
-          E2E_PROVIDER_EDGE_HOST_REACHABLE: '1'
-          COLUMNS: '400'
-        run: |
-          umask 077
-          read -r -a test_files <<< "${TESTS}"
-          for pass in 1 2 3; do
-            report="${RUNNER_TEMP}/e2e-pass-${pass}.xml"
-            log="${RUNNER_TEMP}/e2e-pass-${pass}.log"
-            echo "::group::pass ${pass} of 3"
-            set +e
-            uv run --no-sync pytest "${test_files[@]}" --rootdir=. -v --reruns 0 -p no:cacheprovider \
-              -o junit_family=xunit1 --junitxml="${report}" > "${log}" 2>&1
-            status=$?
-            uv run --no-sync python .github/e2e-stack/assert_tests_ran.py "${report}" "${test_files[@]}"
-            verified=$?
-            set -e
-            grep -E '^(FAILED|ERROR) ' "${log}" || true
-            grep -E '^=+ .* in [0-9.]+s( \([0-9:]+\))? =+$' "${log}" | tail -n 1
-            echo "::endgroup::"
-            if [ "${status}" = "5" ]; then
-              echo "::error::the selected files collected no runnable tests, so nothing was verified"
-              exit 1
-            fi
-            if [ "${status}" != "0" ]; then
-              echo "::error::pass ${pass} of 3 failed with exit code ${status}"
-              exit "${status}"
-            fi
-            if [ "${verified}" != "0" ]; then
-              echo "::error::pass ${pass} of 3 did not verify every selected file"
-              exit 1
-            fi
-            echo "pass ${pass} of 3 passed"
-          done
-
-      - name: Redact the pytest output
-        if: always() && steps.boot.outcome == 'success'
-        run: |
-          umask 077
-          shopt -s nullglob
-          uv run --no-sync python .github/e2e-stack/redact_output.py \
-            --values tests/e2e/.env --values "${RUNNER_TEMP}/litellm-e2e-stack/stack.env" \
-            --out "${RUNNER_TEMP}/e2e-redacted" "${RUNNER_TEMP}"/e2e-pass-*.log "${RUNNER_TEMP}"/e2e-pass-*.xml
-
-      - name: Keep the redacted pytest output
-        if: always() && steps.boot.outcome == 'success'
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        with:
-          name: e2e-changed-pytest-output-${{ github.run_attempt }}
-          path: ${{ runner.temp }}/e2e-redacted
-          retention-days: 14
-          if-no-files-found: ignore
-
-      - name: Stop the stack
-        if: always() && steps.boot.outcome != 'skipped'
-        run: bash .github/e2e-stack/down.sh
-
-      - name: Remove credentials and raw output
-        if: always()
-        run: |
-          rm -f tests/e2e/.env "${RUNNER_TEMP}/e2e-boot.log" "${RUNNER_TEMP}"/e2e-pass-*.log "${RUNNER_TEMP}"/e2e-pass-*.xml
-          rm -rf "${RUNNER_TEMP}/litellm-e2e-stack" "${RUNNER_TEMP}/e2e-redacted"
-
-  gate:
-    name: e2e-changed-tests
-    needs: [detect, run]
-    if: always()
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Require three successful passes when tests changed
-        env:
-          DETECT_RESULT: ${{ needs.detect.result }}
-          ANY_TESTS: ${{ needs.detect.outputs.any }}
-          RUN_RESULT: ${{ needs.run.result }}
-        run: |
-          if [ "${DETECT_RESULT}" != "success" ]; then
-            echo "::error::changed-test detection did not succeed"
-            exit 1
-          fi
-          if [ "${ANY_TESTS}" = "false" ]; then
-            echo "no changed e2e test files supported by this stack; nothing to run"
-            exit 0
-          fi
-          if [ "${ANY_TESTS}" != "true" ] || [ "${RUN_RESULT}" != "success" ]; then
-            echo "::error::selected e2e tests require an approved, successful run; fork PRs must run from a reviewed same-repository branch"
-            exit 1
-          fi

.github/workflows/test-linting.yml

@@ -17,9 +17,9 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     timeout-minutes: 15
-    # actions: read lets scripts/type_check_gate.py download the base-counts
-    # artifact published by publish-basedpyright-base-counts.yml instead of
-    # re-running basedpyright over the merge-base tree.
+    # actions: read lets the four lint gates download the base-counts artifacts
+    # published by publish-lint-base-counts.yml instead of re-scanning the
+    # merge-base tree in a throwaway worktree.
     permissions:
       contents: read
       pull-requests: read
@@ -144,18 +144,24 @@ jobs:
         run: |
           uv run --no-sync ruff check --config ruff-tests.toml tests
 
-      - name: Check strict-rule budget (delta vs base)
+      - 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 budget (mutable collections / casts / type guards / kwargs / unexplained suppressions, delta vs base)
+      - 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 budget (zero-assert / mock-echo tests, sys.path.insert, raw env writes, litellm global mutation, credential-gated skips, conftest snapshot inventory, delta vs base)
+      - 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"
 
@@ -164,7 +170,7 @@ jobs:
         run: |
           uv run --no-sync python -c "import openai; print(f'OpenAI version: {openai.__version__}')"
 
-      - name: Check basedpyright budget (delta vs base)
+      - name: Check basedpyright (delta vs merge-base counts)
         if: steps.changes.outputs.decision != 'skip'
         env:
           GH_TOKEN: ${{ github.token }}
@@ -174,23 +180,25 @@ jobs:
       - 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' | grep -q .; then
-            uv run --no-sync basedpyright tests/e2e
+          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 claude_code harness unit tests
+      - 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 -- ':(glob)tests/e2e/claude_code/**/*.py' ':(glob)tests/e2e/*.py' tests/e2e/claude_code/cron_vm/install_claude_code.sh pyproject.toml uv.lock .github/workflows/test-linting.yml | grep -q .; then
-            echo "No changed claude_code harness files; skipping."
+          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 --noconftest -o addopts= -o pythonpath=tests/e2e -p no:rerunfailures tests/e2e/claude_code/_*_unit_tests
+          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'
@@ -204,40 +212,6 @@ jobs:
         run: |
           uv run --no-sync python -c "from litellm import *" || (echo '🚨 import failed, this means you introduced unprotected imports! 🚨'; exit 1)
 
-  # Intentionally NON-GATING. This job turns red when a *-budget.json ceiling is
-  # raised (or a rule/budget is dropped) so a loosening is obvious in review, but it
-  # must be kept OUT of the branch-protection required-checks list so a justified
-  # bump can still be merged by a human who has seen and accepted the red.
-  budget-ratchet:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          fetch-depth: 1
-          persist-credentials: false
-
-      - name: Fetch ratchet base
-        env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-        run: |
-          retry() { "$@" || { sleep 15; "$@"; } || { sleep 30; "$@"; }; }
-          retry git fetch --no-tags --depth=1 origin "$BASE_SHA"
-
-      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Ratchet check (budgets may only decrease; non-gating)
-        env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-        run: |
-          python scripts/budget_ratchet_check.py --base "$BASE_SHA"
-
   secret-scan:
     runs-on: ubuntu-latest
     timeout-minutes: 5

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

@@ -49,6 +49,10 @@ jobs:
         if: steps.changes.outputs.decision != 'skip'
         run: npm ci
 
+      - name: Check UI production source types
+        if: steps.changes.outputs.decision != 'skip'
+        run: npm run typecheck
+
       - name: Run UI type tests (Vitest)
         if: steps.changes.outputs.decision != 'skip'
         env:

.github/workflows/test-mcp-dependency-resolution.yml

@@ -5,6 +5,27 @@ on:
     branches:
       - main
       - "litellm_**"
+    paths:
+      - "**/pyproject.toml"
+      - "uv.lock"
+      - "uv.toml"
+      - ".python-version"
+      - "rust-toolchain.toml"
+      - "litellm-rust/**"
+      - "litellm/__init__.py"
+      - "litellm/proxy/proxy_server.py"
+      - "litellm/**/*mcp*"
+      - "litellm/**/*mcp*/**"
+      - "litellm/integrations/arize/**"
+      - "scripts/check_mcp_sdk_install.py"
+      - "tests/base_sdk_tests/**"
+      - ".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"
 
 permissions:
   contents: read
@@ -17,7 +38,7 @@ concurrency:
 jobs:
   resolve:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 25
     strategy:
       fail-fast: false
       matrix:

.github/workflows/test-postgres.yml

@@ -1,167 +0,0 @@
-name: "Postgres Tests"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - "litellm_**"
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  postgres:
-    name: ${{ matrix.shard }}
-    runs-on: ubuntu-latest
-    timeout-minutes: ${{ matrix.job-timeout-minutes }}
-    permissions:
-      contents: read
-      id-token: write
-
-    services:
-      postgres:
-        image: postgres:16@sha256:e17e86066e5ef83e0952a9347f5c792b7ece00972e2aa787a6986f471b3dd3d5
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: litellm_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 10
-
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - shard: proxy-behavior
-            test-path: "tests/proxy_behavior"
-            seed: db-push
-            workers: 0
-            timeout-minutes: 25
-            job-timeout-minutes: 50
-
-          - shard: proxy-security
-            test-path: "tests/proxy_security_tests"
-            seed: db-push
-            workers: 0
-            timeout-minutes: 15
-            job-timeout-minutes: 40
-
-          - shard: schema-migration
-            test-path: "tests/proxy_migration_tests"
-            seed: none
-            workers: 0
-            timeout-minutes: 20
-            job-timeout-minutes: 45
-
-    env:
-      DATABASE_URL: "postgresql://postgres:postgres@localhost:5432/litellm_test"
-
-    steps:
-      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        timeout-minutes: 3
-        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'
-        timeout-minutes: 3
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
-        with:
-          python-version: "3.12"
-
-      - name: Set up uv
-        if: steps.changes.outputs.decision != 'skip'
-        timeout-minutes: 3
-        uses: ./.github/actions/setup-uv-with-retries
-        with:
-          version: "0.10.9"
-
-      - name: Cache uv dependencies
-        if: steps.changes.outputs.decision != 'skip' && github.ref == 'refs/heads/main'
-        timeout-minutes: 5
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-        with:
-          path: |
-            ~/.cache/uv
-            .venv
-          key: ${{ runner.os }}-uv-postgres-${{ hashFiles('uv.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-uv-postgres-
-
-      - name: Cache uv dependencies
-        if: steps.changes.outputs.decision != 'skip' && github.ref != 'refs/heads/main'
-        timeout-minutes: 5
-        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
-        with:
-          path: |
-            ~/.cache/uv
-            .venv
-          key: ${{ runner.os }}-uv-postgres-${{ hashFiles('uv.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-uv-postgres-
-
-      - name: Install dependencies
-        if: steps.changes.outputs.decision != 'skip'
-        timeout-minutes: 12
-        run: |
-          .github/scripts/uv_sync_with_retries.sh --frozen --all-groups --all-extras
-
-      - name: Cache Prisma binaries
-        if: steps.changes.outputs.decision != 'skip'
-        timeout-minutes: 3
-        uses: ./.github/actions/cache-prisma-binaries
-
-      - name: Generate Prisma client
-        if: steps.changes.outputs.decision != 'skip'
-        timeout-minutes: 5
-        run: |
-          uv run --no-sync prisma generate --schema litellm/proxy/schema.prisma
-
-      - name: Seed database schema
-        if: steps.changes.outputs.decision != 'skip' && matrix.seed != 'none'
-        timeout-minutes: 10
-        run: |
-          uv run --no-sync prisma db push --schema litellm/proxy/schema.prisma --accept-data-loss
-
-      - name: Run tests
-        if: steps.changes.outputs.decision != 'skip'
-        timeout-minutes: ${{ matrix.timeout-minutes }}
-        env:
-          TEST_PATH: ${{ matrix.test-path }}
-          WORKERS: ${{ matrix.workers }}
-          PYTEST_ADDOPTS: ${{ matrix.shard == 'proxy-behavior' && '--cov=./litellm --cov-report=xml:coverage-lens-postgres.xml' || '' }}
-        run: |
-          if [ "${WORKERS}" = "0" ]; then
-            uv run --no-sync pytest ${TEST_PATH:?} -vv --tb=short --durations=10
-          else
-            uv run --no-sync pytest ${TEST_PATH:?} -vv --tb=short --durations=10 -n "${WORKERS}"
-          fi
-
-      - name: Upload Lens database coverage
-        if: steps.changes.outputs.decision != 'skip' && matrix.shard == 'proxy-behavior' && !cancelled()
-        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
-        with:
-          use_oidc: true
-          version: v11.3.1
-          root_dir: ${{ github.workspace }}
-          files: coverage-lens-postgres.xml
-          flags: lens-postgres
-          fail_ci_if_error: true

.github/workflows/test-redis-compat.yml

@@ -1,106 +0,0 @@
-name: "Unit Tests: Redis Client Version Compatibility"
-
-on:
-  pull_request:
-    branches:
-      - main
-      - "litellm_**"
-    paths:
-      - "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"
-      - ".github/workflows/test-redis-compat.yml"
-      - "pyproject.toml"
-      - "uv.lock"
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  redis-compat:
-    name: "redis-py ${{ matrix.redis-version }}"
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      contents: read
-      id-token: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        # 5.3.1 is the version pinned in uv.lock (redisvl caps it below 6); the
-        # newer legs prove the inspect.signature introspection in litellm/_redis.py
-        # keeps extracting kwargs on the redis-py releases people actually run now.
-        # Only the exact release 6.0.0 is skipped: rq (pulled by the proxy extra)
-        # specifies `redis != 6`, which excludes 6.0.0 alone, so 6.4.0 stands in
-        # for the 6.x line.
-        redis-version: ["5.3.1", "6.4.0", "7.4.1", "8.0.1"]
-
-    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: Install dependencies
-        run: |
-          .github/scripts/uv_sync_with_retries.sh --frozen --group ci --group proxy-dev --extra google --extra proxy --extra extra_proxy --extra semantic-router
-
-      - name: Pin redis-py to the matrix version
-        env:
-          REDIS_VERSION: ${{ matrix.redis-version }}
-        run: |
-          uv pip install "redis==${REDIS_VERSION:?}"
-          uv run --no-sync python -c "import redis; assert redis.__version__ == '${REDIS_VERSION:?}', redis.__version__; print('redis-py', redis.__version__)"
-
-      - name: Build Redis for cluster authentication tests
-        run: |
-          curl --fail --location --retry 3 https://download.redis.io/releases/redis-7.2.16.tar.gz -o "$RUNNER_TEMP/redis-7.2.16.tar.gz"
-          echo "960a8ec15e34ff40e57ff16837b26b33bd81f2da6d24497bb63de532a323a18e  $RUNNER_TEMP/redis-7.2.16.tar.gz" | sha256sum --check
-          tar -xzf "$RUNNER_TEMP/redis-7.2.16.tar.gz" -C "$RUNNER_TEMP"
-          make -C "$RUNNER_TEMP/redis-7.2.16" -j2 MALLOC=libc OPTIMIZATION=-O1 redis-server
-          echo "$RUNNER_TEMP/redis-7.2.16/src" >> "$GITHUB_PATH"
-
-      - name: Run redis unit tests
-        run: |
-          redis-server --version
-          uv run --no-sync pytest \
-            tests/unit/test_redis.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 \
-            tests/local_testing/test_caching.py::test_sync_cluster_authenticates_with_azure_credentials \
-            tests/local_testing/test_caching.py::test_sync_cluster_authenticates_with_gcp_credentials \
-            --tb=short -vv \
-            --reruns 2 \
-            --reruns-delay 1 \
-            --durations=20 \
-            --cov=./litellm --cov-report=xml:coverage-redis.xml
-
-      - name: Upload Redis coverage
-        if: matrix.redis-version == '5.3.1'
-        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
-        with:
-          use_oidc: true
-          files: coverage-redis.xml
-          flags: redis-compat
-          fail_ci_if_error: false

.github/workflows/test-rust.yml

@@ -5,6 +5,10 @@ on:
     paths:
       - "litellm-rust/**"
       - "litellm/rust_bridge/**"
+      - "scripts/generate_trace_types.py"
+      - "scripts/generate_lens_contract.py"
+      - "litellm/proxy/lens/**"
+      - "scripts/trace_codegen/**"
       - "tests/test_litellm_rust/**"
       - "litellm/integrations/custom_logger.py"
       - "litellm/litellm_core_utils/litellm_logging.py"
@@ -32,6 +36,10 @@ on:
     paths:
       - "litellm-rust/**"
       - "litellm/rust_bridge/**"
+      - "scripts/generate_trace_types.py"
+      - "scripts/generate_lens_contract.py"
+      - "litellm/proxy/lens/**"
+      - "scripts/trace_codegen/**"
       - "tests/test_litellm_rust/**"
       - "litellm/integrations/custom_logger.py"
       - "litellm/litellm_core_utils/litellm_logging.py"
@@ -85,11 +93,11 @@ jobs:
           cache-on-failure: true
           save-if: ${{ github.ref == 'refs/heads/main' }}
 
-      - run: cargo clippy --workspace --all-targets --locked -- -D warnings
+      - run: cargo clippy --workspace --all-targets --locked --features litellm-traces/schema,litellm-traces-clickhouse/schema -- -D warnings
 
   rust-test:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     defaults:
       run:
         working-directory: litellm-rust
@@ -124,7 +132,15 @@ jobs:
           cache-on-failure: true
           save-if: ${{ github.ref == 'refs/heads/main' }}
 
-      - run: cargo nextest run --workspace --locked
+      - name: Check generated trace contracts
+        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 test --workspace --doc --locked
 

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

@@ -20,13 +20,6 @@ concurrency:
 # rather than alphabetical letter ranges. Adding a new test file means adding it
 # to whichever group it belongs to, not reshuffling slices.
 #
-# `.circleci/tests.yml` runs each group's files on same-repo events under the
-# `proxy-db-<group>` Codecov flag; `.circleci/scripts/unit_selection.sh` holds
-# the file lists. That pipeline is manual-only while the tests migrate, so
-# `unit-flag` makes the shard run that list on every event. `test-path` keeps
-# the files that still reach real providers and never left
-# tests/proxy_unit_tests.
-#
 # Design targets:
 #   * Every shard runs in <= 7 minutes of wall-clock on the default runner.
 #     Most of a shard's time is pytest plugin load + xdist worker imports +
@@ -46,6 +39,21 @@ concurrency:
 #     pinning the whole file to one worker (the default --dist=loadscope
 #     behavior for single-file targets).
 jobs:
+  lens-python-310:
+    name: Lens Python 3.10
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+    uses: ./.github/workflows/_test-unit-base.yml
+    with:
+      python-version: "3.10"
+      test-path: tests/unit/proxy/lens/test_inference.py
+      workers: 0
+      reruns: 0
+      timeout-minutes: 5
+      artifact-name: lens-python-310
+
   # Fast guard — fails the workflow when a test directory or file inside a sharded
   # tree is claimed by no shard. The semantic-shard design has no catch-all bucket,
   # so an unassigned child runs nowhere; assert_ci_coverage.py holds the tree list
@@ -78,93 +86,136 @@ jobs:
         include:
           # Must run serially — event-loop conflict with the logging worker.
           - test-group: key-generation
-            test-path: ""
-            unit-flag: proxy-db-key-generation
+            test-path: >-
+              tests/unit/proxy/management_endpoints/test_key_generate_prisma.py
             workers: 0
             dist: loadscope
             timeout: 20
 
           # ---- auth: split into 2 shards ----
           - test-group: auth-checks
-            test-path: ""
-            unit-flag: proxy-db-auth-checks
+            test-path: >-
+              tests/unit/proxy/auth/test_auth_checks.py
+              tests/unit/proxy/auth/test_user_api_key_auth.py
+              tests/unit/proxy/test_credential_slot_registry.py
+              tests/unit/proxy/test_deprecated_key_grace_period.py
             workers: 4
             dist: loadscope
             timeout: 15
           - test-group: jwt-and-keys
-            test-path: ""
-            unit-flag: proxy-db-jwt-and-keys
+            test-path: >-
+              tests/unit/proxy/auth/test_jwt.py
+              tests/unit/proxy/management_endpoints/test_jwt_key_mapping.py
+              tests/unit/proxy/test_proxy_custom_auth.py
             workers: 4
             dist: loadscope
             timeout: 15
 
           # ---- test_proxy_utils.py, single shard, worksteal distribution ----
           - test-group: proxy-utils
-            test-path: ""
-            unit-flag: proxy-db-proxy-utils
+            test-path: >-
+              tests/unit/proxy/test_proxy_utils.py
             workers: 4
             dist: worksteal
             timeout: 15
 
           # ---- proxy server: split into 2 shards ----
           - test-group: proxy-server-core
-            test-path: "tests/proxy_unit_tests/test_proxy_server_gemini_pass_through.py"
-            unit-flag: proxy-db-proxy-server-core
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_server_gemini_pass_through.py
+              tests/unit/proxy/test__lazy_features.py
+              tests/unit/proxy/test_aproxy_startup.py
+              tests/unit/proxy/test_proxy_server.py
             workers: 4
             dist: loadscope
             timeout: 15
           - test-group: proxy-runtime
-            test-path: ""
-            unit-flag: proxy-db-proxy-runtime
+            test-path: >-
+              tests/unit/proxy/auth/test_multipart_bypass_repro.py
+              tests/unit/proxy/auth/test_proxy_routes.py
+              tests/unit/proxy/middleware/test_request_size_limit_middleware.py
+              tests/unit/proxy/test_proxy_config_unit_test.py
+              tests/unit/proxy/test_proxy_token_counter.py
+              tests/unit/proxy/test_server_root_path.py
             workers: 4
             dist: loadscope
             timeout: 15
 
           # ---- logging: split into 2 shards ----
           - test-group: custom-logging
-            test-path: "tests/proxy_unit_tests/test_proxy_custom_logger.py"
-            unit-flag: proxy-db-custom-logging
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_custom_logger.py
+              tests/unit/proxy/test_custom_callback_input.py
+              tests/unit/proxy/test_custom_logger_s3_gcs.py
             workers: 4
             dist: loadscope
             timeout: 15
           - test-group: logging-misc
-            test-path: ""
-            unit-flag: proxy-db-logging-misc
+            test-path: >-
+              tests/unit/proxy/management_helpers/test_audit_logs_proxy.py
+              tests/unit/proxy/spend_tracking/test_search_api_logging.py
+              tests/unit/proxy/test_proxy_reject_logging.py
             workers: 4
             dist: loadscope
             timeout: 15
 
           - test-group: db-and-spend
-            test-path: ""
-            unit-flag: proxy-db-db-and-spend
+            test-path: >-
+              tests/unit/proxy/common_utils/test_proxy_encrypt_decrypt.py
+              tests/unit/proxy/db/db_transaction_queue/test_e2e_pod_lock_manager.py
+              tests/unit/proxy/db/test_update_daily_tag_spend.py
+              tests/unit/proxy/test_db_schema_changes.py
+              tests/unit/proxy/test_prisma_client_backoff_retry.py
+              tests/unit/proxy/test_update_spend.py
+              tests/unit/skills/test_skills_db.py
             workers: 4
             dist: loadscope
             timeout: 15
 
           # ---- guardrails + budget + hooks: split into 2 ----
           - test-group: guardrails-hooks
-            test-path: ""
-            unit-flag: proxy-db-guardrails-hooks
+            test-path: >-
+              tests/unit/proxy/hooks/test_banned_keyword_list.py
+              tests/unit/proxy/test_proxy_setting_guardrails.py
+              tests/unit/proxy/test_unit_test_proxy_hooks.py
             workers: 4
             dist: loadscope
             timeout: 15
           - test-group: budgets
-            test-path: ""
-            unit-flag: proxy-db-budgets
+            test-path: >-
+              tests/unit/proxy/auth/test_default_end_user_budget_simple.py
+              tests/unit/proxy/hooks/test_unit_test_max_model_budget_limiter.py
+              tests/unit/proxy/test_zero_cost_model_budget_bypass.py
             workers: 4
             dist: loadscope
             timeout: 15
 
           - test-group: endpoints-and-responses
-            test-path: "tests/proxy_unit_tests/test_proxy_exception_mapping.py"
-            unit-flag: proxy-db-endpoints-and-responses
+            test-path: >-
+              tests/proxy_unit_tests/test_proxy_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
+              tests/unit/proxy/common_utils/test_check_responses_cost.py
+              tests/unit/proxy/common_utils/test_realtime_cache.py
+              tests/unit/proxy/google_endpoints/test_gemini_agents_endpoints.py
+              tests/unit/proxy/google_endpoints/test_google_endpoint_routing.py
+              tests/unit/proxy/google_endpoints/test_google_gemini_proxy_request.py
+              tests/unit/proxy/public_endpoints/test_blog_posts_endpoint.py
+              tests/unit/proxy/response_polling
+              tests/unit/proxy/test_custom_tokenizer_bug.py
+              tests/unit/proxy/test_get_favicon.py
+              tests/unit/proxy/test_get_image.py
+              tests/unit/proxy/test_prompt_test_endpoint.py
+              tests/unit/proxy/test_reducto_ocr_route.py
+              tests/unit/proxy/test_response_polling_pre_call_checks.py
+              tests/unit/proxy/test_ui_path_detection.py
             workers: 4
             dist: loadscope
             timeout: 15
     uses: ./.github/workflows/_test-unit-base.yml
     with:
       test-path: ${{ matrix.test-path }}
-      unit-flag: ${{ matrix.unit-flag }}
       workers: ${{ matrix.workers }}
       reruns: 2
       timeout-minutes: ${{ matrix.timeout }}

.github/workflows/test-unit.yml

@@ -21,10 +21,8 @@ concurrency:
 # files that each wrapped a single call to _test-unit-base.yml. Adding a shard is
 # now one matrix entry rather than a new file.
 #
-# `name` is the shard id and nothing else, so each check reports as
-# "<shard> / Run tests" exactly as it did when the shard had its own file. Those
-# strings are the branch ruleset's required contexts, so they are load-bearing:
-# renaming an entry renames a required check and the ruleset stops matching it.
+# `name` is the shard id, and each check reports as "<shard> / Run tests".
+# Unit shard names are not required ruleset contexts, so matrix entries can be split freely.
 #
 # Every entry states its timeouts even when they equal the base workflow's
 # defaults. An absent matrix key renders as an empty string, which is not a
@@ -35,13 +33,102 @@ concurrency:
 # a matrix and carries a shard-coverage guard that reads that file by name.
 # Folding it in here is a follow-up, together with generalising that guard into
 # assert_ci_coverage.py.
-#
-# `unit-flag` names the `.circleci/tests.yml` job that now runs part of the
-# shard under the same Codecov flag. That pipeline is manual-only while the
-# tests migrate, so the shard also runs those files on every event.
 jobs:
+  rust-bridge:
+    name: Build the Rust bridge
+    outputs:
+      artifact: ${{ steps.rust-bridge-artifact.outputs.name }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    env:
+      UV_PYTHON: "3.12"
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955
+        with:
+          persist-credentials: false
+
+      - name: Detect relevant changes
+        id: changes
+        timeout-minutes: 2
+        uses: ./.github/actions/detect-changes
+
+      - name: Define editable Rust bridge cache key
+        id: rust-bridge-key
+        if: steps.changes.outputs.decision != 'skip'
+        env:
+          RUST_BRIDGE_CACHE_KEY: ${{ runner.os }}-rust-bridge-editable-${{ hashFiles('litellm-rust/Cargo.lock', 'litellm-rust/Cargo.toml', 'litellm-rust/crates/**', 'pyproject.toml') }}
+        run: echo "key=$RUST_BRIDGE_CACHE_KEY" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        if: steps.changes.outputs.decision != 'skip'
+        timeout-minutes: 3
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+
+      - name: Set up uv
+        if: steps.changes.outputs.decision != 'skip'
+        timeout-minutes: 3
+        uses: ./.github/actions/setup-uv-with-retries
+        with:
+          version: "0.10.9"
+
+      - name: Restore editable Rust bridge
+        id: rust-bridge-cache
+        if: steps.changes.outputs.decision != 'skip'
+        timeout-minutes: 5
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830
+        with:
+          path: rust-bridge-dist
+          key: ${{ steps.rust-bridge-key.outputs.key }}
+
+      - name: Cache the Rust build
+        if: steps.changes.outputs.decision != 'skip' && steps.rust-bridge-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
+        uses: ./.github/actions/cache-cargo-build
+
+      - name: Build editable Rust bridge
+        if: steps.changes.outputs.decision != 'skip' && steps.rust-bridge-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 15
+        run: |
+          mkdir -p rust-bridge-dist
+          uv run --no-project --with maturin==1.15.0 python -c 'import maturin; maturin.build_editable("rust-bridge-dist")'
+          strip --strip-debug litellm/rust_bridge/_native.abi3.so
+          mkdir -p rust-bridge-dist/litellm/rust_bridge
+          cp litellm/rust_bridge/_native.abi3.so rust-bridge-dist/litellm/rust_bridge/_native.abi3.so
+
+      - name: Upload Rust bridge artifact
+        if: steps.changes.outputs.decision != 'skip'
+        timeout-minutes: 10
+        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1
+        with:
+          name: rust-bridge-${{ github.run_id }}-${{ github.run_attempt }}
+          path: rust-bridge-dist/
+          retention-days: 1
+
+      - name: Save editable Rust bridge
+        if: steps.changes.outputs.decision != 'skip' && github.ref == 'refs/heads/main' && steps.rust-bridge-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 10
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830
+        with:
+          path: rust-bridge-dist
+          key: ${{ steps.rust-bridge-key.outputs.key }}
+
+      - name: Expose the Rust bridge artifact
+        id: rust-bridge-artifact
+        if: steps.changes.outputs.decision != 'skip'
+        timeout-minutes: 1
+        env:
+          RUN_ID: ${{ github.run_id }}
+          RUN_ATTEMPT: ${{ github.run_attempt }}
+        run: echo "name=rust-bridge-${RUN_ID}-${RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"
+
   unit:
     name: ${{ matrix.shard }}
+    needs: rust-bridge
+    if: ${{ !cancelled() }}
     permissions:
       contents: read
       id-token: write
@@ -50,29 +137,35 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - shard: mcp-integration
-            artifact-name: mcp-integration
-            test-path: "tests/mcp_tests"
-            unit-flag: mcp-integration
-            workers: 2
-            reruns: 0
-            timeout-minutes: 20
-            job-timeout-minutes: 60
-
           - shard: core-utils
             artifact-name: core-utils
-            test-path: ""
-            unit-flag: core-utils
-            workers: 2
-            reruns: 1
+            test-path: >-
+              tests/unit/decisions
+              tests/unit/litellm_core_utils
+            workers: 4
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: enterprise-routing
             artifact-name: enterprise-routing
-            test-path: ""
-            unit-flag: enterprise-routing
-            workers: 2
+            test-path: >-
+              tests/unit/google_genai
+              tests/unit/router_strategy
+              tests/unit/router_utils
+              tests/unit/proxy/common_utils/test_cache_aware_routing.py
+              tests/unit/enterprise/enterprise_callbacks/send_emails
+              tests/unit/enterprise/proxy/test_afile_retrieve_returns_unified_id.py
+              tests/unit/enterprise/proxy/test_batch_retrieve_input_file_id.py
+              tests/unit/enterprise/proxy/test_batch_retrieve_registers_missing_output_file_id.py
+              tests/unit/enterprise/proxy/test_batch_retrieve_returns_unified_input_file_id.py
+              tests/unit/enterprise/proxy/test_batch_update_db_managed_output_file_id.py
+              tests/unit/enterprise/proxy/test_deleted_file_returns_403_not_404.py
+              tests/unit/enterprise/proxy/test_enterprise_routes.py
+              tests/unit/enterprise/proxy/test_file_deletion_blocking.py
+              tests/unit/enterprise/proxy/test_managed_files_access_check.py
+              tests/unit/enterprise/proxy/test_managed_files_hook.py
+            workers: 4
             reruns: 2
             timeout-minutes: 20
             job-timeout-minutes: 60
@@ -82,27 +175,41 @@ jobs:
             test-path: >-
               tests/test_litellm/integrations
               tests/test_litellm/tracing
-            unit-flag: integrations
-            workers: 2
-            reruns: 3
+              tests/unit/integrations
+            workers: 4
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: Vertex AI
             artifact-name: llm-vertex-ai
-            test-path: ""
-            unit-flag: llm-vertex-ai
-            workers: 1
-            reruns: 2
+            test-path: >-
+              tests/unit/llms/vertex_ai
+            workers: 4
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: All Other Providers
             artifact-name: llm-other-providers
-            test-path: ""
-            unit-flag: llm-other-providers
-            workers: 2
-            reruns: 2
+            test-path: >-
+              tests/unit/llms
+              --ignore=tests/unit/llms/vertex_ai
+              --ignore=tests/unit/llms/openai
+              --ignore=tests/unit/llms/meta
+              --ignore=tests/unit/llms/base_llm/batches/base_batches_config_test.py
+            workers: 4
+            reruns: 0
+            timeout-minutes: 20
+            job-timeout-minutes: 60
+
+          - shard: OpenAI and Meta Providers
+            artifact-name: llm-openai-meta
+            test-path: >-
+              tests/unit/llms/openai
+              tests/unit/llms/meta
+            workers: 4
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
@@ -110,19 +217,44 @@ jobs:
             artifact-name: misc
             test-path: >-
               tests/test_litellm/test_*.py
-            unit-flag: misc
-            workers: 2
+              tests/unit/test_*.py
+            workers: 4
             reruns: 2
             timeout-minutes: 20
             job-timeout-minutes: 60
 
+          - shard: misc-dirs
+            artifact-name: misc-dirs
+            test-path: >-
+              tests/unit/test_router
+              tests/unit/a2a_protocol
+              tests/unit/batches
+              tests/unit/chat_completions
+              tests/unit/completion_extras
+              tests/unit/containers
+              tests/unit/embeddings
+              tests/unit/endpoints
+              tests/unit/files
+              tests/unit/harness
+              tests/unit/images
+              tests/unit/interactions
+              tests/unit/messages
+              tests/unit/rag
+              tests/unit/rerank_api
+              tests/unit/rust_bridge
+              tests/unit/secret_managers
+              tests/unit/vector_stores
+              tests/unit/videos
+              --ignore=tests/unit/rust_bridge/native_route_wheel_test.py
+            workers: 4
+            reruns: 0
+            timeout-minutes: 20
+            job-timeout-minutes: 60
+
           - shard: proxy-auth
             artifact-name: proxy-auth
             test-path: >-
               tests/unit/proxy/auth
-              tests/unit/proxy/hooks
-              tests/unit/proxy/policy_engine
-              tests/unit/proxy/client
               --ignore=tests/unit/proxy/auth/test_auth_checks.py
               --ignore=tests/unit/proxy/auth/test_user_api_key_auth.py
               --ignore=tests/unit/proxy/auth/test_default_end_user_budget_simple.py
@@ -130,34 +262,56 @@ jobs:
               --ignore=tests/unit/proxy/auth/test_models_fallback_endpoint.py
               --ignore=tests/unit/proxy/auth/test_multipart_bypass_repro.py
               --ignore=tests/unit/proxy/auth/test_proxy_routes.py
+            workers: 4
+            reruns: 0
+            timeout-minutes: 20
+            job-timeout-minutes: 60
+
+          - shard: proxy-hooks-client
+            artifact-name: proxy-hooks-client
+            test-path: >-
+              tests/unit/proxy/hooks
+              tests/unit/proxy/policy_engine
+              tests/unit/proxy/client
               --ignore=tests/unit/proxy/hooks/test_banned_keyword_list.py
               --ignore=tests/unit/proxy/hooks/test_unit_test_max_model_budget_limiter.py
-            workers: 2
-            reruns: 2
+            workers: 4
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: proxy-endpoints
             artifact-name: proxy-endpoints
             test-path: >-
-              tests/unit/proxy/analytics_endpoints
               tests/unit/proxy/management_endpoints
-              tests/unit/proxy/list_api
-              tests/unit/proxy/memory
-              tests/unit/proxy/guardrails
               tests/unit/proxy/management_helpers
+              tests/unit/proxy/list_api
+              tests/unit/proxy/analytics_endpoints
+              tests/unit/proxy/decisions_endpoints
+              tests/unit/proxy/memory
+              tests/unit/proxy/agent_endpoints
+              tests/unit/proxy/openai_files_endpoint
+              tests/unit/proxy/health_endpoints
+              tests/unit/proxy/batches_endpoints
               --ignore=tests/unit/proxy/management_endpoints/test_jwt_key_mapping.py
               --ignore=tests/unit/proxy/management_endpoints/test_key_generate_prisma.py
               --ignore=tests/unit/proxy/management_endpoints/test_roi_calculator_endpoints.py
               --ignore=tests/unit/proxy/management_helpers/test_audit_logs_proxy.py
+            workers: 4
+            reruns: 0
+            timeout-minutes: 20
+            job-timeout-minutes: 60
+
+          - shard: proxy-feature-endpoints
+            artifact-name: proxy-feature-endpoints
+            test-path: >-
+              tests/unit/proxy/guardrails
               --ignore=tests/unit/proxy/google_endpoints/test_gemini_agents_endpoints.py
               --ignore=tests/unit/proxy/google_endpoints/test_google_endpoint_routing.py
               --ignore=tests/unit/proxy/google_endpoints/test_google_gemini_proxy_request.py
               --ignore=tests/unit/proxy/public_endpoints/test_blog_posts_endpoint.py
               tests/unit/proxy/anthropic_endpoints
               tests/unit/proxy/google_endpoints
-              tests/unit/proxy/openai_files_endpoint
-              tests/unit/proxy/batches_endpoints
               tests/unit/proxy/container_endpoints
               tests/unit/proxy/fine_tuning_endpoints
               tests/unit/proxy/vector_store_files_endpoints
@@ -165,12 +319,11 @@ jobs:
               tests/unit/proxy/response_api_endpoints
               tests/unit/proxy/image_endpoints
               tests/unit/proxy/ocr_endpoints
+              tests/unit/proxy/search_endpoints
               tests/unit/proxy/vector_store_endpoints
-              tests/unit/proxy/agent_endpoints
               tests/unit/proxy/a2a
               tests/unit/proxy/credential_endpoints
               tests/unit/proxy/discovery_endpoints
-              tests/unit/proxy/health_endpoints
               tests/unit/proxy/shutdown
               tests/unit/proxy/public_endpoints
               tests/unit/proxy/prompts
@@ -181,7 +334,7 @@ jobs:
               tests/unit/proxy/config_resolvers
               tests/unit/proxy/utils
             workers: 4
-            reruns: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
@@ -189,7 +342,7 @@ jobs:
             artifact-name: proxy-server
             test-path: "tests/unit/proxy/proxy_server"
             workers: 4
-            reruns: 2
+            reruns: 0
             timeout-minutes: 60
             job-timeout-minutes: 100
 
@@ -216,9 +369,12 @@ jobs:
               tests/unit/proxy/enterprise_billing
               tests/unit/proxy/types_utils
               tests/unit/proxy/logging_endpoints
-            unit-flag: proxy-infra
+              tests/unit/gateway
+              tests/unit/proxy/management
+              tests/unit/proxy/management_endpoints/test_roi_calculator_endpoints.py
+              tests/unit/proxy/roi_calculator
             workers: 4
-            reruns: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
@@ -252,52 +408,93 @@ jobs:
               --ignore=tests/unit/proxy/test_update_spend.py
               --ignore=tests/unit/proxy/test_zero_cost_model_budget_bypass.py
             workers: 4
-            reruns: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: caching-local
             artifact-name: caching-local
-            test-path: ""
-            unit-flag: caching-local
+            test-path: >-
+              tests/unit/caching
             workers: 2
-            reruns: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: proxy-extras
             artifact-name: proxy-extras
-            test-path: ""
-            unit-flag: proxy-extras
+            test-path: >-
+              tests/unit/litellm_proxy_extras
             workers: 2
-            reruns: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
           - shard: enterprise-package
             artifact-name: enterprise-package
-            test-path: ""
-            unit-flag: enterprise-package
+            test-path: >-
+              tests/unit/enterprise/integrations
+              tests/unit/enterprise/proxy/auth
+              tests/unit/enterprise/proxy/guardrails
+              tests/unit/enterprise/proxy/management_endpoints
+              tests/unit/enterprise/proxy/test_audit_logging_endpoints.py
+              tests/unit/enterprise/proxy/test_liteadmin.py
+              tests/unit/enterprise/enterprise_callbacks/test_prometheus_logging_callbacks.py
             workers: 4
-            reruns: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
 
+          - shard: enterprise-managed-files
+            artifact-name: enterprise-managed-files
+            test-path: >-
+              tests/unit/enterprise/proxy/hooks
+            workers: 4
+            reruns: 0
+            timeout-minutes: 20
+            job-timeout-minutes: 60
+            dist: load
+
           - shard: responses-caching-types
             artifact-name: responses-caching-types
-            test-path: ""
-            unit-flag: responses-caching-types
+            test-path: >-
+              tests/unit/responses
+              tests/unit/types
+              --ignore=tests/unit/responses/mcp
             workers: 2
-            reruns: 2
+            reruns: 0
+            timeout-minutes: 20
+            job-timeout-minutes: 60
+
+          - shard: unit
+            artifact-name: unit
+            test-path: >-
+              tests/unit/anthropic_interface
+              tests/unit/compression
+              tests/unit/enterprise/enterprise_callbacks/test_callback_controls.py
+              tests/unit/enterprise/enterprise_callbacks/test_llm_guard.py
+              tests/unit/enterprise/enterprise_callbacks/test_secret_detection.py
+              tests/unit/integration_support
+              tests/unit/models
+              tests/unit/ocr
+              tests/unit/passthrough
+              tests/unit/realtime_api
+              tests/unit/repositories
+              tests/unit/sandbox
+              tests/unit/skills/test_skills_main.py
+              tests/unit/tracing
+              tests/proxy_behavior/lens/test_connection.py
+            workers: 2
+            reruns: 0
             timeout-minutes: 20
             job-timeout-minutes: 60
     uses: ./.github/workflows/_test-unit-base.yml
     with:
+      rust-bridge-artifact: ${{ needs.rust-bridge.outputs.artifact }}
       test-path: ${{ matrix.test-path }}
-      unit-flag: ${{ matrix.unit-flag || '' }}
       workers: ${{ matrix.workers }}
       reruns: ${{ matrix.reruns }}
       timeout-minutes: ${{ matrix.timeout-minutes }}
       job-timeout-minutes: ${{ matrix.job-timeout-minutes }}
+      dist: ${{ matrix.dist || 'loadscope' }}
       artifact-name: ${{ matrix.artifact-name }}
-      legacy-mcp-peer: ${{ matrix.shard == 'mcp-integration' }}

.gitignore

@@ -58,6 +58,7 @@ litellm/proxy/tests/package-lock.json
 ui/litellm-dashboard/.next
 ui/litellm-dashboard/node_modules
 ui/litellm-dashboard/next-env.d.ts
+*.tsbuildinfo
 ui/litellm-dashboard/package.json
 ui/litellm-dashboard/package-lock.json
 helm/litellm-helm/*.tgz
@@ -150,3 +151,6 @@ litellm.log
 
 .coverage-rust
 coverage-rust.xml
+
+# make lens-dev worker token, generated config and logs
+.lens-dev/

AGENTS.md

@@ -54,13 +54,13 @@ 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
 
-Never edit or commit `ruff-strict-budget.json`, `type-discipline-budget.json`, `basedpyright-code-budget.json`, or `test-quality-budget.json` on a PR branch, and don't run `make lint-budget-update` there. A scheduled Devin automation lowers the limits on the default branch in its own PR by exactly what landed since the last ratchet, so concurrent PRs don't fight over the same `"limit"` lines. Keep the hosted automation's target in sync when the repository default changes. If your branch already carries a budget edit, drop it before opening the PR
+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
 
 `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 budget 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; 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 basedpyright ceilings, just validate it in the caller with Pydantic (a model or `TypeAdapter` that returns the typed thing or raises will do) and then pass the now typed variable in
+If you'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
 
@@ -97,6 +97,7 @@ Follow these coding conventions for new/updated code (a three-line fix in a lega
   - 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
+  - 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
 - Use tagged unions + match
@@ -129,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 lint budgets 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

@@ -9,8 +9,8 @@ ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85ab0f263ef12f492d8476aa3a2
 # Pinned by digest like the other base images; bump explicitly on Node upgrades.
 ARG UI_BUILD_IMAGE=node:24.19-alpine3.24@sha256:d32cdf619f63fe0471182d08996dd516c6275bb5fd31ae06e55a570bd9e1ad43
 # Checksum from https://www.pgbouncer.org/downloads/ (the Wolfi repo only carries 1.24.x)
-ARG PGBOUNCER_VERSION=1.25.2
-ARG PGBOUNCER_SHA256=924ad35113fd0a71c8e2dbe85b5d03445532e2b7b37a9f8a48983beea238b332
+ARG PGBOUNCER_VERSION=1.26.0
+ARG PGBOUNCER_SHA256=afd25dd61ee6775d37b40629b87ce08736b3e6955f3057bb212e410fbf21c71d
 
 FROM $UV_IMAGE AS uvbin
 
@@ -79,6 +79,7 @@ COPY litellm-proxy-extras/pyproject.toml litellm-proxy-extras/
 RUN uv sync --frozen --no-install-project --no-install-workspace --no-default-groups --no-editable \
     --extra proxy \
     --extra proxy-runtime \
+    --group admin-mcp \
     --extra extra_proxy \
     --extra semantic-router \
     --extra saml \
@@ -101,6 +102,7 @@ RUN sed -i 's/\r$//' docker/build_admin_ui.sh && chmod +x docker/build_admin_ui.
 RUN uv sync --frozen --no-default-groups --no-editable \
     --extra proxy \
     --extra proxy-runtime \
+    --group admin-mcp \
     --extra extra_proxy \
     --extra semantic-router \
     --extra saml \
@@ -114,8 +116,20 @@ RUN HOME=/opt/prisma XDG_CACHE_HOME=/opt/prisma/.cache PRISMA_BINARY_CACHE_DIR=/
 RUN sed -i 's/\r$//' docker/entrypoint.sh && chmod +x docker/entrypoint.sh && \
     sed -i 's/\r$//' docker/prod_entrypoint.sh && chmod +x docker/prod_entrypoint.sh
 
+FROM $LITELLM_BUILD_IMAGE AS liteadmin-builder
+COPY --from=uvbin /uv /usr/local/bin/uv
+RUN apk add --no-cache python-3.13
+ADD --checksum=sha256:2f7ae5cdd9d91731c0990e74a58239dc3e3fd2bf28dab23b55eafcdc47aaf87e \
+    https://github.com/BerriAI/litellm-admin-agent/archive/ef501e94bc9fbacb9233b922abf71427f030408c.tar.gz /tmp/liteadmin.tar.gz
+RUN mkdir /tmp/liteadmin && tar xzf /tmp/liteadmin.tar.gz --strip-components=1 -C /tmp/liteadmin && \
+    uv venv /opt/liteadmin --python python3.13 && \
+    uv pip install --python /opt/liteadmin/bin/python --require-hashes -r /tmp/liteadmin/requirements.txt && \
+    uv pip install --python /opt/liteadmin/bin/python --no-deps /tmp/liteadmin
+
 # Runtime stage
 FROM $LITELLM_RUNTIME_IMAGE AS runtime
+ARG LITELLM_RELEASE_TAG=""
+ENV LITELLM_RELEASE_TAG=${LITELLM_RELEASE_TAG}
 
 USER root
 
@@ -141,6 +155,7 @@ ENV PATH="/app/.venv/bin:${PATH}" \
 # ship (manifest-scanning tools attribute everything in it to this image).
 # entrypoint.sh invokes litellm/proxy/prisma_migration.py by source path.
 COPY --from=builder /app/.venv /app/.venv
+COPY --from=liteadmin-builder /opt/liteadmin /opt/liteadmin
 COPY --from=builder /app/docker /app/docker
 COPY --from=builder /app/schema.prisma /app/schema.prisma
 COPY --from=builder /app/litellm/proxy/prisma_migration.py /app/litellm/proxy/prisma_migration.py

Makefile

@@ -4,11 +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 \
+	test-rust-extension rust-sqlx-prepare lens-dev \
 	info lint lint-inner lint-dev lint-checks format \
-	lint-basedpyright lint-e2e-basedpyright lint-basedpyright-budget-update lint-type-discipline lint-type-discipline-budget-update \
-	lint-ruff-budget lint-ruff-budget-update lint-budget-update lint-gate \
-	lint-test-quality lint-test-quality-budget-update \
+	lint-basedpyright lint-e2e-basedpyright lint-type-discipline \
+	lint-ruff-strict lint-gate lint-test-quality \
 	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
@@ -31,14 +30,11 @@ help:
 	@echo "  make lint               - Run all linting (Ruff, basedpyright, format check, circular imports, import safety)"
 	@echo "  make lint-ruff          - Run Ruff linting only"
 	@echo "  make lint-basedpyright  - Run basedpyright strict, gated by per-rule error counts"
-	@echo "  make lint-e2e-basedpyright - Run basedpyright over tests/e2e (zero errors allowed)"
-	@echo "  make lint-basedpyright-budget-update - Ratchet basedpyright limits down by what this branch fixed"
+	@echo "  make lint-e2e-basedpyright - Run basedpyright over tests/e2e and tests/e2e_harness (zero errors allowed)"
 	@echo "  make lint-format        - Check ruff format formatting (matches CI)"
-	@echo "  make lint-ruff-budget - Gate the codebase total of each strict ruff rule against its limit"
+	@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-ruff-budget-update - Ratchet ruff-strict-budget.json limits down by what this branch fixed"
-	@echo "  make lint-test-quality  - Gate the test suite against test-quality-budget.json"
-	@echo "  make lint-budget-update - Ratchet all budgets down (ruff + type-discipline + test quality + basedpyright)"
+	@echo "  make lint-test-quality  - Gate the test suite's TQ counts 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"
@@ -58,6 +54,7 @@ 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."
@@ -142,7 +139,7 @@ lint-fetch-base:
 
 # Mirror test-linting.yml's lint job environment: the proxy-dev group plus a generated
 # Prisma client, so `basedpyright tests/e2e` resolves the same modules CI does. The
-# budget gate itself no longer measures here (scripts/type_check_gate.py provisions its
+# basedpyright gate itself no longer measures here (scripts/type_check_gate.py provisions its
 # own .venv-typecheck). --inexact tops up the venv instead of pruning the proxy extras
 # gen:api and the running proxy need.
 lint-install:
@@ -210,27 +207,22 @@ lint-basedpyright: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 	$(UV_RUN) python scripts/type_check_gate.py --base "$(BASE_REF)"
 
 lint-e2e-basedpyright: $(LINT_E2E_DEP_INSTALL)
-	$(UV_RUN) basedpyright tests/e2e
+	$(UV_RUN) basedpyright tests/e2e tests/e2e_harness
 
-# Type-discipline budget (mutable collections / casts / type guards / kwargs /
+# Type-discipline gate (mutable collections / casts / type guards / kwargs /
 # unexplained suppressions), the test-linting.yml step `make lint` used to omit.
 lint-type-discipline: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 	$(UV_RUN) python scripts/type_discipline_gate.py --base "$(BASE_REF)"
 
-# Test-quality budget (zero-assert / mock-echo tests, sys.path.insert, raw env writes,
+# Test-quality gate (zero-assert / mock-echo tests, sys.path.insert, raw env writes,
 # litellm module-global mutation, credential-gated skips, conftest snapshot
 # inventory), counted across tests/ the same delta-vs-base way.
 lint-test-quality: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 	$(UV_RUN) python scripts/test_quality_gate.py --base "$(BASE_REF)"
 
-# --update lowers each limit by what this branch fixed since its branch point, so
-# it needs the base ref fetched to resolve the merge-base.
-lint-basedpyright-budget-update: install-dev
-	$(UV_RUN) python scripts/type_check_gate.py --update --base "$(BASE_REF)"
-
 lint-format: format-check
 
-lint-ruff-budget: install-dev
+lint-ruff-strict: install-dev
 	$(UV_RUN) python scripts/ruff_strict_gate.py --base "$(BASE_REF)"
 
 # Strict gate, invoked the same way CI does in test-linting.yml so a local pass
@@ -238,18 +230,6 @@ lint-ruff-budget: install-dev
 lint-gate: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
 	$(UV_RUN) python scripts/ruff_strict_gate.py --base "$(BASE_REF)"
 
-lint-ruff-budget-update: install-dev
-	$(UV_RUN) python scripts/ruff_strict_gate.py --update --base "$(BASE_REF)"
-
-lint-type-discipline-budget-update: install-dev
-	$(UV_RUN) python scripts/type_discipline_gate.py --update --base "$(BASE_REF)"
-
-lint-test-quality-budget-update: install-dev
-	$(UV_RUN) python scripts/test_quality_gate.py --update --base "$(BASE_REF)"
-
-# Ratchet all budgets in one shot (ruff strict + type-discipline + test quality + basedpyright)
-lint-budget-update: lint-ruff-budget-update lint-type-discipline-budget-update lint-test-quality-budget-update lint-basedpyright-budget-update
-
 check-circular-imports: $(LINT_DEP_INSTALL)
 	cd litellm && $(UV_RUN) python ../tests/documentation_tests/test_circular_imports.py && cd ..
 
@@ -259,7 +239,7 @@ check-import-safety: $(LINT_DEP_INSTALL)
 # Combined linting, isomorphic to test-linting.yml's lint job so a local pass means a
 # green CI lint: it installs the same env (proxy-dev + generated Prisma client) and then
 # runs the diff-scoped ruff format check, whole-tree ruff check, the strict-rule /
-# type-discipline / basedpyright budgets as a delta vs the base, then the circular-import
+# type-discipline / basedpyright gates as a delta vs the base, then the circular-import
 # and import-safety checks. Steps that compare against the base resolve it the same way CI
 # does (merge-base with origin's current default branch). Setup (env sync, Prisma client,
 # base fetch) runs once up front; the checks themselves are independent, so a sub-make
@@ -311,6 +291,9 @@ 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/
 

README.md

@@ -390,11 +390,13 @@ Set `LITELLM_PROXY_API_BASE` and `LITELLM_PROXY_API_KEY` and every model call th
 | [Sail (`sail`)](https://docs.litellm.ai/docs/providers/sail) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Sambanova (`sambanova`)](https://docs.litellm.ai/docs/providers/sambanova) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [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) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Text Completion OpenAI (`text-completion-openai`)](https://docs.litellm.ai/docs/providers/text_completion_openai) | ✅ | ✅ | ✅ |  |  | ✅ | ✅ | ✅ | ✅ |  |
 | [Together AI (`together_ai`)](https://docs.litellm.ai/docs/providers/togetherai) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Topaz (`topaz`)](https://docs.litellm.ai/docs/providers/topaz) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Triton (`triton`)](https://docs.litellm.ai/docs/providers/triton-inference-server) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
+| [Typesafe Decisions API (`typesafe`)](https://docs.litellm.ai/docs/providers) |  |  |  |  |  |  |  |  |  |  |
 | [V0 (`v0`)](https://docs.litellm.ai/docs/providers/v0) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [Vercel AI Gateway (`vercel_ai_gateway`)](https://docs.litellm.ai/docs/providers/vercel_ai_gateway) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |
 | [VLLM (`vllm`)](https://docs.litellm.ai/docs/providers/vllm) | ✅ | ✅ | ✅ |  |  |  |  |  |  |  |

backend/Dockerfile

@@ -44,6 +44,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --frozen --no-install-project --no-install-workspace --no-default-groups --no-editable \
         --extra proxy \
         --extra proxy-runtime \
+        --group admin-mcp \
         --extra extra_proxy \
         --extra semantic-router \
         --extra saml \
@@ -56,6 +57,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --frozen --no-default-groups --no-editable \
         --extra proxy \
         --extra proxy-runtime \
+        --group admin-mcp \
         --extra extra_proxy \
         --extra semantic-router \
         --extra saml \
@@ -71,6 +73,8 @@ RUN sed -i 's/\r$//' docker/component_entrypoint.sh && chmod +x docker/component
 
 # ---------- Runtime ----------
 FROM $LITELLM_RUNTIME_IMAGE AS runtime
+ARG LITELLM_RELEASE_TAG=""
+ENV LITELLM_RELEASE_TAG=${LITELLM_RELEASE_TAG}
 
 USER root
 

backend/main.py

@@ -8,9 +8,13 @@ Run with:
     uvicorn backend.main:app --host 0.0.0.0 --port 4001
 """
 
+from collections.abc import AsyncGenerator, Mapping
 from contextlib import asynccontextmanager
+from typing import Final
 
-from fastapi.routing import Mount
+from starlette.applications import Starlette
+from starlette.routing import Mount
+from starlette.types import Lifespan
 
 # See gateway/main.py for why we assemble DATABASE_URL(s) here before
 # importing proxy_server.
@@ -43,14 +47,16 @@ def _is_backend_route(route) -> bool:
 
 # See gateway/main.py for why the trim runs inside the lifespan instead of at
 # module scope.
-_proxy_lifespan = app.router.lifespan_context
+_proxy_lifespan: Final = app.router.lifespan_context
 
 
 @asynccontextmanager
-async def _backend_lifespan(app_):
-    async with _proxy_lifespan(app_):
+async def _backend_lifespan(
+    app_: Starlette, lifespan: Lifespan[Starlette] = _proxy_lifespan
+) -> AsyncGenerator[Mapping[str, object], None]:
+    async with lifespan(app_) as state:
         app_.router.routes = [r for r in app_.router.routes if _is_backend_route(r)]
-        yield
+        yield state if state is not None else {}
 
 
 app.router.lifespan_context = _backend_lifespan

backend/routes/allowlist.py

@@ -22,6 +22,8 @@ BACKEND_PATH_PREFIXES: tuple[str, ...] = (
     "/customer/",
     "/end_user/",
     "/sso/",
+    "/liteadmin/slack/connect/",
+    "/moyai/connect/",
     "/login",
     "/v2/login",
     "/v3/login",
@@ -84,6 +86,7 @@ BACKEND_PATH_PREFIXES: tuple[str, ...] = (
     "/analytics/",
     "/lens/",
     "/v1/traces",
+    "/v1/logs",
     "/global/",
     "/user_agent",
     "/usage/",
@@ -159,6 +162,7 @@ BACKEND_EXACT_PATHS: frozenset[str] = frozenset(
 
 BACKEND_MOUNT_PATHS: frozenset[str] = frozenset(
     {
+        "/admin",
         "/swagger",  # API documentation static assets belong to the backend
         "/mcp",  # lazily-mounted MCP sub-app serves on the backend component
     }

basedpyright-code-budget.json

@@ -1,146 +0,0 @@
-{
-  "reportAny": {
-    "limit": 13429
-  },
-  "reportArgumentType": {
-    "limit": 2198
-  },
-  "reportAssignmentType": {
-    "limit": 319
-  },
-  "reportAttributeAccessIssue": {
-    "limit": 480
-  },
-  "reportCallIssue": {
-    "limit": 112
-  },
-  "reportConstantRedefinition": {
-    "limit": 40
-  },
-  "reportDeprecated": {
-    "limit": 209
-  },
-  "reportDuplicateImport": {
-    "limit": 19
-  },
-  "reportExplicitAny": {
-    "limit": 3369
-  },
-  "reportFunctionMemberAccess": {
-    "limit": 7
-  },
-  "reportGeneralTypeIssues": {
-    "limit": 101
-  },
-  "reportIncompatibleMethodOverride": {
-    "limit": 56
-  },
-  "reportIncompatibleVariableOverride": {
-    "limit": 8
-  },
-  "reportInconsistentOverload": {
-    "limit": 12
-  },
-  "reportIndexIssue": {
-    "limit": 24
-  },
-  "reportInvalidTypeForm": {
-    "limit": 30
-  },
-  "reportInvalidTypeVarUse": {
-    "limit": 1
-  },
-  "reportMatchNotExhaustive": {
-    "limit": 0
-  },
-  "reportMissingParameterType": {
-    "limit": 5570
-  },
-  "reportMissingTypeArgument": {
-    "limit": 15281
-  },
-  "reportMissingTypeStubs": {
-    "limit": 40
-  },
-  "reportOperatorIssue": {
-    "limit": 0
-  },
-  "reportOptionalCall": {
-    "limit": 0
-  },
-  "reportOptionalIterable": {
-    "limit": 0
-  },
-  "reportOptionalMemberAccess": {
-    "limit": 0
-  },
-  "reportOptionalOperand": {
-    "limit": 0
-  },
-  "reportOptionalSubscript": {
-    "limit": 0
-  },
-  "reportPossiblyUnboundVariable": {
-    "limit": 56
-  },
-  "reportPrivateUsage": {
-    "limit": 1804
-  },
-  "reportRedeclaration": {
-    "limit": 8
-  },
-  "reportReturnType": {
-    "limit": 180
-  },
-  "reportTypedDictNotRequiredAccess": {
-    "limit": 22
-  },
-  "reportUndefinedVariable": {
-    "limit": 0
-  },
-  "reportUnknownArgumentType": {
-    "limit": 44802
-  },
-  "reportUnknownLambdaType": {
-    "limit": 109
-  },
-  "reportUnknownMemberType": {
-    "limit": 38269
-  },
-  "reportUnknownParameterType": {
-    "limit": 19584
-  },
-  "reportUnknownVariableType": {
-    "limit": 29814
-  },
-  "reportUnnecessaryCast": {
-    "limit": 110
-  },
-  "reportUnnecessaryComparison": {
-    "limit": 687
-  },
-  "reportUnnecessaryContains": {
-    "limit": 4
-  },
-  "reportUnnecessaryIsInstance": {
-    "limit": 816
-  },
-  "reportUntypedBaseClass": {
-    "limit": 0
-  },
-  "reportUntypedFunctionDecorator": {
-    "limit": 27
-  },
-  "reportUnusedClass": {
-    "limit": 21
-  },
-  "reportUnusedFunction": {
-    "limit": 136
-  },
-  "reportUnusedImport": {
-    "limit": 542
-  },
-  "reportUnusedVariable": {
-    "limit": 137
-  }
-}

ci_cd/TEST_KEY_PATTERNS.md

@@ -5,7 +5,7 @@ Standard patterns for test/mock keys and credentials in the LiteLLM codebase to
 ## How GitGuardian Works
 
 GitGuardian uses **machine learning and entropy analysis**, not just pattern matching:
-- **Low entropy** values (like `sk-1234`, `postgres`) are automatically ignored
+- **Low entropy** values (like `sk-test`, `postgres`) are automatically ignored
 - **High entropy** values (realistic-looking secrets) trigger detection
 - **Context-aware** detection understands code syntax like `os.environ["KEY"]`
 
@@ -15,8 +15,8 @@ GitGuardian uses **machine learning and entropy analysis**, not just pattern mat
 These won't trigger GitGuardian's ML detector:
 
 ```python
-api_key = "sk-1234"
-api_key = "sk-12345"
+api_key = "sk-test"
+api_key = "sk-mock"
 database_password = "postgres"
 token = "test123"
 ```

cookbook/Migrating_to_LiteLLM_Proxy_from_OpenAI_Azure_OpenAI.ipynb

@@ -16,6 +16,8 @@
         "\n",
         "These are **selected examples**. LiteLLM Proxy is **OpenAI-Compatible**, it works with any project that calls OpenAI. Just change the `base_url`, `api_key` and `model`.\n",
         "\n",
+        "Set `LITELLM_MASTER_KEY` in the notebook environment to the same key configured on the proxy before running authenticated examples\n",
+        "\n",
         "For more examples, [go here](https://docs.litellm.ai/docs/proxy/user_keys)\n",
         "\n",
         "To pass provider-specific args, [go here](https://docs.litellm.ai/docs/completion/provider_specific_params#proxy-usage)\n",
@@ -95,9 +97,10 @@
       },
       "outputs": [],
       "source": [
+        "import os\n",
         "from openai import OpenAI\n",
         "client = OpenAI(\n",
-        "    api_key=\"sk-1234\", # [OPTIONAL] set if you set one on proxy, else set \"\"\n",
+        "    api_key=os.environ[\"LITELLM_MASTER_KEY\"],\n",
         "    base_url=\"http://0.0.0.0:4000\",\n",
         ")\n",
         "\n",
@@ -298,14 +301,14 @@
         "    engine=\"azure-gpt-3.5\",               # model_name on litellm proxy\n",
         "    temperature=0.0,\n",
         "    azure_endpoint=\"http://0.0.0.0:4000\", # litellm proxy endpoint\n",
-        "    api_key=\"sk-1234\",                    # litellm proxy API Key\n",
+        "    api_key=os.environ[\"LITELLM_MASTER_KEY\"],\n",
         "    api_version=\"2023-07-01-preview\",\n",
         ")\n",
         "\n",
         "embed_model = AzureOpenAIEmbedding(\n",
         "    deployment_name=\"azure-embedding-model\",\n",
         "    azure_endpoint=\"http://0.0.0.0:4000\",\n",
-        "    api_key=\"sk-1234\",\n",
+        "    api_key=os.environ[\"LITELLM_MASTER_KEY\"],\n",
         "    api_version=\"2023-07-01-preview\",\n",
         ")\n",
         "\n",
@@ -341,7 +344,7 @@
         "\n",
         "const model = new ChatOpenAI({\n",
         "  modelName: \"gpt-4\",\n",
-        "  openAIApiKey: \"sk-1234\",\n",
+        "  openAIApiKey: process.env.LITELLM_MASTER_KEY,\n",
         "  modelKwargs: {\"metadata\": \"hello world\"} // 👈 PASS Additional params here\n",
         "}, {\n",
         "  basePath: \"http://0.0.0.0:4000\",\n",
@@ -372,7 +375,7 @@
         "const { OpenAI } = require('openai');\n",
         "\n",
         "const openai = new OpenAI({\n",
-        "  apiKey: \"sk-1234\", // This is the default and can be omitted\n",
+        "  apiKey: process.env.LITELLM_MASTER_KEY,\n",
         "  baseURL: \"http://0.0.0.0:4000\"\n",
         "});\n",
         "\n",

cookbook/Proxy_Batch_Users.ipynb

@@ -6,7 +6,9 @@
     "id": "680oRk1af-xJ"
    },
    "source": [
-    "# Environment Setup"
+    "# Environment Setup\n",
+    "\n",
+    "Set `LITELLM_MASTER_KEY` in the notebook environment to the same key configured on the proxy before running the cells"
    ]
   },
   {
@@ -17,6 +19,7 @@
    },
    "outputs": [],
    "source": [
+    "import os\n",
     "import csv\n",
     "from typing import Optional\n",
     "import httpx\n",
@@ -24,7 +27,7 @@
     "import asyncio\n",
     "\n",
     "proxy_base_url = \"http://0.0.0.0:4000\" # 👈 SET TO PROXY URL\n",
-    "master_key = \"sk-1234\" # 👈 SET TO PROXY MASTER KEY"
+    "master_key = os.environ[\"LITELLM_MASTER_KEY\"]"
    ]
   },
   {

cookbook/ai_coding_tool_guides/claude_code_quickstart/guide.md

@@ -47,7 +47,7 @@ Set your environment variables:
 
 ```bash
 export ANTHROPIC_API_KEY="your-anthropic-api-key"
-export LITELLM_MASTER_KEY="sk-1234567890"  # Generate a secure key
+export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)"
 ```
 
 ## Step 2: Start Proxy
@@ -292,4 +292,3 @@ model_list:
 - [LiteLLM Documentation](https://docs.litellm.ai/)
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code/overview)
 - [Anthropic's LiteLLM Configuration Guide](https://docs.anthropic.com/en/docs/claude-code/llm-gateway#litellm-configuration)
-

cookbook/anthropic_agent_sdk/README.md

@@ -20,6 +20,12 @@ litellm --model claude-sonnet-4-20250514
 litellm --config config.yaml
 ```
 
+Generate a master key before starting the proxy:
+
+```bash
+export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)"
+```
+
 ### 3. Run the chat
 
 **Basic Agent (no MCP):**
@@ -58,7 +64,7 @@ Set these environment variables if needed:
 
 ```bash
 export LITELLM_PROXY_URL="http://localhost:4000"
-export LITELLM_API_KEY="sk-1234"
+export LITELLM_API_KEY="$LITELLM_MASTER_KEY"
 export LITELLM_MODEL="bedrock-claude-sonnet-4.5"
 ```
 
@@ -98,7 +104,7 @@ The key is pointing the Agent SDK to LiteLLM instead of directly to Anthropic:
 ```python
 # Point to LiteLLM gateway (not Anthropic)
 os.environ["ANTHROPIC_BASE_URL"] = "http://localhost:4000"
-os.environ["ANTHROPIC_API_KEY"] = "sk-1234"  # Your LiteLLM key
+os.environ["ANTHROPIC_API_KEY"] = os.environ["LITELLM_API_KEY"]
 
 # Use any model configured in LiteLLM
 options = ClaudeAgentOptions(

cookbook/anthropic_agent_sdk/common.py

@@ -13,7 +13,7 @@ class Config:
     LITELLM_PROXY_URL = os.getenv("LITELLM_PROXY_URL", "http://localhost:4000")
 
     # LiteLLM API key (master key or virtual key)
-    LITELLM_API_KEY = os.getenv("LITELLM_API_KEY", "sk-1234")
+    LITELLM_API_KEY = os.environ["LITELLM_API_KEY"]
 
     # Model name as configured in LiteLLM (e.g., "bedrock-claude-sonnet-4", "gpt-4", etc.)
     LITELLM_MODEL = os.getenv("LITELLM_MODEL", "bedrock-claude-sonnet-4.5")

cookbook/litellm_proxy_server/batch_api/bedrock/bedrock.py

@@ -1,8 +1,10 @@
+import os
+
 from openai import OpenAI
 
 client = OpenAI(
     base_url="http://0.0.0.0:4000",
-    api_key="sk-1234",
+    api_key=os.environ["LITELLM_MASTER_KEY"],
 )
 
 BEDROCK_BATCH_MODEL = "bedrock/batch-anthropic.claude-3-5-sonnet-20240620-v1:0"

cookbook/litellm_proxy_server/grafana_dashboard/dashboard_all_metrics/grafana_dashboard.json

@@ -5710,6 +5710,17 @@
         }
       },
       "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "${DS_PROMETHEUS}"
+          },
+          "editorMode": "code",
+          "expr": "histogram_quantile(0.95, sum(rate(litellm_anthropic_wif_latency_bucket[$__rate_interval])) by (le))",
+          "legendFormat": "anthropic_wif",
+          "range": true,
+          "refId": "A"
+        },
         {
           "datasource": {
             "type": "prometheus",
@@ -5719,7 +5730,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_auth_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "auth",
           "range": true,
-          "refId": "A"
+          "refId": "B"
         },
         {
           "datasource": {
@@ -5730,7 +5741,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_batch_write_to_db_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "batch_write_to_db",
           "range": true,
-          "refId": "B"
+          "refId": "C"
         },
         {
           "datasource": {
@@ -5741,7 +5752,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_postgres_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "postgres",
           "range": true,
-          "refId": "C"
+          "refId": "D"
         },
         {
           "datasource": {
@@ -5752,7 +5763,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_proxy_pre_call_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "proxy_pre_call",
           "range": true,
-          "refId": "D"
+          "refId": "E"
         },
         {
           "datasource": {
@@ -5763,7 +5774,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_redis_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "redis",
           "range": true,
-          "refId": "E"
+          "refId": "F"
         },
         {
           "datasource": {
@@ -5774,7 +5785,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_redis_daily_org_spend_update_queue_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "redis_daily_org_spend_update_queue",
           "range": true,
-          "refId": "F"
+          "refId": "G"
         },
         {
           "datasource": {
@@ -5785,7 +5796,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_redis_daily_tag_spend_update_queue_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "redis_daily_tag_spend_update_queue",
           "range": true,
-          "refId": "G"
+          "refId": "H"
         },
         {
           "datasource": {
@@ -5796,7 +5807,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_redis_daily_team_spend_update_queue_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "redis_daily_team_spend_update_queue",
           "range": true,
-          "refId": "H"
+          "refId": "I"
         },
         {
           "datasource": {
@@ -5807,7 +5818,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_redis_window_spend_update_queue_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "redis_window_spend_update_queue",
           "range": true,
-          "refId": "I"
+          "refId": "J"
         },
         {
           "datasource": {
@@ -5818,7 +5829,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_reset_budget_job_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "reset_budget_job",
           "range": true,
-          "refId": "J"
+          "refId": "K"
         },
         {
           "datasource": {
@@ -5829,7 +5840,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_router_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "router",
           "range": true,
-          "refId": "K"
+          "refId": "L"
         },
         {
           "datasource": {
@@ -5840,7 +5851,7 @@
           "expr": "histogram_quantile(0.95, sum(rate(litellm_self_latency_bucket[$__rate_interval])) by (le))",
           "legendFormat": "self",
           "range": true,
-          "refId": "L"
+          "refId": "M"
         }
       ],
       "title": "Service latency p95 (litellm_<service>_latency)",
@@ -5888,6 +5899,28 @@
         }
       },
       "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "${DS_PROMETHEUS}"
+          },
+          "editorMode": "code",
+          "expr": "sum(rate(litellm_anthropic_wif_total_requests_total[$__rate_interval]))",
+          "legendFormat": "anthropic_wif",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "${DS_PROMETHEUS}"
+          },
+          "editorMode": "code",
+          "expr": "sum(rate(litellm_anthropic_wif_cache_total_requests_total[$__rate_interval]))",
+          "legendFormat": "anthropic_wif_cache",
+          "range": true,
+          "refId": "B"
+        },
         {
           "datasource": {
             "type": "prometheus",
@@ -5897,7 +5930,7 @@
           "expr": "sum(rate(litellm_auth_total_requests_total[$__rate_interval]))",
           "legendFormat": "auth",
           "range": true,
-          "refId": "A"
+          "refId": "C"
         },
         {
           "datasource": {
@@ -5908,7 +5941,7 @@
           "expr": "sum(rate(litellm_batch_write_to_db_total_requests_total[$__rate_interval]))",
           "legendFormat": "batch_write_to_db",
           "range": true,
-          "refId": "B"
+          "refId": "D"
         },
         {
           "datasource": {
@@ -5919,7 +5952,7 @@
           "expr": "sum(rate(litellm_postgres_total_requests_total[$__rate_interval]))",
           "legendFormat": "postgres",
           "range": true,
-          "refId": "C"
+          "refId": "E"
         },
         {
           "datasource": {
@@ -5930,7 +5963,7 @@
           "expr": "sum(rate(litellm_proxy_pre_call_total_requests_total[$__rate_interval]))",
           "legendFormat": "proxy_pre_call",
           "range": true,
-          "refId": "D"
+          "refId": "F"
         },
         {
           "datasource": {
@@ -5941,7 +5974,7 @@
           "expr": "sum(rate(litellm_redis_total_requests_total[$__rate_interval]))",
           "legendFormat": "redis",
           "range": true,
-          "refId": "E"
+          "refId": "G"
         },
         {
           "datasource": {
@@ -5952,7 +5985,7 @@
           "expr": "sum(rate(litellm_redis_daily_org_spend_update_queue_total_requests_total[$__rate_interval]))",
           "legendFormat": "redis_daily_org_spend_update_queue",
           "range": true,
-          "refId": "F"
+          "refId": "H"
         },
         {
           "datasource": {
@@ -5963,7 +5996,7 @@
           "expr": "sum(rate(litellm_redis_daily_tag_spend_update_queue_total_requests_total[$__rate_interval]))",
           "legendFormat": "redis_daily_tag_spend_update_queue",
           "range": true,
-          "refId": "G"
+          "refId": "I"
         },
         {
           "datasource": {
@@ -5974,7 +6007,7 @@
           "expr": "sum(rate(litellm_redis_daily_team_spend_update_queue_total_requests_total[$__rate_interval]))",
           "legendFormat": "redis_daily_team_spend_update_queue",
           "range": true,
-          "refId": "H"
+          "refId": "J"
         },
         {
           "datasource": {
@@ -5985,7 +6018,7 @@
           "expr": "sum(rate(litellm_redis_window_spend_update_queue_total_requests_total[$__rate_interval]))",
           "legendFormat": "redis_window_spend_update_queue",
           "range": true,
-          "refId": "I"
+          "refId": "K"
         },
         {
           "datasource": {
@@ -5996,7 +6029,7 @@
           "expr": "sum(rate(litellm_reset_budget_job_total_requests_total[$__rate_interval]))",
           "legendFormat": "reset_budget_job",
           "range": true,
-          "refId": "J"
+          "refId": "L"
         },
         {
           "datasource": {
@@ -6007,7 +6040,7 @@
           "expr": "sum(rate(litellm_router_total_requests_total[$__rate_interval]))",
           "legendFormat": "router",
           "range": true,
-          "refId": "K"
+          "refId": "M"
         },
         {
           "datasource": {
@@ -6018,7 +6051,7 @@
           "expr": "sum(rate(litellm_self_total_requests_total[$__rate_interval]))",
           "legendFormat": "self",
           "range": true,
-          "refId": "L"
+          "refId": "N"
         }
       ],
       "title": "Service request rate (litellm_<service>_total_requests)",
@@ -6066,6 +6099,28 @@
         }
       },
       "targets": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "${DS_PROMETHEUS}"
+          },
+          "editorMode": "code",
+          "expr": "sum(rate(litellm_anthropic_wif_failed_requests_total[$__rate_interval])) by (error_class)",
+          "legendFormat": "anthropic_wif / {{error_class}}",
+          "range": true,
+          "refId": "A"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "${DS_PROMETHEUS}"
+          },
+          "editorMode": "code",
+          "expr": "sum(rate(litellm_anthropic_wif_cache_failed_requests_total[$__rate_interval])) by (error_class)",
+          "legendFormat": "anthropic_wif_cache / {{error_class}}",
+          "range": true,
+          "refId": "B"
+        },
         {
           "datasource": {
             "type": "prometheus",
@@ -6075,7 +6130,7 @@
           "expr": "sum(rate(litellm_auth_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "auth / {{error_class}}",
           "range": true,
-          "refId": "A"
+          "refId": "C"
         },
         {
           "datasource": {
@@ -6086,7 +6141,7 @@
           "expr": "sum(rate(litellm_batch_write_to_db_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "batch_write_to_db / {{error_class}}",
           "range": true,
-          "refId": "B"
+          "refId": "D"
         },
         {
           "datasource": {
@@ -6097,7 +6152,7 @@
           "expr": "sum(rate(litellm_postgres_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "postgres / {{error_class}}",
           "range": true,
-          "refId": "C"
+          "refId": "E"
         },
         {
           "datasource": {
@@ -6108,7 +6163,7 @@
           "expr": "sum(rate(litellm_proxy_pre_call_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "proxy_pre_call / {{error_class}}",
           "range": true,
-          "refId": "D"
+          "refId": "F"
         },
         {
           "datasource": {
@@ -6119,7 +6174,7 @@
           "expr": "sum(rate(litellm_redis_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "redis / {{error_class}}",
           "range": true,
-          "refId": "E"
+          "refId": "G"
         },
         {
           "datasource": {
@@ -6130,7 +6185,7 @@
           "expr": "sum(rate(litellm_redis_daily_org_spend_update_queue_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "redis_daily_org_spend_update_queue / {{error_class}}",
           "range": true,
-          "refId": "F"
+          "refId": "H"
         },
         {
           "datasource": {
@@ -6141,7 +6196,7 @@
           "expr": "sum(rate(litellm_redis_daily_tag_spend_update_queue_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "redis_daily_tag_spend_update_queue / {{error_class}}",
           "range": true,
-          "refId": "G"
+          "refId": "I"
         },
         {
           "datasource": {
@@ -6152,7 +6207,7 @@
           "expr": "sum(rate(litellm_redis_daily_team_spend_update_queue_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "redis_daily_team_spend_update_queue / {{error_class}}",
           "range": true,
-          "refId": "H"
+          "refId": "J"
         },
         {
           "datasource": {
@@ -6163,7 +6218,7 @@
           "expr": "sum(rate(litellm_redis_window_spend_update_queue_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "redis_window_spend_update_queue / {{error_class}}",
           "range": true,
-          "refId": "I"
+          "refId": "K"
         },
         {
           "datasource": {
@@ -6174,7 +6229,7 @@
           "expr": "sum(rate(litellm_reset_budget_job_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "reset_budget_job / {{error_class}}",
           "range": true,
-          "refId": "J"
+          "refId": "L"
         },
         {
           "datasource": {
@@ -6185,7 +6240,7 @@
           "expr": "sum(rate(litellm_router_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "router / {{error_class}}",
           "range": true,
-          "refId": "K"
+          "refId": "M"
         },
         {
           "datasource": {
@@ -6196,7 +6251,7 @@
           "expr": "sum(rate(litellm_self_failed_requests_total[$__rate_interval])) by (error_class)",
           "legendFormat": "self / {{error_class}}",
           "range": true,
-          "refId": "L"
+          "refId": "N"
         }
       ],
       "title": "Service failure rate (litellm_<service>_failed_requests)",

cookbook/litellm_proxy_server/grafana_dashboard/dashboard_all_metrics/readme.md

@@ -1,6 +1,6 @@
 # LiteLLM All Prometheus Metrics dashboard
 
-Every `litellm_*` metric family the proxy can expose on `/metrics` (136 families across 97 panels), grouped into rows: proxy traffic, latency, spend and tokens, cache, LLM API deployments, key and team rate limits, budgets, guardrails, MCP, managed files and batches, users and teams, the Redis circuit breaker, the spend log cleanup job, and the `prometheus_system` service callback metrics (per-service latency, request and failure rates, spend update queue sizes). Panel titles are the metric names so you can grep the JSON for the metric you care about
+Every `litellm_*` metric family the proxy can expose on `/metrics` (141 families across 97 panels), grouped into rows: proxy traffic, latency, spend and tokens, cache, LLM API deployments, key and team rate limits, budgets, guardrails, MCP, managed files and batches, users and teams, the Redis circuit breaker, the spend log cleanup job, and the `prometheus_system` service callback metrics (per-service latency, request and failure rates, spend update queue sizes). Panel titles are the metric names so you can grep the JSON for the metric you care about
 
 Import `grafana_dashboard.json` from **Dashboards > New > Import** and pick your Prometheus data source when prompted (the `DS_PROMETHEUS` variable). Counters are plotted as `rate()` over `$__rate_interval`, histograms as p50 / p95 / p99, gauges as the raw value grouped by the most useful label. Every query names the metric exactly as the proxy emits it (counters carry the `_total` suffix the Prometheus client adds), and `tests/unit/integrations/test_prometheus_metric_name_consistency.py` fails if a metric is renamed without updating this dashboard
 

cookbook/litellm_proxy_server/mcp/mcp_with_litellm_proxy.py

@@ -4,10 +4,12 @@ Use LiteLLM Proxy MCP Gateway to call MCP tools.
 When using LiteLLM Proxy, you can use the same MCP tools across all your LLM providers.
 """
 
+import os
+
 import openai
 
 client = openai.OpenAI(
-    api_key="sk-1234",  # paste your litellm proxy api key here
+    api_key=os.environ["LITELLM_MASTER_KEY"],
     base_url="http://localhost:4000",  # paste your litellm proxy base url here
 )
 print("Making API request to Responses API with MCP tools")

cookbook/livekit_agent_sdk/README.md

@@ -15,12 +15,14 @@ pip install livekit-agents[xai] websockets
 ```bash
 # With xAI
 export XAI_API_KEY="your-xai-key"
+export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)"
 litellm --config config.yaml --port 4000
 ```
 
 ### 3. Run the voice agent
 
 ```bash
+export LITELLM_API_KEY="$LITELLM_MASTER_KEY"
 python main.py
 ```
 
@@ -32,7 +34,7 @@ Set these environment variables if needed:
 
 ```bash
 export LITELLM_PROXY_URL="http://localhost:4000"
-export LITELLM_API_KEY="sk-1234"
+export LITELLM_API_KEY="$LITELLM_MASTER_KEY"
 export LITELLM_MODEL="grok-voice-agent"
 ```
 
@@ -59,7 +61,7 @@ model_list:
       mode: realtime
 
 general_settings:
-  master_key: sk-1234
+  master_key: os.environ/LITELLM_MASTER_KEY
 ```
 
 Then start: `litellm --config config.yaml --port 4000`
@@ -73,7 +75,7 @@ from livekit.plugins import xai
 
 model = xai.realtime.RealtimeModel(
     voice="ara",
-    api_key="sk-1234",              # LiteLLM proxy key
+    api_key=os.environ["LITELLM_MASTER_KEY"],
     base_url="http://localhost:4000", # Point to LiteLLM
 )
 ```

cookbook/livekit_agent_sdk/config.example.yaml

@@ -17,4 +17,4 @@ litellm_settings:
   drop_params: True
 
 general_settings:
-  master_key: sk-1234  # Change this to a secure key
+  master_key: os.environ/LITELLM_MASTER_KEY

cookbook/livekit_agent_sdk/main.py

@@ -13,7 +13,7 @@ import websockets
 
 # Configuration
 PROXY_URL = os.getenv("LITELLM_PROXY_URL", "http://localhost:4000")
-API_KEY = os.getenv("LITELLM_API_KEY", "sk-1234")
+API_KEY = os.environ["LITELLM_API_KEY"]
 MODEL = os.getenv("LITELLM_MODEL", "grok-voice-agent")
 
 

cookbook/misc/config.yaml

@@ -58,7 +58,7 @@ litellm_settings:
   context_window_fallbacks: [{"gpt-3.5-turbo": ["gpt-3.5-turbo-large"]}]
 
 general_settings: 
-  master_key: sk-1234 # [OPTIONAL] Use to enforce auth on proxy. See - https://docs.litellm.ai/docs/proxy/virtual_keys
+  master_key: os.environ/LITELLM_MASTER_KEY
   store_model_in_db: True
   proxy_budget_rescheduler_min_time: 60
   proxy_budget_rescheduler_max_time: 64

cookbook/misc/migrate_proxy_config.py

@@ -12,6 +12,8 @@ Step 2: reads `model_list` and loops through all models
 Step 3: calls `<proxy-base-url>/model/new` for each model
 """
 
+import os
+
 import yaml
 import requests
 
@@ -89,7 +91,7 @@ def migrate_models(config_file, proxy_base_url):
 # Usage
 config_file = "config.yaml"
 proxy_base_url = "http://0.0.0.0:4000"
-master_key = "sk-1234"
+master_key = os.environ["LITELLM_MASTER_KEY"]
 print(f"config_file: {config_file}")
 print(f"proxy_base_url: {proxy_base_url}")
 migrate_models(config_file, proxy_base_url)

cookbook/misc/test_responses_api.py

@@ -1,8 +1,10 @@
 import base64
+import os
+
 from openai import OpenAI
 import time
 
-client = OpenAI(base_url="http://0.0.0.0:4001", api_key="sk-1234")
+client = OpenAI(base_url="http://0.0.0.0:4001", api_key=os.environ["LITELLM_MASTER_KEY"])
 
 
 # Function to encode the image

cookbook/mlflow_langchain_tracing_litellm_proxy.ipynb

@@ -4,7 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Databricks Notebook with MLFlow AutoLogging for LiteLLM Proxy calls\n"
+    "# Databricks Notebook with MLFlow AutoLogging for LiteLLM Proxy calls\n",
+    "\n",
+    "Set `LITELLM_PROXY_API_KEY` in the notebook environment to a key accepted by the proxy before running the model cell\n"
    ]
   },
   {
@@ -160,11 +162,13 @@
    },
    "outputs": [],
    "source": [
+    "import os\n",
+    "\n",
     "model = ChatOpenAI(\n",
     "    openai_api_base=\"LITELLM_PROXY_BASE_URL\", # e.g.: http://0.0.0.0:4000\n",
     "    model = \"gpt-3.5-turbo\", # LITELLM 'model_name'\n",
     "    temperature=0.1, \n",
-    "    api_key=\"LITELLM_PROXY_API_KEY\" # e.g.: \"sk-1234\"\n",
+    "    api_key=os.environ[\"LITELLM_PROXY_API_KEY\"]\n",
     ")"
    ]
   },

cookbook/mock_prompt_management_server/README.md

@@ -69,7 +69,7 @@ litellm --config config.yaml
 ```bash
 curl http://0.0.0.0:4000/v1/chat/completions \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer sk-1234" \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
   -d '{
     "model": "gpt-3.5-turbo",
     "prompt_id": "hello-world-prompt",
@@ -290,4 +290,3 @@ Before deploying to production:
 ## Questions?
 
 This is a reference implementation for the LiteLLM Generic Prompt Management API. For questions or issues, please open an issue on the [LiteLLM GitHub repository](https://github.com/BerriAI/litellm).
-

cookbook/nova_sonic_realtime.py

@@ -10,6 +10,7 @@ Prerequisites:
 - websockets installed: pip install websockets
 
 Usage:
+    export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)"
     python nova_sonic_realtime.py
 """
 
@@ -33,7 +34,7 @@ CHUNK_SIZE = 1024
 
 # LiteLLM proxy configuration
 LITELLM_PROXY_URL = "ws://localhost:4000/v1/realtime?model=bedrock-sonic"
-LITELLM_API_KEY = "sk-12345"  # Your LiteLLM API key
+LITELLM_API_KEY = os.environ["LITELLM_MASTER_KEY"]
 
 
 class RealtimeClient:

cookbook/veo_video_generation.py

@@ -24,8 +24,8 @@ class VeoVideoGenerator:
 
     def __init__(
         self,
+        api_key: str,
         base_url: str = "http://localhost:4000/gemini/v1beta",
-        api_key: str = "sk-1234",
     ):
         """
         Initialize the Veo video generator.
@@ -274,12 +274,12 @@ def main():
 
     Configure these environment variables:
     - LITELLM_BASE_URL: Your LiteLLM proxy URL (default: http://localhost:4000/gemini/v1beta)
-    - LITELLM_API_KEY: Your LiteLLM API key (default: sk-1234)
+    - LITELLM_API_KEY: API key for LiteLLM proxy authentication
     """
 
     # Configuration from environment or defaults
     base_url = os.getenv("LITELLM_BASE_URL", "http://localhost:4000/gemini/v1beta")
-    api_key = os.getenv("LITELLM_API_KEY", "sk-1234")
+    api_key = os.environ["LITELLM_API_KEY"]
 
     print("🚀 Starting Veo Video Generation Example")
     print(f"📡 Using LiteLLM proxy at: {base_url}")

deploy/lens/Dockerfile

@@ -1,6 +1,41 @@
-FROM python:3.12-slim
+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
-RUN pip install --no-cache-dir httpx==0.28.1 pydantic==2.11.7
-COPY litellm/proxy/lens/__init__.py litellm/proxy/lens/models.py litellm/proxy/lens/trace_store.py litellm/proxy/lens/analysis.py litellm/proxy/lens/worker.py /app/lens/
+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
-CMD ["python", "-m", "lens.worker"]
+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,8 +1,15 @@
 **
+!deploy/
+!deploy/lens/
+!deploy/lens/python_policy.c
+!deploy/lens/python_runtime.py
 !litellm/
 !litellm/proxy/
 !litellm/proxy/lens/
-!litellm/proxy/lens/__init__.py
-!litellm/proxy/lens/models.py
-!litellm/proxy/lens/analysis.py
-!litellm/proxy/lens/worker.py
+!litellm/proxy/lens/prompts/
+!litellm/proxy/lens/prompts/**
+!.cargo/
+!.cargo/**
+!litellm-rust/
+!litellm-rust/**
+litellm-rust/target/

deploy/lens/README.md

@@ -1,32 +1,121 @@
-# Lens worker
+# Lens service
 
-Lens reviews recorded activity and saves evidence-linked findings in the LiteLLM dashboard under Observability, Lens (`/ui/lens/`)
+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
 
-## Start a worker
+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
 
-Upgrade your existing LiteLLM proxy to a release that includes Lens with PostgreSQL, agent tracing (`general_settings.tracing: {store: clickhouse}`), and ClickHouse configured through `CLICKHOUSE_URL` and a separate SELECT-only `CLICKHOUSE_READER_URL`. Enable the ClickHouse callback and request/response logging to analyze LLM requests. Lens can only inspect content you actually retain
+## New local installation
 
-In Lens, click **Set up analysis**, choose an existing virtual key or **Create worker key**, then **Generate setup command**. The LiteLLM address is filled in for you; change it only if the server running Docker needs a different network address. Copy the command and run it on your server. The dialog changes to **Analyzer connected** when the container checks in
-
-The command already contains the compatible worker image and one worker token. The selected virtual key stays on the proxy; its secret is never sent to the worker. No source checkout, environment file, or second LiteLLM deployment is needed. Keep the command private because it includes the token. The LiteLLM release provides the dashboard and APIs; the container only runs background analysis
-
-The dashboard and Compose file pin a verified worker image by digest. The image uses Linux amd64, and the generated command selects that platform. Worker image releases are independent of proxy releases: update the pinned image when changing their API contract. CI also publishes immutable commit tags for reproducible builds
-
-For deployments managed with Compose, download `compose.yaml` and provide `LITELLM_URL` and `LENS_WORKER_TOKEN` in an environment file. Its default image is already selected:
+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
-docker compose --env-file /path/to/lens.env -f compose.yaml up -d
+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
 ```
 
-Developers can build locally with `LENS_WORKER_IMAGE=litellm-lens-worker:local docker compose -f deploy/lens/compose.yaml -f deploy/lens/compose.build.yaml up -d --build`
+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
 
-The generated command gives the worker 1 GiB of temporary memory-backed storage, shared across parallel reviews. Change `size=1g` in the Docker command or set `LENS_WORKER_TMP_SIZE` with Compose to fit your server and workload. A storage failure marks the scan as failed, cleans up temporary traces, and leaves the worker available for other scans; it does not silently truncate the review. Existing workers must be recreated with the new image and mount options
+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
 
-The worker needs outbound HTTPS access to LiteLLM. It needs no inbound ports, provider keys, direct database access, or GPU. The proxy calls your selected model through its normal virtual-key authorization and inference pipeline; trace content reaches that model provider. Use a model with JSON output support and known token prices. One worker handles one scan at a time and can serve multiple lenses. For more throughput, start another worker with a separate credential
+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
 
-If your deployment restricts `allowed_ips`, allow the worker's address. For workers behind a reverse proxy with `use_x_forwarded_for: true`, also configure `mcp_trusted_proxy_ranges` with that proxy's CIDRs and, when needed, `mcp_xff_num_trusted_hops`. Lens reuses these existing trusted-proxy settings. Forwarded addresses without an established trust boundary are rejected by the allowlist; accepting them would let a worker impersonate an allowed address
+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
 
-V1 setup, manual runs, feedback, and worker credentials are restricted to proxy administrators. Proxy-admin viewers can inspect results. Regular user and team keys cannot access the Lens API. Worker credentials can serve the administrator’s lenses. Revoke it in the connection dialog when retiring a worker. Redeploy the worker alongside proxy upgrades so their API versions match
+## 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
 
@@ -34,17 +123,17 @@ Choose agent runs, individual LLM requests, or both. The matching-activity previ
 
 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. Every scan recalculates the window, so overlapping windows can review the same activity again. Duplicate a lens when you want a separate investigation without changing an existing monitor
+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 10 seconds; 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. Configuration edits apply to the next scan. A running scan retains its settings and selected execution IDs across retries
+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 batch selector or Scans tab to reopen previous results. Each batch keeps its own findings, settings, selected runs, coverage and cost. Older batches created before snapshot support remain available through accumulated findings. The Runs tab lists the selected batch's sample and can filter per-run observations, including runs without an observed issue and runs with insufficient evidence. These observations precede the final evidence investigation. Linked-run counts on findings include cited counterexamples, so they are not failure counts
+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
 
-Choose **This is expected** and explain why to teach later scans about acceptable behavior. Feedback is kept with the lens and included in subsequent reviews. It does not alter historical evidence or exempt different problems
+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
 
@@ -52,11 +141,15 @@ The proxy selects executions received or updated within the configured lookback
 
 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 reviews the selected executions in parallel. It pages through their recorded spans and gives the first reviewer a catalog, task and outcome excerpts. The reviewer can read more original content to resolve uncertainties. Large catalogs and groups of observations are processed in bounded context windows, with every page available. Grouping retains supporting run IDs in code, so a pattern occurring thousands of times does not require a model to repeat thousands of IDs. Candidate investigators can page through supporting observations, other runs and original evidence
+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
 
-There is no fixed total run, span, candidate or investigation-turn cutoff. Repeated or empty evidence requests stop a stalled investigation. Context windows, the configured budget, available model capacity and recorded evidence still bound practical work. The dashboard reports completed work and gaps. The investigator has no shell, browsing, code-editing or production-action tools
+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
 
-Each model response must match a bounded JSON schema. A malformed response gets one repair attempt through the same budget controls; repeated invalid output fails the scan. Both the worker and proxy validate quoted evidence. 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
+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
 
@@ -64,9 +157,15 @@ Coverage distinguishes eligible, sampled, reviewed, partial, and unassessable ex
 
 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
 
-Before every model call, Lens reserves a conservative amount against the monthly lens budget. Successful calls reconcile to reported cost where pricing is available. Interrupted calls retain their reservation because the provider may have charged. A scan stops when the next reservation would exceed the limit, so it can stop with some budget remaining. Both the Lens budget and the selected virtual key’s budgets, model permissions, and rate limits apply. Analysis spend appears under that key in Virtual Keys and normal request logs, with Lens, scan, 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. Existing workers need a billing key assigned in **Set up analysis** before they can resume
+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
 
-V1 requires ClickHouse for both sources. It does not reconstruct sessions from unrelated trace IDs, guarantee exhaustive reviews, cache all per-execution observations across scans, or automatically fix agent code. Trace contents can change as late spans arrive, even though a job's selected IDs are fixed. Findings should be reviewed by a person before acting on them
+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
@@ -92,11 +191,24 @@ curl "$LITELLM_URL/lens/$LENS_ID/runs/$BATCH_ID" -H "Authorization: Bearer $LITE
 
 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
@@ -104,14 +216,67 @@ python -m tests.proxy_behavior.lens.evaluate --api-base "$LITELLM_URL" \
 
 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 worker uses temporary disk space for trace content while reviewing it, and removes those files after each review. The Docker command supplies a writable temporary mount while keeping the application filesystem read-only
+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
 
-## Upgrading from the original Lens API
+## Release compatibility
 
-The Lens API now uses `/lens` instead of `/engine`, list responses use `lenses`, and worker claims use `lens_id`. Upgrade the proxy and recreate every worker with the image shown by the upgraded dashboard before starting new scans. Update API clients to the new paths and response fields. Old worker images cannot poll the renamed API
+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
 
-Stop workers and let active scans finish before upgrading. Deploy proxy instances together: older proxies cannot use the renamed database tables. The schema migration renames the three Lens tables and the run-history identifier column in place, preserving saved investigations, findings, history, worker credentials, and billing assignments. Existing migration files retain their original names and checksums
+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
 
-Upgrades using `--use_prisma_db_push` stop before schema changes if any legacy Lens table exists, preventing Prisma from dropping saved data. Apply `litellm-proxy-extras/litellm_proxy_extras/migrations/20261001100000_rename_lens/migration.sql` to the configured database schema before retrying. Deployments already using migration history can instead start without `--use_prisma_db_push` to apply the shipped migration normally. Fresh databases and databases already using the renamed tables can continue using database push
+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

@@ -3,4 +3,6 @@ services:
     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,9 +1,18 @@
 services:
   lens-worker:
-    image: ${LENS_WORKER_IMAGE:-ghcr.io/berriai/litellm-lens-worker@sha256:67eba741c1b97c749975c5c38e2370a603e1105babc908d613c1b79d7b995393}
+    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:?Create a worker credential in the Lens UI}
+      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:

deploy/lens/config.yaml

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

deploy/lens/configure.py

@@ -0,0 +1,73 @@
+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

@@ -0,0 +1,63 @@
+#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

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,40 @@
+#!/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