@mlx-node/lm 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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 { loadModel, Qwen3Model } from '@mlx-node/lm';
+ *
+ * const model = await loadModel('./models/qwen3-0.6b');
+ * const result = await model.generate([{ role: 'user', content: 'Hello!' }]);
+ * ```
+ */
+export { Qwen3Model, Qwen3Tokenizer } from '@mlx-node/core';
+export { Qwen35Model, Qwen35Model as Qwen3_5Model } from './stream';
+export type { Qwen35Config, Qwen35GenerationConfig, Qwen35GenerationResult } from '@mlx-node/core';
+export { Qwen35MoeModel, Qwen35MoeModel as Qwen3_5MoeModel } from './stream';
+export type { Qwen35MoeConfig, Qwen35MoeGenerationConfig, Qwen35MoeGenerationResult } from '@mlx-node/core';
+export type { DType } from '@mlx-node/core';
+export type { SamplingConfig, BatchGenerationResult } from '@mlx-node/core';
+export type { ChatConfig, ChatResult, ChatMessage, ToolCallResult, PerformanceMetrics } from '@mlx-node/core';
+export type { ChatStreamDelta, ChatStreamFinal, ChatStreamEvent } from './stream';
+export type { ChatStreamChunk, ChatStreamHandle } from '@mlx-node/core';
+export { _createChatStream } from './stream';
+export { type Qwen3Config, QWEN3_CONFIGS, type GenerationResult, type GenerationConfig, getQwen3Config, } from './models/qwen3-configs';
+export { loadModel, detectModelType, type ModelType } from './models/model-loader';
+export type { TrainableModel } from './interfaces';
+export { QWEN35_CONFIGS, getQwen35Config } from './models/qwen3_5-configs';
+export * from './tools';
+export { enableProfiling, disableProfiling } from './profiling';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"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;AAC5D,OAAO,EAAE,WAAW,EAAE,WAAW,IAAI,YAAY,EAAE,MAAM,UAAU,CAAC;AACpE,YAAY,EAAE,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAGnG,OAAO,EAAE,cAAc,EAAE,cAAc,IAAI,eAAe,EAAE,MAAM,UAAU,CAAC;AAC7E,YAAY,EAAE,eAAe,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAK5G,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5E,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAG9G,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAClF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACL,KAAK,WAAW,EAChB,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3E,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @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 { loadModel, Qwen3Model } from '@mlx-node/lm';
+ *
+ * const model = await loadModel('./models/qwen3-0.6b');
+ * const result = await model.generate([{ role: 'user', content: 'Hello!' }]);
+ * ```
+ */
+// Model classes (for inference)
+export { Qwen3Model, Qwen3Tokenizer } from '@mlx-node/core';
+export { Qwen35Model, Qwen35Model as Qwen3_5Model } from './stream';
+// MoE variant
+export { Qwen35MoeModel, Qwen35MoeModel as Qwen3_5MoeModel } from './stream';
+// Internal: exported for testing the callback-to-AsyncGenerator bridge
+// Not part of the public API — may change without notice
+export { _createChatStream } from './stream';
+// Model utilities (TypeScript-only)
+export { QWEN3_CONFIGS, getQwen3Config, } from './models/qwen3-configs';
+// Model loading
+export { loadModel, detectModelType } from './models/model-loader';
+export { QWEN35_CONFIGS, getQwen35Config } from './models/qwen3_5-configs';
+// Tool calling utilities
+export * from './tools';
+// Profiling API
+export { enableProfiling, disableProfiling } from './profiling';

package/dist/interfaces.d.ts

@@ -0,0 +1,8 @@
+import type { Qwen3Model, Qwen35Model, Qwen35MoeModel } from '@mlx-node/core';
+/**
+ * Union of all model classes that can be used with training engines.
+ * Uses the native (core) types so trainers can pass instances directly
+ * to Rust engine factory methods without type conflicts.
+ */
+export type TrainableModel = Qwen3Model | Qwen35Model | Qwen35MoeModel;
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC"}

package/dist/interfaces.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,13 @@
+/**
+ * Model loading utilities for Qwen3 models
+ *
+ * Handles loading pretrained weights from MLX format or converting from HuggingFace.
+ */
+import type { TrainableModel } from '../interfaces';
+export type ModelType = 'qwen3' | 'qwen3_5' | 'qwen3_5_moe';
+/**
+ * Load a language model from disk, auto-detecting architecture from config.json.
+ */
+export declare function loadModel(modelPath: string): Promise<TrainableModel>;
+export declare function detectModelType(modelPath: string): Promise<ModelType>;
+//# sourceMappingURL=model-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-loader.d.ts","sourceRoot":"","sources":["../../src/models/model-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;AAI5D;;GAEG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAa1E;AAED,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAa3E"}

package/dist/models/model-loader.js

@@ -0,0 +1,42 @@
+/**
+ * Model loading utilities for Qwen3 models
+ *
+ * Handles loading pretrained weights from MLX format or converting from HuggingFace.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Qwen3Model } from '@mlx-node/core';
+import { Qwen35Model, Qwen35MoeModel } from '../stream';
+const SUPPORTED_MODEL_TYPES = new Set(['qwen3', 'qwen3_5', 'qwen3_5_moe']);
+/**
+ * Load a language model from disk, auto-detecting architecture from config.json.
+ */
+export async function loadModel(modelPath) {
+    const modelType = await detectModelType(modelPath);
+    switch (modelType) {
+        case 'qwen3_5_moe':
+            // Cast: stream wrapper extends native — safe for instanceof and engine factories
+            return Qwen35MoeModel.load(modelPath);
+        case 'qwen3_5':
+            // load() auto-detects vision weights and loads encoder if present
+            return Qwen35Model.load(modelPath);
+        case 'qwen3':
+            return Qwen3Model.load(modelPath);
+    }
+}
+export async function detectModelType(modelPath) {
+    try {
+        const raw = await readFile(join(modelPath, 'config.json'), 'utf-8');
+        const config = JSON.parse(raw);
+        const modelType = config.model_type ?? 'qwen3';
+        if (!SUPPORTED_MODEL_TYPES.has(modelType)) {
+            throw new Error(`Unsupported model_type "${modelType}" in ${modelPath}/config.json`);
+        }
+        return modelType;
+    }
+    catch (e) {
+        if (e instanceof Error && e.message.startsWith('Unsupported model_type'))
+            throw e;
+        throw new Error(`Cannot detect model type: config.json not found in ${modelPath}`);
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,83 @@
+/**
+ * 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/models/qwen3_5-configs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Qwen3.5 Model Configurations and Type Definitions
+ *
+ * Supports both dense and MoE variants. MoE fields are optional -
+ * when `numExperts` is undefined, the model uses dense MLP layers.
+ */
+import type { Qwen35Config as RustQwen35Config, Qwen35GenerationConfig as RustQwen35GenerationConfig, Qwen35GenerationResult as RustQwen35GenerationResult } from '@mlx-node/core';
+export type Qwen35Config = RustQwen35Config;
+export type Qwen35GenerationConfig = RustQwen35GenerationConfig;
+export type Qwen35GenerationResult = RustQwen35GenerationResult;
+/**
+ * Default configurations for common Qwen3.5 models
+ */
+export declare const QWEN35_CONFIGS: {
+    [key: string]: Qwen35Config;
+};
+/**
+ * Get a Qwen3.5 configuration by name
+ *
+ * @param name - Model name (e.g., "qwen3.5-0.6b")
+ * @returns Model configuration
+ * @throws Error if model name is not recognized
+ */
+export declare function getQwen35Config(name: string): Qwen35Config;
+//# sourceMappingURL=qwen3_5-configs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"qwen3_5-configs.d.ts","sourceRoot":"","sources":["../../src/models/qwen3_5-configs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,YAAY,IAAI,gBAAgB,EAChC,sBAAsB,IAAI,0BAA0B,EACpD,sBAAsB,IAAI,0BAA0B,EACrD,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAC5C,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAChE,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAyBzD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAM1D"}

package/dist/models/qwen3_5-configs.js

@@ -0,0 +1,49 @@
+/**
+ * Qwen3.5 Model Configurations and Type Definitions
+ *
+ * Supports both dense and MoE variants. MoE fields are optional -
+ * when `numExperts` is undefined, the model uses dense MLP layers.
+ */
+/**
+ * Default configurations for common Qwen3.5 models
+ */
+export const QWEN35_CONFIGS = {
+    'qwen3.5-0.6b': {
+        vocabSize: 151936,
+        hiddenSize: 1024,
+        numLayers: 28,
+        numHeads: 16,
+        numKvHeads: 8,
+        intermediateSize: 3072,
+        rmsNormEps: 1e-6,
+        headDim: 64,
+        tieWordEmbeddings: true,
+        attentionBias: false,
+        maxPositionEmbeddings: 131072,
+        padTokenId: 151643,
+        eosTokenId: 151645,
+        bosTokenId: 151643,
+        linearNumValueHeads: 64,
+        linearNumKeyHeads: 16,
+        linearKeyHeadDim: 192,
+        linearValueHeadDim: 128,
+        linearConvKernelDim: 4,
+        fullAttentionInterval: 4,
+        partialRotaryFactor: 0.25,
+        ropeTheta: 100000.0,
+    },
+};
+/**
+ * Get a Qwen3.5 configuration by name
+ *
+ * @param name - Model name (e.g., "qwen3.5-0.6b")
+ * @returns Model configuration
+ * @throws Error if model name is not recognized
+ */
+export function getQwen35Config(name) {
+    const config = QWEN35_CONFIGS[name];
+    if (!config) {
+        throw new Error(`Unknown Qwen3.5 config: ${name}. Available: ${Object.keys(QWEN35_CONFIGS).join(', ')}`);
+    }
+    return config;
+}

package/dist/profiling.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Enable profiling programmatically.
+ *
+ * When enabled, all subsequent model generate/chat calls will record
+ * timing, memory, and throughput data. Call `disableProfiling()` to
+ * stop recording and write the report.
+ *
+ * If `MLX_PROFILE_DECODE` env var is set, this is a no-op (env var
+ * takes precedence).
+ */
+export declare function enableProfiling(): void;
+/**
+ * Disable profiling and write the collected data to a JSON file.
+ *
+ * Returns the path to the written file, or empty string if no data
+ * was collected. If `MLX_PROFILE_DECODE` env var is set, this is a
+ * no-op (env var controls the lifecycle).
+ */
+export declare function disableProfiling(): Promise<string>;
+//# sourceMappingURL=profiling.d.ts.map

package/dist/profiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAaA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAQtC;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAOxD"}

package/dist/profiling.js

@@ -0,0 +1,64 @@
+import { setProfilingEnabled, isProfilingEnabled, getProfilingData, resetProfilingData } from '@mlx-node/core';
+import { writeFile } from 'node:fs/promises';
+const ENV_VAR = 'MLX_PROFILE_DECODE';
+const envVarSet = !!process.env[ENV_VAR];
+let exitHandlerRegistered = false;
+// Auto-enable if env var set
+if (envVarSet) {
+    setProfilingEnabled(true);
+    registerExitHandler();
+}
+/**
+ * Enable profiling programmatically.
+ *
+ * When enabled, all subsequent model generate/chat calls will record
+ * timing, memory, and throughput data. Call `disableProfiling()` to
+ * stop recording and write the report.
+ *
+ * If `MLX_PROFILE_DECODE` env var is set, this is a no-op (env var
+ * takes precedence).
+ */
+export function enableProfiling() {
+    if (envVarSet) {
+        console.warn(`Warning: env var ${ENV_VAR} is set, ignoring explicit profiling API calls`);
+        return;
+    }
+    setProfilingEnabled(true);
+    resetProfilingData();
+    registerExitHandler();
+}
+/**
+ * Disable profiling and write the collected data to a JSON file.
+ *
+ * Returns the path to the written file, or empty string if no data
+ * was collected. If `MLX_PROFILE_DECODE` env var is set, this is a
+ * no-op (env var controls the lifecycle).
+ */
+export async function disableProfiling() {
+    if (envVarSet) {
+        console.warn(`Warning: env var ${ENV_VAR} is set, ignoring explicit profiling API calls`);
+        return '';
+    }
+    setProfilingEnabled(false);
+    return writeProfilingReport();
+}
+async function writeProfilingReport() {
+    const data = getProfilingData();
+    if (data.generations.length === 0)
+        return '';
+    const path = `mlx-profile-${Date.now()}.json`;
+    await writeFile(path, JSON.stringify(data, null, 2));
+    console.info(`Profiling report written to ${path}`);
+    return path;
+}
+function registerExitHandler() {
+    if (exitHandlerRegistered)
+        return;
+    exitHandlerRegistered = true;
+    process.on('beforeExit', async () => {
+        if (isProfilingEnabled()) {
+            setProfilingEnabled(false);
+            await writeProfilingReport();
+        }
+    });
+}

package/dist/stream.d.ts

@@ -0,0 +1,56 @@
+import { Qwen35Model as Qwen35ModelNative, Qwen35MoeModel as Qwen35MoeModelNative } from '@mlx-node/core';
+import type { ChatConfig, ChatMessage, ChatStreamChunk, ChatStreamHandle, PerformanceMetrics, ToolCallResult } from '@mlx-node/core';
+export interface ChatStreamDelta {
+    text: string;
+    done: false;
+}
+export interface ChatStreamFinal {
+    text: string;
+    done: true;
+    finishReason: string;
+    toolCalls: ToolCallResult[];
+    thinking: string | null;
+    numTokens: number;
+    rawText: string;
+    performance?: PerformanceMetrics;
+}
+export type ChatStreamEvent = ChatStreamDelta | ChatStreamFinal;
+/**
+ * Shared AsyncGenerator implementation that wraps a native callback-based
+ * chatStream into a `for await...of`-compatible stream.
+ *
+ * Cancellation is automatic via the generator's `finally` block.
+ */
+/** @internal Exported for testing only. */
+export declare function _createChatStream(nativeMethod: (messages: ChatMessage[], config: any, callback: (err: Error | null, chunk: ChatStreamChunk) => void) => Promise<ChatStreamHandle>, self: unknown, messages: ChatMessage[], config: unknown): AsyncGenerator<ChatStreamEvent>;
+/**
+ * Qwen3.5 dense model with AsyncGenerator-based `chatStream()`.
+ *
+ * @example
+ * ```typescript
+ * const model = await Qwen35Model.load('./models/qwen3.5-3b');
+ * for await (const event of model.chatStream(messages)) {
+ *   if (!event.done) process.stdout.write(event.text);
+ * }
+ * ```
+ */
+export declare class Qwen35Model extends Qwen35ModelNative {
+    static load(modelPath: string): Promise<Qwen35Model>;
+    chatStream(messages: ChatMessage[], config?: ChatConfig | null): AsyncGenerator<ChatStreamEvent>;
+}
+/**
+ * Qwen3.5 MoE model with AsyncGenerator-based `chatStream()`.
+ *
+ * @example
+ * ```typescript
+ * const model = await Qwen35MoeModel.load('./models/qwen3.5-moe');
+ * for await (const event of model.chatStream(messages)) {
+ *   if (!event.done) process.stdout.write(event.text);
+ * }
+ * ```
+ */
+export declare class Qwen35MoeModel extends Qwen35MoeModelNative {
+    static load(modelPath: string): Promise<Qwen35MoeModel>;
+    chatStream(messages: ChatMessage[], config?: ChatConfig | null): AsyncGenerator<ChatStreamEvent>;
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,iBAAiB,EAAE,cAAc,IAAI,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC1G,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,eAAe,CAAC;AAQhE;;;;;GAKG;AACH,2CAA2C;AAC3C,wBAAuB,iBAAiB,CAEtC,YAAY,EAAE,CACZ,QAAQ,EAAE,WAAW,EAAE,EACvB,MAAM,EAAE,GAAG,EACX,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,eAAe,KAAK,IAAI,KAC1D,OAAO,CAAC,gBAAgB,CAAC,EAC9B,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,WAAW,EAAE,EACvB,MAAM,EAAE,OAAO,GACd,cAAc,CAAC,eAAe,CAAC,CAoDjC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAY,SAAQ,iBAAiB;WAC1B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAO5D,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,cAAc,CAAC,eAAe,CAAC;CAGxG;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,oBAAoB;WAChC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAO/D,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,cAAc,CAAC,eAAe,CAAC;CAGxG"}

package/dist/stream.js

@@ -0,0 +1,108 @@
+import { Qwen35Model as Qwen35ModelNative, Qwen35MoeModel as Qwen35MoeModelNative } from '@mlx-node/core';
+// Save references to the native callback-based methods before we override them
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeDenseChatStream = Qwen35ModelNative.prototype.chatStream;
+// oxlint-disable-next-line @typescript-eslint/unbound-method
+const _nativeMoeChatStream = Qwen35MoeModelNative.prototype.chatStream;
+/**
+ * Shared AsyncGenerator implementation that wraps a native callback-based
+ * chatStream into a `for await...of`-compatible stream.
+ *
+ * Cancellation is automatic via the generator's `finally` block.
+ */
+/** @internal Exported for testing only. */
+export async function* _createChatStream(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+nativeMethod, self, messages, config) {
+    const queue = [];
+    let resolve = null;
+    const waitForItem = () => queue.length > 0
+        ? Promise.resolve()
+        : new Promise((r) => {
+            resolve = r;
+        });
+    const notify = () => {
+        if (resolve) {
+            const r = resolve;
+            resolve = null;
+            r();
+        }
+    };
+    const callback = (err, chunk) => {
+        queue.push(err ? { error: err } : { chunk });
+        notify();
+    };
+    const handle = await nativeMethod.call(self, messages, config ?? null, callback);
+    try {
+        while (true) {
+            await waitForItem();
+            while (queue.length > 0) {
+                const item = queue.shift();
+                if (item.error)
+                    throw item.error;
+                const chunk = item.chunk;
+                if (chunk.done) {
+                    yield {
+                        text: chunk.text,
+                        done: true,
+                        finishReason: chunk.finishReason,
+                        toolCalls: chunk.toolCalls ?? [],
+                        thinking: chunk.thinking ?? null,
+                        numTokens: chunk.numTokens,
+                        rawText: chunk.rawText,
+                        performance: chunk.performance ?? undefined,
+                    };
+                    return;
+                }
+                yield { text: chunk.text, done: false };
+            }
+        }
+    }
+    finally {
+        handle.cancel();
+    }
+}
+/**
+ * Qwen3.5 dense model with AsyncGenerator-based `chatStream()`.
+ *
+ * @example
+ * ```typescript
+ * const model = await Qwen35Model.load('./models/qwen3.5-3b');
+ * for await (const event of model.chatStream(messages)) {
+ *   if (!event.done) process.stdout.write(event.text);
+ * }
+ * ```
+ */
+export class Qwen35Model extends Qwen35ModelNative {
+    static async load(modelPath) {
+        const instance = await Qwen35ModelNative.load(modelPath);
+        Object.setPrototypeOf(instance, Qwen35Model.prototype);
+        return instance;
+    }
+    // @ts-expect-error — override callback-based chatStream with AsyncGenerator
+    async *chatStream(messages, config) {
+        yield* _createChatStream(_nativeDenseChatStream, this, messages, config);
+    }
+}
+/**
+ * Qwen3.5 MoE model with AsyncGenerator-based `chatStream()`.
+ *
+ * @example
+ * ```typescript
+ * const model = await Qwen35MoeModel.load('./models/qwen3.5-moe');
+ * for await (const event of model.chatStream(messages)) {
+ *   if (!event.done) process.stdout.write(event.text);
+ * }
+ * ```
+ */
+export class Qwen35MoeModel extends Qwen35MoeModelNative {
+    static async load(modelPath) {
+        const instance = await Qwen35MoeModelNative.load(modelPath);
+        Object.setPrototypeOf(instance, Qwen35MoeModel.prototype);
+        return instance;
+    }
+    // @ts-expect-error — override callback-based chatStream with AsyncGenerator
+    async *chatStream(messages, config) {
+        yield* _createChatStream(_nativeMoeChatStream, this, messages, config);
+    }
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,30 @@
+/**
+ * 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

@@ -0,0 +1,206 @@
+/**
+ * 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 (matches core ChatMessage.role type)
+ */
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,101 @@
+/**
+ * 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);
+    // Qwen3/3.5 expects <tool_response> XML wrapping for tool results.
+    // Other model families may require a different format.
+    return `<tool_response>\n${contentStr}\n</tool_response>`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlx-node/lm",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "homepage": "https://github.com/mlx-node/mlx-node",
   "bugs": {
     "url": "https://github.com/mlx-node/mlx-node/issues"
@@ -28,6 +28,6 @@
     "test": "vite test run"
   },
   "dependencies": {
-    "@mlx-node/core": "0.0.1"
+    "@mlx-node/core": "0.0.3"
   }
 }