@aria-framework/ai 0.2.0 → 0.4.0

package/health.js

@@ -0,0 +1,219 @@
+/**
+ * Is a provider actually usable right now — and if not, why not.
+ *
+ * NOTHING IN ANY APP DOES THIS TODAY. A provider is configured and then discovered to be broken by
+ * a user pressing a button, which is the worst possible detector: it is slow, it is intermittent,
+ * and the person who finds out is the person least able to fix it.
+ *
+ * ── "UP" AND "LOADED" ARE DIFFERENT FAILURES ────────────────────────────────────────────────────
+ * The distinction most tools collapse into one green dot, and the one that matters most for a local
+ * model server. LM Studio will happily answer `/models` while the model itself has been evicted —
+ * the server is up, and the next completion pays a multi-second reload before it does anything.
+ * Reporting that as "healthy" hides the only fact worth knowing. So `reachable` and `modelPresent`
+ * are separate, and the UI shows them separately.
+ *
+ * `modelPresent` is NULL, not false, where residency has no meaning — a hosted API does not load
+ * models on demand, and flagging one as "not resident" would be a false alarm on a working
+ * provider. Null means "not applicable", false means "we asked and it is not there".
+ *
+ * ── THE CIRCUIT BREAKER IS WHY THIS IS NOT JUST A PING ──────────────────────────────────────────
+ * Without one, every call to a dead provider pays the full timeout before failing over. Annoying at
+ * helpdesk volume; fatal at log-triage volume, where it adds the timeout to every request in the
+ * queue. After N consecutive failures a provider is marked down and calls skip it entirely until a
+ * cooldown expires; one success clears it.
+ *
+ * STATE IS IN MEMORY, deliberately. A restart re-probes, which is correct — knowledge of what was
+ * down five minutes before a restart is not knowledge worth acting on, and persisting it would mean
+ * booting into a breaker that trips on stale evidence. `snapshot()` exposes it for an app that
+ * wants to render "last good 3h ago" across a restart; nothing here requires that.
+ */
+
+'use strict';
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+/** Kinds that load models on demand, where residency is a real question. */
+const RESIDENT_KINDS = new Set(['lmstudio', 'openai-compatible']);
+
+/** Strip a trailing slash so `${base}/models` never becomes `//models`. */
+const apiRoot = (baseUrl) => String(baseUrl || '').replace(/\/+$/, '');
+
+/**
+ * The default probe: ask the endpoint what models it has.
+ *
+ * Distinguishes three outcomes that `listModels()` collapses into an empty array — it returns []
+ * for a dead host and [] for a live host with nothing loaded, which is exactly the difference this
+ * module exists to report.
+ */
+async function defaultProbe(cfg, { fetchImpl = fetch, timeoutMs } = {}) {
+  const url = `${apiRoot(cfg.baseUrl)}/models`;
+  const started = Date.now();
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      headers: cfg.apiKey ? { Authorization: `Bearer ${cfg.apiKey}` } : {},
+      signal: AbortSignal.timeout(timeoutMs || cfg.timeoutMs || DEFAULT_TIMEOUT_MS)
+    });
+  } catch (e) {
+    // No answer at all: refused, DNS, TLS, or the timeout fired.
+    const timedOut = e && (e.name === 'TimeoutError' || e.name === 'AbortError');
+    // `e.message` is a bare "fetch failed" for every connection-level problem — measured against a
+    // closed port. Useless to an operator: refused, DNS and TLS all read identically. The reason
+    // lives in `e.cause.code`, so lead with that and keep the message as context.
+    const cause = (e && e.cause) || {};
+    const detail = cause.code || (e && e.message) || 'unreachable';
+    return {
+      reachable: false, models: [], ms: Date.now() - started,
+      error: timedOut
+        ? `no response within ${timeoutMs || cfg.timeoutMs || DEFAULT_TIMEOUT_MS}ms`
+        : (cause.code ? `${cause.code}${cause.message ? ' — ' + cause.message : ''}` : detail)
+    };
+  }
+  const ms = Date.now() - started;
+  if (!res.ok) {
+    // It ANSWERED, so the host is reachable — the failure is auth, quota or a bad path, and saying
+    // "unreachable" would send an operator to check the network instead of the key.
+    return { reachable: true, models: [], ms, error: `HTTP ${res.status}` };
+  }
+  let payload = null;
+  try { payload = await res.json(); } catch (_) { payload = null; }
+  const models = Array.isArray(payload && payload.data)
+    ? payload.data.map((m) => (m && (m.id || m.name)) || '').filter(Boolean)
+    : [];
+  return { reachable: true, models, ms, error: null };
+}
+
+/**
+ * @param {object} opts
+ *   probe             async (cfg) => {reachable, models, ms, error}. Default: GET {baseUrl}/models
+ *   now               () => number, epoch ms. Injected so tests need no timers.
+ *   cooldownMs        how long a provider stays skipped after tripping. Default 60_000.
+ *   failureThreshold  consecutive failures before it trips. Default 3.
+ */
+function createHealthChecker(opts = {}) {
+  const probe = typeof opts.probe === 'function' ? opts.probe : defaultProbe;
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+  const cooldownMs = Number(opts.cooldownMs) || 60000;
+  const threshold = Math.max(1, Number(opts.failureThreshold) || 3);
+
+  /** id -> { failures, downUntil, lastGoodAt, lastError, lastMs, lastCheckedAt, modelPresent } */
+  const state = new Map();
+  const entry = (id) => {
+    if (!state.has(id)) {
+      state.set(id, {
+        failures: 0, downUntil: 0, lastGoodAt: null,
+        lastError: null, lastMs: null, lastCheckedAt: null, modelPresent: null
+      });
+    }
+    return state.get(id);
+  };
+
+  /** Fold one outcome into the breaker. Exposed because a real CALL is better evidence than a probe. */
+  function report(id, ok, info = {}) {
+    const e = entry(id);
+    e.lastCheckedAt = now();
+    if (info.ms != null) e.lastMs = info.ms;
+    if (ok) {
+      e.failures = 0;
+      e.downUntil = 0;
+      e.lastGoodAt = now();
+      e.lastError = null;
+    } else {
+      e.failures += 1;
+      e.lastError = info.error || 'failed';
+      // Trip on the Nth failure and re-arm the cooldown on every failure after it, so a provider
+      // that keeps failing its probe is not retried the instant the first cooldown lapses.
+      if (e.failures >= threshold) e.downUntil = now() + cooldownMs;
+    }
+    return e;
+  }
+
+  return {
+    /**
+     * Is this provider currently being skipped?
+     *
+     * The question a router asks before spending a timeout. Note it does NOT probe — a breaker
+     * that probes on every check is the timeout cost it was built to avoid.
+     */
+    isDown(id) {
+      const e = state.get(id);
+      return !!(e && e.downUntil && now() < e.downUntil);
+    },
+
+    /** Milliseconds until a downed provider is eligible again; 0 when it is not down. */
+    cooldownRemaining(id) {
+      const e = state.get(id);
+      if (!e || !e.downUntil) return 0;
+      return Math.max(0, e.downUntil - now());
+    },
+
+    report,
+
+    /**
+     * Probe one provider and fold the result into the breaker.
+     *
+     * @param {object} cfg  a resolved provider config (see providerStore.resolve)
+     * @returns {{id, ok, reachable, modelPresent, models, ms, error, checkedAt}}
+     */
+    async check(cfg) {
+      const id = cfg.id || cfg.provider || 'unknown';
+      if (cfg.enabled === false) {
+        return {
+          id, ok: false, reachable: null, modelPresent: null, models: [], ms: 0,
+          error: 'disabled', checkedAt: now()
+        };
+      }
+
+      const r = await probe(cfg);
+      // Residency only means something where models are loaded on demand.
+      let modelPresent = null;
+      if (RESIDENT_KINDS.has(cfg.provider) && r.reachable && !r.error) {
+        modelPresent = cfg.model ? r.models.includes(cfg.model) : null;
+      }
+
+      // REACHABLE BUT NOT LOADED IS NOT A FAILURE. The call will still succeed; it will just be
+      // slow while the server loads the model. Tripping the breaker here would fail over away from
+      // a provider that works, which is worse than the latency it was avoiding.
+      const ok = r.reachable && !r.error;
+      const e = report(id, ok, r);
+      e.modelPresent = modelPresent;
+
+      return {
+        id, ok, reachable: r.reachable, modelPresent, models: r.models,
+        ms: r.ms, error: r.error, checkedAt: e.lastCheckedAt
+      };
+    },
+
+    /** Everything the UI needs for one provider, without probing. */
+    status(id) {
+      const e = state.get(id);
+      if (!e) return { id, status: 'unknown', failures: 0 };
+      const down = !!(e.downUntil && now() < e.downUntil);
+      return {
+        id,
+        status: down ? 'down' : (e.lastGoodAt ? 'up' : 'unknown'),
+        failures: e.failures,
+        lastGoodAt: e.lastGoodAt,
+        lastError: e.lastError,
+        lastMs: e.lastMs,
+        lastCheckedAt: e.lastCheckedAt,
+        modelPresent: e.modelPresent,
+        cooldownRemainingMs: down ? e.downUntil - now() : 0
+      };
+    },
+
+    /** All known state, for persisting across a restart if an app wants to. */
+    snapshot() {
+      const out = {};
+      for (const id of state.keys()) out[id] = this.status(id);
+      return out;
+    },
+
+    /** Forget everything — used by tests and by "recheck now" in a UI. */
+    reset(id) {
+      if (id) state.delete(id); else state.clear();
+    }
+  };
+}
+
+module.exports = { createHealthChecker, defaultProbe, RESIDENT_KINDS };

package/index.js

@@ -174,6 +174,10 @@ module.exports = {
   // 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 createProviderStore() { return require('./providerStore').createProviderStore; },
+  // No database behind health, so it loads eagerly like the rest of the seam.
+  ...require('./health'),
+  get providerSchemaFor() { return require('./providerStore').schemaFor; },
   get usageSchemaFor() { return require('./usageStore').schemaFor; },
   createAiClient,
   PROVIDERS, DEFAULTS,

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.2.0",
+  "version": "0.4.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -16,7 +16,7 @@
     "generate.js",
     "providers/openai-compatible.js",
     "providers/anthropic.js",
-    "browser/ai-polish.js", "usageStore.js"
+    "browser/ai-polish.js", "usageStore.js", "providerStore.js", "health.js"
   ],
   "peerDependencies": {
     "@aria-framework/db-worker": ">=0.7.0"
@@ -25,6 +25,6 @@
     "@aria-framework/db-worker": { "optional": true }
   },
   "scripts": {
-    "test": "node test/smoke.js && node test/usageStore.js"
+    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/health.js"
   }
 }

package/providerStore.js

@@ -0,0 +1,200 @@
+/**
+ * The provider registry — every endpoint the app can talk to, configured once.
+ *
+ * WHY THIS EXISTS. Support101's AI settings page is one flat form with eleven fields describing a
+ * single provider, and nine of those eleven are really per-endpoint. That shape collapses the
+ * moment a second endpoint exists, which is what a backup provider is. The fix is not a
+ * `backup_base_url` beside every field — that is the same form doubled, and it caps at two.
+ *
+ * A PROVIDER IS AN ENDPOINT, not a job. It has a connection, a model or two, capability limits and
+ * its own spend guard, and it can be health-checked. Routes reference providers by id, so one
+ * endpoint can be one route's primary and another's fallback without being configured twice.
+ *
+ * ── THE ID IS THE OPERATOR'S ────────────────────────────────────────────────────────────────────
+ * `local-fast`, `gpu-box-1`, whatever they like. NO CALL SITE EVER NAMES A PROVIDER — code names a
+ * route, the operator decides what serves it. That is the whole reason failover is possible, and
+ * it means renaming a provider must break nothing.
+ *
+ * ── ONE ENDPOINT CAN SERVE CHAT AND EMBEDDINGS ──────────────────────────────────────────────────
+ * `model` and `embedding_model` are separate columns on the SAME row because that is how the
+ * servers actually work: one LM Studio instance answers both. Splitting them into two provider
+ * rows would duplicate the connection, and then its health twice. A chat route reads `model`, an
+ * embedding route reads `embedding_model`.
+ *
+ * ── THE API KEY IS NOT IN THIS TABLE ────────────────────────────────────────────────────────────
+ * It lives in whatever secret store the app already has — Support101 keeps it in an encrypted
+ * credentials database beside its Entra secret. So `secrets` is INJECTED, the package never sees a
+ * credential at rest, and `resolve()` is the only thing that pulls one. Keys are write-only from
+ * the UI's point of view: there is no read-back, because a lost LLM key is rotated at the
+ * provider, not recovered.
+ */
+
+'use strict';
+
+/** Columns the caller may set. `id` is separate — it is the key and is never updated in place. */
+const FIELDS = [
+  'label', 'kind', 'base_url', 'model', 'embedding_model',
+  'context_tokens', 'max_tokens', 'timeout_ms', 'daily_token_cap', 'enabled', 'sort_order'
+];
+
+const NUMERIC = new Set(['context_tokens', 'max_tokens', 'timeout_ms', 'daily_token_cap', 'enabled', 'sort_order']);
+
+/** An id an operator typed, constrained so it can appear in a URL and a log line unescaped. */
+function assertId(id) {
+  if (typeof id !== 'string' || !/^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$/.test(id)) {
+    throw new Error(
+      `provider id ${JSON.stringify(id)} is not usable: 3-40 characters, lowercase letters, ` +
+      'digits and hyphens, not starting or ending with a hyphen.'
+    );
+  }
+  return id;
+}
+
+/**
+ * @param {object} opts
+ *   driver     @aria-framework/db-worker driver contract (required)
+ *   table      default 'ai_providers'
+ *   secrets    { get(id) => Promise<string> } — the app's credential store. Optional; without it
+ *              resolve() returns an empty apiKey, which is correct for local endpoints.
+ *   defaults   { [kind]: { baseUrl, model, label } } — the package's PROVIDER DEFAULTS, so a row
+ *              may leave base_url or model blank and still resolve to something usable.
+ */
+function createProviderStore(opts = {}) {
+  const driver = opts.driver;
+  if (!driver || typeof driver.run !== 'function') {
+    throw new Error('createProviderStore({ driver }): the db-worker driver contract is required');
+  }
+  const table = opts.table || 'ai_providers';
+  const secrets = opts.secrets || null;
+  const defaults = opts.defaults || {};
+
+  const clean = (p) => {
+    const out = {};
+    for (const f of FIELDS) {
+      if (p[f] === undefined) continue;
+      out[f] = NUMERIC.has(f) ? (Number(p[f]) || 0) : (p[f] == null ? null : String(p[f]));
+    }
+    return out;
+  };
+
+  return {
+    table,
+
+    /** Every provider, in the operator's chosen order. */
+    async all() {
+      return driver.all(`SELECT * FROM ${table} ORDER BY sort_order, id`);
+    },
+
+    /** Only the ones that may be used. A disabled provider stays configured but is never called. */
+    async enabled() {
+      return driver.all(`SELECT * FROM ${table} WHERE enabled = 1 ORDER BY sort_order, id`);
+    },
+
+    async byId(id) {
+      return driver.get(`SELECT * FROM ${table} WHERE id = ?`, [String(id)]);
+    },
+
+    async create(p = {}) {
+      const id = assertId(p.id);
+      if (await this.byId(id)) throw new Error(`a provider called ${JSON.stringify(id)} already exists`);
+      if (!p.kind) throw new Error('a provider needs a kind (the adapter that talks to it)');
+      const fields = clean(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 here on purpose: routes reference providers by id,
+     * so renaming one would silently orphan every chain that points at it. A rename is a create
+     * plus a repoint plus a delete, which is a deliberate act rather than a typo in a text field.
+     */
+    async update(id, p = {}) {
+      const existing = await this.byId(id);
+      if (!existing) throw new Error(`no provider 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 };
+    },
+
+    async remove(id) {
+      const r = await driver.run(`DELETE FROM ${table} WHERE id = ?`, [String(id)]);
+      return { changes: r.changes };
+    },
+
+    /**
+     * Everything needed to make a call, in the shape createAiClient's `resolveConfig` returns.
+     *
+     * This is the seam that makes adoption a swap rather than a rewrite: an app whose getConfig()
+     * read eleven settings keys can point at this instead and change nothing else.
+     *
+     * @param {string} id
+     * @param {{embedding?: boolean}} o  resolve the EMBEDDING model rather than the chat one
+     */
+    async resolve(id, o = {}) {
+      const row = await this.byId(id);
+      if (!row) return { provider: 'off', enabled: false, missing: String(id) };
+      if (!row.enabled) return { provider: 'off', enabled: false, disabled: String(id) };
+
+      const d = defaults[row.kind] || {};
+      let apiKey = '';
+      if (secrets && typeof secrets.get === 'function') {
+        // A credential store that is locked or unavailable must not take the whole call down with
+        // an exception — a local endpoint needs no key at all, and the adapter's own auth failure
+        // is a better error than "the keychain was busy".
+        try { apiKey = (await secrets.get(row.id)) || ''; } catch (_) { apiKey = ''; }
+      }
+
+      return {
+        enabled: true,
+        id: row.id,
+        provider: row.kind,
+        label: row.label || d.label || row.id,
+        baseUrl: row.base_url || d.baseUrl || '',
+        model: (o.embedding ? row.embedding_model : row.model) || (o.embedding ? '' : d.model) || '',
+        embeddingModel: row.embedding_model || '',
+        apiKey,
+        timeoutMs: Number(row.timeout_ms) || 60000,
+        maxTokens: Number(row.max_tokens) || 1024,
+        contextTokens: Number(row.context_tokens) || 8192,
+        dailyTokenCap: Number(row.daily_token_cap) || 0
+      };
+    }
+  };
+}
+
+/**
+ * The DDL, in the caller's dialect.
+ *
+ * `id` is TEXT and the primary key rather than an autoincrement integer, because it is the name an
+ * operator types and the thing routes reference. A surrogate key would mean routes pointed at
+ * numbers nobody recognises in a config screen.
+ */
+function schemaFor(dialect) {
+  const t = dialect || { now: () => "datetime('now')" };
+  return `
+  id                TEXT    PRIMARY KEY,
+  label             TEXT,
+  kind              TEXT    NOT NULL,
+  base_url          TEXT,
+  model             TEXT,
+  embedding_model   TEXT,
+  context_tokens    INTEGER NOT NULL DEFAULT 0,
+  max_tokens        INTEGER NOT NULL DEFAULT 0,
+  timeout_ms        INTEGER NOT NULL DEFAULT 0,
+  -- Per PROVIDER, not global: a ceiling is meaningless on a GPU you already own, and the whole
+  -- point of a cheap cloud fallback is capping what it may spend while the primary is down.
+  daily_token_cap   INTEGER NOT NULL DEFAULT 0,
+  enabled           INTEGER NOT NULL DEFAULT 1,
+  sort_order        INTEGER NOT NULL DEFAULT 0,
+  created_at        TEXT    NOT NULL DEFAULT (${t.now()})
+`;
+}
+
+module.exports = { createProviderStore, schemaFor, _assertId: assertId };

package/usageStore.js

@@ -36,10 +36,13 @@
  * 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.
+ * The SCOPE column and its foreign key. Support101 scopes by `ticket_id REFERENCES tickets(id)
+ * ON DELETE SET NULL` — deleting a ticket KEEPS the usage row and forgets which ticket it belonged
+ * to, so the spend history survives the thing it was spent on. (An earlier draft of this comment
+ * said CASCADE, which would have been the opposite and wrong: erasing a ticket would erase the
+ * record that its budget was ever consumed.) That is real behaviour a generic column could not
+ * carry, and app 3 will scope by incident instead. So the package is told the column NAME and the
+ * app owns the column, its type and its constraints.
  */
 
 'use strict';