@aria-framework/ai 0.23.0 → 0.24.1

package/README.md

@@ -134,6 +134,14 @@ for (const step of rekeyPlan(rows, doc.engines)) {
 over to the id. A row whose id has disappeared is left alone, and the panel shows it as
 missing. It is never re-pointed at whichever engine now has its old name.
 
+To find a stored row's engine in a status document, use the same rule the router, the panel and
+the verifier use. Import it from the package root, not from `providers/lmxDiscovery`:
+
+```js
+const { findEngine } = require('@aria-framework/ai');
+const engine = findEngine(doc.engines, { id: row.lmx_engine_id || null, name: row.lmx_engine });
+```
+
 ### Errors and routing
 
 When an lmx call cannot run, the thrown `AiError` carries `err.lmxSkip`. None of these mean the
@@ -152,7 +160,13 @@ endpoints in preference order and take the first one that serves.
 
 ### Embeddings
 
-`embed()` puts the engine's `dimensions` on the config as `embeddingDimensions`. Record the width
+Call `client.embed(cfg, texts, { signal })` and pass your own resolved embedding config; it never
+falls back to `resolveConfig()`. It applies the same retry as `complete()`: a `429` with
+`Retry-After` is waited out once, and a fast dropped connection is retried once. Calling the
+provider adapter's `embed()` directly skips both, and a throttled batch then fails outright.
+Embeddings are not metered against the token budget.
+
+On lmx, `embed()` puts the engine's `dimensions` on the config as `embeddingDimensions`. Record the width
 you built an index with and compare it on startup. A model swap changes the width, and an index
 built at the old width becomes quietly wrong rather than loudly broken.
 

package/index.js

@@ -145,6 +145,32 @@ function createAiClient(deps = {}) {
     return result;
   }
 
+  /**
+   * Embed one or more strings, with the same retry policy as complete().
+   *
+   * THE RETRY IS THE POINT. complete() always went through withOneRetry; embeddings were called on
+   * the adapter directly, so a gateway 429 failed the whole batch even though Retry-After said how
+   * long to wait - the README promised otherwise, and lmx's CLIENT.md requires a wait-and-retry for
+   * every request through the gateway. Embeddings are idempotent, so a resend is always safe.
+   *
+   * THE CONFIG IS THE CALLER'S. An app resolves its embedding settings separately from completion
+   * (embeddingModel, often a different endpoint), so this never falls back to resolveConfig().
+   * No budget metering - embeddings were never metered, and starting is a separate decision.
+   * @param {object} cfg the resolved embedding config (provider, embeddingModel, …)
+   * @param {string|string[]} texts
+   * @param {{signal?: AbortSignal}} [opts]
+   */
+  async function embed(cfg, texts, opts = {}) {
+    const adapter = cfg && PROVIDERS[cfg.provider];
+    if (!adapter) {
+      throw new AiError('unconfigured', `No adapter is registered for provider "${cfg && cfg.provider}".`);
+    }
+    if (typeof adapter.embed !== 'function') {
+      throw new AiError('unsupported', `${cfg.label || cfg.provider} does not support embeddings.`);
+    }
+    return withOneRetry(() => adapter.embed(cfg, texts), opts);
+  }
+
   /** Is there a provider configured at all? Callers use this to decide whether to render a control. */
   async function isEnabled() {
     return (await resolveConfig()).enabled;
@@ -217,7 +243,7 @@ function createAiClient(deps = {}) {
   const boundGenerate = (opts) => generate(complete, opts);
 
   return {
-    complete, isEnabled, test, listModels, listModelsResult, withOneRetry,
+    complete, embed, isEnabled, test, listModels, listModelsResult, withOneRetry,
     benchmark: benchmarkEndpoint,
     polish: boundPolish, generate: boundGenerate,
     facts, AiError, PROVIDERS, DEFAULTS
@@ -260,6 +286,10 @@ module.exports = {
   // Does this stack actually work? Four checks in the only order they can run. No database and no
   // keystore — every credential arrives as an argument — so it loads eagerly.
   lmxVerify: require('./lmxVerify'),
+  // Engine identity - (instance, id), falling back to name - shared by the router, the stack panel
+  // and the verifier. Apps used to deep-require providers/lmxDiscovery for it; that path still
+  // works, but this is the supported one.
+  findEngine: require('./providers/lmxDiscovery').findEngine,
   // The counting rules a screen needs. Separate from the verifier because "what did the stack say"
   // and "what does that mean for what I am relying on" are different questions, and only the second
   // one needs to know which engines this app has adopted.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aria-framework/ai",
   "description": "Aria App Framework \u2014 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.23.0",
+  "version": "0.24.1",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {

package/providers/openai-compatible.js

@@ -404,6 +404,14 @@ async function embed(cfg, texts) {
   } finally {
     clearTimeout(timer);
   }
+  // THE STATUS FIRST, the body second — the order complete() already had. Parsing first turned a
+  // 429 (often an empty body) into "not JSON", and a 429 with a JSON body into "could not embed",
+  // both `bad_response`: never `rate_limit`, so client.embed's Retry-After wait (0.24.0) could not
+  // fire and an lmx gateway throttle read as a broken engine. httpError is handed the body already
+  // read — a real Response cannot be read twice.
+  if (res.status === 401 || res.status === 403 || res.status === 429) {
+    throw await httpError({ status: res.status, headers: res.headers, text: async () => raw }, label, cfg.apiKey);
+  }
   let payload;
   try { payload = JSON.parse(raw); } catch (err) {
     throw new AiError('bad_response', `${label} returned something that is not JSON from ${url}.`);

package/views/ai/lmx-stack.ejs

@@ -84,8 +84,9 @@
      <%# WHAT EDIT PREFILLS. The certificate IS carried, because it is public — it is not even
          encrypted at rest — and an operator opening Edit to a blank certificate box has no way to
          tell a stored one from none at all. The two tokens are carried only as LENGTHS, which is
-         the most that can be said about a write-only secret and, as it happens, exactly enough to
-         notice the same value pasted into both fields. %>
+         the most that can be said about a write-only secret, and enough for an operator to see
+         whether the two match: they SHOULD through the gateway (one lmxk_ key in both fields) and
+         should NOT direct to lmx (status.token and an engine key are different credentials). %>
      data-lmx-cert="<%= inst.caCert || '' %>"
      data-lmx-token-len="<%= (inst.creds && inst.creds.statusTokenLength) || '' %>"
      data-lmx-key-len="<%= (inst.creds && inst.creds.enginesKeyLength) || '' %>"
@@ -367,21 +368,25 @@
         </div>
 
         <%# THE LENGTHS ARE THE POINT. Both are write-only, so the only thing that can be said about
-            a stored secret is how long it is — and two fields offering to keep the same number of
-            characters is exactly how an engines key pasted into both of them became visible. %>
+            a stored secret is how long it is. Equal lengths are expected through the gateway, where
+            one lmxk_ key is both credentials; direct to lmx they are two different secrets, and
+            equal lengths there are worth a second look. The help text says which is which. %>
         <div class="col-md-6">
           <label class="form-label" for="lmx-token-<%= inst.id %>">Status token</label>
           <input id="lmx-token-<%= inst.id %>" type="password" class="form-control" name="status_token"
                  autocomplete="new-password"
                  placeholder="<%= (inst.creds && inst.creds.statusTokenLength) ? 'unchanged — ' + inst.creds.statusTokenLength + ' characters stored' : 'nothing stored — enter a value' %>">
-          <div class="form-text">Reads the status document. Never sent to an engine.</div>
+          <div class="form-text">Reads the status document; never sent to an engine. Direct to lmx: the
+            <code>status.token</code>. Through the gateway: your <code>lmxk_</code> key, the same value
+            as the engines key.</div>
         </div>
         <div class="col-md-6">
           <label class="form-label" for="lmx-key-<%= inst.id %>">Engines key</label>
           <input id="lmx-key-<%= inst.id %>" type="password" class="form-control" name="engines_key"
                  autocomplete="new-password"
                  placeholder="<%= (inst.creds && inst.creds.enginesKeyLength) ? 'unchanged — ' + inst.creds.enginesKeyLength + ' characters stored' : 'nothing stored — enter a value' %>">
-          <div class="form-text">Used by every engine here unless one overrides it.</div>
+          <div class="form-text">Used by every engine here unless one overrides it. Through the gateway:
+            the same <code>lmxk_</code> key as the status token.</div>
         </div>
 
         <div class="col-12">