@mlx-node/lm 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,212 @@
+# @mlx-node/lm
+
+High-level language model inference for Node.js on Apple Silicon. Supports Qwen3 and Qwen3.5 (Dense and MoE) with streaming, tool calling, and profiling — all running locally on Metal GPU.
+
+## Requirements
+
+- macOS with Apple Silicon (M1 or later)
+- Node.js 18+
+
+## Installation
+
+```bash
+npm install @mlx-node/lm
+```
+
+## Quick Start
+
+```typescript
+import { loadModel } from '@mlx-node/lm';
+
+const model = await loadModel('./models/Qwen3-0.6B');
+
+const result = model.chat([{ role: 'user', content: 'What is the capital of France?' }]);
+
+console.log(result.text);
+```
+
+## Streaming
+
+Qwen3.5 models support token-by-token streaming via `AsyncGenerator`:
+
+```typescript
+import { loadModel } from '@mlx-node/lm';
+
+const model = await loadModel('./models/Qwen3.5-0.6B');
+
+for await (const event of model.chatStream(messages, config)) {
+  if (!event.done) {
+    process.stdout.write(event.text);
+  } else {
+    console.log(`\n${event.numTokens} tokens, finish: ${event.finishReason}`);
+  }
+}
+```
+
+Breaking out of the loop automatically cancels generation.
+
+## Tool Calling
+
+OpenAI-compatible function calling with `createToolDefinition`:
+
+```typescript
+import { loadModel, createToolDefinition, formatToolResponse } from '@mlx-node/lm';
+
+const model = await loadModel('./models/Qwen3-0.6B');
+
+const tools = [
+  createToolDefinition(
+    'get_weather',
+    'Get weather for a city',
+    {
+      city: { type: 'string', description: 'City name' },
+    },
+    ['city'],
+  ),
+];
+
+const result = model.chat([{ role: 'user', content: 'What is the weather in Tokyo?' }], { tools });
+
+// If the model calls a tool, execute it and continue
+if (result.toolCalls?.length) {
+  const toolResult = executeMyTool(result.toolCalls[0]);
+  const followUp = model.chat(
+    [
+      ...messages,
+      { role: 'assistant', content: result.rawText },
+      { role: 'tool', content: formatToolResponse(toolResult) },
+    ],
+    { tools },
+  );
+}
+```
+
+## Model Loading
+
+`loadModel()` auto-detects the model architecture from `config.json`:
+
+```typescript
+import { loadModel, Qwen35Model, Qwen35MoeModel } from '@mlx-node/lm';
+
+// Auto-detect (reads config.json model_type field)
+const model = await loadModel('./models/Qwen3-0.6B');
+
+// Or load a specific architecture directly
+const dense = await Qwen35Model.load('./models/Qwen3.5-0.8B');
+const moe = await Qwen35MoeModel.load('./models/Qwen3.5-35B-A3B');
+```
+
+### Pre-defined Configs
+
+```typescript
+import { QWEN3_CONFIGS, QWEN35_CONFIGS, getQwen3Config, getQwen35Config } from '@mlx-node/lm';
+
+// Available Qwen3 configs: 'qwen3-0.6b', 'qwen3-1.7b', 'qwen3-7b'
+const config = getQwen3Config('qwen3-0.6b');
+
+// Available Qwen3.5 configs: 'qwen3.5-0.8b'
+const config35 = getQwen35Config('qwen3.5-0.8b');
+```
+
+## Profiling
+
+Track per-generation timing, memory usage, and TTFT:
+
+```typescript
+import { enableProfiling, disableProfiling } from '@mlx-node/lm';
+
+enableProfiling();
+
+// ... run inference ...
+
+disableProfiling(); // writes mlx-profile-{timestamp}.json
+```
+
+Or set `MLX_PROFILE_DECODE=1` to auto-enable and write a report on exit.
+
+## API Reference
+
+### Classes
+
+| Class            | Description                                                                      |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `loadModel()`    | Auto-detect and load any supported model from disk                               |
+| `Qwen3Model`     | Qwen3 inference — `generate()`, `chat()`, paged attention, speculative decoding  |
+| `Qwen35Model`    | Qwen3.5 Dense — `generate()`, `chat()`, `chatStream()` with compiled C++ forward |
+| `Qwen35MoeModel` | Qwen3.5 MoE — same API as Dense with expert routing                              |
+
+### Streaming Types
+
+```typescript
+// Intermediate token
+interface ChatStreamDelta {
+  text: string;
+  done: false;
+}
+
+// Final result
+interface ChatStreamFinal {
+  text: string;
+  done: true;
+  finishReason: string;
+  toolCalls?: ToolCallResult[];
+  thinking?: string;
+  numTokens: number;
+  rawText: string;
+  performance?: PerformanceMetrics;
+}
+
+type ChatStreamEvent = ChatStreamDelta | ChatStreamFinal;
+```
+
+### Tool Types
+
+```typescript
+interface ToolDefinition {
+  type: 'function';
+  function: FunctionDefinition;
+}
+
+interface FunctionDefinition {
+  name: string;
+  description?: string;
+  parameters?: FunctionParameters;
+}
+
+function createToolDefinition(
+  name: string,
+  description?: string,
+  properties?: Record<string, FunctionParameterProperty>,
+  required?: string[],
+): ToolDefinition;
+
+function formatToolResponse(content: string): string;
+```
+
+### Functions
+
+| Function                 | Description                                          |
+| ------------------------ | ---------------------------------------------------- |
+| `createToolDefinition()` | Create an OpenAI-compatible tool definition          |
+| `formatToolResponse()`   | Wrap tool output in `<tool_response>` tags           |
+| `detectModelType()`      | Read `config.json` and return the `model_type` field |
+| `enableProfiling()`      | Start profiling with auto-report on exit             |
+| `disableProfiling()`     | Stop profiling and write JSON report                 |
+
+## Supported Models
+
+| Model         | `chat()` | `chatStream()` | Training | Notes                                 |
+| ------------- | :------: | :------------: | :------: | ------------------------------------- |
+| Qwen3         |   Yes    |       No       | GRPO/SFT | Paged attention, speculative decoding |
+| Qwen3.5 Dense |   Yes    |      Yes       | GRPO/SFT | Compiled C++ forward, VLM variant     |
+| Qwen3.5 MoE   |   Yes    |      Yes       | GRPO/SFT | Compiled C++ forward, expert routing  |
+
+## Performance
+
+- Almost the same with the python `mlx-lm` package
+- Metal GPU acceleration on all Apple Silicon
+- Compiled forward passes via `mlx::core::compile` for graph caching
+
+## License
+
+[MIT](https://github.com/mlx-node/mlx-node/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@mlx-node/lm",
-  "version": "0.0.0",
+  "version": "0.0.1",
+  "homepage": "https://github.com/mlx-node/mlx-node",
+  "bugs": {
+    "url": "https://github.com/mlx-node/mlx-node/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mlx-node/mlx-node.git",
+    "directory": "packages/lm"
+  },
   "files": [
     "dist"
   ],
@@ -18,6 +28,6 @@
     "test": "vite test run"
   },
   "dependencies": {
-    "@mlx-node/core": "0.0.0"
+    "@mlx-node/core": "0.0.1"
   }
 }

package/dist/index.d.ts

@@ -1,22 +0,0 @@
-/**
- * @mlx-node/lm - High-level inference API for MLX models
- *
- * This package provides everything needed for model loading and inference,
- * aligned with Python's mlx-lm library.
- *
- * @example
- * ```typescript
- * import { Qwen3Model, ModelLoader, QWEN3_CONFIGS } from '@mlx-node/lm';
- *
- * const model = await ModelLoader.loadPretrained('./models/qwen3-0.6b');
- * const result = await model.generate([{ role: 'user', content: 'Hello!' }]);
- * ```
- */
-export { Qwen3Model, Qwen3Tokenizer } from '@mlx-node/core';
-export type { DType } from '@mlx-node/core';
-export type { SamplingConfig, BatchGenerationResult } from '@mlx-node/core';
-export type { ToolCallResult, ChatResult, ChatConfig, ChatMessage } from '@mlx-node/core';
-export { type Qwen3Config, QWEN3_CONFIGS, type GenerationResult, type GenerationConfig, getQwen3Config, } from './models/qwen3-configs';
-export { ModelLoader } from './models/model-loader';
-export * from './tools';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAK5D,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5E,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG1F,OAAO,EACL,KAAK,WAAW,EAChB,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -1,21 +0,0 @@
-/**
- * @mlx-node/lm - High-level inference API for MLX models
- *
- * This package provides everything needed for model loading and inference,
- * aligned with Python's mlx-lm library.
- *
- * @example
- * ```typescript
- * import { Qwen3Model, ModelLoader, QWEN3_CONFIGS } from '@mlx-node/lm';
- *
- * const model = await ModelLoader.loadPretrained('./models/qwen3-0.6b');
- * const result = await model.generate([{ role: 'user', content: 'Hello!' }]);
- * ```
- */
-// Model classes (for inference)
-export { Qwen3Model, Qwen3Tokenizer } from '@mlx-node/core';
-// Model utilities (TypeScript-only)
-export { QWEN3_CONFIGS, getQwen3Config, } from './models/qwen3-configs';
-export { ModelLoader } from './models/model-loader';
-// Tool calling utilities
-export * from './tools';

package/dist/models/model-loader.d.ts

@@ -1,32 +0,0 @@
-/**
- * Model loader utilities for Qwen3 models
- *
- * Handles loading pretrained weights from MLX format or converting from HuggingFace.
- */
-import { Qwen3Model } from '@mlx-node/core';
-/**
- * Model loader for Qwen3 models
- */
-export declare class ModelLoader {
-    /**
-     * Load a pretrained Qwen3 model from disk
-     *
-     * Delegates to Rust implementation for efficient loading without JavaScript memory limits.
-     *
-     * @param modelPath - Path to the model directory or file
-     * @param _deviceMap - Device placement (not used in MLX, kept for compatibility)
-     * @returns Loaded model
-     */
-    static loadPretrained(modelPath: string, _deviceMap?: string): Promise<Qwen3Model>;
-    /**
-     * Save model configuration and metadata to disk
-     *
-     * This delegates to the Rust implementation which efficiently handles
-     * model saving without running into JavaScript memory/array size limits.
-     *
-     * Note: This saves configuration and parameter metadata only.
-     * For full model weight serialization, use safetensors or binary format.
-     */
-    static saveModel(model: Qwen3Model, savePath: string): Promise<void>;
-}
-//# sourceMappingURL=model-loader.d.ts.map

package/dist/models/model-loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"model-loader.d.ts","sourceRoot":"","sources":["../../src/models/model-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;;OAQG;WACU,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,GAAE,MAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAKhG;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIrE"}

package/dist/models/model-loader.js

@@ -1,37 +0,0 @@
-/**
- * Model loader utilities for Qwen3 models
- *
- * Handles loading pretrained weights from MLX format or converting from HuggingFace.
- */
-import { Qwen3Model } from '@mlx-node/core';
-/**
- * Model loader for Qwen3 models
- */
-export class ModelLoader {
-    /**
-     * Load a pretrained Qwen3 model from disk
-     *
-     * Delegates to Rust implementation for efficient loading without JavaScript memory limits.
-     *
-     * @param modelPath - Path to the model directory or file
-     * @param _deviceMap - Device placement (not used in MLX, kept for compatibility)
-     * @returns Loaded model
-     */
-    static async loadPretrained(modelPath, _deviceMap = 'auto') {
-        // Delegate to Rust implementation for efficient loading
-        return await Qwen3Model.loadPretrained(modelPath);
-    }
-    /**
-     * Save model configuration and metadata to disk
-     *
-     * This delegates to the Rust implementation which efficiently handles
-     * model saving without running into JavaScript memory/array size limits.
-     *
-     * Note: This saves configuration and parameter metadata only.
-     * For full model weight serialization, use safetensors or binary format.
-     */
-    static saveModel(model, savePath) {
-        // Delegate to Rust implementation for efficient saving
-        return model.saveModel(savePath);
-    }
-}

package/dist/models/qwen3-configs.d.ts

@@ -1,48 +0,0 @@
-/**
- * Qwen3 Model Configurations and Type Definitions
- *
- * This module provides:
- * - Default configurations for common Qwen3 model sizes
- * - Type re-exports from Rust with enhanced documentation
- * - Helper functions for config management
- */
-import type { Qwen3Config as RustQwen3Config, GenerationConfig as RustGenerationConfig, GenerationResult as RustGenerationResult } from '@mlx-node/core';
-/**
- * Configuration for Qwen3 models
- *
- * All fields are required when creating a model directly.
- * Use QWEN3_CONFIGS for pre-configured model sizes.
- */
-export type Qwen3Config = RustQwen3Config;
-/**
- * Configuration for text generation
- *
- * Controls sampling behavior, temperature, and stopping criteria.
- */
-export type GenerationConfig = RustGenerationConfig;
-/**
- * Result from text generation with detailed metadata
- *
- * Includes generated tokens, log probabilities, finish reason, and token count.
- */
-export type GenerationResult = RustGenerationResult;
-/**
- * Default configurations for common Qwen3 models
- *
- * Includes optimized hyperparameters for:
- * - qwen3-0.6b: Smallest model (1024 hidden size, 28 layers)
- * - qwen3-1.8b: Medium model (1536 hidden size, 28 layers)
- * - qwen3-7b: Large model (3072 hidden size, 32 layers)
- */
-export declare const QWEN3_CONFIGS: {
-    [key: string]: Qwen3Config;
-};
-/**
- * Get a Qwen3 configuration by name
- *
- * @param name - Model name (e.g., "qwen3-0.6b", "qwen3-1.8b", "qwen3-7b")
- * @returns Model configuration
- * @throws Error if model name is not recognized
- */
-export declare function getQwen3Config(name: string): Qwen3Config;
-//# sourceMappingURL=qwen3-configs.d.ts.map

package/dist/models/qwen3-configs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"qwen3-configs.d.ts","sourceRoot":"","sources":["../../src/models/qwen3-configs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,IAAI,eAAe,EAC9B,gBAAgB,IAAI,oBAAoB,EACxC,gBAAgB,IAAI,oBAAoB,EACzC,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;CAoDvD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAMxD"}

package/dist/models/qwen3-configs.js

@@ -1,83 +0,0 @@
-/**
- * Qwen3 Model Configurations and Type Definitions
- *
- * This module provides:
- * - Default configurations for common Qwen3 model sizes
- * - Type re-exports from Rust with enhanced documentation
- * - Helper functions for config management
- */
-/**
- * Default configurations for common Qwen3 models
- *
- * Includes optimized hyperparameters for:
- * - qwen3-0.6b: Smallest model (1024 hidden size, 28 layers)
- * - qwen3-1.8b: Medium model (1536 hidden size, 28 layers)
- * - qwen3-7b: Large model (3072 hidden size, 32 layers)
- */
-export const QWEN3_CONFIGS = {
-    'qwen3-0.6b': {
-        vocabSize: 151936,
-        hiddenSize: 1024,
-        numLayers: 28,
-        numHeads: 16,
-        numKvHeads: 8, // GQA with 2:1 ratio
-        headDim: 64, // hiddenSize / numHeads = 1024 / 16 = 64
-        intermediateSize: 3072,
-        rmsNormEps: 1e-6,
-        ropeTheta: 1000000.0,
-        maxPositionEmbeddings: 40960,
-        useQkNorm: true, // Qwen3 always uses QK normalization (core feature)
-        tieWordEmbeddings: true,
-        padTokenId: 151643,
-        eosTokenId: 151645,
-        bosTokenId: 151643,
-    },
-    'qwen3-1.8b': {
-        vocabSize: 151936,
-        hiddenSize: 1536,
-        numLayers: 28,
-        numHeads: 12,
-        numKvHeads: 2, // GQA with 6:1 ratio
-        headDim: 128, // hiddenSize / numHeads = 1536 / 12 = 128
-        intermediateSize: 8960,
-        rmsNormEps: 1e-6,
-        ropeTheta: 1000000.0,
-        maxPositionEmbeddings: 131072,
-        useQkNorm: true, // Qwen3 always uses QK normalization (core feature)
-        tieWordEmbeddings: false,
-        padTokenId: 151643,
-        eosTokenId: 151645,
-        bosTokenId: 151643,
-    },
-    'qwen3-7b': {
-        vocabSize: 151936,
-        hiddenSize: 3072,
-        numLayers: 32,
-        numHeads: 24,
-        numKvHeads: 4, // GQA with 6:1 ratio
-        headDim: 128, // hiddenSize / numHeads = 3072 / 24 = 128
-        intermediateSize: 18944,
-        rmsNormEps: 1e-6,
-        ropeTheta: 1000000.0,
-        maxPositionEmbeddings: 131072,
-        useQkNorm: true, // Qwen3 always uses QK normalization (core feature)
-        tieWordEmbeddings: false,
-        padTokenId: 151643,
-        eosTokenId: 151645,
-        bosTokenId: 151643,
-    },
-};
-/**
- * Get a Qwen3 configuration by name
- *
- * @param name - Model name (e.g., "qwen3-0.6b", "qwen3-1.8b", "qwen3-7b")
- * @returns Model configuration
- * @throws Error if model name is not recognized
- */
-export function getQwen3Config(name) {
-    const config = QWEN3_CONFIGS[name];
-    if (!config) {
-        throw new Error(`Unknown model configuration: ${name}. Available models: ${Object.keys(QWEN3_CONFIGS).join(', ')}`);
-    }
-    return config;
-}

package/dist/tools/index.d.ts

@@ -1,31 +0,0 @@
-/**
- * Tool calling utilities for Qwen3
- *
- * Provides types and helpers for working with tool/function calling in the chat() API.
- *
- * @example
- * ```typescript
- * import { createToolDefinition, formatToolResponse } from '@mlx-node/lm';
- *
- * const weatherTool = createToolDefinition(
- *   'get_weather',
- *   'Get weather for a location',
- *   { location: { type: 'string', description: 'City name' } },
- *   ['location']
- * );
- *
- * const result = await model.chat(messages, { tools: [weatherTool] });
- *
- * for (const call of result.toolCalls) {
- *   if (call.status === 'ok') {
- *     const toolResult = await executeMyTool(call.name, call.arguments);
- *     // Continue conversation with tool result
- *     messages.push({ role: 'user', content: formatToolResponse(toolResult) });
- *   }
- * }
- * ```
- *
- * @module tools
- */
-export * from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,cAAc,SAAS,CAAC"}

package/dist/tools/index.js

@@ -1,30 +0,0 @@
-/**
- * Tool calling utilities for Qwen3
- *
- * Provides types and helpers for working with tool/function calling in the chat() API.
- *
- * @example
- * ```typescript
- * import { createToolDefinition, formatToolResponse } from '@mlx-node/lm';
- *
- * const weatherTool = createToolDefinition(
- *   'get_weather',
- *   'Get weather for a location',
- *   { location: { type: 'string', description: 'City name' } },
- *   ['location']
- * );
- *
- * const result = await model.chat(messages, { tools: [weatherTool] });
- *
- * for (const call of result.toolCalls) {
- *   if (call.status === 'ok') {
- *     const toolResult = await executeMyTool(call.name, call.arguments);
- *     // Continue conversation with tool result
- *     messages.push({ role: 'user', content: formatToolResponse(toolResult) });
- *   }
- * }
- * ```
- *
- * @module tools
- */
-export * from './types';

package/dist/tools/types.d.ts

@@ -1,206 +0,0 @@
-/**
- * OpenAI-compatible tool calling types for Qwen3
- *
- * These types match the OpenAI function calling API format and can be used
- * with applyChatTemplate() when tools are provided.
- *
- * @remarks
- * **Important**: Due to NAPI-RS limitations with recursive generic types,
- * `FunctionParameters.properties` must be passed as a JSON string to the Rust layer.
- * Use the {@link createToolDefinition} helper to automatically handle this conversion.
- *
- * @example
- * ```typescript
- * // Recommended: Use the helper function
- * const tool = createToolDefinition('get_weather', 'Get weather info', {
- *   location: { type: 'string', description: 'City name' },
- *   units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
- * }, ['location']);
- *
- * // Manual approach (if needed)
- * const manualTool: ToolDefinition = {
- *   type: 'function',
- *   function: {
- *     name: 'get_weather',
- *     parameters: {
- *       type: 'object',
- *       properties: JSON.stringify({ location: { type: 'string' } }),
- *       required: ['location']
- *     }
- *   }
- * };
- * ```
- */
-/**
- * Tool type - currently only "function" is supported
- */
-export type ToolType = 'function';
-/**
- * Function parameter property definition (JSON Schema subset)
- *
- * This type is used for the developer-friendly API in {@link createToolDefinition}.
- * It represents the structure of JSON Schema properties.
- */
-export interface FunctionParameterProperty {
-    type: 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object';
-    description?: string;
-    enum?: string[];
-    items?: FunctionParameterProperty;
-    properties?: Record<string, FunctionParameterProperty>;
-    required?: string[];
-}
-/**
- * Function parameters schema (JSON Schema subset)
- *
- * @remarks
- * **NAPI Limitation**: The `properties` field must be a JSON string, not an object.
- * This is because NAPI-RS cannot expose recursive generic types like
- * `Record<string, FunctionParameterProperty>` directly to Rust.
- *
- * Use {@link createToolDefinition} to avoid manual JSON.stringify() calls.
- */
-export interface FunctionParameters {
-    /** Type of the parameters object (always "object") */
-    type: 'object';
-    /**
-     * JSON string of property definitions.
-     *
-     * @remarks
-     * Must be a JSON-stringified object, e.g.: `JSON.stringify({ name: { type: 'string' } })`
-     * Use {@link createToolDefinition} helper to avoid manual stringification.
-     */
-    properties?: string;
-    /** List of required parameter names */
-    required?: string[];
-}
-/**
- * Function definition for tool calling
- */
-export interface FunctionDefinition {
-    /** Name of the function */
-    name: string;
-    /** Description of what the function does */
-    description?: string;
-    /** JSON Schema for the function parameters */
-    parameters?: FunctionParameters;
-}
-/**
- * OpenAI-compatible tool definition
- */
-export interface ToolDefinition {
-    /** Tool type (currently only "function" is supported) */
-    type: ToolType;
-    /** Function definition */
-    function: FunctionDefinition;
-}
-/**
- * Tool call made by an assistant
- */
-export interface ToolCall {
-    /** Optional unique identifier for the tool call */
-    id?: string;
-    /** Name of the tool/function to call */
-    name: string;
-    /** JSON string of arguments to pass to the tool */
-    arguments: string;
-}
-/**
- * Chat message roles
- */
-export type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
-/**
- * Chat message with tool calling support
- *
- * This extends the basic ChatMessage to support tool calls and responses.
- */
-export interface ChatMessageWithTools {
-    /** Message role */
-    role: ChatRole;
-    /** Message content */
-    content: string;
-    /** Tool calls made by the assistant (for assistant messages) */
-    toolCalls?: ToolCall[];
-    /** Tool call ID this message is responding to (for tool messages) */
-    toolCallId?: string;
-    /** Reasoning content for thinking mode (used with <think> tags) */
-    reasoningContent?: string;
-}
-/**
- * Options for applying chat template with tools
- */
-export interface ApplyChatTemplateOptions {
-    /** Whether to add generation prompt at end (default: true) */
-    addGenerationPrompt?: boolean;
-    /** Array of tool definitions for function calling */
-    tools?: ToolDefinition[];
-    /**
-     * Control thinking mode behavior.
-     *
-     * @remarks
-     * **Counter-intuitive semantics** (from Qwen3's Jinja2 template):
-     * - `undefined` or `true`: Model thinks naturally (no tags added)
-     * - `false`: Adds empty `<think>\n\n</think>\n\n` tags to **disable** thinking
-     *
-     * The default is `false` for tool use, which disables thinking to avoid
-     * verbose reasoning during tool calls.
-     *
-     * @example
-     * ```typescript
-     * // Allow model to think (default behavior without tools)
-     * { enableThinking: true }
-     *
-     * // Disable thinking (adds empty <think></think> tags)
-     * { enableThinking: false }
-     * ```
-     */
-    enableThinking?: boolean;
-}
-/**
- * Create a tool definition with automatic JSON stringification of properties.
- *
- * This helper handles the NAPI-RS limitation where `properties` must be a JSON string.
- *
- * @param name - The function name
- * @param description - Description of what the function does
- * @param properties - Object defining the function parameters (will be JSON stringified)
- * @param required - Array of required parameter names
- * @returns A properly formatted ToolDefinition ready for use with model.chat()
- *
- * @example
- * ```typescript
- * const weatherTool = createToolDefinition(
- *   'get_weather',
- *   'Get weather information for a location',
- *   {
- *     location: { type: 'string', description: 'City name' },
- *     units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
- *   },
- *   ['location']
- * );
- *
- * const result = await model.chat(messages, { tools: [weatherTool] });
- * ```
- */
-export declare function createToolDefinition(name: string, description?: string, properties?: Record<string, FunctionParameterProperty>, required?: string[]): ToolDefinition;
-/**
- * Format a tool response for inclusion in a message
- *
- * Creates a properly formatted tool response string that can be used
- * in tool messages when continuing a conversation after a tool call.
- *
- * @param content - The response content (will be JSON stringified if object)
- * @returns Formatted tool response string wrapped in `<tool_response>` tags
- *
- * @example
- * ```typescript
- * // After executing a tool call from model.chat()
- * const toolResult = await executeMyTool(call.arguments);
- * const responseMessage = {
- *   role: 'user',
- *   content: formatToolResponse(toolResult)
- * };
- * const finalResult = await model.chat([...messages, responseMessage]);
- * ```
- */
-export declare function formatToolResponse(content: unknown): string;
-//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC;AAElC;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,IAAI,EAAE,QAAQ,CAAC;IACf,0BAA0B;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mBAAmB;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,qDAAqD;IACrD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAehB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAK3D"}

package/dist/tools/types.js

@@ -1,101 +0,0 @@
-/**
- * OpenAI-compatible tool calling types for Qwen3
- *
- * These types match the OpenAI function calling API format and can be used
- * with applyChatTemplate() when tools are provided.
- *
- * @remarks
- * **Important**: Due to NAPI-RS limitations with recursive generic types,
- * `FunctionParameters.properties` must be passed as a JSON string to the Rust layer.
- * Use the {@link createToolDefinition} helper to automatically handle this conversion.
- *
- * @example
- * ```typescript
- * // Recommended: Use the helper function
- * const tool = createToolDefinition('get_weather', 'Get weather info', {
- *   location: { type: 'string', description: 'City name' },
- *   units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
- * }, ['location']);
- *
- * // Manual approach (if needed)
- * const manualTool: ToolDefinition = {
- *   type: 'function',
- *   function: {
- *     name: 'get_weather',
- *     parameters: {
- *       type: 'object',
- *       properties: JSON.stringify({ location: { type: 'string' } }),
- *       required: ['location']
- *     }
- *   }
- * };
- * ```
- */
-/**
- * Create a tool definition with automatic JSON stringification of properties.
- *
- * This helper handles the NAPI-RS limitation where `properties` must be a JSON string.
- *
- * @param name - The function name
- * @param description - Description of what the function does
- * @param properties - Object defining the function parameters (will be JSON stringified)
- * @param required - Array of required parameter names
- * @returns A properly formatted ToolDefinition ready for use with model.chat()
- *
- * @example
- * ```typescript
- * const weatherTool = createToolDefinition(
- *   'get_weather',
- *   'Get weather information for a location',
- *   {
- *     location: { type: 'string', description: 'City name' },
- *     units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
- *   },
- *   ['location']
- * );
- *
- * const result = await model.chat(messages, { tools: [weatherTool] });
- * ```
- */
-export function createToolDefinition(name, description, properties, required) {
-    return {
-        type: 'function',
-        function: {
-            name,
-            description,
-            parameters: properties
-                ? {
-                    type: 'object',
-                    properties: JSON.stringify(properties),
-                    required,
-                }
-                : undefined,
-        },
-    };
-}
-/**
- * Format a tool response for inclusion in a message
- *
- * Creates a properly formatted tool response string that can be used
- * in tool messages when continuing a conversation after a tool call.
- *
- * @param content - The response content (will be JSON stringified if object)
- * @returns Formatted tool response string wrapped in `<tool_response>` tags
- *
- * @example
- * ```typescript
- * // After executing a tool call from model.chat()
- * const toolResult = await executeMyTool(call.arguments);
- * const responseMessage = {
- *   role: 'user',
- *   content: formatToolResponse(toolResult)
- * };
- * const finalResult = await model.chat([...messages, responseMessage]);
- * ```
- */
-export function formatToolResponse(content) {
-    const contentStr = typeof content === 'string' ? content : JSON.stringify(content);
-    return `<tool_response>
-${contentStr}
-</tool_response>`;
-}