@vinhnt-sdk/llm 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Thanh Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapter.d.ts

@@ -0,0 +1,172 @@
+/**
+ * LLM Adapter — the abstract contract every provider must implement.
+ *
+ * An adapter is the minimal interface for streaming model calls.
+ * The only required method is `stream()`. Everything else has defaults.
+ *
+ * This is the "Service Definition" in the capability seam pattern:
+ *   Service Definition (LlmAdapter) → Provider (concrete) → Consumer (agent loop)
+ *
+ * @example
+ * ```ts
+ * import type { LlmAdapter, GenerateOptions, StreamChunk } from "@vinhnt-sdk/llm";
+ *
+ * class MyAdapter implements LlmAdapter {
+ *   async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+ *     // Call your LLM API here
+ *     yield { type: "text", content: "Hello" };
+ *     yield { type: "finish", reason: "stop" };
+ *   }
+ * }
+ * ```
+ */
+import type { ModelCapabilities } from "@vinhnt-sdk/schema";
+/**
+ * Options for a model generation call.
+ * This is the adapter's view of the request — provider-owned fields
+ * (model, apiKey, baseUrl) are resolved before reaching the adapter.
+ */
+export interface GenerateOptions {
+    /** The provider/model identifier (e.g., "deepseek-chat", "gpt-4o"). */
+    readonly model: string;
+    /** Conversation messages. */
+    readonly messages: readonly {
+        readonly role: string;
+        readonly content: string | readonly unknown[];
+        readonly [key: string]: unknown;
+    }[];
+    /** Tool definitions (OpenAI function calling format). */
+    readonly tools?: readonly {
+        readonly type: "function";
+        readonly function: {
+            readonly name: string;
+            readonly description: string;
+            readonly parameters?: unknown;
+            readonly strict?: boolean;
+        };
+    }[];
+    /** Tool choice control. */
+    readonly toolChoice?: "auto" | "required" | "none" | {
+        readonly type: "function";
+        readonly function: {
+            readonly name: string;
+        };
+    };
+    /** Max completion tokens. */
+    readonly maxTokens?: number;
+    /** Temperature (0-2). */
+    readonly temperature?: number;
+    /** Top-p sampling. */
+    readonly topP?: number;
+    /** Stop sequences. */
+    readonly stop?: readonly string[];
+    /** Reasoning effort for o-series models. */
+    readonly reasoningEffort?: string;
+    /** Stream options (include_usage, etc.). */
+    readonly streamOptions?: {
+        readonly includeUsage?: boolean;
+    };
+    /** Provider-specific options passthrough. */
+    readonly providerOptions?: Record<string, unknown>;
+}
+/**
+ * Raw streaming chunk emitted by an adapter.
+ * This is the adapter → runtime protocol.
+ */
+export type StreamChunk = {
+    readonly type: "text";
+    readonly content: string;
+} | {
+    readonly type: "reasoning";
+    readonly content: string;
+} | {
+    readonly type: "tool-call";
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+} | {
+    readonly type: "usage";
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly reasoningTokens?: number;
+} | {
+    readonly type: "finish";
+    readonly reason: "stop" | "tool-calls" | "max-tokens" | "error" | "aborted";
+} | {
+    readonly type: "error";
+    readonly error: string;
+};
+/**
+ * Provider retry policy — captured at registration time.
+ */
+export interface RetryPolicy {
+    /** Maximum number of retries. Default: 2. */
+    readonly maxRetries?: number;
+    /** Base delay in ms for exponential backoff. Default: 1000. */
+    readonly baseDelayMs?: number;
+    /** Maximum delay cap in ms. Default: 30000. */
+    readonly maxDelayMs?: number;
+    /** HTTP status codes that are retryable. */
+    readonly retryableStatuses?: readonly number[];
+}
+/**
+ * Provider metadata — returned by `providerInfo()`.
+ */
+export interface ProviderInfo {
+    /** Provider identifier (e.g., "deepseek", "openai", "anthropic"). */
+    readonly id: string;
+    /** Human-readable display name. */
+    readonly name: string;
+}
+/**
+ * Resolved model info — returned by `resolveModel()`.
+ */
+export interface ResolvedModelInfo {
+    /** Provider identifier. */
+    readonly provider: string;
+    /** Model identifier. */
+    readonly id: string;
+    /** Human-readable model name. */
+    readonly name: string;
+    /** Context window in tokens. */
+    readonly contextWindow?: number;
+    /** Model capabilities. */
+    readonly capabilities?: Partial<ModelCapabilities>;
+}
+/**
+ * Abstract LLM adapter — the Service Definition for model providers.
+ *
+ * Every provider implements this interface. The only required method is `stream()`.
+ * Everything else has sensible defaults.
+ *
+ * Adapters are stateless — all configuration is captured at registration time.
+ * The adapter receives only the `GenerateOptions` per call.
+ */
+export declare abstract class LlmAdapter {
+    /**
+     * Stream one model call as raw chunks (token-level deltas).
+     * This is the ONLY required method.
+     */
+    abstract stream(options: GenerateOptions, signal?: AbortSignal): AsyncIterable<StreamChunk>;
+    /**
+     * Provider metadata — used for display and logging.
+     * Default: `{ id: "unknown", name: "Unknown Provider" }`.
+     */
+    providerInfo(provider: string): ProviderInfo;
+    /**
+     * Provider-specific retry policy — captured at registration time.
+     * Default: undefined (use global defaults).
+     */
+    providerRetryPolicy(provider: string): RetryPolicy | undefined;
+    /**
+     * List available models for a provider.
+     * Default: empty array.
+     */
+    listModels(provider: string): Promise<readonly ResolvedModelInfo[]>;
+    /**
+     * Resolve a model identifier to full info.
+     * Default: returns the model id as-is.
+     */
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<ResolvedModelInfo>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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

package/dist/adapter.js

@@ -0,0 +1,62 @@
+/**
+ * LLM Adapter — the abstract contract every provider must implement.
+ *
+ * An adapter is the minimal interface for streaming model calls.
+ * The only required method is `stream()`. Everything else has defaults.
+ *
+ * This is the "Service Definition" in the capability seam pattern:
+ *   Service Definition (LlmAdapter) → Provider (concrete) → Consumer (agent loop)
+ *
+ * @example
+ * ```ts
+ * import type { LlmAdapter, GenerateOptions, StreamChunk } from "@vinhnt-sdk/llm";
+ *
+ * class MyAdapter implements LlmAdapter {
+ *   async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+ *     // Call your LLM API here
+ *     yield { type: "text", content: "Hello" };
+ *     yield { type: "finish", reason: "stop" };
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Abstract LLM adapter — the Service Definition for model providers.
+ *
+ * Every provider implements this interface. The only required method is `stream()`.
+ * Everything else has sensible defaults.
+ *
+ * Adapters are stateless — all configuration is captured at registration time.
+ * The adapter receives only the `GenerateOptions` per call.
+ */
+export class LlmAdapter {
+    /**
+     * Provider metadata — used for display and logging.
+     * Default: `{ id: "unknown", name: "Unknown Provider" }`.
+     */
+    providerInfo(provider) {
+        return { id: provider, name: provider };
+    }
+    /**
+     * Provider-specific retry policy — captured at registration time.
+     * Default: undefined (use global defaults).
+     */
+    providerRetryPolicy(provider) {
+        return undefined;
+    }
+    /**
+     * List available models for a provider.
+     * Default: empty array.
+     */
+    async listModels(provider) {
+        return [];
+    }
+    /**
+     * Resolve a model identifier to full info.
+     * Default: returns the model id as-is.
+     */
+    async resolveModel(provider, model, signal) {
+        return { provider, id: model, name: model };
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAiGH;;;;;;;;GAQG;AACH,MAAM,OAAgB,UAAU;IAO9B;;;OAGG;IACH,YAAY,CAAC,QAAgB;QAC3B,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,mBAAmB,CAAC,QAAgB;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,QAAgB;QAC/B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,KAAa,EAAE,MAAoB;QACtE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC9C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type GenerateOptions, type StreamChunk, type RetryPolicy, type ProviderInfo, type ResolvedModelInfo, LlmAdapter, } from "./adapter.js";
+export { type AdapterRegistrationHandle, LlmRegistry, AdapterRegistrationError, } from "./registry.js";
+export { shouldRetry, calculateDelay, sleep, } from "./retry.js";
+export { TokenMeter } from "./token-meter.js";
+export { ModelCaller, type ModelCallerDeps, type ModelCallerPluginHooks, type ModelCallerLogger, } from "./model-caller.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,yBAAyB,EAC9B,WAAW,EACX,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,cAAc,EACd,KAAK,GACN,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @vinhnt-sdk/llm
+// LLM capability seam — adapter abstraction, registry, retry, token metering, model caller
+export { LlmAdapter, } from "./adapter.js";
+export { LlmRegistry, AdapterRegistrationError, } from "./registry.js";
+export { shouldRetry, calculateDelay, sleep, } from "./retry.js";
+export { TokenMeter } from "./token-meter.js";
+// Re-export ModelCaller (previously in @vinhnt-sdk/model-caller)
+export { ModelCaller, } from "./model-caller.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kBAAkB;AAClB,2FAA2F;AAE3F,OAAO,EAML,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,WAAW,EACX,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,cAAc,EACd,KAAK,GACN,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,iEAAiE;AACjE,OAAO,EACL,WAAW,GAIZ,MAAM,mBAAmB,CAAC"}

package/dist/model-caller.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module @vinhnt-sdk/model-caller
+ * Model caller kernel primitive: build requests, run non-streaming/streaming
+ * generation, fire model-call hooks, count tokens and emit token/cost events.
+ */
+import type { RunId, RequestContext, KnownRunEvent, ToolChoice, ResponseFormat, StreamOptions } from "@vinhnt-sdk/schema";
+import type { ChatMessage, ModelProvider, ModelResponse, ModelRegistry } from "@vinhnt-sdk/schema";
+import type { ToolDefinition } from "@vinhnt-sdk/tools";
+/**
+ * Minimal structural hook surface used by the model caller.
+ *
+ * Hosts (e.g. core's `PluginManager`) only need to implement `fireHook` for
+ * the model-call hook names; no direct dependency on the full plugin contract.
+ */
+export interface ModelCallerPluginHooks {
+    fireHook(name: "onChatParams" | "onBeforeModelCall" | "onAfterModelCall" | "onTokenStreamed", data: Record<string, unknown>): Promise<{
+        modified: Record<string, unknown>;
+    } | null>;
+}
+/** Minimal structural logger used by the model caller (host Logger satisfies it). */
+export interface ModelCallerLogger {
+    info(message: string, ...args: unknown[]): void;
+}
+/** Dependencies required by {@link ModelCaller}. */
+export interface ModelCallerDeps {
+    defaultModel: ModelProvider;
+    readonly modelRegistry: ModelRegistry | undefined;
+    maxTokens: number;
+    thinkingBudget: number;
+    thinkingPrompt: string;
+    readonly pluginManager: ModelCallerPluginHooks | undefined;
+    readonly logger: ModelCallerLogger | undefined;
+    emitEvent(event: Omit<KnownRunEvent, "sequence">, persist?: boolean): Promise<void>;
+    modelForRun(runId: RunId): ModelProvider | undefined;
+    setModelForRun(runId: RunId, model: ModelProvider): void;
+    getAvailableTools(runId: RunId): readonly ToolDefinition[];
+    /** OpenAI: tool_choice — controls tool calling behavior. */
+    readonly toolChoice?: ToolChoice;
+    /** OpenAI: parallel_tool_calls — whether to allow parallel tool calls. */
+    readonly parallelToolCalls?: boolean;
+    /** OpenAI: response_format — controls output format. */
+    readonly responseFormat?: ResponseFormat;
+    /** OpenAI: stream_options — options for streaming. */
+    readonly streamOptions?: StreamOptions;
+    /** OpenAI: presence_penalty — penalizes tokens based on presence. */
+    readonly presencePenalty?: number;
+    /** OpenAI: frequency_penalty — penalizes tokens based on frequency. */
+    readonly frequencyPenalty?: number;
+    /** OpenAI: logit_bias — token-level logit biases. */
+    readonly logitBias?: Record<string, number>;
+    /** OpenAI: seed — for reproducible outputs. */
+    readonly seed?: number;
+    /** OpenAI: user — end-user identifier. */
+    readonly user?: string;
+    /** OpenAI: logprobs — return log probabilities. */
+    readonly logprobs?: boolean;
+    /** OpenAI: top_logprobs — number of top logprobs per token. */
+    readonly topLogprobs?: number;
+    /** OpenAI: max_completion_tokens — for o-series models. */
+    readonly maxCompletionTokens?: number;
+    /** OpenAI: reasoning_effort — controls reasoning token budget. */
+    readonly reasoningEffort?: string;
+}
+/** Runs model generation (streaming and non-streaming) with hooks, token counting and cost/token events. */
+export declare class ModelCaller {
+    private readonly deps;
+    constructor(deps: ModelCallerDeps);
+    /** Swap the default model at runtime (config hot-reload). */
+    setDefaultModel(model: ModelProvider): void;
+    /** Swap runtime-tunable generation settings at runtime (config hot-reload). */
+    setRuntimeOptions(options: Partial<Pick<ModelCallerDeps, "maxTokens" | "thinkingBudget" | "thinkingPrompt">>): void;
+    getDefaultModel(): ModelProvider;
+    resolveAgentModel(agent: {
+        profile: {
+            model?: string;
+        };
+    }, runId?: RunId): ModelProvider;
+    getActiveModel(runId: RunId): ModelProvider;
+    callModelStream(messages: ChatMessage[], step: number, runId: RunId, ctx: RequestContext, signal: AbortSignal, agentMaxTokens?: number, disableTools?: boolean): Promise<ModelResponse>;
+    doThinkingStep(messages: ChatMessage[], step: number, runId: RunId, ctx: RequestContext, signal: AbortSignal): Promise<void>;
+    calculateCost(inputTokens: number, outputTokens: number, model?: ModelProvider): number | undefined;
+}
+//# sourceMappingURL=model-caller.d.ts.map

package/dist/model-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-caller.d.ts","sourceRoot":"","sources":["../src/model-caller.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE1H,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EAEb,aAAa,EACb,aAAa,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CACN,IAAI,EAAE,cAAc,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,iBAAiB,EACnF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjD;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC/C,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,SAAS,CAAC;IACrD,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACzD,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,cAAc,EAAE,CAAC;IAC3D,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,sDAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAkBD,4GAA4G;AAC5G,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,eAAe;IAElD,6DAA6D;IAC7D,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAI3C,+EAA+E;IAC/E,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,gBAAgB,GAAG,gBAAgB,CAAC,CAAC,GAAG,IAAI;IAMnH,eAAe,IAAI,aAAa;IAIhC,iBAAiB,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,aAAa;IAavF,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa;IAIrC,eAAe,CACnB,QAAQ,EAAE,WAAW,EAAE,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,WAAW,EACnB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,OAAO,GACrB,OAAO,CAAC,aAAa,CAAC;IA2KnB,cAAc,CAClB,QAAQ,EAAE,WAAW,EAAE,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC;IA4DhB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS;CAOpG"}

package/dist/model-caller.js

@@ -0,0 +1,276 @@
+/**
+ * @module @vinhnt-sdk/model-caller
+ * Model caller kernel primitive: build requests, run non-streaming/streaming
+ * generation, fire model-call hooks, count tokens and emit token/cost events.
+ */
+import { VntError } from "@vinhnt-sdk/schema";
+import { getTextContent } from "@vinhnt-sdk/schema";
+function emitTC(runId, traceId, data) {
+    return { id: crypto.randomUUID(), runId, type: "token.counted", occurredAt: new Date().toISOString(), traceId, data };
+}
+function emitMC(runId, traceId, data) {
+    return { id: crypto.randomUUID(), runId, type: "model.cost", occurredAt: new Date().toISOString(), traceId, data };
+}
+/** Runs model generation (streaming and non-streaming) with hooks, token counting and cost/token events. */
+export class ModelCaller {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Swap the default model at runtime (config hot-reload). */
+    setDefaultModel(model) {
+        this.deps.defaultModel = model;
+    }
+    /** Swap runtime-tunable generation settings at runtime (config hot-reload). */
+    setRuntimeOptions(options) {
+        if (options.maxTokens !== undefined)
+            this.deps.maxTokens = options.maxTokens;
+        if (options.thinkingBudget !== undefined)
+            this.deps.thinkingBudget = options.thinkingBudget;
+        if (options.thinkingPrompt !== undefined)
+            this.deps.thinkingPrompt = options.thinkingPrompt;
+    }
+    getDefaultModel() {
+        return this.deps.defaultModel;
+    }
+    resolveAgentModel(agent, runId) {
+        const preferred = agent?.profile?.model;
+        if (preferred && this.deps.modelRegistry) {
+            const provider = this.deps.modelRegistry.get(preferred);
+            if (provider) {
+                if (runId)
+                    this.deps.setModelForRun(runId, provider);
+                return provider;
+            }
+        }
+        if (runId)
+            this.deps.setModelForRun(runId, this.deps.defaultModel);
+        return this.deps.defaultModel;
+    }
+    getActiveModel(runId) {
+        return this.deps.modelForRun(runId) ?? this.deps.defaultModel;
+    }
+    async callModelStream(messages, step, runId, ctx, signal, agentMaxTokens, disableTools) {
+        const availableTools = disableTools ? [] : this.deps.getAvailableTools(runId);
+        const thinkingBudget = this.deps.thinkingBudget > 0 ? this.deps.thinkingBudget : undefined;
+        let request = {
+            messages, tools: availableTools, maxTokens: agentMaxTokens ?? this.deps.maxTokens,
+            ...(thinkingBudget !== undefined ? { thinkingBudget } : {}),
+            ...(this.deps.thinkingPrompt ? { thinkingPrompt: this.deps.thinkingPrompt } : {}),
+            // OpenAI fields passthrough
+            ...(this.deps.toolChoice !== undefined ? { toolChoice: this.deps.toolChoice } : {}),
+            ...(this.deps.parallelToolCalls !== undefined ? { parallelToolCalls: this.deps.parallelToolCalls } : {}),
+            ...(this.deps.responseFormat !== undefined ? { responseFormat: this.deps.responseFormat } : {}),
+            ...(this.deps.streamOptions !== undefined ? { streamOptions: this.deps.streamOptions } : {}),
+            ...(this.deps.presencePenalty !== undefined ? { presencePenalty: this.deps.presencePenalty } : {}),
+            ...(this.deps.frequencyPenalty !== undefined ? { frequencyPenalty: this.deps.frequencyPenalty } : {}),
+            ...(this.deps.logitBias !== undefined ? { logitBias: this.deps.logitBias } : {}),
+            ...(this.deps.seed !== undefined ? { seed: this.deps.seed } : {}),
+            ...(this.deps.user !== undefined ? { user: this.deps.user } : {}),
+            ...(this.deps.logprobs !== undefined ? { logprobs: this.deps.logprobs } : {}),
+            ...(this.deps.topLogprobs !== undefined ? { topLogprobs: this.deps.topLogprobs } : {}),
+            ...(this.deps.maxCompletionTokens !== undefined ? { maxCompletionTokens: this.deps.maxCompletionTokens } : {}),
+            ...(this.deps.reasoningEffort !== undefined ? { reasoningEffort: this.deps.reasoningEffort } : {}),
+        };
+        const chatParamsResult = await this.deps.pluginManager?.fireHook("onChatParams", {
+            request: request,
+        });
+        if (chatParamsResult?.modified?.request) {
+            request = chatParamsResult.modified.request;
+        }
+        // P1-F: onBeforeModelCall — intercept/modify the request right before the model call.
+        const beforeCallResult = await this.deps.pluginManager?.fireHook("onBeforeModelCall", {
+            request: request,
+        });
+        if (beforeCallResult?.modified?.request) {
+            request = beforeCallResult.modified.request;
+        }
+        const model = this.getActiveModel(runId);
+        const modelName = model.model ?? "unknown";
+        const startTime = performance.now();
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let reasoningTokens = 0;
+        const modelHasTokens = !!model.countTokens;
+        // RV-42: the input count here is only a local FALLBACK estimate — the
+        // authoritative `token.counted` is emitted exactly once per call, after the
+        // model call, from the provider-reported usage (or this estimate).
+        if (modelHasTokens) {
+            inputTokens = messages.reduce((sum, m) => sum + model.countTokens(getTextContent(m.content)), 0);
+        }
+        let content = "";
+        const toolCalls = [];
+        if (!model.stream) {
+            const res = await model.generate(request, signal);
+            // P1-F: onAfterModelCall — intercept/modify the response after the model call.
+            const afterCallResult = await this.deps.pluginManager?.fireHook("onAfterModelCall", {
+                response: res,
+            });
+            const effectiveRes = (afterCallResult?.modified?.response ?? res);
+            let source = "api";
+            const input = effectiveRes.usage?.inputTokens ?? effectiveRes.usage?.promptTokens ?? 0;
+            const output = effectiveRes.usage?.outputTokens ?? effectiveRes.usage?.completionTokens ?? 0;
+            if (input > 0 && output > 0) {
+                inputTokens = input;
+                outputTokens = output;
+            }
+            else if (modelHasTokens && effectiveRes.content) {
+                const localOut = model.countTokens(effectiveRes.content);
+                if (input > 0)
+                    inputTokens = input;
+                outputTokens = localOut;
+                source = localOut === (output || -1) ? "api" : "local";
+            }
+            await this.deps.emitEvent(emitTC(runId, ctx.traceId, { inputTokens, outputTokens, step, source }));
+            const durationMs = Math.round(performance.now() - startTime);
+            const cost = this.calculateCost(inputTokens, outputTokens, model) ?? 0;
+            await this.deps.emitEvent(emitMC(runId, ctx.traceId, { inputTokens, outputTokens, cost, model: modelName, durationMs, step }));
+            const p = model?.pricing;
+            this.deps.logger?.info(`[llm] ${modelName}: ${inputTokens} in, ${outputTokens} out, $${cost.toFixed(6)}, ${durationMs}ms${p ? ` ($${p.input}/${p.output} per 1M)` : ""}`);
+            // RV-42: surface the authoritative usage on the response when the provider
+            // did not already report it, so the run loop can budget without countTokens.
+            return effectiveRes.usage
+                ? effectiveRes
+                : inputTokens > 0 || outputTokens > 0
+                    ? { ...effectiveRes, usage: { promptTokens: inputTokens, completionTokens: outputTokens } }
+                    : effectiveRes;
+        }
+        for await (const event of model.stream(request, signal)) {
+            if (signal?.aborted)
+                break;
+            switch (event.type) {
+                case "text":
+                    content += event.content;
+                    await this.deps.emitEvent({
+                        id: crypto.randomUUID(), runId, type: "token.streamed",
+                        occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                        data: { content: event.content, step },
+                    }, false);
+                    await this.deps.pluginManager?.fireHook("onTokenStreamed", { content: event.content, step });
+                    break;
+                case "thinking":
+                    // RV-44: DeepSeek reasoner chain-of-thought — surface as
+                    // thinking.content like doThinkingStep, never dropped.
+                    await this.deps.emitEvent({
+                        id: crypto.randomUUID(), runId, type: "thinking.content",
+                        occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                        data: { content: event.content, step },
+                    }, false);
+                    break;
+                case "tool_call":
+                    toolCalls.push({ id: event.id, name: event.name, args: event.args });
+                    break;
+                case "usage":
+                    inputTokens = event.inputTokens;
+                    outputTokens = event.outputTokens;
+                    reasoningTokens = event.reasoningTokens ?? 0;
+                    break;
+                case "done":
+                    break;
+                case "error":
+                    // Surface as a structured, non-retryable error so the circuit
+                    // breaker never retries a truncated/malformed stream.
+                    throw new VntError(event.error, { retryable: false });
+            }
+        }
+        // A cancelled stream must never commit partial content or partially
+        // assembled tool calls as a successful response.
+        if (signal?.aborted) {
+            throw new DOMException("Aborted", "AbortError");
+        }
+        let source = "api";
+        if (outputTokens === 0 && modelHasTokens && content) {
+            outputTokens = model.countTokens(content);
+            source = "local";
+        }
+        // P1-F: onAfterModelCall — intercept/modify the response after streaming completes.
+        // RV-42: attach the authoritative usage (provider-reported or local fallback).
+        const streamedResponse = {
+            ...(toolCalls.length > 0 ? { content, toolCalls } : { content }),
+            ...(inputTokens > 0 || outputTokens > 0
+                ? { usage: { promptTokens: inputTokens, completionTokens: outputTokens, ...(reasoningTokens > 0 ? { reasoningTokens } : {}) } }
+                : {}),
+        };
+        const afterCallResult = await this.deps.pluginManager?.fireHook("onAfterModelCall", {
+            response: streamedResponse,
+        });
+        const effectiveRes = (afterCallResult?.modified?.response ?? streamedResponse);
+        if (inputTokens > 0 || outputTokens > 0) {
+            await this.deps.emitEvent(emitTC(runId, ctx.traceId, { inputTokens, outputTokens, step, source }));
+        }
+        const durationMs = Math.round(performance.now() - startTime);
+        const cost = this.calculateCost(inputTokens, outputTokens, model) ?? 0;
+        await this.deps.emitEvent(emitMC(runId, ctx.traceId, { inputTokens, outputTokens, cost, model: modelName, durationMs, step }));
+        const p = model?.pricing;
+        this.deps.logger?.info(`[llm] ${modelName}: ${inputTokens} in, ${outputTokens} out, $${cost.toFixed(6)}, ${durationMs}ms${p ? ` ($${p.input}/${p.output} per 1M)` : ""}`);
+        // RV-42: a hook may have replaced the response without usage — surface the
+        // authoritative usage so downstream token budgeting is not a no-op.
+        return effectiveRes.usage
+            ? effectiveRes
+            : inputTokens > 0 || outputTokens > 0
+                ? { ...effectiveRes, usage: { promptTokens: inputTokens, completionTokens: outputTokens } }
+                : effectiveRes;
+    }
+    async doThinkingStep(messages, step, runId, ctx, signal) {
+        await this.deps.emitEvent({
+            id: crypto.randomUUID(), runId, type: "thinking.started",
+            occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+            data: { step },
+        });
+        let thinking = "";
+        const thinkModel = this.getActiveModel(runId);
+        if (thinkModel.stream) {
+            for await (const event of thinkModel.stream({ messages: [...messages, { role: "system", content: this.deps.thinkingPrompt }], tools: [] }, signal)) {
+                if (signal?.aborted)
+                    break;
+                if (event.type === "text") {
+                    thinking += event.content;
+                    await this.deps.emitEvent({
+                        id: crypto.randomUUID(), runId, type: "thinking.content",
+                        occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                        data: { content: event.content, step },
+                    }, false);
+                }
+                else if (event.type === "error") {
+                    return;
+                }
+            }
+        }
+        else {
+            try {
+                const res = await thinkModel.generate({ messages: [...messages, { role: "system", content: this.deps.thinkingPrompt }], tools: [], maxTokens: this.deps.thinkingBudget }, signal);
+                thinking = res.content;
+                if (thinking) {
+                    await this.deps.emitEvent({
+                        id: crypto.randomUUID(), runId, type: "thinking.content",
+                        occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+                        data: { content: thinking, step },
+                    }, false);
+                }
+            }
+            catch {
+                return;
+            }
+        }
+        if (thinking.trim()) {
+            messages.push({
+                role: "system",
+                content: `[Thinking from previous pass]\n${thinking.trim()}`,
+            });
+        }
+        await this.deps.emitEvent({
+            id: crypto.randomUUID(), runId, type: "thinking.completed",
+            occurredAt: new Date().toISOString(), traceId: ctx.traceId,
+            data: { content: thinking, step },
+        });
+    }
+    calculateCost(inputTokens, outputTokens, model) {
+        const p = model?.pricing;
+        if (!p)
+            return undefined;
+        const inputCost = (inputTokens * p.input) / 1_000_000;
+        const outputCost = (outputTokens * p.output) / 1_000_000;
+        return Number((inputCost + outputCost).toFixed(6));
+    }
+}
+//# sourceMappingURL=model-caller.js.map