@zenera/neo 1.1.10 → 1.1.11

package/dist/embedding.d.ts

@@ -11,7 +11,11 @@ import type { TokenUsage } from './types.ts';
  */
 export type EmbeddingTaskType = 'query' | 'document';
 export interface EmbeddingRequest {
-    /** the texts to encode, in the order the vectors come back */
+    /**
+     * The texts to encode, in the order the vectors come back. Any length: the
+     * adapter splits it to whatever the model accepts per request and issues
+     * those in parallel, so a caller never has to know the cap or invent one.
+     */
     input: string[];
     taskType?: EmbeddingTaskType;
     /** truncate to this width, where the model supports it */
@@ -21,6 +25,19 @@ export interface EmbeddingRequest {
      * Turn it off to see what the model actually returned.
      */
     normalize?: boolean;
+    /**
+     * Texts finished so far, out of the whole input. A large batch is minutes
+     * of one `await`, and a caller with nothing to say for that long is
+     * indistinguishable from a hung one.
+     */
+    onProgress?: (done: number, total: number) => void;
+    /**
+     * Each slice of the input as it comes back, `at` being where it started in
+     * `input`. A large request is many round trips, and a caller that persists
+     * them can survive a crash without paying for the same vectors twice.
+     * Vectors arrive normalised, exactly as the response will carry them.
+     */
+    onSlice?: (at: number, vectors: number[][]) => void;
     signal?: AbortSignal;
 }
 export interface EmbeddingResponse {
@@ -57,4 +74,6 @@ export interface Embedder {
  * provider without three copies of the same loop.
  */
 export declare function embeddingResponse(vectors: number[][], req: EmbeddingRequest, usage?: TokenUsage): EmbeddingResponse;
+/** Idempotent, so settling a vector that is already unit length changes nothing. */
+export declare function unitVector(vector: number[]): number[];
 //# sourceMappingURL=embedding.d.ts.map

package/dist/embedding.js

@@ -4,12 +4,13 @@
  */
 export function embeddingResponse(vectors, req, usage) {
     return {
-        vectors: req.normalize === false ? vectors : vectors.map(unit),
+        vectors: req.normalize === false ? vectors : vectors.map(unitVector),
         dimensions: vectors[0]?.length ?? 0,
         usage,
     };
 }
-function unit(vector) {
+/** Idempotent, so settling a vector that is already unit length changes nothing. */
+export function unitVector(vector) {
     let sum = 0;
     for (const x of vector) {
         sum += x * x;

package/dist/embeddings/fanout.d.ts

@@ -0,0 +1,51 @@
+import { type EmbeddingRequest, type EmbeddingResponse } from '../embedding.ts';
+import type { ProviderNamed } from '../failure.ts';
+import { RateLimiter } from './limiter.ts';
+/** What one request came back with, before it is joined to the others. */
+export interface EmbeddingSlice {
+    vectors: number[][];
+    /** absent where the vendor reports characters, or nothing */
+    inputTokens?: number;
+}
+/** The per-model knobs every adapter shares, and the connection they share it with. */
+export interface BatchOptions extends ProviderNamed {
+    /** texts per request; the model's own cap applies when unset */
+    maxBatch?: number;
+    /** estimated tokens per request; the model's own cap applies when unset */
+    maxBatchTokens?: number;
+    /**
+     * Paces every embedding request on one connection. Supplied by the registry
+     * so two embedders on one account cannot each ramp up to the full limit;
+     * an adapter built by hand gets one of its own.
+     */
+    limiter?: RateLimiter;
+}
+export interface FanoutPlan {
+    /** the embedder's id, for the one error message that needs it */
+    id: string;
+    limiter: RateLimiter;
+    maxBatch: number;
+    maxBatchTokens: number;
+    send(input: string[]): Promise<EmbeddingSlice>;
+}
+/**
+ * Four characters to a token: within about 15% for English prose, wrong for CJK
+ * and for long identifiers. It only has to be right enough to stay under a cap
+ * that is already generous, and being wrong costs an extra request, not a
+ * failed one.
+ */
+export declare const estimateTokens: (text: string) => number;
+export declare function fanout(req: EmbeddingRequest, plan: FanoutPlan): Promise<EmbeddingResponse>;
+interface Part {
+    /** where these texts started in the caller's array */
+    at: number;
+    texts: string[];
+}
+/**
+ * Greedy, on both caps at once. A single text over the token budget goes alone
+ * and is sent as it is: truncating it would answer with a vector for something
+ * the caller did not ask about, which is worse than the error it will get.
+ */
+export declare function sliceBatch(input: readonly string[], maxBatch: number, maxBatchTokens: number): Part[];
+export {};
+//# sourceMappingURL=fanout.d.ts.map

package/dist/embeddings/fanout.js

@@ -0,0 +1,76 @@
+import { embeddingResponse, unitVector, } from "../embedding.js";
+import { zeroUsage } from "../types.js";
+import { RateLimiter } from "./limiter.js";
+/**
+ * Four characters to a token: within about 15% for English prose, wrong for CJK
+ * and for long identifiers. It only has to be right enough to stay under a cap
+ * that is already generous, and being wrong costs an extra request, not a
+ * failed one.
+ */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+export async function fanout(req, plan) {
+    if (req.input.length === 0) {
+        return embeddingResponse([], req);
+    }
+    const parts = sliceBatch(req.input, plan.maxBatch, plan.maxBatchTokens);
+    const settle = req.normalize !== false;
+    let done = 0;
+    const slices = await Promise.all(parts.map((part) => plan.limiter.run(async () => {
+        const slice = await plan.send(part.texts);
+        if (slice.vectors.length !== part.texts.length) {
+            throw new Error(`embedder "${plan.id}": answered ${slice.vectors.length} vectors ` +
+                `for ${part.texts.length} texts`);
+        }
+        const unit = settle ? slice.vectors.map(unitVector) : slice.vectors;
+        done += part.texts.length;
+        req.onSlice?.(part.at, unit);
+        req.onProgress?.(done, req.input.length);
+        return { ...slice, vectors: unit };
+    }, req.signal)));
+    const vectors = new Array(req.input.length);
+    for (const [at, part] of parts.entries()) {
+        for (const [i, vector] of slices[at].vectors.entries()) {
+            vectors[part.at + i] = vector;
+        }
+    }
+    // Settled slice by slice above. Doing it again over the join would hold a
+    // second copy of every vector at once, which for a large corpus is GBs.
+    return embeddingResponse(vectors, { ...req, normalize: false }, usageOf(slices));
+}
+/**
+ * Greedy, on both caps at once. A single text over the token budget goes alone
+ * and is sent as it is: truncating it would answer with a vector for something
+ * the caller did not ask about, which is worse than the error it will get.
+ */
+export function sliceBatch(input, maxBatch, maxBatchTokens) {
+    const parts = [];
+    let texts = [];
+    let at = 0;
+    let tokens = 0;
+    for (const [i, text] of input.entries()) {
+        const cost = estimateTokens(text);
+        if (texts.length > 0 && (texts.length >= maxBatch || tokens + cost > maxBatchTokens)) {
+            parts.push({ at, texts });
+            texts = [];
+            at = i;
+            tokens = 0;
+        }
+        texts.push(text);
+        tokens += cost;
+    }
+    if (texts.length > 0) {
+        parts.push({ at, texts });
+    }
+    return parts;
+}
+/** Undefined unless something reported a number: a zero would read as free. */
+function usageOf(slices) {
+    let total;
+    for (const slice of slices) {
+        if (slice.inputTokens !== undefined) {
+            total = (total ?? 0) + slice.inputTokens;
+        }
+    }
+    return total === undefined ? undefined : { ...zeroUsage(), inputTokens: total };
+}
+//# sourceMappingURL=fanout.js.map

package/dist/embeddings/gemini.d.ts

@@ -1,19 +1,12 @@
 import type { GoogleGenAI } from '@google/genai';
-import { type Embedder, type EmbeddingRequest, type EmbeddingResponse } from '../embedding.ts';
+import type { Embedder, EmbeddingRequest, EmbeddingResponse } from '../embedding.ts';
+import { type BatchOptions } from './fanout.ts';
 /** Provider-specific knobs. */
-export interface GeminiEmbedderOptions {
+export interface GeminiEmbedderOptions extends BatchOptions {
     /** default width; a request may override it */
     dimensions?: number;
     /** a document's title, which the retrieval task type takes into account */
     title?: string;
-    /**
-     * Texts this model accepts per request. One is the default because that is
-     * what every `gemini-embedding-*` model takes — `embedContent` is a
-     * single-document endpoint there, and the batch path is a separate,
-     * job-based API. The older `text-embedding-*` models accept far more and
-     * can say so.
-     */
-    maxBatch?: number;
 }
 export declare class GeminiEmbedder implements Embedder {
     #private;

package/dist/embeddings/gemini.js

@@ -1,4 +1,6 @@
-import { embeddingResponse, } from "../embedding.js";
+import { callSites, called } from "../failure.js";
+import { fanout } from "./fanout.js";
+import { RateLimiter } from "./limiter.js";
 // ---------------------------------------------------------------------------
 // Google Gemini embeddings adapter
 //
@@ -15,16 +17,36 @@ const TASK_TYPES = {
     query: 'RETRIEVAL_QUERY',
     document: 'RETRIEVAL_DOCUMENT',
 };
-/** Requests in flight at once when a batch has to be split across several. */
-const CONCURRENCY = 8;
+/**
+ * One, because `embedContent` is a single-document endpoint for every
+ * `gemini-embedding-*` model — it answers more than one content with *"The
+ * embedContent API for this model only supports one content at a time"* — and
+ * the batch path is a separate, job-based API. The older `text-embedding-*`
+ * models take far more.
+ *
+ * This is why the fan-out matters most here: a corpus is one request per chunk,
+ * so how many may be in flight is the entire runtime of a build.
+ */
+const MAX_BATCH = 1;
+const LEGACY_MAX_BATCH = 250;
+const MAX_BATCH_TOKENS = 20_000;
+const LEGACY_MODEL = /^text-embedding-/;
 export class GeminiEmbedder {
     id;
     #client;
     #options;
+    #limiter;
+    #maxBatch;
+    #maxBatchTokens;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#options = options;
+        this.#limiter = options.limiter ?? new RateLimiter();
+        this.#site = callSites(id, options.provider);
+        this.#maxBatch = options.maxBatch ?? (LEGACY_MODEL.test(id) ? LEGACY_MAX_BATCH : MAX_BATCH);
+        this.#maxBatchTokens = options.maxBatchTokens ?? MAX_BATCH_TOKENS;
     }
     async embed(req) {
         const config = {
@@ -34,38 +56,32 @@ export class GeminiEmbedder {
             title: this.#options.title,
             outputDimensionality: req.dimensions ?? this.#options.dimensions,
             abortSignal: req.signal,
+            // The SDK retries nothing unless `retryOptions` is present, and the
+            // client was built with some; one attempt hands a refusal back out
+            // to the limiter, which is the only thing that can slow the run down.
+            httpOptions: { retryOptions: { attempts: 1 } },
         };
-        // The contract is batch-first and this endpoint usually is not, so the
-        // splitting happens here rather than in every caller. Chunks are issued
-        // in waves and their results concatenated in order, so a caller cannot
-        // tell how many requests it took.
-        const size = Math.max(1, this.#options.maxBatch ?? 1);
-        const chunks = [];
-        for (let i = 0; i < req.input.length; i += size) {
-            chunks.push(req.input.slice(i, i + size));
-        }
-        const vectors = [];
-        for (let i = 0; i < chunks.length; i += CONCURRENCY) {
-            const wave = await Promise.all(chunks.slice(i, i + CONCURRENCY).map((chunk) => this.#send(chunk, config)));
-            for (const part of wave) {
-                vectors.push(...part);
-            }
-        }
         // Usage stays undefined on purpose: this API reports billable
         // *characters*, on Vertex only, which is not a token count and would be
         // a lie in `TokenUsage`.
-        return embeddingResponse(vectors, req);
-    }
-    async #send(input, config) {
-        const res = await this.#client.models.embedContent({
-            model: this.id,
-            // Spelled out as one `Content` per text. `ContentListUnion` also
-            // accepts a `string[]`, and reads it as the *parts of a single
-            // document* — six sentences in, one vector back, and no error.
-            contents: input.map((text) => ({ parts: [{ text }] })),
-            config,
+        return await fanout(req, {
+            id: this.id,
+            limiter: this.#limiter,
+            maxBatch: this.#maxBatch,
+            maxBatchTokens: this.#maxBatchTokens,
+            send: async (input) => {
+                const res = await called(this.#site('embedding', 'models.embedContent'), () => this.#client.models.embedContent({
+                    model: this.id,
+                    // Spelled out as one `Content` per text.
+                    // `ContentListUnion` also accepts a `string[]`, and
+                    // reads it as the *parts of a single document* — six
+                    // sentences in, one vector back, and no error.
+                    contents: input.map((text) => ({ parts: [{ text }] })),
+                    config,
+                }));
+                return { vectors: (res.embeddings ?? []).map((e) => e.values ?? []) };
+            },
         });
-        return (res.embeddings ?? []).map((e) => e.values ?? []);
     }
 }
 //# sourceMappingURL=gemini.js.map

package/dist/embeddings/index.d.ts

@@ -1,4 +1,7 @@
+export * from './fanout.ts';
 export * from './gemini.ts';
+export * from './limiter.ts';
 export * from './openai.ts';
 export * from './openrouter.ts';
+export * from './rate-limit.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/embeddings/index.js

@@ -1,4 +1,7 @@
+export * from "./fanout.js";
 export * from "./gemini.js";
+export * from "./limiter.js";
 export * from "./openai.js";
 export * from "./openrouter.js";
+export * from "./rate-limit.js";
 //# sourceMappingURL=index.js.map

package/dist/embeddings/limiter.d.ts

@@ -0,0 +1,36 @@
+export interface LimiterOptions {
+    /** never go below this many in flight */
+    min?: number;
+    /** where to start, before anything is known */
+    start?: number;
+    /** never go above this many, whatever the provider tolerates */
+    max?: number;
+    /** consecutive successes, while saturated, that earn one more slot */
+    stride?: number;
+    /** the first wait after a refusal, doubling while they continue */
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    /** attempts after the first, per task */
+    maxRetries?: number;
+}
+export declare const DEFAULT_MIN = 1;
+export declare const DEFAULT_START = 4;
+export declare const DEFAULT_MAX = 16;
+export declare const DEFAULT_STRIDE = 8;
+export declare const DEFAULT_INITIAL_BACKOFF_MS = 1000;
+export declare const DEFAULT_MAX_BACKOFF_MS = 60000;
+export declare const DEFAULT_MAX_RETRIES = 4;
+export declare class RateLimiter {
+    #private;
+    constructor(options?: LimiterOptions);
+    /** How many may be in flight as things stand. Moves; read it for reporting only. */
+    get limit(): number;
+    get inFlight(): number;
+    /**
+     * Runs the task when there is room, retries it when the failure allows, and
+     * gives up when it does not. The slot is released before any wait, so a
+     * task serving its backoff is not also holding the concurrency down.
+     */
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}
+//# sourceMappingURL=limiter.d.ts.map

package/dist/embeddings/limiter.js

@@ -0,0 +1,182 @@
+import { classify, retryAfterMs } from "./rate-limit.js";
+export const DEFAULT_MIN = 1;
+export const DEFAULT_START = 4;
+export const DEFAULT_MAX = 16;
+export const DEFAULT_STRIDE = 8;
+export const DEFAULT_INITIAL_BACKOFF_MS = 1_000;
+export const DEFAULT_MAX_BACKOFF_MS = 60_000;
+export const DEFAULT_MAX_RETRIES = 4;
+export class RateLimiter {
+    #min;
+    #max;
+    #stride;
+    #initial;
+    #maxBackoff;
+    #retries;
+    #limit;
+    #active = 0;
+    #successes = 0;
+    /** bumped on every decrease; a refusal from an older one is already answered */
+    #epoch = 0;
+    #penalty;
+    #pausedUntil = 0;
+    #timer;
+    #waiting = [];
+    constructor(options = {}) {
+        this.#min = Math.max(1, options.min ?? DEFAULT_MIN);
+        this.#max = Math.max(this.#min, options.max ?? DEFAULT_MAX);
+        this.#stride = Math.max(1, options.stride ?? DEFAULT_STRIDE);
+        this.#initial = Math.max(0, options.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS);
+        this.#maxBackoff = Math.max(this.#initial, options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS);
+        this.#retries = Math.max(0, options.maxRetries ?? DEFAULT_MAX_RETRIES);
+        this.#limit = clamp(options.start ?? DEFAULT_START, this.#min, this.#max);
+        this.#penalty = this.#initial;
+    }
+    /** How many may be in flight as things stand. Moves; read it for reporting only. */
+    get limit() {
+        return this.#limit;
+    }
+    get inFlight() {
+        return this.#active;
+    }
+    /**
+     * Runs the task when there is room, retries it when the failure allows, and
+     * gives up when it does not. The slot is released before any wait, so a
+     * task serving its backoff is not also holding the concurrency down.
+     */
+    async run(task, signal) {
+        let backoff = this.#initial;
+        for (let attempt = 0;; attempt++) {
+            const epoch = await this.#acquire(signal);
+            let failure = 'fatal';
+            let err;
+            try {
+                const value = await task();
+                this.#succeeded();
+                return value;
+            }
+            catch (thrown) {
+                err = thrown;
+                failure = classify(thrown);
+                // Before the slot is let go, so the pause is already in force
+                // when the next waiter is granted one.
+                if (failure === 'rate-limit') {
+                    this.#slowDown(epoch, retryAfterMs(thrown));
+                }
+            }
+            finally {
+                this.#release();
+            }
+            if (failure === 'fatal' || attempt >= this.#retries) {
+                throw err;
+            }
+            // A refusal is already being served by the shared pause, which the
+            // next acquire blocks on; waiting again here would double it.
+            if (failure === 'transient') {
+                await sleep(jitter(Math.min(backoff, this.#maxBackoff)), signal);
+                backoff *= 2;
+            }
+        }
+    }
+    #acquire(signal) {
+        if (signal?.aborted) {
+            return Promise.reject(signal.reason);
+        }
+        if (this.#free()) {
+            this.#active++;
+            return Promise.resolve(this.#epoch);
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                grant: (epoch) => {
+                    signal?.removeEventListener('abort', abort);
+                    resolve(epoch);
+                },
+                fail: reject,
+            };
+            const abort = () => {
+                const at = this.#waiting.indexOf(waiter);
+                if (at >= 0) {
+                    this.#waiting.splice(at, 1);
+                }
+                reject(signal?.reason);
+            };
+            signal?.addEventListener('abort', abort, { once: true });
+            this.#waiting.push(waiter);
+        });
+    }
+    #free() {
+        return this.#active < this.#limit && Date.now() >= this.#pausedUntil;
+    }
+    #release() {
+        this.#active--;
+        this.#pump();
+    }
+    /**
+     * The slot is taken here rather than by the waiter, so several woken at
+     * once cannot each see the same free one before any of them claims it.
+     */
+    #pump() {
+        while (this.#waiting.length > 0 && this.#free()) {
+            this.#active++;
+            this.#waiting.shift().grant(this.#epoch);
+        }
+    }
+    #succeeded() {
+        this.#penalty = this.#initial;
+        // Only a limit that is actually the constraint has earned being raised;
+        // with nothing queued, more slots would go unused anyway.
+        if (this.#waiting.length === 0) {
+            return;
+        }
+        if (++this.#successes >= this.#stride) {
+            this.#successes = 0;
+            this.#limit = Math.min(this.#max, this.#limit + 1);
+            this.#pump();
+        }
+    }
+    #slowDown(epoch, retryAfter) {
+        if (epoch === this.#epoch) {
+            this.#epoch++;
+            this.#limit = Math.max(this.#min, Math.floor(this.#limit / 2));
+            this.#successes = 0;
+            this.#penalty = Math.min(this.#maxBackoff, this.#penalty * 2);
+        }
+        // Even a refusal that arrived too late to lower the limit still knows
+        // how long this provider wants to be left alone.
+        this.#pause(retryAfter ?? this.#penalty);
+    }
+    #pause(ms) {
+        const until = Date.now() + Math.max(0, ms);
+        if (until <= this.#pausedUntil) {
+            return;
+        }
+        this.#pausedUntil = until;
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            this.#pump();
+        }, until - Date.now());
+        this.#timer.unref?.();
+    }
+}
+const clamp = (n, low, high) => Math.min(high, Math.max(low, n));
+/** Full jitter: without it, everything that backed off together returns together. */
+const jitter = (ms) => ms / 2 + Math.random() * (ms / 2);
+function sleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+//# sourceMappingURL=limiter.js.map

package/dist/embeddings/openai.d.ts

@@ -1,11 +1,12 @@
 import type OpenAI from 'openai';
-import { type Embedder, type EmbeddingRequest, type EmbeddingResponse } from '../embedding.ts';
+import type { Embedder, EmbeddingRequest, EmbeddingResponse } from '../embedding.ts';
+import { type BatchOptions } from './fanout.ts';
 /**
  * Provider-specific knobs. `taskType` has no counterpart here: OpenAI's models
  * are symmetric, so a query and a document are encoded identically and the
  * request's hint is simply not sent.
  */
-export interface OpenAIEmbedderOptions {
+export interface OpenAIEmbedderOptions extends BatchOptions {
     /** default width; a request may override it */
     dimensions?: number;
 }

package/dist/embeddings/openai.js

@@ -1,26 +1,67 @@
-import { embeddingResponse, } from "../embedding.js";
-import { zeroUsage } from "../types.js";
+import { callSites, called } from "../failure.js";
+import { fanout } from "./fanout.js";
+import { RateLimiter } from "./limiter.js";
+/**
+ * What OpenAI documents for `text-embedding-*`: 2048 inputs, and 300k tokens
+ * across them. The token figure is the one that fires in practice, and it is
+ * held under the real cap because the estimate feeding it counts characters.
+ */
+const MAX_BATCH = 2048;
+const MAX_BATCH_TOKENS = 250_000;
+/**
+ * A gateway is not OpenAI. `openai-compatible` reaches vLLM, Ollama and
+ * whatever else speaks the shape, none of which promise those numbers, so an
+ * unrecognised id gets something any implementation can be expected to hold.
+ */
+const GATEWAY_BATCH = 96;
+const GATEWAY_BATCH_TOKENS = 100_000;
+const OPENAI_MODEL = /^text-embedding-/;
 export class OpenAIEmbedder {
     id;
     #client;
     #dimensions;
+    #limiter;
+    #maxBatch;
+    #maxBatchTokens;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#dimensions = options.dimensions;
+        this.#limiter = options.limiter ?? new RateLimiter();
+        this.#site = callSites(id, options.provider);
+        const known = OPENAI_MODEL.test(id);
+        this.#maxBatch = options.maxBatch ?? (known ? MAX_BATCH : GATEWAY_BATCH);
+        this.#maxBatchTokens =
+            options.maxBatchTokens ?? (known ? MAX_BATCH_TOKENS : GATEWAY_BATCH_TOKENS);
     }
     async embed(req) {
-        const res = await this.#client.embeddings.create({
-            model: this.id,
-            input: req.input,
-            dimensions: req.dimensions ?? this.#dimensions,
-        }, { signal: req.signal });
-        // The API documents the order but does not promise it, and `index` is
-        // the only thing that ties a vector back to its text.
-        const vectors = [...res.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
-        return embeddingResponse(vectors, req, {
-            ...zeroUsage(),
-            inputTokens: res.usage.prompt_tokens,
+        return await fanout(req, {
+            id: this.id,
+            limiter: this.#limiter,
+            maxBatch: this.#maxBatch,
+            maxBatchTokens: this.#maxBatchTokens,
+            send: async (input) => {
+                const res = await called(this.#site('embedding', 'embeddings.create'), () => this.#client.embeddings.create({
+                    model: this.id,
+                    input,
+                    dimensions: req.dimensions ?? this.#dimensions,
+                }, 
+                // The client's own retrying is off because a retry it
+                // serves is one the limiter never sees: the call
+                // succeeds, nothing learns the provider is refusing, and
+                // the run quietly takes as long as the backoff it did
+                // not report.
+                { signal: req.signal, maxRetries: 0 }));
+                // The API documents the order but does not promise it, and
+                // `index` is the only thing tying a vector back to its text.
+                return {
+                    vectors: [...res.data]
+                        .sort((a, b) => a.index - b.index)
+                        .map((d) => d.embedding),
+                    inputTokens: res.usage.prompt_tokens,
+                };
+            },
         });
     }
 }

package/dist/embeddings/openrouter.d.ts

@@ -1,8 +1,9 @@
 import type { OpenRouter } from '@openrouter/sdk';
 import type { ProviderPreferences } from '@openrouter/sdk/models';
 import type { Embedder, EmbeddingRequest, EmbeddingResponse } from '../embedding.ts';
+import { type BatchOptions } from './fanout.ts';
 /** Provider-specific knobs. */
-export interface OpenRouterEmbedderOptions {
+export interface OpenRouterEmbedderOptions extends BatchOptions {
     /** default width; a request may override it */
     dimensions?: number;
     /**