@aria-framework/ai 0.5.0 → 0.8.0

package/health.js

@@ -12,9 +12,19 @@
  * 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".
+ * `modelPresent` is NULL, not false, whenever the answer is not KNOWN — a hosted API does not load
+ * models on demand, and a server that cannot report load state must not be guessed at. Null means
+ * "cannot tell", false means "we asked something that knows, and it said no".
+ *
+ * ── /v1/models CANNOT ANSWER THIS, WHICH TOOK REAL HARDWARE TO FIND ─────────────────────────────
+ * Measured against a live LM Studio: `/v1/models` returned FIVE models with keys `id, object,
+ * owned_by`, while only TWO were actually resident. It lists what is DOWNLOADED, not what is
+ * LOADED — so residency judged from it reports "loaded" for every model on the disk, and the
+ * evicted-model warning this module exists for could never fire at all.
+ *
+ * LM Studio's native `/api/v0/models` carries a `state` field (`loaded` / `not-loaded`), which is
+ * the real signal. So the probe asks that FIRST for kinds that load on demand, and falls back to
+ * `/v1/models` purely for reachability — reporting residency as null rather than inventing it.
  *
  * ── 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
@@ -35,8 +45,19 @@ 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 ADAPTER'S root, not a second one.
+ *
+ * This file originally rolled its own — strip the trailing slash and append `/models` — which is
+ * wrong for the base URL people actually type. `http://host:1234` has no path, so the adapter adds
+ * `/v1`; the probe did not, and asked for `/models`. LM Studio answers that with
+ * "Unexpected endpoint or method. Returning 200 anyway" — a 200 with no model list — so the probe
+ * saw an empty listing and reported a perfectly loaded model as EVICTED, on a server that was
+ * answering completions the whole time.
+ *
+ * Two roots that disagree about where the API lives is a bug waiting to happen twice. There is one.
+ */
+const { apiRoot } = require('./providers/openai-compatible');
 
 /**
  * The default probe: ask the endpoint what models it has.
@@ -45,6 +66,39 @@ const apiRoot = (baseUrl) => String(baseUrl || '').replace(/\/+$/, '');
  * for a dead host and [] for a live host with nothing loaded, which is exactly the difference this
  * module exists to report.
  */
+/**
+ * LM Studio's native model list, which reports LOAD STATE.
+ *
+ * Returns null when the endpoint is not there (any other server), so the caller falls back rather
+ * than treating its absence as a failure.
+ */
+async function nativeResidency(cfg, fetchImpl, signalMs) {
+  // The native API sits beside the OpenAI-compatible one, not under /v1.
+  let base;
+  try {
+    const u = new URL(String(cfg.baseUrl || ''));
+    base = `${u.protocol}//${u.host}`;
+  } catch (_) { return null; }
+
+  try {
+    const res = await fetchImpl(`${base}/api/v0/models`, {
+      headers: cfg.apiKey ? { Authorization: `Bearer ${cfg.apiKey}` } : {},
+      signal: AbortSignal.timeout(signalMs)
+    });
+    if (!res.ok) return null;
+    const payload = await res.json();
+    if (!Array.isArray(payload && payload.data)) return null;
+    const loaded = payload.data
+      .filter((m) => m && m.state === 'loaded')
+      .map((m) => m.id || m.key || '')
+      .filter(Boolean);
+    // An empty `data` is a real answer (nothing loaded); a missing one was handled above.
+    return { loaded, all: payload.data.map((m) => (m && m.id) || '').filter(Boolean) };
+  } catch (_) {
+    return null;
+  }
+}
+
 async function defaultProbe(cfg, { fetchImpl = fetch, timeoutMs } = {}) {
   const url = `${apiRoot(cfg.baseUrl)}/models`;
   const started = Date.now();
@@ -62,25 +116,47 @@ async function defaultProbe(cfg, { fetchImpl = fetch, timeoutMs } = {}) {
     // 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';
+    // NAME THE URL. Nothing normalises a base URL any more, so a wrong one is a real possibility
+    // and the operator's first question is "what did it actually call". `ECONNREFUSED` alone sends
+    // them to check the server; `ECONNREFUSED at http://host:1234/models` shows them the typo.
+    const reason = timedOut
+      ? `no response within ${timeoutMs || cfg.timeoutMs || DEFAULT_TIMEOUT_MS}ms`
+      : (cause.code ? `${cause.code}${cause.message ? ' — ' + cause.message : ''}` : detail);
     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)
+      reachable: false, listed: false, models: [], loaded: null, ms: Date.now() - started,
+      url, error: `${reason} (${url})`
     };
   }
   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}` };
+    return { reachable: true, listed: false, models: [], loaded: null, ms, url, error: `HTTP ${res.status} (${url})` };
   }
   let payload = null;
   try { payload = await res.json(); } catch (_) { payload = null; }
-  const models = Array.isArray(payload && payload.data)
+
+  // "A 200 THAT IS NOT A MODEL LISTING" IS NOT "NO MODELS LOADED".
+  //
+  // Servers answer 200 to things they do not implement — LM Studio logs
+  // "Unexpected endpoint or method. Returning 200 anyway" and returns a body with no `data`.
+  // Treating that as an empty list makes a loaded model look evicted, which is the exact false
+  // alarm this module exists to avoid. So `listed` says whether a real listing came back, and
+  // residency is only judged when it did.
+  const listed = Array.isArray(payload && payload.data);
+  const models = listed
     ? payload.data.map((m) => (m && (m.id || m.name)) || '').filter(Boolean)
     : [];
-  return { reachable: true, models, ms, error: null };
+
+  // Now ask something that actually knows about residency. Only for kinds that load on demand,
+  // and only as an addition — a server without it still reports reachable, with residency null.
+  let loaded = null;
+  if (RESIDENT_KINDS.has(cfg.provider)) {
+    const native = await nativeResidency(cfg, fetchImpl, timeoutMs || cfg.timeoutMs || DEFAULT_TIMEOUT_MS);
+    if (native) loaded = native.loaded;
+  }
+
+  return { reachable: true, listed, models, loaded, ms, url, error: null };
 }
 
 /**
@@ -96,23 +172,38 @@ function createHealthChecker(opts = {}) {
   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
+        lastError: null, lastMs: null, lastCheckedAt: null, modelPresent: null,
+        // The last few completions, for throughput. A window rather than a single value because
+        // one reload spike would otherwise define the number an operator plans capacity from.
+        samples: []
       });
     }
     return state.get(id);
   };
 
+  /** How many completions to average throughput over. Small enough to still track a real change. */
+  const WINDOW = 10;
+
   /** 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;
+
+    // THROUGHPUT, and what it honestly measures: completion tokens divided by the WHOLE call, so
+    // it includes prompt processing, queueing and the network. That is not the model's raw
+    // generation speed — separating those would need time-to-first-token, which no adapter
+    // reports — but it is what the caller actually experienced, which is the number worth planning
+    // against. Only completions count; a health probe generates no tokens and would drag it to 0.
+    if (ok && info.tokens > 0 && info.ms > 0) {
+      e.samples.push({ tokens: info.tokens, ms: info.ms });
+      if (e.samples.length > WINDOW) e.samples.shift();
+    }
     if (ok) {
       e.failures = 0;
       e.downUntil = 0;
@@ -166,9 +257,13 @@ function createHealthChecker(opts = {}) {
 
       const r = await probe(cfg);
       // Residency only means something where models are loaded on demand.
+      // RESIDENCY COMES FROM `loaded`, NEVER FROM THE MODEL LIST. `/v1/models` reports what is
+      // downloaded; judging residency from it says "loaded" for every model on the disk. Null
+      // whenever nothing authoritative answered — an unknown is honest, a guess is not.
       let modelPresent = null;
-      if (RESIDENT_KINDS.has(cfg.provider) && r.reachable && !r.error) {
-        modelPresent = cfg.model ? r.models.includes(cfg.model) : null;
+      if (RESIDENT_KINDS.has(cfg.provider) && r.reachable && !r.error
+          && Array.isArray(r.loaded) && cfg.model) {
+        modelPresent = r.loaded.includes(cfg.model);
       }
 
       // REACHABLE BUT NOT LOADED IS NOT A FAILURE. The call will still succeed; it will just be
@@ -187,7 +282,15 @@ function createHealthChecker(opts = {}) {
     /** Everything the UI needs for one provider, without probing. */
     status(id) {
       const e = state.get(id);
-      if (!e) return { id, status: 'unknown', failures: 0 };
+      // The same SHAPE for an unseen provider, so a caller never has to tell `undefined` (this key
+      // does not exist here) from `null` (we do not know yet) — they mean the same thing to a view.
+      if (!e) {
+        return {
+          id, status: 'unknown', failures: 0, lastGoodAt: null, lastError: null, lastMs: null,
+          lastCheckedAt: null, modelPresent: null, tokensPerSec: null, samples: 0,
+          cooldownRemainingMs: 0
+        };
+      }
       const down = !!(e.downUntil && now() < e.downUntil);
       return {
         id,
@@ -198,6 +301,14 @@ function createHealthChecker(opts = {}) {
         lastMs: e.lastMs,
         lastCheckedAt: e.lastCheckedAt,
         modelPresent: e.modelPresent,
+        // NULL until something has actually generated tokens. Reporting 0 tok/s for a provider
+        // nobody has used yet reads as "it is slow" rather than "we do not know".
+        tokensPerSec: e.samples.length
+          ? Math.round(
+            e.samples.reduce((n, x) => n + x.tokens, 0)
+            / (e.samples.reduce((n, x) => n + x.ms, 0) / 1000))
+          : null,
+        samples: e.samples.length,
         cooldownRemainingMs: down ? e.downUntil - now() : 0
       };
     },

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

package/providers/openai-compatible.js

@@ -251,15 +251,29 @@ async function httpError(res, label, apiKey) {
  * left alone, because other servers in this family mount elsewhere (LiteLLM behind a prefix, for
  * one) and second-guessing an explicit path would break them.
  */
+/**
+ * The configured base URL, with a trailing slash trimmed. Nothing else.
+ *
+ * IT USED TO APPEND `/v1` WHEN THE URL HAD NO PATH, and that was wrong for reasons that only got
+ * clearer the more providers there were:
+ *
+ *   - the stored value and the called value differed, so the form did not show what went on the
+ *     wire;
+ *   - it cannot generalise. One provider wants `/v1`, another `/api/v1`, another nothing at all.
+ *     A blanket rule is wrong for every provider it was not written for, and there is no way to
+ *     know which is which;
+ *   - it turned a typo into a SILENT wrong answer that surfaced three layers away. A base URL
+ *     missing `/v1` still completed chats — because this quietly fixed it — while the health probe
+ *     asked a path LM Studio answers with "Unexpected endpoint, returning 200 anyway", and a
+ *     perfectly loaded model was reported as evicted.
+ *
+ * So: call exactly what was configured. A wrong URL now fails immediately and says which URL it
+ * called, which is a configuration error an operator can act on rather than a mystery.
+ *
+ * Trailing-slash trimming stays because it changes no meaning — it only prevents `//models`.
+ */
 function apiRoot(baseUrl) {
-  const trimmed = String(baseUrl || '').replace(/\/+$/, '');
-  let path;
-  try {
-    path = new URL(trimmed).pathname.replace(/\/+$/, '');
-  } catch (err) {
-    return trimmed;   // not a URL we can parse; leave it exactly as typed
-  }
-  return path === '' ? trimmed + '/v1' : trimmed;
+  return String(baseUrl || '').replace(/\/+$/, '');
 }
 
 /** Both providers report tokens; they name the fields differently. One shape reaches the caller. */

package/views/ai/provider-card.ejs

@@ -64,6 +64,14 @@
           <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 (h.tokensPerSec != null) { %>
+          <%# Completion tokens over the WHOLE call, so it includes prompt processing and the
+              network — what the caller experienced, not the model's raw generation speed. The
+              title says so, because an unqualified "tok/s" invites comparing it to a benchmark. %>
+          <div><div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Throughput</div>
+            <span class="font-monospace"
+                  title="Completion tokens per second of total call time, averaged over the last <%= h.samples %> call<%= h.samples === 1 ? '' : 's' %>. Includes prompt processing and network."><%= h.tokensPerSec %> tok/s</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>