zuplo 6.73.30 → 6.73.31

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -76,17 +76,24 @@ const { text } = await generateText({
 
 ### Google
 
+The `@ai-sdk/google` provider speaks Gemini's native protocol: it sends requests
+to `/models/{model}:generateContent` and authenticates with the `x-goog-api-key`
+header, neither of which the AI Gateway serves. Use the
+[OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
+instead — the AI Gateway translates OpenAI-format requests to Google upstream.
+
 ```typescript
-import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { generateText } from "ai";
 
-const google = createGoogleGenerativeAI({
+const gateway = createOpenAICompatible({
+  name: "zuplo-ai-gateway",
   apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
   baseURL: "https://my-ai-gateway.zuplo.app/v1",
 });
 
 const { text } = await generateText({
-  model: google("gemini-2.5-flash"),
+  model: gateway("gemini-2.5-flash"),
   prompt: "Write a one-sentence bedtime story about a unicorn.",
 });
 ```

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

@@ -1,9 +1,73 @@
 # AI Gateway Model Filtering (v2) Policy
 
-Use this policy to control which models clients may select on AI Gateway routes.
-Model references use `providerName/model`; the first slash separates the
-Provider Name configured in the Zuplo Portal from the provider-specific model
-ID.
+Use this policy when an AI Gateway route must restrict which models clients may
+select. The policy is optional.
+
+Choose the setup that matches the route:
+
+- Omit Model Filtering to let each request select any available model. Every
+  request must provide `model` as `providerName/model`.
+- Use an `allowList` to expose a curated set of models and provide a default
+  model.
+- Use a `blockList` to permit available models except for specific exclusions.
+- Use a custom routing policy when model selection depends on request data or
+  application logic that an allow list or block list cannot express.
+
+`providerName` is the Provider Name configured in the Zuplo Portal. The text
+after the first slash is the provider-specific model ID, so model IDs may
+contain additional slashes.
+
+## Routing without Model Filtering
+
+When neither Model Filtering nor a custom routing policy selects a model, the AI
+Gateway handler reads the request body's `model` and uses it as the primary
+routing target:
+
+```json
+{
+  "model": "openai/gpt-4o-mini",
+  "messages": [{ "role": "user", "content": "Hello" }]
+}
+```
+
+The handler validates that:
+
+- `model` is a string in `providerName/model` form;
+- the Provider Name is configured;
+- the model is available for the route's capability;
+- the Provider Assignment has usable credentials.
+
+Missing, bare, non-string, or malformed model values receive an
+OpenAI-compatible 400 `invalid_request_error`. A validly formatted target that
+cannot be fulfilled is reported as a routing configuration error with a
+suggested fix.
+
+When Semantic Cache is attached, a cache hit also validates request-derived
+routing before returning the cached response. A removed, deprecated, or
+otherwise unavailable target therefore follows the same routing configuration
+error path instead of bypassing validation with a cached response. Native route
+requirements are checked too, so an Anthropic Messages cache hit cannot be
+served by an OpenAI-backed Provider Name.
+
+Attach Model Filtering only when the gateway must enforce model-selection rules.
+An attached policy must always have a valid, non-empty `models` configuration.
+
+### Responses management operations
+
+These Responses API operations do not have a request body:
+
+- `GET /v1/responses/:responseId`
+- `GET /v1/responses/:responseId/input_items`
+- `DELETE /v1/responses/:responseId`
+
+Because they cannot supply `model`, they require routing to be selected before
+the handler runs. Configure a `completions.allowList` in Model Filtering so its
+first entry supplies the default, or use a custom inbound policy that calls
+`AIGatewayModelRouting.set(context, { completions: "providerName/model" })`.
+Without preselected routing, the handler returns an OpenAI-compatible 400
+`invalid_request_error` with this configuration guidance.
+
+## Policy order
 
 Place Model Filtering before Fallback Model in the inbound policy chain:
 
@@ -13,7 +77,8 @@ Model Filtering -> Fallback Model -> AI Gateway handler
 
 Model Filtering accepts or rejects the request and creates the primary model
 selection. Fallback Model can then enrich that allowed selection without
-bypassing the filter.
+bypassing the filter. Fallback Model does not create a primary selection by
+itself.
 
 ## Options
 
@@ -25,9 +90,17 @@ chooses exactly one mode:
 - `blockList` leaves the catalog open except for named models. Every request
   must include `model`.
 
-Every list entry is a plain `providerName/model` string. Matching is
-case-insensitive, while configured casing is preserved for the upstream request.
-Route-target objects and fallback fields belong in the Fallback Model policy.
+Each configured list must contain at least one entry. A capability cannot define
+both `allowList` and `blockList`, and unsupported fields are rejected. Every
+list entry is a plain `providerName/model` string. Matching is case-insensitive,
+while configured casing is preserved for the upstream request. Route-target
+objects and fallback fields belong in the Fallback Model policy.
+
+Configure every capability served by a route using this policy. A route using
+`/v1/embeddings` needs `embeddings`; Chat Completions, Responses, and Anthropic
+Messages routes need `completions`. If the policy is attached but the active
+capability has no rules, the request receives a 403 response explaining which
+capability to add.
 
 ## Allow-list example
 
@@ -70,14 +143,30 @@ reported as warnings because they cannot match a request.
 
 ## Request behavior
 
-`/v1/embeddings` uses `embeddings`; Chat Completions, Responses, and Anthropic
-Messages use `completions`. Native routes also enforce their provider type:
-`/v1/responses` requires an OpenAI-backed Provider Name and `/v1/messages`
-requires an Anthropic-backed Provider Name.
+| Situation                                           | Result                                                 |
+| --------------------------------------------------- | ------------------------------------------------------ |
+| Allow list, request omits `model`                   | The first allow-list entry is selected.                |
+| Allow list, request names a listed model            | The matching configured entry is selected.             |
+| Allow list, request names an unlisted model         | 403 response listing the allowed models.               |
+| Block list, request omits `model`                   | 400 response asking for `providerName/model`.          |
+| Block list, request names a blocked model           | 403 response.                                          |
+| Either mode, request uses a bare or malformed model | 400 response explaining the required format.           |
+| Policy has no rules for the route capability        | 403 response explaining which capability to configure. |
+| Another inbound policy already selected routing     | Model Filtering leaves that selection unchanged.       |
 
-A bare model name receives a 400 response. An unlisted allow-list model or a
-blocked model receives a 403 response. If another policy has already selected a
-model, Model Filtering leaves that selection unchanged.
+Native routes also enforce provider type. `/v1/responses` requires a Provider
+Name backed by OpenAI, and `/v1/messages` requires a Provider Name backed by
+Anthropic. Provider Names may be custom labels; validation uses the provider
+type configured for that Provider Assignment.
+
+For example, this embedding request is evaluated against `models.embeddings`:
+
+```json
+{
+  "model": "openai/text-embedding-3-small",
+  "input": "Search text"
+}
+```
 
 ## Adding fallbacks
 
@@ -143,6 +232,18 @@ Attach the module as an ordinary inbound policy instead of Model Filtering:
 
 `AIGatewayModelRouting.get(context)` returns the sanitized, normalized routing
 for the current request and never returns credentials. The AI Gateway handler
-consumes a custom selection even when Model Filtering is not attached. Prefer
-one policy that creates the primary selection: Model Filtering preserves an
-existing selection, while a later custom policy can replace it.
+consumes a custom selection even when Model Filtering is not attached. If
+neither kind of policy creates a selection, the handler derives one from the
+request's required `providerName/model`.
+
+Policy order determines precedence:
+
+1. Routing selected before Model Filtering remains authoritative because Model
+   Filtering leaves an existing selection unchanged.
+2. Model Filtering creates routing when no earlier policy selected it.
+3. A custom policy placed after Model Filtering may deliberately replace that
+   selection.
+4. If no policy selects routing, the handler derives it from the request.
+
+Prefer one policy as the primary selector so the route's intent is easy to
+understand.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.73.30",
+  "version": "6.73.31",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.73.30",
-    "@zuplo/core": "6.73.30",
-    "@zuplo/runtime": "6.73.30",
+    "@zuplo/cli": "6.73.31",
+    "@zuplo/core": "6.73.31",
+    "@zuplo/runtime": "6.73.31",
     "@zuplo/test": "1.4.4"
   }
 }