@aria-framework/ai 0.1.0 → 0.2.0

package/index.js

@@ -170,6 +170,11 @@ function createAiClient(deps = {}) {
 }
 
 module.exports = {
+  // The usage counter behind every ceiling. LAZY: it needs the db-worker driver contract, which
+  // is an OPTIONAL peer — a consumer using only createAiClient/polish/facts must not be made to
+  // install a database package to require this one.
+  get createUsageStore() { return require('./usageStore').createUsageStore; },
+  get usageSchemaFor() { return require('./usageStore').schemaFor; },
   createAiClient,
   PROVIDERS, DEFAULTS,
   AiError, fromFetchFailure, redact,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aria-framework/ai",
   "description": "Aria App Framework — AI module. A dependency-injected model seam (createAiClient) over several providers (LM Studio / OpenAI-compatible / Anthropic), with a fact-preservation guard, generic Polish and Generate writing engines, and a browser polish widget. Prompts and config stay in the consuming app.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -16,9 +16,15 @@
     "generate.js",
     "providers/openai-compatible.js",
     "providers/anthropic.js",
-    "browser/ai-polish.js"
+    "browser/ai-polish.js", "usageStore.js"
   ],
+  "peerDependencies": {
+    "@aria-framework/db-worker": ">=0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@aria-framework/db-worker": { "optional": true }
+  },
   "scripts": {
-    "test": "node test/smoke.js"
+    "test": "node test/smoke.js && node test/usageStore.js"
   }
 }

package/usageStore.js

@@ -0,0 +1,270 @@
+/**
+ * What the model has cost — the counter behind every ceiling.
+ *
+ * EXTRACTED FROM SUPPORT101 (models/AiUsage.js + lib/ai/budget.js), which has run this in
+ * production since its migration 014. The design decisions below are its, kept because they were
+ * right and the reasoning was written down; what changed is that the app-specific parts became
+ * parameters.
+ *
+ * ── APPEND-ONLY, ONE ROW PER CALL ───────────────────────────────────────────────────────────────
+ * Not a per-day counter that gets incremented. Two reasons, both from the original:
+ *   1. A counter update is a read-modify-write, and two concurrent calls lose one of them. A
+ *      ceiling backed by a lossy counter is a report, not a limit.
+ *   2. A row per call is what makes "which ticket ate the budget" answerable at all.
+ *
+ * The cost is volume, and it is NOT negligible at every scale. Support101's own comment says "the
+ * table is small — a busy day is hundreds of rows", which is true for a helpdesk (~110k rows/year)
+ * and false for log triage (~14.6M rows/year at 40k calls/day). So `rollup()` exists: detail rows
+ * are short-lived, and a daily aggregate is what survives. Append-only is preserved; only the
+ * retention of the detail changes.
+ *
+ * ── CHECKED BEFORE, RECORDED AFTER ──────────────────────────────────────────────────────────────
+ * There is no way to know what a call will cost until it returns, so a ceiling is "you are already
+ * over", never "this would take you over". The last call may overshoot by its own size. The
+ * alternative — estimate and refuse in advance — is a guess about a number that cannot be
+ * computed, and being wrong in the confident direction blocks work that would have fit. A bounded
+ * overshoot is explainable; a wrong estimate is not.
+ *
+ * ── A CEILING OF 0 IS OFF ───────────────────────────────────────────────────────────────────────
+ * Not "no tokens allowed". An install that has never opened the budget screen is unlimited rather
+ * than silently broken — the opposite default presents as "the AI stopped working" on a fresh
+ * install with no clue why.
+ *
+ * ── THE DAY IS THE APP'S DAY ────────────────────────────────────────────────────────────────────
+ * A ceiling is an allowance a person set, so it resets when their day does. Computing it in UTC
+ * rolls the budget over mid-afternoon in +02:00, which gets diagnosed as "the AI randomly stopped
+ * working". The clock is therefore injected, and defaults to the host's local date.
+ *
+ * ── WHAT STAYS IN THE APP ───────────────────────────────────────────────────────────────────────
+ * The SCOPE column and its foreign key. Support101 scopes by `ticket_id` with
+ * `ON DELETE CASCADE`, so deleting a ticket takes its usage with it — real behaviour a generic
+ * column could not carry. App 3 will scope by incident. So the package is told the column NAME and
+ * the app owns the column, its type and its constraints.
+ */
+
+'use strict';
+
+/** YYYY-MM-DD in whatever zone the supplied clock is in. */
+function dayOf(date) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/**
+ * @param {object} opts
+ *   driver         @aria-framework/db-worker driver contract (required)
+ *   table          detail table, default 'ai_usage'
+ *   rollupTable    daily aggregate, default 'ai_usage_daily'
+ *   scopeColumn    the app's scope column, e.g. 'ticket_id'. Omitted = no scope dimension.
+ *   routeColumn    the route column, e.g. 'route'. Omitted = no route dimension.
+ *   now            () => Date, the APP'S clock. Default: host local time.
+ */
+function createUsageStore(opts = {}) {
+  const driver = opts.driver;
+  if (!driver || typeof driver.run !== 'function') {
+    throw new Error('createUsageStore({ driver }): the db-worker driver contract is required');
+  }
+  const table = opts.table || 'ai_usage';
+  const rollupTable = opts.rollupTable || 'ai_usage_daily';
+  const scopeCol = opts.scopeColumn || null;
+  const routeCol = opts.routeColumn || null;
+  const now = typeof opts.now === 'function' ? opts.now : () => new Date();
+
+  /** Column list and placeholders, built once from what the app actually has. */
+  const cols = ['day', 'provider', 'model', 'calls', 'prompt_tokens', 'completion_tokens', 'total_tokens'];
+  if (scopeCol) cols.splice(3, 0, scopeCol);
+  if (routeCol) cols.splice(3, 0, routeCol);
+
+  return {
+    table,
+    rollupTable,
+
+    /** The current day string, exposed because callers compare against it. */
+    today: () => dayOf(now()),
+
+    /**
+     * Record one provider call. NEVER THROWS — see the wrapper in `budget` below; a lost counter
+     * row is a bookkeeping problem, not a reason to fail work that succeeded.
+     */
+    async record(entry = {}) {
+      const prompt = Number(entry.promptTokens) || 0;
+      const completion = Number(entry.completionTokens) || 0;
+      const total = Number(entry.totalTokens) || (prompt + completion);
+
+      const values = [dayOf(now()), String(entry.provider || ''), String(entry.model || '')];
+      if (routeCol) values.push(entry.route == null ? null : String(entry.route));
+      if (scopeCol) values.push(entry.scope == null ? null : entry.scope);
+      values.push(1, prompt, completion, total);
+
+      const placeholders = cols.map(() => '?').join(', ');
+      const r = await driver.run(
+        `INSERT INTO ${table} (${cols.join(', ')}) VALUES (${placeholders})`, values);
+      return { id: r.lastId };
+    },
+
+    /** Tokens spent today, across every path — background jobs and button presses alike. */
+    async tokensToday() {
+      const r = await driver.get(
+        `SELECT COALESCE(SUM(total_tokens), 0) n FROM ${table} WHERE day = ?`, [dayOf(now())]);
+      return Number(r.n) || 0;
+    },
+
+    /**
+     * Tokens ever spent against one scope.
+     *
+     * NOT PER DAY, deliberately, and this is load-bearing: the scope cap exists to stop one
+     * pathological thread — a hundred-message argument, or a retry loop against something the
+     * model keeps failing on — from eating the budget. A cap that reset at midnight would let
+     * exactly that happen, one day at a time, which is the failure it was written to prevent.
+     */
+    async tokensForScope(scope) {
+      if (!scopeCol) throw new Error('createUsageStore: no scopeColumn was configured');
+      const r = await driver.get(
+        `SELECT COALESCE(SUM(total_tokens), 0) n FROM ${table} WHERE ${scopeCol} = ?`, [scope]);
+      return Number(r.n) || 0;
+    },
+
+    /** For the admin screen: recent days, newest first. */
+    async byDay(days = 14) {
+      const limit = Math.min(200, Math.max(1, Number(days) * 4));
+      const group = ['day', 'provider', 'model'].concat(routeCol ? [routeCol] : []);
+      return driver.all(
+        `SELECT ${group.join(', ')},
+                SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
+                SUM(completion_tokens) completion_tokens, SUM(total_tokens) total_tokens
+           FROM ${table}
+          GROUP BY ${group.join(', ')}
+          ORDER BY day DESC, total_tokens DESC
+          LIMIT ?`, [limit]);
+    },
+
+    /** Totals per provider over a window, for the usage screen's per-provider table. */
+    async byProvider(sinceDay) {
+      return driver.all(
+        `SELECT provider, model,
+                SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
+                SUM(completion_tokens) completion_tokens, SUM(total_tokens) total_tokens
+           FROM ${table}
+          WHERE day >= ?
+          GROUP BY provider, model
+          ORDER BY total_tokens DESC`, [String(sinceDay)]);
+    },
+
+    /**
+     * Fold completed days of detail into the daily aggregate, then drop the folded detail.
+     *
+     * THIS IS WHAT MAKES APPEND-ONLY SURVIVABLE AT VOLUME. Deliberately NOT a trigger or an upsert
+     * on the write path: keeping the hot path a plain INSERT is the entire reason two concurrent
+     * calls cannot lose each other's counts.
+     *
+     * GRANULARITY MATCHES THE DATA. The detail table carries `day`, not an hour, so this rolls up
+     * by day — an earlier draft grouped by day and wrote the result into an `hour` column, which
+     * was incoherent. A consumer that needs finer buckets (log triage, where a day is far too
+     * coarse) adds an hour column to its own detail table and configures it; inventing one here
+     * from a date would be inventing precision that was never recorded.
+     *
+     * ONLY COMPLETED DAYS are folded. Folding today would race with calls still arriving into it,
+     * and the aggregate would disagree with the detail for as long as the day lasted.
+     *
+     * IDEMPOTENT via a watermark read from the aggregate's own MAX(day) — see below. Re-running is
+     * a no-op rather than a doubling, which matters because retention can leave folded detail in
+     * place for days.
+     *
+     * @param {{keepDetailDays?: number}} o  how many completed days of DETAIL to keep after
+     *        folding. 0 = keep none; the aggregate is the record from then on.
+     * @returns {{folded: number, deleted: number}}
+     */
+    async rollup(o = {}) {
+      const keepDays = Math.max(0, Number(o.keepDetailDays) || 0);
+      const group = ['provider', 'model'].concat(routeCol ? [routeCol] : []);
+      const todayStr = dayOf(now());
+      // Detail older than this is safe to delete: it has been folded AND is past retention.
+      const deleteBefore = dayOf(new Date(now().getTime() - keepDays * 86400000));
+
+      let folded = 0;
+      let deleted = 0;
+      await driver.transaction(async (tx) => {
+        // THE WATERMARK, and it is what makes this idempotent. Without it, any run with
+        // keepDetailDays > 0 re-folds detail that survived the last run and DOUBLES the aggregate
+        // — the ON CONFLICT accumulates, which is correct for new rows and catastrophic for
+        // repeats. Derived from the aggregate itself rather than stored separately: the highest
+        // day already folded is exactly `MAX(day)` there, so there is no second piece of state to
+        // keep in step.
+        const mark = await tx.get(`SELECT MAX(day) m FROM ${rollupTable}`);
+        const after = (mark && mark.m) || '';
+
+        const rows = await tx.all(
+          `SELECT day, ${group.join(', ')},
+                  SUM(calls) calls, SUM(prompt_tokens) p, SUM(completion_tokens) c,
+                  SUM(total_tokens) t
+             FROM ${table}
+            WHERE day < ? AND day > ?
+            GROUP BY day, ${group.join(', ')}`, [todayStr, after]);
+
+        const key = ['day', 'provider', 'model'].concat(routeCol ? [routeCol] : []);
+        for (const row of rows) {
+          const vals = [row.day, row.provider, row.model];
+          if (routeCol) vals.push(row[routeCol]);
+          await tx.run(
+            `INSERT INTO ${rollupTable} (${key.join(', ')}, calls, prompt_tokens, completion_tokens, total_tokens)
+             VALUES (${key.map(() => '?').join(', ')}, ?, ?, ?, ?)
+             ON CONFLICT(${key.join(', ')}) DO UPDATE SET
+               calls = ${rollupTable}.calls + excluded.calls,
+               prompt_tokens = ${rollupTable}.prompt_tokens + excluded.prompt_tokens,
+               completion_tokens = ${rollupTable}.completion_tokens + excluded.completion_tokens,
+               total_tokens = ${rollupTable}.total_tokens + excluded.total_tokens`,
+            vals.concat([row.calls, row.p, row.c, row.t]));
+          folded++;
+        }
+
+        if (folded && deleteBefore < todayStr) {
+          const res = await tx.run(`DELETE FROM ${table} WHERE day < ?`, [deleteBefore]);
+          deleted = Number(res.changes) || 0;
+        }
+      });
+      return { folded, deleted };
+    }
+  };
+}
+
+/**
+ * The DDL for both tables, in the caller's dialect.
+ *
+ * The app owns its SCOPE column and any foreign key on it — Support101's `ticket_id` cascades from
+ * `tickets`, which a generic column could not do — so this emits everything EXCEPT that, and the
+ * app adds it in its own migration.
+ */
+function schemaFor(dialect, o = {}) {
+  const t = dialect || {
+    autoIncrementPk: () => 'INTEGER PRIMARY KEY AUTOINCREMENT',
+    now: () => "datetime('now')"
+  };
+  const route = o.routeColumn ? `\n  ${o.routeColumn}${' '.repeat(Math.max(1, 14 - o.routeColumn.length))}TEXT,` : '';
+  return {
+    detail: `
+  id                ${t.autoIncrementPk()},
+  day               TEXT    NOT NULL,
+  provider          TEXT    NOT NULL,
+  model             TEXT    NOT NULL,${route}
+  calls             INTEGER NOT NULL DEFAULT 1,
+  prompt_tokens     INTEGER NOT NULL DEFAULT 0,
+  completion_tokens INTEGER NOT NULL DEFAULT 0,
+  total_tokens      INTEGER NOT NULL DEFAULT 0,
+  created_at        TEXT    NOT NULL DEFAULT (${t.now()})
+`,
+    // The UNIQUE key is what ON CONFLICT targets — without it the rollup silently inserts
+    // duplicates instead of accumulating, and every re-run doubles the totals.
+    rollup: `
+  day               TEXT    NOT NULL,
+  provider          TEXT    NOT NULL,
+  model             TEXT    NOT NULL,${route}
+  calls             INTEGER NOT NULL DEFAULT 0,
+  prompt_tokens     INTEGER NOT NULL DEFAULT 0,
+  completion_tokens INTEGER NOT NULL DEFAULT 0,
+  total_tokens      INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(day, provider, model${o.routeColumn ? ', ' + o.routeColumn : ''})
+`
+  };
+}
+
+module.exports = { createUsageStore, schemaFor, _dayOf: dayOf };