@eltjs/embedding 0.1.3 → 0.2.0

package/README.md

@@ -20,16 +20,27 @@ new ComputedDataset({
   from: [listings],
   compute: new Embedding({
     model,
+    clock: globalThis,
     key: 'id',
     fields: ['title', 'description'],
   }),
 });
 ```
 
+- `clock` waits out the limit of each model call. An app gives `globalThis`, and a test gives a fake clock.
 - `key` is the column that identifies a row. It is the key of the output row.
 - `fields` are the columns whose text makes the vector. The rule joins their text with line breaks. A row with no text in these columns has no vector.
 - The output column `vector` holds a unit vector of float32 values in the byte order of the platform. This is the form that `VectorSearch` of `@zukhruf/embeddings` reads, so the cosine similarity of two vectors is their dot product.
 - The identity of each row is the provider and the id of the model. When you change the model, the next refresh makes every vector again.
+
+## Failures
+
+A model failure stays on the output row, and the next pass asks again (ADR 0007 of `elt-sqlite`).
+
+- When the model answers a call with HTTP 400, the rule splits the call in halves until it finds each text that the model refuses. Only the row of that text fails. An example is a text over the limit of the model.
+- Any other failure fails each row of the call. A split would only send more calls to a model that is down.
+- One call has 120 seconds, with its retries. At that limit, each row of the call fails, and the next batch runs.
+- A stopped refresh fails no row. The next refresh makes those rows.
 - The rule sends 64 rows to `embedMany` at a time. When the model refuses a call, each row of that call is stored as `failed` with the error, and the next refresh asks again. The load does not fail.
 - A vector with no usable length, because it is all zeros or holds a value that is not finite, has no unit vector. Its row is stored as `failed` with the error, the other rows of the call stay `computed`, and the next refresh asks again.
 - To search, declare a view that gives `id` and `vector`, and give its name to `VectorSearch`. A search by publish date, such as `nearest`, also needs `published_at`. A query without a date range does not.
@@ -62,6 +73,7 @@ const searches = prompted(
 
 new Embedding({
   model: documents,
+  clock: globalThis,
   key: 'id',
   fields: ['title', 'description'],
 });

package/dist/embedding.d.ts

@@ -1,5 +1,5 @@
 import { type EmbeddingModel } from 'ai';
-import { type LoadedRow, Rule, type RuleResult } from '@eltjs/elt';
+import { type LoadedRow, type PipelineClock, Rule, type RuleResult } from '@eltjs/elt';
 export declare class Embedding extends Rule<string, Uint8Array> {
     #private;
     readonly key: {
@@ -14,8 +14,9 @@ export declare class Embedding extends Rule<string, Uint8Array> {
     };
     readonly batch = 64;
     readonly concurrency = 1;
-    constructor({ model, key, fields, }: {
+    constructor({ model, clock, key, fields, }: {
         model: EmbeddingModel;
+        clock: Pick<PipelineClock, 'setTimeout' | 'clearTimeout'>;
         key: string;
         fields: readonly string[];
     });

package/dist/embedding.js

@@ -1,5 +1,11 @@
-import { embedMany } from 'ai';
+import { APICallError, embedMany } from 'ai';
 import { Rule, errorMessage, } from '@eltjs/elt';
+// How long one call has, its retries included. The AI SDK gives a call no limit,
+// and a model server that never answers takes 3 tries of undici's 300 s header
+// timeout, about 15 minutes for each batch. This is far above a batch of 64
+// short texts on a local model server, and it fails the rows of that batch: the
+// next refresh asks again.
+const callLimitMs = 120_000;
 // The vector of each loaded row's text, made by an embedding model, so a
 // vector search finds rows by meaning, as pgai's vectorizer and LanceDB's
 // embedding functions keep one beside each row. A vector is stored as a unit
@@ -20,13 +26,16 @@ export class Embedding extends Rule {
     // One call at a time: a local model server answers one call at a time.
     concurrency = 1;
     #model;
+    #clock;
     #fields;
     // key: the column that identifies a row, such as id. fields: the columns
     // whose text makes the vector, joined by line breaks; a row with none has
-    // no vector.
-    constructor({ model, key, fields, }) {
+    // no vector. clock waits out the limit of each call (ADR 0019 of elt): an
+    // app gives globalThis.
+    constructor({ model, clock, key, fields, }) {
         super();
         this.#model = model;
+        this.#clock = clock;
         this.key = {
             name: key,
             description: `The ${key} of the row the vector is made from.`,
@@ -51,22 +60,46 @@ export class Embedding extends Rule {
             : `${this.#model.provider}/${this.#model.modelId}`;
     }
     async compute(texts, signal) {
+        const limit = new AbortController();
+        const timer = this.#clock.setTimeout(() => limit.abort(), callLimitMs);
         try {
             const { embeddings } = await embedMany({
                 model: this.#model,
                 values: [...texts],
-                abortSignal: signal,
+                abortSignal: signal === undefined
+                    ? limit.signal
+                    : AbortSignal.any([signal, limit.signal]),
             });
             return embeddings.map(unitVector);
         }
         catch (failure) {
             if (signal?.aborted)
                 return texts.map(() => ({ gone: true }));
+            if (limit.signal.aborted) {
+                const error = `The model did not answer within ${callLimitMs / 1000} s.`;
+                return texts.map(() => ({ error }));
+            }
+            // A 400 refuses something in the call, such as a text over the model's
+            // limit. Halves of the call find the input it refuses, so that failure
+            // stays on its own row. Any other failure says nothing about the texts,
+            // and a split would only send more calls to a model that is down.
+            if (texts.length > 1 &&
+                APICallError.isInstance(failure) &&
+                failure.statusCode === 400) {
+                const half = Math.ceil(texts.length / 2);
+                return [
+                    ...(await this.compute(texts.slice(0, half), signal)),
+                    ...(await this.compute(texts.slice(half), signal)),
+                ];
+            }
             // A model that refuses a call fails each row of it; the next refresh
             // asks again.
             const error = errorMessage(failure);
             return texts.map(() => ({ error }));
         }
+        finally {
+            this.#clock.clearTimeout(timer);
+        }
     }
 }
 // A vector with no usable length has no unit vector: the division gives NaN,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eltjs/embedding",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A rule of an elt computed dataset: it gives each loaded row a vector of its text, made by an AI SDK embedding model, so a search can find rows by meaning.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,12 +40,12 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@eltjs/elt": "^0.1.3",
+    "@eltjs/elt": "^0.2.0",
     "ai": "^7.0.165"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^4.0.37",
-    "@eltjs/elt-sqlite": "^0.1.3",
+    "@eltjs/elt-sqlite": "^0.2.0",
     "@zukhruf/sqlite-open": "^0.8.10",
     "@zukhruf/testing": "^0.8.10"
   }