@node-llm/core 0.3.0 → 0.4.0

package/README.md

@@ -42,9 +42,11 @@ import { LLM } from "@node-llm/core";
 import "dotenv/config";
 
 LLM.configure({
-  provider: "openai", // Uses OPENAI_API_KEY from env
+  provider: "openai", // or "gemini" (Uses GEMINI_API_KEY)
   retry: { attempts: 3, delayMs: 500 },
-  defaultModerationModel: "text-moderation-latest"
+  defaultModerationModel: "text-moderation-latest",
+  defaultTranscriptionModel: "whisper-1",
+  defaultEmbeddingModel: "text-embedding-3-small"
 });
 ```
 
@@ -105,7 +107,37 @@ console.log(response.output_tokens); // 5
 console.log(chat.totalUsage.total_tokens);
 ```
 
-### 6. Audio Transcription (Transcribe)
+### 6. Embeddings
+
+Generate vector representations of text for semantic search, clustering, and similarity comparisons.
+
+```ts
+// Single text embedding
+const embedding = await LLM.embed("Ruby is a programmer's best friend");
+
+console.log(embedding.vector);        // Array of floats (e.g., 1536 dimensions)
+console.log(embedding.dimensions);    // 1536
+console.log(embedding.model);         // "text-embedding-3-small"
+console.log(embedding.input_tokens);  // Token count
+
+// Batch embeddings
+const embeddings = await LLM.embed([
+  "First text",
+  "Second text",
+  "Third text"
+]);
+
+console.log(embeddings.vectors);      // Array of vectors
+console.log(embeddings.vectors.length); // 3
+
+// Custom model and dimensions
+const customEmbedding = await LLM.embed("Semantic search text", {
+  model: "text-embedding-3-large",
+  dimensions: 256  // Reduce dimensions for faster processing
+});
+```
+
+### 7. Audio Transcription (Transcribe)
 
 Convert audio files to text using specialized models like Whisper.
 
@@ -127,7 +159,7 @@ if (result.flagged) {
 }
 ```
 
-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.
+Learn how to implement [custom risk thresholds](../../examples/openai/12-risk-assessment.mjs) for more granular control.
 
 ### 8. Chat Event Handlers
 
@@ -174,29 +206,76 @@ const creative = LLM.chat("gpt-4o").withTemperature(0.9);
 
 ## 📚 Examples
 
-Check the [examples](./examples) directory for focused scripts organized by provider:
+Check the [examples](../../examples) directory for focused scripts organized by provider:
 
 ### OpenAI Examples
+
+#### 💬 Chat
+| Example | Description |
+| :--- | :--- |
+| [Basic & Streaming](../../examples/openai/chat/basic.mjs) | Standard completions and real-time streaming |
+| [System Instructions](../../examples/openai/chat/instructions.mjs) | Tuning behavior with system prompts and temperature |
+| [Tool Calling](../../examples/openai/chat/tools.mjs) | Automatic execution of model-requested functions |
+| [Parallel Tool Calling](../../examples/openai/chat/parallel-tools.mjs) | Executing multiple tools in a single turn |
+| [Lifecycle Events](../../examples/openai/chat/events.mjs) | Hooks for specific chat events (onNewMessage, onToolCall) |
+| [Token Usage](../../examples/openai/chat/usage.mjs) | Tracking costs and token counts |
+| [Max Tokens](../../examples/openai/chat/max-tokens.mjs) | Limiting response length with `maxTokens` |
+
+#### 🖼️ Multimodal
 | Example | Description |
 | :--- | :--- |
-| [Basic Chat](https://github.com/eshaiju/node-llm/blob/main/examples/openai/01-basic-chat.mjs) | Simple completion request |
-| [Streaming](https://github.com/eshaiju/node-llm/blob/main/examples/openai/02-streaming.mjs) | Real-time token streaming |
-| [Tool Calling](https://github.com/eshaiju/node-llm/blob/main/examples/openai/03-tool-calling.mjs) | Automatic tool execution loop |
-| [Vision](https://github.com/eshaiju/node-llm/blob/main/examples/openai/04-vision.mjs) | Image analysis |
-| [List Models](https://github.com/eshaiju/node-llm/blob/main/examples/openai/05-list-models.mjs) | Enumerate available models |
-| [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):
+| [Vision Analysis](../../examples/openai/multimodal/vision.mjs) | Analyzing images via URLs |
+| [Multi-Image Analysis](../../examples/openai/multimodal/multi-image.mjs) | Comparing multiple images in one request |
+| [File Context](../../examples/openai/multimodal/files.mjs) | Reading and analyzing local project files |
+| [Audio Transcription](../../examples/openai/multimodal/transcribe.mjs) | Converting audio files to text (Whisper) |
+
+#### 🎨 Images
+| Example | Description |
+| :--- | :--- |
+| [Generate & Save](../../examples/openai/images/generate.mjs) | Creating images with DALL-E 3 and saving to disk |
+
+#### 🛡️ Safety
+| Example | Description |
+| :--- | :--- |
+| [Moderation](../../examples/openai/safety/moderation.mjs) | Content safety checks and risk assessment |
+
+#### 🧠 Discovery
+| Example | Description |
+| :--- | :--- |
+| [Models & Capabilities](../../examples/openai/discovery/models.mjs) | Listing models and inspecting their specs |
+| [Embeddings](../../examples/openai/embeddings/create.mjs) | Generating semantic vector embeddings |
+
+### Gemini Examples
+
+#### 💬 Chat
+| Example | Description |
+| :--- | :--- |
+| [Basic & Streaming](../../examples/gemini/chat/basic.mjs) | Standard completions and real-time streaming |
+| [System Instructions](../../examples/gemini/chat/instructions.mjs) | Behavior tuning and creativity control |
+| [Tool Calling](../../examples/gemini/chat/tools.mjs) | Function calling with automatic execution |
+| [Lifecycle Events](../../examples/gemini/chat/events.mjs) | Event hooks for chat interactions |
+| [Token Usage](../../examples/gemini/chat/usage.mjs) | Tracking conversation costs |
+
+#### 🖼️ Multimodal
+| Example | Description |
+| :--- | :--- |
+| [Vision Analysis](../../examples/gemini/multimodal/vision.mjs) | Understanding images |
+| [File Context](../../examples/gemini/multimodal/files.mjs) | Reading multiple local files |
+| [Audio Transcription](../../examples/gemini/multimodal/transcribe.mjs) | Native audio understanding |
+
+#### 🎨 Images
+| Example | Description |
+| :--- | :--- |
+| [Generate & Save](../../examples/gemini/images/generate.mjs) | Creating images with Imagen |
+
+#### 🧠 Discovery
+| Example | Description |
+| :--- | :--- |
+| [Models & Capabilities](../../examples/gemini/discovery/models.mjs) | Listing models and capabilities |
+| [Embeddings](../../examples/gemini/embeddings/create.mjs) | Creating vector embeddings |
+
+
+To run an example:
 ```bash
 node examples/openai/01-basic-chat.mjs
 ```
@@ -230,6 +309,64 @@ const reply = await chat
   .ask("What is the weather in London?");
 ```
 
+### Structured Output (Schemas)
+
+Ensure the AI returns data exactly matching a specific structure. Supports strict schema validation using Zod.
+
+**Using Zod (Recommended):**
+
+```ts
+import { z } from "zod";
+
+const personSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  hobbies: z.array(z.string())
+});
+
+const response = await chat
+  .withSchema(personSchema)
+  .ask("Generate a person named Alice who likes hiking");
+
+// Type-safe access to parsed data
+const person = response.parsed;
+console.log(person.name); // "Alice"
+```
+
+**Using Manual JSON Schema:**
+
+```ts
+const schema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "integer" }
+  },
+  required: ["name", "age"],
+  additionalProperties: false // Required for strict mode in OpenAI
+};
+
+const response = await chat
+  .withSchema(schema)
+  .ask("Generate a person");
+
+console.log(response.parsed); // { name: "...", age: ... }
+```
+
+### JSON Mode
+
+Guarantee valid JSON output without enforcing a strict schema.
+
+```ts
+chat.withRequestOptions({
+  responseFormat: { type: "json_object" }
+});
+
+const response = await chat.ask("Generate a JSON object with a greeting");
+console.log(response.parsed); // { greeting: "..." }
+```
+
+
 ### Multi-modal & File Support
 
 Pass local paths or URLs directly. The library handles reading, MIME detection, and encoding for a wide variety of file types.
@@ -277,6 +414,21 @@ chat.withRequestOptions({
 });
 ```
 
+### Model Capabilities & Pricing
+
+Get up-to-date information about context windows, pricing, and capabilities directly from the Parsera API.
+
+```javascript
+// Refresh model information from the API
+await LLM.models.refresh();
+
+// Use the data programmatically
+const model = LLM.models.find("gpt-4o-mini");
+console.log(model.context_window);    // => 128000
+console.log(model.capabilities);      // => ["function_calling", "structured_output", "streaming", "batch"]
+console.log(model.pricing.text_tokens.standard.input_per_million); // => 0.15
+```
+
 ---
 
 ## 📋 Supported Providers
@@ -284,6 +436,7 @@ chat.withRequestOptions({
 | Provider | Status | Notes |
 | :--- | :--- | :--- |
 | **OpenAI** | ✅ Supported | Chat, Streaming, Tools, Vision, Audio, Images, Transcription, Moderation |
+| **Gemini** | ✅ Supported | Chat, Streaming, Tools, Vision, Audio, Video, Embeddings, Transcription |
 | **Anthropic** | 🏗️ Roadmap | Coming soon |
 | **Azure OpenAI** | 🏗️ Roadmap | Coming soon |
 
@@ -302,8 +455,6 @@ chat.withRequestOptions({
 
 `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

package/dist/chat/Chat.d.ts

@@ -1,6 +1,9 @@
 import { Message } from "./Message.js";
 import { ChatOptions } from "./ChatOptions.js";
 import { Provider, Usage } from "../providers/Provider.js";
+import { Tool } from "./Tool.js";
+import { Schema } from "../schema/Schema.js";
+import { z } from "zod";
 export interface AskOptions {
     images?: string[];
     files?: string[];
@@ -11,7 +14,7 @@ export interface AskOptions {
 import { ChatResponseString } from "./ChatResponse.js";
 export declare class Chat {
     private readonly provider;
-    private readonly model;
+    private model;
     private readonly options;
     private messages;
     private executor;
@@ -26,8 +29,20 @@ export declare class Chat {
     get totalUsage(): Usage;
     /**
      * Add a tool to the chat session (fluent API)
+     * Supports passing a tool instance or a tool class (which will be instantiated).
      */
     withTool(tool: any): this;
+    /**
+     * Add multiple tools to the chat session.
+     * Supports passing tool instances or classes (which will be instantiated).
+     * Can replace existing tools if options.replace is true.
+     *
+     * @example
+     * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
+     */
+    withTools(tools: (Tool | any)[], options?: {
+        replace?: boolean;
+    }): this;
     /**
      * Add instructions (system prompt) to the chat.
      * By default, it appends a new system message.
@@ -47,13 +62,23 @@ export declare class Chat {
      * Controls randomness: 0.0 (deterministic) to 1.0 (creative).
      */
     withTemperature(temp: number): this;
+    /**
+     * Switch the model used for this chat session.
+     */
+    withModel(model: string): this;
     /**
      * Set custom headers for the chat session.
      * Merges with existing headers.
      */
     withRequestOptions(options: {
         headers?: Record<string, string>;
+        responseFormat?: any;
     }): this;
+    /**
+     * Enforce a specific schema for the output.
+     * Can accept a Schema object or a Zod schema/JSON Schema directly.
+     */
+    withSchema(schema: Schema | z.ZodType<any> | Record<string, any> | null): this;
     onNewMessage(handler: () => void): this;
     onEndMessage(handler: (message: ChatResponseString) => void): this;
     onToolCall(handler: (toolCall: any) => void): this;

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

package/dist/chat/Chat.js

@@ -2,6 +2,9 @@ import { FileLoader } from "../utils/FileLoader.js";
 import { Executor } from "../executor/Executor.js";
 import { LLM } from "../llm.js";
 import { Stream } from "./Stream.js";
+import { Schema } from "../schema/Schema.js";
+import { toJsonSchema } from "../schema/to-json-schema.js";
+import { z } from "zod";
 import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
@@ -46,12 +49,43 @@ export class Chat {
     }
     /**
      * Add a tool to the chat session (fluent API)
+     * Supports passing a tool instance or a tool class (which will be instantiated).
      */
     withTool(tool) {
+        return this.withTools([tool]);
+    }
+    /**
+     * Add multiple tools to the chat session.
+     * Supports passing tool instances or classes (which will be instantiated).
+     * Can replace existing tools if options.replace is true.
+     *
+     * @example
+     * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
+     */
+    withTools(tools, options) {
+        if (options?.replace) {
+            this.options.tools = [];
+        }
         if (!this.options.tools) {
             this.options.tools = [];
         }
-        this.options.tools.push(tool);
+        for (const tool of tools) {
+            if (typeof tool === "function") {
+                try {
+                    // Attempt to instantiate if it's a class
+                    this.options.tools.push(new tool());
+                }
+                catch (e) {
+                    // If instantiation fails, it might be a function tool or require args? 
+                    // For now, assuming classes with no-arg constructors as per convention.
+                    console.warn("Attempted to instantiate tool class but failed, adding as-is", e);
+                    this.options.tools.push(tool);
+                }
+            }
+            else {
+                this.options.tools.push(tool);
+            }
+        }
         return this;
     }
     /**
@@ -90,6 +124,13 @@ export class Chat {
         this.options.temperature = temp;
         return this;
     }
+    /**
+     * Switch the model used for this chat session.
+     */
+    withModel(model) {
+        this.model = model;
+        return this;
+    }
     /**
      * Set custom headers for the chat session.
      * Merges with existing headers.
@@ -98,6 +139,29 @@ export class Chat {
         if (options.headers) {
             this.options.headers = { ...this.options.headers, ...options.headers };
         }
+        if (options.responseFormat) {
+            this.options.responseFormat = options.responseFormat;
+        }
+        return this;
+    }
+    /**
+     * Enforce a specific schema for the output.
+     * Can accept a Schema object or a Zod schema/JSON Schema directly.
+     */
+    withSchema(schema) {
+        if (schema === null) {
+            this.options.schema = undefined;
+            return this;
+        }
+        if (schema instanceof Schema) {
+            this.options.schema = schema;
+        }
+        else if (schema instanceof z.ZodType) {
+            this.options.schema = Schema.fromZod("output", schema);
+        }
+        else {
+            this.options.schema = Schema.fromJson("output", schema);
+        }
         return this;
     }
     // --- Event Handlers ---
@@ -158,6 +222,23 @@ export class Chat {
             role: "user",
             content: messageContent,
         });
+        // Process Schema/Structured Output
+        let responseFormat = this.options.responseFormat;
+        if (this.options.schema) {
+            if (this.provider.capabilities && !this.provider.capabilities.supportsStructuredOutput(this.model)) {
+                throw new Error(`Model ${this.model} does not support structured output.`);
+            }
+            const jsonSchema = toJsonSchema(this.options.schema.definition.schema);
+            responseFormat = {
+                type: "json_schema",
+                json_schema: {
+                    name: this.options.schema.definition.name,
+                    description: this.options.schema.definition.description,
+                    strict: this.options.schema.definition.strict ?? true,
+                    schema: jsonSchema,
+                }
+            };
+        }
         const executeOptions = {
             model: this.model,
             messages: this.messages,
@@ -165,6 +246,7 @@ export class Chat {
             temperature: options?.temperature ?? this.options.temperature,
             max_tokens: options?.maxTokens ?? this.options.maxTokens,
             headers: { ...this.options.headers, ...options?.headers },
+            response_format: responseFormat, // Pass to provider
         };
         let totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
         const trackUsage = (u) => {

package/dist/chat/ChatOptions.d.ts

@@ -1,5 +1,6 @@
 import { Message } from "./Message.js";
 import { Tool } from "./Tool.js";
+import { Schema } from "../schema/Schema.js";
 export interface ChatOptions {
     systemPrompt?: string;
     messages?: Message[];
@@ -11,5 +12,9 @@ export interface ChatOptions {
     onToolCall?: (toolCall: any) => void;
     onToolResult?: (result: any) => void;
     headers?: Record<string, string>;
+    schema?: Schema;
+    responseFormat?: {
+        type: "json_object" | "text";
+    };
 }
 //# 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;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"}
+{"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;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,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;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAA;KAAE,CAAC;CACnD"}

package/dist/chat/ChatResponse.d.ts

@@ -14,5 +14,10 @@ export declare class ChatResponseString extends String {
     get content(): string;
     get model_id(): string;
     toString(): string;
+    /**
+     * Attempt to parse the content as JSON.
+     * Returns the parsed object or null if parsing fails.
+     */
+    get parsed(): any;
 }
 //# sourceMappingURL=ChatResponse.d.ts.map

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

@@ -1 +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"}
+{"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;IAIR;;;OAGG;IACH,IAAI,MAAM,IAAI,GAAG,CAMhB;CACF"}

package/dist/chat/ChatResponse.js

@@ -23,4 +23,16 @@ export class ChatResponseString extends String {
     toString() {
         return this.valueOf();
     }
+    /**
+     * Attempt to parse the content as JSON.
+     * Returns the parsed object or null if parsing fails.
+     */
+    get parsed() {
+        try {
+            return JSON.parse(this.valueOf());
+        }
+        catch (e) {
+            return null;
+        }
+    }
 }

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_MODELS: {
+    readonly TRANSCRIPTION: "whisper-1";
+    readonly MODERATION: "omni-moderation-latest";
+    readonly EMBEDDING: "text-embedding-3-small";
+    readonly IMAGE: "dall-e-3";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,6 @@
+export const DEFAULT_MODELS = {
+    TRANSCRIPTION: "whisper-1",
+    MODERATION: "omni-moderation-latest",
+    EMBEDDING: "text-embedding-3-small",
+    IMAGE: "dall-e-3",
+};

package/dist/embedding/Embedding.d.ts

@@ -0,0 +1,17 @@
+import { EmbeddingResponse } from "../providers/Embedding.js";
+export declare class Embedding {
+    readonly vectors: number[][];
+    readonly model: string;
+    readonly input_tokens: number;
+    readonly dimensions: number;
+    constructor(response: EmbeddingResponse);
+    /**
+     * Get the first vector (useful for single-input embeddings)
+     */
+    get vector(): number[];
+    /**
+     * Convert to string representation (shows dimensions and token count)
+     */
+    toString(): string;
+}
+//# sourceMappingURL=Embedding.d.ts.map

package/dist/embedding/Embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Embedding.d.ts","sourceRoot":"","sources":["../../src/embedding/Embedding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,qBAAa,SAAS;IACpB,SAAgB,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC;IACpC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,QAAQ,EAAE,iBAAiB;IAOvC;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,EAAE,CAErB;IAED;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/embedding/Embedding.js

@@ -0,0 +1,24 @@
+export class Embedding {
+    vectors;
+    model;
+    input_tokens;
+    dimensions;
+    constructor(response) {
+        this.vectors = response.vectors;
+        this.model = response.model;
+        this.input_tokens = response.input_tokens;
+        this.dimensions = response.dimensions;
+    }
+    /**
+     * Get the first vector (useful for single-input embeddings)
+     */
+    get vector() {
+        return this.vectors[0] || [];
+    }
+    /**
+     * Convert to string representation (shows dimensions and token count)
+     */
+    toString() {
+        return `Embedding(model=${this.model}, dimensions=${this.dimensions}, tokens=${this.input_tokens}, count=${this.vectors.length})`;
+    }
+}

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, Transcription, Moderation } from "./llm.js";
+export { LLM, Transcription, Moderation, Embedding } 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,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"}
+{"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,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,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, Transcription, Moderation } from "./llm.js";
+export { LLM, Transcription, Moderation, Embedding } from "./llm.js";
 export { providerRegistry } from "./providers/registry.js";
 export { OpenAIProvider } from "./providers/openai/OpenAIProvider.js";
 export { registerOpenAIProvider } from "./providers/openai/index.js";