@node-llm/core 0.1.0 → 0.2.1

package/README.md

@@ -1,215 +1,202 @@
-# node-llm
+# @node-llm/core
 
-A provider-agnostic LLM core for Node.js, inspired by ruby-llm.
+[![npm version](https://img.shields.io/npm/v/@node-llm/core.svg)](https://www.npmjs.com/package/@node-llm/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-node-llm focuses on:
-- clean abstractions
-- minimal magic
-- streaming-first design
-- no SDK lock-in
+A provider-agnostic LLM core for Node.js, heavily inspired by the elegant design of [ruby-llm](https://github.com/crmne/ruby_llm).
 
-This is a core library, not a framework.
+`node-llm` focuses on clean abstractions, minimal magic, and a streaming-first design. It provides a unified interface to interact with various LLM providers without being locked into their specific SDKs.
 
 ---
 
-## Features (current)
+## 🚀 Features
 
-- **Provider-agnostic chat API**: Switch between OpenAI, Anthropic, etc. with one line of config.
-- **Ruby-LLM-style configuration**: Simple, global configuration.
-- **Streaming responses**: Native AsyncIterator support for progressive token delivery.
-- **Tool calling (Function calling)**: Automatic execution loop for model-requested tools.
-- **Multi-modal Support**: Built-in support for Vision (images) and Audio.
-- **Smart File Handling**: Pass local file paths or URLs; the library handles reading and encoding.
-- **Fluent API**: Chainable methods like `.withTool()` for dynamic tool registration.
-- **Retry support**: Configurable retry logic at the execution layer.
-- **Strict ESM and TypeScript**: Modern, type-safe development.
+- **Provider-Agnostic**: Switch between OpenAI, Anthropic, and others with a single line of config.
+- **Streaming-First**: Native `AsyncIterator` support for real-time token delivery.
+- **Tool Calling**: Automatic execution loop for model-requested functions.
+- **Multi-modal & Smart Files**: Built-in support for Vision (images), Audio, and Text files.
+- **Fluent API**: Chainable methods like `.withTool()` for dynamic registration.
+- **Resilient**: Configurable retry logic at the execution layer.
+- **Type-Safe**: Written in TypeScript with full ESM support.
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
+npm install @node-llm/core
+# or
 pnpm add @node-llm/core
 ```
 
 ---
 
-## Configuration
+## 🛠️ Quick Start
 
-### Environment variables
+### 1. Configure the Provider
 
-```text
-OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
+```ts
+import { LLM } from "@node-llm/core";
+import "dotenv/config";
+
+LLM.configure({
+  provider: "openai", // Uses OPENAI_API_KEY from env
+  retry: { attempts: 3, delayMs: 500 }
+});
 ```
 
-Load environment variables in your application:
+### 2. Basic Chat
 
 ```ts
-import "dotenv/config";
-```
+const chat = LLM.chat("gpt-4o-mini", {
+  systemPrompt: "You are a helpful assistant."
+});
 
----
+const response = await chat.ask("What is Node.js?");
+
+// Use as a string directly
+console.log(response);
+
+// Or access metadata (RubyLLM style)
+console.log(response.content);
+console.log(`Model: ${response.model_id}`);
+console.log(`Tokens: ${response.input_tokens} in, ${response.output_tokens} out`);
+```
 
-## Basic Chat Usage
+### 3. Streaming Responses
 
 ```ts
-import { LLM } from "@node-llm/core";
+for await (const chunk of chat.stream("Write a poem")) {
+  process.stdout.write(chunk.content);
+}
+```
 
-LLM.configure({
-  provider: "openai",
-});
+### 4. Image Generation (Paint)
 
-const chat = LLM.chat("gpt-4o-mini", {
-  systemPrompt: "You are a concise assistant",
+Generate images and interact with them using a rich API.
+
+```ts
+const image = await LLM.paint("a sunset over mountains", {
+  model: "dall-e-3"
 });
 
-const reply = await chat.ask("Explain HTTP in one sentence");
-console.log(reply);
+// Use as a URL string
+console.log(`URL: ${image}`);
 
-// List available models with metadata (pricing, context window, etc.)
-const models = await LLM.listModels();
-console.log(models[0]);
+// Or use rich methods
+await image.save("sunset.png");
+console.log(`Format: ${image.mimeType}`);
 ```
 
----
-
-## Streaming Responses
+### 5. Token Usage Tracking
 
-Streaming uses the native AsyncIterator pattern.
+Track tokens for individual turns or the entire conversation.
 
 ```ts
-import { LLM } from "@node-llm/core";
+const response = await chat.ask("Hello!");
 
-LLM.configure({ provider: "openai" });
+console.log(response.input_tokens);  // 10
+console.log(response.output_tokens); // 5
 
-const chat = LLM.chat("gpt-4o-mini");
+// Access aggregated usage for the whole session
+console.log(chat.totalUsage.total_tokens);
+```
 
-let full = "";
+---
 
-for await (const token of chat.stream("Explain HTTP in one sentence")) {
-  process.stdout.write(token);
-  full += token;
-}
+## 📚 Examples
 
-console.log("\nFinal response:", full);
+Check the [examples](./examples) directory for focused scripts organized by provider:
+
+### OpenAI Examples
+| Example | Description |
+| :--- | :--- |
+| [Basic Chat](../../examples/openai/01-basic-chat.mjs) | Simple completion request |
+| [Streaming](../../examples/openai/02-streaming.mjs) | Real-time token streaming |
+| [Tool Calling](../../examples/openai/03-tool-calling.mjs) | Automatic tool execution loop |
+| [Vision](../../examples/openai/04-vision.mjs) | Image analysis |
+| [List Models](../../examples/openai/05-list-models.mjs) | Enumerate available models |
+| [Paint](../../examples/openai/06-paint.mjs) | Image generation with DALL-E |
+| [Image Features](../../examples/openai/07-image-features.mjs) | Saving and processing generated images |
+| [Token Usage](../../examples/openai/08-token-usage.mjs) | Detailed stats for turns and conversations |
+
+To run an example (from the project root):
+```bash
+node examples/openai/01-basic-chat.mjs
 ```
 
 ---
 
-## Tool Calling
+## 🔌 Advanced Usage
 
-You can define tools and pass them to the chat instance. The model will decide when to call them, and the library handles the execution loop automatically.
+### Tool Calling (Function Calling)
 
-```ts
-import { LLM, Tool } from "@node-llm/core";
+Define your tools and let the library handle the execution loop automatically.
 
-// 1. Define a tool
-const weatherTool: Tool = {
+```ts
+const weatherTool = {
   type: 'function',
   function: {
     name: 'get_weather',
-    description: 'Get the current weather for a location',
     parameters: {
       type: 'object',
-      properties: {
-        location: { type: 'string', description: 'The city and state, e.g. San Francisco, CA' },
-        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
-      },
-      required: ['location']
+      properties: { location: { type: 'string' } }
     }
   },
-  // 2. Implement the handler
-  handler: async ({ location, unit = 'celsius' }) => {
-    // Call your real API here
-    return JSON.stringify({ location, temperature: 22, unit, condition: "Sunny" });
+  handler: async ({ location }) => {
+    return JSON.stringify({ location, temp: 22, unit: 'celsius' });
   }
 };
 
-// 3. Initialize chat (Option A: via constructor)
-const chat = LLM.chat("gpt-4o-mini", {
-  tools: [weatherTool]
-});
-
-// OR Option B: via fluent API (Ruby-LLM style)
-const chat2 = LLM.chat("gpt-4o-mini")
-  .withTool(weatherTool);
-
-// 4. Ask a question
-const reply = await chat.ask("What is the weather in London?");
-console.log(reply); 
-// Output: "The weather in London is currently 22°C and sunny."
+// Use the fluent API to add tools on the fly
+const reply = await chat
+  .withTool(weatherTool)
+  .ask("What is the weather in London?");
 ```
 
----
-
-## File & Multi-modal Support
+### Multi-modal & File Support
 
-You can send files (images, audio, text, etc.) to models that support them. The library automatically handles local file reading, MIME detection, and base64 encoding.
+Pass local paths or URLs directly. The library handles reading, MIME detection, and encoding.
 
 ```ts
-// Local files (automatically read & converted)
-await chat.ask("Analyze this image", {
-  files: ["./image.jpg"]
-});
-
-// Text files (content is automatically appended to prompt)
-await chat.ask("Summarize this code", {
-  files: ["./app.ts"]
+// Vision
+await chat.ask("What's in this image?", {
+  files: ["./screenshot.png"]
 });
 
-// Remote URLs (passed through)
-await chat.ask("Describe this", {
-  files: ["https://example.com/photo.png"]
-});
-
-// Audio files (OpenAI input_audio support)
-await chat.ask("Transcribe this meeting", {
+// Audio
+await chat.ask("Transcribe this", {
   files: ["./meeting.mp3"]
 });
-```
-
----
-
-## Retry Support
-
-Retries are applied before chat execution, not inside providers.
 
-```ts
-LLM.configure({
-  provider: "openai",
-  retry: {
-    attempts: 3,
-    delayMs: 500,
-  },
+// Text/Code Analysis
+await chat.ask("Explain this code", {
+  files: ["./app.ts"]
 });
 ```
 
-Retry behavior:
-- Only transient failures are retried
-- Chat and providers remain clean
-- Designed for future timeouts and circuit breakers
-
 ---
 
-## Development
+## 📋 Supported Providers
 
-```bash
-pnpm install
-pnpm --filter @node-llm/core build
-node test-openai.mjs
-```
+| Provider | Status | Notes |
+| :--- | :--- | :--- |
+| **OpenAI** | ✅ Supported | Chat, Streaming, Tools, Vision, Audio, Images (DALL-E) |
+| **Anthropic** | 🏗️ Roadmap | Coming soon |
+| **Azure OpenAI** | 🏗️ Roadmap | Coming soon |
 
 ---
 
-## Design Philosophy
+## 🧠 Design Philosophy
 
-- **Explicit over implicit**: No hidden side effects or complex state management.
-- **Provider-agnostic core**: The same code works across different LLM providers.
-- **Ruby-LLM mental model**: Developer experience inspired by the best of Ruby, executed with Node-native patterns.
-- **Production Ready**: Built with TypeScript, ESM, and comprehensive testing.
+- **Explicit over Implicit**: No hidden side effects.
+- **Minimal Dependencies**: Lightweight core with zero bloat.
+- **Developer Experience**: Inspired by Ruby's elegance, built for Node's performance.
+- **Production Ready**: Built-in retries and strict type checking.
 
 ---
 
-## License
+## 📄 License
 
-MIT
+MIT © [node-llm contributors]

package/dist/chat/Chat.d.ts

@@ -1,6 +1,28 @@
 import { Message } from "./Message.js";
 import { ChatOptions } from "./ChatOptions.js";
-import { Provider } from "../providers/Provider.js";
+import { Provider, Usage } from "../providers/Provider.js";
+export interface AskOptions {
+    images?: string[];
+    files?: string[];
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Enhanced string that includes token usage metadata.
+ * Behaves like a regular string but has .usage and .input_tokens etc.
+ */
+export declare class ChatResponseString extends String {
+    readonly usage: Usage;
+    readonly model: string;
+    constructor(content: string, usage: Usage, model: string);
+    get input_tokens(): number;
+    get output_tokens(): number;
+    get total_tokens(): number;
+    get cached_tokens(): number | undefined;
+    get content(): string;
+    get model_id(): string;
+    toString(): string;
+}
 export declare class Chat {
     private readonly provider;
     private readonly model;
@@ -12,6 +34,10 @@ export declare class Chat {
      * Read-only access to message history
      */
     get history(): readonly Message[];
+    /**
+     * Aggregate usage across the entire conversation
+     */
+    get totalUsage(): Usage;
     /**
      * Add a tool to the chat session (fluent API)
      */
@@ -19,17 +45,10 @@ export declare class Chat {
     /**
      * Ask the model a question
      */
-    ask(content: string, options?: {
-        images?: string[];
-        files?: string[];
-        temperature?: number;
-        maxTokens?: number;
-    }): Promise<string>;
+    ask(content: string, options?: AskOptions): Promise<ChatResponseString>;
     /**
      * Streams the model's response to a user question.
-     * @param content The user's question to send to the model.
-     * @returns An async generator yielding chunks of the assistant's response as strings.
      */
-    stream(content: string): AsyncGenerator<string, void, unknown>;
+    stream(content: string): AsyncGenerator<import("../providers/Provider.js").ChatChunk, void, unknown>;
 }
 //# sourceMappingURL=Chat.d.ts.map

package/dist/chat/Chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAIpD,qBAAa,IAAI;IAKb,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,QAAQ,CAAW;gBAGR,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB;IAoB5C;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAQzB;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IA6FxI;;;;OAIG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM;CAyB9B"}
+{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAK3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;aAG1B,KAAK,EAAE,KAAK;aACZ,KAAK,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM;IAK/B,IAAI,YAAY,WAAsC;IACtD,IAAI,aAAa,WAAuC;IACxD,IAAI,YAAY,WAAsC;IACtD,IAAI,aAAa,uBAAuC;IAExD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,QAAQ;CAGT;AAED,qBAAa,IAAI;IAKb,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,QAAQ,CAAW;gBAGR,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB;IAmB5C;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,KAAK,CAatB;IAED;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAQzB;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6G7E;;OAEG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM;CAI9B"}

package/dist/chat/Chat.js

@@ -1,6 +1,33 @@
 import { FileLoader } from "../utils/FileLoader.js";
 import { Executor } from "../executor/Executor.js";
 import { LLM } from "../llm.js";
+import { Stream } from "./Stream.js";
+/**
+ * Enhanced string that includes token usage metadata.
+ * Behaves like a regular string but has .usage and .input_tokens etc.
+ */
+export class ChatResponseString extends String {
+    usage;
+    model;
+    constructor(content, usage, model) {
+        super(content);
+        this.usage = usage;
+        this.model = model;
+    }
+    get input_tokens() { return this.usage.input_tokens; }
+    get output_tokens() { return this.usage.output_tokens; }
+    get total_tokens() { return this.usage.total_tokens; }
+    get cached_tokens() { return this.usage.cached_tokens; }
+    get content() {
+        return this.valueOf();
+    }
+    get model_id() {
+        return this.model;
+    }
+    toString() {
+        return this.valueOf();
+    }
+}
 export class Chat {
     provider;
     model;
@@ -28,6 +55,20 @@ export class Chat {
     get history() {
         return this.messages;
     }
+    /**
+     * Aggregate usage across the entire conversation
+     */
+    get totalUsage() {
+        return this.messages.reduce((acc, msg) => {
+            if (msg.usage) {
+                acc.input_tokens += msg.usage.input_tokens;
+                acc.output_tokens += msg.usage.output_tokens;
+                acc.total_tokens += msg.usage.total_tokens;
+                acc.cached_tokens = (acc.cached_tokens ?? 0) + (msg.usage.cached_tokens ?? 0);
+            }
+            return acc;
+        }, { input_tokens: 0, output_tokens: 0, total_tokens: 0, cached_tokens: 0 });
+    }
     /**
      * Add a tool to the chat session (fluent API)
      */
@@ -71,11 +112,24 @@ export class Chat {
             temperature: options?.temperature ?? this.options.temperature,
             max_tokens: options?.maxTokens ?? this.options.maxTokens,
         };
+        let totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+        const trackUsage = (u) => {
+            if (u) {
+                totalUsage.input_tokens += u.input_tokens;
+                totalUsage.output_tokens += u.output_tokens;
+                totalUsage.total_tokens += u.total_tokens;
+                if (u.cached_tokens) {
+                    totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
+                }
+            }
+        };
         let response = await this.executor.executeChat(executeOptions);
+        trackUsage(response.usage);
         this.messages.push({
             role: "assistant",
-            content: response.content,
+            content: new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model),
             tool_calls: response.tool_calls,
+            usage: response.usage,
         });
         while (response.tool_calls && response.tool_calls.length > 0) {
             for (const toolCall of response.tool_calls) {
@@ -111,37 +165,21 @@ export class Chat {
                 messages: this.messages,
                 tools: this.options.tools,
             });
+            trackUsage(response.usage);
             this.messages.push({
                 role: "assistant",
-                content: response.content,
+                content: new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model),
                 tool_calls: response.tool_calls,
+                usage: response.usage,
             });
         }
-        return response.content ?? "";
+        return new ChatResponseString(response.content ?? "", totalUsage, this.model);
     }
     /**
      * Streams the model's response to a user question.
-     * @param content The user's question to send to the model.
-     * @returns An async generator yielding chunks of the assistant's response as strings.
      */
     async *stream(content) {
-        this.messages.push({ role: "user", content });
-        if (!this.provider.stream) {
-            throw new Error("Streaming not supported by provider");
-        }
-        let full = "";
-        for await (const chunk of this.provider.stream({
-            model: this.model,
-            messages: this.messages,
-        })) {
-            if (chunk.content) {
-                full += chunk.content;
-                yield chunk.content;
-            }
-        }
-        this.messages.push({
-            role: "assistant",
-            content: full,
-        });
+        const streamer = new Stream(this.provider, this.model, this.options, this.messages);
+        yield* streamer.stream(content);
     }
 }

package/dist/chat/Content.d.ts

@@ -18,5 +18,5 @@ export type ContentPart = {
         url: string;
     };
 };
-export type MessageContent = string | ContentPart[];
+export type MessageContent = string | String | ContentPart[];
 //# sourceMappingURL=Content.d.ts.map

package/dist/chat/Content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Content.d.ts","sourceRoot":"","sources":["../../src/chat/Content.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,EAAE,CAAC"}
+{"version":3,"file":"Content.d.ts","sourceRoot":"","sources":["../../src/chat/Content.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,EAAE,CAAC"}

package/dist/chat/Message.d.ts

@@ -1,11 +1,13 @@
 import { Role } from "./Role.js";
 import { ToolCall } from "./Tool.js";
 import { MessageContent } from "./Content.js";
+import { Usage } from "../providers/Provider.js";
 export interface Message {
     role: Role;
     content: MessageContent | null;
     tool_calls?: ToolCall[];
     tool_call_id?: string;
     name?: string;
+    usage?: Usage;
 }
 //# sourceMappingURL=Message.d.ts.map

package/dist/chat/Message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Message.d.ts","sourceRoot":"","sources":["../../src/chat/Message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"Message.d.ts","sourceRoot":"","sources":["../../src/chat/Message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAEjD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;CACf"}

package/dist/chat/Stream.d.ts

@@ -0,0 +1,21 @@
+import { Message } from "./Message.js";
+import { ChatOptions } from "./ChatOptions.js";
+import { Provider } from "../providers/Provider.js";
+export declare class Stream {
+    private readonly provider;
+    private readonly model;
+    private readonly options;
+    private messages;
+    constructor(provider: Provider, model: string, options?: ChatOptions, messages?: Message[]);
+    /**
+     * Read-only access to message history
+     */
+    get history(): readonly Message[];
+    /**
+     * Streams the model's response to a user question.
+     * @param content The user's question to send to the model.
+     * @returns An async generator yielding chunks of the assistant's response as strings.
+     */
+    stream(content: string): AsyncGenerator<import("../providers/Provider.js").ChatChunk, void, unknown>;
+}
+//# sourceMappingURL=Stream.d.ts.map

package/dist/chat/Stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stream.d.ts","sourceRoot":"","sources":["../../src/chat/Stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,qBAAa,MAAM;IAIf,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAY;gBAGT,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE;IAmBtB;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;;;OAIG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM;CA0B9B"}

package/dist/chat/Stream.js

@@ -0,0 +1,57 @@
+export class Stream {
+    provider;
+    model;
+    options;
+    messages;
+    constructor(provider, model, options = {}, messages) {
+        this.provider = provider;
+        this.model = model;
+        this.options = options;
+        this.messages = messages ?? [];
+        // Only initialize if we're starting a new history
+        if (this.messages.length === 0) {
+            if (options.systemPrompt) {
+                this.messages.push({
+                    role: "system",
+                    content: options.systemPrompt,
+                });
+            }
+            if (options.messages) {
+                this.messages.push(...options.messages);
+            }
+        }
+    }
+    /**
+     * Read-only access to message history
+     */
+    get history() {
+        return this.messages;
+    }
+    /**
+     * Streams the model's response to a user question.
+     * @param content The user's question to send to the model.
+     * @returns An async generator yielding chunks of the assistant's response as strings.
+     */
+    async *stream(content) {
+        this.messages.push({ role: "user", content });
+        if (!this.provider.stream) {
+            throw new Error("Streaming not supported by provider");
+        }
+        let full = "";
+        for await (const chunk of this.provider.stream({
+            model: this.model,
+            messages: this.messages,
+            temperature: this.options.temperature,
+            max_tokens: this.options.maxTokens,
+        })) {
+            if (chunk.content) {
+                full += chunk.content;
+            }
+            yield chunk;
+        }
+        this.messages.push({
+            role: "assistant",
+            content: full,
+        });
+    }
+}