@aria-framework/ai 0.12.1 → 0.13.0

package/health.js

@@ -320,13 +320,69 @@ function createHealthChecker(opts = {}) {
       };
     },
 
-    /** All known state, for persisting across a restart if an app wants to. */
+    /** All known state in the shape a UI renders. For PERSISTENCE use exportState(). */
     snapshot() {
       const out = {};
       for (const id of state.keys()) out[id] = this.status(id);
       return out;
     },
 
+    /**
+     * The facts worth surviving a restart.
+     *
+     * NOT EVERYTHING IS. Health lives in memory, so every deploy wipes it and each card reads "no
+     * record" until something touches the endpoint — which is why this exists. But restoring the
+     * whole state would be worse than restoring none of it:
+     *
+     *   lastGoodAt, lastCheckedAt, lastMs, lastError, modelPresent — KEPT. Each is a record of
+     *     something that already happened, and the UI dates them ("last good 3h ago"). An operator
+     *     reading one is not misled about when it was true.
+     *
+     *   failures and downUntil — DROPPED. A cooldown is a decision about NOW, and a restart is very
+     *     often the fix: restoring a trip from before it would hold a repaired endpoint out of
+     *     rotation for a reason that no longer exists. A fresh process gives every endpoint one
+     *     honest attempt, which costs at most a single timeout to discover.
+     *
+     *   throughput samples — DROPPED. A rate is shown bare — "52 tok/s" — with nothing saying when
+     *     it was measured, so carrying one across a restart presents a stale figure as current.
+     *     Unlike "3h ago" it cannot date itself. It refills on the next real call.
+     */
+    exportState() {
+      const out = {};
+      for (const [id, e] of state) {
+        if (!e.lastCheckedAt && !e.lastGoodAt) continue;   // nothing worth writing down
+        out[id] = {
+          lastGoodAt: e.lastGoodAt,
+          lastCheckedAt: e.lastCheckedAt,
+          lastMs: e.lastMs,
+          lastError: e.lastError,
+          modelPresent: e.modelPresent
+        };
+      }
+      return out;
+    },
+
+    /**
+     * Seed from a previous process. Anything already known in THIS process wins.
+     *
+     * A live entry means something has happened since boot, and a fact measured a moment ago beats
+     * one restored from disk — importing over it would move "last good" backwards.
+     */
+    importState(saved) {
+      let seeded = 0;
+      for (const [id, v] of Object.entries(saved || {})) {
+        if (state.has(id) || !v) continue;
+        const e = entry(id);
+        e.lastGoodAt = v.lastGoodAt == null ? null : Number(v.lastGoodAt);
+        e.lastCheckedAt = v.lastCheckedAt == null ? null : Number(v.lastCheckedAt);
+        e.lastMs = v.lastMs == null ? null : Number(v.lastMs);
+        e.lastError = v.lastError == null ? null : String(v.lastError);
+        e.modelPresent = v.modelPresent == null ? null : !!v.modelPresent;
+        seeded += 1;
+      }
+      return seeded;
+    },
+
     /** Forget everything — used by tests and by "recheck now" in a UI. */
     reset(id) {
       if (id) state.delete(id); else state.clear();

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.12.1",
+  "version": "0.13.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {

package/usageStore.js

@@ -71,12 +71,22 @@ function createUsageStore(opts = {}) {
   const rollupTable = opts.rollupTable || 'ai_usage_daily';
   const scopeCol = opts.scopeColumn || null;
   const routeCol = opts.routeColumn || null;
+  /**
+   * WHICH ENDPOINT, as opposed to which KIND.
+   *
+   * `provider` has always held the adapter kind — 'lmstudio', 'openai-compatible' — which was
+   * sufficient while one provider was configured and became wrong the moment a registry could hold
+   * several. Two endpoints of the same kind share a `provider` value, so per-endpoint totals were
+   * unobtainable and a consuming screen keying on the endpoint id found nothing at all.
+   */
+  const endpointCol = opts.endpointColumn || 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);
+  if (endpointCol) cols.splice(3, 0, endpointCol);
 
   return {
     table,
@@ -95,6 +105,9 @@ function createUsageStore(opts = {}) {
       const total = Number(entry.totalTokens) || (prompt + completion);
 
       const values = [dayOf(now()), String(entry.provider || ''), String(entry.model || '')];
+      // ORDER MATCHES THE SPLICES ABOVE, last spliced first: each splice at index 3 pushes the
+      // previous one right, so the column list reads endpoint, route, scope.
+      if (endpointCol) values.push(entry.endpoint == null ? null : String(entry.endpoint));
       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);
@@ -130,7 +143,9 @@ function createUsageStore(opts = {}) {
     /** 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] : []);
+      const group = ['day', 'provider', 'model']
+        .concat(endpointCol ? [endpointCol] : [])
+        .concat(routeCol ? [routeCol] : []);
       return driver.all(
         `SELECT ${group.join(', ')},
                 SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
@@ -141,6 +156,59 @@ function createUsageStore(opts = {}) {
           LIMIT ?`, [limit]);
     },
 
+    /**
+     * Totals per ENDPOINT over a window.
+     *
+     * The question a registry screen asks — "what has this machine cost" — which `byProvider` could
+     * never answer, since it groups by adapter kind and two endpoints of one kind collapse together.
+     * Returns nothing useful unless an endpointColumn is configured, and says so rather than
+     * silently grouping by something else.
+     */
+    async byEndpoint(sinceDay) {
+      if (!endpointCol) throw new Error('createUsageStore: no endpointColumn was configured');
+      return driver.all(
+        `SELECT ${endpointCol} AS endpoint, SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
+                SUM(completion_tokens) completion_tokens, SUM(total_tokens) total_tokens
+           FROM ${table}
+          WHERE day >= ?
+          GROUP BY ${endpointCol}
+          ORDER BY total_tokens DESC`, [String(sinceDay)]);
+    },
+
+    /**
+     * Totals per ROUTE over a window.
+     *
+     * The actionable half of a spend report: a job can be pointed at a cheaper machine, run less
+     * often or switched off, while a machine is only ever the thing that happened to answer. Rows
+     * with no route come back under a NULL key — real spend that no job asked for, which must be
+     * shown rather than folded into a job that did not incur it.
+     */
+    async byRoute(sinceDay) {
+      if (!routeCol) throw new Error('createUsageStore: no routeColumn was configured');
+      return driver.all(
+        `SELECT ${routeCol} AS route, SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
+                SUM(completion_tokens) completion_tokens, SUM(total_tokens) total_tokens
+           FROM ${table}
+          WHERE day >= ?
+          GROUP BY ${routeCol}
+          ORDER BY total_tokens DESC`, [String(sinceDay)]);
+    },
+
+    /**
+     * Tokens spent today by ONE endpoint.
+     *
+     * WHAT A PER-ENDPOINT CEILING HAS TO COUNT. `tokensToday()` sums every endpoint, so comparing it
+     * against one endpoint's cap makes every cap a global one: two machines capped at 10k each stop
+     * at 10k between them rather than 10k apiece, which is not what a per-endpoint field says.
+     */
+    async tokensTodayFor(endpoint) {
+      if (!endpointCol) return this.tokensToday();
+      const r = await driver.get(
+        `SELECT COALESCE(SUM(total_tokens), 0) n FROM ${table} WHERE day = ? AND ${endpointCol} = ?`,
+        [dayOf(now()), String(endpoint)]);
+      return Number(r.n) || 0;
+    },
+
     /** Totals per provider over a window, for the usage screen's per-provider table. */
     async byProvider(sinceDay) {
       return driver.all(
@@ -243,12 +311,13 @@ function schemaFor(dialect, o = {}) {
     now: () => "datetime('now')"
   };
   const route = o.routeColumn ? `\n  ${o.routeColumn}${' '.repeat(Math.max(1, 14 - o.routeColumn.length))}TEXT,` : '';
+  const endpoint = o.endpointColumn ? `\n  ${o.endpointColumn}${' '.repeat(Math.max(1, 14 - o.endpointColumn.length))}TEXT,` : '';
   return {
     detail: `
   id                ${t.autoIncrementPk()},
   day               TEXT    NOT NULL,
   provider          TEXT    NOT NULL,
-  model             TEXT    NOT NULL,${route}
+  model             TEXT    NOT NULL,${endpoint}${route}
   calls             INTEGER NOT NULL DEFAULT 1,
   prompt_tokens     INTEGER NOT NULL DEFAULT 0,
   completion_tokens INTEGER NOT NULL DEFAULT 0,
@@ -260,7 +329,7 @@ function schemaFor(dialect, o = {}) {
     rollup: `
   day               TEXT    NOT NULL,
   provider          TEXT    NOT NULL,
-  model             TEXT    NOT NULL,${route}
+  model             TEXT    NOT NULL,${endpoint}${route}
   calls             INTEGER NOT NULL DEFAULT 0,
   prompt_tokens     INTEGER NOT NULL DEFAULT 0,
   completion_tokens INTEGER NOT NULL DEFAULT 0,

package/views/ai/provider-card.ejs

@@ -151,8 +151,9 @@
         <% } else if (sp && sp.latest && sp.latest.tokens_per_sec != null) { %>
           <div>
             <div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Speed</div>
-            <%# ONE MEASUREMENT IS NOT A TREND, so it is shown as a number and no line. Two points
-                drawn as a chart invite reading a slope into a single pair of readings. %>
+            <%# ONE MEASUREMENT IS NOT A TREND, so it is shown as a number and no line. Two ARE a
+                trend — the smallest one there is, and "it moved from 51.5 to 51.9" is worth seeing —
+                so the line starts at two, which is what the guard above says. %>
             <span class="font-monospace" style="font-variant-numeric: tabular-nums"><%= sp.latest.tokens_per_sec %> tok/s</span>
           </div>
         <% } %>