@convex-dev/ai-budget 0.0.2-alpha.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,421 @@
+# ☂️ @convex-dev/ai-budget
+
+**Add this component and get worry-free AI.** A metered, budget-governed layer
+over the [Convex AI Gateway](https://docs.convex.dev/ai-gateway/overview). Point
+your LLM calls through it and every request is tracked, priced, attributed, and
+held to a budget — with spend caps that actually hold under concurrent load.
+
+```ts
+// userId defaults to the signed-in user — this is the whole integration:
+const { text, costNanos } = await ai.chat(ctx, { prompt });
+```
+
+That one call is authenticated to the gateway with a short-lived deployment
+token (no API keys to manage), attributed to the authenticated user, checked
+against their limits, billed to the right user and feature, and written to a
+full audit log you can replay later.
+
+![Chat with a live request log — every call tracked, priced, and attributed](docs/hero.png)
+
+---
+
+## What you get
+
+| | |
+|---|---|
+| **Usage & cost tracking** | Every request stored with messages, response, tokens, latency, and per-request cost. |
+| **Attribution** | Each call is attributed to a `userId` **and** to the Convex action that made it — auto-detected via `ctx.meta`, no manual tagging. Running totals per user and per action. |
+| **Spend & token limits** | Per-user daily / lifetime **spend** and **token** budgets, plus a requests-per-minute rate limit and a block switch. |
+| **Concurrency-safe caps** | A reserve-then-settle design makes admission a true atomic check — concurrent in-flight requests can't blow past the cap (a naive implementation overshoots ~40×). |
+| **Hard or soft** | Each limit either **blocks** (`hard`) or **allows-with-a-warning** (`soft`). |
+| **Per-feature budgets** | Cap or disable a whole action (e.g. `summarize`) independently of any user. |
+| **Global killswitch** | A deployment-wide spend cap across all users and actions (sharded for throughput; enforced approximately). |
+| **One-time bumps** | "Approve another $X" at any level (user / action / global) without changing the standing cap — daily bumps are today-only, lifetime bumps permanent. |
+| **Model policy** | Allow/deny lists for models; an unknown/unpriced model **fails closed** (charged a conservative max, never $0). |
+| **Replay** | Re-run any stored request with edited messages or a different model; re-runs are linked to their original (lineage). |
+| **Agent-ready** | `ai.languageModel(ctx, { userId })` is a standard AI SDK model — drop it into [`@convex-dev/agent`](https://www.npmjs.com/package/@convex-dev/agent) and every agent generation is budgeted. |
+
+---
+
+## Install
+
+Requires `convex@^1.45`, AI SDK 5+, and a Convex team on a paid plan (the
+gateway is a paid feature). Runs in Convex's **default runtime** — no
+`"use node"` required (the component is pure V8 mutations/queries/crons, and
+`ai.chat` / `ai.languageModel` are `fetch`-based).
+
+```sh
+npm install @convex-dev/ai-budget @convex-dev/ai-sdk-provider ai
+```
+
+Register the component:
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import aiBudget from "@convex-dev/ai-budget/convex.config";
+
+const app = defineApp();
+app.use(aiBudget);
+export default app;
+```
+
+Create a client:
+
+```ts
+// convex/ai.ts
+import { AIBudget } from "@convex-dev/ai-budget";
+import { components } from "./_generated/api";
+
+export const ai = new AIBudget(components.aiBudget, {
+  defaultModel: "openai/gpt-4o-mini",
+  // Optional: surface soft-limit warnings even on the Agent/languageModel path.
+  onSoftLimit: ({ userId, warnings }) => console.warn(userId, warnings),
+});
+```
+
+The admin API is namespaced: `ai.users.*`, `ai.actions.*`, `ai.global.*`,
+`ai.models.*`, `ai.prices.*`, and `ai.requests.*`; `ai.chat` and
+`ai.languageModel` are top-level.
+
+---
+
+## Quickstart
+
+```ts
+// convex/ai.ts
+import { v } from "convex/values";
+import { action } from "./_generated/server";
+
+export const sendMessage = action({
+  args: { prompt: v.string() },
+  handler: async (ctx, { prompt }) => {
+    // userId defaults to the authenticated caller (ctx.auth). Limit-checked,
+    // tracked, priced. Throws a ConvexError if over a hard cap.
+    const { text, costNanos, warnings } = await ai.chat(ctx, { prompt });
+    return { text, costNanos, warnings };
+  },
+});
+```
+
+Pass an explicit `{ userId }` only for service/admin flows or when you manage
+identity yourself.
+
+Give someone a budget:
+
+```ts
+await ai.users.setLimits(ctx, {
+  userId: "alice",
+  dailySpendLimitNanos: 1_000_000_000, // $1.00 / day (1e9 nano)
+  dailyTokenLimit: 500_000,
+  requestsPerMinute: 20,
+});
+```
+
+When a request would exceed a **hard** cap, `chat` throws a `ConvexError`
+carrying `{ kind: "AIBudgetLimit", code, reason }`; the attempt is still
+recorded (`status: "blocked"`) so you can see who's hitting limits.
+
+---
+
+## API reference
+
+All methods are called from a Convex **action** (they run the gateway call) or,
+for the read-only ones, a query. `ctx` is the Convex context.
+
+**Money is integer nanodollars** (`1 USD = 1e9 nano`) everywhere — costs, limits,
+and prices. Integers avoid the rounding drift floating-point cents accumulate and
+keep cap comparisons exact (exact to ~$9M per value). `$1 = 1_000_000_000`.
+
+### Generating
+
+```ts
+ai.chat(ctx, {
+  userId?,           // defaults to the authenticated caller (ctx.auth)
+  prompt?,           // or:
+  messages?,         // [{ role, content }]
+  model?,            // defaults to defaultModel
+  action?,           // attribution name; defaults to the calling Convex action
+}): Promise<{ text, requestId, costNanos, promptTokens, completionTokens, warnings }>
+```
+
+`warnings` is non-empty only when a **soft** limit was exceeded. If no `userId`
+is passed and there is no authenticated user, `chat` throws — budgets are never
+silently un-attributed.
+
+### As an AI SDK model (Agent, generateText, streamText)
+
+```ts
+ai.languageModel(ctx, { userId, model?, action? }): LanguageModel
+```
+
+Returns a standard AI SDK `LanguageModel` that enforces the user's budget and
+records usage/cost on every call — including streaming. Use it anywhere an AI
+SDK model is expected:
+
+```ts
+import { Agent } from "@convex-dev/agent";
+
+// Construct per-request so the agent is bound to this user.
+const agent = new Agent(components.agent, {
+  name: "assistant",
+  languageModel: ai.languageModel(ctx, { userId }),
+});
+const { threadId } = await agent.createThread(ctx, { userId });
+const result = await agent.generateText(ctx, { threadId }, { prompt });
+```
+
+Every generation the agent makes is now tracked and budgeted, attributed to
+`userId` and to the calling action. See `example/convex/agentDemo.ts`.
+
+### Replay
+
+```ts
+ai.requests.rerun(ctx, { requestId, messages?, model? }): Promise<ChatResult>
+ai.requests.lineage(ctx, { requestId }): Promise<{ ancestors, reruns }>
+```
+
+`rerun` re-runs a stored request (optionally with edited messages/model), linked
+to the original. `lineage` walks the re-run chain in both directions.
+
+### User limits
+
+```ts
+ai.users.setLimits(ctx, {
+  userId,
+  requestsPerMinute?,
+  dailySpendLimitNanos?,
+  lifetimeSpendLimitNanos?,
+  dailyTokenLimit?,
+  lifetimeTokenLimit?,
+  enforcement?,       // "hard" (block, default) | "soft" (warn but allow)
+  blocked?,           // hard block on/off
+})
+ai.users.delete(ctx, { userId })   // remove a user and all their request rows
+```
+
+Pass a field as `undefined` to clear that limit (unlimited).
+
+### Per-action budgets
+
+Spend is attributed to the calling action automatically. Cap a feature:
+
+```ts
+ai.actions.setLimits(ctx, {
+  name,                          // e.g. "ai:summarize"
+  dailySpendLimitNanos?,
+  lifetimeSpendLimitNanos?,
+  dailyTokenLimit?,
+  lifetimeTokenLimit?,
+  enforcement?,                  // "hard" | "soft"
+  disabled?,                     // kill switch for the whole feature
+})
+```
+
+### Global (deployment-wide) budget
+
+```ts
+ai.global.setLimits(ctx, { dailySpendLimitNanos?, lifetimeSpendLimitNanos?, enforcement? })
+ai.global.status(ctx)   // { limits, spentTodayNanos, spentTotalNanos }
+```
+
+A killswitch across all users and actions. Backed by a sharded counter for
+throughput, so it's enforced **approximately** (bounded overshoot under burst) —
+per-user and per-action caps remain exact.
+
+### One-time bumps ("approve another $X")
+
+```ts
+ai.users.bump(ctx, { userId, dailyNanos?, lifetimeNanos? })
+ai.actions.bump(ctx, { name, dailyNanos?, lifetimeNanos? })
+ai.global.bump(ctx, { dailyNanos?, lifetimeNanos? })
+```
+
+Adds headroom on top of the standing cap without changing it. Daily bumps apply
+to today only (reset with the day); lifetime bumps are permanent.
+
+### Model policy
+
+```ts
+ai.models.setPolicy(ctx, { mode, models })
+// mode: "open" (default) | "allowlist" (only these) | "denylist" (all but these)
+ai.models.getPolicy(ctx)
+```
+
+### Pricing
+
+Prices are in **nanodollars per million tokens**. Sensible defaults ship for
+common models (validated against OpenRouter's public pricing); override or add
+any model:
+
+```ts
+ai.prices.set(ctx, { model, inputNanosPerMTok, outputNanosPerMTok })  // must be ≥ 0
+ai.prices.list(ctx)
+```
+
+**Real prices from an API.** The gateway's `provider/model` ids match
+OpenRouter's, whose public models endpoint returns per-token pricing — so you can
+keep prices current from your own action (this is app code; the component just
+stores what you give it):
+
+```ts
+const { data } = await (await fetch("https://openrouter.ai/api/v1/models")).json();
+const p = data.find((m) => m.id === "openai/gpt-4o-mini").pricing;
+await ai.prices.set(ctx, {
+  model: "openai/gpt-4o-mini",
+  inputNanosPerMTok: Math.round(Number(p.prompt) * 1e15),   // $/token → nano/Mtok
+  outputNanosPerMTok: Math.round(Number(p.completion) * 1e15),
+});
+```
+
+See `example/convex/ai.ts` → `syncPrices` for a full sync over several models.
+
+An unpriced model is charged the conservative maximum of the known table (so a
+cap can never be bypassed by naming an unlisted model) and its request rows are
+flagged `unpricedModel: true` so you know to add a real price.
+
+### Observability
+
+```ts
+ai.users.list(ctx)                      // per-user spend today / total / tokens / limits
+ai.actions.list(ctx)                    // per-action spend & totals
+ai.requests.list(ctx, { userId?, limit? })  // the audit log (blocked attempts included)
+```
+
+---
+
+## How spend caps stay correct
+
+A naive tracker checks the running total, makes the call, then records the cost.
+Under concurrency that leaks badly: dozens of in-flight requests all read the
+same pre-spend total and all pass, so spend blows past the cap (measured at
+~40× before this design).
+
+`ai-budget` instead **reserves then settles**:
+
+1. **Reserve.** `startRequest` estimates the request's cost/tokens and, *in the
+   same transaction as the limit check*, reserves them against the capped
+   entity. Under Convex's serializable isolation this makes admission a true
+   atomic check-and-reserve — concurrent requests see each other's holds.
+2. **Settle.** `finishRequest` writes only the request's own (uncontended) row
+   and schedules a fold of the real cost into the totals, releasing the
+   reservation. A request is therefore never orphaned mid-flight.
+3. **Reconcile.** A once-a-minute cron folds any stragglers and releases
+   reservations for requests that died before settling. Settlement is
+   **exactly-once** (a terminal request is never re-folded), so a slow request
+   that the reconciler already swept can't double-count when it finally returns.
+
+Reservations are only taken on entities that actually have a cap, so uncapped
+traffic never serializes. The `error.md` file documents the adversarial audits
+this design survived, with live repros.
+
+**One guarantee, all scopes.** Per-user, per-action, and global caps run through
+the *same* admission check — a request is admitted only when
+`committed + reserved + estimate ≤ cap` (bumps included). The only thing that
+differs is the holder: per-user and per-action reserve on a single document, an
+exact atomic check-and-reserve; the **global** killswitch is backed by a sharded
+counter for throughput, so its committed total is read as an eventually-consistent
+sum with no cross-request reservation. That makes the global cap **approximate** —
+it can overshoot by a bounded amount under a burst — the deliberate
+exactness-for-throughput trade for a deployment-wide cap, and the only scope
+that isn't exact.
+
+---
+
+## Security: before you ship
+
+The component is deliberately **identity-agnostic** — like
+`@convex-dev/rate-limiter`, it trusts the `userId` and admin calls your app
+hands it. **Your app owns auth.** The `example/` app skips auth on purpose to
+keep the demo frictionless (a persona dropdown, public admin functions); do not
+copy its endpoints verbatim. In production:
+
+1. **Let `userId` default to the authenticated caller** (that's the built-in
+   behavior — `ai.chat(ctx, { prompt })` uses `ctx.auth.getUserIdentity()`).
+   Only pass an explicit `userId` from a trusted server context; never forward a
+   client-supplied id, or a caller can spend under someone else's budget or
+   dodge their own limits by rotating ids.
+2. **Gate every admin call** — `setLimits`, `setActionLimits`, `setModelPolicy`,
+   `setPrice`, `deleteUser` — behind an admin check. A limit-management surface
+   must not be operable by the party being limited.
+3. **Scope reads and replay to the owner.** `listRequests` / `getRequest` /
+   `lineage` return full prompts, responses, and spend, and `rerun` re-runs a
+   request billed to its **original** user. An unchecked client `requestId` is an
+   IDOR — verify `request.userId === caller`, or treat `rerun` and the
+   cross-user views as admin-only.
+
+---
+
+## Example app
+
+`example/` is a full working demo: chat as different personas on the left; a live
+admin panel on the right with the request audit log (inspect → edit → re-run,
+with lineage), a users table (rate / spend / token limits, soft toggle, block,
+one-time bump), and per-action budgets.
+
+Per-user limits — rate, daily spend, daily tokens, hard/soft, block, one-time bump:
+
+![Users & Limits admin table](docs/users.png)
+
+Per-action budgets, auto-attributed to the calling Convex function (including
+agent generations via `agentChat`):
+
+![Actions & Budgets admin table](docs/actions.png)
+
+```sh
+cd example
+npm install
+npx convex dev      # terminal 1 — provisions a dev deployment
+npm run dev         # terminal 2 — Vite app
+```
+
+### What's in the component vs. the demo
+
+The component (`src/`) is **only** the metering/budget primitive — it knows
+nothing about chat or evaluation. Everything below lives in `example/` as
+**application code that uses the component**, not as part of the published API:
+
+- The real features being metered — `sendMessage`, `summarize`, the agent (`agentDemo.ts`).
+- An **eval playground** — a 🧪 Experiment tab with three modes:
+  - **Matrix** — run one prompt across a system-prompt × model grid; an LLM judge
+    ranks them by *your* criteria.
+  - **Backtest** — replay a candidate system prompt against a specific action's
+    real historical requests and judge whether it improved each one.
+  - **Evolve** — an LLM iteratively improves a prompt toward a goal, scored on
+    real traffic, **stopping when it hits a spend budget.**
+- The public endpoints and UI wiring that drive the admin panel.
+
+These are built entirely on two component primitives: `ai.chat(...)` (every eval
+call is budgeted and tracked) and `ai.requests.list(...)` (the audit log *is* the
+eval dataset). They're a **"how to build on it" reference, not the component's
+surface** — a real, non-trivial feature (budget-capped prompt backtesting on live
+traffic) that falls out of the primitives without the component needing to know
+eval exists. If you productize this, it belongs in your app or its own component
+that *composes* `@convex-dev/ai-budget` — never folded back into it.
+
+---
+
+## Development
+
+```sh
+npm test            # vitest + convex-test: reserve/settle, exactly-once,
+                    # token quotas, soft limits, model policy, pricing
+npm run build       # emit dist/ (client + component) for publishing
+```
+
+## Layout
+
+- `src/component/` — **the component** (published): tables (`users`, `actions`,
+  `requests`, `prices`, `settings`), the reserve/settle mutations (`startRequest` /
+  `finishRequest`), the idempotent `foldTotals`, the `reconcile` cron, and the
+  admin functions. Mounts `@convex-dev/sharded-counter` for the global total.
+- `src/client/` — **the client** (published): the `AIBudget` class — `chat`,
+  `languageModel` (AI SDK middleware around `convexGateway`), and the namespaced
+  admin API (`ai.users.*`, `ai.actions.*`, `ai.global.*`, `ai.models.*`,
+  `ai.prices.*`, `ai.requests.*`).
+- `example/` — **the demo app** (not published): real features, the eval
+  playground, and the UI, all built on the two files above.
+
+## License
+
+Apache-2.0