@aria-framework/ai 0.11.0 → 0.12.1

package/index.js

@@ -204,6 +204,14 @@ module.exports = {
   // install a database package to require this one.
   get createUsageStore() { return require('./usageStore').createUsageStore; },
   get createProviderStore() { return require('./providerStore').createProviderStore; },
+  // Speed history. Lazy for the same reason as the others: it needs the db-worker driver contract,
+  // which is an optional peer.
+  get createSpeedStore() { return require('./speedStore').createSpeedStore; },
+  // EXPORTED SO A CONSUMER CAN ASSERT ITS TABLE MATCHES. An app writes its own migration, which is
+  // a hand copy of this DDL — and a copy with nothing comparing it to the original is the failure
+  // mode this repo has already documented twice. providerSchemaFor and usageSchemaFor exist for the
+  // same reason; leaving this one out meant a drift would surface as an INSERT throwing at runtime.
+  get speedSchemaFor() { return require('./speedStore').schemaFor; },
   // No database behind health, so it loads eagerly like the rest of the seam.
   ...require('./health'),
   /**

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.11.0",
+  "version": "0.12.1",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -16,7 +16,7 @@
     "generate.js",
     "providers/openai-compatible.js",
     "providers/anthropic.js",
-    "browser/ai-polish.js", "usageStore.js", "providerStore.js", "health.js",
+    "browser/ai-polish.js", "usageStore.js", "providerStore.js","speedStore.js", "health.js",
     "benchmark.js", "views/"
   ],
   "peerDependencies": {
@@ -26,6 +26,6 @@
     "@aria-framework/db-worker": { "optional": true }
   },
   "scripts": {
-    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/health.js && node test/listModels.js && node test/benchmark.js && node test/packaging.js && node test/views.js"
+    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/speedStore.js && node test/health.js && node test/listModels.js && node test/benchmark.js && node test/packaging.js && node test/views.js"
   }
 }

package/speedStore.js

@@ -0,0 +1,186 @@
+/**
+ * A speed check, kept.
+ *
+ * WHY IT IS NOT THE AUDIT LOG. A benchmark already leaves an audit row, and it should: someone
+ * spent tokens, and that is an audit concern. But the audit log answers "who did what", and it is
+ * pruned on a policy about how long security records are kept. Coupling "how fast is this GPU over
+ * time" to that policy means either keeping audit rows longer than intended or losing months of
+ * performance history to a decision that had nothing to do with performance. Two questions, two
+ * retentions, two shapes.
+ *
+ * WHY ROWS AND NOT AN AVERAGE. An endpoint's speed is not one number, it is a line: the interesting
+ * moments are the changes. A local model that quietly halved in speed the day a second server
+ * started sharing its GPU is invisible in a running average and obvious in a sequence — and that
+ * exact case was observed while this was being built, LM Studio dropping from 51 tok/s to 8 while a
+ * 22 GB model sat resident beside it.
+ *
+ * WHY THE COLD TIME IS STORED SEPARATELY. It measures a different thing from the rate — whether the
+ * model was resident — and mixing them hides both.
+ */
+
+'use strict';
+
+/** Newest first everywhere: a trend is read backwards from now, and a card wants the last one. */
+const DEFAULT_LIMIT = 30;
+
+function createSpeedStore(opts = {}) {
+  const driver = opts.driver;
+  if (!driver || typeof driver.run !== 'function') {
+    throw new Error('createSpeedStore({ driver }): the db-worker driver contract is required');
+  }
+  const table = opts.table || 'ai_speed_checks';
+  const now = opts.now || (() => new Date());
+
+  const num = (v) => (v == null || v === '' || Number.isNaN(Number(v)) ? null : Number(v));
+
+  /**
+   * `YYYY-MM-DD HH:MM:SS` in UTC — what `datetime('now')` produces, and what every other timestamp
+   * column in a consuming app already holds.
+   *
+   * toISOString() was the obvious thing to write and the wrong thing to store. Apps parse these
+   * columns with `new Date(String(ts).replace(' ', 'T') + 'Z')`; given an ISO string there is no
+   * space to replace, so the 'Z' is appended to one already there and the result is Invalid Date —
+   * silently, because the helper checks isNaN and returns ''. Sorting is worse: 'T' (0x54) sorts
+   * after ' ' (0x20), so an ISO row and a datetime('now') row from the same second compare wrong.
+   */
+  const stamp = (d) => {
+    const p2 = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}-${p2(d.getUTCMonth() + 1)}-${p2(d.getUTCDate())} `
+      + `${p2(d.getUTCHours())}:${p2(d.getUTCMinutes())}:${p2(d.getUTCSeconds())}`;
+  };
+
+  return {
+    table,
+
+    /**
+     * Record one measurement.
+     *
+     * A FAILED CHECK IS RECORDED TOO, with a null rate. "It could not be reached at 14:00" is part
+     * of the trend, and dropping it would draw a line straight through an outage as though nothing
+     * had happened.
+     */
+    async record(entry = {}) {
+      await driver.run(
+        `INSERT INTO ${table}
+           (endpoint, checked_at, tokens_per_sec, cold_ms, run_tokens, verdict, reasoning, tokens_spent, error)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          String(entry.endpoint || ''),
+          stamp(entry.at || now()),
+          num(entry.tokensPerSec),
+          num(entry.coldMs),
+          num(entry.runTokens),
+          entry.verdict ? String(entry.verdict) : null,
+          entry.reasoning ? 1 : 0,
+          Number(entry.tokensSpent) || 0,
+          entry.error ? String(entry.error).slice(0, 500) : null
+        ]
+      );
+    },
+
+    /** The most recent checks for one endpoint, newest first. */
+    async recent(endpoint, limit = DEFAULT_LIMIT) {
+      return driver.all(
+        `SELECT * FROM ${table} WHERE endpoint = ? ORDER BY id DESC LIMIT ?`,
+        [String(endpoint), Math.max(1, Math.min(500, Number(limit) || DEFAULT_LIMIT))]
+      );
+    },
+
+    /**
+     * A series per endpoint, OLDEST FIRST, ready to draw.
+     *
+     * One query for every endpoint rather than one per card: a page with eight endpoints should not
+     * make eight round trips to draw eight small lines.
+     */
+    async seriesFor(endpoints, limit = DEFAULT_LIMIT) {
+      const ids = (endpoints || []).map((e) => String(e)).filter(Boolean);
+      if (!ids.length) return {};
+      const capped = Math.max(1, Math.min(500, Number(limit) || DEFAULT_LIMIT));
+      // LIMITED PER ENDPOINT, IN SQL. A single `WHERE endpoint IN (...) ORDER BY id DESC` reads
+      // every retained row for every endpoint and throws most of them away in JS — at the 200-row
+      // bound with eight endpoints that is 1600 rows, `error` text included, marshalled across the
+      // worker boundary to draw eight 88-pixel lines. It also cannot use the (endpoint, id DESC)
+      // index for a global ordering, so it sorts in a temp b-tree as well.
+      //
+      // UNION ALL of per-endpoint selects rather than a window function: it reads the same on both
+      // engines and needs no version floor.
+      // EACH BRANCH IN A SUBQUERY, and aliased. A bare `... ORDER BY id DESC LIMIT n UNION ALL ...`
+      // is a syntax error — the ORDER BY binds to the compound, not the branch — and Postgres
+      // additionally requires a name for a subquery in FROM. Both engines accept this form.
+      const sql = ids
+        .map((_, i) => `SELECT * FROM (SELECT * FROM ${table} WHERE endpoint = ? `
+          + `ORDER BY id DESC LIMIT ${capped}) AS s${i}`)
+        .join(' UNION ALL ');
+      const rows = await driver.all(sql, ids);
+      const out = {};
+      for (const row of rows) {
+        const bucket = out[row.endpoint] || (out[row.endpoint] = { latest: null, points: [] });
+        // Newest first WITHIN each endpoint's block, which is all this needs — the blocks
+        // themselves may arrive in any order.
+        if (!bucket.latest) bucket.latest = row;
+        bucket.points.push(row);
+      }
+      // Reversed at the end so a caller draws left-to-right in time without thinking about it.
+      for (const id of Object.keys(out)) out[id].points.reverse();
+      return out;
+    },
+
+    /**
+     * Keep the most recent N per endpoint.
+     *
+     * Bounded by ENDPOINT rather than by age: an endpoint checked twice a year deserves to keep its
+     * history, and one checked hourly should not be able to bury it. Age-based pruning gets that
+     * backwards for exactly the endpoints whose trend matters most.
+     */
+    async prune({ keepPerEndpoint = 200, endpoint = null } = {}) {
+      const keep = Math.max(10, Math.min(5000, Number(keepPerEndpoint) || 200));
+      // ONE ENDPOINT WHEN THE CALLER KNOWS WHICH. Pruning on write swept every endpoint in the
+      // table every time — 1 + 2N queries to delete at most one row belonging to one of them, since
+      // none of the others can have grown since their own last write. With eight endpoints that was
+      // seventeen worker round trips inside a request, for one deletion.
+      const ids = endpoint
+        ? [{ endpoint: String(endpoint) }]
+        : await driver.all(`SELECT DISTINCT endpoint FROM ${table}`, []);
+      let removed = 0;
+      for (const { endpoint } of ids) {
+        const cutoff = await driver.get(
+          `SELECT id FROM ${table} WHERE endpoint = ? ORDER BY id DESC LIMIT 1 OFFSET ?`,
+          [endpoint, keep]
+        );
+        if (!cutoff) continue;
+        const r = await driver.run(
+          `DELETE FROM ${table} WHERE endpoint = ? AND id <= ?`, [endpoint, cutoff.id]
+        );
+        removed += (r && r.changes) || 0;
+      }
+      return { removed };
+    }
+  };
+}
+
+/** The DDL, in the caller's dialect. */
+function schemaFor(dialect) {
+  const t = dialect || {
+    autoIncrementPk: () => 'INTEGER PRIMARY KEY AUTOINCREMENT',
+    now: () => "datetime('now')"
+  };
+  return `
+  id             ${t.autoIncrementPk()},
+  -- The endpoint NAME, not a foreign key: a measurement is still true after the endpoint it
+  -- describes has been deleted, and "this machine used to manage 80 tok/s" is worth keeping when
+  -- deciding whether to configure it again.
+  endpoint       TEXT    NOT NULL,
+  checked_at     TEXT    NOT NULL,
+  -- NULL when the check failed. A failed check is part of the trend; a zero would be a lie about
+  -- a server that never answered at all.
+  tokens_per_sec REAL,
+  cold_ms        INTEGER,
+  run_tokens     INTEGER,
+  verdict        TEXT,
+  reasoning      INTEGER NOT NULL DEFAULT 0,
+  tokens_spent   INTEGER NOT NULL DEFAULT 0,
+  error          TEXT
+`;
+}
+
+module.exports = { createSpeedStore, schemaFor };

package/views/ai/provider-card.ejs

@@ -8,6 +8,8 @@
     canEdit  boolean — hides controls rather than disabling them, because a greyed-out
              button still advertises a feature and invites a support ticket
     routes   [{ id, position }] this provider appears in, for the shared-fallback warning
+    speed    { latest, points } from createSpeedStore.seriesFor() — may be undefined. `points` is
+             oldest-first, so the line reads left to right in time.
 
   WHY "reachable" AND "model loaded" ARE SHOWN SEPARATELY: a local server answers /models
   perfectly while the model itself has been evicted, and the next call then pays a
@@ -97,6 +99,63 @@
             <span class="font-monospace">never</span>
           <% } %>
         </div>
+
+        <%
+          // SPEED OVER TIME, because an endpoint's speed is not one number — the interesting moments
+          // are the changes. A local model that quietly halved the day a second server started
+          // sharing its GPU is invisible in the latest figure and obvious in a line. That exact case
+          // turned up while this was being built: 51 tok/s alone, 8 with a 22 GB model beside it.
+          const sp = (typeof speed !== 'undefined' && speed) ? speed : null;
+          // FAILED CHECKS ARE HOLES, NOT ZEROES. A server that never answered has no rate; drawing
+          // it at the bottom of the chart would read as "very slow" when it means "not there".
+          const pts = sp ? (sp.points || []).filter((r) => r.tokens_per_sec != null) : [];
+          const rates = pts.map((r) => Number(r.tokens_per_sec));
+        -%>
+        <% if (rates.length >= 2) { %>
+          <%
+            const lo = Math.min(...rates);
+            const hi = Math.max(...rates);
+            // A FLAT LINE MUST LOOK FLAT. With lo === hi the scale collapses and every point lands
+            // on the same row — which is correct, but only if the divisor does not become zero.
+            const span = (hi - lo) || 1;
+            const W = 88;
+            const H = 22;
+            const step = rates.length > 1 ? W / (rates.length - 1) : W;
+            const xy = rates.map((v, i) => [
+              Math.round(i * step * 10) / 10,
+              Math.round((H - 3 - ((v - lo) / span) * (H - 6)) * 10) / 10
+            ]);
+            const last = xy[xy.length - 1];
+            const latestRate = rates[rates.length - 1];
+            const verdict = sp.latest && sp.latest.verdict;
+          -%>
+          <div>
+            <div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Speed</div>
+            <div class="d-flex align-items-center gap-2">
+              <%# currentColor throughout: this partial renders in two apps and both themes, and a
+                  hard-coded stroke would be invisible in one of them. %>
+              <svg width="<%= W %>" height="<%= H %>" viewBox="0 0 <%= W %> <%= H %>"
+                   class="<%= verdict === 'slow' ? 'text-warning' : (verdict === 'pass' ? 'text-success' : 'text-body-secondary') %>"
+                   role="img"
+                   aria-label="<%= rates.length %> speed checks, oldest <%= lo %> to newest <%= latestRate %> tokens per second">
+                <polyline fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"
+                          stroke-linecap="round" opacity="0.65"
+                          points="<%= xy.map(function (q) { return q[0] + ',' + q[1]; }).join(' ') %>"></polyline>
+                <%# The newest point marked, because "where is it now" is the first question the
+                    line raises and counting to the right-hand end is a poor way to answer it. %>
+                <circle cx="<%= last[0] %>" cy="<%= last[1] %>" r="2" fill="currentColor"></circle>
+              </svg>
+              <span class="font-monospace" style="font-variant-numeric: tabular-nums"><%= latestRate %> tok/s</span>
+            </div>
+          </div>
+        <% } 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. %>
+            <span class="font-monospace" style="font-variant-numeric: tabular-nums"><%= sp.latest.tokens_per_sec %> tok/s</span>
+          </div>
+        <% } %>
       </div>
 
       <% if (p.daily_token_cap) { %>