@jxburros/ai-nugget 0.4.1 → 0.7.0

package/nugget/dist/cjs/util.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REASONING_BUDGET_TOKENS = void 0;
+exports.asRecord = asRecord;
+exports.asString = asString;
+exports.asNumber = asNumber;
+exports.promptChars = promptChars;
+exports.textFromMessages = textFromMessages;
+exports.globalEnv = globalEnv;
+exports.applyProviderOptions = applyProviderOptions;
+exports.joinUrl = joinUrl;
+exports.mapWithConcurrency = mapWithConcurrency;
+exports.sleep = sleep;
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function promptChars(messages) {
+    return messages.reduce((sum, message) => {
+        if (typeof message.content === 'string')
+            return sum + message.content.length;
+        return sum + message.content.reduce((partSum, part) => partSum + (part.text?.length ?? 0) + (part.imageBase64?.length ?? 0), 0);
+    }, 0);
+}
+function textFromMessages(messages) {
+    return messages.map((message) => {
+        if (typeof message.content === 'string')
+            return message.content;
+        return message.content.map((part) => part.text ?? '').join('');
+    }).join('\n');
+}
+function globalEnv() {
+    const maybeProcess = globalThis;
+    return maybeProcess.process?.env ?? {};
+}
+/**
+ * Merges app-supplied {@link ChatRequest.providerOptions} into a provider
+ * request body: shallow at the top level, and one level deep for each key in
+ * `nestedKeys` where both sides are plain objects (Ollama `options`, Google
+ * `generationConfig`). Values in `providerOptions` win on collision.
+ */
+function applyProviderOptions(body, providerOptions, nestedKeys = []) {
+    if (!providerOptions)
+        return body;
+    const merged = { ...body };
+    for (const [key, value] of Object.entries(providerOptions)) {
+        const base = asRecord(merged[key]);
+        if (nestedKeys.includes(key) && base && asRecord(value)) {
+            merged[key] = { ...base, ...value };
+        }
+        else {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/** Joins a base URL and path without producing a double slash, even if `base` ends with `/`. */
+function joinUrl(base, path) {
+    return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+/**
+ * Runs `fn` over `items` with at most `limit` in flight at once, preserving
+ * input order in the returned array. Used to probe many local models
+ * concurrently without opening an unbounded number of sockets.
+ */
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workerCount = Math.max(1, Math.min(limit, items.length));
+    const worker = async () => {
+        for (;;) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: workerCount }, worker));
+    return results;
+}
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal?.removeEventListener('abort', onAbort);
+        const timer = setTimeout(() => {
+            settled = true;
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            cleanup();
+            reject(new DOMException('Sleep aborted', 'AbortError'));
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+/**
+ * Token budgets behind the {@link ReasoningEffort} tiers for providers that
+ * express effort as a thinking-token budget (Anthropic `budget_tokens`, Google
+ * `thinkingBudget`). `'none'` is 0. Deliberately conservative: they are floors
+ * a model may stop under, not ceilings it fills.
+ */
+exports.REASONING_BUDGET_TOKENS = {
+    none: 0,
+    minimal: 1024,
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+};

package/nugget/dist/connect.d.ts

@@ -0,0 +1,31 @@
+import type { Connection } from './types.js';
+export interface EnvConnectionOptions {
+    /** Read from this env-like object instead of the process/global environment. */
+    env?: Record<string, string | undefined>;
+    /** Connection id. Defaults to `'app'`. */
+    id?: string;
+    /** Env var names to read (override if an app already uses different names). */
+    providerVar?: string;
+    modelVar?: string;
+    keyEnvVar?: string;
+    baseUrlVar?: string;
+    /** Fallbacks used when the corresponding env var is unset. */
+    defaultProvider?: string;
+    defaultModel?: string;
+    defaultKeyEnv?: string;
+}
+export interface EnvConnection {
+    connection: Connection;
+    model: string;
+}
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export declare function envConnection(options?: EnvConnectionOptions): EnvConnection;
+//# sourceMappingURL=connect.d.ts.map

package/nugget/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAc/E"}

package/nugget/dist/connect.js

@@ -0,0 +1,25 @@
+import { globalEnv } from './util.js';
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export function envConnection(options = {}) {
+    const env = options.env ?? globalEnv();
+    const provider = env[options.providerVar ?? 'AI_PROVIDER']?.trim() || options.defaultProvider || 'openai';
+    const model = env[options.modelVar ?? 'AI_MODEL']?.trim() || options.defaultModel || 'gpt-4o-mini';
+    const keyEnvName = env[options.keyEnvVar ?? 'AI_KEY_ENV']?.trim() || options.defaultKeyEnv || 'OPENAI_API_KEY';
+    const baseUrl = env[options.baseUrlVar ?? 'AI_BASE_URL']?.trim();
+    const connection = {
+        id: options.id ?? 'app',
+        provider,
+        keyRef: { kind: 'env', name: keyEnvName },
+        ...(baseUrl ? { baseUrl } : {}),
+    };
+    return { connection, model };
+}
+//# sourceMappingURL=connect.js.map

package/nugget/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAuBtC;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,SAAS,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,eAAe,IAAI,QAAQ,CAAC;IAC1G,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,YAAY,IAAI,aAAa,CAAC;IACnG,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,aAAa,IAAI,gBAAgB,CAAC;IAC/G,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;IAEjE,MAAM,UAAU,GAAe;QAC7B,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,KAAK;QACvB,QAAQ;QACR,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE;QACzC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChC,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC"}

package/nugget/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { AIErrorKind } from './types.js';
+export declare class AIError extends Error {
+    kind: AIErrorKind;
+    status?: number;
+    retryable: boolean;
+    provider?: string;
+    raw?: string;
+    retryAfterMs?: number;
+    constructor(message: string, opts: {
+        kind: AIErrorKind;
+        status?: number;
+        retryable?: boolean;
+        provider?: string;
+        raw?: string;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+export declare function defaultRetryable(kind: AIErrorKind): boolean;
+export declare function classify(status: number, body?: string, provider?: string, headers?: Headers): AIError;
+export declare function fromUnknown(error: unknown, provider?: string): AIError;
+//# sourceMappingURL=errors.d.ts.map

package/nugget/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAW9C,qBAAa,OAAQ,SAAQ,KAAK;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QACjC,IAAI,EAAE,WAAW,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAWF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE3D;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,SAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAmCjG;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAYtE"}

package/nugget/dist/errors.js

@@ -0,0 +1,104 @@
+import { createDefaultRedactor } from './redact.js';
+/**
+ * Pattern-based redaction applied at the wire boundary, before an error object
+ * exists. `AIHandler` redacts again on the way out (adding session-registered
+ * exact secrets), but doing it here means a provider body that echoes a
+ * recognizable secret can never be carried by an `AIError` in the first place —
+ * including on code paths that never reach the handler's own catch blocks.
+ */
+const wireRedactor = createDefaultRedactor();
+export class AIError extends Error {
+    kind;
+    status;
+    retryable;
+    provider;
+    raw;
+    retryAfterMs;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'AIError';
+        this.kind = opts.kind;
+        this.retryable = opts.retryable ?? defaultRetryable(opts.kind);
+        if (opts.status !== undefined)
+            this.status = opts.status;
+        if (opts.provider !== undefined)
+            this.provider = opts.provider;
+        if (opts.raw !== undefined)
+            this.raw = opts.raw;
+        if (opts.retryAfterMs !== undefined)
+            this.retryAfterMs = opts.retryAfterMs;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+export function defaultRetryable(kind) {
+    return kind === 'rate_limit' || kind === 'timeout' || kind === 'network' || kind === 'server' || kind === 'invalid_response';
+}
+export function classify(status, body = '', provider, headers) {
+    const excerpt = wireRedactor.redact(body.slice(0, 200));
+    const lower = body.toLowerCase();
+    let kind = 'server';
+    // 403 is classified as `auth` (non-retryable) deliberately: a forbidden
+    // response almost always means a bad/insufficient credential or a blocked
+    // region/model, none of which a retry fixes. Callers that know a specific
+    // provider returns a retryable 403 can reclassify in a `beforeCall`/adapter.
+    if (status === 401 || status === 403)
+        kind = 'auth';
+    else if (status === 408)
+        kind = 'timeout';
+    else if (status === 429)
+        kind = 'rate_limit';
+    else if (status === 400 || status === 422) {
+        kind = lower.includes('context') || lower.includes('maximum context') || lower.includes('token limit')
+            ? 'context_length'
+            : 'invalid_request';
+    }
+    else if (status === 404 || status === 410) {
+        // A missing route/deployment is not a malformed request: it is usually a
+        // wrong baseUrl or model name, and sometimes a temporarily misrouted load
+        // balancer. `not_found` keeps it distinguishable from `invalid_request` so
+        // apps don't tell a user "your request was invalid" for an infra problem.
+        // Non-retryable by default — a caller that knows its 404s are transient can
+        // retry on `kind === 'not_found'` itself.
+        kind = 'not_found';
+    }
+    else if (status >= 500)
+        kind = 'server';
+    // Everything else in 4xx (409 conflict, 405, 415, 451, …) is a genuine
+    // client-side request problem, so `invalid_request` is honest for it.
+    else
+        kind = 'invalid_request';
+    return new AIError(`HTTP ${status}: ${excerpt}`, {
+        kind,
+        status,
+        provider,
+        raw: excerpt,
+        retryAfterMs: parseRetryAfter(headers?.get('retry-after') ?? null),
+    });
+}
+export function fromUnknown(error, provider) {
+    if (error instanceof AIError)
+        return error;
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return new AIError('Request was canceled', { kind: 'canceled', retryable: false, provider, cause: error });
+    }
+    if (error instanceof Error && /timeout|timed out/i.test(error.message)) {
+        return new AIError(error.message, { kind: 'timeout', provider, cause: error });
+    }
+    if (error instanceof Error) {
+        return new AIError(error.message, { kind: 'network', provider, cause: error });
+    }
+    return new AIError('Unknown AI provider error', { kind: 'network', provider, cause: error });
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const time = Date.parse(value);
+    if (!Number.isNaN(time))
+        return Math.max(0, time - Date.now());
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/nugget/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/nugget/dist/handler.d.ts

@@ -0,0 +1,114 @@
+import type { CallInfo, CallRecord, ChatRequest, ChatResult, Connection, EmbedRequest, EmbedResult, GovernancePolicy, KeySource, ModelInfo, ParsedResult, Redactor, StandardSchemaV1, StreamEvent, TelemetrySink, Usage } from './types.js';
+export interface HandlerOptions {
+    keySource: KeySource;
+    policy?: GovernancePolicy;
+    redactor?: Redactor;
+    telemetry?: TelemetrySink;
+    hooks?: {
+        beforeCall?(info: CallInfo): Promise<void | 'deny'>;
+        afterCall?(record: CallRecord): Promise<void>;
+    };
+    retry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    /**
+     * Concurrency and pacing limits, enforced by an **in-memory queue on this
+     * handler instance only**. There is no shared/external coordination, so N
+     * instances behind a load balancer allow N × `maxConcurrent` in flight against
+     * the provider. Size these per instance, or put a shared limiter in front if a
+     * global ceiling matters.
+     */
+    limits?: {
+        maxConcurrent?: number;
+        minIntervalMs?: number;
+    };
+    /**
+     * Silence the one-time startup notice logged when no `policy` is supplied.
+     * Set this only when running unrestricted is a deliberate choice — passing an
+     * explicit `policy: allowAllPolicy()` says the same thing and is clearer.
+     */
+    silencePolicyWarning?: boolean;
+    /**
+     * Strip inline `<think>…</think>`-style reasoning out of `delta` events and `ChatResult.text`,
+     * emitting it as `{ type: 'reasoning' }` events instead (default `true`; see `src/reasoning.ts`).
+     * Set `false` to receive the raw answer text exactly as the provider sent it.
+     */
+    stripInlineReasoning?: boolean;
+    /**
+     * Optional cost estimator. Called once per successful call/embedding with the
+     * final usage; its return value (USD) is stored on the telemetry record's
+     * `costUsd`. Return undefined to leave a call uncosted. Pricing tables live in
+     * the app, not the library — this is only the seam to attach one.
+     */
+    pricing?(info: {
+        provider: string;
+        model: string;
+        usage: Usage;
+    }): number | undefined;
+}
+/** Test seam: reset the once-per-process startup notice. */
+export declare function resetPolicyWarningForTests(): void;
+export declare class AIHandler {
+    private opts;
+    private active;
+    private queue;
+    private lastStarted;
+    private sessionRedactor;
+    private policy;
+    constructor(opts: HandlerOptions);
+    chat(conn: Connection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: Connection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    /**
+     * The shared pre-call preamble: policy check → key resolution → `beforeCall`
+     * hook. Every entry point (`stream`, `embed`, `listModels`/`testConnection`)
+     * runs exactly this sequence, so it lives once. Failures are *returned*, not
+     * recorded — each caller owns its own telemetry shape (`recordFailure` for
+     * chat/probe, `recordEmbed` for embeddings) and records the returned error.
+     */
+    private preflight;
+    /** Record a failed call and emit the single redacted `error` event for it. */
+    private failStream;
+    listModels(conn: Connection): Promise<ModelInfo[]>;
+    testConnection(conn: Connection): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /**
+     * Warm a connection so the first real call doesn't pay cold DNS/TLS and
+     * (for a local daemon) process spin-up on the hot path. Runs a lightweight
+     * health probe and never throws — call it once at boot. Combined with a CJS
+     * `require` path it removes the cold-start "offline" false negative.
+     */
+    prewarm(conn: Connection): Promise<void>;
+    /**
+     * Chat that returns typed, validated output. Requests JSON mode, extracts the
+     * JSON from the reply, and validates it against any Standard Schema validator
+     * (Zod / Valibot / ArkType). On a validation miss it performs exactly one
+     * corrective retry that shows the model its error, then throws
+     * `invalid_response` if still invalid. No schema library is bundled — the
+     * caller supplies the schema.
+     */
+    chatParsed<T>(conn: Connection, req: ChatRequest, schema: StandardSchemaV1<T>): Promise<ParsedResult<T>>;
+    /**
+     * Produce embeddings through the same governed pipeline as chat: policy check,
+     * key resolution, `beforeCall` hook, concurrency, and exactly one redacted
+     * telemetry record. Throws a typed `invalid_request` error for providers whose
+     * adapter has no `embed` (Anthropic, Google) rather than failing silently.
+     */
+    embed(conn: Connection, req: EmbedRequest): Promise<EmbedResult>;
+    private recordEmbed;
+    private runProbe;
+    private resolveConnection;
+    private acquire;
+    private release;
+    private retryDelay;
+    private recordSuccess;
+    private recordFailure;
+    private record;
+    private redact;
+    private redactedError;
+    private redactedCause;
+}
+//# sourceMappingURL=handler.d.ts.map

package/nugget/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"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"}