nexus-ai-pro 2.7.0 → 2.9.0

package/dist/embeddings/batch-mock.d.ts

@@ -0,0 +1,45 @@
+import type { BatchJobRef, BatchJobState, BatchJobStatus, BatchProviderCallContext } from '../types/batch.js';
+import type { EmbeddingProviderMediaPart } from '../types/embeddings.js';
+import type { EmbeddingBatchOutputItem, EmbeddingBatchProvider, EmbeddingBatchProviderCapabilities, EmbeddingBatchProviderInfo, EmbeddingBatchProviderRequest } from './batch.js';
+/** Options for the mock embedding batch tier. */
+export interface MockEmbeddingBatchProviderOptions {
+    /** Its name, which its refs carry. Defaults to `mock`. */
+    name?: string;
+    /** Capabilities reported, merged over the defaults. */
+    capabilities?: Partial<EmbeddingBatchProviderCapabilities>;
+    /**
+     * Statuses successive polls of a batch return; the last repeats, so `['in_progress', 'completed']`
+     * finishes on the second poll. Defaults to completing at once.
+     */
+    statuses?: readonly BatchJobStatus[];
+    /** customIds that come back as errors instead of vectors. */
+    failItems?: readonly string[];
+    /** Vector width when the request sets none. Defaults to 16. */
+    dimensions?: number;
+    /** Reports input tokens per item, a word count. Defaults to true; false leaves the cost to be estimated. */
+    reportTokens?: boolean;
+    /** The text a media part's vector is hashed from, as `MockEmbeddingProviderOptions.describeMedia`. */
+    describeMedia?: (part: EmbeddingProviderMediaPart) => string;
+}
+/**
+ * A deterministic embedding batch tier, in memory. Each input's vector is the one
+ * `MockEmbeddingProvider` returns for it, so a test can compare the batch path with the direct one. It
+ * keeps every batch it was given in `submitted`.
+ */
+export declare class MockEmbeddingBatchProvider implements EmbeddingBatchProvider {
+    private readonly options;
+    /** Its name and capabilities. */
+    readonly info: EmbeddingBatchProviderInfo;
+    /** Every batch submitted, in order. */
+    readonly submitted: EmbeddingBatchProviderRequest[];
+    private readonly batches;
+    constructor(options?: MockEmbeddingBatchProviderOptions);
+    /** Accepts a batch and returns its ref. */
+    submit(request: EmbeddingBatchProviderRequest, context: BatchProviderCallContext): Promise<BatchJobRef>;
+    /** The next scripted status. */
+    poll(ref: BatchJobRef): Promise<BatchJobState>;
+    /** Every input's vector, or its scripted failure. */
+    results(ref: BatchJobRef): Promise<EmbeddingBatchOutputItem[]>;
+    /** Cancels a batch: its next poll reports `cancelled`. */
+    cancel(ref: BatchJobRef): Promise<BatchJobState>;
+}

package/dist/embeddings/batch-mock.js

@@ -0,0 +1,71 @@
+import { createHashEmbeddings } from '../hallucination/retrieval.js';
+export class MockEmbeddingBatchProvider {
+    options;
+    info;
+    submitted = [];
+    batches = new Map();
+    constructor(options = {}) {
+        this.options = options;
+        this.info = {
+            name: options.name ?? 'mock',
+            capabilities: {
+                maxItems: 50_000,
+                supportsCancel: true,
+                discount: 0.5,
+                inputModalities: ['text', 'image', 'audio', 'document'],
+                ...options.capabilities,
+            },
+        };
+    }
+    async submit(request, context) {
+        if (context.signal.aborted)
+            throw context.signal.reason ?? new Error('aborted');
+        this.submitted.push(request);
+        const id = `mock-batch-${this.submitted.length}`;
+        this.batches.set(id, { request, polls: 0 });
+        return { id, provider: this.info.name };
+    }
+    async poll(ref) {
+        const batch = this.batches.get(ref.id);
+        if (!batch)
+            throw new Error(`no mock batch ${ref.id}`);
+        const statuses = this.options.statuses ?? ['completed'];
+        const status = batch.cancelled
+            ? 'cancelled'
+            : (statuses[Math.min(batch.polls, statuses.length - 1)] ?? 'completed');
+        batch.polls += 1;
+        const total = batch.request.items.length;
+        const failed = (this.options.failItems ?? []).filter((id) => batch.request.items.some((item) => item.customId === id)).length;
+        return {
+            ref,
+            status,
+            counts: status === 'completed' ? { total, completed: total - failed, failed } : { total, completed: 0, failed: 0 },
+        };
+    }
+    async results(ref) {
+        const batch = this.batches.get(ref.id);
+        if (!batch)
+            throw new Error(`no mock batch ${ref.id}`);
+        const { request } = batch;
+        const describe = this.options.describeMedia ??
+            ((part) => `${part.type} ${(part.data ?? part.url)?.slice(0, 64)}`);
+        const texts = request.items.map((item) => item.contents
+            ? item.contents.map((part) => (part.type === 'text' ? part.text : describe(part))).join(' ')
+            : item.input);
+        const vectors = createHashEmbeddings(texts, request.dimensions ?? this.options.dimensions ?? 16);
+        const failures = new Set(this.options.failItems ?? []);
+        return request.items.map((item, index) => failures.has(item.customId)
+            ? { customId: item.customId, error: { message: 'scripted failure', code: 'mock_failure' } }
+            : {
+                customId: item.customId,
+                vector: vectors[index],
+                ...(this.options.reportTokens === false ? {} : { inputTokens: (texts[index] ?? '').split(/\s+/).length }),
+            });
+    }
+    async cancel(ref) {
+        const batch = this.batches.get(ref.id);
+        if (batch)
+            batch.cancelled = true;
+        return { ref, status: 'cancelled' };
+    }
+}

package/dist/embeddings/batch-openai.d.ts

@@ -0,0 +1,23 @@
+import { type OpenAIBatchClientOptions } from '../batch/openai-client.js';
+import type { BatchJobRef, BatchJobState, BatchProviderCallContext } from '../types/batch.js';
+import type { EmbeddingBatchOutputItem, EmbeddingBatchProvider, EmbeddingBatchProviderInfo, EmbeddingBatchProviderRequest } from './batch.js';
+/** Options for OpenAI's embedding batch tier: the key, and optionally the base URL, organization, and `fetch`. */
+export type OpenAIEmbeddingBatchProviderOptions = OpenAIBatchClientOptions;
+/**
+ * OpenAI's Batch API for `/v1/embeddings`: half price, a 24-hour window, and at most 50,000 inputs a
+ * batch. Each input is one line; failed lines are read from the error file, so none goes missing.
+ */
+export declare class OpenAIEmbeddingBatchProvider implements EmbeddingBatchProvider {
+    /** Always `openai`, with its batch limits. */
+    readonly info: EmbeddingBatchProviderInfo;
+    private readonly client;
+    constructor(options: OpenAIEmbeddingBatchProviderOptions);
+    /** Uploads one line per input and creates a batch over them. */
+    submit(request: EmbeddingBatchProviderRequest, context: BatchProviderCallContext): Promise<BatchJobRef>;
+    /** Reads a batch's status and counts. */
+    poll(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+    /** Every input's vector or error, from the output and error files. */
+    results(ref: BatchJobRef, context: BatchProviderCallContext): Promise<EmbeddingBatchOutputItem[]>;
+    /** Cancels a batch. Inputs already embedded keep their results. */
+    cancel(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+}

package/dist/embeddings/batch-openai.js

@@ -0,0 +1,55 @@
+import { lineError, OpenAIBatchClient } from '../batch/openai-client.js';
+export class OpenAIEmbeddingBatchProvider {
+    info = {
+        name: 'openai',
+        capabilities: {
+            maxItems: 50_000,
+            maxBytes: 200 * 1024 * 1024,
+            completionWindows: ['24h'],
+            supportsCancel: true,
+            discount: 0.5,
+            inputModalities: ['text'],
+        },
+    };
+    client;
+    constructor(options) {
+        this.client = new OpenAIBatchClient(options);
+    }
+    async submit(request, context) {
+        const { batch, fileId } = await this.client.create(request.items.map((item) => ({
+            custom_id: item.customId,
+            method: 'POST',
+            url: '/v1/embeddings',
+            body: {
+                model: request.model,
+                input: item.input,
+                encoding_format: 'float',
+                ...(request.dimensions !== undefined ? { dimensions: request.dimensions } : {}),
+            },
+        })), { endpoint: '/v1/embeddings', completionWindow: request.completionWindow, metadata: request.metadata }, context);
+        return { id: batch.id, provider: 'openai', metadata: { inputFileId: fileId } };
+    }
+    async poll(ref, context) {
+        return this.client.state(ref, await this.client.read(ref.id, context));
+    }
+    async results(ref, context) {
+        return (await this.client.lines(ref.id, context)).map((line) => {
+            const customId = line.custom_id ?? '';
+            const error = lineError(line);
+            if (error)
+                return { customId, error };
+            const body = line.response?.body;
+            const vector = body.data?.[0]?.embedding;
+            if (!Array.isArray(vector))
+                return { customId, error: { message: 'the line carried no embedding' } };
+            return {
+                customId,
+                vector,
+                ...(body.usage?.prompt_tokens !== undefined ? { inputTokens: body.usage.prompt_tokens } : {}),
+            };
+        });
+    }
+    async cancel(ref, context) {
+        return this.client.state(ref, await this.client.cancel(ref.id, context));
+    }
+}

package/dist/embeddings/batch.d.ts

@@ -0,0 +1,230 @@
+import type { BatchCounts, BatchJobRef, BatchJobState, BatchJobStatus, BatchProviderCallContext, BatchProviderCapabilities } from '../types/batch.js';
+import type { EmbeddingInputType, EmbeddingModality, EmbeddingModelRegistryConfig, EmbeddingParts, EmbeddingProviderPart } from '../types/embeddings.js';
+import type { OperationLifecycleLike } from '../types/lifecycle.js';
+import type { DurableOperationHandle, OperationRunnerConfig } from '../types/operations.js';
+import type { ResponseCost, TokenUsage } from '../types/response.js';
+/** One input of an embedding batch, under the id its vector comes back by. */
+export interface EmbeddingBatchItem {
+    /** Echoed back with the vector. Required, and unique: a provider does not keep the order. */
+    customId: string;
+    /** A text, or parts holding media for a model that takes it. */
+    input: string | EmbeddingParts;
+}
+/** A batch of inputs to embed through a provider's batch tier. */
+export interface EmbeddingBatchSubmitRequest {
+    /** The inputs. Every `customId` must be unique. */
+    items: readonly EmbeddingBatchItem[];
+    /** The concrete model. A batch tier takes no alias routing. */
+    model: string;
+    /** The adapter to use. Defaults to the manager's default. */
+    provider?: string;
+    /** What the vectors will be used for. */
+    inputType?: EmbeddingInputType;
+    /** Vector size to return, on models that can shorten theirs. */
+    dimensions?: number;
+    /** Scales every vector to unit length. */
+    normalize?: boolean;
+    /** How long the provider may take, in its own vocabulary. Defaults to `24h`. */
+    completionWindow?: string;
+    /** Replays the operation accepted under this key instead of submitting a second batch. */
+    idempotencyKey?: string;
+    /** Labels attached to the batch on the provider's side. */
+    metadata?: Record<string, string>;
+    /** Overrides the manager's poll interval. */
+    pollIntervalMs?: number;
+    /** Gives up waiting after this long. The provider-side batch is left running. */
+    timeoutMs?: number;
+    /** Stops waiting. The provider-side batch keeps running unless it is cancelled. */
+    signal?: AbortSignal;
+}
+/** One input as an adapter receives it: its text, and its parts when the batch holds media. */
+export interface EmbeddingBatchProviderItem {
+    /** The id its vector comes back by. */
+    customId: string;
+    /** Its text: a string itself, or its text parts joined. */
+    input: string;
+    /** Its parts, media resolved to base64 or a URL, when the batch holds media. */
+    contents?: EmbeddingProviderPart[];
+}
+/** A batch as an adapter receives it: inputs checked and resolved. */
+export interface EmbeddingBatchProviderRequest {
+    /** The inputs. */
+    items: EmbeddingBatchProviderItem[];
+    /** The provider's model name. */
+    model: string;
+    /** What the vectors will be used for. */
+    inputType?: EmbeddingInputType;
+    /** Vector size to return. */
+    dimensions?: number;
+    /** The completion window. */
+    completionWindow?: string;
+    /** Labels for the provider's side. */
+    metadata?: Record<string, string>;
+}
+/** One input's outcome: its vector, or why it failed. */
+export interface EmbeddingBatchOutputItem {
+    /** The id of the input this answers. */
+    customId: string;
+    /** The vector, when the input succeeded. */
+    vector?: number[];
+    /** Why it failed, when it did. */
+    error?: {
+        message: string;
+        code?: string;
+        status?: number;
+    };
+    /** Input tokens, when the provider reports them. */
+    inputTokens?: number;
+}
+/** What an embedding batch tier supports: a batch tier's limits, and the media it takes. */
+export interface EmbeddingBatchProviderCapabilities extends BatchProviderCapabilities {
+    /** What its inputs can hold. Text only when absent. */
+    inputModalities?: readonly EmbeddingModality[];
+}
+/** Identifies an embedding batch adapter and what it supports. */
+export interface EmbeddingBatchProviderInfo {
+    /** The adapter's name, which its refs carry. */
+    name: string;
+    /** What it supports. */
+    capabilities: EmbeddingBatchProviderCapabilities;
+}
+/**
+ * A provider's batch tier for embeddings. Everything after `submit` takes only a `BatchJobRef`, which
+ * is JSON and survives a restart, so a worker can collect a batch it did not submit.
+ */
+export interface EmbeddingBatchProvider {
+    /** What the adapter is and what it supports. */
+    readonly info: EmbeddingBatchProviderInfo;
+    /** Submits the batch and returns a reference that survives a restart. */
+    submit(request: EmbeddingBatchProviderRequest, context: BatchProviderCallContext): Promise<BatchJobRef>;
+    /** Reads the batch's current status. */
+    poll(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+    /** Every input's outcome, once the batch has finished. */
+    results(ref: BatchJobRef, context: BatchProviderCallContext): Promise<EmbeddingBatchOutputItem[]>;
+    /** Cancels a running batch. */
+    cancel?(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
+}
+/** A finished embedding batch: every input's outcome, its usage, and its cost at the batch price. */
+export interface EmbeddingBatchResult {
+    /** The batch. */
+    ref: BatchJobRef;
+    /** Its final status. */
+    status: BatchJobStatus;
+    /** Every input's outcome, matched by `customId`, never by position. */
+    items: EmbeddingBatchOutputItem[];
+    /** How many succeeded and failed. */
+    counts: BatchCounts;
+    /** Input tokens: reported where the provider reports them, estimated where it does not. */
+    usage: TokenUsage;
+    /** Priced from the embedding registry, with the provider's discount applied. */
+    cost: ResponseCost;
+    /** ISO-8601 time it was submitted. */
+    createdAt?: string;
+    /** ISO-8601 time it finished. */
+    completedAt?: string;
+    /** The provider's final status payload. */
+    raw?: unknown;
+}
+/** Configuration for `EmbeddingBatchManager`. */
+export interface EmbeddingBatchConfig {
+    /** Adapters, by name. */
+    providers?: Record<string, EmbeddingBatchProvider>;
+    /** The adapter used when a submission names none. */
+    defaultProvider?: string;
+    /** How often to poll a running batch. Defaults to 30 seconds. */
+    pollIntervalMs?: number;
+    /** The longest poll interval once backoff has grown it. Defaults to 5 minutes. */
+    maxPollIntervalMs?: number;
+    /** How long a submission waits before giving up. Defaults to 26 hours. */
+    timeoutMs?: number;
+    /** Embedding models and prices beyond the bundled ones, used to check inputs and price results. */
+    models?: EmbeddingModelRegistryConfig;
+}
+/** What the manager runs on. */
+export interface EmbeddingBatchManagerRuntime {
+    /** Persists each submission, so a submitted batch survives a restart. */
+    operations?: OperationRunnerConfig<EmbeddingBatchResult>;
+    /**
+     * Runs every submission as one operation of a client's lifecycle, labelled `embedding`: pass
+     * `ai.lifecycle`. It is authorized before the provider sees it, and its cost is reconciled when the
+     * batch is collected.
+     */
+    lifecycle?: OperationLifecycleLike;
+}
+/**
+ * Embedding batch tiers behind one handle: submit, poll with backoff, collect, and price at the
+ * batch rate. A submission is a durable operation that records its batch the moment it exists, so a
+ * worker that dies while it waits is replaced by one that collects that batch, never a second.
+ */
+export declare class EmbeddingBatchManager {
+    private readonly config;
+    private readonly runtime;
+    private readonly providers;
+    /** Loaded on the first `submit()`: `start()` and `resume()` need neither the runner nor the lifecycle. */
+    private durable?;
+    private readonly tokenizer;
+    constructor(config?: EmbeddingBatchConfig, runtime?: EmbeddingBatchManagerRuntime);
+    /** Registers an adapter under a name. Returns the manager, for chaining. */
+    registerEmbeddingBatchProvider(name: string, provider: EmbeddingBatchProvider): this;
+    /** Whether an adapter is registered. */
+    hasEmbeddingBatchProvider(name: string): boolean;
+    /** Every registered adapter's name. */
+    listEmbeddingBatchProviders(): string[];
+    /**
+     * Submits a batch and returns a durable handle that settles when the provider finishes, which can
+     * be hours away: persist `handle.id`, rather than block a request on `handle.result()`.
+     */
+    submit(request: EmbeddingBatchSubmitRequest): Promise<DurableOperationHandle<EmbeddingBatchResult>>;
+    /**
+     * Submits a batch and returns its ref at once, without waiting: for a caller that keeps the ref
+     * itself, as the ingestion pipeline does, and collects it later with `resume()`.
+     */
+    start(request: EmbeddingBatchSubmitRequest): Promise<BatchJobRef>;
+    /** Waits for a batch, submitted here or by another process, and collects it. */
+    resume(ref: BatchJobRef, options?: {
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+    }): Promise<EmbeddingBatchResult>;
+    /** The batch's state now, without waiting. */
+    status(ref: BatchJobRef): Promise<BatchJobState>;
+    /** Cancels a batch. Throws when the adapter cannot cancel. */
+    cancel(ref: BatchJobRef): Promise<BatchJobState>;
+    private prepare;
+    private collect;
+    private price;
+    private resolveProvider;
+    /** The adapter a ref belongs to: by its registered name, or the adapter's own name the ref carries. */
+    private providerFor;
+}
+/** What `batchEmbedder()` submits under. */
+export interface BatchEmbedderOptions {
+    /** The concrete model. */
+    model: string;
+    /** The adapter. Defaults to the manager's default. */
+    provider?: string;
+    /** What the vectors will be used for. Ingestion stores documents, so defaults to `document`. */
+    inputType?: EmbeddingInputType;
+    /** Vector size to return. */
+    dimensions?: number;
+    /** Scales every vector to unit length. */
+    normalize?: boolean;
+    /** Texts per provider batch. Defaults to 10,000. */
+    size?: number;
+    /** How often to poll. Defaults to the manager's interval. */
+    pollIntervalMs?: number;
+}
+/** What `createIngestionPipeline()` takes as `batchEmbed`: submit texts as one batch, collect it later. */
+export interface BatchEmbedder {
+    /** Texts per provider batch. */
+    readonly size: number;
+    /** Submits texts as one batch, labelled with `key`, and returns its ref, which survives a restart. */
+    submit(texts: string[], key: string): Promise<BatchJobRef>;
+    /** Waits for a batch and returns its vectors, in the order its texts were submitted. */
+    collect(ref: BatchJobRef, signal?: AbortSignal): Promise<number[][]>;
+}
+/**
+ * An embedding batch tier as the ingestion pipeline's `batchEmbed`: each window of chunks becomes one
+ * provider batch at the batch price. A batch that does not complete, or any input that fails, fails
+ * the collection, so a window is never written half embedded.
+ */
+export declare function batchEmbedder(manager: EmbeddingBatchManager, options: BatchEmbedderOptions): BatchEmbedder;