@aria-framework/ai 0.3.0 → 0.5.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

@@ -175,6 +175,15 @@ module.exports = {
   // 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'),
+  /**
+   * Where this package's EJS partials live, for the consumer's view-roots list.
+   *
+   * Same contract as backup/server/notify/uploads: the package knows its own layout, the app
+   * puts its own views FIRST so a local file of the same name wins.
+   */
+  viewsDir: require('path').join(__dirname, 'views'),
   get providerSchemaFor() { return require('./providerStore').schemaFor; },
   get usageSchemaFor() { return require('./usageStore').schemaFor; },
   createAiClient,

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.3.0",
+  "version": "0.5.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", "providerStore.js"
+    "browser/ai-polish.js", "usageStore.js", "providerStore.js", "health.js", "views/"
   ],
   "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 && node test/providerStore.js"
+    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/health.js && node test/views.js"
   }
 }

package/views/ai/provider-card.ejs

@@ -0,0 +1,138 @@
+<%#
+  One provider: what it is, whether it works, and what it has cost.
+
+  LOCALS
+    p        a row from createProviderStore.all()
+    health   a status object from createHealthChecker.status(p.id) — may be undefined
+    usage    { calls, total_tokens } for the window, or undefined
+    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
+
+  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
+  multi-second reload. One green dot would hide the only fact worth knowing.
+-%>
+<%
+  const h = typeof health !== 'undefined' && health ? health : { status: 'unknown', failures: 0 };
+  const local = p.kind === 'lmstudio' || p.kind === 'openai-compatible';
+  const dot = !p.enabled ? 'secondary'
+    : h.status === 'down' ? 'danger'
+    : h.status === 'up' ? (h.modelPresent === false ? 'warning' : 'success')
+    : 'secondary';
+  const ago = (ts) => {
+    if (!ts) return null;
+    const s = Math.max(0, Math.round((Date.now() - ts) / 1000));
+    if (s < 60) return s + 's ago';
+    if (s < 3600) return Math.round(s / 60) + 'm ago';
+    if (s < 86400) return Math.round(s / 3600) + 'h ago';
+    return Math.round(s / 86400) + 'd ago';
+  };
+  const shared = (typeof routes !== 'undefined' && routes) ? routes : [];
+-%>
+<article class="card mb-3">
+  <div class="card-body d-flex flex-wrap gap-3 justify-content-between align-items-start">
+    <div class="flex-grow-1" style="min-width:18rem">
+
+      <div class="d-flex align-items-center gap-2 mb-1">
+        <span class="badge rounded-pill bg-<%= dot %>" style="width:.6rem;height:.6rem;padding:0"
+              aria-hidden="true"></span>
+        <strong class="fs-6"><%= p.id %></strong>
+        <span class="badge text-bg-light border"><%= p.kind %></span>
+        <% if (local) { %><span class="badge text-bg-light border">local</span><% } %>
+        <% if (!p.enabled) { %><span class="badge text-bg-secondary">disabled</span><% } %>
+        <% if (h.status === 'down') { %>
+          <span class="badge text-bg-danger">
+            down<%= h.cooldownRemainingMs ? ' · retrying in ' + Math.ceil(h.cooldownRemainingMs / 1000) + 's' : '' %>
+          </span>
+        <% } else if (h.modelPresent === false) { %>
+          <span class="badge text-bg-warning">model not loaded</span>
+        <% } %>
+      </div>
+
+      <div class="text-body-secondary small font-monospace mb-2">
+        <%= p.model || '(no chat model)' %><% if (p.embedding_model) { %> · <%= p.embedding_model %><% } %>
+        <% if (p.base_url) { %> · <%= p.base_url %><% } %>
+      </div>
+
+      <div class="d-flex flex-wrap gap-4 small">
+        <% if (p.context_tokens) { %>
+          <div><div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Context</div>
+            <span class="font-monospace"><%= Number(p.context_tokens).toLocaleString() %></span></div>
+        <% } %>
+        <% if (h.lastMs != null) { %>
+          <div><div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Latency</div>
+            <span class="font-monospace"><%= h.lastMs %> ms</span></div>
+        <% } %>
+        <% if (typeof usage !== 'undefined' && usage) { %>
+          <div><div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Calls</div>
+            <span class="font-monospace"><%= Number(usage.calls || 0).toLocaleString() %></span></div>
+          <div><div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Tokens</div>
+            <span class="font-monospace"><%= Number(usage.total_tokens || 0).toLocaleString() %></span></div>
+        <% } %>
+        <div>
+          <%# LAST GOOD, not just a dot. "last good 3h ago" tells a story a green light cannot. %>
+          <div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Last good</div>
+          <span class="font-monospace"><%= ago(h.lastGoodAt) || 'never' %></span>
+        </div>
+      </div>
+
+      <% if (p.daily_token_cap) { %>
+        <%
+          const spent = (typeof usage !== 'undefined' && usage) ? Number(usage.total_tokens || 0) : 0;
+          const pct = Math.min(100, Math.round((spent / Number(p.daily_token_cap)) * 100));
+        -%>
+        <div class="mt-3" style="max-width:26rem">
+          <div class="d-flex justify-content-between small text-body-secondary">
+            <span>Daily token cap</span>
+            <span class="font-monospace"><%= spent.toLocaleString() %> / <%= Number(p.daily_token_cap).toLocaleString() %></span>
+          </div>
+          <div class="progress" style="height:.4rem" role="progressbar" aria-valuenow="<%= pct %>"
+               aria-valuemin="0" aria-valuemax="100">
+            <div class="progress-bar bg-<%= pct >= 100 ? 'danger' : pct >= 80 ? 'warning' : 'success' %>"
+                 style="width:<%= pct %>%"></div>
+          </div>
+        </div>
+      <% } %>
+
+      <% if (h.status === 'down' && h.lastError) { %>
+        <div class="alert alert-danger d-flex gap-2 mt-3 mb-0 py-2">
+          <i class="bi bi-exclamation-triangle mt-1"></i>
+          <div class="small">
+            <strong>Marked down after <%= h.failures %> consecutive failure<%= h.failures === 1 ? '' : 's' %>.</strong>
+            Last error: <code><%= h.lastError %></code>. Calls skip this provider entirely rather than
+            paying its timeout, and it returns to service on the first success.
+          </div>
+        </div>
+      <% } else if (h.modelPresent === false) { %>
+        <div class="alert alert-warning d-flex gap-2 mt-3 mb-0 py-2">
+          <i class="bi bi-hourglass-split mt-1"></i>
+          <div class="small">
+            <strong>Reachable, but <code><%= p.model %></code> is not loaded.</strong>
+            The next call pays a reload before it does anything. This is not a failure and nothing
+            fails over — but if it keeps happening, turn off automatic model unloading on the server.
+          </div>
+        </div>
+      <% } %>
+
+      <% if (shared.length > 1) { %>
+        <div class="alert alert-warning d-flex gap-2 mt-3 mb-0 py-2">
+          <i class="bi bi-diagram-3 mt-1"></i>
+          <div class="small">
+            <strong>Serves <%= shared.length %> routes.</strong>
+            <%= shared.map((r) => r.id + ' (' + (r.position === 0 ? 'primary' : 'fallback') + ')').join(', ') %>.
+            If it goes down, one route fails over <em>and</em> another loses its safety net at the
+            same moment.
+          </div>
+        </div>
+      <% } %>
+    </div>
+
+    <div class="d-flex flex-column gap-2 align-items-end">
+      <% if (typeof canEdit !== 'undefined' && canEdit) { %>
+        <button class="btn btn-sm btn-outline-secondary" name="test_provider" value="<%= p.id %>">Test</button>
+        <a class="btn btn-sm btn-outline-secondary" href="?edit=<%= encodeURIComponent(p.id) %>">Edit</a>
+      <% } %>
+    </div>
+  </div>
+</article>

package/views/ai/usage-table.ejs

@@ -0,0 +1,58 @@
+<%#
+  Per-provider usage over a window.
+
+  LOCALS
+    rows    from createUsageStore.byProvider(sinceDay) — [{provider, model, calls, ...}]
+    prices  optional { [model]: costPerMillionTokens } supplied BY THE APP. Prices change, and
+            a stale hardcoded price silently produces confidently wrong cost reports, so the
+            package never carries one.
+    kinds   optional { [providerId]: kind } so a local endpoint can be shown as having no cost
+            rather than a cost of zero — different facts.
+-%>
+<%
+  const priceFor = (m) => (typeof prices !== 'undefined' && prices && prices[m] != null) ? Number(prices[m]) : null;
+  const kindOf = (id) => (typeof kinds !== 'undefined' && kinds) ? kinds[id] : undefined;
+  const isLocal = (id) => ['lmstudio', 'openai-compatible'].includes(kindOf(id));
+  const n = (v) => Number(v || 0).toLocaleString();
+-%>
+<div class="table-responsive">
+  <table class="table table-sm align-middle mb-0">
+    <thead>
+      <tr class="small text-body-secondary text-uppercase">
+        <th>Provider</th><th>Model</th>
+        <th class="text-end">Calls</th><th class="text-end">Prompt</th>
+        <th class="text-end">Completion</th><th class="text-end">Total</th><th class="text-end">Cost</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% if (!rows || !rows.length) { %>
+        <tr><td colspan="7" class="text-body-secondary py-3">Nothing recorded in this window.</td></tr>
+      <% } %>
+      <% (rows || []).forEach(function (r) {
+           const price = priceFor(r.model);
+           const cost = price == null ? null : (Number(r.total_tokens || 0) / 1e6) * price;
+      -%>
+        <tr>
+          <td><%= r.provider %></td>
+          <td class="font-monospace small"><%= r.model %></td>
+          <td class="text-end font-monospace"><%= n(r.calls) %></td>
+          <td class="text-end font-monospace"><%= n(r.prompt_tokens) %></td>
+          <td class="text-end font-monospace"><%= n(r.completion_tokens) %></td>
+          <td class="text-end font-monospace"><%= n(r.total_tokens) %></td>
+          <td class="text-end font-monospace">
+            <%# A local GPU has NO cost, which is a different fact from a cost of zero. Showing
+                "0.00" would invite someone to compare it against a cloud row as if it were cheap. %>
+            <% if (isLocal(r.provider)) { %><span class="text-body-secondary">&mdash;</span>
+            <% } else if (cost == null) { %><span class="text-body-secondary" title="No price configured for this model">?</span>
+            <% } else { %><%= cost.toFixed(2) %><% } %>
+          </td>
+        </tr>
+      <% }); -%>
+    </tbody>
+  </table>
+</div>
+<p class="small text-body-secondary mt-2 mb-0">
+  Tokens are recorded for every call, including local models. Cost is derived from tokens and the
+  price table this app supplies &mdash; never stored &mdash; so a local endpoint still reports real
+  numbers, just different ones: throughput and utilisation rather than spend.
+</p>