zuplo 7.2.3 → 7.2.4

package/docs/policies/ai-gateway-fallback-model-v2-inbound/doc.md

@@ -1,4 +1,4 @@
-# AI Gateway Fallback Model (v2) Policy
+# AI Gateway Fallback Model
 
 Use this policy to add resilience to a model selection created by Model
 Filtering or a custom routing policy. Place it after Model Filtering:
@@ -10,6 +10,10 @@ Model Filtering -> Fallback Model -> AI Gateway handler
 Fallback Model never creates a primary selection. If it runs without a prior
 selection, it logs a warning and leaves the request unchanged.
 
+> **Policy order matters.** Put Fallback Model immediately after Model
+> Filtering. Because filtering accepts the primary selection first, a fallback
+> cannot widen the models an application may select.
+
 ## Options
 
 `models` must contain `completions`, `embeddings`, or both. Each configured
@@ -22,7 +26,11 @@ capability must set at least one of:
   fallback.
 
 `fallbackTimeoutSeconds` applies to every configured `fallback`. It defaults to
-60 seconds and accepts values from 1 through 300.
+60 seconds and accepts values from 1 through 300. The timeout covers connection
+setup and the wait for response headers. It does not limit how long a streaming
+response body may continue after its headers arrive.
+
+A fallback that names the same model as the primary selection is skipped.
 
 ## Cross-provider fallback example
 

package/docs/policies/ai-gateway-fallback-model-v2-inbound/intro.md

@@ -1,4 +1,4 @@
-AI Gateway Fallback Model (v2) adds retry, timeout, and quota fallbacks to an
-existing model selection. Place it after AI Gateway Model Filtering (v2). It
+AI Gateway Fallback Model adds retry, timeout, and quota fallbacks to an
+existing model selection. Place it after AI Gateway Model Filtering. It
 preserves the primary selection and never creates one when the policy chain is
 misordered.

package/docs/policies/ai-gateway-fallback-model-v2-inbound/schema.json

@@ -2,16 +2,17 @@
   "$schema": "https://json-schema.org/draft-07/schema",
   "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-fallback-model-v2-inbound.json",
   "type": "object",
-  "title": "AI Gateway Fallback Model (v2)",
+  "title": "AI Gateway Fallback Model",
   "isDeprecated": false,
   "isPaidAddOn": false,
   "isEnterprise": false,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
+  "policyType": "ai-gateway-fallback-model-v2",
   "products": ["ai-gateway"],
-  "description": "Adds failure and quota fallbacks to an existing AI Gateway model selection.\n\nPlace this policy after AI Gateway Model Filtering (v2). It never creates a model selection, so a misplaced policy cannot bypass filtering.",
+  "description": "Adds failure and quota fallbacks to an existing AI Gateway model selection.\n\nPlace this policy after AI Gateway Model Filtering. It never creates a model selection, so a misplaced policy cannot bypass filtering.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -35,6 +36,17 @@
           "description": "Options for adding failure and quota fallbacks to an existing AI Gateway model selection.",
           "additionalProperties": false,
           "required": ["models"],
+          "examples": [
+            {
+              "models": {
+                "completions": {
+                  "fallback": "anthropic/claude-haiku-4-5",
+                  "quotaFallback": "openai/gpt-4o-mini"
+                }
+              },
+              "fallbackTimeoutSeconds": 60
+            }
+          ],
           "properties": {
             "models": {
               "type": "object",
@@ -88,7 +100,7 @@
             "fallbackTimeoutSeconds": {
               "type": "number",
               "title": "Fallback Timeout Seconds",
-              "description": "How long a primary model may take before the failure fallback is attempted.",
+              "description": "How long to wait for primary-model response headers before attempting the failure fallback. The timeout does not bound a streaming response body after its headers arrive.",
               "minimum": 1,
               "maximum": 300,
               "default": 60
@@ -101,11 +113,13 @@
           "export": "AIGatewayFallbackModelV2InboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "fallbackTimeoutSeconds": 60,
             "models": {
-              "completions": {},
-              "embeddings": {}
-            }
+              "completions": {
+                "fallback": "anthropic/claude-haiku-4-5",
+                "quotaFallback": "openai/gpt-4o-mini"
+              }
+            },
+            "fallbackTimeoutSeconds": 60
           }
         }
       ]

package/docs/policies/ai-gateway-metering-v2-inbound/doc.md

@@ -1,8 +1,17 @@
-# AI Gateway Metering (v2)
+# AI Gateway Metering
 
-`ai-gateway-metering-v2-inbound` records AI Gateway usage and enforces daily or
-monthly limits before the provider request runs. Declare the policy in
-`policies.json`, then add it to an application's `inboundPolicyChain`.
+AI Gateway Metering records application usage and enforces budgets before the
+provider request runs. It meters spend, tokens, and requests. Each meter has
+independent daily and monthly periods and an optional warning threshold that
+notifies without blocking.
+
+When a limit is exceeded, the policy activates the model selection's
+`quotaFallback` when AI Gateway Fallback Model supplied one. Otherwise it
+returns `429 Too Many Requests`.
+
+Place Metering after Model Filtering and Fallback Model so an exceeded budget
+can activate the quota fallback. Put policies that may answer early, such as
+Semantic Cache, after Metering so cache hits still count toward request limits.
 
 ## Example
 
@@ -37,8 +46,9 @@ The supported meters are `costs`, `tokens`, and `requests`. Each meter can have
 `daily` and `monthly` settings. A period is enforced only when `enabled` is
 `true` and `limit` is present. Usage equal to the limit is blocked.
 
-When `throwOnFailure` is `false`, metering failures pass the request through.
-Set it to `true` to fail the request instead.
+> **Budgets fail open by default.** When `throwOnFailure` is `false`, a metering
+> service failure lets the request proceed unmetered and no limit is checked.
+> Set it to `true` to reject the request instead.
 
 ## Team limits
 
@@ -47,19 +57,12 @@ through a server-side hierarchical check against aggregated usage. The
 `options.limits` settings govern only the app running this policy; the server
 walks the ancestor chain and reports the first exceeded limit.
 
-An exceeded team or root limit follows the same configured model-fallback or 429
-response path as an app limit. Ancestor enforcement cannot be disabled from the
-app's policy-chain entry. When the hierarchical check is unavailable,
+An exceeded team or gateway limit follows the same configured model-fallback or
+429 response path as an app limit. Ancestor enforcement cannot be disabled from
+the app's policy-chain entry. When the hierarchical check is unavailable,
 `throwOnFailure` controls the behavior: the default skips enforcement for that
 request while continuing to meter it, and `true` fails the request.
 
-### Known residual
-
-Grandfathered v2 apps that already store `metadata.limits` are still evaluated
-at the leaf by the server's hierarchy walk. The companion Gateway Service change
-rejects introducing or modifying app metadata limits; cleaning up stale rows is
-tracked separately.
-
 ## Set limits from custom code
 
 Use a custom inbound policy to vary limits for individual requests. For example,

package/docs/policies/ai-gateway-metering-v2-inbound/intro.md

@@ -0,0 +1,9 @@
+The AI Gateway Metering policy records each application's spend, tokens, and
+requests and enforces daily or monthly budgets. When a limit is exceeded, it
+uses the model selection's quota fallback when one is configured or returns
+`429 Too Many Requests`.
+
+Place it after Model Filtering and Fallback Model, and before policies such as
+Semantic Cache that may answer without calling a provider. Metering fails open
+by default when its service is unavailable; set `throwOnFailure` to `true` to
+reject requests instead.

package/docs/policies/ai-gateway-metering-v2-inbound/schema.json

@@ -2,16 +2,17 @@
   "$schema": "https://json-schema.org/draft-07/schema",
   "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-metering-v2-inbound.json",
   "type": "object",
-  "title": "AI Gateway Metering (v2)",
+  "title": "AI Gateway Metering",
   "isDeprecated": false,
   "isPaidAddOn": false,
   "isEnterprise": false,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
+  "policyType": "ai-gateway-metering-v2",
   "products": ["ai-gateway"],
-  "description": "Meters AI Gateway v2 usage and enforces app and ancestor usage limits.\n\nLimits configured on parent teams or the bucket root are enforced through a server-side hierarchical check.\n\nThe authentication policy must run before this policy so the app configuration id is available for meter storage and analytics.",
+  "description": "Meters AI Gateway usage and enforces app and ancestor usage limits.\n\nLimits configured on parent teams or the bucket root are enforced through a server-side hierarchical check.\n\nThe authentication policy must run before this policy so the app configuration id is available for meter storage and analytics.",
   "deprecatedMessage": "",
   "required": ["handler"],
   "properties": {
@@ -32,9 +33,22 @@
           "x-zuplo-policy-type": "ai-gateway-metering-v2",
           "title": "AIGatewayMeteringV2InboundPolicyOptions",
           "type": "object",
-          "description": "Options for metering AI Gateway v2 usage and enforcing request-time limits.",
+          "description": "Options for metering AI Gateway usage and enforcing request-time limits.",
           "additionalProperties": false,
           "required": [],
+          "examples": [
+            {
+              "limits": {
+                "requests": {
+                  "daily": {
+                    "enabled": true,
+                    "limit": 1000
+                  }
+                }
+              },
+              "throwOnFailure": false
+            }
+          ],
           "properties": {
             "throwOnFailure": {
               "type": "boolean",
@@ -258,28 +272,10 @@
           "module": "$import(@zuplo/runtime)",
           "options": {
             "limits": {
-              "costs": {
-                "daily": {
-                  "warning": {}
-                },
-                "monthly": {
-                  "warning": {}
-                }
-              },
               "requests": {
                 "daily": {
-                  "warning": {}
-                },
-                "monthly": {
-                  "warning": {}
-                }
-              },
-              "tokens": {
-                "daily": {
-                  "warning": {}
-                },
-                "monthly": {
-                  "warning": {}
+                  "enabled": true,
+                  "limit": 1000
                 }
               }
             },

package/docs/policies/ai-gateway-model-filtering-v2-inbound/doc.md

@@ -1,7 +1,8 @@
-# AI Gateway Model Filtering (v2) Policy
+# AI Gateway Model Filtering
 
 Use this policy when an AI Gateway route must restrict which models clients may
-select. The policy is optional.
+select. Without it, an application can use any available model from the
+providers configured for the Zuplo project. The policy is optional.
 
 Choose the setup that matches the route:
 
@@ -170,9 +171,9 @@ For example, this embedding request is evaluated against `models.embeddings`:
 
 ## Adding fallbacks
 
-Declare AI Gateway Fallback Model (v2) separately and place it immediately after
-this policy. Its `fallback` handles retryable errors and timeouts;
-`quotaFallback` handles usage-limit signals independently.
+Declare AI Gateway Fallback Model separately and place it immediately after this
+policy. Its `fallback` handles retryable errors and timeouts; `quotaFallback`
+handles usage-limit signals independently.
 
 ## Write your own routing policy
 

package/docs/policies/ai-gateway-model-filtering-v2-inbound/intro.md

@@ -1,5 +1,5 @@
-AI Gateway Model Filtering (v2) controls which `providerName/model` references
+AI Gateway Model Filtering controls which `providerName/model` references
 clients may select. Use an `allowList` for a curated catalog with a default, or
 a `blockList` for an open catalog with explicit exclusions. Put this policy
-before AI Gateway Fallback Model (v2), which adds fallback behavior only after a
+before AI Gateway Fallback Model, which adds fallback behavior only after a
 primary model has passed filtering.

package/docs/policies/ai-gateway-model-filtering-v2-inbound/schema.json

@@ -2,14 +2,15 @@
   "$schema": "https://json-schema.org/draft-07/schema",
   "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-model-filtering-v2-inbound.json",
   "type": "object",
-  "title": "AI Gateway Model Filtering (v2)",
+  "title": "AI Gateway Model Filtering",
   "isDeprecated": false,
   "isPaidAddOn": false,
   "isEnterprise": false,
   "isInternal": false,
-  "isBeta": true,
+  "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
+  "policyType": "ai-gateway-model-filtering-v2",
   "products": ["ai-gateway"],
   "description": "Matches AI Gateway requests against curated allow lists or open block lists, then stores the winning model reference for the route handler.",
   "deprecatedMessage": "",
@@ -35,6 +36,15 @@
           "description": "Options for allowing or blocking providerName/model references for each AI Gateway capability.",
           "additionalProperties": false,
           "required": ["models"],
+          "examples": [
+            {
+              "models": {
+                "completions": {
+                  "allowList": ["openai/gpt-4o-mini"]
+                }
+              }
+            }
+          ],
           "properties": {
             "models": {
               "type": "object",
@@ -139,7 +149,11 @@
           "export": "AIGatewayModelFilteringV2InboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
-            "models": {}
+            "models": {
+              "completions": {
+                "allowList": ["openai/gpt-4o-mini"]
+              }
+            }
           }
         }
       ]

package/docs/policies/ai-gateway-semantic-cache-v2-inbound/doc.md

@@ -0,0 +1,72 @@
+# AI Gateway Semantic Cache
+
+AI Gateway Semantic Cache answers a request from a previous response when the
+new prompt is semantically similar to one already seen. A hit skips the provider
+call. One inbound policy handles both directions: it checks the cache on the way
+in and, on a miss, stores a successful provider response on the way out.
+
+A cache hit returns immediately, so later inbound policies do not run. Place
+Semantic Cache after Metering so hits still count toward application request
+limits. Put guardrails before the cache when they must inspect every request.
+
+## How matching works
+
+The cache builds an embedding from the system context and the most recent
+conversation messages. It then requires the endpoint format, model, system
+context, and non-conversation request parameters to match exactly before
+accepting a semantic match. This prevents a similar prompt from crossing model,
+parameter, or system-prompt boundaries.
+
+`semanticTolerance` controls how loose the semantic match may be. A response is
+reused when similarity is at least `1 - semanticTolerance`; the default `0.2`
+therefore requires a similarity of at least `0.8`.
+
+All three text-based AI Gateway shapes are supported: Chat Completions,
+Responses, and Anthropic Messages. Streaming responses are accumulated for
+storage and can be replayed as streams on a later hit.
+
+## Options
+
+| Option                  | Default                             | What it does                                                                                                        |
+| ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `semanticTolerance`     | `0.2`                               | Controls the minimum semantic similarity. Smaller values require a closer match.                                    |
+| `expirationSecondsTtl`  | `3600`                              | Keeps a cached response for this many seconds, up to 30 days.                                                       |
+| `recentMessageCount`    | `1`                                 | Uses this many recent conversation messages in the semantic key. System and developer messages are always included. |
+| `maxConversationLength` | Unset                               | Skips conversations longer than this many messages.                                                                 |
+| `endpoints`             | All three shapes                    | Limits caching to selected endpoint shapes.                                                                         |
+| `namespace`             | Resolved configuration ID, or unset | Partitions entries when no application configuration ID is available.                                               |
+
+Increasing `recentMessageCount` makes the cache consider more conversational
+context. Setting `maxConversationLength` can reduce topic-drift risk when only a
+small recent window is used.
+
+## What isn't cached
+
+- Requests whose selected message window has no user message.
+- Selected messages containing images, files, audio, tool calls, tool results,
+  or other content that cannot be represented safely as text.
+- Conversations longer than `maxConversationLength`, when that option is set.
+- Provider responses whose status is not `200`.
+- Empty, filtered, malformed, or otherwise unreadable responses.
+
+Earlier multimodal messages outside the selected recent window do not prevent a
+text-only recent prompt from being cached.
+
+The cache always fails open. If a lookup, match, or store operation fails, the
+request continues to the provider rather than being rejected.
+
+## Application isolation
+
+When a request resolves to an application, its configuration ID fixes the
+namespace and isolates its cached responses from other applications. The
+`namespace` option only applies when the gateway has no application
+configuration ID. Set it explicitly when unidentified traffic must be isolated
+from other requests that also lack a configuration ID.
+
+## Read cache outcomes
+
+Responses report the outcome in the RFC 9211 `Cache-Status` header under the
+cache name `zp-aigw-sem-cache`. Responses also include these headers:
+
+- `x-ai-gateway-cache`: `HIT` or `MISS`.
+- `x-ai-gateway-cache-similarity`: the similarity score for a hit.

package/docs/policies/ai-gateway-semantic-cache-v2-inbound/intro.md

@@ -0,0 +1,9 @@
+The AI Gateway Semantic Cache returns a previous response when a new prompt is
+semantically similar, avoiding another provider call. One inbound policy checks
+the cache and stores successful responses on a miss; no outbound policy is
+required.
+
+Place it after Metering so cache hits still count toward application request
+limits. Resolved applications are isolated by configuration ID; set `namespace`
+to partition traffic that has no configuration ID. Failures always pass the
+request through to the provider.

package/docs/policies/ai-gateway-semantic-cache-v2-inbound/schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-semantic-cache-v2-inbound.json",
+  "type": "object",
+  "title": "AI Gateway Semantic Cache",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": true,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": true,
+  "policyType": "ai-gateway-semantic-cache-v2",
+  "products": ["ai-gateway"],
+  "description": "AI Gateway Semantic Cache policy. This inbound policy looks up the semantic cache on entry and, on a miss, registers a response-sending hook to write the upstream response back into the cache.\n\nCaching parameters (semanticTolerance, expirationSecondsTtl, namespace, recentMessageCount) come from the policy options, and presence in the route's chain is what enables it. An id from the authenticated app configuration always provides the cache namespace so application-supplied options cannot cross tenant partitions. The cache key covers the system prompt plus the last `recentMessageCount` messages (default 1) — applied when storing and when matching — so multi-turn conversations can hit entries cached from earlier, shorter ones.\n\nCache outcomes are reported on the response via the RFC 9211 `Cache-Status` header under the cache name `zp-aigw-sem-cache` (hit: `zp-aigw-sem-cache; hit; detail=\"similarity=0.93\"`; miss: `zp-aigw-sem-cache; fwd=miss; stored`). Responses also include the `x-ai-gateway-cache: HIT|MISS` and `x-ai-gateway-cache-similarity` headers.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AIGatewaySemanticCacheV2InboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "x-zuplo-policy-type": "ai-gateway-semantic-cache-v2",
+          "type": "object",
+          "title": "AIGatewaySemanticCacheInboundPolicyOptions",
+          "description": "Options for the AI Gateway Semantic Cache policy. Configured inline in policies.json; the policy reads nothing from the AI Gateway configuration to decide whether to cache.",
+          "additionalProperties": false,
+          "required": [],
+          "examples": [
+            {
+              "semanticTolerance": 0.2,
+              "expirationSecondsTtl": 3600,
+              "recentMessageCount": 1
+            }
+          ],
+          "properties": {
+            "semanticTolerance": {
+              "type": "number",
+              "title": "Semantic Tolerance",
+              "description": "The semantic similarity threshold for semantic cache matches. Values closer to 0 require closer similarity, while larger values allow more flexible matching. Default is 0.2.",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.2
+            },
+            "expirationSecondsTtl": {
+              "type": "integer",
+              "title": "Cache TTL (seconds)",
+              "description": "How long a cached response lives, in whole seconds. Defaults to 3600 (1 hour); maximum 2592000 (30 days).",
+              "minimum": 1,
+              "maximum": 2592000,
+              "default": 3600
+            },
+            "namespace": {
+              "type": "string",
+              "title": "Cache Namespace",
+              "description": "Partitions the cache when the authenticated application has no configuration id. Applications with a configuration id always use it, so cache entries stay isolated per application."
+            },
+            "recentMessageCount": {
+              "type": "integer",
+              "title": "Recent Message Count",
+              "description": "How many of the conversation's most recent messages (input items on the Responses endpoint) form the cache key, both when storing a response and when matching later requests. Earlier messages are ignored, so a multi-turn conversation can hit an entry cached from a shorter one; system messages are always included. Requests whose keyed window contains no user message (for example a conversation ending in an assistant prefill) are not cached. Defaults to 1 (match on the newest message only).",
+              "minimum": 1,
+              "default": 1
+            },
+            "maxConversationLength": {
+              "type": "number",
+              "title": "Max Conversation Length",
+              "x-advanced": true,
+              "description": "Skip caching entirely when the conversation has more than this many messages. Unset by default (no limit). Set a bound to guard against topic drift: the cache key covers only the last recentMessageCount messages, so the deeper a conversation goes, the more likely a match on recent messages alone ignores earlier context that should change the answer.",
+              "minimum": 1
+            },
+            "endpoints": {
+              "type": "array",
+              "title": "Applicable Endpoints",
+              "x-advanced": true,
+              "description": "The endpoint shapes to cache. Defaults to all shapes: \\['openai-chat', 'anthropic-messages', 'openai-responses'\\].",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "openai-chat",
+                  "openai-responses",
+                  "anthropic-messages"
+                ]
+              }
+            },
+            "onUnknownShape": {
+              "type": "string",
+              "title": "On Unknown Shape",
+              "x-advanced": true,
+              "description": "Unused by the cache (a cache miss is never unsafe, so it always fails open). Present for interface consistency.",
+              "enum": ["deny", "skip"],
+              "default": "skip"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AIGatewaySemanticCacheV2InboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "semanticTolerance": 0.2,
+            "expirationSecondsTtl": 3600,
+            "recentMessageCount": 1
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/akamai-ai-firewall-v2-inbound/doc.md

@@ -0,0 +1,87 @@
+# Akamai AI Firewall
+
+The Akamai AI Firewall policy sends prompts and completions to
+[Akamai Firewall for AI](https://www.akamai.com/products/firewall-for-ai) and
+blocks content that your Akamai configuration denies. One inbound policy covers
+both directions: it scans the request before the provider call and the response
+afterward, including streaming responses.
+
+Detection rules and their categories live in Akamai Control Center. The policy
+enforces rules configured to deny; rules configured only to alert do not block
+the request.
+
+## Configure the policy
+
+Create or select an Akamai Firewall for AI configuration and API key. Declare
+the policy once in `config/policies.json`, then add the declaration to each
+application policy chain that should be protected. To protect new applications
+by default, include it in the team's policy template.
+
+```json
+{
+  "name": "akamai-ai-firewall-v2-inbound",
+  "policyType": "akamai-ai-firewall-v2",
+  "handler": {
+    "export": "AkamaiAIFirewallV2InboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "configurationId": "your-configuration-id",
+      "api-key": "$env(AKAMAI_AI_FIREWALL_API_KEY)"
+    }
+  }
+}
+```
+
+When an application chain entry should inherit these credentials, omit the
+entry's `options`. Entry options replace the declaration's complete options
+object; they do not merge with it.
+
+## Options
+
+| Option                                  | Default    | What it does                                                    |
+| --------------------------------------- | ---------- | --------------------------------------------------------------- |
+| `configurationId`                       | Required   | Selects the Akamai firewall configuration.                      |
+| `api-key`                               | Required   | Authenticates to Akamai. The property name includes the hyphen. |
+| `applicationId`                         | Unset      | Supplies an optional Akamai application identifier.             |
+| `endpoints`                             | All shapes | Limits inspection to selected AI Gateway endpoint shapes.       |
+| `onUnknownShape`                        | `deny`     | Denies or skips a request whose shape cannot be inspected.      |
+| `onError`                               | `block`    | Blocks or allows traffic when the Akamai detection call fails.  |
+| `streamingAccumulation.enabled`         | `true`     | Enables response inspection for streaming requests.             |
+| `streamingAccumulation.eventsInterval`  | `5`        | Buffers this many stream events between checks.                 |
+| `streamingAccumulation.checkIntervalMs` | Unset      | Also runs checks on a timer when configured.                    |
+
+Unknown option keys and incomplete credentials are rejected. Invalid options
+fail closed so a broken chain never silently disables the guardrail.
+
+## Streaming behavior
+
+For streaming responses, the gateway withholds each batch of events until the
+Akamai check passes. This prevents denied content from reaching the client, but
+the buffering and network check add latency. If a later batch is denied, the
+stream ends with a content-filter stop rather than changing the HTTP status of a
+response that has already started.
+
+## Block and failure behavior
+
+A denied request or non-streaming response returns `400` in the request shape's
+native error format and includes the Akamai rule ID. Anthropic Messages uses an
+Anthropic-style error; Chat Completions and Responses use an OpenAI-style error.
+Provider error responses are not scanned.
+
+| Situation                                                               | Result                                             |
+| ----------------------------------------------------------------------- | -------------------------------------------------- |
+| Options are invalid or incomplete                                       | Request rejected before unguarded traffic can run. |
+| The endpoint shape cannot be inspected                                  | `400`, with code `guardrail_uninspectable`.        |
+| A recognized request body cannot be parsed                              | Request continues without input inspection.        |
+| A successful response body cannot be parsed                             | Response passes through without output inspection. |
+| Akamai rejects the credentials, rate-limits the call, or is unavailable | `502`, with code `guardrail_unavailable`.          |
+| The endpoint is excluded by `endpoints`                                 | Request passes through without inspection.         |
+
+Setting `onError` to `allow` changes service failures to fail open. An expired
+credential can then leave the gateway returning successful responses without
+inspection, so monitor firewall findings and sudden drops in block volume.
+
+## Additional resources
+
+- [Akamai Firewall for AI](https://www.akamai.com/products/firewall-for-ai)
+- [Akamai AI security solutions](https://www.akamai.com/solutions/security/ai-security)

package/docs/policies/akamai-ai-firewall-v2-inbound/intro.md

@@ -0,0 +1,10 @@
+The Akamai AI Firewall policy scans AI Gateway prompts and completions with
+Akamai Firewall for AI. One inbound policy protects both request and response
+content, including streaming responses, and blocks content that an Akamai rule
+denies.
+
+For runtime inspection, the policy denies unknown endpoint shapes and handled
+Akamai detection-call failures by default. If a recognized request or successful
+response has an unparseable JSON body, the policy skips scanning that body and
+passes it through. Detection rules and categories are configured in Akamai
+Control Center.