@node-llm/core 0.2.2 → 0.3.0

package/README.md

@@ -15,6 +15,7 @@ A provider-agnostic LLM core for Node.js, heavily inspired by the elegant design
 - **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.
+- **Content Moderation**: Built-in safety checks for user input and model output.
 - **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.
@@ -42,7 +43,8 @@ import "dotenv/config";
 
 LLM.configure({
   provider: "openai", // Uses OPENAI_API_KEY from env
-  retry: { attempts: 3, delayMs: 500 }
+  retry: { attempts: 3, delayMs: 500 },
+  defaultModerationModel: "text-moderation-latest"
 });
 ```
 
@@ -103,6 +105,71 @@ console.log(response.output_tokens); // 5
 console.log(chat.totalUsage.total_tokens);
 ```
 
+### 6. Audio Transcription (Transcribe)
+
+Convert audio files to text using specialized models like Whisper.
+
+```ts
+const text = await LLM.transcribe("meeting.mp3");
+console.log(text);
+```
+
+### 7. Content Moderation (Moderate)
+
+Check if text content violates safety policies.
+
+```ts
+const result = await LLM.moderate("I want to help everyone!");
+if (result.flagged) {
+  console.log(`❌ Flagged for: ${result.flaggedCategories.join(", ")}`);
+} else {
+  console.log("✅ Content appears safe");
+}
+```
+
+Learn how to implement [custom risk thresholds](https://github.com/eshaiju/node-llm/blob/main/examples/openai/12-risk-assessment.mjs) for more granular control.
+
+### 8. Chat Event Handlers
+
+Hook into the chat lifecycle for logging, UI updates, or auditing.
+
+```ts
+chat
+  .onNewMessage(() => console.log("AI started typing..."))
+  .onToolCall((tool) => console.log(`Calling ${tool.function.name}...`))
+  .onToolResult((result) => console.log(`Tool returned: ${result}`))
+  .onEndMessage((response) => console.log(`Done. Usage: ${response.total_tokens}`));
+
+await chat.ask("What's the weather?");
+```
+
+### 9. System Prompts (Instructions)
+
+Guide the AI's behavior, personality, or constraints.
+
+```ts
+// Set initial instructions
+chat.withInstructions("You are a helpful assistant that explains simply.");
+
+// Update instructions mid-conversation (replace: true removes previous ones)
+chat.withInstructions("Now assume the persona of a pirate.", { replace: true });
+
+await chat.ask("Hello");
+// => "Ahoy matey!"
+```
+
+### 10. Temperature Control (Creativity)
+
+Adjust the randomness of the model's responses.
+
+```ts
+// Factual (0.0 - 0.3)
+const factual = LLM.chat("gpt-4o").withTemperature(0.2);
+
+// Creative (0.7 - 1.0)
+const creative = LLM.chat("gpt-4o").withTemperature(0.9);
+```
+
 ---
 
 ## 📚 Examples
@@ -120,6 +187,14 @@ Check the [examples](./examples) directory for focused scripts organized by prov
 | [Paint](https://github.com/eshaiju/node-llm/blob/main/examples/openai/06-paint.mjs) | Image generation with DALL-E |
 | [Image Features](https://github.com/eshaiju/node-llm/blob/main/examples/openai/07-image-features.mjs) | Saving and processing generated images |
 | [Token Usage](https://github.com/eshaiju/node-llm/blob/main/examples/openai/08-token-usage.mjs) | Detailed stats for turns and conversations |
+| [Transcribe](https://github.com/eshaiju/node-llm/blob/main/examples/openai/09-transcribe.mjs) | Audio to text transcription |
+| [Capabilities](https://github.com/eshaiju/node-llm/blob/main/examples/openai/10-capabilities.mjs) | Dynamic model specs and pricing |
+| [Moderate](https://github.com/eshaiju/node-llm/blob/main/examples/openai/11-moderate.mjs) | Content safety moderation |
+| [Risk Assessment](https://github.com/eshaiju/node-llm/blob/main/examples/openai/12-risk-assessment.mjs) | Custom thresholds and risk levels |
+| [Chat Events](https://github.com/eshaiju/node-llm/blob/main/examples/openai/13-chat-events.mjs) | Lifecycle hooks (onNewMessage, onToolCall etc) |
+| [System Prompts](https://github.com/eshaiju/node-llm/blob/main/examples/openai/15-system-prompts.mjs) | Dynamic system instructions |
+| [Temperature](https://github.com/eshaiju/node-llm/blob/main/examples/openai/16-temperature.mjs) | Control creativity vs determinism |
+| [Multi-File](https://github.com/eshaiju/node-llm/blob/main/examples/openai/17-multi-file.mjs) | Analyze multiple files at once |
 
 To run an example (from the project root):
 ```bash
@@ -157,7 +232,15 @@ const reply = await chat
 
 ### Multi-modal & File Support
 
-Pass local paths or URLs directly. The library handles reading, MIME detection, and encoding.
+Pass local paths or URLs directly. The library handles reading, MIME detection, and encoding for a wide variety of file types.
+
+**Supported File Types:**
+- **Images**: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
+- **Videos**: `.mp4`, `.mpeg`, `.mov`
+- **Audio**: `.wav`, `.mp3`
+- **Documents**: `.csv`, `.json`
+- **Code**: `.js`, `.mjs`, `.cjs`, `.ts`, `.py`, `.rb`, `.go`, `.java`, `.c`, `.cpp`, `.rs`, `.swift`, `.kt`
+- **Text**: `.txt`, `.md`, `.html`, `.css`, `.xml`, `.yml`, `.yaml`
 
 ```ts
 // Vision
@@ -170,10 +253,28 @@ await chat.ask("Transcribe this", {
   files: ["./meeting.mp3"]
 });
 
-// Text/Code Analysis
+// Code Analysis
 await chat.ask("Explain this code", {
   files: ["./app.ts"]
 });
+
+// Multiple files at once
+await chat.ask("Analyze these files", {
+  files: ["diagram.png", "data.json", "notes.txt"]
+});
+```
+
+### Custom HTTP Headers (Proxies/Observability)
+
+Inject custom headers into requests, useful for tools like Helicone or Portkey.
+
+```ts
+chat.withRequestOptions({
+  headers: {
+    "Helicone-Auth": "Bearer my-key",
+    "X-Custom-Trace": "123"
+  }
+});
 ```
 
 ---
@@ -182,7 +283,7 @@ await chat.ask("Explain this code", {
 
 | Provider | Status | Notes |
 | :--- | :--- | :--- |
-| **OpenAI** | ✅ Supported | Chat, Streaming, Tools, Vision, Audio, Images (DALL-E) |
+| **OpenAI** | ✅ Supported | Chat, Streaming, Tools, Vision, Audio, Images, Transcription, Moderation |
 | **Anthropic** | 🏗️ Roadmap | Coming soon |
 | **Azure OpenAI** | 🏗️ Roadmap | Coming soon |
 
@@ -197,6 +298,26 @@ await chat.ask("Explain this code", {
 
 ---
 
+## 🧪 Testing
+
+`node-llm` uses VCR-style testing (via Polly.js) for robust, deterministic integration tests. This allows us to record real LLM provider interactions once and replay them during tests without making actual API calls.
+
+### Running Tests
+
+- **Replay Mode (Default)**: Runs tests using recorded cassettes. Fast, deterministic, and requires no API keys.
+  ```bash
+  npm test
+  ```
+
+- **Record Mode**: Hits real APIs and updates cassettes. Requires a valid API key.
+  ```bash
+  VCR_MODE=record OPENAI_API_KEY=your_key npm test
+  ```
+
+*All recordings are automatically scrubbed of sensitive data (API keys, org IDs) before being saved to disk.*
+
+---
+
 ## 📄 License
 
 MIT © [node-llm contributors]

package/dist/chat/Chat.d.ts

@@ -6,23 +6,9 @@ export interface AskOptions {
     files?: string[];
     temperature?: number;
     maxTokens?: number;
+    headers?: Record<string, string>;
 }
-/**
- * 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;
-}
+import { ChatResponseString } from "./ChatResponse.js";
 export declare class Chat {
     private readonly provider;
     private readonly model;
@@ -42,6 +28,36 @@ export declare class Chat {
      * Add a tool to the chat session (fluent API)
      */
     withTool(tool: any): this;
+    /**
+     * Add instructions (system prompt) to the chat.
+     * By default, it appends a new system message.
+     * If { replace: true } is passed, it removes all previous system messages first.
+     */
+    withInstructions(instruction: string, options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Alias for withInstructions
+     */
+    withSystemPrompt(instruction: string, options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Set the temperature for the chat session.
+     * Controls randomness: 0.0 (deterministic) to 1.0 (creative).
+     */
+    withTemperature(temp: number): this;
+    /**
+     * Set custom headers for the chat session.
+     * Merges with existing headers.
+     */
+    withRequestOptions(options: {
+        headers?: Record<string, string>;
+    }): this;
+    onNewMessage(handler: () => void): this;
+    onEndMessage(handler: (message: ChatResponseString) => void): this;
+    onToolCall(handler: (toolCall: any) => void): this;
+    onToolResult(handler: (result: any) => void): this;
     /**
      * Ask the model a question
      */

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,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"}
+{"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;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,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;;;;OAIG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAmB5E;;OAEG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAI5E;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKnC;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI;IASvE,YAAY,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAKvC,YAAY,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAKlE,UAAU,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI;IAKlD,YAAY,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI;IAKlD;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAwJ7E;;OAEG;IACI,MAAM,CAAC,OAAO,EAAE,MAAM;CAI9B"}

package/dist/chat/Chat.js

@@ -2,32 +2,7 @@ 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();
-    }
-}
+import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
     model;
@@ -79,6 +54,69 @@ export class Chat {
         this.options.tools.push(tool);
         return this;
     }
+    /**
+     * Add instructions (system prompt) to the chat.
+     * By default, it appends a new system message.
+     * If { replace: true } is passed, it removes all previous system messages first.
+     */
+    withInstructions(instruction, options) {
+        if (options?.replace) {
+            this.messages = this.messages.filter((m) => m.role !== "system");
+        }
+        // System messages usually go first, but for "appending" behavior 
+        // mid-conversation, most providers handle them fine in history.
+        // Ideally, if it's "replace", we might want to unshift it to index 0,
+        // but simply pushing a new system message works for "updating" context too.
+        // For consistency with "replace" meaning "this is THE system prompt":
+        if (options?.replace) {
+            this.messages.unshift({ role: "system", content: instruction });
+        }
+        else {
+            this.messages.push({ role: "system", content: instruction });
+        }
+        return this;
+    }
+    /**
+     * Alias for withInstructions
+     */
+    withSystemPrompt(instruction, options) {
+        return this.withInstructions(instruction, options);
+    }
+    /**
+     * Set the temperature for the chat session.
+     * Controls randomness: 0.0 (deterministic) to 1.0 (creative).
+     */
+    withTemperature(temp) {
+        this.options.temperature = temp;
+        return this;
+    }
+    /**
+     * Set custom headers for the chat session.
+     * Merges with existing headers.
+     */
+    withRequestOptions(options) {
+        if (options.headers) {
+            this.options.headers = { ...this.options.headers, ...options.headers };
+        }
+        return this;
+    }
+    // --- Event Handlers ---
+    onNewMessage(handler) {
+        this.options.onNewMessage = handler;
+        return this;
+    }
+    onEndMessage(handler) {
+        this.options.onEndMessage = handler;
+        return this;
+    }
+    onToolCall(handler) {
+        this.options.onToolCall = handler;
+        return this;
+    }
+    onToolResult(handler) {
+        this.options.onToolResult = handler;
+        return this;
+    }
     /**
      * Ask the model a question
      */
@@ -91,10 +129,25 @@ export class Chat {
             if (hasBinary && this.provider.capabilities && !this.provider.capabilities.supportsVision(this.model)) {
                 throw new Error(`Model ${this.model} does not support vision/binary files.`);
             }
-            messageContent = [
-                { type: "text", text: content },
-                ...processedFiles
-            ];
+            // Separate text files from binary files
+            const textFiles = processedFiles.filter(p => p.type === "text");
+            const binaryFiles = processedFiles.filter(p => p.type !== "text");
+            // Concatenate text files into the main content
+            let fullText = content;
+            if (textFiles.length > 0) {
+                fullText += "\n" + textFiles.map(f => f.text).join("\n");
+            }
+            // If we have binary files, create multimodal content
+            if (binaryFiles.length > 0) {
+                messageContent = [
+                    { type: "text", text: fullText },
+                    ...binaryFiles
+                ];
+            }
+            else {
+                // Only text files, keep as string
+                messageContent = fullText;
+            }
         }
         if (this.options.tools && this.options.tools.length > 0) {
             if (this.provider.capabilities && !this.provider.capabilities.supportsTools(this.model)) {
@@ -111,6 +164,7 @@ export class Chat {
             tools: this.options.tools,
             temperature: options?.temperature ?? this.options.temperature,
             max_tokens: options?.maxTokens ?? this.options.maxTokens,
+            headers: { ...this.options.headers, ...options?.headers },
         };
         let totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
         const trackUsage = (u) => {
@@ -123,21 +177,32 @@ export class Chat {
                 }
             }
         };
+        // First round
+        if (this.options.onNewMessage)
+            this.options.onNewMessage();
         let response = await this.executor.executeChat(executeOptions);
         trackUsage(response.usage);
+        const firstAssistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model);
         this.messages.push({
             role: "assistant",
-            content: new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model),
+            content: firstAssistantMessage,
             tool_calls: response.tool_calls,
             usage: response.usage,
         });
+        if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
+            this.options.onEndMessage(firstAssistantMessage);
+        }
         while (response.tool_calls && response.tool_calls.length > 0) {
             for (const toolCall of response.tool_calls) {
+                if (this.options.onToolCall)
+                    this.options.onToolCall(toolCall);
                 const tool = this.options.tools?.find((t) => t.function.name === toolCall.function.name);
                 if (tool?.handler) {
                     try {
                         const args = JSON.parse(toolCall.function.arguments);
                         const result = await tool.handler(args);
+                        if (this.options.onToolResult)
+                            this.options.onToolResult(result);
                         this.messages.push({
                             role: "tool",
                             tool_call_id: toolCall.id,
@@ -164,14 +229,19 @@ export class Chat {
                 model: this.model,
                 messages: this.messages,
                 tools: this.options.tools,
+                headers: this.options.headers,
             });
             trackUsage(response.usage);
+            const assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model);
             this.messages.push({
                 role: "assistant",
-                content: new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model),
+                content: assistantMessage,
                 tool_calls: response.tool_calls,
                 usage: response.usage,
             });
+            if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
+                this.options.onEndMessage(assistantMessage);
+            }
         }
         return new ChatResponseString(response.content ?? "", totalUsage, this.model);
     }

package/dist/chat/ChatOptions.d.ts

@@ -6,5 +6,10 @@ export interface ChatOptions {
     tools?: Tool[];
     temperature?: number;
     maxTokens?: number;
+    onNewMessage?: () => void;
+    onEndMessage?: (message: any) => void;
+    onToolCall?: (toolCall: any) => void;
+    onToolResult?: (result: any) => void;
+    headers?: Record<string, string>;
 }
 //# sourceMappingURL=ChatOptions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC"}

package/dist/chat/ChatResponse.d.ts

@@ -0,0 +1,18 @@
+import { Usage } from "../providers/Provider.js";
+/**
+ * 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;
+}
+//# sourceMappingURL=ChatResponse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ChatResponse.d.ts","sourceRoot":"","sources":["../../src/chat/ChatResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAEjD;;;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"}

package/dist/chat/ChatResponse.js

@@ -0,0 +1,26 @@
+/**
+ * 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();
+    }
+}

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

@@ -1 +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"}
+{"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;AAGpD,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;CAwC9B"}

package/dist/chat/Stream.js

@@ -1,3 +1,4 @@
+import { ChatResponseString } from "./ChatResponse.js";
 export class Stream {
     provider;
     model;
@@ -38,12 +39,18 @@ export class Stream {
             throw new Error("Streaming not supported by provider");
         }
         let full = "";
+        let isFirst = true;
         for await (const chunk of this.provider.stream({
             model: this.model,
             messages: this.messages,
             temperature: this.options.temperature,
             max_tokens: this.options.maxTokens,
         })) {
+            if (isFirst) {
+                if (this.options.onNewMessage)
+                    this.options.onNewMessage();
+                isFirst = false;
+            }
             if (chunk.content) {
                 full += chunk.content;
             }
@@ -53,5 +60,8 @@ export class Stream {
             role: "assistant",
             content: full,
         });
+        if (this.options.onEndMessage) {
+            this.options.onEndMessage(new ChatResponseString(full, { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model));
+        }
     }
 }

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { Role } from "./chat/Role.js";
 export type { ChatOptions } from "./chat/ChatOptions.js";
 export type { Tool, ToolCall } from "./chat/Tool.js";
 export type { MessageContent, ContentPart } from "./chat/Content.js";
-export { LLM } from "./llm.js";
+export { LLM, Transcription, Moderation } from "./llm.js";
 export { providerRegistry } from "./providers/registry.js";
 export { OpenAIProvider } from "./providers/openai/OpenAIProvider.js";
 export { registerOpenAIProvider } from "./providers/openai/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC3E,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC3E,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 export { Chat } from "./chat/Chat.js";
 export { Stream } from "./chat/Stream.js";
 export { GeneratedImage } from "./image/GeneratedImage.js";
-export { LLM } from "./llm.js";
+export { LLM, Transcription, Moderation } from "./llm.js";
 export { providerRegistry } from "./providers/registry.js";
 export { OpenAIProvider } from "./providers/openai/OpenAIProvider.js";
 export { registerOpenAIProvider } from "./providers/openai/index.js";

package/dist/llm.d.ts

@@ -1,7 +1,10 @@
 import { Chat } from "./chat/Chat.js";
 import { ChatOptions } from "./chat/ChatOptions.js";
-import { Provider } from "./providers/Provider.js";
+import { Provider, ModelInfo } from "./providers/Provider.js";
 import { GeneratedImage } from "./image/GeneratedImage.js";
+import { ModelRegistry } from "./models/ModelRegistry.js";
+import { Transcription } from "./transcription/Transcription.js";
+import { Moderation } from "./moderation/Moderation.js";
 export interface RetryOptions {
     attempts?: number;
     delayMs?: number;
@@ -9,23 +12,42 @@ export interface RetryOptions {
 type LLMConfig = {
     provider: Provider;
     retry?: RetryOptions;
+    defaultTranscriptionModel?: string;
+    defaultModerationModel?: string;
 } | {
     provider: string;
     retry?: RetryOptions;
+    defaultTranscriptionModel?: string;
+    defaultModerationModel?: string;
 };
 declare class LLMCore {
+    readonly models: ModelRegistry;
     private provider?;
+    private defaultTranscriptionModelId?;
+    private defaultModerationModelId?;
     private retry;
     configure(config: LLMConfig): void;
     chat(model: string, options?: ChatOptions): Chat;
-    listModels(): Promise<import("./providers/Provider.js").ModelInfo[]>;
+    listModels(): Promise<ModelInfo[]>;
     paint(prompt: string, options?: {
         model?: string;
         size?: string;
         quality?: string;
     }): Promise<GeneratedImage>;
+    transcribe(file: string, options?: {
+        model?: string;
+        prompt?: string;
+        language?: string;
+        speakerNames?: string[];
+        speakerReferences?: string[];
+    }): Promise<Transcription>;
+    get defaultTranscriptionModel(): string | undefined;
+    get defaultModerationModel(): string | undefined;
     getRetryConfig(): Required<RetryOptions>;
+    moderate(input: string | string[], options?: {
+        model?: string;
+    }): Promise<Moderation>;
 }
+export { Transcription, Moderation };
 export declare const LLM: LLMCore;
-export {};
 //# sourceMappingURL=llm.d.ts.map

package/dist/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,SAAS,GACV;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAA;CAAE,GAC5C;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC;AAE/C,cAAM,OAAO;IACX,OAAO,CAAC,QAAQ,CAAC,CAAW;IAE5B,OAAO,CAAC,KAAK,CAGX;IAEF,SAAS,CAAC,MAAM,EAAE,SAAS;IAmB3B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAQ1C,UAAU;IAUV,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAgBnH,cAAc;CAIf;AAED,eAAO,MAAM,GAAG,SAAgB,CAAC"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EACL,QAAQ,EACR,SAAS,EAKV,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAU,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,SAAS,GACV;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAAE,GACjH;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpH,cAAM,OAAO;IACX,SAAgB,MAAM,EAAE,aAAa,CAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,2BAA2B,CAAC,CAAS;IAC7C,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAE1C,OAAO,CAAC,KAAK,CAGX;IAEF,SAAS,CAAC,MAAM,EAAE,SAAS;IA2B3B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IAQ1C,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAUlC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAgB7G,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC9B,GACA,OAAO,CAAC,aAAa,CAAC;IAiBzB,IAAI,yBAAyB,IAAI,MAAM,GAAG,SAAS,CAElD;IAED,IAAI,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAE/C;IAED,cAAc;IAIR,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;CAgB5F;AAED,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AAErC,eAAO,MAAM,GAAG,SAAgB,CAAC"}