--- name: bijection-ai-budget description: "Evaluate and integrate the AI Budget component with Bijection." --- # AI Budget AI usage metering and budget reservations - Package: @bijectionhq/ai-budget - Category: AI & Agents - Status: Reference - License: Apache-2.0 - Bijection source (repository access required): https://github.com/bijectionhq/ai-budget/tree/62f834de10b336ee9e6f2906d61eb6486fb44c72 - Upstream: https://github.com/convex/ai-budget/tree/6fe03d099da773518d256b069dc098471c9821a0 - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/ai-budget ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/ai-budget.git cd ai-budget git checkout 62f834de10b336ee9e6f2906d61eb6486fb44c72 ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes @convex-dev/ai-budget. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses AI Budget. Follow the installation and configuration steps exactly. # AI Budget ## Instructions Use AI Budget to track, attribute, and cap llm costs per user, action, and custom tag in convex with atomic admission control and a built-in admin dashboard. This Convex component integrates directly with your backend. ### Installation ```bash npm install @convex-dev/ai-budget ``` Current npm version: `@convex-dev/ai-budget@0.0.2-alpha.0` ### Capabilities - Enforce per-user and per-feature spend caps atomically using a reserve-then-settle pattern that prevents concurrent requests from exhausting the same budget simultaneously. - Attribute every LLM request to a user and the calling Convex action automatically via ctx.meta, with support for custom dimensions like team, customer, or environment. - Integrate with the Convex AI Gateway without managing API keys using short-lived deployment tokens generated per request. - Drop a budgeted language model into convex-dev/agent or any AI SDK call with a single ai.languageModel(ctx) call, keeping all cost tracking and limits in place. ## Examples ### how to limit AI spending per user in Convex The @convex-dev/ai-budget component provides ai.users.setLimits() to configure daily spend, token, and requests-per-minute caps per user. Calls to ai.chat() or ai.languageModel() are automatically checked against these limits before the LLM request is made, throwing a ConvexError with kind 'AIBudgetLimit' when a hard cap is exceeded. Blocked attempts are still recorded so you can audit who is hitting limits. ### track LLM token usage and cost per user in Convex actions ai.chat() returns costNanos, promptTokens, completionTokens, and cachedTokens for every call, and @convex-dev/ai-budget writes a full request log with messages, response, latency, and per-request cost to durable storage. Spend is rolled up into daily and monthly history per user, action, and any custom tag dimensions you define, and these rollups survive request log retention expiry. ### how to add cost tracking to convex-dev/agent Pass ai.languageModel(ctx, { userId }) as the languageModel option when constructing an Agent from @convex-dev/agent. This wraps every generation in the budget component's reserve-then-settle cycle, so each agent generation is attributed to the user, checked against their caps, priced using the gateway's authoritative cost, and written to the audit log without any additional instrumentation. ### how to budget async AI jobs like video generation in Convex For long-running jobs that span multiple Convex functions, @convex-dev/ai-budget provides ai.begin() to reserve budget at job submission and ai.settle() to record actual cost when the job completes. Set reserveTtlMs to the job's maximum expected duration so the hold is not reaped mid-flight, and use ai.registerWebhook() to settle from a provider webhook. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by AI Budget is not needed ## Troubleshooting **Does @convex-dev/ai-budget require Node.js or 'use node' in Convex actions?** @convex-dev/ai-budget runs in Convex's default V8 runtime and does not require 'use node'. The component is pure V8 and ai.chat() and ai.languageModel() use fetch-based requests, so they work in standard Convex actions without switching to the Node.js runtime. **How does @convex-dev/ai-budget prevent concurrent requests from overspending a budget?** @convex-dev/ai-budget uses a reserve-then-settle design where each request atomically reserves an estimated cost against every capped bucket it touches before the LLM call is made. This means two concurrent requests cannot both read the same remaining budget and both proceed past a cap. Final cost may differ from the estimate and is recorded at settlement, but the admission check is always atomic against live reserved amounts. **What is a nanodollar and why does @convex-dev/ai-budget use them?** A nanodollar is one billionth of a US dollar, so $1.00 equals 1,000,000,000 nanodollars. @convex-dev/ai-budget uses integer nanodollars for all costs, limits, and prices to avoid the floating-point rounding drift that accumulates with fractional cent arithmetic, and to keep cap comparisons exact. The integer representation supports values up to approximately $9 million per field. **Can @convex-dev/ai-budget track costs for providers or APIs not available through the Convex AI Gateway?** Yes. ai.meter() allows you to bring any external LLM or API call under the same caps, audit log, and cost tracking that ai.chat() uses. You provide a run callback that executes your provider call and returns token counts or an explicit costNanos value, and @convex-dev/ai-budget handles the reserve-then-settle cycle, cap enforcement, and request logging around it. **What Convex plan is required to use @convex-dev/ai-budget?** @convex-dev/ai-budget requires convex@^1.45 and a Convex team on a paid plan because it routes LLM calls through the Convex AI Gateway, which is a paid feature. The component itself installs via npm as @convex-dev/ai-budget and also requires @convex-dev/ai-sdk-provider and the ai package. ## Resources - [npm package](https://www.npmjs.com/package/%40convex-dev%2Fai-budget) - [GitHub repository](https://github.com/get-convex/ai-budget) - [Live demo](https://github.com/get-convex/ai-budget/tree/main/example) - [Convex Components Directory](https://www.convex.dev/components/ai-budget) - [Convex documentation](https://docs.convex.dev)