langchain/dist/agents/middleware/provider/anthropic/promptCaching.cjs.map

Typescript bindings for langchain

{"version":3,"file":"promptCaching.cjs","names":["z","createMiddleware"],"sources":["../../../../../src/agents/middleware/provider/anthropic/promptCaching.ts"],"sourcesContent":["import { z } from \"zod/v3\";\nimport { InferInteropZodInput } from \"@langchain/core/utils/types\";\n\nimport { ConfigurableModel } from \"../../../../chat_models/universal.js\";\nimport { createMiddleware } from \"../../../middleware.js\";\n\nconst DEFAULT_ENABLE_CACHING = true;\nconst DEFAULT_TTL = \"5m\";\nconst DEFAULT_MIN_MESSAGES_TO_CACHE = 3;\nconst DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR = \"warn\";\n\nconst contextSchema = z.object({\n  /**\n   * Whether to enable prompt caching.\n   * @default true\n   */\n  enableCaching: z.boolean().optional(),\n  /**\n   * The time-to-live for the cached prompt.\n   * @default \"5m\"\n   */\n  ttl: z.enum([\"5m\", \"1h\"]).optional(),\n  /**\n   * The minimum number of messages required before caching is applied.\n   * @default 3\n   */\n  minMessagesToCache: z.number().optional(),\n  /**\n   * The behavior to take when an unsupported model is used.\n   * - \"ignore\" will ignore the unsupported model and continue without caching.\n   * - \"warn\" will warn the user and continue without caching.\n   * - \"raise\" will raise an error and stop the agent.\n   * @default \"warn\"\n   */\n  unsupportedModelBehavior: z.enum([\"ignore\", \"warn\", \"raise\"]).optional(),\n});\nexport type PromptCachingMiddlewareConfig = Partial<\n  InferInteropZodInput<typeof contextSchema>\n>;\n\nclass PromptCachingMiddlewareError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"PromptCachingMiddlewareError\";\n  }\n}\n\n/**\n * Creates a prompt caching middleware for Anthropic models to optimize API usage.\n *\n * This middleware automatically adds cache control headers to the last messages when using Anthropic models,\n * enabling their prompt caching feature. This can significantly reduce costs for applications with repetitive\n * prompts, long system messages, or extensive conversation histories.\n *\n * ## How It Works\n *\n * The middleware intercepts model requests and adds cache control metadata that tells Anthropic's\n * API to cache processed prompt prefixes. On subsequent requests with matching prefixes, the\n * cached representations are reused, skipping redundant token processing.\n *\n * ## Benefits\n *\n * - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly (up to 90% savings on cached portions)\n * - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed\n * - **Better Scalability**: Reduced computational load enables handling more requests\n * - **Consistent Performance**: Stable response times for repetitive queries\n *\n * @param middlewareOptions - Configuration options for the caching behavior\n * @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)\n * @param middlewareOptions.ttl - Cache time-to-live: `\"5m\"` for 5 minutes or `\"1h\"` for 1 hour (default: `\"5m\"`)\n * @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `3`)\n * @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `\"warn\"`)\n *\n * @returns A middleware instance that can be passed to `createAgent`\n *\n * @throws {Error} If used with non-Anthropic models\n *\n * @example\n * Basic usage with default settings\n * ```typescript\n * import { createAgent } from \"langchain\";\n * import { anthropicPromptCachingMiddleware } from \"langchain\";\n *\n * const agent = createAgent({\n *   model: \"anthropic:claude-sonnet-4-5\",\n *   middleware: [\n *     anthropicPromptCachingMiddleware()\n *   ]\n * });\n * ```\n *\n * @example\n * Custom configuration for longer conversations\n * ```typescript\n * const cachingMiddleware = anthropicPromptCachingMiddleware({\n *   ttl: \"1h\",  // Cache for 1 hour instead of default 5 minutes\n *   minMessagesToCache: 5  // Only cache after 5 messages\n * });\n *\n * const agent = createAgent({\n *   model: \"anthropic:claude-sonnet-4-5\",\n *   systemPrompt: \"You are a helpful assistant with deep knowledge of...\", // Long system prompt\n *   middleware: [cachingMiddleware]\n * });\n * ```\n *\n * @example\n * Conditional caching based on runtime context\n * ```typescript\n * const agent = createAgent({\n *   model: \"anthropic:claude-sonnet-4-5\",\n *   middleware: [\n *     anthropicPromptCachingMiddleware({\n *       enableCaching: true,\n *       ttl: \"5m\"\n *     })\n *   ]\n * });\n *\n * // Disable caching for specific requests\n * await agent.invoke(\n *   { messages: [new HumanMessage(\"Process this without caching\")] },\n *   {\n *     configurable: {\n *       middleware_context: { enableCaching: false }\n *     }\n *   }\n * );\n * ```\n *\n * @example\n * Optimal setup for customer support chatbot\n * ```typescript\n * const supportAgent = createAgent({\n *   model: \"anthropic:claude-sonnet-4-5\",\n *   systemPrompt: `You are a customer support agent for ACME Corp.\n *\n *     Company policies:\n *     - Always be polite and professional\n *     - Refer to knowledge base for product information\n *     - Escalate billing issues to human agents\n *     ... (extensive policies and guidelines)\n *   `,\n *   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],\n *   middleware: [\n *     anthropicPromptCachingMiddleware({\n *       ttl: \"1h\",  // Long TTL for stable system prompt\n *       minMessagesToCache: 1  // Cache immediately due to large system prompt\n *     })\n *   ]\n * });\n * ```\n *\n * @remarks\n * - **Anthropic Only**: This middleware only works with Anthropic models and will throw an error if used with other providers\n * - **Automatic Application**: Caching is applied automatically when message count exceeds `minMessagesToCache`\n * - **Cache Scope**: Caches are isolated per API key and cannot be shared across different keys\n * - **TTL Options**: Only supports \"5m\" (5 minutes) and \"1h\" (1 hour) as TTL values per Anthropic's API\n * - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications\n * - **Cost Impact**: Cached tokens are billed at 10% of the base input token price, cache writes are billed at 25% of the base\n *\n * @see {@link createAgent} for agent creation\n * @see {@link https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching} Anthropic's prompt caching documentation\n * @public\n */\nexport function anthropicPromptCachingMiddleware(\n  middlewareOptions?: PromptCachingMiddlewareConfig\n) {\n  return createMiddleware({\n    name: \"PromptCachingMiddleware\",\n    contextSchema,\n    wrapModelCall: (request, handler) => {\n      /**\n       * Prefer runtime context values over middleware options values over defaults\n       */\n      const enableCaching =\n        request.runtime.context.enableCaching ??\n        middlewareOptions?.enableCaching ??\n        DEFAULT_ENABLE_CACHING;\n      const ttl =\n        request.runtime.context.ttl ?? middlewareOptions?.ttl ?? DEFAULT_TTL;\n      const minMessagesToCache =\n        request.runtime.context.minMessagesToCache ??\n        middlewareOptions?.minMessagesToCache ??\n        DEFAULT_MIN_MESSAGES_TO_CACHE;\n      const unsupportedModelBehavior =\n        request.runtime.context.unsupportedModelBehavior ??\n        middlewareOptions?.unsupportedModelBehavior ??\n        DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR;\n\n      // Skip if caching is disabled\n      if (!enableCaching || !request.model) {\n        return handler(request);\n      }\n\n      const isAnthropicModel =\n        request.model.getName() === \"ChatAnthropic\" ||\n        (request.model.getName() === \"ConfigurableModel\" &&\n          (request.model as ConfigurableModel)._defaultConfig?.modelProvider ===\n            \"anthropic\");\n      if (!isAnthropicModel) {\n        // Get model name for better error context\n        const modelName = request.model.getName();\n        const modelInfo =\n          request.model.getName() === \"ConfigurableModel\"\n            ? `${modelName} (${\n                (request.model as ConfigurableModel)._defaultConfig\n                  ?.modelProvider\n              })`\n            : modelName;\n\n        const baseMessage = `Unsupported model '${modelInfo}'. Prompt caching requires an Anthropic model`;\n\n        if (unsupportedModelBehavior === \"raise\") {\n          throw new PromptCachingMiddlewareError(\n            `${baseMessage} (e.g., 'anthropic:claude-4-0-sonnet').`\n          );\n        } else if (unsupportedModelBehavior === \"warn\") {\n          console.warn(\n            `PromptCachingMiddleware: Skipping caching for ${modelName}. Consider switching to an Anthropic model for caching benefits.`\n          );\n        }\n        return handler(request);\n      }\n\n      const messagesCount =\n        request.state.messages.length + (request.systemPrompt ? 1 : 0);\n\n      if (messagesCount < minMessagesToCache) {\n        return handler(request);\n      }\n\n      /**\n       * The cache_control is applied at the final message formatting layer in ChatAnthropic,\n       * which avoids issues with message content block manipulation during earlier\n       * processing stages (e.g., streaming response reassembly).\n       *\n       * @see https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching\n       */\n      return handler({\n        ...request,\n        modelSettings: {\n          ...request.modelSettings,\n          cache_control: {\n            type: \"ephemeral\" as const,\n            ttl,\n          },\n        },\n      });\n    },\n  });\n}\n"],"mappings":";;;;AAMA,MAAM,yBAAyB;AAC/B,MAAM,cAAc;AACpB,MAAM,gCAAgC;AACtC,MAAM,qCAAqC;AAE3C,MAAM,gBAAgBA,OAAAA,EAAE,OAAO;;;;;CAK7B,eAAeA,OAAAA,EAAE,SAAS,CAAC,UAAU;;;;;CAKrC,KAAKA,OAAAA,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,UAAU;;;;;CAKpC,oBAAoBA,OAAAA,EAAE,QAAQ,CAAC,UAAU;;;;;;;;CAQzC,0BAA0BA,OAAAA,EAAE,KAAK;EAAC;EAAU;EAAQ;EAAQ,CAAC,CAAC,UAAU;CACzE,CAAC;AAKF,IAAM,+BAAN,cAA2C,MAAM;CAC/C,YAAY,SAAiB;AAC3B,QAAM,QAAQ;AACd,OAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0HhB,SAAgB,iCACd,mBACA;AACA,QAAOC,mBAAAA,iBAAiB;EACtB,MAAM;EACN;EACA,gBAAgB,SAAS,YAAY;;;;GAInC,MAAM,gBACJ,QAAQ,QAAQ,QAAQ,iBACxB,mBAAmB,iBACnB;GACF,MAAM,MACJ,QAAQ,QAAQ,QAAQ,OAAO,mBAAmB,OAAO;GAC3D,MAAM,qBACJ,QAAQ,QAAQ,QAAQ,sBACxB,mBAAmB,sBACnB;GACF,MAAM,2BACJ,QAAQ,QAAQ,QAAQ,4BACxB,mBAAmB,4BACnB;AAGF,OAAI,CAAC,iBAAiB,CAAC,QAAQ,MAC7B,QAAO,QAAQ,QAAQ;AAQzB,OAAI,EAJF,QAAQ,MAAM,SAAS,KAAK,mBAC3B,QAAQ,MAAM,SAAS,KAAK,uBAC1B,QAAQ,MAA4B,gBAAgB,kBACnD,cACiB;IAErB,MAAM,YAAY,QAAQ,MAAM,SAAS;IASzC,MAAM,cAAc,sBAPlB,QAAQ,MAAM,SAAS,KAAK,sBACxB,GAAG,UAAU,IACV,QAAQ,MAA4B,gBACjC,cACL,KACD,UAE8C;AAEpD,QAAI,6BAA6B,QAC/B,OAAM,IAAI,6BACR,GAAG,YAAY,yCAChB;aACQ,6BAA6B,OACtC,SAAQ,KACN,iDAAiD,UAAU,kEAC5D;AAEH,WAAO,QAAQ,QAAQ;;AAMzB,OAFE,QAAQ,MAAM,SAAS,UAAU,QAAQ,eAAe,IAAI,KAE1C,mBAClB,QAAO,QAAQ,QAAQ;;;;;;;;AAUzB,UAAO,QAAQ;IACb,GAAG;IACH,eAAe;KACb,GAAG,QAAQ;KACX,eAAe;MACb,MAAM;MACN;MACD;KACF;IACF,CAAC;;EAEL,CAAC"}