nexus-ai-pro 2.7.0 → 2.9.0

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

@@ -0,0 +1,83 @@
+import type { BatchJobRef, BatchJobState, BatchProviderCallContext } from '../types/batch.js';
+/** What every OpenAI batch adapter needs to reach the API. */
+export interface OpenAIBatchClientOptions {
+    /** OpenAI API key. */
+    apiKey: string;
+    /** API base URL. Defaults to `https://api.openai.com/v1`. */
+    baseUrl?: string;
+    /** Sent as the `OpenAI-Organization` header. */
+    organization?: string;
+    /** Headers added to every request. */
+    headers?: Record<string, string>;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** OpenAI's batch object, as far as the adapters read it. */
+export interface OpenAIBatchPayload {
+    id?: string;
+    status?: string;
+    output_file_id?: string | null;
+    error_file_id?: string | null;
+    created_at?: number;
+    completed_at?: number;
+    expires_at?: number;
+    request_counts?: {
+        total?: number;
+        completed?: number;
+        failed?: number;
+    };
+    errors?: {
+        data?: Array<{
+            message?: string;
+            code?: string;
+        }>;
+    };
+}
+/** One line of a batch's output or error file. */
+export interface OpenAIBatchLine {
+    custom_id?: string;
+    response?: {
+        status_code?: number;
+        body?: Record<string, unknown>;
+    };
+    error?: {
+        message?: string;
+        code?: string;
+    } | null;
+}
+/**
+ * OpenAI's Batch API wire protocol, shared by the completion and embedding adapters: a JSONL upload,
+ * a batch pointing at it, and JSONL downloads of what succeeded and what failed.
+ */
+export declare class OpenAIBatchClient {
+    private readonly options;
+    constructor(options: OpenAIBatchClientOptions);
+    /** Uploads the lines as a JSONL file and creates a batch over them. */
+    create(lines: readonly unknown[], batch: {
+        endpoint: string;
+        completionWindow?: string;
+        metadata?: Record<string, string>;
+    }, context: BatchProviderCallContext): Promise<{
+        batch: OpenAIBatchPayload;
+        fileId: string;
+    }>;
+    /** Reads a batch. */
+    read(id: string, context: BatchProviderCallContext): Promise<OpenAIBatchPayload>;
+    /** Cancels a batch. */
+    cancel(id: string, context: BatchProviderCallContext): Promise<OpenAIBatchPayload>;
+    /**
+     * Every line a finished batch wrote: the output file holds what succeeded and the error file what
+     * failed, so both are read, or a failed request would be missing from the results altogether.
+     */
+    lines(id: string, context: BatchProviderCallContext): Promise<OpenAIBatchLine[]>;
+    /** A batch as the neutral state. */
+    state(ref: BatchJobRef, batch: OpenAIBatchPayload): BatchJobState;
+    private json;
+    private send;
+}
+/** A failed line's reason: the error the line carries, or the error body of its response. */
+export declare function lineError(line: OpenAIBatchLine): {
+    message: string;
+    code?: string;
+    status?: number;
+} | undefined;

package/dist/batch/openai-client.js

@@ -0,0 +1,120 @@
+import { BatchProviderResponseError } from './errors.js';
+const STATUS_MAP = {
+    validating: 'validating',
+    in_progress: 'in_progress',
+    finalizing: 'finalizing',
+    completed: 'completed',
+    failed: 'failed',
+    expired: 'expired',
+    cancelling: 'cancelling',
+    cancelled: 'cancelled',
+};
+export class OpenAIBatchClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async create(lines, batch, context) {
+        const form = new FormData();
+        form.append('purpose', 'batch');
+        form.append('file', new Blob([lines.map((line) => JSON.stringify(line)).join('\n')], { type: 'application/jsonl' }), 'batch.jsonl');
+        const file = (await this.json('/files', { method: 'POST', body: form }, context));
+        if (!file.id)
+            throw new BatchProviderResponseError('openai', 'the file upload returned no id');
+        const created = (await this.json('/batches', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                input_file_id: file.id,
+                endpoint: batch.endpoint,
+                completion_window: batch.completionWindow ?? '24h',
+                metadata: batch.metadata,
+            }),
+        }, context));
+        if (!created.id)
+            throw new BatchProviderResponseError('openai', 'the batch response returned no id');
+        return { batch: created, fileId: file.id };
+    }
+    read(id, context) {
+        return this.json(`/batches/${encodeURIComponent(id)}`, {}, context);
+    }
+    cancel(id, context) {
+        return this.json(`/batches/${encodeURIComponent(id)}/cancel`, { method: 'POST' }, context);
+    }
+    async lines(id, context) {
+        const batch = await this.read(id, context);
+        const lines = [];
+        for (const fileId of [batch.output_file_id, batch.error_file_id]) {
+            if (!fileId)
+                continue;
+            const response = await this.send(`/files/${encodeURIComponent(fileId)}/content`, {}, context);
+            for (const line of (await response.text()).split('\n')) {
+                if (!line.trim())
+                    continue;
+                try {
+                    lines.push(JSON.parse(line));
+                }
+                catch (error) {
+                    throw new BatchProviderResponseError('openai', 'an output line was not valid JSON', error);
+                }
+            }
+        }
+        return lines;
+    }
+    state(ref, batch) {
+        const counts = batch.request_counts;
+        return {
+            ref,
+            status: STATUS_MAP[batch.status ?? ''] ?? 'in_progress',
+            counts: counts
+                ? { total: counts.total ?? 0, completed: counts.completed ?? 0, failed: counts.failed ?? 0 }
+                : undefined,
+            createdAt: batch.created_at ? new Date(batch.created_at * 1000).toISOString() : undefined,
+            completedAt: batch.completed_at ? new Date(batch.completed_at * 1000).toISOString() : undefined,
+            expiresAt: batch.expires_at ? new Date(batch.expires_at * 1000).toISOString() : undefined,
+            error: batch.errors?.data?.[0]
+                ? { message: batch.errors.data[0].message ?? 'batch failed', code: batch.errors.data[0].code }
+                : undefined,
+            raw: batch,
+        };
+    }
+    async json(path, init, context) {
+        return (await this.send(path, init, context)).json();
+    }
+    async send(path, init, context) {
+        const fetchImpl = this.options.fetch ?? fetch;
+        const baseUrl = (this.options.baseUrl || 'https://api.openai.com/v1').replace(/\/$/, '');
+        const headers = {
+            authorization: `Bearer ${this.options.apiKey}`,
+            ...(this.options.organization ? { 'openai-organization': this.options.organization } : {}),
+            ...this.options.headers,
+            ...(init.headers ?? {}),
+        };
+        const response = await fetchImpl(`${baseUrl}${path}`, { ...init, headers, signal: context.signal });
+        if (!response.ok) {
+            throw new BatchProviderResponseError('openai', `${path} failed: ${response.status} ${await safeText(response)}`);
+        }
+        return response;
+    }
+}
+export function lineError(line) {
+    if (line.error)
+        return { message: line.error.message ?? 'batch item failed', code: line.error.code };
+    const status = line.response?.status_code ?? 200;
+    if (status < 400 && line.response?.body)
+        return undefined;
+    const body = line.response?.body;
+    return {
+        message: body?.error?.message ?? `batch item failed with status ${status}`,
+        ...(body?.error?.code ? { code: body.error.code } : {}),
+        status,
+    };
+}
+async function safeText(response) {
+    try {
+        return (await response.text()).slice(0, 500);
+    }
+    catch {
+        return '';
+    }
+}

package/dist/batch/openai.d.ts

@@ -1,42 +1,33 @@
 import type { BatchJobRef, BatchJobState, BatchOutputItem, BatchProvider, BatchProviderCallContext, BatchProviderInfo, BatchSubmitRequest } from '../types/batch.js';
+import { type OpenAIBatchClientOptions } from './openai-client.js';
 /** Options for the OpenAI batch provider. */
-export interface OpenAIBatchProviderOptions {
-    /** OpenAI API key. */
-    apiKey: string;
-    /** API base URL. Defaults to `https://api.openai.com/v1`. */
-    baseUrl?: string;
-    /** Sent as the `OpenAI-Organization` header. */
-    organization?: string;
-    /** Headers added to every request. */
-    headers?: Record<string, string>;
-    /** Replaces the global `fetch`. */
-    fetch?: typeof fetch;
-    /** Endpoint every item targets. Defaults to chat completions. */
+export interface OpenAIBatchProviderOptions extends OpenAIBatchClientOptions {
+    /**
+     * Endpoint every item targets. Defaults to chat completions. Embeddings are batched by
+     * `OpenAIEmbeddingBatchProvider`, on `nexus-ai-pro/embeddings/batch/openai`; this adapter refuses
+     * `/v1/embeddings`, since its items are completions.
+     */
     endpoint?: '/v1/chat/completions' | '/v1/embeddings' | (string & {});
 }
 /**
  * OpenAI's Batch API: half price, 24-hour window.
  *
- * The wire protocol is a JSONL upload, a batch pointing at it, then a JSONL download — three
- * different content types across four endpoints, which is why this adapter is larger than a
- * synchronous one.
+ * The wire protocol is a JSONL upload, a batch pointing at it, then JSONL downloads of what succeeded
+ * and what failed — three different content types across four endpoints, which is why this adapter
+ * is larger than a synchronous one.
  */
 export declare class OpenAIBatchProvider implements BatchProvider {
     private readonly options;
     /** Always `openai`, with its batch limits. */
     readonly info: BatchProviderInfo;
+    private readonly client;
     constructor(options: OpenAIBatchProviderOptions);
     /** Uploads the items as JSONL and creates a batch over them. */
     submit(request: BatchSubmitRequest, context: BatchProviderCallContext): Promise<BatchJobRef>;
     /** Reads a batch's status and counts. */
     poll(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
-    /** Downloads a finished batch's results. Empty until the output file exists. */
+    /** Downloads a finished batch's results: what succeeded and what failed. Empty until they exist. */
     results(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchOutputItem[]>;
     /** Cancels a batch. Items already processed keep their results. */
     cancel(ref: BatchJobRef, context: BatchProviderCallContext): Promise<BatchJobState>;
-    private toState;
-    private toOutputItem;
-    private request;
-    private requestText;
-    private send;
 }

package/dist/batch/openai.js

@@ -1,15 +1,6 @@
 import { buildMeta } from '../core/usage.js';
-import { BatchProviderResponseError } from './errors.js';
-const STATUS_MAP = {
-    validating: 'validating',
-    in_progress: 'in_progress',
-    finalizing: 'finalizing',
-    completed: 'completed',
-    failed: 'failed',
-    expired: 'expired',
-    cancelling: 'cancelling',
-    cancelled: 'cancelled',
-};
+import { BatchCapabilityError } from './errors.js';
+import { lineError, OpenAIBatchClient } from './openai-client.js';
 export class OpenAIBatchProvider {
     options;
     info = {
@@ -22,13 +13,17 @@ export class OpenAIBatchProvider {
             discount: 0.5,
         },
     };
+    client;
     constructor(options) {
         this.options = options;
+        this.client = new OpenAIBatchClient(options);
     }
     async submit(request, context) {
         const endpoint = this.options.endpoint ?? '/v1/chat/completions';
-        const jsonl = request.items
-            .map((item) => JSON.stringify({
+        if (endpoint === '/v1/embeddings') {
+            throw new BatchCapabilityError('openai', 'endpoint', 'OpenAIBatchProvider batches completions; batch embeddings with OpenAIEmbeddingBatchProvider from nexus-ai-pro/embeddings/batch/openai');
+        }
+        const { batch, fileId } = await this.client.create(request.items.map((item) => ({
             custom_id: item.customId,
             method: 'POST',
             url: endpoint,
@@ -38,124 +33,37 @@ export class OpenAIBatchProvider {
                 max_tokens: item.request.maxTokens,
                 temperature: item.request.temperature,
             },
-        }))
-            .join('\n');
-        const form = new FormData();
-        form.append('purpose', 'batch');
-        form.append('file', new Blob([jsonl], { type: 'application/jsonl' }), 'batch.jsonl');
-        const file = (await this.request('/files', { method: 'POST', body: form }, context));
-        if (!file.id)
-            throw new BatchProviderResponseError('openai', 'the file upload returned no id');
-        const batch = (await this.request('/batches', {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                input_file_id: file.id,
-                endpoint,
-                completion_window: request.completionWindow ?? '24h',
-                metadata: request.metadata,
-            }),
-        }, context));
-        if (!batch.id)
-            throw new BatchProviderResponseError('openai', 'the batch response returned no id');
-        return { id: batch.id, provider: 'openai', metadata: { inputFileId: file.id, endpoint } };
+        })), { endpoint, completionWindow: request.completionWindow, metadata: request.metadata }, context);
+        return { id: batch.id, provider: 'openai', metadata: { inputFileId: fileId, endpoint } };
     }
     async poll(ref, context) {
-        const batch = (await this.request(`/batches/${encodeURIComponent(ref.id)}`, {}, context));
-        return this.toState(ref, batch);
+        return this.client.state(ref, await this.client.read(ref.id, context));
     }
     async results(ref, context) {
-        const batch = (await this.request(`/batches/${encodeURIComponent(ref.id)}`, {}, context));
-        if (!batch.output_file_id)
-            return [];
-        const body = await this.requestText(`/files/${encodeURIComponent(batch.output_file_id)}/content`, context);
-        return body
-            .split('\n')
-            .filter((line) => line.trim().length > 0)
-            .map((line) => this.toOutputItem(line));
+        return (await this.client.lines(ref.id, context)).map(toOutputItem);
     }
     async cancel(ref, context) {
-        const batch = (await this.request(`/batches/${encodeURIComponent(ref.id)}/cancel`, { method: 'POST' }, context));
-        return this.toState(ref, batch);
-    }
-    toState(ref, batch) {
-        const counts = batch.request_counts;
-        return {
-            ref,
-            status: STATUS_MAP[batch.status ?? ''] ?? 'in_progress',
-            counts: counts
-                ? { total: counts.total ?? 0, completed: counts.completed ?? 0, failed: counts.failed ?? 0 }
-                : undefined,
-            createdAt: batch.created_at ? new Date(batch.created_at * 1000).toISOString() : undefined,
-            completedAt: batch.completed_at ? new Date(batch.completed_at * 1000).toISOString() : undefined,
-            expiresAt: batch.expires_at ? new Date(batch.expires_at * 1000).toISOString() : undefined,
-            error: batch.errors?.data?.[0]
-                ? { message: batch.errors.data[0].message ?? 'batch failed', code: batch.errors.data[0].code }
-                : undefined,
-            raw: batch,
-        };
-    }
-    toOutputItem(line) {
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch (error) {
-            throw new BatchProviderResponseError('openai', 'an output line was not valid JSON', error);
-        }
-        const customId = parsed.custom_id ?? '';
-        if (parsed.error) {
-            return { customId, error: { message: parsed.error.message ?? 'batch item failed', code: parsed.error.code } };
-        }
-        const body = parsed.response?.body;
-        const status = parsed.response?.status_code ?? 200;
-        if (!body || status >= 400) {
-            return { customId, error: { message: `batch item failed with status ${status}`, status } };
-        }
-        const choice = body.choices?.[0];
-        const response = {
-            content: choice?.message?.content ?? '',
-            role: 'assistant',
-            finishReason: choice?.finish_reason === 'length' ? 'length' : 'stop',
-            meta: buildMeta({
-                provider: 'openai',
-                model: body.model ?? '',
-                latencyMs: 0,
-                inputTokens: body.usage?.prompt_tokens,
-                outputTokens: body.usage?.completion_tokens,
-            }),
-        };
-        return { customId, response };
-    }
-    async request(path, init, context) {
-        const response = await this.send(path, init, context);
-        return response.json();
-    }
-    async requestText(path, context) {
-        const response = await this.send(path, {}, context);
-        return response.text();
-    }
-    async send(path, init, context) {
-        const fetchImpl = this.options.fetch ?? fetch;
-        const baseUrl = (this.options.baseUrl || 'https://api.openai.com/v1').replace(/\/$/, '');
-        const headers = {
-            authorization: `Bearer ${this.options.apiKey}`,
-            ...(this.options.organization ? { 'openai-organization': this.options.organization } : {}),
-            ...this.options.headers,
-            ...(init.headers ?? {}),
-        };
-        const response = await fetchImpl(`${baseUrl}${path}`, { ...init, headers, signal: context.signal });
-        if (!response.ok) {
-            throw new BatchProviderResponseError('openai', `${path} failed: ${response.status} ${await safeText(response)}`);
-        }
-        return response;
+        return this.client.state(ref, await this.client.cancel(ref.id, context));
     }
 }
-async function safeText(response) {
-    try {
-        return (await response.text()).slice(0, 500);
-    }
-    catch {
-        return '';
-    }
+function toOutputItem(line) {
+    const customId = line.custom_id ?? '';
+    const error = lineError(line);
+    if (error)
+        return { customId, error };
+    const body = line.response?.body;
+    const choice = body.choices?.[0];
+    const response = {
+        content: choice?.message?.content ?? '',
+        role: 'assistant',
+        finishReason: choice?.finish_reason === 'length' ? 'length' : 'stop',
+        meta: buildMeta({
+            provider: 'openai',
+            model: body.model ?? '',
+            latencyMs: 0,
+            inputTokens: body.usage?.prompt_tokens,
+            outputTokens: body.usage?.completion_tokens,
+        }),
+    };
+    return { customId, response };
 }

package/dist/batch/poll.d.ts

@@ -0,0 +1,22 @@
+import { type BatchJobState } from '../types/batch.js';
+/** How a batch, or any job with a status, is waited on. */
+export interface BatchPollOptions<State = BatchJobState> {
+    /** The first wait between polls, in milliseconds. */
+    intervalMs: number;
+    /** The longest wait, once backoff has grown it. */
+    maxIntervalMs: number;
+    /** Stops waiting. The provider-side batch keeps running. */
+    signal: AbortSignal;
+    /** Called with each state that is not yet final. */
+    onState?: (state: State) => void;
+    /** Whether a state is final. Defaults to a batch's terminal statuses. */
+    settled?: (state: State) => boolean;
+}
+/**
+ * Polls a batch until it reaches a status it never leaves. A batch measured in hours does not deserve
+ * a fixed short interval: the wait grows by half each time up to the maximum, which keeps the poll
+ * count sane without delaying a fast batch, which the first few short polls still catch.
+ */
+export declare function pollUntilSettled<State extends {
+    status: string;
+} = BatchJobState>(poll: () => Promise<State>, options: BatchPollOptions<State>): Promise<State>;

package/dist/batch/poll.js

@@ -0,0 +1,30 @@
+import { isTerminalBatchStatus } from '../types/batch.js';
+export async function pollUntilSettled(poll, options) {
+    const settled = options.settled ?? ((state) => isTerminalBatchStatus(state.status));
+    let interval = options.intervalMs;
+    let state = await poll();
+    while (!settled(state)) {
+        if (options.signal.aborted)
+            throw options.signal.reason ?? new Error('aborted');
+        options.onState?.(state);
+        await delay(interval, options.signal);
+        interval = Math.min(Math.round(interval * 1.5), options.maxIntervalMs);
+        state = await poll();
+    }
+    return state;
+}
+function delay(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/cli/models.d.ts

@@ -0,0 +1,36 @@
+import { type RegistryData } from '../models/data.js';
+import { type ParsedArgs } from './args.js';
+/** How the command reaches the outside: replaced in tests. */
+export interface ModelsCommandIo {
+    fetch: typeof fetch;
+    env: Record<string, string | undefined>;
+}
+/**
+ * `nexus models export | check | refresh`: registry data as a file the application keeps.
+ *
+ * `export` writes the bundled data, as a file to start from. `check` validates a file and says how it
+ * differs from the bundled data. `refresh` lists each provider's models with the keys in the
+ * environment and compares them with the data: what the data lacks, and what the provider no longer
+ * lists. Prices are not in any provider's model list, so they stay a check against its pricing page.
+ */
+export declare function runModelsCommand(subcommand: string, { positionals, flags }: ParsedArgs, io?: ModelsCommandIo): Promise<void>;
+/** How the data compares with what one provider lists. */
+export interface RefreshRow {
+    /** The provider. */
+    provider: string;
+    /** Models the provider lists that the data does not have. */
+    missing: string[];
+    /** Models the data has for the provider that it no longer lists. */
+    unlisted: string[];
+}
+/** Compares registry data with each provider's model list, completion and embedding models alike. */
+export declare function refreshReport(data: RegistryData, listings: Record<string, string[]>): RefreshRow[];
+interface ProviderList {
+    /** The environment variable that holds its key. */
+    env: string;
+    /** Every model id it lists. */
+    list(key: string, fetch: typeof globalThis.fetch): Promise<string[]>;
+}
+/** Each provider's own model list, read with the application's key: nothing else is contacted. */
+export declare const PROVIDER_LISTS: Record<string, ProviderList>;
+export {};