Merge remote-tracking branch 'origin/main' into litellm_bedrock_grok_chat_completions_lit8684

.circleci/config.yml

@@ -3419,7 +3419,7 @@ workflows:
           name: integration-<< matrix.suite >>
           matrix:
             parameters:
-              suite: [management, accounting, database, providers, mcp, sdk, cost, browser]
+              suite: [management, accounting, database, providers, mcp, sdk, cost, security, browser]
       - integration_contracts:
           name: integration-extensions
           suite: extensions

.circleci/scripts/unit_selection.sh

@@ -89,6 +89,7 @@ legacy_paths() {
     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
@@ -147,7 +148,10 @@ legacy_paths() {
       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 ;;
+    proxy-infra)
+      echo tests/unit/gateway
+      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 ;;

.github/CODEOWNERS

@@ -1,10 +1,2 @@
-/ui/ @yuneng-berri @ryan-crabbe-berri
-/litellm/proxy/_experimental/out/ @yuneng-berri @ryan-crabbe-berri
-/ui/Dockerfile
-/ui/nginx.conf
-/ui/litellm-dashboard/src/lib/http/schema.d.ts
-/ui/litellm-dashboard/tsconfig.tsbuildinfo
 /model_prices_and_context_window.json @mateo-berri @ryan-crabbe-berri @kerry-berri
 /litellm/model_prices_and_context_window_backup.json @mateo-berri @ryan-crabbe-berri @kerry-berri
-/litellm-proxy-extras/litellm_proxy_extras/migrations/ @yuneng-berri @ryan-crabbe-berri
-/.github/CODEOWNERS @yuneng-berri

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

@@ -15,6 +15,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+    outputs:
+      version: ${{ steps.version.outputs.version }}
     steps:
       - name: Require main
         env:
@@ -64,3 +66,14 @@ jobs:
               sha: context.sha,
             });
             core.info(`Created branch ${branchName} at ${context.sha}`);
+
+  linear-release:
+    name: Move the Linear release to rc
+    needs: create-rc-branch
+    permissions:
+      contents: read
+    uses: ./.github/workflows/linear-release.yml
+    with:
+      rc_version: ${{ needs.create-rc-branch.outputs.version }}
+    secrets:
+      LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}

.github/workflows/linear-release.yml

@@ -0,0 +1,131 @@
+name: Linear Release
+
+on:
+  push:
+    branches:
+      - main
+      - "rc/**"
+  release:
+    types: [published]
+  workflow_call:
+    inputs:
+      rc_version:
+        description: "X.Y.0 release whose rc branch was just cut"
+        required: true
+        type: string
+    secrets:
+      LINEAR_API_KEY:
+        required: true
+
+permissions: {}
+
+jobs:
+  linear-release:
+    name: Linear Release
+    if: github.repository == 'BerriAI/litellm'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Plan
+        id: plan
+        env:
+          EVENT: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          BEFORE: ${{ github.event.before }}
+          CREATED: ${{ github.event.created }}
+          RC_VERSION: ${{ inputs.rc_version }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          PRERELEASE: ${{ github.event.release.prerelease }}
+        run: |
+          set -euo pipefail
+          sync_base="${BEFORE}"
+          if [ "${CREATED}" = "true" ]; then
+            sync_base=""
+          fi
+          if [ -n "${RC_VERSION}" ]; then
+            echo "version=${RC_VERSION}" >> "$GITHUB_OUTPUT"
+            echo "stage=rc" >> "$GITHUB_OUTPUT"
+          elif [ "${EVENT}" = "release" ]; then
+            if [ "${PRERELEASE}" = "true" ] || ! echo "${RELEASE_TAG}" | grep -qE '^v[0-9]+\.[0-9]+\.0$'; then
+              echo "::notice::${RELEASE_TAG} is not an X.Y.0 stable release; nothing to complete"
+              exit 0
+            fi
+            echo "version=${RELEASE_TAG#v}" >> "$GITHUB_OUTPUT"
+            echo "complete=true" >> "$GITHUB_OUTPUT"
+          elif [ "${REF_NAME}" = "main" ]; then
+            version="$(python3 .github/scripts/read_rc_version.py | cut -d= -f2)"
+            status=0
+            git ls-remote --exit-code --heads origin "rc/${version}" > /dev/null || status=$?
+            case "${status}" in
+              0)
+                IFS=. read -r major minor _ <<< "${version}"
+                version="${major}.$((minor + 1)).0"
+                ;;
+              2) ;;
+              *)
+                echo "::error::could not check whether rc/${version} exists (git ls-remote exit ${status})"
+                exit 1
+                ;;
+            esac
+            echo "version=${version}" >> "$GITHUB_OUTPUT"
+            echo "sync_base=${sync_base}" >> "$GITHUB_OUTPUT"
+            echo "main=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=${REF_NAME#rc/}" >> "$GITHUB_OUTPUT"
+            echo "sync_base=${sync_base}" >> "$GITHUB_OUTPUT"
+            echo "stage=rc" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Sync commits into the release
+        if: steps.plan.outputs.sync_base != ''
+        uses: linear/linear-release-action@d4af10092984f9bc6d5efa075b242bdf01333463 # v0.18.0
+        with:
+          access_key: ${{ secrets.LINEAR_API_KEY }}
+          command: sync
+          name: LiteLLM ${{ steps.plan.outputs.version }}
+          version: ${{ steps.plan.outputs.version }}
+          base_ref: ${{ steps.plan.outputs.sync_base }}
+          cli_version: v0.18.0
+
+      - name: Keep the main stage unless the rc branch was cut during this run
+        id: main_stage
+        if: steps.plan.outputs.main == 'true'
+        env:
+          VERSION: ${{ steps.plan.outputs.version }}
+        run: |
+          set -euo pipefail
+          status=0
+          git ls-remote --exit-code --heads origin "rc/${VERSION}" > /dev/null || status=$?
+          case "${status}" in
+            0) echo "::notice::rc/${VERSION} was cut during this run; leaving the release in its rc stage" ;;
+            2) echo "stage=main" >> "$GITHUB_OUTPUT" ;;
+            *)
+              echo "::error::could not check whether rc/${VERSION} exists (git ls-remote exit ${status})"
+              exit 1
+              ;;
+          esac
+
+      - name: Move the release to its stage
+        if: steps.plan.outputs.stage != '' || steps.main_stage.outputs.stage != ''
+        uses: linear/linear-release-action@d4af10092984f9bc6d5efa075b242bdf01333463 # v0.18.0
+        with:
+          access_key: ${{ secrets.LINEAR_API_KEY }}
+          command: update
+          stage: ${{ steps.plan.outputs.stage || steps.main_stage.outputs.stage }}
+          version: ${{ steps.plan.outputs.version }}
+          cli_version: v0.18.0
+
+      - name: Complete the release
+        if: steps.plan.outputs.complete == 'true'
+        uses: linear/linear-release-action@d4af10092984f9bc6d5efa075b242bdf01333463 # v0.18.0
+        with:
+          access_key: ${{ secrets.LINEAR_API_KEY }}
+          command: complete
+          version: ${{ steps.plan.outputs.version }}
+          cli_version: v0.18.0

.github/workflows/test-unit.yml

@@ -79,7 +79,9 @@ jobs:
 
           - shard: integrations
             artifact-name: integrations
-            test-path: ""
+            test-path: >-
+              tests/test_litellm/integrations
+              tests/test_litellm/tracing
             unit-flag: integrations
             workers: 2
             reruns: 3

basedpyright-code-budget.json

@@ -99,7 +99,7 @@
     "limit": 0
   },
   "reportUnknownArgumentType": {
-    "limit": 44358
+    "limit": 44802
   },
   "reportUnknownLambdaType": {
     "limit": 109

cookbook/litellm_proxy_server/mcp/README.md

@@ -1,37 +0,0 @@
-# Publish MCP servers in the AI Hub
-
-Set `litellm_settings.public_mcp_servers` to the concrete IDs of the servers you want listed in the public AI Hub. Pin `server_id` in each configuration entry so the publication list stays stable across deployments
-
-```yaml
-mcp_servers:
-  documentation:
-    server_id: documentation-mcp
-    url: https://mcp.example.com/mcp
-    transport: http
-    available_on_public_internet: true
-
-litellm_settings:
-  public_mcp_hub_strict_whitelist: true
-  public_mcp_servers:
-    - documentation-mcp
-```
-
-Use `documentation-mcp`, the `server_id`, in the publication list. The configuration key `documentation`, display names, and aliases are not publication IDs. Database-created servers use the ID returned by `/v1/mcp/server`
-
-The dashboard's **AI Hub > MCP Hub > Manage MCP Hub Visibility** dialog edits this same list. Its YAML example includes the selected server IDs. With database-backed configuration (`store_model_in_db: true`), a value declared in YAML is owned by that file: edit the file and reload, or remove that key from YAML to let the dashboard manage it in the database. File-backed deployments can save the list directly to their configuration file
-
-To remove all explicit entries, save an empty selection in the dialog or configure:
-
-```yaml
-litellm_settings:
-  public_mcp_hub_strict_whitelist: true
-  public_mcp_servers: []
-```
-
-## Hub listing and network access
-
-The **Hub listing** column in AI Hub identifies servers that appear in `/public/mcp_hub`. The dashboard derives this status from the current registry and publication settings. Setting `mcp_info.is_public` on a server does not publish it; that response field is derived metadata. `mcp_info.is_public_explicit` identifies registered servers included in the explicit publication list
-
-Gateway cards and server details show **All Networks** when `available_on_public_internet` is enabled or the server is explicitly published in `public_mcp_servers`. They show **Internal Only** when both are false. The per-server flag defaults to `true`; explicit publication overrides a disabled flag for compatibility. Older proxies that omit the metadata needed to determine access show **Unknown**. These labels describe allowed client IPs; authentication and tool permissions still apply
-
-The default `public_mcp_hub_strict_whitelist: true` lists only registered servers in `public_mcp_servers`. Legacy mode (`false`) additionally lists registered servers with `available_on_public_internet: true`. In legacy mode, clearing the explicit publication list leaves these automatically listed servers visible. Enable strict mode when the publication list should fully determine hub visibility

cookbook/misc/config.yaml

@@ -24,7 +24,7 @@ model_list:
   - model_name: sagemaker-completion-model
     litellm_params:
       model: sagemaker/berri-benchmarking-Llama-2-70b-chat-hf-4
-      input_cost_per_second: 0.000420  
+      cost_per_second: 0.000420
   - model_name: text-embedding-ada-002
     litellm_params: 
       model: azure/azure-embedding-model

cookbook/misc/test_responses_api.py

@@ -12,7 +12,7 @@ def encode_image(image_path):
 
 
 # Path to your image
-image_path = "litellm/proxy/logo.jpg"
+image_path = "litellm/proxy/logo.png"
 
 # Getting the Base64 string
 base64_image = encode_image(image_path)
@@ -27,7 +27,7 @@ response = client.responses.create(
                 {"type": "input_text", "text": "what color is the image"},
                 {
                     "type": "input_image",
-                    "image_url": f"data:image/jpeg;base64,{base64_image}",
+                    "image_url": f"data:image/png;base64,{base64_image}",
                 },
             ],
         }

docker/Dockerfile.non_root

@@ -103,7 +103,7 @@ ENV LITELLM_NON_ROOT=true
 
 RUN mkdir -p /var/lib/litellm/ui /var/lib/litellm/assets && \
     cp -r /app/litellm/proxy/_experimental/out/. /var/lib/litellm/ui/ && \
-    cp /app/litellm/proxy/logo.jpg /var/lib/litellm/assets/logo.jpg && \
+    cp /app/litellm/proxy/logo.png /var/lib/litellm/assets/logo.png && \
     touch /var/lib/litellm/ui/.litellm_ui_ready
 
 RUN --mount=type=cache,target=/app/.cache/uv,id=litellm-uv-cache \

enterprise/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "litellm-enterprise"
-version = "0.1.71"
+version = "0.1.72"
 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.71"
+version = "0.1.72"
 version_files = [
     "pyproject.toml:^version",
     "../pyproject.toml:litellm-enterprise==",

litellm-proxy-extras/litellm_proxy_extras/migrations/20260921190000_agent_identity/migration.sql

@@ -0,0 +1,97 @@
+-- AlterTable
+ALTER TABLE "LiteLLM_AgentsTable" ADD COLUMN IF NOT EXISTS "enabled" BOOLEAN NOT NULL DEFAULT true,
+ADD COLUMN IF NOT EXISTS "execution_mode" TEXT NOT NULL DEFAULT 'autonomous',
+ADD COLUMN IF NOT EXISTS "identity_managed" BOOLEAN NOT NULL DEFAULT false;
+
+-- AlterTable
+ALTER TABLE "LiteLLM_SpendLogs" ADD COLUMN IF NOT EXISTS "billing_agent_id" TEXT;
+
+-- CreateTable
+CREATE TABLE IF NOT EXISTS "LiteLLM_AgentIdentity" (
+    "agent_id" TEXT NOT NULL,
+    "active" BOOLEAN NOT NULL DEFAULT true,
+    "provider" TEXT NOT NULL,
+    "issuer" TEXT NOT NULL,
+    "tenant_id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "service_principal_id" TEXT,
+    "required_roles" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "required_scopes" TEXT[] DEFAULT ARRAY['user_impersonation']::TEXT[],
+    "revision" TEXT NOT NULL,
+    "last_authenticated_at" TIMESTAMP(3),
+
+    CONSTRAINT "LiteLLM_AgentIdentity_pkey" PRIMARY KEY ("agent_id")
+);
+
+-- CreateTable
+CREATE TABLE IF NOT EXISTS "LiteLLM_RetiredAgentIdentity" (
+    "binding_id" TEXT NOT NULL,
+    "agent_id" TEXT,
+    "provider" TEXT NOT NULL,
+    "issuer" TEXT NOT NULL,
+    "tenant_id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+
+    CONSTRAINT "LiteLLM_RetiredAgentIdentity_pkey" PRIMARY KEY ("binding_id")
+);
+
+-- CreateTable
+CREATE TABLE IF NOT EXISTS "LiteLLM_RetiredAgent" (
+    "original_agent_id" TEXT NOT NULL,
+    "retired_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "LiteLLM_RetiredAgent_pkey" PRIMARY KEY ("original_agent_id")
+);
+
+-- CreateTable
+CREATE TABLE IF NOT EXISTS "LiteLLM_VerifiedSubject" (
+    "subject_id" TEXT NOT NULL,
+    "issuer" TEXT NOT NULL,
+    "tenant_id" TEXT NOT NULL,
+    "oid" TEXT NOT NULL,
+    "kind" TEXT NOT NULL DEFAULT 'human',
+    "user_id" TEXT,
+    "verified_via" TEXT NOT NULL DEFAULT 'sso_interactive',
+    "verified_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "LiteLLM_VerifiedSubject_pkey" PRIMARY KEY ("subject_id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX IF NOT EXISTS "LiteLLM_AgentIdentity_provider_tenant_id_client_id_key" ON "LiteLLM_AgentIdentity"("provider", "tenant_id", "client_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX IF NOT EXISTS "LiteLLM_AgentIdentity_issuer_service_principal_id_key" ON "LiteLLM_AgentIdentity"("issuer", "service_principal_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX IF NOT EXISTS "LiteLLM_RetiredAgentIdentity_provider_tenant_id_client_id_key" ON "LiteLLM_RetiredAgentIdentity"("provider", "tenant_id", "client_id");
+
+-- CreateIndex
+CREATE INDEX IF NOT EXISTS "LiteLLM_VerifiedSubject_user_id_idx" ON "LiteLLM_VerifiedSubject"("user_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX IF NOT EXISTS "LiteLLM_VerifiedSubject_issuer_tenant_id_oid_key" ON "LiteLLM_VerifiedSubject"("issuer", "tenant_id", "oid");
+
+-- AddForeignKey
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'LiteLLM_AgentIdentity_agent_id_fkey') THEN
+        ALTER TABLE "LiteLLM_AgentIdentity" ADD CONSTRAINT "LiteLLM_AgentIdentity_agent_id_fkey" FOREIGN KEY ("agent_id") REFERENCES "LiteLLM_AgentsTable"("agent_id") ON DELETE CASCADE ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+-- AddForeignKey
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'LiteLLM_RetiredAgentIdentity_agent_id_fkey') THEN
+        ALTER TABLE "LiteLLM_RetiredAgentIdentity" ADD CONSTRAINT "LiteLLM_RetiredAgentIdentity_agent_id_fkey" FOREIGN KEY ("agent_id") REFERENCES "LiteLLM_AgentsTable"("agent_id") ON DELETE SET NULL ON UPDATE CASCADE;
+    END IF;
+END $$;
+
+-- AddForeignKey
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'LiteLLM_VerifiedSubject_user_id_fkey') THEN
+        ALTER TABLE "LiteLLM_VerifiedSubject" ADD CONSTRAINT "LiteLLM_VerifiedSubject_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "LiteLLM_UserTable"("user_id") ON DELETE CASCADE ON UPDATE CASCADE;
+    END IF;
+END $$;

litellm-proxy-extras/litellm_proxy_extras/migrations/20260925000000_add_mcp_pinned_tools/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "LiteLLM_MCPServerTable" ADD COLUMN IF NOT EXISTS "pinned_tools" JSONB DEFAULT '{}';

litellm-proxy-extras/litellm_proxy_extras/migrations/20260928000000_add_daily_model_usage/migration.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS "LiteLLM_DailyModelUsage" (
+    "date" TEXT NOT NULL,
+    "model_group" TEXT NOT NULL,
+    "model" TEXT NOT NULL,
+    "custom_llm_provider" TEXT NOT NULL,
+    "task_type" TEXT NOT NULL,
+    "spend" DOUBLE PRECISION NOT NULL DEFAULT 0.0,
+    "prompt_tokens" BIGINT NOT NULL DEFAULT 0,
+    "completion_tokens" BIGINT NOT NULL DEFAULT 0,
+    "request_count" BIGINT NOT NULL DEFAULT 0,
+    "successful_requests" BIGINT NOT NULL DEFAULT 0,
+    "failed_requests" BIGINT NOT NULL DEFAULT 0,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    CONSTRAINT "LiteLLM_DailyModelUsage_pkey" PRIMARY KEY ("date", "model_group", "model", "custom_llm_provider", "task_type")
+);
+
+CREATE INDEX IF NOT EXISTS "LiteLLM_DailyModelUsage_date_idx" ON "LiteLLM_DailyModelUsage"("date");
+CREATE INDEX IF NOT EXISTS "LiteLLM_DailyModelUsage_model_group_idx" ON "LiteLLM_DailyModelUsage"("model_group");

litellm-proxy-extras/litellm_proxy_extras/schema.prisma

@@ -78,6 +78,11 @@ model LiteLLM_AgentsTable {
   object_permission_id String?
   object_permission LiteLLM_ObjectPermissionTable? @relation(fields: [object_permission_id], references: [object_permission_id])
   spend      Float    @default(0.0)
+  identity_managed Boolean @default(false)
+  enabled Boolean @default(true)
+  execution_mode String @default("autonomous")
+  identity LiteLLM_AgentIdentity?
+  retired_identities LiteLLM_RetiredAgentIdentity[]
   tpm_limit  Int?
   rpm_limit  Int?
   session_tpm_limit Int?
@@ -88,6 +93,56 @@ model LiteLLM_AgentsTable {
   updated_by String
 }
 
+model LiteLLM_AgentIdentity {
+  agent_id String @id
+  active Boolean @default(true)
+  agent LiteLLM_AgentsTable @relation(fields: [agent_id], references: [agent_id], onDelete: Cascade)
+  provider String
+  issuer String
+  tenant_id String
+  client_id String
+  service_principal_id String?
+  required_roles String[] @default([])
+  required_scopes String[] @default(["user_impersonation"])
+  revision String @default(uuid())
+  last_authenticated_at DateTime?
+  @@unique([provider, tenant_id, client_id])
+  @@unique([issuer, service_principal_id])
+}
+
+model LiteLLM_RetiredAgentIdentity {
+  binding_id String @id @default(uuid())
+  agent_id String?
+  agent LiteLLM_AgentsTable? @relation(fields: [agent_id], references: [agent_id], onDelete: SetNull)
+  provider String
+  issuer String
+  tenant_id String
+  client_id String
+  @@unique([provider, tenant_id, client_id])
+}
+
+model LiteLLM_RetiredAgent {
+  original_agent_id String @id
+  retired_at DateTime @default(now())
+}
+
+model LiteLLM_VerifiedSubject {
+  subject_id String @id @default(uuid())
+  issuer String
+  tenant_id String
+  oid String
+  kind String @default("human")
+  user_id String?
+  user LiteLLM_UserTable? @relation(fields: [user_id], references: [user_id], onDelete: Cascade)
+  verified_via String @default("sso_interactive")
+  verified_at DateTime @default(now())
+  @@unique([issuer, tenant_id, oid])
+  @@index([user_id])
+}
+
+
+
+
 model LiteLLM_OrganizationTable {
 		organization_id String @id @default(uuid())
     organization_alias  String
@@ -241,6 +296,7 @@ model LiteLLM_DeletedTeamTable {
 
 // Track spend, rate limit, budget Users
 model LiteLLM_UserTable {
+    verified_subjects LiteLLM_VerifiedSubject[]
 		user_id    String @id
     user_alias String? 
     team_id    String?
@@ -322,6 +378,7 @@ model LiteLLM_MCPServerTable {
   allowed_tools String[]      @default([])
   tool_name_to_display_name Json? @default("{}")
   tool_name_to_description   Json? @default("{}")
+  pinned_tools Json? @default("{}")
   extra_headers String[]    @default([])
   static_headers Json?        @default("{}")
   // Admin-configured environment variables interpolated into static_headers
@@ -674,6 +731,7 @@ model LiteLLM_SpendLogs {
   session_id          String?
   status              String?
   mcp_namespaced_tool_name String? 
+  billing_agent_id    String?
   agent_id            String?
   proxy_server_request Json?     @default("{}")
   litellm_call_id     String?
@@ -1259,6 +1317,26 @@ model LiteLLM_DailyToolSpend {
   @@id([date, tool_name])
 }
 
+model LiteLLM_DailyModelUsage {
+  date                String
+  model_group         String
+  model               String
+  custom_llm_provider String
+  task_type           String
+  spend               Float    @default(0.0)
+  prompt_tokens       BigInt   @default(0)
+  completion_tokens   BigInt   @default(0)
+  request_count       BigInt   @default(0)
+  successful_requests BigInt   @default(0)
+  failed_requests     BigInt   @default(0)
+  created_at          DateTime @default(now())
+  updated_at          DateTime @updatedAt
+
+  @@id([date, model_group, model, custom_llm_provider, task_type])
+  @@index([date])
+  @@index([model_group])
+}
+
 // Gateway request counts recorded at the ASGI edge by
 // BillableRequestMetricsMiddleware. This is the source of truth for SGR
 // (successful gateway requests): it counts what the proxy actually answered,

litellm-proxy-extras/pyproject.toml

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

litellm-rust/Cargo.lock

@@ -1274,6 +1274,18 @@ version = "0.4.33"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e8ccc4ea9f6acc32d102c0f6d471d11d913ad15f20c04de743374861fa1d414"
 
+[[package]]
+name = "const-hex"
+version = "1.19.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e59eef12462b0f9b0a3620219be5d639afd79fe39dff0a42c3997061f9298b4"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "proptest",
+ "serde_core",
+]
+
 [[package]]
 name = "const-oid"
 version = "0.9.6"
@@ -2372,9 +2384,9 @@ dependencies = [
  "http-body-util",
  "hyper 1.10.1",
  "lazy_static",
- "opentelemetry",
+ "opentelemetry 0.32.0",
  "opentelemetry-semantic-conventions",
- "opentelemetry_sdk",
+ "opentelemetry_sdk 0.32.1",
  "percent-encoding",
  "pin-project",
  "prost",
@@ -3552,8 +3564,10 @@ name = "litellm-cache-response"
 version = "0.1.0"
 dependencies = [
  "litellm-cache",
+ "litellm-cache-gcs",
  "litellm-cache-memory",
  "litellm-cache-redis",
+ "litellm-http",
  "py_literal",
  "redis",
  "redis-test",
@@ -3562,6 +3576,7 @@ dependencies = [
  "serde_json",
  "sha2 0.10.9",
  "tokio",
+ "wiremock",
 ]
 
 [[package]]
@@ -3616,7 +3631,6 @@ dependencies = [
  "litellm-auth",
  "litellm-host",
  "litellm-host-python",
- "litellm-types",
  "proptest",
  "pyo3",
  "rstest",
@@ -3646,14 +3660,18 @@ dependencies = [
  "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",
- "litellm-types",
  "mime_guess",
  "moka",
  "rand 0.8.7",
@@ -3669,6 +3687,7 @@ dependencies = [
  "time",
  "tokio",
  "tokio-tungstenite",
+ "tokio-util",
  "tracing",
  "url",
  "veil",
@@ -3680,13 +3699,12 @@ name = "litellm-core-utils"
 version = "0.1.0"
 dependencies = [
  "fancy-regex 0.19.2",
+ "litellm-llms-types",
  "litellm-tracing",
- "litellm-types",
  "rstest",
  "serde",
  "serde_json",
  "serde_path_to_error",
- "serde_with",
  "strum",
  "thiserror 2.0.19",
  "url",
@@ -3808,15 +3826,19 @@ dependencies = [
  "bytes",
  "futures-util",
  "litellm-auth",
+ "litellm-cache-memory",
+ "litellm-cache-response",
  "litellm-core",
  "litellm-gateway-auth",
+ "litellm-host",
  "litellm-host-http",
  "litellm-http",
  "litellm-llms",
+ "litellm-llms-types",
  "litellm-router",
  "litellm-secrets",
- "litellm-types",
  "rstest",
+ "serde",
  "serde_json",
  "thiserror 2.0.19",
  "tokio",
@@ -3987,9 +4009,9 @@ dependencies = [
  "litellm-framing",
  "litellm-host",
  "litellm-http",
+ "litellm-llms-types",
  "litellm-python-compat",
  "litellm-secrets",
- "litellm-types",
  "reqwest 0.12.28",
  "rstest",
  "serde",
@@ -4003,13 +4025,26 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "litellm-llms-types"
+version = "0.1.0"
+dependencies = [
+ "macro_rules_attribute",
+ "rstest",
+ "schemars 1.2.2",
+ "serde",
+ "serde_json",
+ "serde_with",
+ "strum",
+]
+
 [[package]]
 name = "litellm-model-catalog"
 version = "0.1.0"
 dependencies = [
  "indexmap 2.14.0",
  "jsonschema",
- "litellm-types",
+ "litellm-llms-types",
  "rstest",
  "schemars 1.2.2",
  "serde",
@@ -4047,12 +4082,13 @@ dependencies = [
  "litellm-host-python",
  "litellm-http",
  "litellm-llms",
+ "litellm-llms-types",
  "litellm-secrets",
  "litellm-secrets-aws",
  "litellm-secrets-types",
  "litellm-token-counter",
+ "litellm-traces",
  "litellm-tracing",
- "litellm-types",
  "pyo3",
  "pyo3-async-runtimes",
  "qdrant-client",
@@ -4328,6 +4364,25 @@ dependencies = [
  "tiktoken-rs",
 ]
 
+[[package]]
+name = "litellm-traces"
+version = "0.1.0"
+dependencies = [
+ "base64 0.22.1",
+ "flate2",
+ "litellm-http",
+ "opentelemetry-proto",
+ "prost",
+ "rstest",
+ "serde",
+ "serde_json",
+ "testcontainers-modules",
+ "thiserror 2.0.19",
+ "time",
+ "tokio",
+ "url",
+]
+
 [[package]]
 name = "litellm-tracing"
 version = "0.1.0"
@@ -4342,17 +4397,6 @@ dependencies = [
  "tracing-subscriber",
 ]
 
-[[package]]
-name = "litellm-types"
-version = "0.1.0"
-dependencies = [
- "rstest",
- "schemars 1.2.2",
- "serde",
- "serde_json",
- "strum",
-]
-
 [[package]]
 name = "litemap"
 version = "0.8.2"
@@ -4748,6 +4792,33 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "opentelemetry"
+version = "0.33.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cdb0b1b267eb9db3331b434ed9ddab10d50e280a9adf9d13e5233e2002b61b5"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+ "js-sys",
+ "pin-project-lite",
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "opentelemetry-proto"
+version = "0.33.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25da1ac11a0aeccf38d7f77ee0348715adaf8340f65ad46c94a02c6b20e2f65d"
+dependencies = [
+ "base64 0.22.1",
+ "const-hex",
+ "opentelemetry 0.33.0",
+ "opentelemetry_sdk 0.33.0",
+ "prost",
+ "serde",
+]
+
 [[package]]
 name = "opentelemetry-semantic-conventions"
 version = "0.32.1"
@@ -4763,7 +4834,23 @@ dependencies = [
  "futures-channel",
  "futures-executor",
  "futures-util",
- "opentelemetry",
+ "opentelemetry 0.32.0",
+ "percent-encoding",
+ "portable-atomic",
+ "rand 0.9.5",
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "opentelemetry_sdk"
+version = "0.33.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb39533d9d1c912123efd7d41d7e0c29d16917b60ce15b4c8d87cb1af7f67520"
+dependencies = [
+ "futures-channel",
+ "futures-executor",
+ "futures-util",
+ "opentelemetry 0.33.0",
  "percent-encoding",
  "portable-atomic",
  "rand 0.9.5",
@@ -5692,6 +5779,7 @@ checksum = "16a1cfa75cc186dd73d5818e510e042e40927bccc9c236b061cea97e1eb08029"
 dependencies = [
  "base64 0.23.1",
  "bytes",
+ "encoding_rs",
  "futures-core",
  "futures-util",
  "h2 0.4.15",
@@ -5703,6 +5791,7 @@ dependencies = [
  "hyper-util",
  "js-sys",
  "log",
+ "mime",
  "percent-encoding",
  "pin-project-lite",
  "quinn",
@@ -6933,6 +7022,7 @@ dependencies = [
  "memchr",
  "parse-display",
  "pin-project-lite",
+ "reqwest 0.13.5",
  "serde",
  "serde_json",
  "serde_with",
@@ -7493,7 +7583,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "adbc64cba7137545b8044cb1fe9814f7aacf3c6b5f9b45be8bb5db538befdb26"
 dependencies = [
  "js-sys",
- "opentelemetry",
+ "opentelemetry 0.32.0",
  "tracing",
  "tracing-core",
  "tracing-subscriber",

litellm-rust/Cargo.toml

@@ -12,6 +12,7 @@ repository = "https://github.com/BerriAI/litellm"
 litellm-config = { path = "crates/config" }
 litellm-router = { path = "crates/router" }
 litellm-tracing = { path = "crates/tracing" }
+litellm-traces = { path = "crates/traces" }
 litellm-core = { path = "crates/core" }
 litellm-gateway-mcp = { path = "crates/gateway-mcp" }
 litellm-gateway = { path = "crates/gateway" }
@@ -39,7 +40,7 @@ litellm-secrets-azure = { path = "crates/secrets-azure" }
 litellm-secrets-cyberark = { path = "crates/secrets-cyberark" }
 litellm-http = { path = "crates/http" }
 litellm-llms = { path = "crates/llms" }
-litellm-types = { path = "crates/types" }
+litellm-llms-types = { path = "crates/llms-types" }
 litellm-core-utils = { path = "crates/core-utils" }
 litellm-db = { path = "crates/db" }
 litellm-db-testing = { path = "crates/db-testing" }
@@ -74,6 +75,7 @@ proptest = "1.7.0"
 pyo3 = "0.29.2"
 pyo3-async-runtimes = { version = "0.29.0", features = ["tokio-runtime"] }
 rand = "0.8"
+macro_rules_attribute = "0.2.3"
 schemars = "1"
 reqwest = { version = "0.12", default-features = false, features = ["json", "multipart", "rustls-tls", "http2", "stream"] }
 qdrant-client = { version = "1.19.0", default-features = false }

litellm-rust/crates/cache-gcs/tests/cache.rs

@@ -56,6 +56,7 @@ async fn set_writes_encoded_object_and_headers(#[future(awt)] server: MockServer
 )]
 #[case::missing("missing", ResponseTemplate::new(404), Ok(None))]
 #[case::server_error("server-error", ResponseTemplate::new(500), Err(Error::Unavailable))]
+#[case::unauthorized("unauthorized", ResponseTemplate::new(401), Err(Error::Unavailable))]
 #[case::invalid(
     "invalid",
     ResponseTemplate::new(200).set_body_string("not json"),

litellm-rust/crates/cache-response/AGENTS.md

@@ -0,0 +1,29 @@
+# Response caching
+
+Design this crate for shared Rust execution used by the Python SDK and the Rust gateway. The Python SDK will remain, with more core execution moving to Rust and Python callbacks staying in Python. The Rust gateway is still evolving and is intended to replace the Python proxy. Keep response-cache policy independent of Python, HTTP serving, and either proxy's configuration format
+
+Separate what is cached, how a hit is matched, and where entries are stored. Chat Completions, Messages, Responses, and embeddings are API workloads. Exact and semantic matching are lookup behaviors. Memory, Redis, disk, and object stores are storage choices. Embeddings are inference too, so do not use an inference-cache name to imply a category that excludes embeddings. Consult the existing Python cache and caching handler for behavior and compatibility contracts without copying their class structure
+
+Storage traits, codecs, and backend capabilities belong in `litellm-cache` and the storage crates. Keep storage reusable for value types beyond LLM responses. This crate owns response entries, matching and freshness semantics, the Python-compatible response codec, and deferred-write policy. Core owns route-specific request identity, response encoding and reconstruction, embedding partial-hit orchestration, and stream capture and replay. Boundaries own configuration translation, resource construction, and caller identity
+
+Construct and inject the response-cache service at the Python bridge or gateway boundary, as with the HTTP client. Reuse it across calls. Core and provider code must not discover cache configuration through Python globals, process configuration, or backend-specific factories
+
+Keep `ResponseCache<B>` generic over its storage backend. Preserve typed backend contexts and capability bounds internally. Inject an object-safe service into core for runtime backend selection, so storage types do not spread through route and host types. Keep API request and response types statically typed. Add a generic parameter only where it preserves a useful type relationship or capability
+
+Keep the core service contract narrow. Lookup and store must not require connection testing, ping, flush, deletion, counters, queues, or scripts. Require batch operations where a consumer needs partial hits, and keep management capabilities on their own interfaces. An exact-only adapter must remain explicit about its matching restriction. Supporting semantic matching requires a defined lookup-context and embedding execution contract, not just a renamed trait
+
+Separate reusable resources from per-call policy. Backend configuration, namespace, default expiry, and entry limits belong to the configured service or backend. Read/write controls, expiry and freshness overrides, and authenticated caller scope belong to the call. Passing call options must not replace or mutate the route's configured service
+
+Keep cache misses and storage failures distinguishable in return values. Core owns the decision to continue with provider execution after a cache failure. A read can reject an entry for freshness while the backend still retains it. Preserve the timestamp at which a response was produced when writing it later
+
+Define lookup placement explicitly relative to authorization, deployment and credential resolution, and request-transforming callbacks. Cache identity must account for every input that affects reuse, including API surface and caller scope, while preserving intentional Python caching groups. Preserve existing keys and response formats unless changing them is an explicit migration decision
+
+Cache normalized provider results before caller-specific response transformations. Hits must still run the applicable response processing, success callbacks, and cache-hit accounting. Keep callback execution in the host. Python cache implementations and semantic embedders that require the caller's task must use the existing host-operation mechanism rather than Python calls from a Rust worker. Preserve legacy fallback until that contract is supported
+
+Keep unary caching independent of stream-only methods. Store streams only after successful exhaustion and protocol completion. Errors, incomplete streams, cancellation, and oversized entries must not populate the cache. Embedding batches need ordered partial results and reconstruction around the uncached inputs
+
+Test each contract in its owner: storage capabilities in backend tests, envelopes and freshness here, reuse and replay in core, Python callback and fallback behavior at the bridge, and HTTP behavior at the gateway. Run backend contract checks and Python response-codec fixtures before exposing a new backend
+
+`ScopedCache` requires an explicit shared or isolated scope at construction. Per-call `CachePolicy` controls reads, writes, expiry, and freshness without replacing the attached scope or service. `CacheOptions` binds that policy to an explicit scope for storage requests and has no default sharing policy. Versioned native envelopes reject incompatible API surfaces and versions as misses; this envelope is distinct from the legacy Python response codec
+
+Response storage is not the source of budget or rate-limit coordination dependencies. Keep counters, reservations, and atomic admission operations out of `ResponseCacheService`, including when both services happen to use Redis

litellm-rust/crates/cache-response/Cargo.toml

@@ -13,9 +13,12 @@ serde_json.workspace = true
 sha2.workspace = true
 
 [dev-dependencies]
+litellm-cache-gcs.workspace = true
+litellm-http = { workspace = true, features = ["test-support"] }
 litellm-cache-memory.workspace = true
 litellm-cache-redis.workspace = true
 redis = "1.7.0"
 redis-test = "1.0.4"
 rstest.workspace = true
 tokio.workspace = true
+wiremock = "0.6.5"

litellm-rust/crates/cache-response/README.md

@@ -1,51 +0,0 @@
-# Response cache
-
-`ResponseCache<B>` adds request keys, independent read/write controls, response envelopes, and freshness checks to any `B: BaseCache<Value = CacheEntry>`
-
-## Ownership
-
-`litellm-cache` defines typed storage, codec, and capability traits. `BaseCache` is only get, set, TTL, and pipeline writes. Everything else is an optional capability a backend implements only where its Python class defines the method: `DisconnectCache`, `ConnectionCache` (`test_connection`), `PingCache`, `BatchCache`, `DeleteCache`, `FlushCache`, counters, queues, TTL, scan, and scripts. Memory, Redis, disk, S3, GCS, and Azure Blob implement those traits without depending on response policy, so other consumers can store their own value types in the same backends
-
-Semantic backends (Redis, Valkey, Qdrant) are generic over their embedder and codec, and share one prompt and embedding contract from `litellm_cache::semantic`. They take a `SemanticCacheContext`, so `ResponseCache` drives them the same way it drives exact backends
-
-`litellm-cache-response` owns response keys, controls, entries, the Python-compatible response codec, and `WriteBuffer`, the backend-neutral deferred-write policy. It has no runtime dependency on a specific cache backend or Python
-
-`ExactResponseCache` is the object-safe view of a `ResponseCache` over an exact backend. `ConnectionProbe` is the object-safe `test_connection`, implemented only when the backend implements `ConnectionCache`, so a host holds one next to its `ExactResponseCache` and reports the operation as unsupported otherwise, as Python's `BaseCache` does. Lookup, store, batch, and flush never require it
-
-## Native Rust use
-
-```rust
-use std::{sync::Arc, time::Duration};
-use litellm_cache_memory::InMemoryCache;
-use litellm_cache_response::{CacheKeyInput, ResponseCache, ResponseCacheRequest};
-use serde_json::json;
-
-let cache = ResponseCache::new(Arc::new(InMemoryCache::default()));
-let request = ResponseCacheRequest::new(CacheKeyInput {
-    preset: Some("example:key".into()),
-    ..Default::default()
-});
-let now = Duration::from_secs(100);
-cache.store(&request, json!({"answer": 7}), now)?;
-assert_eq!(cache.async_lookup(&request, now).await?, Some(json!({"answer": 7})));
-```
-
-For Redis, inject `RedisCache::new(url, ttl, ResponseCacheCodec)` instead. Namespaces are optional and existing namespace prefixes are preserved
-
-Callers supply Unix time for response freshness. Backend TTL uses its own clock. A read can reject an entry through `max_age` even while the backend still retains it
-
-## Python integration
-
-The bridge activates backends through the Rust catalog in `litellm/rust_bridge/catalog.py`. Every cache rule ships as `PYTHON_ONLY`, so SDK, Router, and proxy calls stay on Python and construct no native cache resources until a rule is changed
-
-When a rule selects a backend, the Python `Cache` facade builds the native runtime from its own configuration and routes its storage calls (sync and async lookup and store, and pipelined batch store) to it. Stream replay, embedding partial-hit merging, response reconstruction, and callbacks stay in Python on top of that native store. The Python backend object remains for its direct API
-
-Object responses are written as they are, and every other response shape is written as a serialized string, which is the pair of shapes Python reads. A string on the wire is therefore always a serialized response, so string-valued responses round trip. Typed backends such as memory never pass through the codec
-
-Native cache handles must be recreated after fork. Native errors propagate to the host, which owns the existing fail-open and logging policy
-
-## Adding another backend
-
-Implement `BaseCache` for the backend with its associated value type and the capability traits its Python class supports, and accept a `CacheCodec` when wire serialization is needed. `ResponseCache<B>` then works without another response implementation
-
-Run the `litellm-cache-testing` contract checks the backend's capabilities allow, and run response fixtures with `ResponseCacheCodec`, including both Python envelope encodings, before adding a catalog rule

litellm-rust/crates/cache-response/src/lib.rs

@@ -4,6 +4,7 @@ mod codec;
 mod embedding;
 mod exact;
 mod response;
+mod service;
 
 pub use buffer::WriteBuffer;
 pub use caching::{
@@ -14,3 +15,8 @@ pub use codec::ResponseCacheCodec;
 pub use embedding::PartialHits;
 pub use exact::{ConnectionProbe, ExactResponseCache};
 pub use response::{ResponseCache, ResponseCacheRequest};
+
+pub use service::{
+    CacheOptions, CachePolicy, CacheScope, ResponseCacheConfig, ResponseCacheService,
+    ResponseEnvelope, ScopedCache,
+};

litellm-rust/crates/cache-response/src/response.rs

@@ -7,7 +7,9 @@ use litellm_cache::{
 };
 use serde_json::Value;
 
-use crate::{CacheControls, CacheEntry, CacheKeyInput, PartialHits, cache_key};
+use crate::{
+    CacheControls, CacheEntry, CacheKeyInput, PartialHits, ResponseCacheConfig, cache_key,
+};
 
 #[derive(Clone)]
 pub struct ResponseCacheRequest<C: CacheContext = litellm_cache::ExactCacheContext> {
@@ -50,6 +52,7 @@ where
     B::Context: Default + PartialEq,
 {
     backend: Arc<B>,
+    config: ResponseCacheConfig,
 }
 
 impl<B> ResponseCache<B>
@@ -58,7 +61,18 @@ where
     B::Context: Default + PartialEq,
 {
     pub fn new(backend: Arc<B>) -> Self {
-        Self { backend }
+        Self {
+            backend,
+            config: ResponseCacheConfig::default(),
+        }
+    }
+
+    pub fn with_config(self, config: ResponseCacheConfig) -> Self {
+        Self { config, ..self }
+    }
+
+    pub fn config(&self) -> &ResponseCacheConfig {
+        &self.config
     }
 
     pub fn backend(&self) -> &B {
@@ -221,7 +235,7 @@ where
         response: Value,
         now: Duration,
     ) -> Result<(), Error> {
-        if !request.controls.writes() {
+        if !request.controls.writes() || !self.fits(&response) {
             return Ok(());
         }
         self.backend.set_cache(
@@ -240,7 +254,7 @@ where
         response: Value,
         now: Duration,
     ) -> Result<(), Error> {
-        if !request.controls.writes() {
+        if !request.controls.writes() || !self.fits(&response) {
             return Ok(());
         }
         self.backend
@@ -277,7 +291,7 @@ where
     ) -> Result<(), Error> {
         let writable = entries
             .into_iter()
-            .filter(|(request, _, _)| request.controls.writes())
+            .filter(|(request, response, _)| request.controls.writes() && self.fits(response))
             .map(|(request, response, now)| {
                 (
                     cache_key(&request.key),
@@ -312,6 +326,11 @@ where
         Ok(())
     }
 
+    fn fits(&self, response: &Value) -> bool {
+        self.config.max_entry_bytes == usize::MAX
+            || response.to_string().len() <= self.config.max_entry_bytes
+    }
+
     fn partial_hits(
         requests: &[ResponseCacheRequest<B::Context>],
         readable: Vec<(usize, &ResponseCacheRequest<B::Context>)>,

litellm-rust/crates/cache-response/src/service.rs

@@ -0,0 +1,185 @@
+use std::{future::Future, pin::Pin, time::Duration};
+
+use litellm_cache::{BaseCache, Error, ExactCacheContext};
+use serde_json::Value;
+
+use crate::{
+    CacheControls, CacheEntry, CacheKeyField, CacheKeyInput, ResponseCache, ResponseCacheRequest,
+};
+
+type CacheFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, Error>> + Send + 'a>>;
+
+#[derive(Clone)]
+pub struct ResponseCacheConfig {
+    pub namespace: String,
+    pub max_entry_bytes: usize,
+}
+
+impl Default for ResponseCacheConfig {
+    fn default() -> Self {
+        Self {
+            namespace: String::new(),
+            max_entry_bytes: usize::MAX,
+        }
+    }
+}
+
+pub trait ResponseCacheService: Send + Sync {
+    fn config(&self) -> &ResponseCacheConfig;
+
+    fn lookup<'a>(
+        &'a self,
+        request: &'a ResponseCacheRequest,
+        now: Duration,
+    ) -> CacheFuture<'a, Option<Value>>;
+
+    fn store<'a>(
+        &'a self,
+        request: &'a ResponseCacheRequest,
+        response: Value,
+        now: Duration,
+    ) -> CacheFuture<'a, ()>;
+}
+
+impl<B> ResponseCacheService for ResponseCache<B>
+where
+    B: BaseCache<Value = CacheEntry, Context = ExactCacheContext>,
+{
+    fn config(&self) -> &ResponseCacheConfig {
+        self.config()
+    }
+
+    fn lookup<'a>(
+        &'a self,
+        request: &'a ResponseCacheRequest,
+        now: Duration,
+    ) -> CacheFuture<'a, Option<Value>> {
+        Box::pin(self.async_lookup(request, now))
+    }
+
+    fn store<'a>(
+        &'a self,
+        request: &'a ResponseCacheRequest,
+        response: Value,
+        now: Duration,
+    ) -> CacheFuture<'a, ()> {
+        Box::pin(self.async_store(request, response, now))
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum CacheScope {
+    Shared,
+    Isolated(String),
+}
+
+#[derive(Clone, Copy, Default)]
+pub struct CachePolicy {
+    pub caching: Option<bool>,
+    pub no_cache: bool,
+    pub no_store: bool,
+    pub ttl: Option<Duration>,
+    pub max_age: Option<Duration>,
+}
+
+impl CachePolicy {
+    pub fn enabled(&self) -> bool {
+        self.caching != Some(false) && !(self.no_cache && self.no_store)
+    }
+}
+
+#[derive(Clone)]
+pub struct CacheOptions {
+    pub policy: CachePolicy,
+    pub scope: CacheScope,
+}
+
+impl CacheOptions {
+    pub fn new(scope: CacheScope) -> Self {
+        Self {
+            policy: CachePolicy::default(),
+            scope,
+        }
+    }
+
+    pub fn request(self, namespace: &str, surface: &str, mut input: Value) -> ResponseCacheRequest {
+        input.sort_all_objects();
+        let scope = match self.scope {
+            CacheScope::Shared => String::new(),
+            CacheScope::Isolated(scope) => serde_json::json!(["isolated", scope]).to_string(),
+        };
+        ResponseCacheRequest {
+            key: CacheKeyInput {
+                namespace: Some(format!("{namespace}:inference-v2")),
+                fields: [
+                    ("surface", surface.to_owned()),
+                    ("scope", scope),
+                    ("request", input.to_string()),
+                ]
+                .into_iter()
+                .map(|(name, value)| CacheKeyField {
+                    name: name.into(),
+                    value: Some(value),
+                    api_parameter: true,
+                    internal_parameter: false,
+                })
+                .collect(),
+                ..Default::default()
+            },
+            controls: CacheControls {
+                configured: true,
+                supported_call_type: true,
+                native_backend: true,
+                default_on: true,
+                caching: self.policy.caching,
+                no_cache: self.policy.no_cache,
+                no_store: self.policy.no_store,
+                ..Default::default()
+            },
+            context: ExactCacheContext {
+                ttl: self.policy.ttl,
+            },
+            max_age: self.policy.max_age,
+        }
+    }
+}
+
+#[derive(serde::Serialize, serde::Deserialize)]
+pub struct ResponseEnvelope<T> {
+    version: u32,
+    surface: String,
+    output: T,
+}
+
+impl<T> ResponseEnvelope<T> {
+    pub fn new(surface: &str, output: T) -> Self {
+        Self {
+            version: 1,
+            surface: surface.into(),
+            output,
+        }
+    }
+
+    pub fn decode(self, surface: &str) -> Option<T> {
+        (self.version == 1 && self.surface == surface).then_some(self.output)
+    }
+}
+
+#[derive(Clone)]
+pub struct ScopedCache {
+    pub service: std::sync::Arc<dyn ResponseCacheService>,
+    pub scope: CacheScope,
+}
+
+impl ScopedCache {
+    pub fn new(service: std::sync::Arc<dyn ResponseCacheService>, scope: CacheScope) -> Self {
+        Self { service, scope }
+    }
+
+    pub fn options(&self, policy: Option<CachePolicy>) -> CacheOptions {
+        CacheOptions {
+            policy: policy.unwrap_or_default(),
+            scope: self.scope.clone(),
+        }
+    }
+}

litellm-rust/crates/cache-response/tests/response.rs

@@ -18,7 +18,7 @@ use litellm_cache_response::{
     WriteBuffer, cache_key,
 };
 use redis_test::MockCmd;
-use rstest::rstest;
+use rstest::{fixture, rstest};
 use serde_json::{Value, json};
 use support::{keyed, memory, redis, request};
 
@@ -648,3 +648,129 @@ async fn write_buffer_clear_drops_pending_entries(memory: Memory, request: Respo
     assert_eq!(memory.lookup(&request, now).unwrap(), None);
     assert_eq!(memory.lookup(&other, now).unwrap(), None);
 }
+
+#[rstest]
+#[case::python_sync("{'timestamp': 100.0, 'response': '{\"answer\": 7}'}")]
+#[case::python_async(r#"{"timestamp":100.0,"response":{"answer":7}}"#)]
+#[case::bare_response(r#"{"answer":7}"#)]
+#[tokio::test]
+async fn gcs_reads_python_entries_and_writes_python_compatible_envelopes(
+    #[case] encoded: &str,
+    #[values(false, true)] asynchronous: bool,
+    #[future(awt)] gcs: (wiremock::MockServer, Gcs),
+) {
+    use wiremock::{
+        Mock, ResponseTemplate,
+        matchers::{body_json, header, method, path, query_param},
+    };
+
+    let (server, cache) = gcs;
+    let response = json!({"answer": 7});
+    Mock::given(method("GET"))
+        .and(path("/storage/v1/b/bucket/o/cache%2Fpython"))
+        .and(query_param("alt", "media"))
+        .and(header("authorization", "Bearer token"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(encoded))
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("POST"))
+        .and(path("/upload/storage/v1/b/bucket/o"))
+        .and(query_param("uploadType", "media"))
+        .and(query_param("name", "cache/native"))
+        .and(header("authorization", "Bearer token"))
+        .and(header("content-type", "application/json"))
+        .and(body_json(json!({"timestamp": 102.0, "response": response})))
+        .respond_with(ResponseTemplate::new(200))
+        .expect(1)
+        .mount(&server)
+        .await;
+    let lookup = if asynchronous {
+        cache
+            .async_lookup(&keyed("python"), Duration::from_secs(102))
+            .await
+    } else {
+        cache.lookup(&keyed("python"), Duration::from_secs(102))
+    };
+    assert_eq!(lookup.unwrap(), Some(response.clone()));
+    let request = ResponseCacheRequest {
+        context: litellm_cache::ExactCacheContext {
+            ttl: Some(Duration::from_secs(12)),
+        },
+        ..keyed("native")
+    };
+    let stored = if asynchronous {
+        cache
+            .async_store(&request, response, Duration::from_secs(102))
+            .await
+    } else {
+        cache.store(&request, response, Duration::from_secs(102))
+    };
+    assert_eq!(stored, Ok(()));
+    let requests = server.received_requests().await.unwrap();
+    let upload = requests
+        .iter()
+        .find(|request| request.method.as_str() == "POST")
+        .unwrap();
+    assert_eq!(
+        upload.url.query(),
+        Some("uploadType=media&name=cache%2Fnative")
+    );
+}
+
+#[rstest]
+#[tokio::test]
+async fn gcs_batch_reads_preserve_order_and_treat_invalid_entries_as_misses(
+    #[future(awt)] gcs: (wiremock::MockServer, Gcs),
+) {
+    use wiremock::{
+        Mock, ResponseTemplate,
+        matchers::{method, path},
+    };
+
+    let (server, cache) = gcs;
+    Mock::given(method("GET"))
+        .and(path("/storage/v1/b/bucket/o/cache%2Fhit"))
+        .respond_with(
+            ResponseTemplate::new(200)
+                .set_body_json(json!({"timestamp": 100.0, "response": {"answer":7}})),
+        )
+        .mount(&server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path("/storage/v1/b/bucket/o/cache%2Finvalid"))
+        .respond_with(ResponseTemplate::new(200).set_body_string("not an entry"))
+        .mount(&server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path("/storage/v1/b/bucket/o/cache%2Fmissing"))
+        .respond_with(ResponseTemplate::new(404))
+        .mount(&server)
+        .await;
+    let requests = [keyed("hit"), keyed("missing"), keyed("invalid")];
+    let partial = cache
+        .async_lookup_batch(&requests, Duration::from_secs(102))
+        .await
+        .unwrap();
+    assert_eq!(partial.values, vec![Some(json!({"answer":7})), None, None]);
+    assert_eq!(partial.missing_indices, vec![1, 2]);
+}
+
+type Gcs = ResponseCache<litellm_cache_gcs::GcsCache<litellm_cache_response::ResponseCacheCodec>>;
+
+#[fixture]
+async fn gcs() -> (wiremock::MockServer, Gcs) {
+    let server = wiremock::MockServer::start().await;
+    let cache = ResponseCache::new(Arc::new(litellm_cache_gcs::GcsCache::with_token_source(
+        litellm_cache_gcs::GcsConfig {
+            bucket_name: "bucket".into(),
+            gcs_path: Some("cache".into()),
+            path_service_account: None,
+            endpoint: server.uri(),
+        },
+        litellm_http::Client::plain_for_test(),
+        litellm_cache_response::ResponseCacheCodec,
+        Arc::new(litellm_cache_gcs::StaticTokenSource("token".into())),
+    )));
+    (server, cache)
+}

litellm-rust/crates/cache-response/tests/service.rs

@@ -0,0 +1,185 @@
+use std::{
+    sync::{
+        Arc,
+        atomic::{AtomicU64, Ordering},
+    },
+    time::Duration,
+};
+
+use litellm_cache::ExactCacheContext;
+use litellm_cache_memory::InMemoryCache;
+use litellm_cache_response::{
+    CacheEntry, CacheKeyInput, ResponseCache, ResponseCacheConfig, ResponseCacheRequest,
+    ResponseCacheService,
+};
+use rstest::rstest;
+use serde_json::json;
+
+#[rstest]
+#[tokio::test]
+async fn service_honors_per_call_expiry_and_freshness() {
+    let clock = Arc::new(AtomicU64::new(0));
+    let cache_clock = clock.clone();
+    let cache: Arc<dyn ResponseCacheService> = Arc::new(ResponseCache::new(Arc::new(
+        InMemoryCache::with_clock(Some(100), Some(Duration::from_secs(60)), move || {
+            Duration::from_secs(cache_clock.load(Ordering::SeqCst))
+        }),
+    )));
+    let request = ResponseCacheRequest {
+        context: ExactCacheContext {
+            ttl: Some(Duration::from_secs(5)),
+        },
+        ..ResponseCacheRequest::new(CacheKeyInput {
+            preset: Some("entry".into()),
+            ..Default::default()
+        })
+    };
+    cache
+        .store(&request, json!({"answer":7}), Duration::ZERO)
+        .await
+        .unwrap();
+    assert_eq!(
+        cache.lookup(&request, Duration::ZERO).await.unwrap(),
+        Some(json!({"answer":7}))
+    );
+    let stale_request = ResponseCacheRequest {
+        max_age: Some(Duration::from_secs(1)),
+        ..request.clone()
+    };
+    clock.store(2, Ordering::SeqCst);
+    assert_eq!(
+        cache
+            .lookup(&stale_request, Duration::from_secs(2))
+            .await
+            .unwrap(),
+        None
+    );
+    assert!(
+        cache
+            .lookup(&request, Duration::from_secs(2))
+            .await
+            .unwrap()
+            .is_some()
+    );
+    clock.store(6, Ordering::SeqCst);
+    assert_eq!(
+        cache
+            .lookup(&request, Duration::from_secs(6))
+            .await
+            .unwrap(),
+        None
+    );
+}
+
+#[rstest]
+#[tokio::test]
+async fn entry_limit_applies_to_sync_async_and_batch_writes() {
+    let storage = Arc::new(InMemoryCache::<CacheEntry>::default());
+    let cache = ResponseCache::new(storage.clone()).with_config(ResponseCacheConfig {
+        namespace: "service-test".into(),
+        max_entry_bytes: json!({"answer":7}).to_string().len(),
+    });
+    let small = json!({"answer":7});
+    let large = json!({"answer":"too large"});
+    let request = |key: &str| {
+        ResponseCacheRequest::new(CacheKeyInput {
+            preset: Some(key.into()),
+            ..Default::default()
+        })
+    };
+    cache
+        .store(&request("sync"), large.clone(), Duration::ZERO)
+        .unwrap();
+    cache
+        .async_store(&request("async"), large.clone(), Duration::ZERO)
+        .await
+        .unwrap();
+    cache
+        .async_store_batch(
+            vec![
+                (request("batch-large"), large),
+                (request("batch-small"), small.clone()),
+            ],
+            Duration::ZERO,
+        )
+        .await
+        .unwrap();
+    let service: Arc<dyn ResponseCacheService> = Arc::new(cache);
+    service
+        .store(&request("service"), small.clone(), Duration::ZERO)
+        .await
+        .unwrap();
+    for key in ["sync", "async", "batch-large"] {
+        assert!(storage.get_cache(key).unwrap().is_none());
+    }
+    for key in ["batch-small", "service"] {
+        assert_eq!(
+            service.lookup(&request(key), Duration::ZERO).await.unwrap(),
+            Some(small.clone())
+        );
+    }
+}
+
+#[rstest]
+#[case::same_scope("tenant-a", "tenant-a", true)]
+#[case::different_scope("tenant-a", "tenant-b", false)]
+#[case::empty_isolated_scope("", "", true)]
+#[tokio::test]
+async fn isolated_policy_controls_actual_entry_reuse(
+    #[case] first: &str,
+    #[case] second: &str,
+    #[case] hit: bool,
+    #[values(false, true)] override_policy: bool,
+) {
+    use litellm_cache_response::{CachePolicy, CacheScope, ScopedCache};
+    let service = Arc::new(ResponseCache::new(Arc::new(
+        InMemoryCache::<CacheEntry>::default(),
+    )));
+    let request = |scope| {
+        ScopedCache::new(service.clone(), scope)
+            .options(override_policy.then_some(CachePolicy {
+                ttl: Some(Duration::from_secs(30)),
+                ..CachePolicy::default()
+            }))
+            .request("test", "messages", json!({"prompt":"hello"}))
+    };
+    service
+        .async_store(
+            &request(CacheScope::Isolated(first.into())),
+            json!({"answer":7}),
+            Duration::ZERO,
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        service
+            .async_lookup(
+                &request(CacheScope::Isolated(second.into())),
+                Duration::ZERO
+            )
+            .await
+            .unwrap(),
+        hit.then(|| json!({"answer":7}))
+    );
+    assert_eq!(
+        service
+            .async_lookup(&request(CacheScope::Shared), Duration::ZERO)
+            .await
+            .unwrap(),
+        None
+    );
+}
+
+#[rstest]
+#[case::valid(1, "messages", Some(7))]
+#[case::unknown_version(2, "messages", None)]
+#[case::another_surface(1, "responses", None)]
+fn envelopes_require_a_matching_surface_and_version(
+    #[case] version: u32,
+    #[case] surface: &str,
+    #[case] expected: Option<u32>,
+) {
+    let envelope: litellm_cache_response::ResponseEnvelope<u32> =
+        serde_json::from_value(json!({"version":version,"surface":surface,"output":7})).unwrap();
+    assert_eq!(envelope.decode("messages"), expected);
+}

litellm-rust/crates/callbacks-legacy-python/AGENTS.md

@@ -7,6 +7,7 @@
   - The enum only shrinks: when Rust owns a subsystem, delete its group rather than adding a Rust path beside it
   - Calling a user's own callback directly is permanent Python surface and gets its own type outside `LegacyPython`
 - `PublicCall` is the caller's call as `Logging` sees it: the positional arguments, the keyword view as the call rewrites it (setup, deployment hook, preflight) and the bound request object backing omitted keywords; shared bridge composition hands it to `LegacyLogging`; routes use the neutral call boundary
+- `LoggingOperation` selects legacy logging entrypoints and response handling. It belongs here rather than in shared inference data contracts
 - `setup` reuses a `Logging` passed as `litellm_logging_obj` (the proxy and Router) and otherwise builds one through `function_setup`; which callbacks run is `Logging`'s decision, never this crate's
 - Callbacks receive the caller's own objects and may mutate them; this crate alone carries that obligation
   - Retain complete boundary arguments, opaque values, aliases, omitted/default distinctions and deliberate copies; preserve the deployment-hook kwargs view

litellm-rust/crates/callbacks-legacy-python/Cargo.toml

@@ -6,7 +6,6 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
-litellm-types.workspace = true
 litellm-host.workspace = true
 litellm-host-python.workspace = true
 

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

@@ -2,8 +2,8 @@
 //! raises is answered with the same `Logging` calls, in the same order, as the Python
 //! `@client` path makes them.
 
+use crate::LoggingOperation;
 use litellm_host_python::PythonOwned;
-use litellm_types::Operation;
 
 use litellm_host::{
     interceptors::{RawResponse, RequestContext, WireRequest},
@@ -45,7 +45,7 @@ struct LoggedRequest {
 }
 
 pub struct LegacyLogging {
-    operation: Operation,
+    operation: LoggingOperation,
     call: PublicCall,
     logger: Option<PythonLogger>,
     start: Py<PyAny>,
@@ -56,6 +56,7 @@ pub struct LegacyLogging {
     stream: Option<DeliveredStream>,
     asynchronous: bool,
     internal: bool,
+    cache_key: Option<String>,
 }
 
 fn datetime(py: Python<'_>, epoch_seconds: f64) -> PyResult<Py<PyAny>> {
@@ -67,7 +68,12 @@ fn is_cancellation(py: Python<'_>, error: &PyErr) -> bool {
 }
 
 impl LegacyLogging {
-    pub fn new(py: Python<'_>, operation: Operation, call: PublicCall, asynchronous: bool) -> Self {
+    pub fn new(
+        py: Python<'_>,
+        operation: LoggingOperation,
+        call: PublicCall,
+        asynchronous: bool,
+    ) -> Self {
         Self {
             operation,
             call,
@@ -80,37 +86,40 @@ impl LegacyLogging {
             stream: None,
             asynchronous,
             internal: false,
+            cache_key: None,
         }
     }
 
     fn call_type(&self) -> &'static str {
         match (self.operation, self.asynchronous) {
-            (Operation::Completion, false) => "completion",
-            (Operation::Completion, true) => "acompletion",
-            (Operation::Responses, false) => "responses",
-            (Operation::Responses, true) => "aresponses",
-            (Operation::Messages, _) => "anthropic_messages",
-            (Operation::Ocr, false) => "ocr",
-            (Operation::Ocr, true) => "aocr",
+            (LoggingOperation::Completion, false) => "completion",
+            (LoggingOperation::Completion, true) => "acompletion",
+            (LoggingOperation::Responses, false) => "responses",
+            (LoggingOperation::Responses, true) => "aresponses",
+            (LoggingOperation::Messages, _) => "anthropic_messages",
+            (LoggingOperation::Ocr, false) => "ocr",
+            (LoggingOperation::Ocr, true) => "aocr",
         }
     }
 
     fn input_description(&self) -> &'static str {
         match self.operation {
-            Operation::Completion => "Chat completions",
-            Operation::Responses => "Responses",
-            Operation::Messages => "Messages",
-            Operation::Ocr => "OCR document processing",
+            LoggingOperation::Completion => "Chat completions",
+            LoggingOperation::Responses => "Responses",
+            LoggingOperation::Messages => "Messages",
+            LoggingOperation::Ocr => "OCR document processing",
         }
     }
 
     fn stream_billing(&self) -> Option<PassThroughStream> {
         match self.operation {
-            Operation::Messages => Some(PassThroughStream {
+            LoggingOperation::Messages => Some(PassThroughStream {
                 url_route: "/v1/messages",
                 endpoint_type: "anthropic",
             }),
-            Operation::Completion | Operation::Responses | Operation::Ocr => None,
+            LoggingOperation::Completion | LoggingOperation::Responses | LoggingOperation::Ocr => {
+                None
+            }
         }
     }
 
@@ -207,10 +216,10 @@ impl LegacyLogging {
                 logger.object(py),
                 billing.url_route,
                 billing.endpoint_type,
-                &self
-                    .request
-                    .as_ref()
-                    .map(|request| request.body.clone_ref(py)),
+                &self.request.as_ref().map_or_else(
+                    || self.call.kwargs().clone_ref(py),
+                    |request| request.body.clone_ref(py),
+                ),
                 &stream.chunks,
                 &self.start,
                 &self.end,
@@ -246,10 +255,10 @@ impl LegacyLogging {
             (
                 logger.object(py),
                 billing.endpoint_type,
-                &self
-                    .request
-                    .as_ref()
-                    .map(|request| request.body.clone_ref(py)),
+                &self.request.as_ref().map_or_else(
+                    || self.call.kwargs().clone_ref(py),
+                    |request| request.body.clone_ref(py),
+                ),
                 &stream.chunks,
                 error,
             ),
@@ -428,6 +437,40 @@ impl LegacyLogging {
         self.finalize(py)
     }
 
+    pub(crate) fn result_ready(
+        &mut self,
+        py: Python<'_>,
+        facts: &litellm_host::interceptors::ExecutionFacts,
+    ) -> PyResult<HookStep<Self, ()>> {
+        use litellm_host::interceptors::ResultSource;
+
+        let logger = self.logger()?.object(py);
+        let params = logger
+            .getattr("litellm_params")?
+            .cast_into::<PyDict>()?
+            .copy()?;
+        params.set_item("custom_llm_provider", &facts.provider.provider)?;
+        crate::python::Logging::Update.call(
+            py,
+            (
+                &logger,
+                self.call.kwargs(),
+                &facts.provider.model,
+                logger.getattr("optional_params")?,
+                params,
+                &facts.provider.provider,
+            ),
+        )?;
+        let details = logger.getattr("model_call_details")?;
+        self.cache_key = match &facts.source {
+            ResultSource::Provider => None,
+            ResultSource::Cache { key } => Some(key.clone()),
+        };
+        details.set_item("cache_hit", self.cache_key.is_some())?;
+        details.set_item("cache_key", self.cache_key.as_deref())?;
+        Ok(HookStep::Ready(()))
+    }
+
     pub(crate) fn post_call(
         &mut self,
         py: Python<'_>,
@@ -485,10 +528,14 @@ impl LegacyLogging {
         self.dispatch_failure(py)
     }
 
-    pub(crate) fn stream_opened(&mut self, py: Python<'_>) -> PyResult<()> {
+    pub(crate) fn stream_opened(&mut self, py: Python<'_>, head: &Py<PyAny>) -> PyResult<()> {
         if self.stream_billing().is_none() {
             return Err(missing_state());
         }
+        if let Some(key) = &self.cache_key {
+            head.bind(py).set_item("cache_key", key)?;
+            head.bind(py).set_item("cache_hit", true)?;
+        }
         Streaming::Opened.call(py, (self.logger()?.object(py),))?;
         self.stream = Some(DeliveredStream {
             chunks: PyList::empty(py).unbind(),
@@ -603,16 +650,16 @@ kwargs = {'logger': logger, 'document': document}
     }
 
     #[rstest]
-    #[case::sync_completion(litellm_types::Operation::Completion, false, "completion")]
-    #[case::async_completion(litellm_types::Operation::Completion, true, "acompletion")]
-    #[case::sync_responses(litellm_types::Operation::Responses, false, "responses")]
-    #[case::async_responses(litellm_types::Operation::Responses, true, "aresponses")]
-    #[case::sync_messages(litellm_types::Operation::Messages, false, "anthropic_messages")]
-    #[case::async_messages(litellm_types::Operation::Messages, true, "anthropic_messages")]
-    #[case::sync_ocr(litellm_types::Operation::Ocr, false, "ocr")]
-    #[case::async_ocr(litellm_types::Operation::Ocr, true, "aocr")]
+    #[case::sync_completion(crate::LoggingOperation::Completion, false, "completion")]
+    #[case::async_completion(crate::LoggingOperation::Completion, true, "acompletion")]
+    #[case::sync_responses(crate::LoggingOperation::Responses, false, "responses")]
+    #[case::async_responses(crate::LoggingOperation::Responses, true, "aresponses")]
+    #[case::sync_messages(crate::LoggingOperation::Messages, false, "anthropic_messages")]
+    #[case::async_messages(crate::LoggingOperation::Messages, true, "anthropic_messages")]
+    #[case::sync_ocr(crate::LoggingOperation::Ocr, false, "ocr")]
+    #[case::async_ocr(crate::LoggingOperation::Ocr, true, "aocr")]
     fn operation_selects_the_legacy_setup_and_deployment_hook_contract(
-        #[case] operation: litellm_types::Operation,
+        #[case] operation: crate::LoggingOperation,
         #[case] asynchronous: bool,
         #[case] expected: &str,
     ) {
@@ -1048,12 +1095,12 @@ check = lambda: None
     }
 
     #[rstest]
-    #[case::completion(litellm_types::Operation::Completion, "Chat completions")]
-    #[case::responses(litellm_types::Operation::Responses, "Responses")]
-    #[case::messages(litellm_types::Operation::Messages, "Messages")]
-    #[case::ocr(litellm_types::Operation::Ocr, "OCR document processing")]
+    #[case::completion(crate::LoggingOperation::Completion, "Chat completions")]
+    #[case::responses(crate::LoggingOperation::Responses, "Responses")]
+    #[case::messages(crate::LoggingOperation::Messages, "Messages")]
+    #[case::ocr(crate::LoggingOperation::Ocr, "OCR document processing")]
     fn prepared_arguments_replace_the_legacy_view_without_losing_callback_aliases(
-        #[case] operation: litellm_types::Operation,
+        #[case] operation: crate::LoggingOperation,
         #[case] description: &str,
     ) {
         Python::initialize();
@@ -1723,10 +1770,12 @@ assert logger.calls[1][1] is response
         Python::attach(|py| {
             let locals = namespace(py, c"first = b'first'\nlast = b'last'\nresponse = None");
             let mut logging = LegacyLogging {
-                operation: litellm_types::Operation::Messages,
+                operation: crate::LoggingOperation::Messages,
                 ..logged(py, &locals, true)
             };
-            logging.on_stream_open(py).unwrap();
+            logging
+                .on_stream_open(py, &pyo3::types::PyDict::new(py).into_any().unbind())
+                .unwrap();
             logging
                 .on_stream_chunk(py, &local(&locals, "first").unbind())
                 .unwrap();

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

@@ -20,5 +20,13 @@ pub(crate) use callbacks::{LegacyCallbacks, is_internal_call};
 pub(crate) use logger::{DeploymentHooks, PythonLogger, finalize, setup};
 pub use mapping::{CallBoundary, CallbackMapping, Dispatch, callback_mappings};
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum LoggingOperation {
+    Completion,
+    Responses,
+    Messages,
+    Ocr,
+}
+
 #[cfg(test)]
 mod test_support;

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

@@ -56,7 +56,7 @@ type After = fn(&mut LegacyLogging, Python<'_>, &RawResponse) -> Step<()>;
 type Transform = fn(&mut LegacyLogging, Python<'_>, Py<PyAny>, Timing) -> Step<Py<PyAny>>;
 type Success = fn(&mut LegacyLogging, Python<'_>, Timing, &Py<PyAny>) -> Step<()>;
 type Failure = fn(&mut LegacyLogging, Python<'_>, Timing, FailureOrigin, &PyErr) -> Step<()>;
-type Open = fn(&mut LegacyLogging, Python<'_>) -> PyResult<()>;
+type Open = fn(&mut LegacyLogging, Python<'_>, &Py<PyAny>) -> PyResult<()>;
 type Chunk = fn(&mut LegacyLogging, Python<'_>, &Py<PyAny>) -> PyResult<()>;
 
 const PREPARE: Binding<Prepare> = Binding {
@@ -173,6 +173,9 @@ impl CallHooks<PythonRuntime> for LegacyLogging {
             PythonCallEvent::Started { .. } | PythonCallEvent::Cancelled { .. } => {
                 Ok(HookStep::Ready(()))
             }
+            PythonCallEvent::Execution(ExecutionEvent::ResultReady { facts }) => {
+                self.result_ready(py, &facts)
+            }
             PythonCallEvent::Execution(ExecutionEvent::ProviderResponseReceived { raw }) => {
                 (AFTER.invoke)(self, py, raw)
             }
@@ -187,8 +190,8 @@ impl CallHooks<PythonRuntime> for LegacyLogging {
         }
     }
 
-    fn on_stream_open(&mut self, py: Python<'_>) -> PyResult<()> {
-        (OPEN.invoke)(self, py)
+    fn on_stream_open(&mut self, py: Python<'_>, head: &Py<PyAny>) -> PyResult<()> {
+        (OPEN.invoke)(self, py, head)
     }
 
     fn on_stream_chunk(&mut self, py: Python<'_>, chunk: &Py<PyAny>) -> PyResult<()> {

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

@@ -189,5 +189,5 @@ pub(crate) fn legacy_call(
         .map(|kwargs| kwargs.cast_into::<PyDict>().unwrap())
         .unwrap_or_else(|| PyDict::new(py));
     let call = PublicCall::capture(&request, &PyTuple::empty(py), &kwargs).unwrap();
-    LegacyLogging::new(py, litellm_types::Operation::Ocr, call, asynchronous)
+    LegacyLogging::new(py, crate::LoggingOperation::Ocr, call, asynchronous)
 }

litellm-rust/crates/core-utils/Cargo.toml

@@ -8,11 +8,10 @@ repository.workspace = true
 [dependencies]
 fancy-regex.workspace = true
 litellm-tracing.workspace = true
-litellm-types.workspace = true
+litellm-llms-types.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 serde_path_to_error = "0.1"
-serde_with.workspace = true
 strum.workspace = true
 thiserror.workspace = true
 url.workspace = true

litellm-rust/crates/core-utils/src/core_helpers.rs

@@ -2,7 +2,7 @@
 
 use std::time::{SystemTime, UNIX_EPOCH};
 
-use litellm_types::utils::{ChatCompletionsUsage, PromptTokensDetails};
+use litellm_llms_types::formats::chat_completions::{ChatCompletionsUsage, PromptTokensDetails};
 
 /// OpenAI finish reasons, mirroring Python's `_FINISH_REASON_MAP` for the
 /// reasons the providers on this route can emit. Python warns and falls back to

litellm-rust/crates/core-utils/src/get_provider_specific_headers.rs

@@ -1,4 +1,4 @@
-use litellm_types::utils::{ProviderSpecificHeader, ProviderSpecificHeaders};
+use litellm_llms_types::headers::{ProviderSpecificHeader, ProviderSpecificHeaders};
 use serde_json::{Map, Value};
 
 pub fn get_provider_specific_headers(

litellm-rust/crates/core-utils/src/prompt_templates/factory.rs

@@ -10,7 +10,7 @@
 //! `_bedrock_converse_messages_pt` for the text-only surface this route
 //! accepts; anything richer is declined upstream by the capability gate.
 
-use litellm_types::llms::openai::{ChatMessage, ChatMessageContent};
+use litellm_llms_types::formats::chat_completions::{ChatMessage, ChatMessageContent};
 use strum::IntoStaticStr;
 
 pub const EMPTY_TEXT_PLACEHOLDER: &str =

litellm-rust/crates/core-utils/src/serde_compat.rs

@@ -1,12 +1,3 @@
-use serde::{
-    Deserializer,
-    de::{Error, Visitor},
-};
-use serde_with::DeserializeAs;
-
-pub struct LaxI64;
-pub struct FiniteF64;
-
 pub fn parse_str_bool(value: &str) -> Option<bool> {
     let token = value.trim_matches(|character: char| {
         character.is_whitespace() || matches!(character, '\u{1c}'..='\u{1f}')
@@ -22,129 +13,12 @@ pub fn parse_redis_bool(value: &str) -> bool {
     value == "1" || value.eq_ignore_ascii_case("true") || value.eq_ignore_ascii_case("yes")
 }
 
-impl<'de> DeserializeAs<'de, i64> for LaxI64 {
-    fn deserialize_as<D: Deserializer<'de>>(deserializer: D) -> Result<i64, D::Error> {
-        deserializer.deserialize_any(Self)
-    }
-}
-
-impl<'de> Visitor<'de> for LaxI64 {
-    type Value = i64;
-
-    fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        formatter.write_str("an integer in the i64 range")
-    }
-
-    fn visit_i64<E: Error>(self, value: i64) -> Result<i64, E> {
-        Ok(value)
-    }
-
-    fn visit_u64<E: Error>(self, value: u64) -> Result<i64, E> {
-        i64::try_from(value).map_err(E::custom)
-    }
-
-    fn visit_f64<E: Error>(self, value: f64) -> Result<i64, E> {
-        integral_float(value).ok_or_else(|| E::custom("expected an integer in the i64 range"))
-    }
-
-    fn visit_str<E: Error>(self, value: &str) -> Result<i64, E> {
-        integer_string(value.trim())
-            .ok_or_else(|| E::custom("expected an integer in the i64 range"))
-    }
-
-    fn visit_bool<E: Error>(self, value: bool) -> Result<i64, E> {
-        Ok(i64::from(value))
-    }
-}
-
-impl<'de> DeserializeAs<'de, f64> for FiniteF64 {
-    fn deserialize_as<D: Deserializer<'de>>(deserializer: D) -> Result<f64, D::Error> {
-        deserializer.deserialize_any(Self)
-    }
-}
-
-impl<'de> Visitor<'de> for FiniteF64 {
-    type Value = f64;
-
-    fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        formatter.write_str("a finite number")
-    }
-
-    fn visit_i64<E: Error>(self, value: i64) -> Result<f64, E> {
-        Ok(value as f64)
-    }
-
-    fn visit_u64<E: Error>(self, value: u64) -> Result<f64, E> {
-        Ok(value as f64)
-    }
-
-    fn visit_f64<E: Error>(self, value: f64) -> Result<f64, E> {
-        value
-            .is_finite()
-            .then_some(value)
-            .ok_or_else(|| E::custom("expected a finite number"))
-    }
-
-    fn visit_str<E: Error>(self, value: &str) -> Result<f64, E> {
-        self.visit_f64(value.trim().parse::<f64>().map_err(E::custom)?)
-    }
-
-    fn visit_bool<E: Error>(self, value: bool) -> Result<f64, E> {
-        Ok(f64::from(value))
-    }
-}
-
-fn integer_string(value: &str) -> Option<i64> {
-    let integer = match value.split_once('.') {
-        Some((integer, fraction)) => {
-            if fraction.is_empty() || !fraction.bytes().all(|byte| byte == b'0') {
-                return None;
-            }
-            integer
-        }
-        None => value,
-    };
-    if integer.starts_with('_') || integer.ends_with('_') || integer.contains("__") {
-        return None;
-    }
-    let digits = integer.strip_prefix(['+', '-']).unwrap_or(integer);
-    if digits.is_empty()
-        || digits.starts_with('_')
-        || !digits
-            .bytes()
-            .all(|byte| byte.is_ascii_digit() || byte == b'_')
-    {
-        return None;
-    }
-    integer.replace('_', "").parse().ok()
-}
-
-fn integral_float(value: f64) -> Option<i64> {
-    (value.is_finite()
-        && value.fract() == 0.0
-        && value >= i64::MIN as f64
-        && value < -(i64::MIN as f64))
-        .then_some(value as i64)
-}
-
 #[cfg(test)]
 mod tests {
     use rstest::rstest;
-    use serde::{Deserialize, Serialize};
-    use serde_json::json;
-    use serde_with::serde_as;
 
     use super::*;
 
-    #[serde_as]
-    #[derive(Debug, Deserialize, Serialize, PartialEq)]
-    struct Numbers {
-        #[serde_as(deserialize_as = "Option<Vec<LaxI64>>")]
-        integers: Option<Vec<i64>>,
-        #[serde_as(deserialize_as = "Option<FiniteF64>")]
-        float: Option<f64>,
-    }
-
     #[rstest]
     #[case::trimmed_true(" True ", Some(true))]
     #[case::control_whitespace_true("\u{1c}TRUE\u{1f}", Some(true))]
@@ -160,73 +34,4 @@ mod tests {
     ) {
         assert_eq!(parse_str_bool(input), expected, "{input:?}");
     }
-
-    #[test]
-    fn adapters_compose_and_serialize_as_numbers() {
-        let numbers: Numbers = serde_json::from_value(json!({
-            "integers": ["9007199254740993.0", "1_000", " +2.000 ", 3.0, true],
-            "float": " 1.5 "
-        }))
-        .unwrap();
-        assert_eq!(
-            serde_json::to_value(numbers).unwrap(),
-            json!({
-                "integers": [9_007_199_254_740_993_i64, 1000, 2, 3, 1], "float": 1.5
-            })
-        );
-        for input in [json!({}), json!({"integers": null, "float": null})] {
-            assert_eq!(
-                serde_json::from_value::<Numbers>(input).unwrap(),
-                Numbers {
-                    integers: None,
-                    float: None,
-                }
-            );
-        }
-    }
-
-    #[test]
-    fn integer_bounds_and_invalid_values_are_checked() {
-        for input in [
-            json!(i64::MIN),
-            json!(i64::MAX),
-            json!(i64::MAX.to_string()),
-        ] {
-            assert!(serde_json::from_value::<Numbers>(json!({"integers": [input]})).is_ok());
-        }
-        for input in [
-            json!(u64::MAX),
-            json!(9_223_372_036_854_775_808_u64),
-            json!(9_223_372_036_854_775_808.0),
-            json!("-9223372036854775809"),
-            json!("1.0000000000000001"),
-            json!("1e3"),
-            json!("2."),
-            json!(".0"),
-            json!("_2"),
-            json!("2__0"),
-            json!(2.5),
-            json!(null),
-            json!({}),
-        ] {
-            assert!(serde_json::from_value::<Numbers>(json!({"integers": [input]})).is_err());
-        }
-    }
-
-    #[test]
-    fn floats_reject_nonfinite_and_invalid_values() {
-        for input in [
-            json!("NaN"),
-            json!("inf"),
-            json!("-inf"),
-            json!("1e999"),
-            json!([]),
-        ] {
-            assert!(serde_json::from_value::<Numbers>(json!({"float": input})).is_err());
-        }
-        for (input, expected) in [(json!(2), 2.0), (json!(2.5), 2.5), (json!(true), 1.0)] {
-            let numbers: Numbers = serde_json::from_value(json!({"float": input})).unwrap();
-            assert_eq!(numbers.float, Some(expected));
-        }
-    }
 }

litellm-rust/crates/core/AGENTS.md

@@ -10,11 +10,11 @@ Responses WebSocket sessions remain separate from the HTTP call driver because a
 
 ## Crate layering
 
-For Messages, Responses, Chat Completions, OCR, and other API formats, `core/src/<format>/` owns orchestration. Shared API data contracts belong in `litellm-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
+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
 
-Each crate mirrors one top-level Python package, so a Rust path reads as its Python path with the crate name in place of the package directory. Dependencies only point down:
+Crates separate API data, transformations, transport, and orchestration. Python package names identify counterparts, not ownership. Dependencies only point down:
 
-- `litellm-types` mirrors `litellm/types/`: pure serde data, no I/O
+- `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)
@@ -33,3 +33,17 @@ Scope follows the concept, not the first caller. An error type under `litellm-ll
 `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/Cargo.toml

@@ -6,8 +6,12 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
+litellm-cache.workspace = true
+litellm-cache-response.workspace = true
+litellm-framing.workspace = true
+tokio-util = { version = "0.7", features = ["codec"] }
 litellm-secrets.workspace = true
-litellm-types.workspace = true
+litellm-llms-types.workspace = true
 litellm-core-utils.workspace = true
 litellm-host.workspace = true
 bytes.workspace = true
@@ -36,6 +40,7 @@ url.workspace = true
 veil.workspace = true
 
 [dev-dependencies]
+litellm-cache-memory.workspace = true
 litellm-http = { workspace = true, features = ["test-support"] }
 litellm-auth-gcp.workspace = true
 litellm-host-native.workspace = true

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

@@ -0,0 +1,376 @@
+use std::{
+    future::Future,
+    marker::PhantomData,
+    sync::Arc,
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use bytes::{Bytes, BytesMut};
+use futures_util::{StreamExt, TryStreamExt, stream};
+use litellm_cache_response::{
+    CacheOptions, CachePolicy, ResponseCacheRequest, ResponseCacheService, ResponseEnvelope,
+    ScopedCache, cache_key,
+};
+use litellm_host::{
+    call::{CallOutput, OutputOf},
+    interceptors::{ExecutionFacts, Interceptors, ProviderIdentity, ResultSource, WireRequest},
+    lifecycle::{CallEvent, ExecutionEvent},
+    observation::ObservationSender,
+    protocol::Protocol,
+};
+use serde::{Deserialize, Serialize, de::DeserializeOwned};
+use serde_json::Value;
+use tokio_util::codec::Decoder;
+
+use crate::RouteError;
+
+pub trait Cachable: Protocol<Error = RouteError> {
+    const SURFACE: &'static str;
+
+    fn reusable(_response: &Self::Response) -> bool {
+        true
+    }
+}
+
+pub struct CacheRequest {
+    pub identity: ProviderIdentity,
+    pub input: Value,
+}
+
+impl CacheRequest {
+    pub fn from_wire(identity: ProviderIdentity, wire: Option<&WireRequest>) -> Self {
+        Self {
+            input: wire.map_or(Value::Null, |wire| {
+                serde_json::json!({
+                    "provider": identity.provider,
+                    "model": identity.model,
+                    "url": wire.url,
+                    "headers": wire.headers,
+                    "body": wire.body,
+                })
+            }),
+            identity,
+        }
+    }
+}
+
+pub trait StreamCachable: Cachable {
+    const TERMINAL_EVENT: &'static str;
+
+    fn replay(data: Bytes) -> Option<OutputOf<Self>>;
+    fn bytes(chunk: &Self::Chunk) -> &[u8];
+}
+
+#[derive(Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value")]
+pub enum CachedOutput<R> {
+    Response(R),
+    Stream(String),
+}
+
+struct CacheSession {
+    service: Arc<dyn ResponseCacheService>,
+    request: ResponseCacheRequest,
+}
+
+impl CacheSession {
+    fn prepare<P: Cachable>(
+        service: Option<Arc<dyn ResponseCacheService>>,
+        options: Option<CacheOptions>,
+        request: &CacheRequest,
+    ) -> Option<Self> {
+        let options = options.filter(|options| options.policy.enabled())?;
+        let service = service?;
+        let input = request.input.clone();
+        let request = options.request(&service.config().namespace, P::SURFACE, input);
+        Some(Self { service, request })
+    }
+
+    async fn lookup<P: Cachable>(&self) -> Option<CachedOutput<P::Response>>
+    where
+        P::Response: DeserializeOwned,
+    {
+        if !self.request.controls.reads() {
+            return None;
+        }
+        match self.service.lookup(&self.request, now()).await {
+            Ok(Some(value)) => {
+                serde_json::from_value::<ResponseEnvelope<CachedOutput<P::Response>>>(value)
+                    .ok()
+                    .and_then(|entry| entry.decode(P::SURFACE))
+            }
+            Ok(None) => None,
+            Err(_) => {
+                tracing::warn!("response cache lookup failed");
+                None
+            }
+        }
+    }
+
+    async fn store(&self, entry: Value) {
+        if !self.request.controls.writes() {
+            return;
+        }
+        if self
+            .service
+            .store(&self.request, entry, now())
+            .await
+            .is_err()
+        {
+            tracing::warn!("response cache write failed");
+        }
+    }
+
+    async fn store_response<P: Cachable>(&self, response: &P::Response)
+    where
+        P::Response: Serialize,
+    {
+        if !self.request.controls.writes() || !P::reusable(response) {
+            return;
+        }
+        if let Ok(value) = serde_json::to_value(response)
+            && let Ok(entry) = serde_json::to_value(ResponseEnvelope::new(
+                P::SURFACE,
+                CachedOutput::Response(value),
+            ))
+        {
+            self.store(entry).await;
+        }
+    }
+}
+
+pub async fn execute_unary<P, F, Fut>(
+    request: CacheRequest,
+    cache: Option<Arc<dyn ResponseCacheService>>,
+    options: Option<CacheOptions>,
+    interceptors: &impl Interceptors<RouteError>,
+    observers: Option<&ObservationSender>,
+    provider: F,
+) -> Result<P::Response, RouteError>
+where
+    P: Cachable,
+    P::Response: Serialize + DeserializeOwned,
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<P::Response, RouteError>>,
+{
+    let identity = request.identity.clone();
+    crate::diagnostic::provider(&identity.model, &identity.provider);
+    let session = CacheSession::prepare::<P>(cache, options, &request);
+    let hit = match &session {
+        Some(session) => session.lookup::<P>().await.and_then(|entry| match entry {
+            CachedOutput::Response(response) => Some((response, cache_key(&session.request.key))),
+            CachedOutput::Stream(_) => None,
+        }),
+        None => None,
+    };
+    let (response, source) = match hit {
+        Some((response, key)) => (response, ResultSource::Cache { key }),
+        None => (provider().await?, ResultSource::Provider),
+    };
+    let from_provider = source == ResultSource::Provider;
+    publish(
+        ExecutionFacts {
+            provider: identity,
+            source,
+        },
+        interceptors,
+        observers,
+    )
+    .await?;
+    if from_provider && let Some(session) = session {
+        session.store_response::<P>(&response).await;
+    }
+    Ok(response)
+}
+
+pub async fn execute_streaming<P, F, Fut>(
+    request: CacheRequest,
+    cache: Option<Arc<dyn ResponseCacheService>>,
+    options: Option<CacheOptions>,
+    interceptors: &impl Interceptors<RouteError>,
+    observers: Option<&ObservationSender>,
+    provider: F,
+) -> Result<OutputOf<P>, RouteError>
+where
+    P: StreamCachable,
+    P::Response: Serialize + DeserializeOwned,
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = Result<OutputOf<P>, RouteError>>,
+{
+    let identity = request.identity.clone();
+    crate::diagnostic::provider(&identity.model, &identity.provider);
+    let session = CacheSession::prepare::<P>(cache, options, &request);
+    let cache = CallCache::<P> {
+        session,
+        protocol: PhantomData,
+    };
+    let hit = cache.lookup().await;
+    let (output, source) = match hit {
+        Some(hit) => hit,
+        None => (provider().await?, ResultSource::Provider),
+    };
+    publish(
+        ExecutionFacts {
+            provider: identity,
+            source: source.clone(),
+        },
+        interceptors,
+        observers,
+    )
+    .await?;
+    Ok(cache.finish(output, &source).await)
+}
+
+pub(crate) struct CallCache<P> {
+    session: Option<CacheSession>,
+    protocol: PhantomData<P>,
+}
+
+impl<P: StreamCachable> CallCache<P> {
+    pub(crate) fn from_wire(
+        cache: Option<&ScopedCache>,
+        policy: CachePolicy,
+        identity: &ProviderIdentity,
+        wire: &WireRequest,
+    ) -> Self {
+        let session = cache.and_then(|cache| {
+            if !policy.enabled() {
+                return None;
+            }
+            let options = cache.options(Some(policy));
+            let request = CacheRequest::from_wire(identity.clone(), Some(wire));
+            Some(CacheSession {
+                request: options.request(
+                    &cache.service.config().namespace,
+                    P::SURFACE,
+                    request.input,
+                ),
+                service: cache.service.clone(),
+            })
+        });
+        Self {
+            session,
+            protocol: PhantomData,
+        }
+    }
+
+    pub(crate) async fn lookup(&self) -> Option<(OutputOf<P>, ResultSource)>
+    where
+        P::Response: DeserializeOwned,
+    {
+        let session = self.session.as_ref()?;
+        let output = match session.lookup::<P>().await? {
+            CachedOutput::Response(response) => CallOutput::Complete(response),
+            CachedOutput::Stream(data) => P::replay(Bytes::from(data))?,
+        };
+        Some((
+            output,
+            ResultSource::Cache {
+                key: cache_key(&session.request.key),
+            },
+        ))
+    }
+
+    pub(crate) async fn finish(self, output: OutputOf<P>, source: &ResultSource) -> OutputOf<P>
+    where
+        P::Response: Serialize,
+    {
+        let Some(session) = self.session.filter(|session| {
+            *source == ResultSource::Provider && session.request.controls.writes()
+        }) else {
+            return output;
+        };
+        match output {
+            CallOutput::Complete(response) => {
+                session.store_response::<P>(&response).await;
+                CallOutput::Complete(response)
+            }
+            CallOutput::Stream { head, chunks } => CallOutput::Stream {
+                head,
+                chunks: capture_stream::<P>(chunks, session),
+            },
+        }
+    }
+}
+
+fn capture_stream<P: StreamCachable>(
+    chunks: futures_util::stream::BoxStream<'static, Result<P::Chunk, RouteError>>,
+    session: CacheSession,
+) -> futures_util::stream::BoxStream<'static, Result<P::Chunk, RouteError>> {
+    stream::try_unfold(
+        (chunks, Some(Vec::<u8>::new()), session),
+        |(mut chunks, captured, session)| async move {
+            match chunks.try_next().await? {
+                Some(chunk) => {
+                    let captured = captured.and_then(|mut data| {
+                        let bytes = P::bytes(&chunk);
+                        if data.len().saturating_add(bytes.len())
+                            > session.service.config().max_entry_bytes
+                        {
+                            return None;
+                        }
+                        data.extend_from_slice(bytes);
+                        Some(data)
+                    });
+                    Ok(Some((chunk, (chunks, captured, session))))
+                }
+                None => {
+                    if let Some(data) = captured
+                        && let Ok(text) = String::from_utf8(data)
+                        && successful_stream(&text, P::TERMINAL_EVENT)
+                        && let Ok(entry) = serde_json::to_value(ResponseEnvelope::new(
+                            P::SURFACE,
+                            CachedOutput::<Value>::Stream(text),
+                        ))
+                    {
+                        session.store(entry).await;
+                    }
+                    Ok::<_, RouteError>(None)
+                }
+            }
+        },
+    )
+    .boxed()
+}
+
+fn now() -> Duration {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+}
+
+fn successful_stream(text: &str, terminal: &str) -> bool {
+    let mut pending = BytesMut::from(text.as_bytes());
+    let mut codec = litellm_framing::sse::SseCodec::default();
+    let mut complete = false;
+    loop {
+        let event = match codec.decode(&mut pending) {
+            Ok(Some(event)) => event,
+            Ok(None) => return complete && pending.is_empty(),
+            Err(_) => return false,
+        };
+        let Ok(value) = serde_json::from_str::<Value>(&event.data) else {
+            return false;
+        };
+        let Some(kind) = value.get("type").and_then(Value::as_str) else {
+            return false;
+        };
+        if matches!(kind, "error" | "response.failed" | "response.incomplete") {
+            return false;
+        }
+        complete |= kind == terminal;
+    }
+}
+
+async fn publish(
+    facts: ExecutionFacts,
+    interceptors: &impl Interceptors<RouteError>,
+    observers: Option<&ObservationSender>,
+) -> Result<(), RouteError> {
+    if let Some(observers) = observers {
+        observers.emit(CallEvent::Execution(ExecutionEvent::ResultReady {
+            facts: facts.clone(),
+        }));
+    }
+    interceptors.result_ready(facts).await
+}

litellm-rust/crates/core/src/chat_completions/handler.rs

@@ -1,5 +1,4 @@
-use litellm_host::lifecycle::ExecutionEvent;
-use litellm_host::observation::ObservationSender;
+use litellm_host::{lifecycle::ExecutionEvent, observation::ObservationSender};
 use std::time::Duration;
 
 use litellm_auth::AuthServices;
@@ -9,7 +8,7 @@ use litellm_llms::base_llm::{
     auth::{Authenticated, resolve_auth},
     chat::transformation::ProviderChatResponseData,
 };
-use litellm_types::utils::ChatCompletionsResponse;
+use litellm_llms_types::formats::chat_completions::ChatCompletionsResponse;
 use serde_json::Value;
 
 use super::Error;
@@ -22,6 +21,8 @@ pub(super) async fn execute(
     http: &Client,
     auth: &AuthServices,
     request: ProviderChatCompletionsRequest,
+    cache: Option<litellm_cache_response::ScopedCache>,
+    cache_options: Option<litellm_cache_response::CachePolicy>,
     interceptors: &impl Interceptors<Error>,
     observers: Option<&ObservationSender>,
 ) -> Result<ChatCompletionsResponse, Error> {
@@ -45,6 +46,10 @@ pub(super) async fn execute(
         api_key,
     };
     let authenticated = resolve_auth(auth, environment, &|key| secrets.get(key)).await?;
+    let identity = litellm_host::interceptors::ProviderIdentity {
+        model: context.model.clone(),
+        provider: context.custom_llm_provider.clone(),
+    };
     let wire = interceptors
         .before_provider_request(
             WireRequest {
@@ -55,59 +60,72 @@ pub(super) async fn execute(
             context,
         )
         .await?;
-    let outbound = outbound_request(
-        Authenticated {
-            headers: wire.headers,
-            signer: authenticated.signer,
+    let cache = cache.filter(|_| authenticated.signer.is_none());
+    let cache_request =
+        crate::caching::CacheRequest::from_wire(identity, cache.as_ref().map(|_| &wire));
+    crate::caching::execute_unary::<super::route::ChatCompletions, _, _>(
+        cache_request,
+        cache.as_ref().map(|cache| cache.service.clone()),
+        cache.as_ref().map(|cache| cache.options(cache_options)),
+        interceptors,
+        observers,
+        || async move {
+            let outbound = outbound_request(
+                Authenticated {
+                    headers: wire.headers,
+                    signer: authenticated.signer,
+                },
+                wire.url,
+                &wire.body,
+                timeout,
+            )?;
+
+            let response = crate::outbound::send(outbound, http).await.map_err(|err| {
+                // Failing to establish the connection means the request never went out,
+                // so the host can still serve it. Everything else here, a timeout
+                // above all, may have reached the provider and been answered.
+                if err.is_connect() || err.is_builder() {
+                    Error::Transport(litellm_http::transport::Error::Connect(err.to_string()))
+                } else {
+                    Error::Transport(litellm_http::transport::Error::Network(err.to_string()))
+                }
+            })?;
+
+            let status = response.status();
+            let text = response.text().await.map_err(|err| {
+                Error::Transport(litellm_http::transport::Error::Network(err.to_string()))
+            })?;
+
+            if !status.is_success() {
+                return Err(Error::Transport(litellm_http::transport::Error::Http {
+                    status: status.as_u16(),
+                    body: truncate_error_body(&text),
+                }));
+            }
+            let raw = RawResponse { body: text.clone() };
+            if let Some(observers) = observers {
+                observers.emit(litellm_host::lifecycle::CallEvent::Execution(
+                    ExecutionEvent::ProviderResponseReceived { raw: raw.clone() },
+                ));
+            }
+            interceptors
+                .after_provider_response(raw)
+                .await
+                .map_err(Error::post_call)?;
+
+            let body: Value = serde_json::from_str(&text).map_err(|err| {
+                Error::InvalidResponse(litellm_llms::ErrorDetail::invalid(
+                    "chat completions response JSON",
+                    err,
+                ))
+            })?;
+            config
+                .transform_response(&model, ProviderChatResponseData { body })
+                .map_err(Error::from)
+                .map_err(as_response_error)
         },
-        wire.url,
-        &wire.body,
-        timeout,
-    )?;
-
-    let response = crate::outbound::send(outbound, http).await.map_err(|err| {
-        // Failing to establish the connection means the request never went out,
-        // so the host can still serve it. Everything else here, a timeout
-        // above all, may have reached the provider and been answered.
-        if err.is_connect() || err.is_builder() {
-            Error::Transport(litellm_http::transport::Error::Connect(err.to_string()))
-        } else {
-            Error::Transport(litellm_http::transport::Error::Network(err.to_string()))
-        }
-    })?;
-
-    let status = response.status();
-    let text = response.text().await.map_err(|err| {
-        Error::Transport(litellm_http::transport::Error::Network(err.to_string()))
-    })?;
-
-    if !status.is_success() {
-        return Err(Error::Transport(litellm_http::transport::Error::Http {
-            status: status.as_u16(),
-            body: truncate_error_body(&text),
-        }));
-    }
-    let raw = RawResponse { body: text.clone() };
-    if let Some(observers) = observers {
-        observers.emit(litellm_host::lifecycle::CallEvent::Execution(
-            ExecutionEvent::ProviderResponseReceived { raw: raw.clone() },
-        ));
-    }
-    interceptors
-        .after_provider_response(raw)
-        .await
-        .map_err(Error::post_call)?;
-
-    let body: Value = serde_json::from_str(&text).map_err(|err| {
-        Error::InvalidResponse(litellm_llms::ErrorDetail::invalid(
-            "chat completions response JSON",
-            err,
-        ))
-    })?;
-    config
-        .transform_response(&model, ProviderChatResponseData { body })
-        .map_err(Error::from)
-        .map_err(as_response_error)
+    )
+    .await
 }
 
 /// Re-tag an error raised while normalizing a response the provider already
@@ -232,6 +250,8 @@ mod tests {
             &Client::plain_for_test(),
             &AuthServices::default(),
             prepared(&upstream.uri()),
+            None,
+            None,
             &interceptors,
             None,
         )
@@ -271,6 +291,8 @@ mod tests {
             &Client::plain_for_test(),
             &AuthServices::default(),
             prepared(&upstream.uri()),
+            None,
+            None,
             &interceptors,
             None,
         )

litellm-rust/crates/core/src/chat_completions/mod.rs

@@ -5,7 +5,7 @@ pub use crate::error::RouteError as Error;
 mod common_utils;
 pub(crate) mod handler;
 mod prepare;
-use litellm_types::utils::ChatCompletionsResponse;
+use litellm_llms_types::formats::chat_completions::ChatCompletionsResponse;
 use prepare::{prepare_provider_request, resolve_request};
 
 use crate::chat_completions::types::ChatCompletionsRequest;
@@ -18,6 +18,7 @@ pub struct ChatCompletionsRoute {
     http: litellm_http::Client,
     auth: Arc<AuthServices>,
     secrets: Arc<dyn SecretSource>,
+    cache: Option<litellm_cache_response::ScopedCache>,
 }
 
 impl ChatCompletionsRoute {
@@ -30,6 +31,14 @@ impl ChatCompletionsRoute {
             http,
             auth,
             secrets,
+            cache: None,
+        }
+    }
+
+    pub fn with_cache(self, cache: litellm_cache_response::ScopedCache) -> Self {
+        Self {
+            cache: Some(cache),
+            ..self
         }
     }
 
@@ -37,49 +46,48 @@ impl ChatCompletionsRoute {
         &self,
         request: ChatCompletionsRequest<'_>,
         interceptors: &impl litellm_host::interceptors::Interceptors<Error>,
-        observers: Option<ObservationSender>,
+        options: impl Into<crate::CallOptions>,
     ) -> Result<ChatCompletionsResponse, Error> {
+        let crate::CallOptions {
+            cache: cache_options,
+            observers,
+        } = options.into();
         litellm_host::lifecycle::observe_unary(
             observers.clone(),
-            self.run(request, interceptors, observers.as_ref()),
+            self.run_call(
+                request.into(),
+                cache_options,
+                interceptors,
+                observers.as_ref(),
+            ),
         )
         .await
     }
 
-    #[tracing::instrument(name = "litellm.route", skip_all, fields(
-        route = "chat_completions",
-        model = %request.model,
-        provider,
-        resolved_model,
-        stream = false,
-        outcome
-    ))]
     async fn run(
         &self,
         request: ChatCompletionsRequest<'_>,
+        cache_options: Option<litellm_cache_response::CachePolicy>,
         interceptors: &impl litellm_host::interceptors::Interceptors<Error>,
         observers: Option<&ObservationSender>,
     ) -> Result<ChatCompletionsResponse, Error> {
-        crate::diagnostic::unary(async {
-            let resolved = resolve_request(request)?;
-            let snapshot = self
-                .secrets
-                .resolve(&resolved.config.secret_names())
-                .await?;
-            let prepared = prepare_provider_request(resolved, snapshot)?;
-            crate::diagnostic::provider(&prepared.model, &prepared.custom_llm_provider);
-            let execute: futures_util::future::BoxFuture<
-                '_,
-                Result<ChatCompletionsResponse, Error>,
-            > = Box::pin(handler::execute(
+        let resolved = resolve_request(request)?;
+        let snapshot = self
+            .secrets
+            .resolve(&resolved.config.secret_names())
+            .await?;
+        let prepared = prepare_provider_request(resolved, snapshot)?;
+        crate::diagnostic::provider(&prepared.model, &prepared.custom_llm_provider);
+        let execute: futures_util::future::BoxFuture<'_, Result<ChatCompletionsResponse, Error>> =
+            Box::pin(handler::execute(
                 &self.http,
                 &self.auth,
                 prepared,
+                self.cache.clone(),
+                cache_options,
                 interceptors,
                 observers,
             ));
-            execute.await
-        })
-        .await
+        execute.await
     }
 }

litellm-rust/crates/core/src/chat_completions/prepare.rs

@@ -2,8 +2,8 @@ use litellm_auth::SecretValue;
 use litellm_core_utils::settings::Lookup;
 use litellm_http::request::with_default_headers;
 use litellm_llms::base_llm::{auth::ValidatedEnvironment, chat::transformation::BaseConfig};
+use litellm_llms_types::formats::chat_completions::ChatMessage;
 use litellm_secrets::source::Secrets;
-use litellm_types::llms::openai::ChatMessage;
 use serde_json::Value;
 
 use super::{

litellm-rust/crates/core/src/chat_completions/route.rs

@@ -5,7 +5,7 @@ use litellm_host::{
     call::{CallOutput, HostedMachine, hosted_call},
     protocol::Protocol,
 };
-use litellm_types::utils::ChatCompletionsResponse;
+use litellm_llms_types::formats::chat_completions::ChatCompletionsResponse;
 
 use super::{
     ChatCompletionsRoute, Error,
@@ -27,26 +27,56 @@ impl ChatCompletionsRoute {
     pub fn machine(
         self,
         call: ChatCompletionsCall,
-        observers: Option<ObservationSender>,
+        options: impl Into<crate::CallOptions>,
     ) -> HostedMachine<ChatCompletions> {
+        let crate::CallOptions {
+            cache: cache_options,
+            observers,
+        } = options.into();
         hosted_call(
             call,
             observers,
-            move |call: ChatCompletionsCall, _, interceptors, observers| async move {
-                let request = ChatCompletionsRequest {
-                    model: &call.model,
-                    messages: call.messages,
-                    optional_params: call.optional_params,
-                    api_key: call.api_key.as_deref(),
-                    api_base: call.api_base.as_deref(),
-                    custom_llm_provider: call.custom_llm_provider.as_deref(),
-                    extra_headers: call.extra_headers,
-                    timeout: call.timeout,
-                };
-                self.run(request, &interceptors, observers.as_ref())
+            move |call, _, interceptors, observers| async move {
+                self.run_call(call, cache_options, &interceptors, observers.as_ref())
                     .await
                     .map(CallOutput::Complete)
             },
         )
     }
+
+    #[tracing::instrument(name = "litellm.route", skip_all, fields(
+        route = "chat_completions",
+        model = %call.model,
+        provider,
+        resolved_model,
+        stream = false,
+        outcome
+    ))]
+    pub(super) async fn run_call(
+        &self,
+        call: ChatCompletionsCall,
+        cache_options: Option<litellm_cache_response::CachePolicy>,
+        interceptors: &impl litellm_host::interceptors::Interceptors<Error>,
+        observers: Option<&ObservationSender>,
+    ) -> Result<ChatCompletionsResponse, Error> {
+        crate::diagnostic::unary(async {
+            let request = ChatCompletionsRequest {
+                model: &call.model,
+                messages: call.messages,
+                optional_params: call.optional_params,
+                api_key: call.api_key.as_deref(),
+                api_base: call.api_base.as_deref(),
+                custom_llm_provider: call.custom_llm_provider.as_deref(),
+                extra_headers: call.extra_headers,
+                timeout: call.timeout,
+            };
+            self.run(request, cache_options, interceptors, observers)
+                .await
+        })
+        .await
+    }
+}
+
+impl crate::caching::Cachable for ChatCompletions {
+    const SURFACE: &'static str = "chat_completions";
 }

litellm-rust/crates/core/src/chat_completions/types.rs

@@ -3,7 +3,7 @@ use std::time::Duration;
 
 use litellm_auth::SecretValue;
 use litellm_llms::base_llm::{auth::ValidatedEnvironment, chat::transformation::BaseConfig};
-use litellm_types::llms::openai::ChatMessage;
+use litellm_llms_types::formats::chat_completions::ChatMessage;
 use serde_json::{Map, Value};
 
 /// A `/chat/completions` call as it crosses into the core.

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

@@ -0,0 +1,48 @@
+use litellm_cache_response::CachePolicy;
+use litellm_host::{
+    interceptors::{ExecutionFacts, Interceptors, RawResponse},
+    lifecycle::{CallEvent, ExecutionEvent},
+    observation::ObservationSender,
+};
+
+use crate::{CallOptions, RouteError};
+
+pub(crate) struct CallContext<'a, I> {
+    pub interceptors: &'a I,
+    pub observers: Option<ObservationSender>,
+    pub cache: CachePolicy,
+}
+
+impl<'a, I: Interceptors<RouteError>> CallContext<'a, I> {
+    pub fn new(interceptors: &'a I, options: CallOptions) -> Self {
+        Self {
+            interceptors,
+            observers: options.observers,
+            cache: options.cache.unwrap_or_default(),
+        }
+    }
+
+    pub async fn result_ready(&self, facts: ExecutionFacts) -> Result<(), RouteError> {
+        if let Some(observers) = &self.observers {
+            observers.emit(CallEvent::Execution(ExecutionEvent::ResultReady {
+                facts: facts.clone(),
+            }));
+        }
+        self.interceptors.result_ready(facts).await
+    }
+
+    pub async fn response_received(&self, body: &str) -> Result<(), RouteError> {
+        let raw = RawResponse {
+            body: body.to_owned(),
+        };
+        if let Some(observers) = &self.observers {
+            observers.emit(CallEvent::Execution(
+                ExecutionEvent::ProviderResponseReceived { raw: raw.clone() },
+            ));
+        }
+        self.interceptors
+            .after_provider_response(raw)
+            .await
+            .map_err(RouteError::post_call)
+    }
+}

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

@@ -1,6 +1,8 @@
+mod context;
 mod diagnostic;
 
 pub mod audio_transcription;
+pub mod caching;
 pub mod chat_completions;
 pub mod constants;
 pub mod error;
@@ -12,3 +14,27 @@ pub mod resources;
 pub mod responses;
 
 pub use error::RouteError;
+
+#[derive(Clone, Default)]
+pub struct CallOptions {
+    pub cache: Option<litellm_cache_response::CachePolicy>,
+    pub observers: Option<litellm_host::observation::ObservationSender>,
+}
+
+impl From<Option<litellm_host::observation::ObservationSender>> for CallOptions {
+    fn from(observers: Option<litellm_host::observation::ObservationSender>) -> Self {
+        Self {
+            cache: None,
+            observers,
+        }
+    }
+}
+
+impl From<litellm_cache_response::CachePolicy> for CallOptions {
+    fn from(cache: litellm_cache_response::CachePolicy) -> Self {
+        Self {
+            cache: Some(cache),
+            observers: None,
+        }
+    }
+}

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

@@ -1,4 +1,4 @@
-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-types::messages`, adapter contracts and execution inputs in `llms/src/base_llm/messages`, and provider implementations in `llms/src/<provider>/messages`
+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
 

litellm-rust/crates/core/src/messages/common_utils.rs

@@ -3,7 +3,7 @@ pub(super) use litellm_http::request::truncate_error_body;
 use litellm_llms::{
     anthropic::messages::transformation::ANTHROPIC_MESSAGES_CONFIG,
     azure_ai::messages::transformation::AZURE_ANTHROPIC_MESSAGES_CONFIG,
-    base_llm::messages::transformation::BaseAnthropicMessagesConfig,
+    base_llm::messages::transformation::BaseMessagesConfig,
     bedrock::messages::invoke_transformations::anthropic_claude3_transformation::BEDROCK_ANTHROPIC_MESSAGES_CONFIG,
 };
 use serde_json::{Map, Value};
@@ -30,7 +30,7 @@ impl MessagesProvider {
         .into()
     }
 
-    pub(crate) fn config(self) -> &'static dyn BaseAnthropicMessagesConfig {
+    pub(crate) fn config(self) -> &'static dyn BaseMessagesConfig {
         match self {
             Self::Anthropic => &ANTHROPIC_MESSAGES_CONFIG,
             Self::AzureAi => &AZURE_ANTHROPIC_MESSAGES_CONFIG,

litellm-rust/crates/core/src/messages/handler.rs

@@ -1,100 +1,145 @@
-use litellm_host::lifecycle::ExecutionEvent;
-use litellm_host::observation::ObservationSender;
 use std::time::Duration;
 
 use bytes::Bytes;
 use futures_util::{StreamExt, TryStreamExt, stream::BoxStream};
-use litellm_auth::AuthServices;
-use litellm_host::interceptors::{Interceptors, RawResponse, RequestContext, WireRequest};
+use litellm_host::interceptors::{Interceptors, ProviderIdentity, RequestContext, WireRequest};
 use litellm_http::transport::Error as TransportError;
 use litellm_llms::base_llm::{
     auth::{Authenticated, resolve_auth},
     messages::{
         streaming::{ByteStream, StreamDecoder, encode_anthropic_sse},
-        transformation::BaseAnthropicMessagesConfig,
+        transformation::BaseMessagesConfig,
     },
 };
+use litellm_llms_types::formats::messages::MessagesResponse;
 use litellm_tracing::ByteChunk;
-use litellm_types::llms::anthropic_messages::anthropic_response::AnthropicMessagesResponse;
 use serde_json::Value;
 
 use super::{
-    Error, MessagesResponse, common_utils::truncate_error_body, prepare::ProviderMessagesRequest,
+    Error, MessagesCallResponse, MessagesRoute, common_utils::truncate_error_body,
+    prepare::ProviderMessagesRequest,
 };
-use crate::{constants::MESSAGES_TIMEOUT_SECS, outbound::outbound_request};
+use crate::{constants::MESSAGES_TIMEOUT_SECS, context::CallContext, outbound::outbound_request};
 
-pub(super) async fn execute(
-    http: &litellm_http::Client,
-    auth: &AuthServices,
-    request: ProviderMessagesRequest,
-    interceptors: &impl Interceptors<Error>,
-    observers: Option<&ObservationSender>,
-) -> Result<MessagesResponse, Error> {
-    let ProviderMessagesRequest {
-        provider,
-        url,
-        body,
-        environment,
-        timeout,
-        api_key,
-    } = request;
-    let stream = body.params.stream == Some(true);
-    let context = RequestContext {
-        model: body.model.clone(),
-        custom_llm_provider: provider.as_str().to_string(),
-        optional_params: serde_json::to_value(&body.params).map_err(serialize_failure)?,
-        secret_fields: Vec::new(),
-        api_key,
-    };
-    let authenticated = resolve_auth(auth, environment, &|key| std::env::var(key).ok()).await?;
-    let wire = interceptors
-        .before_provider_request(
-            WireRequest {
-                url,
-                headers: authenticated.headers,
-                body: serde_json::to_value(&body).map_err(serialize_failure)?,
+pub(super) struct ProviderCall {
+    pub identity: ProviderIdentity,
+    pub wire: WireRequest,
+    provider: super::common_utils::MessagesProvider,
+    signer: Option<litellm_auth_aws::SigV4Signer>,
+    timeout: Option<Duration>,
+    stream: bool,
+}
+
+impl ProviderCall {
+    pub fn cacheable(&self) -> bool {
+        self.signer.is_none()
+    }
+}
+
+impl MessagesRoute {
+    pub(super) async fn prepare_outbound(
+        &self,
+        request: ProviderMessagesRequest,
+        context: &CallContext<'_, impl Interceptors<Error>>,
+    ) -> Result<ProviderCall, Error> {
+        let ProviderMessagesRequest {
+            provider,
+            url,
+            body,
+            environment,
+            timeout,
+            api_key,
+        } = request;
+        let request_context = RequestContext {
+            model: body.model.clone(),
+            custom_llm_provider: provider.as_str().to_string(),
+            optional_params: serde_json::to_value(&body.params).map_err(serialize_failure)?,
+            secret_fields: Vec::new(),
+            api_key,
+        };
+        let authenticated =
+            resolve_auth(&self.auth, environment, &|key| std::env::var(key).ok()).await?;
+        let identity = ProviderIdentity {
+            model: request_context.model.clone(),
+            provider: request_context.custom_llm_provider.clone(),
+        };
+        let wire = context
+            .interceptors
+            .before_provider_request(
+                WireRequest {
+                    url,
+                    headers: authenticated.headers,
+                    body: serde_json::to_value(&body).map_err(serialize_failure)?,
+                },
+                request_context,
+            )
+            .await?;
+        let stream = match wire.body.get("stream") {
+            None | Some(Value::Null) => false,
+            Some(Value::Bool(stream)) => *stream,
+            Some(value) => {
+                return Err(Error::InvalidRequest(
+                    litellm_llms::ErrorDetail::InvalidValue {
+                        field: "stream",
+                        expected: "a boolean",
+                        actual: value.clone(),
+                    },
+                ));
+            }
+        };
+        Ok(ProviderCall {
+            identity,
+            wire,
+            provider,
+            signer: authenticated.signer,
+            timeout,
+            stream,
+        })
+    }
+
+    pub(super) async fn call_provider(
+        &self,
+        request: ProviderCall,
+        context: &CallContext<'_, impl Interceptors<Error>>,
+    ) -> Result<MessagesCallResponse, Error> {
+        let ProviderCall {
+            identity,
+            wire,
+            provider,
+            signer,
+            timeout,
+            stream,
+        } = request;
+        let provider_name = provider.as_str();
+        log_request_body(provider_name, stream, &wire.body);
+        let response = send(
+            &self.http,
+            Authenticated {
+                headers: wire.headers,
+                signer,
             },
-            context,
+            &wire.url,
+            &wire.body,
+            timeout,
         )
         .await?;
-    let provider_name = provider.as_str();
-    log_request_body(provider_name, stream, &wire.body);
-    let response = send(
-        http,
-        Authenticated {
-            headers: wire.headers,
-            signer: authenticated.signer,
-        },
-        &wire.url,
-        &wire.body,
-        timeout,
-    )
-    .await?;
-    if !response.status().is_success() {
-        return Err(provider_error(response).await);
+        if !response.status().is_success() {
+            return Err(provider_error(response).await);
+        }
+        let config = provider.config();
+        if stream {
+            return Ok(streaming_response(
+                response,
+                config.stream_decoder(),
+                provider_name,
+            ));
+        }
+        let text = response.text().await.map_err(network)?;
+        log_response_body(&text);
+        context.response_received(&text).await?;
+        decode_response(config, &identity.model, &text)
+            .map(|message| MessagesCallResponse::Complete(Box::new(message)))
     }
-    let config = provider.config();
-    if stream {
-        return Ok(streaming_response(
-            response,
-            config.stream_decoder(),
-            provider_name,
-        ));
-    }
-    let text = response.text().await.map_err(network)?;
-    log_response_body(&text);
-    let raw = RawResponse { body: text.clone() };
-    if let Some(observers) = observers {
-        observers.emit(litellm_host::lifecycle::CallEvent::Execution(
-            ExecutionEvent::ProviderResponseReceived { raw: raw.clone() },
-        ));
-    }
-    interceptors
-        .after_provider_response(raw)
-        .await
-        .map_err(Error::post_call)?;
-    decode_response(config, &body.model, &text)
-        .map(|message| MessagesResponse::Complete(Box::new(message)))
 }
 
 fn serialize_failure(err: serde_json::Error) -> Error {
@@ -139,10 +184,10 @@ async fn provider_error(response: reqwest::Response) -> Error {
 }
 
 fn decode_response(
-    config: &dyn BaseAnthropicMessagesConfig,
+    config: &dyn BaseMessagesConfig,
     model: &str,
     text: &str,
-) -> Result<AnthropicMessagesResponse, Error> {
+) -> Result<MessagesResponse, Error> {
     let response = serde_json::from_str(text).map_err(|err| {
         Error::InvalidResponse(litellm_llms::ErrorDetail::invalid(
             "messages response JSON",
@@ -158,7 +203,7 @@ fn streaming_response(
     response: reqwest::Response,
     decoder: Option<StreamDecoder>,
     provider: &'static str,
-) -> MessagesResponse {
+) -> MessagesCallResponse {
     let headers = response
         .headers()
         .iter()
@@ -175,7 +220,7 @@ fn streaming_response(
         .boxed(),
         Some(decode) => decoded_chunks(response, decode, provider),
     };
-    MessagesResponse::Stream {
+    MessagesCallResponse::Stream {
         head: super::route::MessagesStreamHead { headers },
         chunks,
     }
@@ -249,7 +294,7 @@ mod tests {
             .send()
             .await
             .unwrap();
-        let MessagesResponse::Stream { mut chunks, .. } =
+        let MessagesCallResponse::Stream { mut chunks, .. } =
             streaming_response(response, Some(anthropic_sse_event_stream), "test")
         else {
             panic!("a streaming response returns chunks");

litellm-rust/crates/core/src/messages/mod.rs

@@ -1,22 +1,26 @@
-use litellm_host::observation::ObservationSender;
 mod common_utils;
 mod handler;
 mod prepare;
 pub mod route;
 mod types;
 
+use futures_util::FutureExt;
 use litellm_auth::AuthServices;
+use litellm_host::interceptors::{ExecutionFacts, Interceptors, ResultSource};
+
+use crate::{caching::CallCache, context::CallContext};
 use litellm_secrets::source::SecretSource;
 use std::sync::Arc;
 
 pub use crate::error::RouteError as Error;
-pub use types::{MessagesCall, MessagesResponse, MessagesShaping, messages_body};
+pub use types::{MessagesCall, MessagesCallResponse, MessagesShaping, messages_body};
 
 #[derive(Clone)]
 pub struct MessagesRoute {
     http: litellm_http::Client,
     auth: Arc<AuthServices>,
     secrets: Arc<dyn SecretSource>,
+    cache: Option<litellm_cache_response::ScopedCache>,
 }
 
 impl MessagesRoute {
@@ -29,6 +33,15 @@ impl MessagesRoute {
             http,
             auth,
             secrets,
+            cache: None,
+        }
+    }
+
+    #[must_use]
+    pub fn with_cache(self, cache: litellm_cache_response::ScopedCache) -> Self {
+        Self {
+            cache: Some(cache),
+            ..self
         }
     }
 
@@ -36,13 +49,11 @@ impl MessagesRoute {
         &self,
         call: MessagesCall,
         interceptors: &impl litellm_host::interceptors::Interceptors<Error>,
-        observers: Option<ObservationSender>,
-    ) -> Result<MessagesResponse, Error> {
-        litellm_host::lifecycle::observe_call(
-            observers.clone(),
-            self.run(call, interceptors, observers.as_ref()),
-        )
-        .await
+        options: impl Into<crate::CallOptions>,
+    ) -> Result<MessagesCallResponse, Error> {
+        let context = CallContext::new(interceptors, options.into());
+        litellm_host::lifecycle::observe_call(context.observers.clone(), self.run(call, context))
+            .await
     }
 
     #[tracing::instrument(name = "litellm.route", skip_all, fields(
@@ -56,21 +67,33 @@ impl MessagesRoute {
     async fn run(
         &self,
         call: MessagesCall,
-        interceptors: &impl litellm_host::interceptors::Interceptors<Error>,
-        observers: Option<&ObservationSender>,
-    ) -> Result<MessagesResponse, Error> {
+        context: CallContext<'_, impl Interceptors<Error>>,
+    ) -> Result<MessagesCallResponse, Error> {
         crate::diagnostic::call(async {
-            let request = prepare::prepare(call, self.secrets.as_ref()).await?;
-            crate::diagnostic::provider(&request.body.model, request.provider.as_str());
-            let execute: futures_util::future::BoxFuture<'_, Result<MessagesResponse, Error>> =
-                Box::pin(handler::execute(
-                    &self.http,
-                    &self.auth,
-                    request,
-                    interceptors,
-                    observers,
-                ));
-            execute.await
+            let prepared = prepare::prepare(call, self.secrets.as_ref()).await?;
+            crate::diagnostic::provider(&prepared.body.model, prepared.provider.as_str());
+            let request = self.prepare_outbound(prepared, &context).boxed().await?;
+            let cache = CallCache::<route::Messages>::from_wire(
+                self.cache.as_ref().filter(|_| request.cacheable()),
+                context.cache,
+                &request.identity,
+                &request.wire,
+            );
+            let identity = request.identity.clone();
+            let (output, source) = match cache.lookup().await {
+                Some(hit) => hit,
+                None => (
+                    self.call_provider(request, &context).await?,
+                    ResultSource::Provider,
+                ),
+            };
+            context
+                .result_ready(ExecutionFacts {
+                    provider: identity,
+                    source: source.clone(),
+                })
+                .await?;
+            Ok(cache.finish(output, &source).await)
         })
         .await
     }

litellm-rust/crates/core/src/messages/prepare.rs

@@ -9,8 +9,8 @@ use litellm_http::request::with_default_headers;
 use litellm_llms::base_llm::{
     auth::ValidatedEnvironment, messages::context::MessagesTransformContext,
 };
+use litellm_llms_types::formats::messages::MessagesRequest;
 use litellm_secrets::source::SecretSource;
-use litellm_types::llms::anthropic_messages::anthropic_request::AnthropicMessagesRequest;
 
 use super::{
     Error, MessagesCall,
@@ -27,7 +27,7 @@ struct ResolvedProvider {
 pub(super) struct ProviderMessagesRequest {
     pub(super) provider: MessagesProvider,
     pub(super) url: String,
-    pub(super) body: AnthropicMessagesRequest,
+    pub(super) body: MessagesRequest,
     pub(super) environment: ValidatedEnvironment,
     pub(super) timeout: Option<Duration>,
     /// The caller's own credential, reported to the host beside the wire request.
@@ -79,7 +79,7 @@ fn prepare_provider_request(
     let env_lookup = |key: &str| secrets.get(key);
 
     let sanitized = config.shape_request(
-        AnthropicMessagesRequest { model, ..body },
+        MessagesRequest { model, ..body },
         shaping.reasoning_auto_summary,
     )?;
     let trimmed = without_additional_drop_params(sanitized, &shaping.additional_drop_params)?;
@@ -124,9 +124,9 @@ fn prepare_provider_request(
 }
 
 fn without_additional_drop_params(
-    request: AnthropicMessagesRequest,
+    request: MessagesRequest,
     paths: &[String],
-) -> Result<AnthropicMessagesRequest, Error> {
+) -> Result<MessagesRequest, Error> {
     if paths.is_empty() {
         return Ok(request);
     }
@@ -134,7 +134,7 @@ fn without_additional_drop_params(
     let trimmed = paths
         .iter()
         .fold(params, |params, path| delete_nested_value(params, path));
-    Ok(AnthropicMessagesRequest {
+    Ok(MessagesRequest {
         params: serde_json::from_value(trimmed).map_err(invalid_request)?,
         ..request
     })
@@ -143,7 +143,7 @@ fn without_additional_drop_params(
 #[cfg(test)]
 mod tests {
     use litellm_llms::base_llm::auth::resolve_auth;
-    use litellm_types::utils::ProviderSpecificHeaders;
+    use litellm_llms_types::headers::ProviderSpecificHeaders;
     use rstest::{fixture, rstest};
     use serde_json::{Map, Value, json};
 
@@ -155,7 +155,7 @@ mod tests {
         MessagesShaping::default()
     }
 
-    fn body(value: Value) -> AnthropicMessagesRequest {
+    fn body(value: Value) -> MessagesRequest {
         serde_json::from_value(value).unwrap()
     }
 

litellm-rust/crates/core/src/messages/route.rs

@@ -1,4 +1,3 @@
-use litellm_host::observation::ObservationSender;
 use std::convert::Infallible;
 
 use bytes::Bytes;
@@ -6,11 +5,11 @@ use litellm_host::{
     call::{HostedCompletion, HostedMachine, hosted_call},
     protocol::Protocol,
 };
-use litellm_types::llms::anthropic_messages::anthropic_response::AnthropicMessagesResponse;
+use litellm_llms_types::formats::messages::MessagesResponse;
 
 use super::{Error, MessagesCall};
 
-pub type MessagesOutput = HostedCompletion<Box<AnthropicMessagesResponse>>;
+pub type MessagesOutput = HostedCompletion<Box<MessagesResponse>>;
 
 /// The upstream response as the caller sees it at stream hand-off, before any chunk.
 pub struct MessagesStreamHead {
@@ -20,7 +19,7 @@ pub struct MessagesStreamHead {
 pub struct Messages;
 
 impl Protocol for Messages {
-    type Response = Box<AnthropicMessagesResponse>;
+    type Response = Box<MessagesResponse>;
     type Error = Error;
     type Request = MessagesCall;
     type HostCall = Infallible;
@@ -34,14 +33,46 @@ impl super::MessagesRoute {
     pub fn machine(
         self,
         request: super::MessagesCall,
-        observers: Option<ObservationSender>,
+        options: impl Into<crate::CallOptions>,
     ) -> MessagesMachine {
+        let crate::CallOptions {
+            cache: cache_options,
+            observers,
+        } = options.into();
         hosted_call(
             request,
             observers,
             move |call, _, interceptors, observers| async move {
-                self.run(call, &interceptors, observers.as_ref()).await
+                let context = crate::context::CallContext::new(
+                    &interceptors,
+                    crate::CallOptions {
+                        cache: cache_options,
+                        observers,
+                    },
+                );
+                self.run(call, context).await
             },
         )
     }
 }
+
+impl crate::caching::Cachable for Messages {
+    const SURFACE: &'static str = "messages";
+}
+
+impl crate::caching::StreamCachable for Messages {
+    const TERMINAL_EVENT: &'static str = "message_stop";
+
+    fn replay(data: bytes::Bytes) -> Option<litellm_host::call::OutputOf<Self>> {
+        Some(litellm_host::call::CallOutput::Stream {
+            head: MessagesStreamHead {
+                headers: Vec::new(),
+            },
+            chunks: Box::pin(futures_util::stream::iter([Ok(data)])),
+        })
+    }
+
+    fn bytes(chunk: &Self::Chunk) -> &[u8] {
+        chunk.as_ref()
+    }
+}

litellm-rust/crates/core/src/messages/types.rs

@@ -2,12 +2,10 @@ use std::time::Duration;
 
 use bytes::Bytes;
 use litellm_host::call::CallOutput;
-use litellm_llms::base_llm::messages::context::MessagesModelCapabilities as AnthropicModelCapabilities;
-use litellm_types::{
-    llms::anthropic_messages::{
-        anthropic_request::AnthropicMessagesRequest, anthropic_response::AnthropicMessagesResponse,
-    },
-    utils::ProviderSpecificHeaders,
+use litellm_llms::base_llm::messages::context::MessagesModelCapabilities;
+use litellm_llms_types::{
+    formats::messages::{MessagesRequest, MessagesResponse},
+    headers::ProviderSpecificHeaders,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
@@ -15,7 +13,7 @@ use serde_json::{Map, Value};
 use super::Error;
 
 pub struct MessagesCall {
-    pub body: AnthropicMessagesRequest,
+    pub body: MessagesRequest,
     pub api_key: Option<String>,
     pub api_base: Option<String>,
     pub custom_llm_provider: Option<String>,
@@ -25,7 +23,7 @@ pub struct MessagesCall {
     pub shaping: MessagesShaping,
 }
 
-pub fn messages_body(body: Map<String, Value>) -> Result<AnthropicMessagesRequest, Error> {
+pub fn messages_body(body: Map<String, Value>) -> Result<MessagesRequest, Error> {
     serde_json::from_value(Value::Object(body)).map_err(invalid_request)
 }
 
@@ -33,13 +31,13 @@ pub(super) fn invalid_request(err: serde_json::Error) -> Error {
     Error::InvalidRequest(format!("invalid Anthropic messages request: {err}").into())
 }
 
-pub type MessagesResponse =
-    CallOutput<Box<AnthropicMessagesResponse>, super::route::MessagesStreamHead, Bytes, Error>;
+pub type MessagesCallResponse =
+    CallOutput<Box<MessagesResponse>, super::route::MessagesStreamHead, Bytes, Error>;
 
 #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
 pub struct MessagesShaping {
     #[serde(default)]
-    pub capabilities: AnthropicModelCapabilities,
+    pub capabilities: MessagesModelCapabilities,
     #[serde(default)]
     pub drop_params: bool,
     #[serde(default)]
@@ -76,9 +74,9 @@ mod tests {
     #[case::partial_capabilities(
         json!({"capabilities": {"supports_reasoning": true}}),
         MessagesShaping {
-            capabilities: AnthropicModelCapabilities {
+            capabilities: MessagesModelCapabilities {
                 supports_reasoning: true,
-                ..AnthropicModelCapabilities::default()
+                ..MessagesModelCapabilities::default()
             },
             ..MessagesShaping::default()
         },
@@ -100,7 +98,7 @@ mod tests {
             "additional_drop_params": ["metadata.user_id", "thinking"]
         }),
         MessagesShaping {
-            capabilities: AnthropicModelCapabilities {
+            capabilities: MessagesModelCapabilities {
                 supports_reasoning: true,
                 supports_adaptive_thinking: true,
                 thinking_always_on: false,

litellm-rust/crates/core/src/ocr/client.rs

@@ -2,9 +2,8 @@ use litellm_host::observation::ObservationSender;
 use std::sync::Arc;
 
 use litellm_host::interceptors::Interceptors;
-use litellm_llms::base_llm::ocr::{
-    error::Error, handler::OcrClient, transformation::LiteLLMOcrResponse,
-};
+use litellm_llms::base_llm::ocr::{error::Error, handler::OcrClient};
+use litellm_llms_types::formats::ocr::LiteLLMOcrResponse;
 
 use super::{
     handler::perform_ocr_request,

litellm-rust/crates/core/src/ocr/document.rs

@@ -1,10 +1,8 @@
 use std::{collections::BTreeMap as Map, io::Read, path::Path};
 
 use base64::{Engine, engine::general_purpose::STANDARD};
-use litellm_llms::base_llm::ocr::{
-    error::Error,
-    transformation::{OCR_INLINE_MAX_BYTES, OcrDocument},
-};
+use litellm_llms::base_llm::ocr::{error::Error, transformation::OCR_INLINE_MAX_BYTES};
+use litellm_llms_types::formats::ocr::OcrDocument;
 
 use crate::ocr::types::OcrDocumentInput;
 

litellm-rust/crates/core/src/ocr/handler.rs

@@ -1,12 +1,12 @@
 use futures_util::future::BoxFuture;
 use litellm_host::interceptors::{Interceptors, RawResponse, RequestContext, WireRequest};
-use litellm_host::lifecycle::ExecutionEvent;
-use litellm_host::observation::ObservationSender;
+use litellm_host::{lifecycle::ExecutionEvent, observation::ObservationSender};
 use litellm_llms::base_llm::ocr::{
     error::Error,
     handler::{CallHooks, OcrClient},
-    transformation::{LiteLLMOcrResponse, PreparedOcrRequest},
+    transformation::PreparedOcrRequest,
 };
+use litellm_llms_types::formats::ocr::LiteLLMOcrResponse;
 use serde_json::Value;
 
 use super::{arguments::is_secret_param, prepare::prepare_request, provider_config::OcrConfigKind};

litellm-rust/crates/core/src/ocr/prepare.rs

@@ -85,12 +85,13 @@ mod tests {
         base_llm::ocr::{
             error::Error,
             handler::{CallHooks, OcrClient},
-            transformation::{BaseOcrConfig, OcrResponseFormat},
+            transformation::BaseOcrConfig,
         },
         cohere::ocr::transformation::CohereParseConfig,
         mistral::ocr::transformation::MistralOcrConfig,
         vertex_ai::ocr::transformation::VertexAiOcrConfig,
     };
+    use litellm_llms_types::formats::ocr::OcrResponseFormat;
     use serde_json::{Value, json};
 
     use super::*;

litellm-rust/crates/core/src/ocr/provider_config.rs

@@ -14,8 +14,7 @@ use litellm_llms::{
         error::Error,
         handler::{self, CallHooks, OcrClient},
         transformation::{
-            BaseOcrConfig, LiteLLMOcrResponse, OcrCredentialInputs, OcrDocument, OcrResponseFormat,
-            PreparedOcrRequest, ResolvedOcrCredentials,
+            BaseOcrConfig, OcrCredentialInputs, PreparedOcrRequest, ResolvedOcrCredentials,
         },
     },
     cohere::ocr::transformation::CohereParseConfig,
@@ -25,6 +24,7 @@ use litellm_llms::{
         deepseek_transformation::VertexAIDeepSeekOCRConfig, transformation::VertexAiOcrConfig,
     },
 };
+use litellm_llms_types::formats::ocr::{LiteLLMOcrResponse, OcrDocument, OcrResponseFormat};
 
 macro_rules! with_config {
     ($kind:expr, $config:ident => $body:expr) => {

litellm-rust/crates/core/src/ocr/route.rs

@@ -6,7 +6,8 @@ use litellm_host::{
     protocol::Protocol,
     protocol::Reply,
 };
-use litellm_llms::base_llm::ocr::{error::Error, transformation::LiteLLMOcrResponse};
+use litellm_llms::base_llm::ocr::error::Error;
+use litellm_llms_types::formats::ocr::LiteLLMOcrResponse;
 
 use crate::ocr::types::{LiteLLMOcrRequest, OcrDocumentInput};
 

litellm-rust/crates/core/src/ocr/types.rs

@@ -5,10 +5,9 @@ use litellm_auth::{InputSource, SecretValue, TokenProviderHandle};
 use litellm_core_utils::call_arguments::CallArguments;
 use litellm_llms::base_llm::ocr::{
     error::Error,
-    transformation::{
-        OcrCredentialInputs, OcrDocument, OcrResponseFormat, OcrTransportConfig, response_format,
-    },
+    transformation::{OcrCredentialInputs, OcrTransportConfig, response_format},
 };
+use litellm_llms_types::formats::ocr::{OcrDocument, OcrResponseFormat};
 use serde_json::{Map, Value};
 
 use super::provider_config::{OcrConfigKind, resolve_provider_config};
@@ -222,7 +221,7 @@ mod tests {
     use super::*;
 
     fn document() -> OcrDocument {
-        OcrDocument::try_from(
+        serde_json::from_value(
             json!({"type":"document_url","document_url":"data:application/pdf;base64,YWJj"}),
         )
         .unwrap()

litellm-rust/crates/core/src/ocr/wire.rs

@@ -1,10 +1,8 @@
 use std::{collections::BTreeMap, time::Duration};
 
 use litellm_auth::{InputSource, SecretValue};
-use litellm_llms::base_llm::ocr::{
-    error::Error,
-    transformation::{OcrDocument, decode_request_value},
-};
+use litellm_llms::base_llm::ocr::{error::Error, transformation::decode_request_value};
+use litellm_llms_types::formats::ocr::OcrDocument;
 use serde::Deserialize;
 use serde_json::{Map, Value};
 

litellm-rust/crates/core/src/responses/handler.rs

@@ -15,10 +15,16 @@ pub(super) async fn execute(
     http: &litellm_http::Client,
     auth: &litellm_auth::AuthServices,
     request: ProviderResponsesRequest,
+    cache: Option<litellm_cache_response::ScopedCache>,
+    cache_options: Option<litellm_cache_response::CachePolicy>,
     interceptors: &impl Interceptors<Error>,
     observers: Option<&ObservationSender>,
 ) -> Result<ResponsesOutput, Error> {
     let authenticated = resolve_auth(auth, request.environment, &|_| None).await?;
+    let identity = litellm_host::interceptors::ProviderIdentity {
+        model: request.context.model.clone(),
+        provider: request.context.custom_llm_provider.clone(),
+    };
     let wire = interceptors
         .before_provider_request(
             WireRequest {
@@ -29,65 +35,80 @@ pub(super) async fn execute(
             request.context,
         )
         .await?;
-    let stream = match wire.body.get("stream") {
-        None => false,
-        Some(serde_json::Value::Bool(value)) => *value,
-        Some(_) => return Err(Error::InvalidRequest("stream must be a boolean".into())),
-    };
-    let outbound = crate::outbound::outbound_request(
-        Authenticated {
-            headers: wire.headers,
-            signer: authenticated.signer,
+    let cache = cache.filter(|_| authenticated.signer.is_none());
+    let cache_request =
+        crate::caching::CacheRequest::from_wire(identity, cache.as_ref().map(|_| &wire));
+    crate::caching::execute_streaming::<super::route::Responses, _, _>(
+        cache_request,
+        cache.as_ref().map(|cache| cache.service.clone()),
+        cache.as_ref().map(|cache| cache.options(cache_options)),
+        interceptors,
+        observers,
+        || async move {
+            let stream = match wire.body.get("stream") {
+                None => false,
+                Some(serde_json::Value::Bool(value)) => *value,
+                Some(_) => return Err(Error::InvalidRequest("stream must be a boolean".into())),
+            };
+            let outbound = crate::outbound::outbound_request(
+                Authenticated {
+                    headers: wire.headers,
+                    signer: authenticated.signer,
+                },
+                wire.url,
+                &wire.body,
+                Some(request.timeout.unwrap_or(Duration::from_secs(600))),
+            )?;
+            let response = crate::outbound::send(outbound, http)
+                .await
+                .map_err(network)?;
+            let status = response.status().as_u16();
+            if !response.status().is_success() {
+                let body = response.text().await.map_err(network)?;
+                return Err(litellm_http::transport::Error::Http {
+                    status,
+                    body: litellm_http::request::truncate_error_body(&body),
+                }
+                .into());
+            }
+            if stream {
+                let headers = response
+                    .headers()
+                    .iter()
+                    .filter_map(|(name, value)| {
+                        Some((name.to_string(), value.to_str().ok()?.to_owned()))
+                    })
+                    .collect();
+                let chunks = response
+                    .bytes_stream()
+                    .map(|chunk| chunk.map_err(network))
+                    .boxed();
+                return Ok(ResponsesOutput::Stream {
+                    head: ResponsesStreamHead { headers },
+                    chunks,
+                });
+            }
+            let body = response.text().await.map_err(network)?;
+            let raw = RawResponse { body: body.clone() };
+            if let Some(observers) = observers {
+                observers.emit(litellm_host::lifecycle::CallEvent::Execution(
+                    ExecutionEvent::ProviderResponseReceived { raw: raw.clone() },
+                ));
+            }
+            interceptors
+                .after_provider_response(raw)
+                .await
+                .map_err(Error::post_call)?;
+            let value = serde_json::from_str(&body)
+                .map_err(|error| Error::InvalidResponse(error.to_string().into()))?;
+            request
+                .config
+                .transform_response_api_response(value)
+                .map(ResponsesOutput::Complete)
+                .map_err(Error::from)
         },
-        wire.url,
-        &wire.body,
-        Some(request.timeout.unwrap_or(Duration::from_secs(600))),
-    )?;
-    let response = crate::outbound::send(outbound, http)
-        .await
-        .map_err(network)?;
-    let status = response.status().as_u16();
-    if !response.status().is_success() {
-        let body = response.text().await.map_err(network)?;
-        return Err(litellm_http::transport::Error::Http {
-            status,
-            body: litellm_http::request::truncate_error_body(&body),
-        }
-        .into());
-    }
-    if stream {
-        let headers = response
-            .headers()
-            .iter()
-            .filter_map(|(name, value)| Some((name.to_string(), value.to_str().ok()?.to_owned())))
-            .collect();
-        let chunks = response
-            .bytes_stream()
-            .map(|chunk| chunk.map_err(network))
-            .boxed();
-        return Ok(ResponsesOutput::Stream {
-            head: ResponsesStreamHead { headers },
-            chunks,
-        });
-    }
-    let body = response.text().await.map_err(network)?;
-    let raw = RawResponse { body: body.clone() };
-    if let Some(observers) = observers {
-        observers.emit(litellm_host::lifecycle::CallEvent::Execution(
-            ExecutionEvent::ProviderResponseReceived { raw: raw.clone() },
-        ));
-    }
-    interceptors
-        .after_provider_response(raw)
-        .await
-        .map_err(Error::post_call)?;
-    let value = serde_json::from_str(&body)
-        .map_err(|error| Error::InvalidResponse(error.to_string().into()))?;
-    request
-        .config
-        .transform_response_api_response(value)
-        .map(ResponsesOutput::Complete)
-        .map_err(Error::from)
+    )
+    .await
 }
 
 fn network(error: reqwest::Error) -> Error {

litellm-rust/crates/core/src/responses/mod.rs

@@ -19,6 +19,7 @@ pub struct ResponsesRoute {
     http: litellm_http::Client,
     auth: Arc<AuthServices>,
     secrets: Arc<dyn SecretSource>,
+    cache: Option<litellm_cache_response::ScopedCache>,
 }
 
 impl ResponsesRoute {
@@ -31,6 +32,14 @@ impl ResponsesRoute {
             http,
             auth,
             secrets,
+            cache: None,
+        }
+    }
+
+    pub fn with_cache(self, cache: litellm_cache_response::ScopedCache) -> Self {
+        Self {
+            cache: Some(cache),
+            ..self
         }
     }
 
@@ -38,11 +47,15 @@ impl ResponsesRoute {
         &self,
         call: ResponsesCall,
         interceptors: &impl Interceptors<Error>,
-        observers: Option<ObservationSender>,
+        options: impl Into<crate::CallOptions>,
     ) -> Result<ResponsesOutput, Error> {
+        let crate::CallOptions {
+            cache: cache_options,
+            observers,
+        } = options.into();
         litellm_host::lifecycle::observe_call(
             observers.clone(),
-            self.run(call, interceptors, observers.as_ref()),
+            self.run(call, cache_options, interceptors, observers.as_ref()),
         )
         .await
     }
@@ -58,25 +71,36 @@ impl ResponsesRoute {
     async fn run(
         &self,
         call: ResponsesCall,
-        interceptors: &impl Interceptors<Error>,
+        cache_options: Option<litellm_cache_response::CachePolicy>,
+        interceptors: &impl litellm_host::interceptors::Interceptors<Error>,
         observers: Option<&ObservationSender>,
     ) -> Result<ResponsesOutput, Error> {
         crate::diagnostic::call(async {
-            let request = prepare::prepare(call, self.secrets.as_ref()).await?;
-            crate::diagnostic::provider(
-                &request.context.model,
-                &request.context.custom_llm_provider,
-            );
-            let execute: futures_util::future::BoxFuture<'_, Result<ResponsesOutput, Error>> =
-                Box::pin(handler::execute(
-                    &self.http,
-                    &self.auth,
-                    request,
-                    interceptors,
-                    observers,
-                ));
-            execute.await
+            self.run_provider(call, cache_options, interceptors, observers)
+                .await
         })
         .await
     }
+
+    async fn run_provider(
+        &self,
+        call: ResponsesCall,
+        cache_options: Option<litellm_cache_response::CachePolicy>,
+        interceptors: &impl Interceptors<Error>,
+        observers: Option<&ObservationSender>,
+    ) -> Result<ResponsesOutput, Error> {
+        let request = prepare::prepare(call, self.secrets.as_ref()).await?;
+        crate::diagnostic::provider(&request.context.model, &request.context.custom_llm_provider);
+        let execute: futures_util::future::BoxFuture<'_, Result<ResponsesOutput, Error>> =
+            Box::pin(handler::execute(
+                &self.http,
+                &self.auth,
+                request,
+                self.cache.clone(),
+                cache_options,
+                interceptors,
+                observers,
+            ));
+        execute.await
+    }
 }

litellm-rust/crates/core/src/responses/prepare.rs

@@ -16,14 +16,9 @@ pub(super) async fn prepare(
     call: ResponsesCall,
     secrets: &dyn SecretSource,
 ) -> Result<ProviderResponsesRequest, Error> {
-    let provider = call.custom_llm_provider.as_deref().unwrap_or("openai");
-    if provider != "openai" {
-        return Err(Error::Unsupported("native HTTP responses provider"));
-    }
-    let model = call.model.strip_prefix("openai/").unwrap_or(&call.model);
-    if model.is_empty() || model.contains('/') {
-        return Err(Error::InvalidProvider(call.model));
-    }
+    let identity = resolve_provider(&call.model, call.custom_llm_provider.as_deref())?;
+    let provider = identity.provider.as_str();
+    let model = identity.model.as_str();
     let config: &'static dyn BaseResponsesApiConfig = &OpenAiResponsesApiConfig;
     let snapshot = secrets
         .resolve(config.secret_names(call.api_key.as_deref(), call.api_base.as_deref()))
@@ -56,3 +51,21 @@ pub(super) async fn prepare(
         timeout: call.timeout,
     })
 }
+
+pub(super) fn resolve_provider(
+    model: &str,
+    custom_llm_provider: Option<&str>,
+) -> Result<litellm_host::interceptors::ProviderIdentity, Error> {
+    let provider = custom_llm_provider.unwrap_or("openai");
+    if provider != "openai" {
+        return Err(Error::Unsupported("native HTTP responses provider"));
+    }
+    let resolved = model.strip_prefix("openai/").unwrap_or(model);
+    if resolved.is_empty() || resolved.contains('/') {
+        return Err(Error::InvalidProvider(model.into()));
+    }
+    Ok(litellm_host::interceptors::ProviderIdentity {
+        model: resolved.into(),
+        provider: provider.into(),
+    })
+}

litellm-rust/crates/core/src/responses/route.rs

@@ -1,4 +1,3 @@
-use litellm_host::observation::ObservationSender;
 use std::convert::Infallible;
 
 use bytes::Bytes;
@@ -6,7 +5,7 @@ use litellm_host::{
     call::{HostedMachine, hosted_call},
     protocol::Protocol,
 };
-use litellm_types::responses::main::ResponsesApiResponse;
+use litellm_llms_types::formats::responses::ResponsesApiResponse;
 
 use super::{
     Error, ResponsesRoute,
@@ -28,14 +27,48 @@ impl ResponsesRoute {
     pub fn machine(
         self,
         call: ResponsesCall,
-        observers: Option<ObservationSender>,
+        options: impl Into<crate::CallOptions>,
     ) -> HostedMachine<Responses> {
+        let crate::CallOptions {
+            cache: cache_options,
+            observers,
+        } = options.into();
         hosted_call(
             call,
             observers,
             move |call, _, interceptors, observers| async move {
-                self.run(call, &interceptors, observers.as_ref()).await
+                self.run(call, cache_options, &interceptors, observers.as_ref())
+                    .await
             },
         )
     }
 }
+
+impl crate::caching::Cachable for Responses {
+    const SURFACE: &'static str = "responses";
+
+    fn reusable(response: &Self::Response) -> bool {
+        response
+            .extra
+            .get("status")
+            .and_then(serde_json::Value::as_str)
+            == Some("completed")
+    }
+}
+
+impl crate::caching::StreamCachable for Responses {
+    const TERMINAL_EVENT: &'static str = "response.completed";
+
+    fn replay(data: bytes::Bytes) -> Option<litellm_host::call::OutputOf<Self>> {
+        Some(litellm_host::call::CallOutput::Stream {
+            head: ResponsesStreamHead {
+                headers: Vec::new(),
+            },
+            chunks: Box::pin(futures_util::stream::iter([Ok(data)])),
+        })
+    }
+
+    fn bytes(chunk: &Self::Chunk) -> &[u8] {
+        chunk.as_ref()
+    }
+}

litellm-rust/crates/core/src/responses/types.rs

@@ -5,7 +5,7 @@ use litellm_host::call::CallOutput;
 use litellm_llms::base_llm::{
     auth::ValidatedEnvironment, responses::transformation::BaseResponsesApiConfig,
 };
-use litellm_types::responses::main::ResponsesApiResponse;
+use litellm_llms_types::formats::responses::ResponsesApiResponse;
 use serde_json::{Map, Value};
 
 use super::Error;

litellm-rust/crates/core/src/responses/websocket.rs

@@ -2,7 +2,7 @@ use std::{collections::HashMap, sync::Arc, time::Duration};
 
 use futures_util::{SinkExt, StreamExt};
 use litellm_http::websocket::{UpstreamWebSocket, connect_upstream};
-use litellm_types::responses::streaming_websocket::ResponsesWsEventType;
+use litellm_llms_types::formats::responses::streaming_websocket::ResponsesWsEventType;
 use tokio::sync::Mutex;
 use tokio_tungstenite::tungstenite::{
     Message,

litellm-rust/crates/core/tests/chat_completions.rs

@@ -1,9 +1,13 @@
 use litellm_host::interceptors::RawResponse;
+use litellm_host::{
+    interceptors::{ExecutionFacts, ResultSource},
+    lifecycle::ExecutionEvent,
+};
 use std::time::Duration;
 
 use litellm_core::chat_completions::{Error, types::ChatCompletionsRequest};
 use litellm_http::transport::Error as TransportError;
-use litellm_types::utils::ChatCompletionsResponse;
+use litellm_llms_types::formats::chat_completions::ChatCompletionsResponse;
 use rstest::{fixture, rstest};
 use serde_json::{Map, Value, json};
 use wiremock::ResponseTemplate;
@@ -310,7 +314,13 @@ async fn direct_and_hosted_calls_share_hooks_and_lifecycle(
         &events[..],
         [
             CallEvent::Started { .. },
-            CallEvent::Execution(_),
+            CallEvent::Execution(ExecutionEvent::ProviderResponseReceived { .. }),
+            CallEvent::Execution(ExecutionEvent::ResultReady {
+                facts: ExecutionFacts {
+                    source: ResultSource::Provider,
+                    ..
+                }
+            }),
             CallEvent::Succeeded { .. }
         ]
     ));

litellm-rust/crates/core/tests/messages/host.rs

@@ -1,9 +1,9 @@
 use litellm_host::lifecycle::ExecutionEvent;
 use std::sync::Mutex;
 
-use litellm_core::messages::route::Messages;
+use litellm_core::messages::{MessagesCallResponse, route::Messages};
 use litellm_host::{
-    interceptors::{RequestContext, WireRequest},
+    interceptors::{ExecutionFacts, RequestContext, ResultSource, WireRequest},
     lifecycle::CallEvent,
 };
 use litellm_llms::base_llm::messages::context::MessagesModelCapabilities as AnthropicModelCapabilities;
@@ -20,6 +20,8 @@ struct RecordingHost {
     rewrite: Rewrite,
     events: super::support::Observations,
     optional_params: Mutex<Vec<Value>>,
+    facts: Mutex<Vec<ExecutionFacts>>,
+    reject_result: bool,
 }
 
 impl RecordingHost {
@@ -29,6 +31,8 @@ impl RecordingHost {
             rewrite,
             events: super::support::Observations::default(),
             optional_params: Mutex::new(Vec::new()),
+            facts: Mutex::new(Vec::new()),
+            reject_result: false,
         }
     }
 
@@ -73,6 +77,14 @@ impl litellm_host::lifecycle::CallObserver for RecordingHost {
 impl litellm_host::interceptors::Interceptors<<Messages as litellm_host::protocol::Protocol>::Error>
     for RecordingHost
 {
+    async fn result_ready(&self, facts: ExecutionFacts) -> Result<(), Error> {
+        self.facts.lock().unwrap().push(facts);
+        if self.reject_result {
+            return Err(Error::Unsupported("result rejected"));
+        }
+        Ok(())
+    }
+
     async fn before_provider_request(
         &self,
         wire: WireRequest,
@@ -98,6 +110,91 @@ impl litellm_host::interceptors::Interceptors<<Messages as litellm_host::protoco
     }
 }
 
+#[rstest]
+#[case::native_unary(false, false)]
+#[case::native_stream(true, false)]
+#[case::hosted_unary(false, true)]
+#[case::hosted_stream(true, true)]
+#[tokio::test]
+async fn rejected_results_are_not_delivered_or_cached(
+    call: MessagesCall,
+    #[case] streaming: bool,
+    #[case] hosted: bool,
+) {
+    use futures_util::TryStreamExt;
+    use litellm_cache_memory::InMemoryCache;
+    use litellm_cache_response::{CacheScope, ResponseCache, ScopedCache};
+
+    let response = if streaming {
+        ResponseTemplate::new(200).set_body_raw(
+            "event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n",
+            "text/event-stream",
+        )
+    } else {
+        message_response()
+    };
+    let upstream = upstream([response.clone(), response]).await;
+    let route = messages_route(no_secrets()).with_cache(ScopedCache::new(
+        Arc::new(ResponseCache::new(Arc::new(InMemoryCache::new(
+            Some(100),
+            Some(Duration::from_secs(60)),
+        )))),
+        CacheScope::Shared,
+    ));
+    for (reject, expected_requests, cached) in [
+        (true, 1, false),
+        (false, 2, false),
+        (true, 2, true),
+        (false, 2, true),
+    ] {
+        let request = authenticated(
+            with_fields(
+                MessagesCall {
+                    body: call.body.clone(),
+                    ..super::call()
+                },
+                json!({"stream": streaming}),
+            ),
+            upstream.uri(),
+        );
+        let host = RecordingHost {
+            reject_result: reject,
+            ..RecordingHost::passthrough(request)
+        };
+        let result = if hosted {
+            litellm_host_native::in_process::run_hosted(
+                route.clone().machine(host.request().unwrap(), None),
+                host.runtime(),
+            )
+            .await
+            .map(|_| ())
+        } else {
+            match route.execute(host.request().unwrap(), &host, None).await {
+                Ok(MessagesCallResponse::Complete(_)) => Ok(()),
+                Ok(MessagesCallResponse::Stream { chunks, .. }) => {
+                    chunks.try_collect::<Vec<_>>().await.map(|_| ())
+                }
+                Err(error) => Err(error),
+            }
+        };
+        assert_eq!(
+            result,
+            if reject {
+                Err(Error::Unsupported("result rejected"))
+            } else {
+                Ok(())
+            }
+        );
+        assert_eq!(received(&upstream).await.len(), expected_requests);
+        let facts = host.facts.lock().unwrap();
+        assert_eq!(facts.len(), 1);
+        assert_eq!(
+            matches!(facts[0].source, ResultSource::Cache { .. }),
+            cached
+        );
+    }
+}
+
 async fn run_through(host: &RecordingHost) -> Result<MessagesOutput, Error> {
     litellm_host_native::in_process::run_hosted(
         machine(Arc::new(RecordingSecrets::empty()))(host.request()?),
@@ -143,6 +240,81 @@ async fn what_before_send_returns_is_what_the_provider_receives(call: MessagesCa
     assert_eq!(request.header("x-api-key"), Some("sk-ant"));
 }
 
+#[rstest]
+#[case::enable(false, json!(true), Some(true))]
+#[case::disable(true, json!(false), Some(false))]
+#[case::null(true, Value::Null, Some(false))]
+#[case::invalid(false, json!("true"), None)]
+#[tokio::test]
+async fn response_mode_follows_the_intercepted_request(
+    call: MessagesCall,
+    traces: TraceCapture,
+    #[case] original_stream: bool,
+    #[case] rewritten_stream: Value,
+    #[case] expected_stream: Option<bool>,
+) {
+    use futures_util::TryStreamExt;
+
+    let sse = "event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n";
+    let response = if expected_stream == Some(true) {
+        ResponseTemplate::new(200).set_body_raw(sse, "text/event-stream")
+    } else {
+        message_response()
+    };
+    let upstream = upstream([response]).await;
+    let rewrite = rewritten_stream.clone();
+    let host = RecordingHost::new(
+        authenticated(
+            with_fields(call, json!({"stream": original_stream})),
+            upstream.uri(),
+        ),
+        Box::new(move |wire| {
+            let mut body = wire.body;
+            body["stream"] = rewrite.clone();
+            Ok(WireRequest { body, ..wire })
+        }),
+    );
+    let result = traces
+        .logger()
+        .instrument(async {
+            let output = messages_route(no_secrets())
+                .execute(host.request()?, &host, None)
+                .await?;
+            match output {
+                MessagesCallResponse::Stream { chunks, .. } => {
+                    assert_eq!(expected_stream, Some(true));
+                    assert_eq!(
+                        chunks.try_collect::<Vec<_>>().await?.concat(),
+                        sse.as_bytes()
+                    );
+                }
+                MessagesCallResponse::Complete(message) => {
+                    assert_eq!(expected_stream, Some(false));
+                    assert_eq!(*message, serde_json::from_value(message_body()).unwrap());
+                }
+            }
+            Ok::<_, Error>(())
+        })
+        .await;
+
+    let summaries = traces.summaries("litellm.route");
+    assert_eq!(summaries.len(), 1);
+    let Some(expected_stream) = expected_stream else {
+        assert!(matches!(result, Err(Error::InvalidRequest(_))));
+        assert!(received(&upstream).await.is_empty());
+        assert_eq!(summaries[0]["outcome"], "failure");
+        return;
+    };
+    result.unwrap();
+    assert_eq!(
+        only_request(&upstream).await.json()["stream"],
+        rewritten_stream
+    );
+    assert_eq!(host.raw_responses().len(), usize::from(!expected_stream));
+    assert_eq!(summaries[0]["stream"], expected_stream);
+    assert_eq!(summaries[0]["outcome"], "success");
+}
+
 #[rstest]
 #[tokio::test]
 async fn a_before_send_failure_never_sends(call: MessagesCall) {

litellm-rust/crates/core/tests/messages/main.rs

@@ -8,10 +8,8 @@ use litellm_core::messages::{
     route::{Messages, MessagesMachine, MessagesOutput},
 };
 use litellm_http::{HttpSettings, Resolution};
+use litellm_llms_types::formats::messages::{MessagesRequest, MessagesResponse};
 use litellm_secrets::source::SecretSource;
-use litellm_types::llms::anthropic_messages::{
-    anthropic_request::AnthropicMessagesRequest, anthropic_response::AnthropicMessagesResponse,
-};
 use rstest::fixture;
 use serde_json::{Map, Value, json};
 use wiremock::ResponseTemplate;
@@ -35,7 +33,7 @@ fn object(value: Value) -> Map<String, Value> {
     map
 }
 
-fn body(value: Value) -> AnthropicMessagesRequest {
+fn body(value: Value) -> MessagesRequest {
     serde_json::from_value(value).unwrap()
 }
 
@@ -116,7 +114,7 @@ async fn run(call: MessagesCall) -> Result<MessagesOutput, Error> {
     run_with(Arc::new(RecordingSecrets::empty()), call).await
 }
 
-async fn run_message(call: MessagesCall) -> AnthropicMessagesResponse {
+async fn run_message(call: MessagesCall) -> MessagesResponse {
     match run(call).await.expect("messages call succeeds") {
         MessagesOutput::Complete(message) => *message,
         MessagesOutput::StreamEnded | MessagesOutput::Detached => {

litellm-rust/crates/core/tests/messages/request.rs

@@ -1,6 +1,8 @@
 use litellm_llms::base_llm::messages::context::{MessagesModelCapabilities, SupportedEffortTiers};
-use litellm_types::llms::anthropic::{AnthropicBeta, BetaSet};
-use litellm_types::utils::{ProviderSpecificHeader, ProviderSpecificHeaders};
+use litellm_llms_types::{
+    headers::{ProviderSpecificHeader, ProviderSpecificHeaders},
+    providers::anthropic::{AnthropicBeta, BetaSet},
+};
 use rstest::rstest;
 
 use super::*;

litellm-rust/crates/core/tests/messages/response.rs

@@ -1,4 +1,8 @@
-use litellm_core::messages::{MessagesResponse, messages_body};
+use litellm_core::messages::{MessagesCallResponse, messages_body};
+use litellm_host::{
+    interceptors::{ExecutionFacts, ResultSource},
+    lifecycle::ExecutionEvent,
+};
 use litellm_http::transport::Error as TransportError;
 use rstest::rstest;
 
@@ -29,7 +33,7 @@ async fn calls_defer_execution_until_polled(
     let request = host.request().unwrap();
     let observer: Option<litellm_host::observation::ObservationSender> =
         with_observer.then(|| host.events.0.sender.clone());
-    let future: BoxFuture<'_, Result<MessagesResponse, Error>> = if with_hooks {
+    let future: BoxFuture<'_, Result<MessagesCallResponse, Error>> = if with_hooks {
         Box::pin(route.execute(request, &host, observer))
     } else {
         Box::pin(route.execute(request, &(), observer))
@@ -39,7 +43,7 @@ async fn calls_defer_execution_until_polled(
     assert!(host.events.0.lock().unwrap().is_empty());
     assert!(received(&upstream).await.is_empty());
 
-    let MessagesResponse::Complete(response) = future.await.unwrap() else {
+    let MessagesCallResponse::Complete(response) = future.await.unwrap() else {
         panic!("expected a completed message");
     };
     assert_eq!(
@@ -60,7 +64,13 @@ async fn calls_defer_execution_until_polled(
                 true,
                 [
                     CallEvent::Started { .. },
-                    CallEvent::Execution(_),
+                    CallEvent::Execution(ExecutionEvent::ProviderResponseReceived { .. }),
+                    CallEvent::Execution(ExecutionEvent::ResultReady {
+                        facts: ExecutionFacts {
+                            source: ResultSource::Provider,
+                            ..
+                        }
+                    }),
                     CallEvent::Succeeded { .. }
                 ]
             )
@@ -69,7 +79,13 @@ async fn calls_defer_execution_until_polled(
                 true,
                 [
                     CallEvent::Started { .. },
-                    CallEvent::Execution(_),
+                    CallEvent::Execution(ExecutionEvent::ProviderResponseReceived { .. }),
+                    CallEvent::Execution(ExecutionEvent::ResultReady {
+                        facts: ExecutionFacts {
+                            source: ResultSource::Provider,
+                            ..
+                        }
+                    }),
                     CallEvent::Succeeded { .. }
                 ]
             )
@@ -270,7 +286,7 @@ async fn the_facade_sends_through_the_injected_http_pool_configuration(call: Mes
     .await
     .expect("messages request succeeds");
 
-    let MessagesResponse::Complete(message) = response else {
+    let MessagesCallResponse::Complete(message) = response else {
         panic!("a non-streaming request returns a message");
     };
     assert_eq!(message.id, "msg_1");
@@ -321,3 +337,120 @@ async fn message_route_summary_excludes_payload_diagnostics(
     assert!(summaries[0].get("body").is_none());
     assert!(!format!("{:?}", traces.records()).contains("private-key-sentinel"));
 }
+
+#[rstest]
+#[case::uncached(false, 2)]
+#[case::cached(true, 1)]
+#[tokio::test]
+async fn route_uses_injected_dependencies_and_optional_cache(
+    #[case] caching: bool,
+    #[case] expected_requests: usize,
+) {
+    use litellm_cache_memory::InMemoryCache;
+    use litellm_cache_response::{CacheScope, ResponseCache, ScopedCache};
+    use litellm_core::messages::MessagesRoute;
+
+    let upstream = upstream([message_response(), message_response()]).await;
+    let resources = resources();
+    let route = MessagesRoute::new(
+        provider_http(&resources, &http_config()),
+        resources.auth.clone(),
+        Arc::new(RecordingSecrets::new([("ANTHROPIC_API_KEY", "route-key")])),
+    );
+    let route = if caching {
+        route.with_cache(ScopedCache::new(
+            Arc::new(ResponseCache::new(Arc::new(InMemoryCache::new(
+                Some(100),
+                Some(Duration::from_secs(60)),
+            )))),
+            CacheScope::Shared,
+        ))
+    } else {
+        route
+    };
+    for _ in 0..2 {
+        let request = MessagesCall {
+            api_base: Some(upstream.uri()),
+            ..super::call()
+        };
+        let MessagesCallResponse::Complete(response) =
+            route.execute(request, &(), None).await.unwrap()
+        else {
+            panic!("expected a completed message");
+        };
+        assert_eq!(
+            response.content,
+            message_body()["content"].as_array().unwrap().as_slice()
+        );
+    }
+    let requests = received(&upstream).await;
+    assert_eq!(requests.len(), expected_requests);
+    assert_eq!(requests[0].header("x-api-key"), Some("route-key"));
+}
+
+#[rstest]
+#[tokio::test]
+async fn cache_overrides_preserve_the_routes_isolated_scope(call: MessagesCall) {
+    use litellm_cache_memory::InMemoryCache;
+    use litellm_cache_response::{CachePolicy, CacheScope, ResponseCache, ScopedCache};
+
+    let first_body = message_body();
+    let second_body = Value::Object(
+        first_body
+            .as_object()
+            .unwrap()
+            .iter()
+            .map(|(key, value)| {
+                (
+                    key.clone(),
+                    if key == "id" {
+                        json!("msg_second")
+                    } else {
+                        value.clone()
+                    },
+                )
+            })
+            .collect(),
+    );
+    let upstream = upstream([
+        json_response(first_body.clone()),
+        json_response(second_body.clone()),
+    ])
+    .await;
+    let service = Arc::new(ResponseCache::new(Arc::new(InMemoryCache::new(
+        Some(100),
+        Some(Duration::from_secs(60)),
+    ))));
+    let first = messages_route(no_secrets()).with_cache(ScopedCache::new(
+        service.clone(),
+        CacheScope::Isolated("first".into()),
+    ));
+    let second = messages_route(no_secrets()).with_cache(ScopedCache::new(
+        service,
+        CacheScope::Isolated("second".into()),
+    ));
+    for (route, expected) in [
+        (&first, &first_body),
+        (&second, &second_body),
+        (&first, &first_body),
+        (&second, &second_body),
+    ] {
+        let request = MessagesCall {
+            body: call.body.clone(),
+            api_key: Some("same-key".into()),
+            api_base: Some(upstream.uri()),
+            ..super::call()
+        };
+        let override_options = CachePolicy {
+            ttl: Some(Duration::from_secs(30)),
+            ..CachePolicy::default()
+        };
+        let MessagesCallResponse::Complete(response) =
+            route.execute(request, &(), override_options).await.unwrap()
+        else {
+            panic!("expected a completed message");
+        };
+        assert_eq!(response.id, expected["id"].as_str().unwrap());
+    }
+    assert_eq!(received(&upstream).await.len(), 2);
+}

litellm-rust/crates/core/tests/messages/stream.rs

@@ -6,7 +6,7 @@ use std::{
 use bytes::Bytes;
 use futures_util::{StreamExt, TryStreamExt};
 use litellm_core::messages::{
-    MessagesResponse,
+    MessagesCallResponse,
     route::{Messages, MessagesStreamHead},
 };
 use litellm_tracing::{Logger, Metadata, Record, Sink};
@@ -353,7 +353,7 @@ async fn the_sdk_returns_stream_headers_and_every_sse_byte(
         .await
         .unwrap();
 
-    let MessagesResponse::Stream { head, chunks } = response else {
+    let MessagesCallResponse::Stream { head, chunks } = response else {
         panic!("a streaming request returns a stream");
     };
     for (name, value) in UPSTREAM_HEADERS {
@@ -407,7 +407,7 @@ async fn dropping_the_sdk_stream_closes_the_unfinished_upstream(
     .expect("messages() returns before the upstream finishes")
     .unwrap();
 
-    let MessagesResponse::Stream { mut chunks, .. } = response else {
+    let MessagesCallResponse::Stream { mut chunks, .. } = response else {
         panic!("a streaming request returns a stream");
     };
     if read_chunk {
@@ -442,7 +442,7 @@ async fn the_sdk_yields_a_body_error_once_after_delivered_chunks(call: MessagesC
         .await
         .unwrap();
 
-    let MessagesResponse::Stream { mut chunks, .. } = response else {
+    let MessagesCallResponse::Stream { mut chunks, .. } = response else {
         panic!("a streaming request returns a stream");
     };
     assert_eq!(

litellm-rust/crates/core/tests/ocr/lifecycle.rs

@@ -19,6 +19,7 @@ use super::*;
 
 pub(crate) fn event_name(event: &CallEvent) -> &'static str {
     match event {
+        CallEvent::Execution(ExecutionEvent::ResultReady { .. }) => "result_ready",
         CallEvent::Started { .. } => "started",
         CallEvent::Execution(ExecutionEvent::ProviderResponseReceived { .. }) => "response",
         CallEvent::Succeeded { .. } => "success",

litellm-rust/crates/core/tests/ocr/machine.rs

@@ -41,6 +41,11 @@ async fn drive_until(
             Err(error) => break Err(error),
         };
         let answer = match op {
+            HostRequest::Intercept(InterceptRequest::ResultReady { facts, reply }) => host
+                .result_ready(facts)
+                .await
+                .map(|()| reply.send(()))
+                .map_err(HostFailure::Error),
             HostRequest::Stream(stream) => match stream {
                 litellm_host::protocol::StreamDelivery::Open(head, _) => match head {},
                 litellm_host::protocol::StreamDelivery::Chunk(chunk, _) => match chunk {},
@@ -80,6 +85,7 @@ async fn drive_until_notified(machine: &mut OcrMachine, host: &LocalOcrHost, sto
                 _ = stop.notified() => break,
                 step = machine.resume() => {
                     match step.unwrap() {
+                        MachineStep::Suspended(HostRequest::Intercept(InterceptRequest::ResultReady { reply, .. })) => reply.send(()),
                         MachineStep::Suspended(HostRequest::HostCall(op)) => host.handle_host_call(op).await.unwrap(),
                         MachineStep::Suspended(HostRequest::Intercept(InterceptRequest::BeforeProviderRequest { wire, reply, .. })) => reply.send(*wire),
                         MachineStep::Suspended(HostRequest::Intercept(InterceptRequest::AfterProviderResponse { reply, .. })) => reply.send(()),