zuplo 7.1.0 → 7.1.2

package/docs/ai-gateway/teams.mdx

@@ -1,18 +1,24 @@
 ---
 title: AI Gateway Teams
 sidebar_label: Overview
+description:
+  Teams manage access to AI Gateway apps, carry usage limits and policy
+  templates, and organize members with hierarchical sub-teams.
 ---
 
-Teams are used to manage access to AI Gateway applications, set usage limits,
-and monitor activity. Each team can have multiple members and sub-teams. Use
-teams to group users by department, project, or any other logical grouping.
+Teams are used to manage access to AI Gateway apps, set usage limits, and
+monitor activity. Each team can have multiple members and sub-teams. Use teams
+to group users by department, project, or any other logical grouping.
 
 ## Teams & Apps
 
-Apps in the AI Gateway represent any app or integration that will call the AI
-Gateway. Apps in the AI Gateway are owned by a specific team. Members of the
-team will have permissions to perform various actions on the App depending on
-their permissions.
+Every [app](./apps.mdx)—each service or integration that calls the AI
+Gateway—belongs to exactly one team. What a team member may do to an app depends
+on that member's role.
+
+Teams also carry a [policy template](./policy-templates.mdx)—the policy chain
+that apps created in the team start with—and [usage limits](./usage-limits.mdx)
+that apply to all of the team's apps combined.
 
 ## Members
 
@@ -21,9 +27,9 @@ depend on their role in the Zuplo account, project, and team.
 
 There are two roles at the team level:
 
-- **Member**: Can access AI Providers and Apps assigned to the team.
-- **Admin**: Can manage team settings, members, and access AI Providers and Apps
-  assigned to the team.
+- **Member**: Can access the AI providers and apps assigned to the team.
+- **Admin**: Can manage team settings and members, and access the AI providers
+  and apps assigned to the team.
 
 For more information on roles and permissions, see the
 [document on roles and permissions](../articles/accounts/roles-and-permissions.mdx).

package/docs/ai-gateway/universal-api.mdx

@@ -1,36 +1,46 @@
 ---
 title: AI Gateway Universal API
 sidebar_label: Universal API
+description:
+  Every AI Gateway app exposes an OpenAI-compatible API. Point your SDK's base
+  URL at the app's gateway URL and reference models as providerName/model.
 ---
 
 Zuplo AI Gateway provides a universal API that standardizes interactions with
 various AI providers. This API follows the
 [OpenAI API specification](https://platform.openai.com/docs/api-reference/introduction),
-making it easy to integrate with existing applications that already use OpenAI's
-API.
+making it easy to integrate with existing apps that already use OpenAI's API.
 
 ## Using the Universal API
 
-The Universal API is automatically enabled for all AI Gateway applications.
-Using this endpoint is as simple as changing your API base URL to point to
-Zuplo. For example, if your Zuplo application is hosted at
-`https://my-ai-gateway.zuplo.app`, you can simply change the base URL in your
-API client to `https://my-ai-gateway.zuplo.app/v1`.
+Every AI Gateway app serves the Universal API. The app page in the portal shows
+each app's **API URL**, which ends in the app's ID—for example
+`https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e`.
+Client libraries expect a base URL ending in `/v1`, so append that suffix. When
+the gateway runs the
+[authentication policy](./policy-chains.mdx#authentication), send the app's API
+key as a bearer token.
+
+Models are referenced as `providerName/model`, where `providerName` is the
+provider name configured in your gateway. This is how the gateway knows which
+provider to route each request to—and it means one app can use models from
+several providers through the same endpoint.
 
 If you are using an SDK or library that supports custom base URLs, you can
-configure it to use your Zuplo application's URL. For example, with the OpenAI
-Node.js SDK, you can set the `baseURL` option:
+configure it to use your app's URL. For example, with the OpenAI Node.js SDK,
+you can set the `baseURL` option:
 
 ```ts
 import OpenAI from "openai";
 
 const client = new OpenAI({
-  apiKey: process.env.ZUPLO_API_KEY,
-  baseURL: "https://my-ai-gateway.zuplo.app/v1",
+  apiKey: process.env.ZUPLO_APP_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
 });
 
 const response = await client.chat.completions.create({
-  model: "gpt-4",
+  model: "openai/gpt-5-mini",
   messages: [
     {
       role: "user",
@@ -41,3 +51,20 @@ const response = await client.chat.completions.create({
 
 console.log(response.choices[0].message.content);
 ```
+
+:::tip
+
+If the app's [Model Filtering](./policies/model-filtering.mdx) policy has an
+allow list, a request that omits `model` uses the first model in the list—so
+clients that can't set a model still work.
+
+:::
+
+## Supported endpoints
+
+| Endpoint               | Notes                                                  |
+| ---------------------- | ------------------------------------------------------ |
+| `/v1/chat/completions` | Chat completions for every provider                    |
+| `/v1/embeddings`       | Embeddings for every provider except Anthropic         |
+| `/v1/responses`        | OpenAI Responses API, for OpenAI-backed providers      |
+| `/v1/messages`         | Anthropic Messages API, for Anthropic-backed providers |

package/docs/ai-gateway/usage-limits.mdx

@@ -1,88 +1,118 @@
 ---
 title: "Usage Limits & Thresholds"
 sidebar_label: "Usage Limits"
+description:
+  Set hierarchical spending, token, and request limits at the gateway, team, and
+  app levels, with warning thresholds and quota fallbacks.
 ---
 
 The Zuplo AI Gateway provides hierarchical usage limits and budget controls to
-manage LLM spending across your organization. Limits can be set at the
-organization, team, and application levels.
+manage LLM spending across your organization. Limits can be set at the gateway,
+team, and app levels.
 
 ## Budget Hierarchy
 
-Budget limits cascade down through your organizational structure:
+Limits at every level apply together—a request is blocked when _any_ level's
+limit is exceeded, and the error names the level that blocked it:
 
-- **Root Team** - Organization-wide limits (for example, $1,000/day)
-- **Sub-Teams** - Team-specific limits that cannot exceed the parent team's
-  budget (for example, $500/day for the Engineering team)
-- **Applications** - Per-app limits for granular control (for example, $10/day
-  for a hackathon project)
+- **Gateway** - Organization-wide limits (for example, $1,000/day), covering all
+  teams and apps combined
+- **Teams** - Team-specific limits covering all of the team's apps combined (for
+  example, $500/day for the Engineering team)
+- **Apps** - Per-app limits for granular control (for example, $10/day for a
+  hackathon project)
 
-A sub-team's budget can never exceed the available budget from its parent team.
-Similarly, an application's budget cannot exceed its owning team's budget.
+## Where limits are configured
 
-## Configuring Limits
+| Level   | Where                                                                             |
+| ------- | --------------------------------------------------------------------------------- |
+| Gateway | **Settings → Usage Limits**                                                       |
+| Team    | The team's **Usage & Limits** tab                                                 |
+| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) |
 
-### Daily Budgets
+Each level supports the same three meters, each with independent daily and
+monthly settings:
 
-Set a maximum daily spend for a team or application. When the daily budget is
-reached, requests are either blocked or flagged with a warning depending on your
-enforcement configuration.
+- **Budget** - spend in dollars
+- **Tokens** - input plus output tokens
+- **Requests** - request count
 
-To configure daily budgets:
+For each meter and period you can set a **Limit** (usage at or above it gets
+blocked) and a **Warning** threshold (a percentage of the limit that triggers a
+warning notification without blocking). Leave a field empty to not enforce it.
 
-1. Open your AI Gateway project in the Zuplo Portal
-2. Select the [Teams](https://portal.zuplo.com/+/account/project/ai/teams) or
-   [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab
-3. Click on the team or app to edit
-4. Select the **Usage & Limits** tab and configure the **Daily Budget** field
-5. Click **Save Changes**
+:::note
 
-### Monthly Budgets
+Daily and monthly periods are anchored to your gateway, not the calendar: a
+daily period rolls over at the time of day (UTC) the gateway was created, and a
+monthly period runs anchor-day to anchor-day. Changing a limit mid-period
+doesn't reset the period's usage.
 
-Set a maximum monthly spend for applications. Monthly budgets reset on the first
-day of each calendar month.
+:::
 
-### Rate Limits
+## Setting an app's limits
 
-In addition to budget-based limits, you can configure request rate limits to
-control the volume of requests flowing through the gateway.
+<Stepper>
 
-## Enforcement Modes
+1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab and
+   select the app.
 
-When a limit is reached, the AI Gateway can operate in two modes:
+1. On the **Policies** tab, configure the **Budgets and Costs** policy (add it
+   from **Add Policy** if the chain doesn't have it).
 
-- **Enforce** - Requests are blocked and an error response is returned to the
-  caller
-- **Warn** - Requests are allowed through but a warning notification is
-  generated
+1. Set daily or monthly limits for budget, tokens, or requests, and optional
+   warning thresholds.
 
-## Monitoring Usage
+1. Save. The change applies within about a minute.
 
-Track current usage and spending through the AI Gateway dashboard:
+</Stepper>
 
-1. Open the
-   [**Analytics**](https://portal.zuplo.com/+/account/project/ai/analytics) tab
-   of your AI Gateway project
-2. Click on an app and select **Dashboard**
-3. View real-time metrics including:
-   - Request count
-   - Token usage (input and output)
-   - Current spending against budget
-   - Time to first byte
+:::note
 
-## Semantic Caching
+Each period in the Budgets and Costs policy's options carries an `enabled` flag
+next to its number, and so does each warning threshold. A period enforces
+nothing until `enabled` is `true` _and_ `limit` is set—options that set only
+`limit` are silently inert. Watch for this when editing the policy's options
+directly, such as in `config/policies.json` or a
+[policy template](./policy-templates.mdx).
 
-Enable semantic caching on applications to reduce costs by identifying and
-returning cached responses for similar prompts. This can significantly reduce
-token usage and spending, especially for applications with repeated or similar
-queries.
+:::
 
-To enable semantic caching:
+If the app has a **quota fallback** model configured, an exceeded limit routes
+requests to that model instead of blocking with a `429`—see
+[Fallback Models](./fallback.mdx). The fallback's usage still counts toward the
+limits.
 
-1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) tab and
-   click on the app to edit
-2. Enable the **Semantic Caching** toggle under **Advanced Features**
-3. Save your changes
+:::warning
+
+An app without the Budgets and Costs policy in its chain doesn't enforce
+app-level limits. Team and gateway limits still protect overall spend, but
+per-app budgets need Budgets and Costs in the chain—use a
+[policy template](./policy-templates.mdx) to make sure every app starts with it.
+
+:::
+
+:::caution{title="Budgets fail open by default"}
+
+The Budgets and Costs policy's `throwOnFailure` option defaults to `false`, so
+if the metering service is unavailable the request proceeds unmetered: no limit
+is checked and the request reaches the provider even if the app is already over
+budget. Set `throwOnFailure` to `true` to fail closed instead, so a metering
+outage rejects the request rather than letting it escape the budget.
+
+:::
+
+## Monitoring Usage
+
+Each app, team, and the gateway show current usage against their limits:
+
+1. Open the [Apps](https://portal.zuplo.com/+/account/project/ai/apps) or
+   [Teams](https://portal.zuplo.com/+/account/project/ai/teams) tab and select
+   an app or team
+2. The **Overview** tab shows daily and monthly usage—spend, tokens, and
+   requests—with progress against any configured limits
+3. For request-level metrics (request count, token usage, time to first byte),
+   open the app's **Dashboard**
 
 ## Related Resources
 
@@ -90,3 +120,5 @@ To enable semantic caching:
   project with budget controls
 - [Managing Teams](./managing-teams.mdx) - Configure team-level budgets
 - [Managing Apps](./managing-apps.mdx) - Configure app-level limits
+- [Fallback Models](./fallback.mdx) - Serve a cheaper model instead of blocking
+  when a limit is exceeded

package/docs/policies/cdn-cache-control-outbound/doc.md

@@ -173,8 +173,8 @@ policy to that route.** There is no configuration that lets a backend-set
 targeted header through: `edge` is required unless `cacheConfig` supplies it at
 runtime, and the vendor's headers are stripped on every path — including when a
 response is opted out with `cache: false`, which removes them and writes nothing
-in their place. `client.mode: "preserve"` preserves the _client_
-`Cache-Control` only; it has no bearing on the edge headers.
+in their place. `client.mode: "preserve"` preserves the _client_ `Cache-Control`
+only; it has no bearing on the edge headers.
 
 ## tags
 
@@ -226,13 +226,13 @@ The names you configure are **unioned** with any `Vary` the upstream already
 sent, deduplicated case-insensitively; `Vary: *` from either side absorbs the
 rest. Unlike the edge headers, `Vary` is still emitted when an upstream veto or
 `cache: false` suppresses edge caching — a `private, max-age=300` response is
-uncacheable at the edge but still cached by the browser, and it needs the variant
-key just as much. The policy never narrows an upstream `Vary`, because doing so silently is
-unsafe: if the origin sent `Vary: Authorization` and you configure
-`vary: ["accept-language"]`, replacing it would stop a shared cache keying on
-`Authorization` and let it serve one user's authorized response to another. To
-deliberately drop a wasteful upstream `Vary` — `Vary: User-Agent` shreds hit
-rates — remove it in a separate outbound policy before this one runs.
+uncacheable at the edge but still cached by the browser, and it needs the
+variant key just as much. The policy never narrows an upstream `Vary`, because
+doing so silently is unsafe: if the origin sent `Vary: Authorization` and you
+configure `vary: ["accept-language"]`, replacing it would stop a shared cache
+keying on `Authorization` and let it serve one user's authorized response to
+another. To deliberately drop a wasteful upstream `Vary` — `Vary: User-Agent`
+shreds hit rates — remove it in a separate outbound policy before this one runs.
 
 If your response genuinely varies by a request header, configure the cache key
 at the CDN — Cache ID Modification on Akamai, Cache Keys on Cloudflare — rather
@@ -283,10 +283,10 @@ message naming the cause, rather than letting the response go out truncated.
 
 The three return values:
 
-| Return             | Effect                                                                              |
-| ------------------ | ----------------------------------------------------------------------------------- |
-| `undefined`/`null` | Use the static options unchanged.                                                   |
-| a config object    | Use it in place of the static options.                                              |
+| Return             | Effect                                                                                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `undefined`/`null` | Use the static options unchanged.                                                                                                                        |
+| a config object    | Use it in place of the static options.                                                                                                                   |
 | `{ cache: false }` | Emit no edge headers or tags, **and** send `Cache-Control: no-store` to the client — except under `client.mode: "preserve"`, which is a trap; see below. |
 
 `{ cache: false }` is a positive statement that the response must not be cached

package/package.json

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

package/docs/ai-gateway/guardrails.mdx

@@ -1,65 +0,0 @@
----
-title: Zuplo AI Guardrails
-sidebar_label: Overview
----
-
-The Zuplo AI Gateway supports guardrails to protect your AI-powered applications
-from security threats, ensure compliance, and maintain quality in both requests
-and responses flowing through the gateway.
-
-## Available Guardrail Policies
-
-### Akamai AI Firewall
-
-The [Akamai AI Firewall](./policies/akamai-ai-firewall.mdx) provides
-enterprise-grade security for AI applications, including:
-
-- **Prompt injection defense** - Protects against attackers manipulating AI
-  models through deceptive inputs
-- **Data loss prevention (DLP)** - Detects and blocks sensitive data leaks in
-  AI-generated responses and incoming requests
-- **Toxic content filtering** - Flags hate speech, misinformation, and offensive
-  content
-- **Adversarial AI security** - Protects against remote code execution, model
-  back doors, and data poisoning attacks
-
-## Observability & Tracing
-
-Guardrails work alongside observability policies to provide visibility into AI
-interactions:
-
-- [Comet Opik Tracing](./policies/comet-opik-tracing.mdx) - Trace and monitor AI
-  interactions with Comet's Opik platform
-- [Galileo Tracing](./policies/galileo-tracing.mdx) - Monitor AI quality and
-  performance with Galileo
-
-## How Guardrails Work
-
-Guardrails are applied as policies on your AI Gateway routes. They inspect both
-inbound requests (prompts sent to LLM providers) and outbound responses (content
-returned from LLM providers) in real-time.
-
-When a guardrail detects a policy violation:
-
-1. The request or response is blocked before reaching its destination
-2. An appropriate error response is returned to the caller
-3. The violation is logged for audit and monitoring purposes
-
-## Getting Started
-
-To add guardrails to your AI Gateway:
-
-1. Open your [project](https://portal.zuplo.com/+/account/project/) associated
-   with your AI Gateway in the Zuplo Portal
-2. Open the **Code** tab and select your `routes.oas.json` file
-3. Select the route for your AI Gateway endpoint
-4. Click **Add Policy** and search for the guardrail you want to add
-5. Configure the policy settings and click **OK**
-6. Save your changes to deploy
-
-## Custom Guardrails
-
-You can build custom guardrails using Zuplo's programmable gateway. Create a
-custom inbound or outbound policy that inspects request/response content and
-applies your own rules. This allows you to implement organization-specific
-content policies, regulatory compliance checks, or domain-specific validation.