@aria-framework/ai 0.14.2 → 0.15.0

package/lmxStatus.js

@@ -0,0 +1,120 @@
+/**
+ * Turning a stack's rows and its last verification into the handful of facts a screen shows.
+ *
+ * ── WHY THIS IS A FUNCTION AND NOT A FEW LINES IN A VIEW ────────────────────────────────────────
+ * Because the definitions are not obvious, and two apps that each invent them will disagree about
+ * whether the same stack is working. "How many engines has this stack got" has four defensible
+ * answers, and only one of them is the question an operator is actually asking.
+ *
+ *   reported  — what the stack publishes. Interesting only as a denominator.
+ *   added     — how many this app has made endpoints of. This is "configured", and it is the number
+ *               that made a broken stack look exactly like a working one.
+ *   ACTIVE    — added, enabled here, AND healthy in the stack's own document right now. The only
+ *               one that answers "if this goes away, what stops working?", which is the question
+ *               somebody has before they touch anything.
+ *   missing   — added, and the stack no longer reports it at all.
+ *
+ * ── MISSING IS NOT THE SAME AS UNVERIFIED ───────────────────────────────────────────────────────
+ * An engine can only be called missing if a document actually arrived. Without one, every engine is
+ * unverified — and telling somebody their engine has vanished because the stack was asleep sends
+ * them to fix entirely the wrong thing. So `missing` is false, not unknown, until there is
+ * something to be absent from.
+ *
+ * ── TWO FACTS THE DOCUMENT DOES NOT CARRY ───────────────────────────────────────────────────────
+ * The model NAME (the document reports a full path, which is mostly directory) and the REASONING
+ * FLAG. The flag is a property of the model, not of the job, and the supervisor does not report it;
+ * reading a field that is never there makes a screen say "no known reasoning flag" about a model
+ * that has one. Getting it wrong is silent in exactly one direction — the model spends its whole
+ * budget thinking and returns nothing, with no error at all — so the screen must agree with what a
+ * call actually does, which means asking the same function the adapter asks.
+ */
+
+'use strict';
+
+const { reasoningFor } = require('./providers/lmx');
+
+/** Inside this window a certificate is worth mentioning: an expired pin fails at the handshake. */
+const EXPIRY_WARN_DAYS = 30;
+
+/** A gguf path is mostly directory. The file is the part that identifies the model. */
+function modelName(p) {
+  // The class carries BOTH separators. It lost its backslash once, to a tool that ate it, leaving a
+  // perfectly valid regex that splits on the one separator these stacks never use — and nothing
+  // failed, the name simply stayed long.
+  return p ? (String(p).split(/[\\/]/).pop() || null) : null;
+}
+
+/** How the flag would be sent, in the words an operator can compare to a config. */
+function reasoningLabel(model) {
+  const flag = reasoningFor(model);
+  if (!flag) return null;
+  if (flag.reasoning_effort) return `reasoning_effort: ${flag.reasoning_effort}`;
+  return 'enable_thinking: false';
+}
+
+/**
+ * One engine from the status document, with the two computed facts attached.
+ * The document's own fields are preserved untouched — this only ever adds.
+ */
+function describeEngine(e) {
+  if (!e) return e;
+  return Object.assign({}, e, {
+    modelName: modelName(e.model),
+    reasoning: e.reasoning || reasoningLabel(e.model) || null
+  });
+}
+
+/**
+ * Everything a stack panel needs, from what the app already has.
+ *
+ * @param {object} o
+ *   engines   the endpoint ROWS this app has adopted (from lmxStore.engines)
+ *   report    the last verification (from lmxVerify), or null if never checked
+ *   health    { [endpointId]: healthStatus } — optional, the app's own health snapshot
+ *   routes    { [endpointId]: [{ id, position }] } — optional, which jobs each endpoint serves
+ *   pin       the certificate summary from lmxVerify.readPin(), optional
+ */
+function describeStack(o = {}) {
+  const rows = o.engines || [];
+  const health = o.health || {};
+  const routes = o.routes || {};
+  const pin = o.pin || { present: false };
+
+  // NULL, NOT [] — "we never got a document" and "this stack has no engines" send an operator to
+  // completely different places, and only the first one means "press Check".
+  const reported = (o.report && o.report.engines) ? o.report.engines.map(describeEngine) : null;
+  const byName = new Map((reported || []).map((e) => [e.name, e]));
+
+  const added = rows.map((row) => ({
+    row,
+    engine: byName.get(row.lmx_engine) || null,
+    missing: !!reported && !byName.has(row.lmx_engine),
+    health: health[row.id] || null,
+    routes: routes[row.id] || []
+  }));
+
+  const available = (reported || []).filter((e) => !rows.some((r) => r.lmx_engine === e.name));
+
+  const activeCount = added
+    .filter((a) => Number(a.row.enabled) && a.engine && a.engine.state === 'healthy').length;
+  const drainingCount = added.filter((a) => a.engine && a.engine.state !== 'healthy').length;
+  const missingCount = added.filter((a) => a.missing).length;
+
+  return {
+    added,
+    available,
+    reported,
+    reportedCount: reported ? reported.length : null,
+    activeCount,
+    drainingCount,
+    missingCount,
+    // WHAT KEEPS A PANEL OPEN. Attention beats tidiness: a stack with any of these does not get to
+    // fold itself away, whatever a viewer chose to remember about it. A fold that honours a
+    // preference from last week and hides the thing that broke yesterday is worse than no fold.
+    attention: !!(missingCount
+      || pin.expired || pin.expiringSoon
+      || (o.report && !o.report.ok))
+  };
+}
+
+module.exports = { describeStack, describeEngine, modelName, reasoningLabel, EXPIRY_WARN_DAYS };

package/lmxStore.js

@@ -0,0 +1,188 @@
+/**
+ * The supervisors — one row per supervised inference stack this app can reach.
+ *
+ * ── A SUPERVISOR IS NOT A THING YOU SEND WORK TO ────────────────────────────────────────────────
+ * It is the thing that says WHERE the engines are. It holds one address, the status listener, and
+ * everything else about a stack — which engines exist, what they are running, which are healthy —
+ * comes from the live document rather than from here. That is the whole point: ports move, engines
+ * come and go, and a row that tried to remember any of it would go stale in silence.
+ *
+ * So this table deliberately has none of an endpoint's columns. No model, no token ceiling, no
+ * speed floor: a supervisor can never use them, and a column that can never be used is a question
+ * somebody will eventually answer.
+ *
+ * ── WHY IT IS A SEPARATE TABLE FROM THE ENDPOINTS ───────────────────────────────────────────────
+ * Because the two have different lifetimes and different identities. An engine row is an endpoint —
+ * something a route can name — and it points at a supervisor by id. Several engines share one
+ * supervisor, so one poller serves all of them; folding the supervisor's address into each engine
+ * row would mean N pollers for one stack, and N places for the certificate to disagree with itself.
+ *
+ * ── THE ID IS THE STACK'S OWN NAME ──────────────────────────────────────────────────────────────
+ * Not one the operator invents. It is compared against the `instance` the status document reports,
+ * and that comparison is the only thing standing between a mistyped URL and work being sent to
+ * another deployment — engine names collide across stacks, so `analysis` on the wrong machine
+ * answers perfectly plausibly. Which is why `update()` cannot change it.
+ *
+ * ── WHAT IS NOT HERE ────────────────────────────────────────────────────────────────────────────
+ * No token and no key. Those are credentials and belong in whatever secret store the app already
+ * has, exactly as with providerStore — this package never sees a credential at rest.
+ */
+
+'use strict';
+
+/** Columns a caller may set. `id` is the key and is never updated in place. */
+const FIELDS = ['label', 'status_url', 'poll_ms', 'stale_ms', 'enabled', 'sort_order'];
+
+const NUMERIC = new Set(['poll_ms', 'stale_ms', 'enabled', 'sort_order']);
+
+/**
+ * The same shape as an endpoint id, so a supervisor can appear in a URL and a log line unescaped.
+ *
+ * It must ALSO be what the stack calls itself, which is why the message says so: an id that is
+ * merely valid but does not match the document turns the identity check into a permanent failure
+ * that looks like a connection problem.
+ */
+function assertId(id) {
+  if (typeof id !== 'string' || !/^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$/.test(id)) {
+    throw new Error(
+      `lmx instance id ${JSON.stringify(id)} is not usable: 3-40 characters, lowercase letters, `
+      + 'digits and hyphens, not starting or ending with a hyphen. It must match the `instance` '
+      + 'the status document reports.'
+    );
+  }
+  return id;
+}
+
+/**
+ * @param {object} opts
+ *   driver          @aria-framework/db-worker driver contract (required)
+ *   table           default 'ai_lmx_instances'
+ *   providersTable  default 'ai_providers' — read by engines(), which is the join that makes a
+ *                   stack and its endpoints one object on screen
+ */
+function createLmxStore(opts = {}) {
+  const driver = opts.driver;
+  if (!driver || typeof driver.run !== 'function') {
+    throw new Error('createLmxStore({ driver }): the db-worker driver contract is required');
+  }
+  const table = opts.table || 'ai_lmx_instances';
+  const providers = opts.providersTable || 'ai_providers';
+
+  const clean = (p) => {
+    const out = {};
+    for (const f of FIELDS) {
+      if (p[f] === undefined) continue;
+      // null is MEANINGFUL for the two intervals: it means "use the package default", which is not
+      // the same as zero. Coercing it to 0 would set a poll interval of zero milliseconds.
+      if (p[f] === null && (f === 'poll_ms' || f === 'stale_ms')) { out[f] = null; continue; }
+      out[f] = NUMERIC.has(f) ? (Number(p[f]) || 0) : String(p[f]);
+    }
+    return out;
+  };
+
+  return {
+    table,
+
+    async all() {
+      return driver.all(`SELECT * FROM ${table} ORDER BY sort_order, id`);
+    },
+
+    /** Only the ones that may be used. A disabled supervisor stays configured but is never polled. */
+    async enabled() {
+      return driver.all(`SELECT * FROM ${table} WHERE enabled = 1 ORDER BY sort_order, id`);
+    },
+
+    async byId(id) {
+      if (typeof id !== 'string' || !id) return null;
+      return (await driver.get(`SELECT * FROM ${table} WHERE id = ?`, [id])) || null;
+    },
+
+    async create(p = {}) {
+      const id = assertId(p.id);
+      if (await this.byId(id)) throw new Error(`an lmx supervisor called ${JSON.stringify(id)} already exists`);
+      if (!p.status_url) throw new Error('an lmx supervisor needs the URL of its status listener');
+      const fields = clean(Object.assign({ label: p.id, enabled: 1, sort_order: 0 }, p));
+      const cols = ['id'].concat(Object.keys(fields));
+      const vals = [id].concat(Object.values(fields));
+      await driver.run(
+        `INSERT INTO ${table} (${cols.join(', ')}) VALUES (${cols.map(() => '?').join(', ')})`, vals);
+      return { id };
+    },
+
+    /**
+     * Update in place. THE ID IS NOT UPDATABLE, and that is load-bearing twice over: every engine
+     * row points at it, so a rename would orphan them all; and it is the value checked against the
+     * document, so a rename would silently disable the one guard that catches a status URL aimed at
+     * the wrong deployment.
+     */
+    async update(id, p = {}) {
+      if (!await this.byId(id)) throw new Error(`no lmx supervisor called ${JSON.stringify(id)}`);
+      const fields = clean(p);
+      const keys = Object.keys(fields);
+      if (!keys.length) return { changes: 0 };
+      const r = await driver.run(
+        `UPDATE ${table} SET ${keys.map((k) => `${k} = ?`).join(', ')} WHERE id = ?`,
+        Object.values(fields).concat([String(id)]));
+      return { changes: r.changes };
+    },
+
+    /**
+     * REFUSES WHILE ENGINES STILL POINT AT IT.
+     *
+     * Those rows would become endpoints whose address can never be resolved — still enabled, still
+     * listed in routes, failing every call. Cascading the delete instead would be worse: a job
+     * would quietly lose a step, and nobody chose that.
+     */
+    async remove(id) {
+      const engines = await this.engines(id);
+      if (engines.length) {
+        throw new Error(
+          `${engines.length} endpoint(s) still use the ${JSON.stringify(id)} supervisor `
+          + `(${engines.map((e) => e.id).join(', ')}). Remove or reassign them first — without it `
+          + 'their addresses cannot be resolved at all.'
+        );
+      }
+      const r = await driver.run(`DELETE FROM ${table} WHERE id = ?`, [String(id)]);
+      return { changes: r.changes };
+    },
+
+    /** The endpoint rows served by this supervisor — the join that groups a stack on screen. */
+    async engines(id) {
+      return driver.all(
+        `SELECT id, label, lmx_engine, enabled, sort_order FROM ${providers} `
+        + 'WHERE lmx_instance = ? ORDER BY sort_order, id', [String(id)]);
+    }
+  };
+}
+
+/**
+ * The DDL, in the caller's dialect.
+ *
+ * EXPORTED SO A CONSUMER CAN ASSERT ITS TABLE MATCHES — the same reason providerSchemaFor,
+ * usageSchemaFor and speedSchemaFor are exported. An app writes its own migration, that migration
+ * is a hand copy of this, and a copy with nothing comparing it to the original is a failure mode
+ * this repo has now documented three times. The first app to carry this table wrote it by hand with
+ * nothing to check it against; this is what stops the second one drifting from the first.
+ */
+function schemaFor(dialect) {
+  const t = dialect || { now: () => "datetime('now')" };
+  return `
+  -- The stack's OWN name, checked against the \`instance\` its status document reports. Not a label
+  -- somebody chose: engine names collide across deployments, so this comparison is the only thing
+  -- that catches a status URL pointed at the wrong machine.
+  id           TEXT    PRIMARY KEY,
+  label        TEXT,
+  -- The ONLY address stored anywhere for this stack. Engine addresses are discovered per call,
+  -- because ports move and a stored URL is the one thing the contract says not to keep.
+  status_url   TEXT    NOT NULL,
+  -- NULL means "use the package default" for both, which is not the same as 0 — a zero poll
+  -- interval is not a slower poll, it is a busy loop.
+  poll_ms      INTEGER,
+  stale_ms     INTEGER,
+  enabled      INTEGER NOT NULL DEFAULT 1,
+  sort_order   INTEGER NOT NULL DEFAULT 0,
+  created_at   TEXT    NOT NULL DEFAULT (${t.now()})
+`;
+}
+
+module.exports = { createLmxStore, schemaFor, _assertId: assertId, _fields: FIELDS };