@owlmeans/llm 0.1.14

package/build/types.d.ts

@@ -0,0 +1,190 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { AIMessage, BaseMessage, MessageFieldWithRole } from '@langchain/core/messages';
+import type { BaseCallbackHandler, CallbackHandlerMethods } from '@langchain/core/callbacks/base';
+import type { JSONSchemaType } from 'ajv';
+import type { InitializedService } from '@owlmeans/context';
+import type { LlmPurpose, ModelProvider, NullCapture, SpectatorArgument, SpectatorEntryLogged } from '@owlmeans/llm-common';
+export type MaybeArray<T> = T | T[];
+/**
+ * Out-of-band result channel for a model call: the caller passes a `ref` and receives
+ * the raw message, the spectator entry it was logged under, and an optional callback
+ * fired as soon as the value is known (before the caller's own await resolves).
+ */
+export interface RefferedResult<T> {
+    spectatorEntry?: SpectatorEntryLogged;
+    value?: T;
+    callback?: (arg: T) => Promise<void>;
+}
+export interface RetryOptions {
+    retries: number;
+    outputErrors?: boolean;
+    /**
+     * Abort the retry loop for this call. Return the error to throw, or `null` to keep
+     * retrying. Consulted in addition to the globally registered resolvers
+     * (`registerFatalError`) and the provider plugins' `isFatal`.
+     */
+    fatal?: (e: unknown) => Error | null;
+}
+/** Decides whether an error must abort a retry loop instead of being retried. */
+export interface FatalErrorResolver {
+    (e: unknown): Error | null;
+}
+export interface LlmLogging {
+    /** Print every swallowed retry error to the console. */
+    outputErrors?: boolean;
+    /** Hand a full {@link NullCapture} to the spectator when a call returns nothing usable. */
+    captureNull?: boolean;
+    purpose: LlmPurpose;
+}
+export interface LlmModelOptions extends LlmLogging {
+    model: BaseChatModel;
+    retries?: number;
+}
+export type ModelMessage = BaseMessage | MessageFieldWithRole;
+export type ModelInputItem = ModelMessage | string;
+export type ModelInput = MaybeArray<ModelInputItem>;
+export interface LlmCallOptions {
+    /** Short name of the operation — used as the LangChain run name and in spectator entries. */
+    action: string;
+    /** Ask the provider to cache the prompt prefix (no-op for providers without prompt caching). */
+    useCache?: boolean;
+    /** How many leading messages to mark as cacheable (capped by the provider's own limit). */
+    cacheMax?: number;
+}
+export interface LlmAskOptions extends LlmCallOptions {
+    ref?: RefferedResult<AIMessage>;
+    filter?: (output: string, result: AIMessage) => (string | null) | Promise<string | null>;
+}
+export interface LlmTalkOptions extends LlmCallOptions {
+    ref?: RefferedResult<AIMessage>;
+    filter?: (result: AIMessage) => Promise<AIMessage | null>;
+}
+export interface LlmInvokeOptions<T> extends LlmCallOptions {
+    temperature?: number | undefined;
+    ref?: RefferedResult<AIMessage>;
+    filter?: (output: T, result: AIMessage) => (T | null) | Promise<T | null>;
+}
+export interface LlmRequestOptions extends LlmCallOptions {
+    ref?: RefferedResult<AIMessage>;
+    filter?: (result: AIMessage) => Promise<AIMessage | null>;
+}
+/**
+ * The four ways to talk to a model. Every method streams under an idle deadline,
+ * retries with escalating output budget, logs to the spectator and validates the result.
+ *
+ * - `ask` → plain text.
+ * - `talk` → the raw `AIMessage`.
+ * - `invoke` → a schema-validated object.
+ * - `request` → an `AIMessage` whose `content` is the schema-validated JSON.
+ */
+export interface LlmModel {
+    ask: (input: ModelInput, options: LlmAskOptions) => Promise<string>;
+    talk: (input: ModelInput, options: LlmTalkOptions) => Promise<AIMessage>;
+    invoke: <T>(input: ModelInput, schema: JSONSchemaType<T>, options: LlmInvokeOptions<T>) => Promise<T>;
+    request: <T>(input: ModelInput, schema: JSONSchemaType<T>, options: LlmRequestOptions) => Promise<AIMessage>;
+}
+/**
+ * Observability sink the model writes every call to. Deliberately minimal — a consumer's
+ * richer spectator (with `derive`, `update`, storage backends) satisfies it structurally.
+ */
+export interface LlmSpectator {
+    log: (arg: SpectatorArgument) => Promise<SpectatorEntryLogged>;
+    /** Optional sink for full diagnostics of a call that returned nothing usable. */
+    captureNull?: (capture: NullCapture) => Promise<void>;
+}
+/** Resolves a model of the same role at a different temperature. */
+export interface TemperatureFactory {
+    (temperature?: number | undefined): BaseChatModel;
+}
+/**
+ * Full runtime configuration of one model alias. The JSON-safe subset that may travel
+ * inside an execution state is `ModelConfigPatch` (`@owlmeans/llm-common`) — this type
+ * additionally carries credentials and provider wiring and must never be serialized.
+ */
+export interface ModelConfig {
+    provider?: ModelProvider | string;
+    secret?: string;
+    alias: string;
+    /** Inherit every field of another alias in the same config list. */
+    preset?: string;
+    model?: string;
+    temperature?: number;
+    /** Initial output-token budget per request (`max_tokens`). */
+    maxTokens?: number;
+    /**
+     * Hard ceiling for output tokens used by the retry escalator. Each retry doubles
+     * `maxTokens` toward this cap; without it the escalator uses
+     * {@link DEFAULT_MAX_OUTPUT_CAP}, which exceeds many models' real per-request output
+     * limit and turns retries into 400 "max_tokens exceeds model limit" errors.
+     */
+    maxTokensCap?: number;
+    topP?: number;
+    baseUrl?: string;
+    organization?: string;
+    /** Provider-routing hint for aggregators that expose one (e.g. HuggingFace). */
+    inferenceProvider?: string;
+    headers?: Record<string, string>;
+    /**
+     * Suppress the model's chain-of-thought / "thinking" tokens. For the Qwen3 family
+     * this injects the `/no_think` soft switch into the prompt; without it those models
+     * routinely spend the entire output budget on hidden reasoning and return empty
+     * content with `finish_reason="length"`.
+     */
+    disableThinking?: boolean;
+    /**
+     * OpenAI-compatible reasoning control, forwarded verbatim as the top-level `reasoning`
+     * request-body field. Use `{ max_tokens: N }` to hard-cap the thinking budget —
+     * universal, and it works even for always-reasoning models (the request `max_tokens`
+     * must stay strictly higher) — or `{ effort: 'none' }` to disable thinking on hybrid
+     * models that enumerate effort levels. `{ exclude: true }` keeps reasoning internal but
+     * omits it from the response.
+     */
+    reasoning?: {
+        effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+        max_tokens?: number;
+        exclude?: boolean;
+        enabled?: boolean;
+    };
+    /**
+     * Force how `invoke`/`request` obtain structured output, overriding the provider
+     * plugin's default: `true` → the provider's NATIVE JSON-schema mode, `false` → the
+     * forced-`tool_choice` tool-calling hack. Plugins that support only one mode
+     * (Anthropic — tool calling) ignore this flag.
+     */
+    structuredOutput?: boolean;
+    /**
+     * Idle/inactivity timeout (ms) for a streamed response. NOT a total cap — the timer
+     * resets on every chunk. Falls back to {@link MODEL_STREAM_TIMEOUT_MS}.
+     */
+    streamTimeout?: number;
+    /**
+     * Stronger model the retry escalator switches to once the primary has failed
+     * {@link FALLBACK_AFTER_ATTEMPTS} times. Specified inline as a partial config merged
+     * over the base config, so it inherits `secret`, `headers`, etc. The escalation only
+     * happens when the fallback belongs to the SAME plugin family as the primary —
+     * rotating providers mid-call would flip the structured-output format.
+     */
+    fallback?: Partial<ModelConfig>;
+}
+export interface LlmServiceOptions {
+    /** The full config list; resolved by `alias` on every `getModel` call. */
+    models: () => ModelConfig[];
+}
+/**
+ * Model factory and registry. Builds a `BaseChatModel` from a `ModelConfig` through the
+ * registered provider plugins, memoizing per alias+override so repeated resolution of a
+ * role does not rebuild the client.
+ */
+export interface LlmService extends InitializedService {
+    models: Map<string, BaseChatModel>;
+    callbacks: (BaseCallbackHandler | CallbackHandlerMethods)[];
+    addCallbacks: (callbacks: (BaseCallbackHandler | CallbackHandlerMethods)[]) => void;
+    /** Resolve (and cache) the model registered under `alias`, with an optional patch. */
+    getModel: (alias: string, override?: Partial<ModelConfig>, createNew?: boolean) => BaseChatModel;
+    /** The configured model list, as supplied by {@link LlmServiceOptions.models}. */
+    configs: () => ModelConfig[];
+}
+export interface WithLlmService {
+    llm: () => LlmService;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

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

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/utils/config.d.ts

@@ -0,0 +1,13 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ModelConfig } from '../types.js';
+/**
+ * Read the original `ModelConfig` back off a model instance. Every plugin's `build`
+ * passes `metadata: { config }` on the client constructor, so the config is reachable
+ * for any provider. Returns an empty object when unavailable — notably for a REFINED
+ * instance, which is rebuilt from `lc_kwargs` and does not reliably carry metadata.
+ * That is why callers read the config from the ORIGINAL model.
+ */
+export declare const readConfig: (model: BaseChatModel) => Partial<ModelConfig>;
+/** Per-model idle stream timeout (ms), falling back to the package default. */
+export declare const idleTimeout: (config: Partial<ModelConfig>) => number;
+//# sourceMappingURL=config.d.ts.map

package/build/utils/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,aAAa,KAAG,OAAO,CAAC,WAAW,CAGpE,CAAA;AAED,+EAA+E;AAC/E,eAAO,MAAM,WAAW,GAAI,QAAQ,OAAO,CAAC,WAAW,CAAC,KAAG,MACV,CAAA"}

package/build/utils/config.js

@@ -0,0 +1,15 @@
+import { MODEL_STREAM_TIMEOUT_MS } from '../consts.js';
+/**
+ * Read the original `ModelConfig` back off a model instance. Every plugin's `build`
+ * passes `metadata: { config }` on the client constructor, so the config is reachable
+ * for any provider. Returns an empty object when unavailable — notably for a REFINED
+ * instance, which is rebuilt from `lc_kwargs` and does not reliably carry metadata.
+ * That is why callers read the config from the ORIGINAL model.
+ */
+export const readConfig = (model) => {
+    const meta = model.metadata;
+    return meta?.config ?? {};
+};
+/** Per-model idle stream timeout (ms), falling back to the package default. */
+export const idleTimeout = (config) => config.streamTimeout ?? MODEL_STREAM_TIMEOUT_MS;
+//# sourceMappingURL=config.js.map

package/build/utils/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAGtD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAoB,EAAwB,EAAE;IACvE,MAAM,IAAI,GAAI,KAAqE,CAAC,QAAQ,CAAA;IAC5F,OAAO,IAAI,EAAE,MAAM,IAAI,EAAE,CAAA;AAC3B,CAAC,CAAA;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAA4B,EAAU,EAAE,CAClE,MAAM,CAAC,aAAa,IAAI,uBAAuB,CAAA"}

package/build/utils/null-report.d.ts

@@ -0,0 +1,36 @@
+import type { AIMessageChunk, MessageFieldWithRole } from '@langchain/core/messages';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { LlmPurpose, NullCapture, NullKind } from '@owlmeans/llm-common';
+import type { LlmSpectator, ModelConfig } from '../types.js';
+export interface NullReportParams {
+    kind: NullKind;
+    action: string;
+    purpose?: LlmPurpose;
+    attempt: number;
+    startedAt: number;
+    /** The instance that actually ran — its `lc_kwargs` carry the effective request shape. */
+    refined: BaseChatModel;
+    /** The ORIGINAL model config (refined instances do not reliably keep metadata). */
+    config: Partial<ModelConfig>;
+    msgs: MessageFieldWithRole[];
+    raw: AIMessageChunk | null;
+    schema?: {
+        toolName: string;
+        innerSchema: unknown;
+    };
+    useCache: boolean;
+}
+/**
+ * Assemble a complete, replayable record of a model call that returned nothing usable:
+ * the effective request, the raw response with its metadata, and the diagnostics that
+ * distinguish the common causes (budget spent on hidden reasoning vs. a refused tool
+ * call vs. an empty content array).
+ */
+export declare const buildNullReport: (p: NullReportParams) => NullCapture;
+/**
+ * Print the diagnostics of a null result, and hand the full capture to the spectator
+ * sink when the caller opted into capturing. A failing sink must never mask the model
+ * error the caller is about to throw.
+ */
+export declare const reportNull: (spectator: LlmSpectator, captureNull: boolean, p: NullReportParams) => Promise<void>;
+//# sourceMappingURL=null-report.d.ts.map

package/build/utils/null-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-report.d.ts","sourceRoot":"","sources":["../../src/utils/null-report.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAA;AAEhF,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,0FAA0F;IAC1F,OAAO,EAAE,aAAa,CAAA;IACtB,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAC5B,IAAI,EAAE,oBAAoB,EAAE,CAAA;IAC5B,GAAG,EAAE,cAAc,GAAG,IAAI,CAAA;IAC1B,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAA;IACnD,QAAQ,EAAE,OAAO,CAAA;CAClB;AAKD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,gBAAgB,KAAG,WA4DrD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GACrB,WAAW,YAAY,EACvB,aAAa,OAAO,EACpB,GAAG,gBAAgB,KAClB,OAAO,CAAC,IAAI,CAsBd,CAAA"}

package/build/utils/null-report.js

@@ -0,0 +1,84 @@
+import util from 'util';
+import { createIdOfLength } from '@owlmeans/basic-ids';
+/** How many characters of each prompt message the console preview keeps. */
+const PREVIEW_CHARS = 300;
+/**
+ * Assemble a complete, replayable record of a model call that returned nothing usable:
+ * the effective request, the raw response with its metadata, and the diagnostics that
+ * distinguish the common causes (budget spent on hidden reasoning vs. a refused tool
+ * call vs. an empty content array).
+ */
+export const buildNullReport = (p) => {
+    const kwargs = p.refined.lc_kwargs;
+    const raw = p.raw;
+    const responseMeta = raw?.response_metadata;
+    const usageMeta = raw?.usage_metadata;
+    const toolCalls = raw?.tool_calls;
+    return {
+        meta: {
+            kind: p.kind,
+            action: p.action,
+            purpose: p.purpose,
+            attempt: p.attempt,
+            id: createIdOfLength(12),
+            timestamp: Date.now(),
+            elapsedMs: Date.now() - p.startedAt,
+        },
+        model: {
+            // The provider-side model slug (needed for replay); falls back to the config alias.
+            id: kwargs.model ?? p.config.model,
+            provider: p.config.provider,
+            baseUrl: kwargs.configuration?.baseURL,
+            maxTokens: p.refined.maxTokens,
+            reasoning: kwargs.modelKwargs?.reasoning,
+            temperature: p.refined.temperature,
+            topP: kwargs.topP,
+        },
+        request: {
+            messages: p.msgs,
+            schema: p.schema,
+            useCache: p.useCache,
+        },
+        response: raw != null ? {
+            content: raw.content,
+            additional_kwargs: raw.additional_kwargs,
+            response_metadata: raw.response_metadata,
+            usage_metadata: raw.usage_metadata,
+            tool_calls: toolCalls,
+        } : null,
+        diagnostics: {
+            finishReason: responseMeta?.finish_reason,
+            inputTokens: usageMeta?.input_tokens ?? responseMeta?.usage?.prompt_tokens,
+            outputTokens: usageMeta?.output_tokens ?? responseMeta?.usage?.completion_tokens,
+            reasoningTokens: responseMeta?.usage?.reasoning_tokens,
+            contentEmpty: raw == null || raw.content === '' || raw.content == null
+                || (Array.isArray(raw.content) && raw.content.length === 0),
+            hadToolCall: Array.isArray(toolCalls) && toolCalls.length > 0,
+        },
+    };
+};
+/**
+ * Print the diagnostics of a null result, and hand the full capture to the spectator
+ * sink when the caller opted into capturing. A failing sink must never mask the model
+ * error the caller is about to throw.
+ */
+export const reportNull = async (spectator, captureNull, p) => {
+    const capture = buildNullReport(p);
+    const requestPreview = p.msgs.map(msg => {
+        const text = typeof msg.content === 'string' ? msg.content.substring(0, PREVIEW_CHARS) : '[complex content]';
+        return `[${msg.role ?? 'unknown'}] ${text}`;
+    }).join('\n---\n');
+    console.error('[MODEL-NULL]', util.inspect({
+        meta: capture.meta, model: capture.model, diagnostics: capture.diagnostics,
+        response: capture.response, requestPreview,
+    }, { depth: null, maxStringLength: 2000, breakLength: 120 }));
+    if (captureNull) {
+        try {
+            await spectator.captureNull?.(capture);
+        }
+        catch (e) {
+            console.warn('[MODEL-NULL] capture write failed', e);
+        }
+    }
+};
+//# sourceMappingURL=null-report.js.map

package/build/utils/null-report.js.map

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

package/build/utils/prompt.d.ts

@@ -0,0 +1,15 @@
+import type { MessageFieldWithRole } from '@langchain/core/messages';
+/**
+ * Ensure the word "json" appears somewhere in the prompt. Several providers refuse or
+ * silently ignore a JSON mode unless it does; when it is missing the JSON instruction is
+ * appended in place.
+ */
+export declare const ensureJsonMention: (msgs: MessageFieldWithRole[]) => void;
+/**
+ * Append the `/no_think` soft switch when the config asks for it. Without it,
+ * thinking-mode models frequently spend their entire output budget on hidden reasoning
+ * and return empty content with `finish_reason="length"`, which then fails every filter
+ * and exhausts the retries.
+ */
+export declare const applyNoThink: (msgs: MessageFieldWithRole[], disableThinking: boolean | undefined) => void;
+//# sourceMappingURL=prompt.d.ts.map

package/build/utils/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/utils/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAyBpE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,oBAAoB,EAAE,KAAG,IAGhE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,oBAAoB,EAAE,EAAE,iBAAiB,OAAO,GAAG,SAAS,KAAG,IAIjG,CAAA"}

package/build/utils/prompt.js

@@ -0,0 +1,45 @@
+import { JSON_INSTRUCTION, NO_THINK_DIRECTIVE } from '../consts.js';
+const messageMentions = (msg, needle) => {
+    if (typeof msg.content === 'string')
+        return msg.content.toLowerCase().includes(needle);
+    if (Array.isArray(msg.content)) {
+        return msg.content.some((part) => typeof part === 'object' && part !== null && 'text' in part
+            && typeof part.text === 'string'
+            && part.text.toLowerCase().includes(needle));
+    }
+    return false;
+};
+/** Append `text` to the last message, or push it as a new user message when that is not possible. */
+const appendDirective = (msgs, text) => {
+    const last = msgs[msgs.length - 1];
+    if (last != null && typeof last.content === 'string') {
+        last.content = `${last.content}\n${text}`;
+    }
+    else {
+        msgs.push({ role: 'user', content: text });
+    }
+};
+/**
+ * Ensure the word "json" appears somewhere in the prompt. Several providers refuse or
+ * silently ignore a JSON mode unless it does; when it is missing the JSON instruction is
+ * appended in place.
+ */
+export const ensureJsonMention = (msgs) => {
+    if (msgs.some(msg => messageMentions(msg, 'json')))
+        return;
+    appendDirective(msgs, JSON_INSTRUCTION);
+};
+/**
+ * Append the `/no_think` soft switch when the config asks for it. Without it,
+ * thinking-mode models frequently spend their entire output budget on hidden reasoning
+ * and return empty content with `finish_reason="length"`, which then fails every filter
+ * and exhausts the retries.
+ */
+export const applyNoThink = (msgs, disableThinking) => {
+    if (disableThinking !== true)
+        return;
+    if (msgs.some(msg => typeof msg.content === 'string' && msg.content.includes(NO_THINK_DIRECTIVE)))
+        return;
+    appendDirective(msgs, NO_THINK_DIRECTIVE);
+};
+//# sourceMappingURL=prompt.js.map

package/build/utils/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/utils/prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEnE,MAAM,eAAe,GAAG,CAAC,GAAyB,EAAE,MAAc,EAAW,EAAE;IAC7E,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACtF,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CACrB,CAAC,IAAa,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAK,IAAgC;eACtG,OAAQ,IAA+B,CAAC,IAAI,KAAK,QAAQ;eACxD,IAA+B,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAC1E,CAAA;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,qGAAqG;AACrG,MAAM,eAAe,GAAG,CAAC,IAA4B,EAAE,IAAY,EAAQ,EAAE;IAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAClC,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAA;IAC3C,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5C,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAA4B,EAAQ,EAAE;IACtE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAAE,OAAM;IAC1D,eAAe,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;AACzC,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAA4B,EAAE,eAAoC,EAAQ,EAAE;IACvG,IAAI,eAAe,KAAK,IAAI;QAAE,OAAM;IACpC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAAE,OAAM;IACzG,eAAe,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAA;AAC3C,CAAC,CAAA"}

package/build/utils/schema.d.ts

@@ -0,0 +1,20 @@
+import type { Ajv, JSONSchemaType, ValidateFunction } from 'ajv';
+/**
+ * Split the caller's schema into the optional wrapper `name` and the schema proper, and
+ * compile a validator for the latter. A `name` means the model is expected to answer
+ * `{ [name]: <object> }`; see {@link unwrapNamed}.
+ */
+export declare const resolveSchemaValidator: <T>(ajv: Ajv, schema: JSONSchemaType<T>) => {
+    name: string | undefined;
+    innerSchema: JSONSchemaType<T>;
+    validate: ValidateFunction<T>;
+};
+/**
+ * Derive a function/tool name for tool-calling structured output. Provider tool names
+ * must match `^[A-Za-z0-9_-]+$`, so the schema title/name is sanitised; falls back to
+ * {@link DEFAULT_TOOL_NAME} when nothing usable is present.
+ */
+export declare const toToolName: (raw: string | undefined) => string;
+/** Unwrap `{ [name]: value }` when the schema declared a wrapper name. */
+export declare const unwrapNamed: <T>(result: T, name: string | undefined) => T;
+//# sourceMappingURL=schema.d.ts.map

package/build/utils/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAGhE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,CAAC,EAAE,KAAK,GAAG,EAAE,QAAQ,cAAc,CAAC,CAAC,CAAC,KAAG;IAC9E,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;IAC9B,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAA;CAK9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,MAGpD,CAAA;AAED,0EAA0E;AAC1E,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,KAAG,CAKpE,CAAA"}

package/build/utils/schema.js

@@ -0,0 +1,28 @@
+import { DEFAULT_TOOL_NAME } from '../consts.js';
+/**
+ * Split the caller's schema into the optional wrapper `name` and the schema proper, and
+ * compile a validator for the latter. A `name` means the model is expected to answer
+ * `{ [name]: <object> }`; see {@link unwrapNamed}.
+ */
+export const resolveSchemaValidator = (ajv, schema) => {
+    const { name, ...innerSchema } = schema;
+    const validate = ajv.compile(innerSchema);
+    return { name, innerSchema: innerSchema, validate };
+};
+/**
+ * Derive a function/tool name for tool-calling structured output. Provider tool names
+ * must match `^[A-Za-z0-9_-]+$`, so the schema title/name is sanitised; falls back to
+ * {@link DEFAULT_TOOL_NAME} when nothing usable is present.
+ */
+export const toToolName = (raw) => {
+    const cleaned = (raw ?? '').replace(/[^A-Za-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+    return cleaned.length > 0 ? cleaned : DEFAULT_TOOL_NAME;
+};
+/** Unwrap `{ [name]: value }` when the schema declared a wrapper name. */
+export const unwrapNamed = (result, name) => {
+    if (name != null && result != null && typeof result === 'object' && name in result) {
+        return result[name];
+    }
+    return result;
+};
+//# sourceMappingURL=schema.js.map

package/build/utils/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAI,GAAQ,EAAE,MAAyB,EAI3E,EAAE;IACF,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,EAAE,GAAG,MAA+C,CAAA;IAChF,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAI,WAAgC,CAAC,CAAA;IACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,WAAgC,EAAE,QAAQ,EAAE,CAAA;AAC1E,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAuB,EAAU,EAAE;IAC5D,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IACpF,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAA;AACzD,CAAC,CAAA;AAED,0EAA0E;AAC1E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAI,MAAS,EAAE,IAAwB,EAAK,EAAE;IACvE,IAAI,IAAI,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,IAAI,IAAK,MAAkC,EAAE,CAAC;QAChH,OAAQ,MAAkC,CAAC,IAAI,CAAM,CAAA;IACvD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/build/utils/stream.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract `finish_reason` from a stream chunk regardless of whether it is a plain
+ * `AIMessageChunk` (ask/talk) or a `{ raw, parsed }` combined chunk (structured output).
+ */
+export declare const getChunkFinishReason: (chunk: unknown) => string | undefined;
+/**
+ * Iterate a model stream under an IDLE (inactivity) deadline. `start` receives an
+ * `AbortSignal` to forward to `model.stream(..., { signal })`; the timer is re-armed on
+ * every received chunk, so it only fires after `timeoutMs` of SILENCE — a provider that
+ * accepted the request but stalls and never streams another token. On fire the call is
+ * aborted and surfaced as a retryable {@link LlmModelError} so the retry escalator moves
+ * on instead of hanging forever. Because the timer resets per token, long but actively
+ * streaming generations are never aborted.
+ *
+ * The loop also breaks after the first chunk carrying a non-empty `finish_reason`. Some
+ * providers send the final SSE data event twice, which makes `AIMessageChunk.concat()`
+ * double-append every string field (`finish_reason` becomes `'stopstop'`, the model name
+ * doubles) and corrupts accumulated tool-call argument strings, breaking structured-output
+ * parsing. Nothing meaningful arrives after `finish_reason`, so breaking there is safe.
+ */
+export declare function streamWithDeadline<T>(start: (signal: AbortSignal) => Promise<AsyncIterable<T>>, timeoutMs?: number): AsyncGenerator<T>;
+//# sourceMappingURL=stream.d.ts.map

package/build/utils/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAM9D,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAuB,kBAAkB,CAAC,CAAC,EACzC,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EACzD,SAAS,GAAE,MAAgC,GAC1C,cAAc,CAAC,CAAC,CAAC,CAwBnB"}

package/build/utils/stream.js

@@ -0,0 +1,54 @@
+import { LlmModelError } from '../errors.js';
+import { MODEL_STREAM_TIMEOUT_MS } from '../consts.js';
+/**
+ * Extract `finish_reason` from a stream chunk regardless of whether it is a plain
+ * `AIMessageChunk` (ask/talk) or a `{ raw, parsed }` combined chunk (structured output).
+ */
+export const getChunkFinishReason = (chunk) => {
+    const c = chunk;
+    return c.response_metadata?.finish_reason ?? c.raw?.response_metadata?.finish_reason;
+};
+/**
+ * Iterate a model stream under an IDLE (inactivity) deadline. `start` receives an
+ * `AbortSignal` to forward to `model.stream(..., { signal })`; the timer is re-armed on
+ * every received chunk, so it only fires after `timeoutMs` of SILENCE — a provider that
+ * accepted the request but stalls and never streams another token. On fire the call is
+ * aborted and surfaced as a retryable {@link LlmModelError} so the retry escalator moves
+ * on instead of hanging forever. Because the timer resets per token, long but actively
+ * streaming generations are never aborted.
+ *
+ * The loop also breaks after the first chunk carrying a non-empty `finish_reason`. Some
+ * providers send the final SSE data event twice, which makes `AIMessageChunk.concat()`
+ * double-append every string field (`finish_reason` becomes `'stopstop'`, the model name
+ * doubles) and corrupts accumulated tool-call argument strings, breaking structured-output
+ * parsing. Nothing meaningful arrives after `finish_reason`, so breaking there is safe.
+ */
+export async function* streamWithDeadline(start, timeoutMs = MODEL_STREAM_TIMEOUT_MS) {
+    const controller = new AbortController();
+    let timer;
+    const arm = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(), timeoutMs);
+    };
+    arm();
+    try {
+        const stream = await start(controller.signal);
+        for await (const chunk of stream) {
+            arm(); // reset the idle timer on each received token
+            yield chunk;
+            const reason = getChunkFinishReason(chunk);
+            if (reason != null && reason !== '')
+                break;
+        }
+    }
+    catch (e) {
+        if (controller.signal.aborted) {
+            throw new LlmModelError(`stream-stalled:no token for ${timeoutMs}ms (idle deadline)`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=stream.js.map

package/build/utils/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAsB,EAAE;IACzE,MAAM,CAAC,GAAG,KAGT,CAAA;IACD,OAAO,CAAC,CAAC,iBAAiB,EAAE,aAAa,IAAI,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,aAAa,CAAA;AACtF,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,kBAAkB,CACvC,KAAyD,EACzD,YAAoB,uBAAuB;IAE3C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;IACxC,IAAI,KAAoC,CAAA;IACxC,MAAM,GAAG,GAAG,GAAG,EAAE;QACf,YAAY,CAAC,KAAK,CAAC,CAAA;QACnB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;IACzD,CAAC,CAAA;IACD,GAAG,EAAE,CAAA;IACL,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACjC,GAAG,EAAE,CAAA,CAAC,8CAA8C;YACpD,MAAM,KAAK,CAAA;YACX,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAA;YAC1C,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,EAAE;gBAAE,MAAK;QAC5C,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,aAAa,CAAC,+BAA+B,SAAS,oBAAoB,CAAC,CAAA;QACvF,CAAC;QACD,MAAM,CAAC,CAAA;IACT,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAM,CAAC,CAAA;IACtB,CAAC;AACH,CAAC"}