Merge branch 'main' into fix/router-track-empty-model-list-live-routers

.circleci/config.yml

@@ -524,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
@@ -545,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: |
@@ -599,7 +610,9 @@ jobs:
   local_testing_part2:
     docker:
       - *python312_image
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
     parallelism: 4
     steps:
       - checkout
@@ -619,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: |
@@ -673,7 +689,9 @@ jobs:
   langfuse_logging_unit_tests:
     docker:
       - *python312_image
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
     resource_class: medium
 
     steps:
@@ -694,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: |
@@ -722,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
@@ -892,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
@@ -1021,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
@@ -1547,7 +1486,9 @@ jobs:
   installing_litellm_on_python:
     docker:
       - *python312_image
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
 
     steps:
       - checkout
@@ -1560,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: |
@@ -1571,7 +1515,9 @@ jobs:
         auth:
           username: ${DOCKERHUB_USERNAME}
           password: ${DOCKERHUB_PASSWORD}
+      - *postgres16_sidecar
     working_directory: ~/project
+    environment: *sidecar_database_url
     resource_class: medium
 
     steps:
@@ -1584,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: |
@@ -1592,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
@@ -1706,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
@@ -1729,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 \
@@ -1802,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
@@ -1825,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 \
@@ -1872,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
@@ -1901,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
@@ -1922,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" \
@@ -1987,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
@@ -2012,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 \
@@ -2073,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" \
@@ -2122,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
@@ -2151,11 +2115,10 @@ 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=host.docker.internal \
               -e REDIS_PORT=6379 \
-              -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 \
@@ -2210,6 +2173,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
@@ -2234,12 +2202,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 \
@@ -2257,12 +2224,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 \
@@ -2309,6 +2275,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
@@ -2335,10 +2306,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 \
@@ -2388,6 +2358,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
@@ -2410,12 +2385,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 \
@@ -2472,6 +2446,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
@@ -2493,9 +2472,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 \
@@ -2563,6 +2541,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
@@ -2585,9 +2568,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 \
@@ -2613,7 +2595,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 \
@@ -2647,7 +2629,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
@@ -2676,6 +2658,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
@@ -2766,8 +2753,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: ""
@@ -2787,7 +2772,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
@@ -2834,6 +2819,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
@@ -2910,8 +2900,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
@@ -2926,7 +2914,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
@@ -3019,6 +3007,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:
@@ -3138,6 +3131,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
@@ -3167,9 +3165,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:
@@ -3292,35 +3294,6 @@ jobs:
       - store_artifacts:
           path: test-results
 
-  unit:
-    machine:
-      image: ubuntu-2204:2024.04.1
-    resource_class: large
-    working_directory: ~/project
-    parallelism: 4
-    steps:
-      - 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
-          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"
-      - store_test_results:
-          path: test-results
-      - store_artifacts:
-          path: test-results
-
   postgres_suite:
     parameters:
       test_path:
@@ -3541,7 +3514,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
@@ -3594,13 +3571,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
@@ -3634,7 +3609,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
@@ -3649,7 +3623,6 @@ workflows:
       - upload-coverage:
           requires:
             - realtime_translation_testing
-            - agent_testing
             - google_generate_content_endpoint_testing
             - guardrails_testing
             - ocr_testing
@@ -3663,7 +3636,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/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

.circleci/scripts/unit_selection.sh

@@ -1,187 +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/proxy/test_liteadmin.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/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/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
@@ -27,6 +26,7 @@ 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,44 +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]:
@@ -211,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(
@@ -505,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",
@@ -678,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,11 +74,16 @@ on:
         description: "Unique name for the coverage artifact (must be unique per run)"
         required: true
         type: string
+      rust-bridge-artifact:
+        description: "Prebuilt editable Rust bridge artifact"
+        required: false
+        type: string
+        default: ""
 permissions:
   contents: read
 
 env:
-  UV_PYTHON: "3.12"
+  UV_PYTHON: ${{ inputs.python-version }}
   LITELLM_LOCAL_MODEL_COST_MAP: "True"
 
 jobs:
@@ -128,17 +128,28 @@ 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:
+          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
+          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
+          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 --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
@@ -158,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 }}
@@ -168,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/image-scan.yml

@@ -9,10 +9,12 @@ 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/**
@@ -21,6 +23,10 @@ on:
       - 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
@@ -142,6 +148,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
@@ -155,9 +164,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
@@ -176,21 +186,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 --build-arg LITELLM_RELEASE_TAG=v0.0.0-lens-ci -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
@@ -200,11 +217,13 @@ 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
@@ -266,9 +285,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
@@ -316,6 +336,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:
@@ -324,7 +347,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-worker.yml

@@ -6,12 +6,14 @@ on:
     paths:
       - deploy/lens/**
       - litellm/proxy/lens/**
+      - tests/proxy_behavior/lens/**
       - .github/workflows/lens-worker.yml
   push:
     branches: [main]
     paths:
       - deploy/lens/**
       - litellm/proxy/lens/**
+      - tests/proxy_behavior/lens/**
       - .github/workflows/lens-worker.yml
   workflow_dispatch:
 
@@ -27,6 +29,7 @@ jobs:
     permissions:
       contents: read
       packages: write
+      id-token: write
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -54,12 +57,66 @@ jobs:
           with trace_store() as store:
               assert store.count() == 0
           '
-      - name: Verify recovery after temporary storage fills
+      - name: Prepare test-only coverage tool
+        run: |
+          coverage_directory=$(mktemp -d "$RUNNER_TEMP/lens-coverage.XXXXXX")
+          curl --fail --silent --show-error --location \
+            https://files.pythonhosted.org/packages/61/e8/cb8e80d6f9f55b99588625062822bf946cf03ed06315df4bd8397f5632a1/coverage-7.14.0-py3-none-any.whl \
+            --output "$coverage_directory/coverage.whl"
+          printf '%s  %s\n' 8de5b61163aee3d05c8a2beab6f47913df7981dad1baf82c414d99158c286ab1 \
+            "$coverage_directory/coverage.whl" | sha256sum --check
+          chmod 777 "$coverage_directory"
+          echo "LENS_COVERAGE_DIRECTORY=$coverage_directory" >> "$GITHUB_ENV"
+      - name: Verify confined Python execution
+        run: |
+          docker run --rm --network none --read-only --cap-drop ALL \
+            --tmpfs /tmp:rw,noexec,nosuid,size=1g --security-opt no-new-privileges \
+            -v "$PWD/tests/proxy_behavior/lens/worker_python_smoke.py:/app/python_smoke.py:ro" \
+            -v "$PWD/tests/proxy_behavior/lens/coverage.ini:/coverage.ini:ro" \
+            -v "$LENS_COVERAGE_DIRECTORY:/coverage" \
+            -e PYTHONPATH=/coverage/coverage.whl -e COVERAGE_RCFILE=/coverage.ini \
+            --entrypoint python lens-worker:${{ github.sha }} \
+            -m coverage run --data-file=/coverage/.coverage.python /app/python_smoke.py
+      - name: Verify workspace investigation and live review output
+        run: |
+          docker run --rm --network none --read-only --cap-drop ALL \
+            --tmpfs /tmp:rw,noexec,nosuid,size=1g --security-opt no-new-privileges \
+            -v "$PWD/tests/proxy_behavior/lens/worker_context_smoke.py:/app/context_smoke.py:ro" \
+            -v "$PWD/tests/proxy_behavior/lens/coverage.ini:/coverage.ini:ro" \
+            -v "$LENS_COVERAGE_DIRECTORY:/coverage" \
+            -e PYTHONPATH=/coverage/coverage.whl -e COVERAGE_RCFILE=/coverage.ini \
+            --entrypoint python lens-worker:${{ github.sha }} \
+            -m coverage run --data-file=/coverage/.coverage.context /app/context_smoke.py
+      - name: Verify default workspace recovery after Python scratch storage fills
         run: |
           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
+            -v "$PWD/tests/proxy_behavior/lens/coverage.ini:/coverage.ini:ro" \
+            -v "$LENS_COVERAGE_DIRECTORY:/coverage" \
+            -e PYTHONPATH=/coverage/coverage.whl -e COVERAGE_RCFILE=/coverage.ini \
+            --entrypoint python lens-worker:${{ github.sha }} \
+            -m coverage run --data-file=/coverage/.coverage.storage /app/storage_smoke.py
+      - name: Map native worker coverage to repository sources
+        if: always() && env.LENS_COVERAGE_DIRECTORY != ''
+        run: |
+          docker run --rm --network none --read-only --cap-drop ALL \
+            --security-opt no-new-privileges -w /workspace \
+            -v "$PWD/litellm/proxy/lens:/workspace/litellm/proxy/lens:ro" \
+            -v "$PWD/tests/proxy_behavior/lens/coverage.ini:/coverage.ini:ro" \
+            -v "$LENS_COVERAGE_DIRECTORY:/coverage" \
+            -e PYTHONPATH=/coverage/coverage.whl -e COVERAGE_RCFILE=/coverage.ini \
+            --entrypoint /bin/sh lens-worker:${{ github.sha }} \
+            -c 'python -m coverage combine && python -m coverage xml'
+      - name: Upload native worker coverage
+        if: always() && env.LENS_COVERAGE_DIRECTORY != ''
+        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
+        with:
+          use_oidc: true
+          files: ${{ env.LENS_COVERAGE_DIRECTORY }}/lens-worker.xml
+          root_dir: ${{ github.workspace }}
+          flags: lens-worker
+          fail_ci_if_error: false
       - name: Publish versioned Lens worker
         if: github.event_name != 'pull_request' && github.repository == 'BerriAI/litellm' && github.ref == 'refs/heads/main'
         env:

.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-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
@@ -52,18 +139,33 @@ jobs:
         include:
           - shard: core-utils
             artifact-name: core-utils
-            test-path: tests/unit/decisions
-            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
@@ -73,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
 
@@ -101,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
@@ -121,35 +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/management_endpoints
+              tests/unit/proxy/management_helpers
+              tests/unit/proxy/list_api
               tests/unit/proxy/analytics_endpoints
               tests/unit/proxy/decisions_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/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
@@ -159,11 +321,9 @@ jobs:
               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
@@ -174,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
 
@@ -182,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
 
@@ -209,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
 
@@ -245,51 +408,92 @@ 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
+            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 }}

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 \

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 \

backend/routes/allowlist.py

@@ -85,6 +85,7 @@ BACKEND_PATH_PREFIXES: tuple[str, ...] = (
     "/analytics/",
     "/lens/",
     "/v1/traces",
+    "/v1/logs",
     "/global/",
     "/user_agent",
     "/usage/",
@@ -160,6 +161,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
     }

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/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

@@ -6,23 +6,31 @@ FROM $UV_IMAGE AS uvbin
 
 FROM $LITELLM_BUILD_IMAGE AS builder
 COPY --from=uvbin /uv /usr/local/bin/uv
-RUN apk add --no-cache python-3.13
+RUN apk add --no-cache python-3.13 build-base libseccomp-dev
 ENV UV_PYTHON_DOWNLOADS=0 UV_LINK_MODE=copy
 WORKDIR /app
 COPY deploy/lens/requirements.lock /tmp/requirements.lock
 RUN uv venv --python python3.13 /app/.venv && \
     uv pip sync --python /app/.venv/bin/python --require-hashes --only-binary :all: /tmp/requirements.lock
+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 /app/python.seccomp
 
 FROM $LITELLM_RUNTIME_IMAGE AS runtime
 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
+RUN apk add --no-cache python-3.13 setpriv
 ENV LITELLM_RELEASE_TAG=${LITELLM_RELEASE_TAG} \
     PATH="/app/.venv/bin:${PATH}" \
     PYTHONDONTWRITEBYTECODE=1
 WORKDIR /app
 COPY --from=builder /app/.venv /app/.venv
 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 litellm/proxy/lens/release.py /app/lens/
+COPY litellm/proxy/lens/context_pipeline.py litellm/proxy/lens/agent_review.py litellm/proxy/lens/agent_runtime.py litellm/proxy/lens/agent_workspace.py litellm/proxy/lens/python_tool.py litellm/proxy/lens/activity.py litellm/proxy/lens/agent_context.py /app/lens/
+COPY litellm/proxy/lens/reviews.py litellm/proxy/lens/reconciliation.py /app/lens/
 COPY litellm/proxy/lens/prompts/ /app/lens/prompts/
+COPY --from=builder /app/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"]

deploy/lens/Dockerfile.dockerignore

@@ -2,14 +2,11 @@
 !deploy/
 !deploy/lens/
 !deploy/lens/requirements.lock
+!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/trace_store.py
-!litellm/proxy/lens/analysis.py
-!litellm/proxy/lens/worker.py
-!litellm/proxy/lens/release.py
+!litellm/proxy/lens/*.py
 !litellm/proxy/lens/prompts/
 !litellm/proxy/lens/prompts/**

deploy/lens/README.md

@@ -21,7 +21,7 @@ docker build --build-arg LITELLM_RELEASE_TAG="$LITELLM_RELEASE_TAG" \
 docker compose -f docker/docker-compose.tracing.yml up -d --build
 ```
 
-Open `http://localhost:4002/ui/` and sign in as `admin` with password `sk-1234`. Go to **Lens > Investigations > Connect worker**, choose a model and monthly budget, then **Get install command**. Expand **Using Docker Compose or Helm?** and copy the worker token. In the same terminal, run:
+Open `http://localhost:4002/ui/` and sign in as `admin` with the key saved in `.lens-dev/master_key`. Go to **Lens > Investigations > Connect worker**, choose a model and monthly budget, then **Get install command**. Expand **Using Docker Compose or Helm?** and copy the worker token. In the same terminal, run:
 
 ```bash
 export LITELLM_URL=http://litellm:4000
@@ -100,13 +100,13 @@ docker compose --env-file /path/to/lens.env -f compose.yaml up -d
 
 To work on Lens itself, `make lens-dev` runs the proxy, a worker from source and the hot-reload dashboard together; set `LENS_DEV_PROXY_PORT` / `LENS_DEV_UI_PORT` to move them off 4000/3000. For a local container build, set `LENS_WORKER_IMAGE=litellm-lens-worker:local` and `LITELLM_RELEASE_TAG` to the gateway's release tag, then use `docker compose -f deploy/lens/compose.yaml -f deploy/lens/compose.build.yaml up -d --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
+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. Python reports storage failures to the reviewer and cleans up temporary files, so the reviewer can retry a smaller computation or report insufficient evidence. The worker remains available for other scans. Existing workers must be recreated with the new image and mount options
 
-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
+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 up to three investigations concurrently and can serve multiple lenses. For more throughput, start another worker with a separate credential
 
 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
 
-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
+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
 
 ## Configure a lens
 
@@ -114,17 +114,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 two 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. 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
 
@@ -132,11 +132,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
 
@@ -144,9 +148,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
@@ -215,22 +225,21 @@ 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
-
-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
-
-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
-
-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
-
-
 ## Release compatibility
 
-Gateway and worker builds carry the same `LITELLM_RELEASE_TAG`. A worker announces its release and protocol before claiming an investigation. A mismatch returns HTTP 409 with the required image, leaving queued investigations untouched. During a rolling upgrade, workers wait for a gateway from their release
+Gateway and worker builds carry the same `LITELLM_RELEASE_TAG`. A worker announces its release and protocol before claiming an investigation. A mismatch returns HTTP 409 with the required image, leaving queued investigations untouched
+
+PostgreSQL stores complete review checkpoints in `LiteLLM_LensReview`, alongside Lens records and run history. Schema migrations preserve saved investigations, findings, history, worker credentials and billing assignments without rewriting stored Lens records
+
+Drain active scans, stop workers, back up the database, and deploy all gateway replicas as a coordinated replacement or traffic cutover. Keep traffic paused until every gateway replica uses the selected build and its migrations have completed. Mixed gateway versions sharing Lens data are not supported because every replica must understand the stored records. Pausing workers alone does not prevent dashboard or API writes. Recreate workers with the matching image and their existing tokens, then resume traffic and schedules. Scanning waits until a compatible worker connects
+
+Use the shipped migration history for databases containing Lens data. The schema guard stops `--use_prisma_db_push` before changes if it detects Lens tables that require renaming; run the shipped rename migration against the configured schema before retrying. Fresh databases and databases with the current table names can use database push
+
+A rollback to a gateway that cannot read saved Lens records requires restoring a compatible database backup. Database push from such a build can also remove the review table. Test recovery on a separate database and account for all gateway data written after the backup
 
 The dashboard reads its image from the running gateway. `LENS_WORKER_IMAGE` overrides the registry/image for private deployments. Set an explicit `LENS_WORKER_IMAGE` for worker-only Compose. Verify that the image exists and matches the gateway before deploying it
 
@@ -242,3 +251,42 @@ The hourly development pipeline pins all component images to the same selected c
 ## Worker dependencies
 
 The worker uses the same digest-pinned Wolfi base and Python version as the component images. Python dependencies and their hashes are locked in `deploy/lens/requirements.lock`. To update them, edit `deploy/lens/requirements.in`, then run `uv pip compile --universal --python-version 3.13 --generate-hashes --no-emit-index-url deploy/lens/requirements.in -o deploy/lens/requirements.lock`. The image installs only the locked wheels with hash verification. CI builds and scans both native architectures
+
+## 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. Set `LENS_PYTHON_CONCURRENCY` to a positive integer to change this worker-wide pool. 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 | 8 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 --build-arg LITELLM_RELEASE_TAG=lens-python-test \
+  -f deploy/lens/Dockerfile -t lens-worker:python-test .
+docker run --rm --pull never --read-only --cap-drop ALL \
+  --security-opt no-new-privileges --network none \
+  --tmpfs /tmp:rw,noexec,nosuid,size=1g --entrypoint python -i \
+  lens-worker:python-test - < tests/proxy_behavior/lens/worker_python_smoke.py
+```
+
+The same checks can run through pytest by setting `LENS_TEST_WORKER_IMAGE` to an already-built native image. The worker image CI runs the standalone smoke without adding pytest to the production image

deploy/lens/compose.yaml

@@ -4,6 +4,7 @@ services:
     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_PYTHON_CONCURRENCY: ${LENS_PYTHON_CONCURRENCY:-2}
     restart: unless-stopped
     read_only: true
     tmpfs:

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/stack.yaml

@@ -40,6 +40,7 @@ services:
     environment:
       LITELLM_URL: http://litellm:4000
       LENS_WORKER_TOKEN: ${LENS_WORKER_TOKEN:-}
+      LENS_PYTHON_CONCURRENCY: ${LENS_PYTHON_CONCURRENCY:-2}
     depends_on: [litellm]
     networks: [proxy]
     restart: unless-stopped

docker/Dockerfile.database

@@ -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
 
@@ -77,6 +77,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 \
@@ -99,6 +100,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 \

docker/Dockerfile.non_root

@@ -7,8 +7,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
 
@@ -81,6 +81,7 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
     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 \
@@ -108,6 +109,7 @@ RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \
     uv sync --frozen --no-default-groups --no-editable \
       --extra proxy \
       --extra proxy-runtime \
+      --group admin-mcp \
       --extra extra_proxy \
       --extra semantic-router \
       --extra saml \

docker/README.md

@@ -70,6 +70,32 @@ To stop the running containers, use the following command:
 docker compose down
 ```
 
+## Embedded LiteAdmin MCP
+
+Source builds containing embedded LiteAdmin MCP can serve it at `/admin/mcp` on the existing LiteLLM port. This capability is unreleased. Keep your existing database, master key, and proxy configuration, then add these settings to the serving container's environment:
+
+```bash
+LITELLM_ENABLE_ADMIN_MCP=true
+LITELLM_LICENSE="your-enterprise-license"
+PROXY_BASE_URL=https://gateway.example.com
+```
+
+For the unified source deployment described above, put them in its `.env` file and rebuild:
+
+```bash
+docker compose up -d --build
+```
+
+In componentized deployments, set the flag and license on the backend container and route `/admin/mcp` to the backend service. The gateway component excludes this endpoint. The unified, database, non-root, and backend image builds bundle the connector
+
+Hosting is disabled by default. Opting in requires a valid base Enterprise license; an unlicensed opt-in or invalid flag value prevents startup. Enabling it reserves `/admin`, so rename any MCP server alias called `admin` first
+
+With native key authentication, connect with a personal proxy-admin bearer key. When `enable_oauth2_proxy_auth` is enabled, the existing trusted-proxy identity headers select the user instead; the MCP bearer is required by the connector but does not select the native user. The resolved user must have the stored `proxy_admin` role, and `trusted_proxy_ranges` applies to the original caller's direct peer
+
+Embedded responses default to `full`; selecting `LITELLM_ADMIN_RESPONSE_VIEW=compact` requires subsequent saved-result reads to reach the same worker process, including within a multi-worker pod
+
+See the [LiteAdmin MCP guide](https://docs.litellm.ai/docs/proxy/liteadmin_mcp#run-liteadmin-mcp-inside-litellm) for client configuration, tool restrictions, and verification
+
 ## Hardened / Offline Testing
 
 To ensure changes are safe for non-root, read-only root filesystems and restricted egress, always validate with the hardened compose file:

docker/component_entrypoint.sh

@@ -3,7 +3,7 @@
 # stale samples from a previous container incarnation would be summed into the aggregate
 if [ -n "$PROMETHEUS_MULTIPROC_DIR" ]; then
     mkdir -p "$PROMETHEUS_MULTIPROC_DIR"
-    rm -f "$PROMETHEUS_MULTIPROC_DIR"/*.db
+    rm -f "$PROMETHEUS_MULTIPROC_DIR"/*.db "$PROMETHEUS_MULTIPROC_DIR"/litellm_admitted_series_*
 fi
 
 case "$USE_DDTRACE" in

docker/docker-compose.tracing.yml

@@ -9,8 +9,7 @@ services:
         LITELLM_RELEASE_TAG: ${LITELLM_RELEASE_TAG:-}
     command: ["--config", "/app/tracing-config.yaml", "--port", "4000"]
     environment:
-      LITELLM_MASTER_KEY: sk-1234
-      LITELLM_DANGEROUSLY_PERMIT_WEAK_OR_UNSET_MASTER_KEY: "true"
+      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?set LITELLM_MASTER_KEY}
       LITELLM_SALT_KEY: sk-local-tracing-salt-key
       DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm
       STORE_MODEL_IN_DB: "True"

enterprise/enterprise_hooks/__init__.py

@@ -1,15 +1,15 @@
 from typing import Dict, Literal, Type, Union
 
-from litellm_enterprise.proxy.hooks.managed_files import _PROXY_LiteLLMManagedFiles
+from litellm_enterprise.proxy.hooks.managed_files import PROXY_LiteLLMManagedFiles
 from litellm_enterprise.proxy.hooks.managed_vector_stores import (
-    _PROXY_LiteLLMManagedVectorStores,
+    PROXY_LiteLLMManagedVectorStores,
 )
 
 from litellm.integrations.custom_logger import CustomLogger
 
 ENTERPRISE_PROXY_HOOKS: Dict[str, Type[CustomLogger]] = {
-    "managed_files": _PROXY_LiteLLMManagedFiles,
-    "managed_vector_stores": _PROXY_LiteLLMManagedVectorStores,
+    "managed_files": PROXY_LiteLLMManagedFiles,
+    "managed_vector_stores": PROXY_LiteLLMManagedVectorStores,
 }
 
 

enterprise/enterprise_hooks/banned_keywords.py

@@ -20,7 +20,7 @@ from litellm._logging import verbose_proxy_logger
 from fastapi import HTTPException
 
 
-class _ENTERPRISE_BannedKeywords(CustomLogger):
+class ENTERPRISE_BannedKeywords(CustomLogger):
     enforces_request_content: bool = True
     # Class variables or attributes
     def __init__(self):
@@ -114,3 +114,4 @@ class _ENTERPRISE_BannedKeywords(CustomLogger):
         response: str,
     ):
         self.test_violation(test_str=response)
+_ENTERPRISE_BannedKeywords = ENTERPRISE_BannedKeywords

enterprise/enterprise_hooks/blocked_user_list.py

@@ -21,7 +21,7 @@ from litellm.proxy.common_utils.user_api_key_cache import AUTH_OBJECTS_TARGET
 from litellm.proxy.utils import PrismaClient
 
 
-class _ENTERPRISE_BlockedUserList(CustomLogger):
+class ENTERPRISE_BlockedUserList(CustomLogger):
     enforces_request_content: bool = True
     # Class variables or attributes
     def __init__(self, prisma_client: Optional[PrismaClient]):
@@ -128,3 +128,4 @@ class _ENTERPRISE_BlockedUserList(CustomLogger):
                     str(e)
                 )
             )
+_ENTERPRISE_BlockedUserList = ENTERPRISE_BlockedUserList

enterprise/enterprise_hooks/google_text_moderation.py

@@ -16,7 +16,7 @@ from litellm.proxy.guardrails._content_utils import iter_message_text
 from litellm.types.utils import CallTypesLiteral
 
 
-class _ENTERPRISE_GoogleTextModeration(CustomLogger):
+class ENTERPRISE_GoogleTextModeration(CustomLogger):
     user_api_key_cache = None
     confidence_categories = [
         "toxic",
@@ -125,9 +125,10 @@ class _ENTERPRISE_GoogleTextModeration(CustomLogger):
                     )
             # Handle the response
             return data
+_ENTERPRISE_GoogleTextModeration = ENTERPRISE_GoogleTextModeration
 
 
-# google_text_moderation_obj = _ENTERPRISE_GoogleTextModeration()
+# google_text_moderation_obj = ENTERPRISE_GoogleTextModeration()
 # asyncio.run(
 #     google_text_moderation_obj.async_moderation_hook(
 #         data={"messages": [{"role": "user", "content": "Hey, how's it going?"}]}

enterprise/enterprise_hooks/openai_moderation.py

@@ -24,7 +24,7 @@ from litellm.proxy.guardrails._content_utils import iter_message_text
 from litellm.types.utils import CallTypesLiteral
 
 
-class _ENTERPRISE_OpenAI_Moderation(CustomLogger):
+class ENTERPRISE_OpenAI_Moderation(CustomLogger):
     @property
     def model_name(self) -> str:
         return litellm.openai_moderations_model_name or DEFAULT_OPENAI_MODERATIONS_MODEL
@@ -55,3 +55,4 @@ class _ENTERPRISE_OpenAI_Moderation(CustomLogger):
                 status_code=403, detail={"error": "Violated content safety policy"}
             )
         pass
+_ENTERPRISE_OpenAI_Moderation = ENTERPRISE_OpenAI_Moderation

enterprise/litellm_enterprise/enterprise_callbacks/callback_controls.py

@@ -7,7 +7,6 @@ from litellm.integrations.custom_logger import CustomLogger
 from litellm.litellm_core_utils.llm_request_utils import (
     get_proxy_server_request_headers,
 )
-from litellm.proxy._types import CommonProxyErrors
 from litellm.types.utils import StandardCallbackDynamicParams
 
 
@@ -86,6 +85,7 @@ class EnterpriseCallbackControls:
     @staticmethod
     def _should_allow_dynamic_callback_disabling():
         import litellm
+        from litellm.proxy._types import CommonProxyErrors
         from litellm.proxy.proxy_server import premium_user
 
         # Check if admin has disabled this feature

enterprise/litellm_enterprise/enterprise_callbacks/send_emails/base_email.py

@@ -46,6 +46,8 @@ from litellm.proxy._types import (
     UserAPIKeyAuth,
     WebhookEvent,
 )
+from litellm.repositories.table_repositories import InvitationLinkRepository
+from litellm.repositories.user_repository import UserRepository
 from litellm.secret_managers.main import get_secret_bool
 from litellm.types.integrations.slack_alerting import LITELLM_LOGO_URL
 
@@ -844,7 +846,7 @@ class BaseEmailLogger(CustomLogger):
             )
             return None
 
-        user_row = await prisma_client.db.litellm_usertable.find_unique(
+        user_row = await UserRepository(prisma_client).table.find_unique(
             where={"user_id": user_id}
         )
 
@@ -929,7 +931,7 @@ class BaseEmailLogger(CustomLogger):
         try:
             # Try to get existing invitation
             existing_invitations = (
-                await prisma_client.db.litellm_invitationlink.find_many(
+                await InvitationLinkRepository(prisma_client).table.find_many(
                     where={"user_id": user_id},
                     order={"created_at": "desc"},
                 )

enterprise/litellm_enterprise/enterprise_callbacks/send_emails/endpoints.py

@@ -3,9 +3,10 @@ Endpoints for managing email alerts on litellm
 """
 
 import json
-from typing import Dict
+from typing import Dict, Final, cast
 
 from fastapi import APIRouter, Depends, HTTPException
+from pydantic import JsonValue
 from litellm_enterprise.types.enterprise_callbacks.send_emails import (
     DefaultEmailSettings,
     EmailEvent,
@@ -38,14 +39,15 @@ async def _get_email_settings(prisma_client) -> Dict[str, bool]:
             and general_settings_entry.param_value is not None
         ):
             # Get general settings value
-            if isinstance(general_settings_entry.param_value, str):
-                general_settings = json.loads(general_settings_entry.param_value)
-            else:
-                general_settings = general_settings_entry.param_value
+            general_settings: Final = (
+                cast(Dict[str, object], json.loads(general_settings_entry.param_value))
+                if isinstance(general_settings_entry.param_value, str)
+                else cast(Dict[str, object], general_settings_entry.param_value)
+            )
 
             # Extract email_settings from general settings if it exists
             if general_settings and "email_settings" in general_settings:
-                email_settings = general_settings["email_settings"]
+                email_settings: Final = cast(Dict[str, bool], general_settings["email_settings"])
                 # Update settings_dict with values from general_settings
                 for event_name, enabled in email_settings.items():
                     settings_dict[event_name] = enabled
@@ -64,7 +66,7 @@ async def _save_email_settings(prisma_client, settings: Dict[str, bool]):
     from litellm.proxy.proxy_server import proxy_config
 
     proxy_config.reject_config_owned_writes(
-        section_name="general_settings", changed_keys={"email_settings": settings}
+        section_name="general_settings", changed_keys={"email_settings": cast(JsonValue, settings)}
     )
     try:
         verbose_proxy_logger.debug(
@@ -77,16 +79,15 @@ async def _save_email_settings(prisma_client, settings: Dict[str, bool]):
         )
 
         # Initialize general settings dict
-        if (
-            general_settings_entry is not None
-            and general_settings_entry.param_value is not None
-        ):
-            if isinstance(general_settings_entry.param_value, str):
-                general_settings = json.loads(general_settings_entry.param_value)
-            else:
-                general_settings = dict(general_settings_entry.param_value)
-        else:
-            general_settings = {}
+        general_settings: Final = (
+            (
+                cast(Dict[str, object], json.loads(general_settings_entry.param_value))
+                if isinstance(general_settings_entry.param_value, str)
+                else cast(Dict[str, object], dict(general_settings_entry.param_value))
+            )
+            if general_settings_entry is not None and general_settings_entry.param_value is not None
+            else {}
+        )
 
         # Update email_settings in general_settings
         general_settings["email_settings"] = settings

enterprise/litellm_enterprise/integrations/custom_guardrail.py

@@ -36,7 +36,7 @@ class EnterpriseCustomGuardrailHelper:
 
         proxy_server_request = data.get("proxy_server_request", {})
 
-        request_tags = StandardLoggingPayloadSetup._get_request_tags(
+        request_tags = StandardLoggingPayloadSetup.get_request_tags(
             litellm_params=data,
             proxy_server_request=proxy_server_request,
         )

enterprise/litellm_enterprise/proxy/common_utils/check_batch_cost.py

@@ -15,6 +15,10 @@ from litellm.constants import (
     MANAGED_OBJECT_STALENESS_CUTOFF_DAYS,
     MAX_OBJECTS_PER_POLL_CYCLE,
 )
+from litellm.repositories.table_repositories import ManagedObjectRepository
+from litellm.repositories.team_repository import TeamRepository
+from litellm.repositories.user_repository import UserRepository
+from litellm.repositories.verification_token_repository import VerificationTokenRepository
 
 if TYPE_CHECKING:
     from prisma import models as prisma_models
@@ -56,27 +60,47 @@ class _ManagedObjectRow(Protocol):
     @property
     def file_object(self) -> object: ...
 
+    @property
+    def org_id(self) -> str | None: ...
+
+    @property
+    def api_key(self) -> str | None: ...
+
+    @property
+    def team_id(self) -> str | None: ...
+
+
+class _ReadableFileContent(Protocol):
+    async def read(self) -> bytes: ...
+
+
+class _HasFileContent(Protocol):
+    @property
+    def content(self) -> bytes: ...
+
+
+async def _file_content_bytes(file_content: object) -> bytes:
+    if hasattr(file_content, "content"):
+        return cast(_HasFileContent, file_content).content
+    if hasattr(file_content, "read"):
+        return await cast(_ReadableFileContent, file_content).read()
+    return cast(bytes, file_content)
+
 
 def _managed_object_table(prisma_client: "PrismaClient") -> "TableActions[_ManagedObjectRow]":
-    table: Final[TableActions[_ManagedObjectRow]] = prisma_client.db.litellm_managedobjecttable
-    return table
+    return ManagedObjectRepository(prisma_client).table
 
 
 def _user_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_UserTable]":
-    table: Final[TableActions[prisma_models.LiteLLM_UserTable]] = prisma_client.db.litellm_usertable
-    return table
+    return UserRepository(prisma_client).table
 
 
 def _token_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_VerificationToken]":
-    table: Final[TableActions[prisma_models.LiteLLM_VerificationToken]] = (
-        prisma_client.db.litellm_verificationtoken
-    )
-    return table
+    return VerificationTokenRepository(prisma_client).table
 
 
 def _team_table(prisma_client: "PrismaClient") -> "TableActions[prisma_models.LiteLLM_TeamTable]":
-    table: Final[TableActions[prisma_models.LiteLLM_TeamTable]] = prisma_client.db.litellm_teamtable
-    return table
+    return TeamRepository(prisma_client).table
 
 
 class CheckBatchCost:
@@ -177,17 +201,21 @@ class CheckBatchCost:
             return None
 
     async def _get_org_id(self, job: "_ManagedObjectRow", batch_id: str) -> str | None:
-        org_id = getattr(job, "org_id", None)
+        org_id: Final = getattr(job, "org_id", None)
         if org_id:
             return org_id
-        api_key = getattr(job, "api_key", None)
-        team_id = getattr(job, "team_id", None)
+        api_key: Final = getattr(job, "api_key", None)
+        team_id: Final = getattr(job, "team_id", None)
         if api_key:
             try:
                 key_row: prisma_models.LiteLLM_VerificationToken | None = await _token_table(
                     self.prisma_client
                 ).find_unique(where={"token": api_key})
-                key_org_id = getattr(key_row, "organization_id", None) if key_row is not None else None
+                key_org_id: Final = (
+                    cast(str | None, getattr(key_row, "organization_id", None))
+                    if key_row is not None
+                    else None
+                )
                 if key_org_id:
                     return key_org_id
             except Exception as e:
@@ -201,7 +229,7 @@ class CheckBatchCost:
             team_row: prisma_models.LiteLLM_TeamTable | None = await _team_table(self.prisma_client).find_unique(
                 where={"team_id": team_id}
             )
-            return getattr(team_row, "organization_id", None) if team_row is not None else None
+            return cast(str | None, getattr(team_row, "organization_id", None)) if team_row is not None else None
         except Exception as e:
             verbose_proxy_logger.error(f"CheckBatchCost: could not resolve the team's org for batch {batch_id}: {e}")
             return None
@@ -675,16 +703,17 @@ class CheckBatchCost:
 
         from litellm.types.utils import LiteLLMBatch
 
-        file_object = job.file_object
-        if isinstance(file_object, str):
-            try:
-                file_object = json.loads(file_object)
-            except (json.JSONDecodeError, ValueError):
-                return None
-        if not isinstance(file_object, dict):
+        file_object: Final = job.file_object
+        try:
+            parsed_file_object: Final[object] = (
+                json.loads(file_object) if isinstance(file_object, str) else file_object
+            )
+        except (json.JSONDecodeError, ValueError):
+            return None
+        if not isinstance(parsed_file_object, dict):
             return None
         try:
-            return LiteLLMBatch.model_validate(file_object).input_file_id
+            return LiteLLMBatch.model_validate(parsed_file_object).input_file_id
         except Exception:
             return None
 
@@ -706,10 +735,11 @@ class CheckBatchCost:
         """
         from litellm.batches.batch_utils import (
             count_error_file_failed_requests,
-            _get_file_content_as_dictionary,
+            get_file_content_as_dictionary,
             calculate_batch_cost_and_usage,
         )
         from litellm.files.main import afile_content
+        from litellm.files.types import FileContentCallOptions
         from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider
         from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLogging
         from litellm.litellm_core_utils.litellm_logging import deployment_pricing_model_info, mask_api_base_credentials
@@ -747,30 +777,22 @@ class CheckBatchCost:
             except (IndexError, AttributeError):
                 pass
 
-        credentials = self.llm_router.get_deployment_credentials_with_provider(model_id) or {}
+        credentials: Final = self.llm_router.get_deployment_credentials_with_provider(model_id) or {}
         _file_content = await afile_content(
-            file_id=raw_output_file_id,
+            file_id=cast(str, raw_output_file_id),
             _litellm_internal_model_credentials=MappingProxyType(dict(credentials)),
-            **credentials,
+            **cast(FileContentCallOptions, credentials),
         )
 
-        # Access content - handle both direct attribute and method call
-        if hasattr(_file_content, 'content'):
-            content_bytes = _file_content.content  # type: ignore[union-attr]
-        elif hasattr(_file_content, 'read'):
-            content_bytes = await _file_content.read()  # type: ignore[misc]
-        else:
-            content_bytes = _file_content  # type: ignore[assignment]
+        content_bytes: Final = await _file_content_bytes(_file_content)
 
-        file_content_as_dict = _get_file_content_as_dictionary(
-            content_bytes  # type: ignore[arg-type]
-        )
+        file_content_as_dict = get_file_content_as_dictionary(content_bytes)
 
         # Record output file size
         if prom_logger and content_bytes:
             try:
                 prom_logger.record_managed_file_size(
-                    size_bytes=len(content_bytes),  # type: ignore
+                    size_bytes=len(content_bytes),
                     purpose="batch",
                     file_type="output",
                     model=model_id,
@@ -807,7 +829,7 @@ class CheckBatchCost:
                 team_id=getattr(job, "team_id", None),
             )
             for _file_attr in ["output_file_id", "error_file_id"]:
-                _raw_file_id = getattr(response, _file_attr, None)
+                _raw_file_id = cast(str | None, getattr(response, _file_attr, None))
                 if _raw_file_id and not _is_base64_encoded_unified_file_id(_raw_file_id):
                     try:
                         _unified_file_id = managed_files_hook.get_unified_output_file_id(

enterprise/litellm_enterprise/proxy/common_utils/check_responses_cost.py

@@ -16,6 +16,7 @@ from litellm.constants import (
     MAX_OBJECTS_PER_POLL_CYCLE,
     STALE_OBJECT_CLEANUP_BATCH_SIZE,
 )
+from litellm.repositories.table_repositories import ManagedObjectRepository
 from litellm.responses.utils import ResponsesAPIRequestUtils
 from litellm.types.llms.openai import ResponsesAPIResponse
 from litellm.types.utils import BACKGROUND_RESPONSE_COST_POLL_CALL_ORIGIN
@@ -43,8 +44,7 @@ class _ManagedObjectRow(Protocol):
 
 
 def _managed_object_table(prisma_client: "PrismaClient") -> "TableActions[_ManagedObjectRow]":
-    table: Final[TableActions[_ManagedObjectRow]] = prisma_client.db.litellm_managedobjecttable
-    return table
+    return ManagedObjectRepository(prisma_client).table
 
 
 class CheckResponsesCost:

enterprise/litellm_enterprise/proxy/enterprise_routes.py

@@ -8,7 +8,7 @@ from . import ui_crud_endpoints  # side-effect: registers extra UI settings
 from .audit_logging_endpoints import router as audit_logging_router
 from .liteadmin import router as liteadmin_router
 from .management_endpoints import management_endpoints_router
-from .utils import _should_block_robots
+from .utils import should_block_robots
 
 __all__ = ["router", "ui_crud_endpoints"]
 
@@ -25,7 +25,7 @@ async def get_robots():
     Block all web crawlers from indexing the proxy server endpoints
     This is useful for ensuring that the API endpoints aren't indexed by search engines
     """
-    if _should_block_robots():
+    if should_block_robots():
         return Response(content="User-agent: *\nDisallow: /", media_type="text/plain")
     else:
         return Response(status_code=404)

enterprise/litellm_enterprise/proxy/hooks/managed_files.py

@@ -23,6 +23,7 @@ from uuid import NAMESPACE_URL, uuid5
 import httpx
 from fastapi import HTTPException
 from pydantic import ValidationError
+from typing_extensions import ReadOnly
 
 import litellm
 from litellm import Router, verbose_logger
@@ -30,10 +31,13 @@ from litellm._internal_context import with_service_target
 from litellm._uuid import uuid
 from litellm.caching.caching import DualCache
 from litellm.constants import MAX_FILE_LIST_LIMIT
+from litellm.files.types import FileRetrieveCallOptions, FileRetrieveProvider
 from litellm.integrations.custom_logger import CustomLogger
+from litellm.litellm_core_utils.hidden_params import HIDDEN_PARAMS_ATTR
 from litellm.litellm_core_utils.prompt_templates.common_utils import (
     extract_file_metadata,
 )
+from openai import AsyncOpenAI
 from openai.types.file_deleted import FileDeleted
 
 from litellm.llms.base_llm.files.storage_backend_factory import get_storage_backend
@@ -190,6 +194,19 @@ class _ManagedObjectTableActions(Protocol):
     async def update_many(self, where: Mapping[str, object], data: Mapping[str, object]) -> int: ...
 
 
+class _ManagedResourceDatabase(Protocol):
+    @property
+    def litellm_managedfiletable(self) -> _ManagedFileTableActions: ...
+
+    @property
+    def litellm_managedobjecttable(self) -> _ManagedObjectTableActions: ...
+
+
+class _ManagedResourcePrismaClient(Protocol):
+    @property
+    def db(self) -> _ManagedResourceDatabase: ...
+
+
 class _SchedulerWithJobLookup(Protocol):
     def get_job(self, job_id: str) -> object: ...
 
@@ -199,7 +216,12 @@ class _CursorPageArgs(TypedDict, total=False):
     skip: int
 
 
-def _managed_file_table(prisma_client: PrismaClient) -> _ManagedFileTableActions:
+class _RouterFileCallKwargs(TypedDict, total=False):
+    client: ReadOnly[AsyncOpenAI | None]
+    custom_llm_provider: ReadOnly[str | None]
+
+
+def _managed_file_table(prisma_client: _ManagedResourcePrismaClient) -> _ManagedFileTableActions:
     return prisma_client.db.litellm_managedfiletable
 
 
@@ -213,7 +235,7 @@ def _iter_provider_file_id_pairs(
                 yield provider_file_id, row.unified_file_id
 
 
-def _managed_object_table(prisma_client: PrismaClient) -> _ManagedObjectTableActions:
+def _managed_object_table(prisma_client: _ManagedResourcePrismaClient) -> _ManagedObjectTableActions:
     return prisma_client.db.litellm_managedobjecttable
 
 
@@ -233,7 +255,7 @@ def _storage_metadata_of(file_object: OpenAIFileObject | None) -> Mapping[str, s
 _MANAGED_FILES_TARGET: Final = "managed_files"
 
 
-class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
+class PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
     # Class variables or attributes
     def __init__(self, internal_usage_cache: InternalUsageCache, prisma_client: PrismaClient):
         self.internal_usage_cache = internal_usage_cache
@@ -1282,7 +1304,7 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
             target_model_names_list=target_model_names_list,
             litellm_parent_otel_span=litellm_parent_otel_span,
         )
-        response = await _PROXY_LiteLLMManagedFiles.return_unified_file_id(
+        response = await PROXY_LiteLLMManagedFiles.return_unified_file_id(
             file_objects=responses,
             create_file_request=create_file_request,
             internal_usage_cache=self.internal_usage_cache,
@@ -1294,7 +1316,10 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
         model_mappings: Dict[str, str] = {}
 
         for file_object in responses:
-            model_file_id_mapping = file_object._hidden_params.get("model_file_id_mapping")
+            file_hidden_params = cast(  # cast-ok: preserve mapping operations on dynamic file metadata
+                dict[str, object], getattr(file_object, HIDDEN_PARAMS_ATTR)
+            )
+            model_file_id_mapping = file_hidden_params.get("model_file_id_mapping")
             if model_file_id_mapping and isinstance(model_file_id_mapping, dict):
                 model_mappings.update(model_file_id_mapping)
 
@@ -1344,7 +1369,8 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
         _, file_type = extract_file_metadata(create_file_request["file"])
 
         output_file_id = file_objects[0].id
-        model_id = file_objects[0]._hidden_params.get("model_id")
+        file_hidden_params: Final = cast(dict[str, object], getattr(file_objects[0], HIDDEN_PARAMS_ATTR))
+        model_id = file_hidden_params.get("model_id")
 
         unified_file_id = SpecialEnums.LITELLM_MANAGED_FILE_COMPLETE_STR.value.format(
             file_type,
@@ -1410,11 +1436,12 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
             if decoded_batch_id and is_litellm_executed_batch(decoded_batch_id):
                 return response
             ## Check if unified_file_id is in the response
-            unified_file_id = response._hidden_params.get("unified_file_id")  # managed file id
-            unified_batch_id = response._hidden_params.get("unified_batch_id")  # managed batch id
-            is_batch_create: Final = response._hidden_params.get(BATCH_CREATE_HIDDEN_PARAM) is True
-            model_id = cast(Optional[str], response._hidden_params.get("model_id"))
-            model_name = cast(Optional[str], response._hidden_params.get("model_name"))
+            response_hidden_params: Final = cast(dict[str, object], getattr(response, HIDDEN_PARAMS_ATTR))
+            unified_file_id = response_hidden_params.get("unified_file_id")
+            unified_batch_id = response_hidden_params.get("unified_batch_id")
+            is_batch_create: Final = response_hidden_params.get(BATCH_CREATE_HIDDEN_PARAM) is True
+            model_id = cast(Optional[str], response_hidden_params.get("model_id"))
+            model_name = cast(Optional[str], response_hidden_params.get("model_name"))
 
             resolved_model_name = resolve_managed_output_file_model_name(
                 unified_input_file_id=unified_file_id if isinstance(unified_file_id, str) else response.input_file_id,
@@ -1459,13 +1486,14 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
                                 _creds = _llm_router.get_deployment_credentials_with_provider(model_id) or {}
                                 file_object = await litellm.afile_retrieve(
                                     file_id=provider_file_id,
-                                    **_creds,
+                                    **cast(FileRetrieveCallOptions, _creds),
                                 )
                             else:
                                 file_object = await litellm.afile_retrieve(
-                                    custom_llm_provider=model_name.split("/")[0]
-                                    if model_name and "/" in model_name
-                                    else "openai",  # type: ignore[arg-type]
+                                    custom_llm_provider=cast(
+                                        FileRetrieveProvider,
+                                        model_name.split("/")[0] if model_name and "/" in model_name else "openai",
+                                    ),
                                     file_id=provider_file_id,
                                 )
                             verbose_logger.debug(
@@ -1525,12 +1553,12 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
 
         elif isinstance(response, LiteLLMFineTuningJob):
             ## Check if unified_file_id is in the response
-            unified_file_id = response._hidden_params.get("unified_file_id")  # managed file id
-            unified_finetuning_job_id = response._hidden_params.get(
-                "unified_finetuning_job_id"
-            )  # managed finetuning job id
-            model_id = cast(Optional[str], response._hidden_params.get("model_id"))
-            model_name = cast(Optional[str], response._hidden_params.get("model_name"))
+            finetuning_response_hidden_params: Final = cast(  # cast-ok: preserve dynamic mapping behavior
+                dict[str, object], getattr(response, HIDDEN_PARAMS_ATTR)
+            )
+            unified_file_id = finetuning_response_hidden_params.get("unified_file_id")
+            unified_finetuning_job_id = finetuning_response_hidden_params.get("unified_finetuning_job_id")
+            model_id = cast(Optional[str], finetuning_response_hidden_params.get("model_id"))
             original_response_id = response.id
             if (unified_file_id or unified_finetuning_job_id) and model_id:
                 response.id = self.get_unified_generic_response_id(model_id=model_id, generic_response_id=response.id)
@@ -1608,8 +1636,11 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
 
         try:
             model_id, model_file_id = next(iter(stored_file_object.model_mappings.items()))
-            credentials = llm_router.get_deployment_credentials_with_provider(model_id) or {}
-            response = await litellm.afile_retrieve(file_id=model_file_id, **credentials)
+            credentials: Final = llm_router.get_deployment_credentials_with_provider(model_id) or {}
+            response = await litellm.afile_retrieve(
+                file_id=model_file_id,
+                **cast(FileRetrieveCallOptions, credentials),
+            )
             response.id = file_id  # Replace with unified ID
             return response
         except Exception as e:
@@ -1647,7 +1678,7 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
 
         owner_filter: Final = build_owner_filter(user_api_key_dict)
         if owner_filter is None:
-            return FileListPage(**build_list_page([]))
+            return FileListPage.model_validate(build_list_page([]))
 
         if after:
             cursor_row = await _managed_file_table(self.prisma_client).find_first(
@@ -1686,7 +1717,7 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
             cursor_id = chunk[-1].unified_file_id
             chunk_size = max(chunk_size, FILE_LIST_CONTINUATION_CHUNK_SIZE)
 
-        return FileListPage(**build_list_page(matches[:page_size], has_more=len(matches) > page_size))
+        return FileListPage.model_validate(build_list_page(matches[:page_size], has_more=len(matches) > page_size))
 
     def _is_batch_polling_enabled(self) -> bool:
         """
@@ -1904,7 +1935,11 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
                     else {}
                 ),
             }
-            await llm_router.afile_delete(model=model_id, file_id=model_file_id, **delete_data)
+            await llm_router.afile_delete(
+                model=model_id,
+                file_id=model_file_id,
+                **cast(_RouterFileCallKwargs, delete_data),
+            )
 
     async def afile_content(
         self,
@@ -1940,7 +1975,14 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
                         data["_litellm_internal_model_credentials"] = cast(Dict, MappingProxyType(dict(credentials)))
                     else:
                         data.pop("_litellm_internal_model_credentials", None)
-                    return await llm_router.afile_content(model=model_id, file_id=provider_file_id, **data)  # type: ignore
+                    return cast(
+                        HttpxBinaryResponseContent,
+                        await llm_router.afile_content(
+                            model=model_id,
+                            file_id=provider_file_id,
+                            **cast(_RouterFileCallKwargs, data),
+                        ),
+                    )
                 except Exception as e:
                     exception_dict[model_id] = str(e)
             raise Exception(
@@ -2068,3 +2110,4 @@ class _PROXY_LiteLLMManagedFiles(CustomLogger, BaseFileEndpoints):
                                 verbose_logger.debug(
                                     f"Converted file {file_id} from storage backend to base64 with format {content_type}"
                                 )
+_PROXY_LiteLLMManagedFiles = PROXY_LiteLLMManagedFiles

enterprise/litellm_enterprise/proxy/hooks/managed_vector_stores.py

@@ -2,11 +2,11 @@
 ## This hook is used to manage vector stores with target_model_names support
 ## It allows creating vector stores across multiple models and managing them with unified IDs
 
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union, cast
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Dict, Final, List, Optional, Union, cast
 
 from fastapi import HTTPException
 
-import litellm
 from litellm import Router, verbose_logger
 from litellm._uuid import uuid
 from litellm.integrations.custom_logger import CustomLogger
@@ -38,7 +38,7 @@ else:
     PrismaClient = Any
 
 
-class _PROXY_LiteLLMManagedVectorStores(
+class PROXY_LiteLLMManagedVectorStores(
     CustomLogger, BaseManagedResource[VectorStoreCreateResponse]
 ):
     """
@@ -89,10 +89,10 @@ class _PROXY_LiteLLMManagedVectorStores(
         
         # Model ID is stored in hidden params if the response object supports it
         # For TypedDict responses, we need to check if _hidden_params was added
-        hidden_params: Dict[str, Any] = {}
+        hidden_params: Mapping[str, object] = {}
         if hasattr(resource_object, "_hidden_params"):
-            hidden_params = getattr(resource_object, "_hidden_params", {}) or {}
-        model_id = hidden_params.get("model_id", "")
+            hidden_params = cast(Mapping[str, object], getattr(resource_object, "_hidden_params", {}) or {})
+        model_id: Final = cast(str, hidden_params.get("model_id", ""))
 
         return generate_unified_id_string(
             resource_type=self.resource_type,
@@ -106,7 +106,7 @@ class _PROXY_LiteLLMManagedVectorStores(
         self,
         llm_router: Router,
         model: str,
-        request_data: Dict[str, Any],
+        request_data: dict[str, object] | VectorStoreCreateOptionalRequestParams,
         litellm_parent_otel_span: Span,
     ) -> VectorStoreCreateResponse:
         """
@@ -122,10 +122,8 @@ class _PROXY_LiteLLMManagedVectorStores(
             VectorStoreCreateResponse from the provider
         """
         # Use the router to create the vector store
-        response = await llm_router.avector_store_create(
-            model=model, **request_data
-        )
-        return response
+        response: Final = await llm_router.avector_store_create(model=model, **request_data)
+        return cast(VectorStoreCreateResponse, response)
 
     # ============================================================================
     #                     VECTOR STORE CRUD OPERATIONS
@@ -464,3 +462,4 @@ class _PROXY_LiteLLMManagedVectorStores(
             parent_otel_span=parent_otel_span,
             resource_id_key="vector_store_id",
         )
+_PROXY_LiteLLMManagedVectorStores = PROXY_LiteLLMManagedVectorStores

enterprise/litellm_enterprise/proxy/liteadmin.py

@@ -15,11 +15,12 @@ from urllib.parse import urlencode, urlsplit
 import httpx
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import HTMLResponse, RedirectResponse, Response
-from pydantic import BaseModel, ConfigDict, Field, SecretStr, TypeAdapter, ValidationError
+from pydantic import ConfigDict, Field, SecretStr, TypeAdapter, ValidationError
 
 from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
 from litellm.proxy._experimental.mcp_server.oauth_utils import get_request_base_url
 from litellm.proxy._types import LiteLLM_UserTable, LitellmUserRoles, UserAPIKeyAuth
+from litellm.types.llms.base import LiteLLMBaseModel
 from litellm.types.proxy.auth.auth_checks import UserNotFoundError
 
 router: Final = APIRouter()
@@ -34,14 +35,14 @@ _HEADERS: Final = {
 }
 
 
-class LinkDetails(BaseModel):
+class LinkDetails(LiteLLMBaseModel):
     model_config = ConfigDict(frozen=True, strict=True, extra="forbid")
     workspace_id: str = Field(min_length=1, max_length=64)
     slack_user_id: str = Field(min_length=1, max_length=64)
     email: str = Field(min_length=1, max_length=320)
 
 
-class AdminSession(BaseModel):
+class AdminSession(LiteLLMBaseModel):
     model_config = ConfigDict(frozen=True)
     user_id: str
     credential: SecretStr

enterprise/litellm_enterprise/proxy/management_endpoints/project_endpoints.py

@@ -22,7 +22,9 @@ from litellm._uuid import uuid
 from litellm.proxy._types import *
 from litellm.proxy.auth.auth_checks import delete_cached_project_object
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
-from litellm.proxy.management.teams.access import is_team_admin
+from litellm.proxy.management.teams.authz import TEAM_OR_ORG_ADMIN, TeamAccess, is_team_admin, is_team_member
+from litellm.proxy.management.teams.dependencies import get_team_access
+from litellm.proxy.management.users.service import org_admin_org_ids
 from litellm.proxy.management_endpoints.common_utils import _set_object_metadata_field
 from litellm.proxy.management_endpoints.team_admin_field_permissions import team_admin_may_manage_projects
 from litellm.proxy.management_helpers.utils import (
@@ -118,6 +120,37 @@ async def _check_user_permission_for_project(
     return is_team_admin(user_api_key_dict, team) or user_api_key_dict.user_id in (team.admins or [])
 
 
+async def _can_view_team_projects(
+    user_api_key_dict: UserAPIKeyAuth,
+    team_id: str | None,
+    prisma_client: PrismaClient,
+    team_access: TeamAccess,
+) -> bool:
+    if user_api_key_has_admin_view(user_api_key_dict):
+        return True
+    if not team_id or not user_api_key_dict.user_id:
+        return False
+    team_row: Final = await _team_table(prisma_client).find_unique(where={"team_id": team_id})
+    if team_row is None:
+        return False
+    team: Final = LiteLLM_TeamTable.model_validate(team_row.model_dump())
+    return is_team_member(user_api_key_dict, team) or await team_access.allows(
+        user_api_key_dict, team, TEAM_OR_ORG_ADMIN
+    )
+
+
+def _visible_projects_where(team_ids: list[str], admin_org_ids: frozenset[str]) -> dict[str, object]:
+    # bounded-ok: one caller's team memberships
+    member_scope: Final[dict[str, object]] = {"team_id": {"in": team_ids}}
+    if not admin_org_ids:
+        return member_scope
+    org_scope: Final[dict[str, object]] = {
+        # bounded-ok: orgs one caller administers
+        "litellm_team_table": {"is": {"organization_id": {"in": sorted(admin_org_ids)}}}
+    }
+    return {"OR": [member_scope, org_scope]}
+
+
 async def _validate_team_exists(
     team_id: str,
     prisma_client: PrismaClient,
@@ -433,7 +466,7 @@ async def new_project(
 
     ```bash
     curl --location 'http://0.0.0.0:4000/project/new' \\
-    --header 'Authorization: Bearer sk-1234' \\
+    --header "Authorization: Bearer $LITELLM_MASTER_KEY" \\
     --header 'Content-Type: application/json' \\
     --data '{
         "project_alias": "flight-search-assistant",
@@ -460,7 +493,7 @@ async def new_project(
 
     ```bash
     curl --location 'http://0.0.0.0:4000/project/new' \\
-    --header 'Authorization: Bearer sk-1234' \\
+    --header "Authorization: Bearer $LITELLM_MASTER_KEY" \\
     --header 'Content-Type: application/json' \\
     --data '{
         "project_alias": "hotel-recommendations",
@@ -648,7 +681,7 @@ async def update_project(
     Example:
     ```bash
     curl --location 'http://0.0.0.0:4000/project/update' \\
-    --header 'Authorization: Bearer sk-1234' \\
+    --header "Authorization: Bearer $LITELLM_MASTER_KEY" \\
     --header 'Content-Type: application/json' \\
     --data '{
         "project_id": "project-123",
@@ -876,7 +909,7 @@ async def delete_project(
     Example:
     ```bash
     curl --location --request DELETE 'http://0.0.0.0:4000/project/delete' \\
-    --header 'Authorization: Bearer sk-1234' \\
+    --header "Authorization: Bearer $LITELLM_MASTER_KEY" \\
     --header 'Content-Type: application/json' \\
     --data '{
         "project_ids": ["project-123", "project-456"]
@@ -973,6 +1006,7 @@ async def delete_project(
 async def project_info(
     project_id: str,
     user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
+    team_access: TeamAccess = Depends(get_team_access),
 ):
     """
     Get information about a specific project
@@ -983,7 +1017,7 @@ async def project_info(
     Example:
     ```bash
     curl --location 'http://0.0.0.0:4000/project/info?project_id=project-123' \\
-    --header 'Authorization: Bearer sk-1234'
+    --header "Authorization: Bearer $LITELLM_MASTER_KEY"
     ```
     """
     from litellm.proxy.proxy_server import prisma_client
@@ -1009,21 +1043,7 @@ async def project_info(
                 param="project_id",
             )
 
-        # Check if user has access to this project (admin or team member)
-        is_admin = user_api_key_has_admin_view(user_api_key_dict)
-        is_team_member = False
-
-        if project.team_id and user_api_key_dict.user_id:
-            team = await _team_table(prisma_client).find_unique(where={"team_id": project.team_id})
-            if team:
-                caller_user_id = user_api_key_dict.user_id
-                for m in team.members_with_roles or []:
-                    m_user_id = m.get("user_id") if isinstance(m, dict) else getattr(m, "user_id", None)
-                    if m_user_id == caller_user_id:
-                        is_team_member = True
-                        break
-
-        if not (is_admin or is_team_member):
+        if not await _can_view_team_projects(user_api_key_dict, project.team_id, prisma_client, team_access):
             raise HTTPException(
                 status_code=403,
                 detail={"error": "You don't have access to this project"},
@@ -1052,7 +1072,7 @@ async def list_projects(
     Example:
     ```bash
     curl --location 'http://0.0.0.0:4000/project/list' \\
-    --header 'Authorization: Bearer sk-1234'
+    --header "Authorization: Bearer $LITELLM_MASTER_KEY"
     ```
     """
     from litellm.proxy.proxy_server import prisma_client
@@ -1072,16 +1092,13 @@ async def list_projects(
                 include={"litellm_budget_table": True, "object_permission": True}
             )
         else:
-            # Look up the user's team memberships via the reverse-index on
-            # LiteLLM_UserTable.teams (maintained by team_member_add alongside
-            # members_with_roles). This avoids a full scan of all team rows.
             user_record: Final = await _user_table(prisma_client).find_unique(
                 where={"user_id": user_api_key_dict.user_id},
+                include={"organization_memberships": True},
             )
-            user_team_ids: list[str] = user_record.teams if user_record is not None and user_record.teams else []
-
+            user: Final = None if user_record is None else LiteLLM_UserTable.model_validate(user_record.model_dump())
             projects = await _project_table(prisma_client).find_many(
-                where={"team_id": {"in": user_team_ids}},
+                where=_visible_projects_where(user.teams if user is not None else [], org_admin_org_ids(user)),
                 include={"litellm_budget_table": True, "object_permission": True},
             )
 

enterprise/litellm_enterprise/proxy/proxy_server.py

@@ -9,7 +9,7 @@ custom_auth_settings: Optional[CustomAuthSettings] = None
 class EnterpriseProxyConfig:
     async def load_custom_auth_settings(
         self, general_settings: dict
-    ) -> CustomAuthSettings:
+    ) -> Optional[CustomAuthSettings]:
         custom_auth_settings = general_settings.get("custom_auth_settings", None)
         if custom_auth_settings is not None:
             custom_auth_settings = CustomAuthSettings(

enterprise/litellm_enterprise/proxy/utils.py

@@ -3,7 +3,7 @@ from typing import Optional, Union
 from litellm.secret_managers.main import str_to_bool
 
 
-def _should_block_robots():
+def should_block_robots():
     """
     Returns True if the robots.txt file should block web crawlers
 
@@ -33,3 +33,4 @@ def _should_block_robots():
             )
         return True
     return False
+_should_block_robots = should_block_robots

enterprise/litellm_enterprise/proxy/vector_stores/endpoints.py

@@ -171,7 +171,7 @@ async def list_vector_stores(
     try:
         # Get vector stores from database (source of truth)
         # Only return what's in the database to ensure consistency across instances
-        vector_stores_from_db = await VectorStoreRegistry._get_vector_stores_from_db(
+        vector_stores_from_db = await VectorStoreRegistry.get_vector_stores_from_db(
             prisma_client=prisma_client
         )
         

enterprise/litellm_enterprise/types/enterprise_callbacks/send_emails.py

@@ -1,12 +1,13 @@
 import enum
 from typing import Dict, List, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import Field
 
 from litellm.proxy._types import WebhookEvent
+from litellm.types.llms.base import LiteLLMBaseModel
 
 
-class EmailParams(BaseModel):
+class EmailParams(LiteLLMBaseModel):
     logo_url: str
     support_contact: str
     base_url: str
@@ -39,14 +40,14 @@ class EmailEvent(str, enum.Enum):
     soft_budget_crossed = "Soft Budget Crossed"
     max_budget_alert = "Max Budget Alert"
 
-class EmailEventSettings(BaseModel):
+class EmailEventSettings(LiteLLMBaseModel):
     event: EmailEvent
     enabled: bool
-class EmailEventSettingsUpdateRequest(BaseModel):
+class EmailEventSettingsUpdateRequest(LiteLLMBaseModel):
     settings: List[EmailEventSettings]
-class EmailEventSettingsResponse(BaseModel):
+class EmailEventSettingsResponse(LiteLLMBaseModel):
     settings: List[EmailEventSettings]
-class DefaultEmailSettings(BaseModel):
+class DefaultEmailSettings(LiteLLMBaseModel):
     """Default settings for email events"""
     settings: Dict[EmailEvent, bool] = Field(
         default_factory=lambda: {

enterprise/litellm_enterprise/types/proxy/audit_logging_endpoints.py

@@ -1,10 +1,12 @@
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import Field
+
+from litellm.types.llms.base import LiteLLMBaseModel
 
 
-class AuditLogResponse(BaseModel):
+class AuditLogResponse(LiteLLMBaseModel):
     """Response model for a single audit log entry"""
 
     id: str
@@ -18,7 +20,7 @@ class AuditLogResponse(BaseModel):
     updated_values: Optional[Dict[str, Any]] = None
 
 
-class PaginatedAuditLogResponse(BaseModel):
+class PaginatedAuditLogResponse(LiteLLMBaseModel):
     """Response model for paginated audit logs"""
 
     audit_logs: List[AuditLogResponse]

enterprise/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "litellm-enterprise"
-version = "0.1.73"
+version = "0.1.74"
 description = "Package for LiteLLM Enterprise features"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,7 +26,7 @@ required-version = ">=0.10.9"
 module-root = ""
 
 [tool.commitizen]
-version = "0.1.73"
+version = "0.1.74"
 version_files = [
     "pyproject.toml:^version",
     "../pyproject.toml:litellm-enterprise==",

gateway/Dockerfile

@@ -2,8 +2,8 @@ ARG LITELLM_BUILD_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:1d95114038f76513a9a
 ARG LITELLM_RUNTIME_IMAGE=cgr.dev/chainguard/wolfi-base@sha256:1d95114038f76513a9ace6fca107d5582b08c65981f81f61cb56bf7fd2ef216d
 ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.11.7@sha256:240fb85ab0f263ef12f492d8476aa3a2e4e1e333f7d67fbdd923d00a506a516a
 # 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
 
@@ -60,6 +60,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 bedrock-realtime \
@@ -72,6 +73,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 bedrock-realtime \

gateway/routes/allowlist.py

@@ -76,6 +76,7 @@ GATEWAY_PATH_PREFIXES: tuple[str, ...] = (
     "/containers",
     "/v1/evals",
     "/v1/traces",
+    "/v1/logs",
     "/v1/memory",
     "/queue/chat/",
     # Google data plane (v1beta is the Google AI Studio version)

litellm-proxy-extras/litellm_proxy_extras/migrations/20260923000000_add_mcp_catalog_revision_trigger/migration.sql

@@ -0,0 +1,13 @@
+CREATE OR REPLACE FUNCTION litellm_bump_mcp_catalog_revision() RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO "LiteLLM_Config" ("param_name", "reload_revision")
+  VALUES ('mcp_catalog', 1)
+  ON CONFLICT ("param_name") DO UPDATE SET "reload_revision" = "LiteLLM_Config"."reload_revision" + 1;
+  RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS "litellm_mcp_catalog_revision" ON "LiteLLM_MCPServerTable";
+CREATE TRIGGER "litellm_mcp_catalog_revision"
+AFTER INSERT OR UPDATE OR DELETE ON "LiteLLM_MCPServerTable"
+FOR EACH STATEMENT EXECUTE PROCEDURE litellm_bump_mcp_catalog_revision();

litellm-proxy-extras/litellm_proxy_extras/migrations/20260930000000_add_end_user_models/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "LiteLLM_EndUserTable" ADD COLUMN IF NOT EXISTS "models" TEXT[] DEFAULT ARRAY[]::TEXT[];

litellm-proxy-extras/litellm_proxy_extras/migrations/20261005230000_lens_trace_findings_indexes/migration.sql

@@ -0,0 +1,3 @@
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "LiteLLM_LensRun_completed_executions_idx"
+ON "LiteLLM_LensRun" USING GIN ((data->'sample'->'executions') jsonb_path_ops)
+WHERE data->>'status'='completed';

litellm-proxy-extras/litellm_proxy_extras/migrations/20261005230100_lens_current_findings_index/migration.sql

@@ -0,0 +1,2 @@
+CREATE INDEX CONCURRENTLY IF NOT EXISTS "LiteLLM_Lens_jobs_idx"
+ON "LiteLLM_Lens" USING GIN ((data->'jobs') jsonb_path_ops);

litellm-proxy-extras/litellm_proxy_extras/migrations/20261006000000_lens_review_checkpoints/migration.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS "LiteLLM_LensReview" (
+    "lens_id" TEXT NOT NULL REFERENCES "LiteLLM_Lens"("id") ON DELETE CASCADE,
+    "criteria_key" TEXT NOT NULL,
+    "execution_id" TEXT NOT NULL,
+    "data" JSONB NOT NULL,
+    PRIMARY KEY ("lens_id", "criteria_key", "execution_id")
+);

litellm-proxy-extras/litellm_proxy_extras/migrations/20261006000100_lens_datasets/migration.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS "LiteLLM_LensDataset" (
+    "id" TEXT NOT NULL,
+    "revision" INTEGER NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL,
+    "data" JSONB NOT NULL,
+    CONSTRAINT "LiteLLM_LensDataset_pkey" PRIMARY KEY ("id", "revision")
+);

litellm-proxy-extras/litellm_proxy_extras/migrations/20261007000000_lens_review_fk_on_update_cascade/migration.sql

@@ -0,0 +1,15 @@
+-- DropForeignKey
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'LiteLLM_LensReview_lens_id_fkey' AND conrelid = '"LiteLLM_LensReview"'::regclass) THEN
+        ALTER TABLE "LiteLLM_LensReview" DROP CONSTRAINT "LiteLLM_LensReview_lens_id_fkey";
+    END IF;
+END $$;
+
+-- AddForeignKey
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'LiteLLM_LensReview_lens_id_fkey' AND conrelid = '"LiteLLM_LensReview"'::regclass) THEN
+        ALTER TABLE "LiteLLM_LensReview" ADD CONSTRAINT "LiteLLM_LensReview_lens_id_fkey" FOREIGN KEY ("lens_id") REFERENCES "LiteLLM_Lens"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+    END IF;
+END $$;

litellm-proxy-extras/litellm_proxy_extras/schema.prisma

@@ -656,6 +656,7 @@ model LiteLLM_EndUserTable {
   spend      Float    @default(0.0)
   allowed_model_region String? // require all user requests to use models in this specific region
   default_model String? // use along with 'allowed_model_region'. if no available model in region, default to this model.
+  models String[] @default([])
   budget_id String?
   object_permission_id String?
   litellm_budget_table LiteLLM_BudgetTable?   @relation(fields: [budget_id], references: [budget_id])
@@ -1934,6 +1935,7 @@ model LiteLLM_BackgroundInteractionSettlement {
 }
 
 model LiteLLM_Lens {
+  reviews LiteLLM_LensReview[]
   id      String @id
   version Int @default(0)
   data    Json
@@ -1948,8 +1950,27 @@ model LiteLLM_LensRun {
   @@index([lens_id, created_at])
 }
 
+model LiteLLM_LensReview {
+  lens_id String
+  criteria_key String
+  execution_id String
+  data Json
+  lens LiteLLM_Lens @relation(fields: [lens_id], references: [id], onDelete: Cascade)
+
+  @@id([lens_id, criteria_key, execution_id])
+}
+
 model LiteLLM_LensWorker {
   id         String @id
   token_hash String @unique
   data       Json
 }
+
+model LiteLLM_LensDataset {
+  id         String
+  revision   Int
+  created_at DateTime
+  data       Json
+
+  @@id([id, revision])
+}

litellm-proxy-extras/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "litellm-proxy-extras"
-version = "0.4.105"
+version = "0.4.106"
 description = "Additional files for the LiteLLM Proxy. Reduces the size of the main litellm package."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,7 +30,7 @@ required-version = ">=0.10.9"
 module-root = ""
 
 [tool.commitizen]
-version = "0.4.105"
+version = "0.4.106"
 version_files = [
     "pyproject.toml:^version",
     "../pyproject.toml:litellm-proxy-extras==",

litellm-rust/.agents/skills/rust-string-enums/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: rust-string-enums
+description: Define or refactor Rust string-valued enums and their Serde adapters in litellm-rust, using Strum and serde_with while preserving parsing, wire values, and schemas
+---
+
+# Rust string enums
+
+Use this skill when adding or changing enums represented by a single string, or surveying handwritten string conversions
+
+## Choose the representation
+
+For an enum with fixed spellings and an unknown-string fallback, prefer `strum::EnumString` and `strum::Display` together with `serde_with::DeserializeFromStr` and `serde_with::SerializeDisplay`. Keep each wire spelling in the Strum attributes instead of repeating it in a handwritten Serde match
+
+Strum implements string conversion traits, not Serde traits. `EnumString` implements `FromStr`; `Display` formats the wire string. The two `serde_with` derives connect those traits to Serde. `AsRefStr` provides a borrowed string accessor and is optional
+
+```rust
+#[derive(
+    Clone,
+    Debug,
+    PartialEq,
+    Eq,
+    strum::AsRefStr,
+    strum::EnumString,
+    strum::Display,
+    serde_with::DeserializeFromStr,
+    serde_with::SerializeDisplay,
+)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))]
+pub enum EventType {
+    #[strum(serialize = "event.created")]
+    Created,
+    #[strum(default, transparent)]
+    Other(String),
+}
+```
+
+Use `#[strum(serialize_all = "snake_case")]` or another supported case style when it exactly matches the contract. Use explicit variant spellings otherwise. With multiple accepted aliases, set `to_string` to the existing canonical output: Strum Display otherwise selects the longest `serialize` spelling
+
+Use only the derives the contract needs. A deserialize-only type should remain deserialize-only. Do not add an unknown variant to a closed enum, or derive Serde for a type that currently has no serialization contract
+
+Plain Serde derives with `rename` or `rename_all` remain appropriate for closed unit enums. Adding Strum and serde_with solely to replace working Serde derives adds little value. When a type has both Serde and Strum parsing, compare their accepted inputs before sharing the parser: case-insensitive Strum parsing must not silently make strict JSON parsing case-insensitive
+
+## Preserve behavior during migration
+
+Read the type, its callers, and existing tests before changing it. Preserve canonical output, accepted aliases, case sensitivity, whitespace handling, unknown values, malformed-input rejection, and existing public conversion APIs. Keep conversions needed by callers or compatibility even when Serde no longer uses them
+
+Use the workspace dependencies and enable `serde_with.workspace = true` in a crate only when needed. Check the versions and enabled features in `Cargo.toml` and `Cargo.lock` rather than upgrading dependencies for this refactor
+
+Remove replaced manual Serde implementations and obsolete Serde conversion attributes. Do not combine the new derives with `wire_type`, `request_type`, or `response_type` aliases that already derive the same Serde traits. Expand the necessary non-Serde derives and schema attributes locally rather than changing shared aliases for unrelated types
+
+Preserve the generated schema, including titles and definition names. Open string enums need a string schema, including unknown values. When replacing Serde `from`/`into` attributes that previously supplied that schema, retain their schema behavior with `#[cfg_attr(feature = "schema", schemars(from = "String", into = "String"))]` and compare the full generated result. `schemars(with = "String")` also makes a string schema, but changes the schema name and title, so keep it only where it already matches the contract
+
+Keep custom `FromStr` and `Display` implementations for structured strings or validation that Strum does not express faithfully. Their Serde adapters can still use `DeserializeFromStr` and `SerializeDisplay`. Do not replace JSON visitors, tagged payload enums, permissive value wrappers, or domain transformations with string parsing
+
+For a requested survey, document candidates and exceptions without migrating source. If the user asks to approve a bulk migration, present the concrete scope and wait for that approval
+
+## Verify the contract
+
+Extend existing mapped tests with named `rstest` cases. Assert both parsing into the expected variant and serialization to the expected wire string. Include unknown and empty strings for open enums, accepted aliases when present, and rejection of non-string JSON. A decode-only assertion does not prove a round trip
+
+Test structured parsers with valid and invalid payloads, including their existing error behavior. For types with schema support, check the string schema and run the affected crate tests with the schema feature enabled. Run affected downstream checks when conversion APIs or derive aliases change
+
+## Upstream references
+
+The workspace used Strum 0.28.0 and serde_with 3.16.1 when this guidance was written. Consult the matching version of the [EnumString docs](https://docs.rs/strum/0.28.0/strum/derive.EnumString.html), [Display docs](https://docs.rs/strum_macros/0.28.0/strum_macros/derive.Display.html), [DeserializeFromStr docs](https://docs.rs/serde_with/3.16.1/serde_with/derive.DeserializeFromStr.html), and [SerializeDisplay docs](https://docs.rs/serde_with/3.16.1/serde_with/derive.SerializeDisplay.html). Schemars documents [schema overrides and Serde conversion attributes](https://docs.rs/schemars/1.2.2/schemars/derive.JsonSchema.html)

litellm-rust/AGENTS.md

@@ -2,6 +2,8 @@
 
 For diagnostic tracing changes, follow [.agents/skills/rust-tracing/SKILL.md](.agents/skills/rust-tracing/SKILL.md)
 
+For string-valued enums and their Serde conversions, follow [.agents/skills/rust-string-enums/SKILL.md](.agents/skills/rust-string-enums/SKILL.md)
+
 ## Test placement
 
 - Never create a `tests.rs` (or `test.rs`) file under `src/`, and never `#[path = "tests.rs"] mod tests;`

litellm-rust/Cargo.lock

@@ -3697,50 +3697,6 @@ dependencies = [
  "thiserror 2.0.19",
 ]
 
-[[package]]
-name = "litellm-core"
-version = "0.1.0"
-dependencies = [
- "base64 0.22.1",
- "bytes",
- "futures-util",
- "litellm-auth",
- "litellm-auth-aws",
- "litellm-auth-gcp",
- "litellm-cache",
- "litellm-cache-memory",
- "litellm-cache-response",
- "litellm-core-utils",
- "litellm-framing",
- "litellm-host",
- "litellm-host-native",
- "litellm-http",
- "litellm-llms",
- "litellm-llms-types",
- "litellm-secrets",
- "litellm-tracing",
- "mime_guess",
- "moka",
- "rand 0.8.7",
- "reqwest 0.12.28",
- "rstest",
- "rstest_reuse",
- "serde",
- "serde_json",
- "sha2 0.10.9",
- "strum",
- "subtle",
- "thiserror 2.0.19",
- "time",
- "tokio",
- "tokio-tungstenite",
- "tokio-util",
- "tracing",
- "url",
- "veil",
- "wiremock",
-]
-
 [[package]]
 name = "litellm-core-utils"
 version = "0.1.0"
@@ -3796,7 +3752,7 @@ dependencies = [
 ]
 
 [[package]]
-name = "litellm-framing"
+name = "litellm-framer"
 version = "0.1.0"
 dependencies = [
  "aws-smithy-eventstream",
@@ -3821,12 +3777,12 @@ dependencies = [
  "http-body-util",
  "litellm-auth-types",
  "litellm-config",
- "litellm-core",
  "litellm-gateway-auth",
  "litellm-gateway-inference",
  "litellm-gateway-mcp",
  "litellm-gateway-ui",
  "litellm-http",
+ "litellm-inference",
  "litellm-llms",
  "litellm-secrets",
  "litellm-tracing",
@@ -3875,11 +3831,16 @@ dependencies = [
  "litellm-auth",
  "litellm-cache-memory",
  "litellm-cache-response",
- "litellm-core",
  "litellm-gateway-auth",
  "litellm-host",
  "litellm-host-http",
  "litellm-http",
+ "litellm-inference",
+ "litellm-inference-chat",
+ "litellm-inference-messages",
+ "litellm-inference-ocr",
+ "litellm-inference-responses",
+ "litellm-inference-transcription",
  "litellm-llms",
  "litellm-llms-types",
  "litellm-router",
@@ -4038,6 +3999,178 @@ dependencies = [
  "webpki-roots",
 ]
 
+[[package]]
+name = "litellm-inference"
+version = "0.1.0"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "litellm-auth",
+ "litellm-cache",
+ "litellm-cache-memory",
+ "litellm-cache-response",
+ "litellm-core-utils",
+ "litellm-framer",
+ "litellm-host",
+ "litellm-http",
+ "litellm-llms",
+ "litellm-secrets",
+ "litellm-tracing",
+ "reqwest 0.12.28",
+ "rstest",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.19",
+ "time",
+ "tokio",
+ "tokio-util",
+ "tracing",
+ "url",
+]
+
+[[package]]
+name = "litellm-inference-chat"
+version = "0.1.0"
+dependencies = [
+ "futures-util",
+ "litellm-auth",
+ "litellm-cache-memory",
+ "litellm-cache-response",
+ "litellm-core-utils",
+ "litellm-host",
+ "litellm-host-native",
+ "litellm-http",
+ "litellm-inference",
+ "litellm-inference-testing",
+ "litellm-llms",
+ "litellm-llms-types",
+ "litellm-secrets",
+ "litellm-tracing",
+ "rstest",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "wiremock",
+]
+
+[[package]]
+name = "litellm-inference-messages"
+version = "0.1.0"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "litellm-auth",
+ "litellm-auth-aws",
+ "litellm-cache-memory",
+ "litellm-cache-response",
+ "litellm-core-utils",
+ "litellm-host",
+ "litellm-host-native",
+ "litellm-http",
+ "litellm-inference",
+ "litellm-inference-testing",
+ "litellm-llms",
+ "litellm-llms-types",
+ "litellm-secrets",
+ "litellm-tracing",
+ "reqwest 0.12.28",
+ "rstest",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "wiremock",
+]
+
+[[package]]
+name = "litellm-inference-ocr"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "bytes",
+ "futures-util",
+ "litellm-auth",
+ "litellm-auth-aws",
+ "litellm-auth-gcp",
+ "litellm-core-utils",
+ "litellm-host",
+ "litellm-host-native",
+ "litellm-http",
+ "litellm-inference",
+ "litellm-inference-testing",
+ "litellm-llms",
+ "litellm-llms-types",
+ "litellm-secrets",
+ "litellm-tracing",
+ "mime_guess",
+ "rand 0.8.7",
+ "rstest",
+ "serde",
+ "serde_json",
+ "time",
+ "tokio",
+ "tracing",
+ "wiremock",
+]
+
+[[package]]
+name = "litellm-inference-responses"
+version = "0.1.0"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "litellm-auth",
+ "litellm-cache",
+ "litellm-cache-memory",
+ "litellm-cache-response",
+ "litellm-host",
+ "litellm-host-native",
+ "litellm-http",
+ "litellm-inference",
+ "litellm-inference-testing",
+ "litellm-llms",
+ "litellm-llms-types",
+ "litellm-secrets",
+ "litellm-tracing",
+ "reqwest 0.12.28",
+ "rstest",
+ "serde_json",
+ "tokio",
+ "tokio-tungstenite",
+ "tracing",
+ "wiremock",
+]
+
+[[package]]
+name = "litellm-inference-testing"
+version = "0.1.0"
+dependencies = [
+ "futures-util",
+ "litellm-http",
+ "litellm-inference",
+ "litellm-secrets",
+]
+
+[[package]]
+name = "litellm-inference-transcription"
+version = "0.1.0"
+dependencies = [
+ "futures-util",
+ "litellm-auth",
+ "litellm-core-utils",
+ "litellm-http",
+ "litellm-inference",
+ "litellm-inference-testing",
+ "litellm-llms",
+ "litellm-secrets",
+ "litellm-tracing",
+ "rstest",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "wiremock",
+]
+
 [[package]]
 name = "litellm-llms"
 version = "0.1.0"
@@ -4053,7 +4186,7 @@ dependencies = [
  "litellm-auth-azure",
  "litellm-auth-gcp",
  "litellm-core-utils",
- "litellm-framing",
+ "litellm-framer",
  "litellm-host",
  "litellm-http",
  "litellm-llms-types",
@@ -4112,22 +4245,20 @@ dependencies = [
  "litellm-auth",
  "litellm-auth-aws",
  "litellm-cache",
- "litellm-cache-azure-blob",
- "litellm-cache-disk",
- "litellm-cache-gcs",
  "litellm-cache-memory",
- "litellm-cache-qdrant-semantic",
  "litellm-cache-redis",
- "litellm-cache-redis-semantic",
  "litellm-cache-response",
- "litellm-cache-s3",
- "litellm-cache-valkey-semantic",
  "litellm-callbacks-legacy-python",
- "litellm-core",
  "litellm-core-utils",
  "litellm-host",
  "litellm-host-python",
  "litellm-http",
+ "litellm-inference",
+ "litellm-inference-chat",
+ "litellm-inference-messages",
+ "litellm-inference-ocr",
+ "litellm-inference-responses",
+ "litellm-inference-transcription",
  "litellm-llms",
  "litellm-llms-types",
  "litellm-secrets",
@@ -4142,21 +4273,18 @@ dependencies = [
  "prost",
  "pyo3",
  "pyo3-async-runtimes",
- "qdrant-client",
  "redis",
  "reqwest 0.12.28",
  "rstest",
  "serde",
  "serde_json",
  "serde_with",
- "sha2 0.10.9",
  "sqlx",
  "strum",
  "thiserror 2.0.19",
  "tokio",
  "tokio-tungstenite",
  "tracing",
- "url",
  "veil",
  "wiremock",
 ]
@@ -4181,7 +4309,8 @@ name = "litellm-router"
 version = "0.1.0"
 dependencies = [
  "litellm-config",
- "litellm-core",
+ "litellm-inference",
+ "litellm-inference-messages",
  "rstest",
 ]
 
@@ -4450,6 +4579,8 @@ dependencies = [
  "schemars 1.2.2",
  "serde",
  "serde_json",
+ "serde_with",
+ "sha2 0.10.9",
  "strum",
  "thiserror 2.0.19",
  "time",
@@ -6054,17 +6185,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "rstest_reuse"
-version = "0.7.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b3a8fb4672e840a587a66fc577a5491375df51ddb88f2a2c2a792598c326fe14"
-dependencies = [
- "quote",
- "rand 0.8.7",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "rusqlite"
 version = "0.39.0"

litellm-rust/Cargo.toml

@@ -16,7 +16,13 @@ litellm-traces = { path = "crates/traces" }
 litellm-traces-cache = { path = "crates/traces-cache" }
 litellm-traces-clickhouse = { path = "crates/traces-clickhouse" }
 litellm-storage-clickhouse = { path = "crates/storage-clickhouse" }
-litellm-core = { path = "crates/core" }
+litellm-inference = { path = "crates/inference" }
+litellm-inference-transcription = { path = "crates/inference-transcription" }
+litellm-inference-responses = { path = "crates/inference-responses" }
+litellm-inference-messages = { path = "crates/inference-messages" }
+litellm-inference-chat = { path = "crates/inference-chat" }
+litellm-inference-ocr = { path = "crates/inference-ocr" }
+litellm-inference-testing = { path = "crates/inference-testing" }
 litellm-gateway-mcp = { path = "crates/gateway-mcp" }
 litellm-gateway = { path = "crates/gateway" }
 litellm-gateway-inference = { path = "crates/gateway-inference" }
@@ -28,7 +34,7 @@ litellm-host = { path = "crates/host" }
 litellm-host-http = { path = "crates/host-http" }
 litellm-host-native = { path = "crates/host-native" }
 litellm-callbacks-legacy-python = { path = "crates/callbacks-legacy-python" }
-litellm-framing = { path = "crates/framer" }
+litellm-framer = { path = "crates/framer" }
 litellm-auth = { path = "crates/auth" }
 litellm-auth-types = { path = "crates/auth-types" }
 litellm-auth-aws = { path = "crates/auth-aws" }

litellm-rust/crates/callbacks-legacy-python/python_contract.json

@@ -88,7 +88,8 @@
     "call_type"
   ],
   "stream_opened": [
-    "logger"
+    "logger",
+    "head"
   ],
   "stream_success": [
     "logger",

litellm-rust/crates/callbacks-legacy-python/src/adapter.rs

@@ -536,7 +536,7 @@ impl LegacyLogging {
             head.bind(py).set_item("cache_key", key)?;
             head.bind(py).set_item("cache_hit", true)?;
         }
-        Streaming::Opened.call(py, (self.logger()?.object(py),))?;
+        Streaming::Opened.call(py, (self.logger()?.object(py), head.bind(py)))?;
         self.stream = Some(DeliveredStream {
             chunks: PyList::empty(py).unbind(),
             first_chunk: None,
@@ -1768,13 +1768,13 @@ assert logger.calls[1][1] is response
     fn stream_bindings_deliver_collected_chunks_in_order_without_success_fan_out() {
         Python::initialize();
         Python::attach(|py| {
-            let locals = namespace(py, c"first = b'first'\nlast = b'last'\nresponse = None");
+            let locals = namespace(py, c"first = b'first'\nlast = b'last'\nresponse = None\nhead = {'additional_headers': {'request-id': 'req_native'}}");
             let mut logging = LegacyLogging {
                 operation: crate::LoggingOperation::Messages,
                 ..logged(py, &locals, true)
             };
             logging
-                .on_stream_open(py, &pyo3::types::PyDict::new(py).into_any().unbind())
+                .on_stream_open(py, &local(&locals, "head").unbind())
                 .unwrap();
             logging
                 .on_stream_chunk(py, &local(&locals, "first").unbind())
@@ -1791,6 +1791,7 @@ assert logger.calls[1][1] is response
                 &locals,
                 c"
 assert logger.names() == ['stream_opened', 'stream_success'], logger.calls
+assert logger.calls[0][1] is head
 chunks = logger.calls[1][1]
 assert len(chunks) == 2
 assert chunks[0] is first

litellm-rust/crates/callbacks-legacy-python/src/test_support.rs

@@ -84,7 +84,7 @@ FAKES = {
         'success', response, call_type
     ),
     'after_deployment_failure': lambda kwargs, error, call_type: kwargs['logger'].hook('failure', error, call_type),
-    'stream_opened': lambda logger: logger.record('stream_opened', None),
+    'stream_opened': lambda logger, head: logger.record('stream_opened', head),
     'stream_success': lambda logger, url_route, endpoint_type, request_body, chunks, start, end, first_chunk: logger.record(
         'stream_success', list(chunks)
     ),

litellm-rust/crates/core/AGENTS.md

@@ -1,49 +0,0 @@
-litellm-core owns route orchestration. Messages and HTTP Responses return `litellm_host::call::CallOutput`, containing either a completed response or a stream head and chunks. OCR and currently non-streaming Chat Completions return their completed response directly
-
-Hosts assemble route objects from shared `CoreResources`, HTTP settings, and secret sources. Each route owns its provider client and authentication dependencies. Gateway routes live for the gateway lifetime; Python assembles routes per call from its settings snapshot
-
-Chat Completions, Messages, Responses, and OCR execute through their route objects. Calls pass `Interceptors` and an optional `ObservationSender` separately; use `&()` for no hooks and `None` for no observer. Construction does no work; preparation and lifecycle observation begin when the future is polled. Handlers accept `Interceptors`, never a concrete `ChannelInterceptors`. Native observers receive start and terminal events through the shared call runner; a stream retains its lifecycle until exhaustion, error, or drop. Hosted routes leave terminal observation to their driver
-
-`route.rs` declares the concrete `Protocol` and implements a route method that accepts a typed request and constructs a `litellm_host::call::HostedMachine` with `hosted_call`. The shared call plumbing owns stream opening, delivery, backpressure, and detachment. Request decoding belongs to the boundary before the machine starts. Route closures only supply execution dependencies and route-specific host capabilities such as an OCR token provider. Use `run_hosted` for a native host so detachment is reported as cancellation. Python uses its own shared driver and preserves caller-task callback execution
-
-Responses WebSocket sessions remain separate from the HTTP call driver because a connection can accept multiple requests while receiving events
-
-## Crate layering
-
-For Messages, Responses, Chat Completions, OCR, and other API formats, `core/src/<format>/` owns orchestration. Shared API data contracts belong in `litellm-llms-types`, adapter contracts and shared transformation machinery in `llms/src/base_llm/<format>/`, and provider policy in `llms/src/<provider>/<format>/`. A repeated format directory name does not imply interchangeable responsibilities. Select concrete adapters here, then invoke their contracts instead of applying one provider's policy to every call. Route types describe call envelopes and execution state, not duplicate public payload schemas
-
-Crates separate API data, transformations, transport, and orchestration. Python package names identify counterparts, not ownership. Dependencies only point down:
-
-- `litellm-llms-types` owns shared inference API contracts, grouped by format: pure serde data and shape validation, no I/O
-- `litellm-core-utils` mirrors `litellm/litellm_core_utils/`: pure helpers (provider resolution, prompt factory, call arguments, settings lookup and layer merge), no network I/O
-- `litellm-http` is Rust-only and route-neutral: settings resolution, the pooled `reqwest` clients, TLS, proxies, the SSRF-safe media fetcher, request and header helpers, and transport errors. Python's `litellm/llms/custom_httpx/` is split by responsibility instead of mirrored: its transport half lives here, its OCR handler in `litellm-llms`
-- `litellm-llms` mirrors `litellm/llms/`: `base_llm/<api>/transformation.rs`, `<provider>/<api>/transformation.rs`, and `base_llm/ocr/handler.rs` (the OCR request handler)
-- `litellm-core` mirrors the route packages (`litellm/ocr/`, `litellm/messages/`, ...): entrypoints, route request types, provider dispatch, the route machine, and hooks
-
-A route module owns the call entrypoint, route request types (`*Request<'a>`), credential fallback, provider dispatch, and the handler glue that runs a provider config. Provider code never imports from core; when it needs the caller's hooks mid-call it goes through `litellm_llms::base_llm::ocr::handler::CallHooks`, the provider-level hooks OCR implements over its host until it folds into `litellm_host::interceptors::Interceptors`. Import every item from its canonical path. Never re-export another crate's items or give an item a second public path; the only re-export allowed is a private submodule surfacing its item at its module root (`mod error; pub use error::Error;`). Handlers belong in core or llms, never in a host crate
-
-## Error placement
-
-The workspace `Error definitions` rules shape each crate's error; this section decides which crate and module a failure belongs to
-
-A failure is declared once, by the lowest crate that raises it. Every crate above nests that error unchanged (`#[error(transparent)] Auth(#[from] litellm_auth::Error)`) or maps it once at its boundary, as `src/error.rs` does for `litellm_llms::Error`. `RouteError` collects route failures and never re-declares a variant a lower crate raises
-
-Scope follows the concept, not the first caller. An error type under `litellm-llms`'s `<provider>/` is private to that provider: no other provider and nothing in `base_llm` may import it. A failure two providers or two routes can hit, such as wire framing, stream event decoding, or a malformed provider response, belongs to the crate that owns the concept: `litellm-framing` for framing, `litellm_llms::Error` for the transformation layer
-
-`litellm_llms::Error` (`crates/llms/src/error.rs`) is the one transformation error for every provider and API. `base_llm/ocr/error.rs` is the recorded exception until OCR folds into it
-
-Not here: serving HTTP (axum routes, extractors), config file reading, rollout state, databases, or callback execution of any kind. Core runs each route as a machine that yields host operations and call events; which integrations consume those events is the host's business.
-
-## Response caching and accounting boundary
-
-Attach a `litellm_cache_response::ScopedCache` with `route.with_cache(cache)`. Cached and uncached routes use the same `execute` and `machine` methods. `CallOptions` carries a scope-free `CachePolicy` and observation; per-call policy never replaces the attached scope or service
-
-Messages groups per-call dependencies in `CallContext` and explicitly sequences cache lookup, provider execution, result acceptance, and cache storage. Provider transport does not own cache orchestration. Stream capture remains in the shared cache implementation
-
-Core owns request identity, typed response reconstruction and stream capture/replay. `cache-response` owns cache policy, namespacing, scope encoding, versioned envelopes and freshness. The SDK explicitly chooses shared scope. The gateway derives isolated scope from authenticated identity before attaching its service
-
-Core delivers `ExecutionFacts` through the awaited `ResultReady` host operation for both provider and cached results, before public response processing or stream opening. Facts carry resolved model/provider and result source, including the hit key. Usage remains in the typed response or delivered stream, where completion and cancellation determine what was actually reported. Passive observation is not an accounting delivery mechanism
-
-Core does not calculate prices, charge budgets, or update rate-limit counters. The legacy Python callback adapter translates execution facts into the existing Python logging contract; Python remains the accounting owner on that path. Native gateway accounting belongs to gateway dependencies, independently of `host-python`. Response-cache services expose no coordination counters or reservation APIs. A shared Redis deployment does not make response storage and accounting coordination the same dependency
-
-Cache lookup follows provider preparation, credential resolution and the request interceptor. Keys describe the effective provider URL, authenticated headers and rewritten body. Signed requests bypass caching until the signing identity has a stable cache representation

litellm-rust/crates/core/src/constants.rs

@@ -1,15 +0,0 @@
-pub const OPENAI_DEFAULT_API_BASE: &str = "https://api.openai.com";
-
-/// Full-request timeout ceiling for Anthropic Messages provider calls, in
-/// seconds. Mirrors the Python Anthropic Messages default. The per-request
-/// timeout from the caller still overrides this on the request builder.
-pub(crate) const MESSAGES_TIMEOUT_SECS: u64 = 600;
-
-/// Full-request timeout ceiling for chat completions provider calls, in
-/// seconds. Mirrors the Python chat completions default.
-pub(crate) const CHAT_COMPLETIONS_TIMEOUT_SECS: u64 = 600;
-
-pub(crate) const AUDIO_TRANSCRIPTION_TIMEOUT_SECS: u64 = 600;
-
-/// `object` field every non-streaming chat completion response carries.
-pub const CHAT_COMPLETION_OBJECT: &str = "chat.completion";

litellm-rust/crates/core/src/messages/AGENTS.md

@@ -1,7 +0,0 @@
-This directory owns provider-independent Messages call orchestration: the entrypoint, call envelopes, provider selection, credential resolution, transport coordination, hooks, and stream lifecycle. Shared API data contracts belong in `litellm-llms-types::formats::messages`, adapter contracts and execution inputs in `llms/src/base_llm/messages`, and provider implementations in `llms/src/<provider>/messages`
-
-Select concrete provider adapters and invoke their contracts. Delegate authentication policy, beta selection, payload rewriting, and response interpretation to those adapters. Keep provider policy out of request preparation and transport handlers. Calling a concrete provider helper for every provider is still a policy dependency
-
-Route types such as `MessagesCall`, prepared requests, and response wrappers containing live streams describe execution. Reuse the shared Messages payload types inside them instead of defining another request or response schema here
-
-Preserve the order of validation, normalization, caller-requested parameter removal, and provider transformation when that order affects observable behavior. Test provider dispatch, auth precedence, header handling, transformations, and responses through behavior, not source structure