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

package/src/component/schema.ts

@@ -6,67 +6,107 @@ export const vMessage = v.object({
   content: v.string(),
 });
 
+// One attribution tag: a (dimension, value) pair, e.g. {dimension:"user",
+// value:"alice"} or {dimension:"customer", value:"acme"}. `user` and `action`
+// are built-in dimensions; apps can add any others (team, project, env, …).
+export const vTag = v.object({ dimension: v.string(), value: v.string() });
+
 export default defineSchema({
-  users: defineTable({
-    userId: v.string(), // app-provided stable key (your user id)
+  // A budget holder, keyed by (dimension, value). Unifies what used to be the
+  // `users` and `actions` tables — those are just the "user" and "action"
+  // dimensions now. Any tag a request carries can have its own budget here.
+  buckets: defineTable({
+    dimension: v.string(),
+    value: v.string(),
     // limits (all optional — unlimited by default)
-    requestsPerMinute: v.optional(v.number()),
+    requestsPerMinute: v.optional(v.number()), // rolling limit for this bucket
+    maxConcurrent: v.optional(v.number()), // max in-flight (pending) requests
     dailySpendLimitNanos: v.optional(v.number()),
+    monthlySpendLimitNanos: v.optional(v.number()),
     lifetimeSpendLimitNanos: v.optional(v.number()),
     dailyTokenLimit: v.optional(v.number()),
+    monthlyTokenLimit: v.optional(v.number()),
     lifetimeTokenLimit: v.optional(v.number()),
-    blocked: v.optional(v.boolean()),
+    blocked: v.optional(v.boolean()), // hard block (was `blocked`/`disabled`)
+    // Fire an approaching-limit alert once usage crosses this fraction of a cap
+    // (e.g. 0.8 = warn at 80%). Falls back to the deployment default.
+    warnAtPct: v.optional(v.number()),
     // "hard" (default): exceeding a budget blocks. "soft": warn but allow.
     enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
-    // one-time bumps ("approve another $X") added on top of the cap. Daily bump
-    // is scoped to bumpDayStamp (resets with the day); lifetime bump is permanent.
+    // one-time bumps ("approve another $X"). Daily/monthly bumps are scoped to
+    // their stamp (reset with the window); lifetime bump is permanent.
     dailyBumpNanos: v.optional(v.number()),
+    monthlyBumpNanos: v.optional(v.number()),
     lifetimeBumpNanos: v.optional(v.number()),
     bumpDayStamp: v.optional(v.string()),
+    bumpMonthStamp: v.optional(v.string()),
     // settled totals (from finished requests)
     totalSpendNanos: v.number(),
     totalRequests: v.number(),
     totalTokens: v.number(),
     // daily window
-    dayStamp: v.string(), // e.g. "2026-08-27" (UTC)
+    dayStamp: v.string(),
     spendTodayNanos: v.number(),
     tokensToday: v.optional(v.number()),
+    // monthly window (UTC calendar month, e.g. "2026-09")
+    monthStamp: v.optional(v.string()),
+    spendThisMonthNanos: v.optional(v.number()),
+    tokensThisMonth: v.optional(v.number()),
     // in-flight reservations (pessimistic holds; released on settle/expiry)
     reservedTodayNanos: v.optional(v.number()),
+    reservedMonthNanos: v.optional(v.number()),
     reservedTotalNanos: v.optional(v.number()),
     reservedTodayTokens: v.optional(v.number()),
+    reservedMonthTokens: v.optional(v.number()),
     reservedTotalTokens: v.optional(v.number()),
     pendingCount: v.optional(v.number()),
-  }).index("userId", ["userId"]),
+  })
+    .index("dim_value", ["dimension", "value"])
+    .index("dimension", ["dimension"]),
 
-  // per-action-name budgets and running totals (e.g. "chat", "summarize")
-  actions: defineTable({
-    name: v.string(),
-    dailySpendLimitNanos: v.optional(v.number()),
-    lifetimeSpendLimitNanos: v.optional(v.number()),
-    dailyTokenLimit: v.optional(v.number()),
-    lifetimeTokenLimit: v.optional(v.number()),
-    disabled: v.optional(v.boolean()),
-    enforcement: v.optional(v.union(v.literal("hard"), v.literal("soft"))),
-    dailyBumpNanos: v.optional(v.number()),
-    lifetimeBumpNanos: v.optional(v.number()),
-    bumpDayStamp: v.optional(v.string()),
-    totalSpendNanos: v.number(),
-    totalRequests: v.number(),
-    totalTokens: v.number(),
-    dayStamp: v.string(),
-    spendTodayNanos: v.number(),
-    tokensToday: v.optional(v.number()),
-    reservedTodayNanos: v.optional(v.number()),
-    reservedTotalNanos: v.optional(v.number()),
-    reservedTodayTokens: v.optional(v.number()),
-    reservedTotalTokens: v.optional(v.number()),
-    pendingCount: v.optional(v.number()),
-  }).index("name", ["name"]),
+  // Durable per-(bucket, period) spend history. Written from settled requests
+  // and manual adjustments; NEVER swept by request retention, so spend charts
+  // and "what did we spend last month" survive long after the raw request rows
+  // are purged. period is "day" ("2026-09-04") or "month" ("2026-09").
+  usage: defineTable({
+    dimension: v.string(),
+    value: v.string(),
+    period: v.union(v.literal("day"), v.literal("month")),
+    stamp: v.string(),
+    spendNanos: v.number(),
+    tokens: v.number(),
+    requests: v.number(),
+  })
+    .index("bucket_period_stamp", ["dimension", "value", "period", "stamp"])
+    .index("period_stamp", ["period", "stamp"]),
+
+  // Reverse index for filtering the request log by an arbitrary tag dimension
+  // (user/action are already indexed on `requests`). One row per extra tag per
+  // request; cleaned up with the request on retention/deletion.
+  requestTags: defineTable({
+    dimension: v.string(),
+    value: v.string(),
+    requestId: v.id("requests"),
+  })
+    .index("dim_value", ["dimension", "value"])
+    .index("requestId", ["requestId"]),
+
+  // Manual credits/debits applied to a bucket (comp a user, correct an
+  // overcharge). Negative delta = credit/refund, positive = extra charge.
+  adjustments: defineTable({
+    dimension: v.string(),
+    value: v.string(),
+    deltaNanos: v.number(),
+    tokens: v.optional(v.number()),
+    reason: v.optional(v.string()),
+  }).index("dim_value", ["dimension", "value"]),
 
   requests: defineTable({
+    // `user` and `action` stay first-class + indexed (the hot-path filters and
+    // rate limiting); the full attribution incl. extra tags lives in `tags`.
     userId: v.string(),
     actionName: v.optional(v.string()),
+    tags: v.optional(v.array(vTag)),
     model: v.string(),
     // pessimistic holds placed at start; reconciled to actual on settle
     estimatedNanos: v.optional(v.number()),
@@ -92,6 +132,9 @@ export default defineSchema({
     completionTokens: v.optional(v.number()),
     // subset of promptTokens served from the provider's prompt cache (cheaper).
     cachedTokens: v.optional(v.number()),
+    // server-side tool invocations that bill a per-call fee on top of tokens
+    // (e.g. { web_search: 3 }). Priced via serverToolPrices at settle.
+    serverToolUses: v.optional(v.record(v.string(), v.number())),
     costNanos: v.optional(v.number()),
     latencyMs: v.optional(v.number()),
     rerunOf: v.optional(v.id("requests")),
@@ -107,6 +150,9 @@ export default defineSchema({
     model: v.string(),
     inputNanosPerMTok: v.number(),
     outputNanosPerMTok: v.number(),
+    // price for cached (prompt-cache-read) input tokens. Providers bill these
+    // at a fraction of the input rate; if unset, a default discount is applied.
+    cachedNanosPerMTok: v.optional(v.number()),
   }).index("model", ["model"]),
 
   // singleton component config (key === "singleton")
@@ -122,12 +168,12 @@ export default defineSchema({
       )
     ),
     models: v.optional(v.array(v.string())),
-    // Deployment-wide ("global") spend cap across ALL users and actions. The
-    // running totals live in a sharded counter (high write throughput); only
-    // the limit config lives here. The cap is enforced approximately — the
-    // sharded total is read without a reservation, so under heavy concurrency
-    // it can overshoot by a bounded amount. Right for a global killswitch;
-    // per-user/per-action caps stay exact via reserve/settle.
+    // Deployment-wide ("global") spend cap across ALL requests. Running totals
+    // live in a sharded counter (high write throughput) since every request
+    // touches it; only the limit config lives here. Enforced approximately —
+    // the sharded total is read without a reservation, so under heavy
+    // concurrency it can overshoot by a bounded amount. Right for a global
+    // killswitch; per-bucket concurrent admission is atomic via reserve/settle.
     globalDailySpendLimitNanos: v.optional(v.number()),
     globalLifetimeSpendLimitNanos: v.optional(v.number()),
     globalEnforcement: v.optional(
@@ -138,5 +184,11 @@ export default defineSchema({
     globalBumpDayStamp: v.optional(v.string()),
     // request-row retention window in ms (default 1h); 0 disables sweeping.
     retentionMs: v.optional(v.number()),
+    // default approaching-limit alert threshold (fraction of a cap) for buckets
+    // that don't set their own warnAtPct. 0/unset disables threshold alerts.
+    defaultWarnAtPct: v.optional(v.number()),
+    // per-call price (nanodollars) overrides for provider server tools, keyed by
+    // tool name (e.g. { web_search: 12_000_000 }). Merged over the defaults.
+    serverToolPrices: v.optional(v.record(v.string(), v.number())),
   }).index("key", ["key"]),
 });