@degreesign/chat 0.5.2 → 0.6.2

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ChatModelId, ChatStatus, LlmBackend, LlmPhase, LlmRole, LlmStatus } from './enums';
+import type { BuiltinTool, ChatModelId, ChatStatus, LlmBackend, LlmPhase, LlmRole, LlmStatus, WebSearchProvider } from './enums';
 /** One chat message, owned by the host */
 interface ChatMessage {
     role: LlmRole;
@@ -8,6 +8,174 @@ interface ChatMessage {
     /** Audio data URLs or URLs attached to the turn */
     audio?: string[];
 }
+/** One JSON-safe value passed to or returned from a tool */
+type ChatToolValue = string | number | boolean | null | ChatToolValue[] | {
+    [key: string]: ChatToolValue;
+};
+/** The JSON-schema subset the model reads for a tool parameter */
+interface ChatToolSchema {
+    type?: `object` | `array` | `string` | `number` | `integer` | `boolean` | `null`;
+    description?: string;
+    properties?: Record<string, ChatToolSchema>;
+    required?: string[];
+    items?: ChatToolSchema;
+    enum?: string[];
+}
+/** One tool the model may call, run by the package or by the host */
+interface ChatTool {
+    /** Unique tool name, the model calls it by this */
+    name: string;
+    /** What the tool does, read by the model before a call */
+    description?: string;
+    parameters?: ChatToolSchema;
+    execute: (args: Record<string, ChatToolValue>) => ChatToolValue | Promise<ChatToolValue>;
+}
+/** One call the model made, with its parsed arguments */
+interface ChatToolCall {
+    id: number;
+    name: string;
+    arguments: Record<string, ChatToolValue>;
+}
+/** One finished tool call, carrying its value or its error */
+interface ChatToolResult extends ChatToolCall {
+    result?: ChatToolValue;
+    error?: string;
+}
+/** Search provider settings of the built-in websearch tool */
+interface WebSearchConfig {
+    provider?: WebSearchProvider;
+    /** Wikipedia language edition, two or three letters plus an optional region */
+    language?: string;
+    /** Results asked of the provider, 1 to 20 */
+    limit?: number;
+    /** Characters kept per snippet */
+    snippetLength?: number;
+    /** Request budget in milliseconds */
+    timeout?: number;
+}
+/** One search hit returned to the model */
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/** Websearch settings with every default and clamp resolved */
+interface WebSearchSettings {
+    provider: WebSearchProvider;
+    language: string;
+    limit: number;
+    snippetLength: number;
+    timeout: number;
+}
+/** Fiat and metal rates of one feed fetch, quoted per EUR */
+interface FiatSnapshot {
+    /** Local fetch time, milliseconds */
+    fetchedAt: number;
+    /** Feed timestamp, milliseconds */
+    sourceAt: number;
+    rates: Record<string, number>;
+    yesterday: Record<string, number>;
+}
+/** Crypto prices of one feed fetch, quoted in EUR per unit */
+interface CryptoSnapshot {
+    fetchedAt: number;
+    sourceAt: number;
+    prices: Record<string, number>;
+    yesterday: Record<string, number>;
+}
+/** The price sections held in memory and in localStorage */
+interface PriceSnapshot {
+    fiat?: FiatSnapshot;
+    crypto?: CryptoSnapshot;
+}
+/** Price sections one request has to read */
+interface PriceSections {
+    fiat: boolean;
+    crypto: boolean;
+}
+/** One conversion returned to the model */
+interface CurrencyResult {
+    from: string;
+    to: string;
+    amount: number;
+    rate: number;
+    previousRate?: number;
+    change?: number;
+    changePercent?: number;
+    result: number;
+    updatedAt: string;
+    stale: boolean;
+}
+/** Tool fields shared by the host input and one generation */
+interface ChatToolParams {
+    /** Extra host tools, appended after the built-ins */
+    tools?: ChatTool[];
+    /** Called before a host or built-in tool runs */
+    onToolCall?: (call: ChatToolCall) => void;
+    /** Called when a tool returns or throws */
+    onToolResult?: (result: ChatToolResult) => void;
+    /** Max tool rounds in one reply, defaults to 4 */
+    maxToolRounds?: number;
+}
+/** Host tools resolved against the built-ins for one request */
+interface ResolvedTools {
+    /** Tools offered to the model, host tools replacing a built-in */
+    tools: ChatTool[];
+    /** Whether the host passed tools of its own */
+    explicit: boolean;
+}
+/** One evaluated arithmetic expression */
+interface CalculationResult {
+    /** Normalized expression that was evaluated */
+    expression: string;
+    result: number;
+}
+/** One page of a Wikipedia search response */
+interface WikipediaPage {
+    key?: string;
+    title?: string;
+    description?: string;
+    excerpt?: string;
+}
+/** One Wikipedia search response */
+interface WikipediaResponse {
+    pages?: WikipediaPage[];
+}
+/** One DuckDuckGo topic, a group carries nested topics */
+interface DuckDuckGoTopic {
+    FirstURL?: string;
+    Text?: string;
+    Topics?: DuckDuckGoTopic[];
+}
+/** One DuckDuckGo instant answer response */
+interface DuckDuckGoResponse {
+    Heading?: string;
+    AbstractText?: string;
+    AbstractURL?: string;
+    Results?: DuckDuckGoTopic[];
+    RelatedTopics?: DuckDuckGoTopic[];
+}
+/** One crypto row of the price feed */
+interface PriceCoin {
+    /** Price in EUR per unit */
+    pr?: number;
+    /** Price in EUR per unit, 24 hours earlier */
+    yst?: number;
+}
+/** The CoinExams price feed, validated before use */
+interface PriceFeed {
+    rates?: {
+        /** Feed timestamp of the fiat and metal rates, milliseconds */
+        date?: number;
+        /** Units of each symbol per EUR */
+        current?: Record<string, number>;
+        /** The same rates, 24 hours earlier */
+        yesterday?: Record<string, number>;
+    };
+    coins?: Record<string, PriceCoin>;
+    /** Feed timestamp of the crypto prices, milliseconds */
+    date?: number;
+}
 /** One LiteRT-LM model file and its capabilities */
 interface LitertArtifact {
     /** File name inside the model repository */
@@ -16,6 +184,8 @@ interface LitertArtifact {
     vision: boolean;
     /** Whether the build accepts audio */
     audio: boolean;
+    /** Whether the build accepts tool declarations */
+    tools: boolean;
 }
 /** One on-device model */
 interface ChatModel {
@@ -70,6 +240,8 @@ interface ChatStatusSnapshot {
     supportsImages: boolean;
     /** Whether the requested model accepts audio on this backend */
     supportsAudio: boolean;
+    /** Whether the requested model accepts tool declarations on this backend */
+    supportsTools: boolean;
     ready: boolean;
     loading: boolean;
     /** Whether a reply is streaming right now */
@@ -81,7 +253,7 @@ interface ChatStatusSnapshot {
     error?: string;
 }
 /** One chat request, invoked for every response */
-interface ChatInput {
+interface ChatInput extends ChatToolParams {
     /** Model that answers, the GPU model when WebGPU is available, else the CPU one */
     model?: ChatModelId;
     /** Complete prompt, including the system and user turns */
@@ -92,6 +264,10 @@ interface ChatInput {
     reasoning?: boolean;
     /** Whether package and engine logs reach the console, defaults to off */
     logging?: boolean;
+    /** Built-in tools to attach, all three by default */
+    builtins?: BuiltinTool[] | false;
+    /** Search provider settings */
+    websearch?: WebSearchConfig;
     /** Accumulated reasoning text, streamed while the model thinks */
     onThinking?: (text: string) => void;
     /** Accumulated reply text, streamed while the model answers */
@@ -238,7 +414,7 @@ interface ModelStore {
     purge: () => Promise<void>;
 }
 /** One generation request */
-interface RuntimeChatParams {
+interface RuntimeChatParams extends ChatToolParams {
     messages: ChatMessage[];
     limits: LlmLimits;
     reasoning: boolean;
@@ -246,6 +422,8 @@ interface RuntimeChatParams {
     logging?: boolean;
     onReason: (text: string) => void;
     onText: (text: string) => void;
+    /** Called before a rebuilt engine restarts the reply */
+    onRestart?: () => void;
     /** Current generation speed in tokens per second */
     onSpeed?: (tokensPerSecond: number) => void;
     signal?: AbortSignal;
@@ -266,7 +444,7 @@ interface Runtime {
     model: () => ChatModel | undefined;
 }
 /** Params for a single on-device chat generation */
-interface EngineChatParams {
+interface EngineChatParams extends ChatToolParams {
     messages: ChatMessage[];
     limits: LlmLimits;
     /** User preference, off unless explicitly turned on */
@@ -277,6 +455,8 @@ interface EngineChatParams {
     onReason: (text: string) => void;
     /** Streamed reply delta */
     onText: (text: string) => void;
+    /** Called before a rebuilt engine restarts the reply */
+    onRestart?: () => void;
     /** Current generation speed in tokens per second */
     onSpeed?: (tokensPerSecond: number) => void;
     signal?: AbortSignal;
@@ -305,6 +485,8 @@ interface LlmRuntime {
     contextSize: number;
     /** Stream one reply, returning the final text or undefined when stopped */
     chat: (params: EngineChatParams) => Promise<string | undefined>;
+    /** Whether the runtime cannot serve another turn */
+    fatal?: () => boolean;
     /** Release the model from memory, keeping its cache */
     unload: () => Promise<void>;
 }
@@ -372,6 +554,23 @@ type LitertContentPart = import('@litert-lm/core').ContentPart;
 type LitertMessage = import('@litert-lm/core').Message;
 /** One LiteRT-LM engine */
 type LitertEngine = import('@litert-lm/core').Engine;
+/** WebGPU device the wasm module initialized */
+type LitertDevice = NonNullable<import('@litert-lm/core').Wasm.LiteRtLmWasm[`preinitializedWebGPUDevice`]>;
+/** One live LiteRT-LM engine and its device */
+interface LitertGpu {
+    /** Live engine, rebuilt after a device loss */
+    engine: LitertEngine;
+    /** Wasm module the engine belongs to */
+    mod: LitertModule;
+    /** Device the engine runs on */
+    device?: LitertDevice;
+    /** Whether the device was lost */
+    lost: boolean;
+    /** Context window step of this engine */
+    contextStep: number;
+    /** Model file stream of a rebuild */
+    reopen: () => Promise<ReadableStream<Uint8Array>>;
+}
 /** The LiteRT-LM module namespace */
 type LitertModule = typeof import('@litert-lm/core');
 /** Settings handed to the LiteRT-LM engine */
@@ -386,23 +585,26 @@ interface LitertSettingsParams {
     source: ReadableStream<Uint8Array>;
     /** Loaded LiteRT module */
     mod: LitertModule;
+    /** Context window of this engine */
+    contextTokens?: number;
 }
 /** One reused LiteRT-LM conversation and the turns it already holds */
 interface LitertSession {
-    /** Live conversation, dropped when a turn cannot be continued */
-    conversation?: import('@litert-lm/core').Conversation;
+    /** Live conversation or tool chat, dropped when a turn cannot be continued */
+    conversation?: import('@litert-lm/core').ChatInterface;
     /** Built turns already sent to the conversation */
     sent: EngineMessage[];
     /** Reasoning flag the conversation was created with */
     reasoning: boolean;
     /** Output token budget the conversation was created with */
     maxTokens: number;
+    /** Tools the conversation was created with */
+    tools?: ChatTool[];
 }
 /** Params of one LiteRT-LM chat call */
 interface LitertChatParams {
-    engine: LitertEngine;
+    gpu: LitertGpu;
     model: ChatModel;
-    mod: LitertModule;
     params: EngineChatParams;
     session: LitertSession;
 }
@@ -460,4 +662,4 @@ interface EngineRunParams {
     /** Called when a slow stream keeps the text already delivered */
     onStall?: () => void;
 }
-export type { ChatMessage, ChatModel, LitertArtifact, LlmLimits, ChatStatusSnapshot, ChatInput, ChatPreloadInput, ChatState, CancelChat, WllamaAssets, LitertAssets, GpuNavigator, MobileNavigator, ActiveCall, RuntimeDeps, RuntimeLoadParams, RuntimeLoadWaiter, RuntimeChatParams, StoredPart, StoredFilePart, StoredModel, StoredModelMeta, ResumePlan, StoreDownloadParams, ModelStore, Runtime, EngineChatParams, StartLlmParams, LlmRuntime, LlmEngine, EngineMessage, EngineContentPart, WllamaContentPart, WllamaMessage, LitertContentPart, LitertMessage, LitertEngine, LitertModule, LitertSettings, LitertSettingsParams, LitertSession, LitertChatParams, StreamLitertParams, EngineDelta, EngineChunk, StreamReplyParams, EngineRunParams, };
+export type { ChatMessage, ChatModel, LitertArtifact, ChatTool, ChatToolCall, ChatToolResult, ChatToolSchema, ChatToolValue, ChatToolParams, ResolvedTools, CalculationResult, WebSearchConfig, WebSearchResult, WebSearchSettings, FiatSnapshot, CryptoSnapshot, PriceSnapshot, PriceSections, CurrencyResult, WikipediaPage, WikipediaResponse, DuckDuckGoTopic, DuckDuckGoResponse, PriceCoin, PriceFeed, LlmLimits, ChatStatusSnapshot, ChatInput, ChatPreloadInput, ChatState, CancelChat, WllamaAssets, LitertAssets, GpuNavigator, MobileNavigator, ActiveCall, RuntimeDeps, RuntimeLoadParams, RuntimeLoadWaiter, RuntimeChatParams, StoredPart, StoredFilePart, StoredModel, StoredModelMeta, ResumePlan, StoreDownloadParams, ModelStore, Runtime, EngineChatParams, StartLlmParams, LlmRuntime, LlmEngine, EngineMessage, EngineContentPart, WllamaContentPart, WllamaMessage, LitertContentPart, LitertMessage, LitertEngine, LitertModule, LitertDevice, LitertGpu, LitertSettings, LitertSettingsParams, LitertSession, LitertChatParams, StreamLitertParams, EngineDelta, EngineChunk, StreamReplyParams, EngineRunParams, };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@degreesign/chat",
-    "version": "0.5.2",
+    "version": "0.6.2",
     "description": "Headless on-device AI chat for browsers and Node with wllama CPU and LiteRT WebGPU engines",
     "main": "dist/node/chat.node.min.js",
     "module": "dist/browser/chat.min.mjs",
@@ -61,6 +61,7 @@
         "dist/"
     ],
     "dependencies": {
+        "@degreesign/utils": "^1.0.5",
         "@litert-lm/core": "0.19.0-nightly.20261024",
         "@wllama/wllama": "^3.8.1",
         "@wllama/wllama-compat": "^3.8.1"