@jxburros/ai-nugget 0.4.1 → 0.7.0

package/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/dist/errors.js

@@ -1,3 +1,12 @@
+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;
@@ -26,9 +35,13 @@ 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 = body.slice(0, 200);
+    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)
@@ -40,8 +53,19 @@ export function classify(status, body = '', provider, headers) {
             ? '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}`, {

package/dist/handler.d.ts

@@ -1,4 +1,4 @@
-import type { CallInfo, CallRecord, ChatRequest, ChatResult, Connection, GovernancePolicy, KeySource, ModelInfo, Redactor, StreamEvent, TelemetrySink } from './types.js';
+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;
@@ -13,11 +13,43 @@ export interface HandlerOptions {
         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;
@@ -28,11 +60,45 @@ export declare class AIHandler {
     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;