zuplo 7.12.1 → 7.12.3

package/docs/ai-gateway/budget-alerts.mdx

@@ -0,0 +1,118 @@
+---
+title: "AI Gateway Budget Alerts"
+sidebar_label: "Budget Alerts"
+description:
+  Get notified in the portal and by email when an AI Gateway pool, app, or
+  person crosses a budget rule's warning or block amount, and mute alerts you
+  don't need.
+---
+
+Budget alerts tell you when usage crosses an amount set in a budget rule, so you
+don't have to watch the analytics to find out. There's nothing to set up. Each
+**Warn** or **Block** row in a [budget rule](./usage-limits.mdx) sets an amount;
+crossing that amount sends an alert to the people who can see the pool or app.
+
+## What you're notified about
+
+A budget rule caps cost, tokens, or requests over a UTC period and can have a
+**Warn** row, a **Block** row, or both for the same meter and period. See
+[Usage Limits](./usage-limits.mdx) for how to write one.
+
+Each budget is reported once per row per period: the first time its usage
+crosses the amount, and again after the period resets. A **By metadata** rule
+gives every value its own budget, so each value is reported separately. Usage is
+checked about once a minute, and an alert usually arrives within a minute or two
+of the crossing. Alerts for several values of one rule are held for up to five
+minutes so they arrive together.
+
+| Alert             | When it's sent                           | What it means                                                                                                                                                                                                                                         |
+| ----------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Warning**       | Usage first crosses the **Warn** amount  | Requests continue. Use the time left in the period to raise the limit or slow the caller down.                                                                                                                                                        |
+| **Limit reached** | Usage first crosses the **Block** amount | Requests are rejected with `429 Too Many Requests`, or served by the app's [quota fallback](./fallback.mdx), until the period resets. The alert includes the reset time. See [When a limit is exceeded](./usage-limits.mdx#when-a-limit-is-exceeded). |
+
+If one request pushes usage past both amounts, you get only a **Limit reached**
+alert.
+
+What the alert names depends on the rule's scope:
+
+- A **Shared** rule names the gateway, pool, or app whose budget it is.
+- A **By metadata** rule names the metadata value that crossed, such as one
+  `x-user` value. When several values of the same rule cross an amount within
+  five minutes, they arrive as one alert listing the values.
+- The [User App](./user-apps.mdx)'s per-person budget names the person.
+
+## Who is notified
+
+Alerts go to the people who can already see the usage in the Zuplo Portal:
+
+- **A pool or an app**: everyone with view access to it. A pool member receives
+  alerts for that pool and the apps in it; someone with access to the whole
+  project receives alerts for every pool.
+- **The User App**: only the Admins who can edit it, the people who set its
+  budget. Everyone else on the project can see only their own usage, so they
+  aren't told about the app's total or about other people.
+- **A personal budget**: the person it belongs to, and the User App's Admins.
+
+## Where alerts arrive
+
+Each alert is delivered two ways, and both are on by default:
+
+- **In-app feed**: the notification bell in the Zuplo Portal header. The feed
+  links to the app, pool, or gateway page that shows the usage.
+- **Email**: a message to the address on your Zuplo profile.
+
+## Turn alerts off
+
+Turning alerts off changes only what you receive. Everyone else keeps their own
+settings.
+
+### Turn off all budget alerts
+
+To stop receiving budget alerts for every gateway, open your
+[Profile](https://portal.zuplo.com/user/profile) in the Zuplo Portal and find
+the **Notifications** section. On the **AI Gateway Budget Alerts** row, clear
+**In-app Feed**, **Email**, or both.
+
+### Mute a gateway, pool, or app
+
+To keep alerts for most of a gateway and silence the parts you don't need, mute
+them from the analytics:
+
+<Stepper>
+
+1. Open your AI Gateway project in the Zuplo Portal and go to
+   [**Observability → Analytics**](https://portal.zuplo.com/+/account/project/ai/analytics),
+   then select **Pools & Apps**.
+
+1. Select the alert bell on a pool card or an app row. It's the mute control for
+   that pool or app.
+
+1. Switch off **Warnings**, **Limit reached**, or both.
+
+</Stepper>
+
+Muting a pool mutes every pool and app inside it, including ones created later.
+Under a muted pool, each pool and app shows locked switches and names the muted
+pool. To receive alerts for any of them again, turn that pool's alerts back on.
+
+The gateway card at the top of the **Pools & Apps** page covers the whole
+gateway. Muting it mutes every pool, every app, the User App, and every person's
+personal budget, your own included.
+
+:::note{title="Alerts don't change enforcement"}
+
+Muting an alert, or turning the category off on your profile, changes who is
+told, not what happens. A **Block** row still rejects requests at its amount, or
+sends them to the app's [quota fallback](./fallback.mdx), and a **Warn** row
+still lets them through.
+
+:::
+
+## Related resources
+
+- [Usage Limits](./usage-limits.mdx) - Set the amounts that trigger these
+  alerts.
+- [User Apps](./user-apps.mdx) - Set the per-person budget behind personal
+  budget alerts.
+- [Fallback Models](./fallback.mdx) - Serve a cheaper model instead of a `429`
+  when a **Block** amount is reached.

package/docs/ai-gateway/cookbooks/dynamic-model-routing.mdx

@@ -16,8 +16,9 @@ active completions model.
 Two public primitives from `@zuplo/runtime` do the work:
 
 - `AIGatewayModels.load(context)` returns the cached provider catalog, including
-  each model's capability, status, and per-token pricing. Credentials are never
-  returned.
+  each model's capability, status, and token rate card (`tokenRateCard`): the
+  prices the gateway charges, which are the list prices with your project's
+  prices applied. Credentials are never returned.
 - `AIGatewayModelRouting.set(context, routing)` validates the routing, resolves
   provider credentials internally, and stores the selection the AI Gateway
   handler uses. `AIGatewayModelRouting.get(context)` reads the current
@@ -27,6 +28,7 @@ Two public primitives from `@zuplo/runtime` do the work:
 
 ```ts title="modules/cheapest-model.ts"
 import {
+  AIGatewayModelInfo,
   AIGatewayModelRouting,
   AIGatewayModels,
   ZuploContext,
@@ -37,6 +39,25 @@ interface CheapestModelOptions {
   providers?: string[];
 }
 
+// The model's base input plus output price per token: the rates with no
+// input-size tier or cache lifetime. Undefined when the model has no rate card
+// or lacks either base rate.
+function basePrice(model: AIGatewayModelInfo): number | undefined {
+  const baseRate = (category: "input" | "output") =>
+    model.tokenRateCard?.rates.find(
+      (rate) =>
+        rate.category === category &&
+        rate.minInputTokens === undefined &&
+        rate.maxInputTokens === undefined &&
+        rate.cacheTtl === undefined,
+    )?.costPerToken;
+  const input = baseRate("input");
+  const output = baseRate("output");
+  return input === undefined || output === undefined
+    ? undefined
+    : input + output;
+}
+
 export default async function cheapestModel(
   request: ZuploRequest,
   context: ZuploContext,
@@ -49,18 +70,17 @@ export default async function cheapestModel(
       provider.models.map((model) => ({
         providerName: provider.providerName,
         model,
+        price: basePrice(model),
       })),
     )
     .filter(
-      ({ model }) =>
-        model.capability === "completions" && model.status === "active",
+      (candidate): candidate is typeof candidate & { price: number } =>
+        candidate.model.capability === "completions" &&
+        candidate.model.status === "active" &&
+        // Skip unpriced models instead of treating them as free.
+        candidate.price !== undefined,
     )
-    .sort(
-      (left, right) =>
-        left.model.inputCostPerToken +
-        left.model.outputCostPerToken -
-        (right.model.inputCostPerToken + right.model.outputCostPerToken),
-    );
+    .sort((left, right) => left.price - right.price);
 
   const cheapest = candidates[0];
   if (!cheapest) {

package/docs/ai-gateway/managing-apps.mdx

@@ -90,7 +90,9 @@ the app's **Policies** tab and add budget rules capping spending, tokens, or
 requests over an hourly, daily, weekly, or monthly period—either for the app as
 a whole or per metadata value, so each caller gets its own budget. Pool and
 gateway limits apply to every app automatically, even when the app's chain
-doesn't include Budgets and Costs. See [Usage Limits](./usage-limits.mdx).
+doesn't include Budgets and Costs. See [Usage Limits](./usage-limits.mdx). The
+people who can view the app are notified when it crosses a **Warn** or **Block**
+amount; see [Budget Alerts](./budget-alerts.mdx).
 
 ## Editing an App
 

package/docs/ai-gateway/managing-pools.mdx

@@ -42,7 +42,8 @@ After creating a pool, use its tabs to configure it:
 - **Policy Template**—the pool's [policy template](./policy-templates.mdx), the
   starting policy chain for apps created in the pool.
 - **Usage & Limits**—shared budgets for the pool, its sub-pools, and their apps.
-  See [Usage Limits](./usage-limits.mdx).
+  See [Usage Limits](./usage-limits.mdx). Crossing a limit notifies everyone who
+  can view the pool; see [Budget Alerts](./budget-alerts.mdx).
 - **Members**—who belongs to the pool.
 
 ## Adding Pool Members

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

@@ -112,6 +112,10 @@ Add as many rows as you need to cap several meters and periods at once. A Warn
 row and a Block row on the same meter and period give you warn-then-block—warn
 at $80, block at $100. The warn amount has to be the lower of the two.
 
+When usage first crosses a **Warn** or **Block** amount in a period, the people
+who can see the pool or app are notified in the Zuplo Portal and by email. See
+[Budget Alerts](./budget-alerts.mdx).
+
 The **Overview** tab charts daily and monthly usage only. Hourly and weekly rows
 are enforced, but no meter on that tab tracks them.
 
@@ -374,3 +378,5 @@ Each app, pool, and the gateway show current usage against their limits:
 - [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
+- [Budget Alerts](./budget-alerts.mdx) - Who is notified when a **Warn** or
+  **Block** amount is crossed, and how to mute alerts

package/docs/ai-gateway/user-apps.mdx

@@ -151,6 +151,8 @@ The **My Keys** tab also shows your allowance and what you've spent against it.
 If no budget is set, it says your requests have no personal spending limit. Once
 you reach your allowance, the gateway refuses requests with
 `429 Too Many Requests` until the period resets or an Admin raises your budget.
+You're notified in the Zuplo Portal and by email when you reach your allowance;
+see [Budget Alerts](./budget-alerts.mdx).
 
 ## Removing access
 

package/docs/policies/ai-gateway-configuration-executor-inbound/doc.md

@@ -451,6 +451,7 @@ mutate them.
 
 ```ts
 import {
+  AIGatewayModelInfo,
   AIGatewayModelRouting,
   AIGatewayModels,
   ZuploContext,
@@ -461,6 +462,16 @@ interface CheapestModelOptions {
   providers?: string[];
 }
 
+// The model's base input plus output price per token: the rates with no
+// input-size tier. A model without a rate card sorts last.
+function basePrice(model: AIGatewayModelInfo): number {
+  const baseRate = (category: "input" | "output") =>
+    model.tokenRateCard?.rates.find(
+      (rate) => rate.category === category && rate.minInputTokens === undefined
+    )?.costPerToken ?? Number.POSITIVE_INFINITY;
+  return baseRate("input") + baseRate("output");
+}
+
 export default async function cheapestModel(
   request: ZuploRequest,
   context: ZuploContext,
@@ -484,12 +495,7 @@ export default async function cheapestModel(
       ({ model }) =>
         model.capability === "completions" && model.status === "active"
     )
-    .sort(
-      (left, right) =>
-        left.model.inputCostPerToken +
-        left.model.outputCostPerToken -
-        (right.model.inputCostPerToken + right.model.outputCostPerToken)
-    );
+    .sort((left, right) => basePrice(left.model) - basePrice(right.model));
 
   const cheapest = candidates[0];
   if (!cheapest) {

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

@@ -82,7 +82,7 @@ Fallback Model also uses the public routing primitives, so custom code can
 choose fallbacks dynamically:
 
 - `AIGatewayModels.load(context)` returns the cached provider catalog, including
-  each model's capability, status, and per-token pricing.
+  each model's capability, status, and per-token prices (`tokenRateCard`).
 - `AIGatewayModelRouting.get(context)` returns the sanitized, normalized routing
   selected earlier in the chain. It never returns provider credentials.
 - `AIGatewayModelRouting.set(context, routing)` validates every target, resolves

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

@@ -187,7 +187,7 @@ inbound policy can replace it entirely. The policy's job is to choose one
 allowed target and store it:
 
 - `AIGatewayModels.load(context)` returns the cached provider catalog, including
-  each model's capability, status, and per-token pricing.
+  each model's capability, status, and per-token prices (`tokenRateCard`).
 - `AIGatewayModelRouting.set(context, routing)` validates the routing, resolves
   provider credentials internally, and stores the selection that the AI Gateway
   handler consumes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.12.1",
+  "version": "7.12.3",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.12.1",
-    "@zuplo/core": "7.12.1",
-    "@zuplo/runtime": "7.12.1",
-    "@zuplo/test": "7.12.1"
+    "@zuplo/cli": "7.12.3",
+    "@zuplo/core": "7.12.3",
+    "@zuplo/runtime": "7.12.3",
+    "@zuplo/test": "7.12.3"
   }
 }