modelmix 4.3.4 → 4.3.6

package/README.md

@@ -23,6 +23,11 @@ Recommended: install dotenv to manage environment variables
 npm install modelmix dotenv
 ```
 
+> **AI Skill**: You can also add ModelMix as a skill for AI agentic development:
+> ```bash
+> npx skills add https://github.com/clasen/ModelMix --skill modelmix
+> ```
+
 2. **Setup your environment variables (.env file)**:
 Only the API keys you plan to use are required.
 ```plaintext
@@ -55,7 +60,7 @@ console.log(await model.json(outputExample));
 const setup = {
     config: {
         system: "You are ALF, if they ask your name, respond with 'ALF'.",
-        debug: true
+        debug: 2
     }
 };
 
@@ -187,107 +192,175 @@ const result = await ModelMix.new({
     .message();
 ```
 
-## 🔄 Templating Methods
+## 🔄 Templates
+
+ModelMix includes a simple but powerful templating system. You can write your system prompts and user messages in external `.md` files with placeholders, then use `replace` to fill them in at runtime.
 
-### `replace` Method
+### Core methods
 
-The `replace` method is used to define key-value pairs for text replacement in the messages and system prompt. 
+| Method | Description |
+| --- | --- |
+| `setSystemFromFile(path)` | Load the system prompt from a file |
+| `addTextFromFile(path)` | Load a user message from a file |
+| `replace({ key: value })` | Replace placeholders in all messages and the system prompt |
+| `replaceKeyFromFile(key, path)` | Replace a placeholder with the contents of a file |
+
+### Basic example with `replace`
 
-#### Usage:
 ```javascript
-model.replace({ '{{key1}}': 'value1', '{{key2}}': 'value2' });
+const gpt = ModelMix.new().gpt5mini();
+
+gpt.addText('Write a short story about a {animal} that lives in {place}.');
+gpt.replace({ '{animal}': 'cat', '{place}': 'a haunted castle' });
+
+console.log(await gpt.message());
 ```
 
-#### How it works:
-1. It updates the `config.replace` object with the provided key-value pairs.
-2. In the template, placeholders like `{{key1}}` will be replaced with 'value1'.
+### Loading prompts from `.md` files
 
-#### Example:
-```javascript
-model
-  .replace({ '{{name}}': 'Alice', '{{age}}': '30' })
-  .addText('Hello {{name}}, are you {{age}} years old?');
+Instead of writing long prompts inline, keep them in separate Markdown files. This makes them easier to read, edit, and version control.
+
+**`prompts/system.md`**
+```markdown
+You are {role}, an expert in {topic}.
+Always respond in {language}.
 ```
-This would result in the message: "Hello Alice, are you 30 years old?"
 
-### `replaceKeyFromFile` Method
+**`prompts/task.md`**
+```markdown
+Analyze the following and provide 3 key insights:
 
-The `replaceKeyFromFile` method is similar to `replace`, but it reads the replacement value from a file.
+{content}
+```
 
-#### Usage:
+**`app.js`**
 ```javascript
-model.replaceKeyFromFile('longText', './path/to/file.txt');
+const gpt = ModelMix.new().gpt5mini();
+
+gpt.setSystemFromFile('./prompts/system.md');
+gpt.addTextFromFile('./prompts/task.md');
+
+gpt.replace({
+    '{role}': 'a senior analyst',
+    '{topic}': 'market trends',
+    '{language}': 'Spanish',
+    '{content}': 'Bitcoin surpassed $100,000 in December 2024...'
+});
+
+console.log(await gpt.message());
 ```
 
-#### How it works:
-1. It reads the content of the specified file synchronously.
-2. It then calls the `replace` method, using the provided key and the file content as the value.
+### Injecting file contents into a placeholder
+
+Use `replaceKeyFromFile` when the replacement value itself is a large text stored in a file.
+
+**`prompts/summarize.md`**
+```markdown
+Summarize the following article in 3 bullet points:
 
-#### Example:
+{article}
+```
+
+**`app.js`**
 ```javascript
-messageHandler
-  .replaceKeyFromFile('article_file_contents', './article.txt')
-  .addText('Please summarize this article: article_file_contents');
+const gpt = ModelMix.new().gpt5mini();
+
+gpt.addTextFromFile('./prompts/summarize.md');
+gpt.replaceKeyFromFile('{article}', './data/article.md');
+
+console.log(await gpt.message());
 ```
-This would replace `article_file_contents` with the entire content of 'article.txt'.
 
-### When to use each method:
-- Use `replace` for short, inline replacements or dynamically generated content.
-- Use `replaceKeyFromFile` for longer texts or content that's stored externally.
+### Full template workflow
+
+Combine all methods to build reusable, file-based prompt pipelines:
 
-Both methods allow for flexible content insertion, enabling you to create dynamic and customizable prompts for your AI model interactions.
+**`prompts/system.md`**
+```markdown
+You are {role}. Follow these rules:
+- Be concise
+- Use examples when possible
+- Respond in {language}
+```
 
-## 🧩 JSON Export Options
+**`prompts/review.md`**
+```markdown
+Review the following code and suggest improvements:
 
-The `json` method signature includes these options:
+{code}
+```
 
+**`app.js`**
 ```javascript
-async json(schemaExample = null, schemaDescription = {}, { 
-    type = 'json_object', 
-    addExample = false, 
-    addSchema = true, 
-    addNote = false 
-} = {})
+const gpt = ModelMix.new().gpt5mini();
+
+gpt.setSystemFromFile('./prompts/system.md');
+gpt.addTextFromFile('./prompts/review.md');
+
+gpt.replace({ '{role}': 'a senior code reviewer', '{language}': 'English' });
+gpt.replaceKeyFromFile('{code}', './src/utils.js');
+
+console.log(await gpt.message());
 ```
 
-### Option Details
+## 🧩 JSON Structured Output
 
-**`addSchema` (default: `true`)**
-- When set to `true`, includes the generated JSON schema in the system prompt
+The `json` method forces the model to return a structured JSON response. You define the shape with an example object and optionally describe each field.
 
-**`addExample` (default: `false`)**
-- When set to `true`, adds the example JSON structure to the system prompt
+```javascript
+await model.json(schemaExample, schemaDescription, options)
+```
 
-**`addNote` (default: `false`)**
-- When set to `true`, adds a technical note about JSON formatting requirements
-- Specifically adds this instruction to the system prompt:
-  ```
-  Output JSON Note: Escape all unescaped double quotes, backslashes, and ASCII control characters inside JSON strings, and ensure the output contains no comments.
-  ```
-- Helps prevent common JSON parsing errors
+### Basic usage
 
-### Usage Examples
+```javascript
+const model = ModelMix.new()
+    .gpt5mini()
+    .addText('Name and capital of 3 South American countries.');
+
+const result = await model.json({ countries: [{ name: "", capital: "" }] });
+console.log(result);
+// { countries: [{ name: "Argentina", capital: "Buenos Aires" }, ...] }
+```
+
+### Adding field descriptions
+
+The second argument lets you describe each field so the model understands exactly what you expect:
 
 ```javascript
-// Basic usage with example and note
-const result = await model.json(
-    { name: "John", age: 30, skills: ["JavaScript", "Python"] },
-    { name: "Person's full name", age: "Age in years" },
-    { addExample: true, addNote: true }
-);
+const model = ModelMix.new()
+    .gpt5mini()
+    .addText('Name and capital of 3 South American countries.');
 
-// Only add the example, skip the technical note
 const result = await model.json(
-    { status: "success", data: [] },
-    {},
-    { addExample: true, addNote: false }
+    { countries: [{ name: "Argentina", capital: "BUENOS AIRES" }] },
+    { countries: [{ name: "name of the country", capital: "capital of the country in uppercase" }] },
+    { addNote: true }
 );
+console.log(result);
+// { countries: [
+//   { name: "Brazil", capital: "BRASILIA" },
+//   { name: "Colombia", capital: "BOGOTA" },
+//   { name: "Chile", capital: "SANTIAGO" }
+// ]}
+```
 
-// Add note for robust JSON parsing
+The example values (like `"Argentina"` and `"BUENOS AIRES"`) show the model the expected format, while the descriptions clarify what each field should contain.
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `addSchema` | `true` | Include the generated JSON schema in the system prompt |
+| `addExample` | `false` | Include the example object in the system prompt |
+| `addNote` | `false` | Add a note about JSON escaping to prevent parsing errors |
+
+```javascript
+// Include the example and the escaping note
 const result = await model.json(
-    { message: "Hello \"world\"" },
-    {},
-    { addNote: true }
+    { name: "John", age: 30, skills: ["JavaScript"] },
+    { name: "Full name", age: "Age in years", skills: "List of programming languages" },
+    { addExample: true, addNote: true }
 );
 ```
 
@@ -311,16 +384,28 @@ Every response from `raw()` now includes a `tokens` object with the following st
 }
 ```
 
+### `lastRaw` — Access full response after `message()` or `json()`
+
+After calling `message()` or `json()`, use `lastRaw` to access the complete response (tokens, thinking, tool calls, etc.). It has the same structure as `raw()`.
+
+```javascript
+const text = await model.message();
+console.log(model.lastRaw.tokens);
+// { input: 122, output: 86, total: 541, cost: 0.000319 }
+```
+
+The `cost` field is the estimated cost in USD based on the model's pricing per 1M tokens (input/output). If the model is not found in the pricing table, `cost` will be `null`.
+
 ## 🐛 Enabling Debug Mode
 
 To activate debug mode in ModelMix and view detailed request information, follow these two steps:
 
-1. In the ModelMix constructor, include `debug: true` in the configuration:
+1. In the ModelMix constructor, include `debug: 3` in the configuration:
 
    ```javascript
    const mix = ModelMix.new({
      config: {
-       debug: true
+       debug: 3
        // ... other configuration options ...
      }
    });
@@ -390,10 +475,14 @@ new ModelMix(args = { options: {}, config: {} })
 - `new()`: `static` Creates a new `ModelMix`.
 - `new()`: Creates a new `ModelMix` using instance setup.
 
+- `setSystem(text)`: Sets the system prompt.
+- `setSystemFromFile(filePath)`: Sets the system prompt from a file.
 - `addText(text, config = { role: "user" })`: Adds a text message.
-- `addTextFromFile(filePath, config = { role: "user" })`: Adds a text message from a file path.
+- `addTextFromFile(filePath, config = { role: "user" })`: Adds a text message from a file.
 - `addImage(filePath, config = { role: "user" })`: Adds an image message from a file path.
 - `addImageFromUrl(url, config = { role: "user" })`: Adds an image message from URL.
+- `replace(keyValues)`: Defines placeholder replacements for messages and system prompt.
+- `replaceKeyFromFile(key, filePath)`: Defines a placeholder replacement with file contents as value.
 - `message()`: Sends the message and returns the response.
 - `raw()`: Sends the message and returns the complete response data including:
   - `message`: The text response from the model

package/demo/custom.js

@@ -9,7 +9,7 @@ const mmix = new ModelMix({
     config: {
         system: 'You are ALF from Melmac.',
         max_history: 2,
-        debug: true
+        debug: 3
     }
 });
 

package/demo/demo.js

@@ -10,7 +10,7 @@ const mmix = new ModelMix({
         system: 'You are {name} from Melmac.',
         max_history: 2,
         bottleneck: { maxConcurrent: 1 },
-        debug: true,
+        debug: 3,
     }
 });
 
@@ -33,7 +33,7 @@ gpt.replace({ '{animal}': 'cat' });
 await gpt.json({ time: '24:00:00', message: 'Hello' }, { time: 'Time in format HH:MM:SS' });
 
 console.log("\n" + '--------| sonnet45() |--------');
-const claude = mmix.new({ config: { debug: true } }).sonnet45();
+const claude = mmix.new({ config: { debug: 2 } }).sonnet45();
 claude.addImageFromUrl('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC');
 claude.addText('in one word, which is the main color of the image?');
 const imageDescription = await claude.message();

package/demo/free.js

@@ -1,7 +1,7 @@
 process.loadEnvFile();
 import { ModelMix } from '../index.js';
 
-const ai = ModelMix.new({ config: { debug: true } })
+const ai = ModelMix.new({ config: { debug: 2 } })
     .gptOss()
     .kimiK2()
     .deepseekR1()

package/demo/gpt51.js

@@ -3,7 +3,7 @@ import { ModelMix } from '../index.js';
 
 const mmix = new ModelMix({
     config: {
-        debug: true,
+        debug: 2,
     }
 });
 

package/demo/grok.js

@@ -9,7 +9,7 @@ const mmix = new ModelMix({
     config: {
         system: 'You are ALF from Melmac.',
         max_history: 2,
-        debug: true
+        debug: 2
     }
 });
 

package/demo/images.js

@@ -1,7 +1,7 @@
 process.loadEnvFile();
 import { ModelMix } from '../index.js';
 
-const model = ModelMix.new({ config: { max_history: 2, debug: true } }).maverick()
+const model = ModelMix.new({ config: { max_history: 2, debug: 2 } }).maverick()
 // model.addImageFromUrl('https://pbs.twimg.com/media/F6-GsjraAAADDGy?format=jpg');
 model.addImage('./img.png');
 model.addText('in one word, which is the main color of the image?');

package/demo/json.js

@@ -1,8 +1,8 @@
 process.loadEnvFile();
 import { ModelMix } from '../index.js';
 
-const model = await ModelMix.new({ options: { max_tokens: 10000 }, config: { debug: true } })
-    .gemini3pro()
+const model = await ModelMix.new({ options: { max_tokens: 10000 }, config: { debug: 3 } })
+    .gemini3flash()
     // .gptOss()
     // .scout({ config: { temperature: 0 } })    
     // .o4mini()
@@ -11,5 +11,17 @@ const model = await ModelMix.new({ options: { max_tokens: 10000 }, config: { deb
     // .gemini25flash()
     .addText("Name and capital of 3 South American countries.")
 
-const jsonResult = await model.json({ countries: [{ name: "", capital: "" }] }, {}, { addNote: true });
-console.log(jsonResult);
+const jsonResult = await model.json({
+    countries: [{
+        name: "Argentina",
+        capital: "BUENOS AIRES"
+    }]
+}, {
+    countries: [{
+        name: "name of the country",
+        capital: "capital of the country in uppercase"
+    }]
+}, { addNote: true });
+
+console.log(jsonResult);
+console.log(model.lastRaw.tokens);

package/demo/mcp-simple.js

@@ -92,7 +92,7 @@ async function simpleCalculator() {
 async function contentGenerator() {
     console.log('\n=== Content Generator ===');
 
-    const mmix = ModelMix.new({ config: { debug: true, max_history: 1 } })
+    const mmix = ModelMix.new({ config: { debug: 2, max_history: 1 } })
         .gemini3flash()
         .setSystem('You are a creative assistant that can generate different types of content.');
 

package/demo/minimax.js

@@ -6,7 +6,7 @@ process.loadEnvFile();
 const main = async () => {
 
     const bot = ModelMix
-        .new({ config: { debug: true } })
+        .new({ config: { debug: 3 } })
         .minimaxM21()
         .setSystem('You are a helpful assistant.');
 

package/demo/parallel.js

@@ -10,7 +10,7 @@ const mix = new ModelMix({
         bottleneck: {
             maxConcurrent: 1,     // Maximum number of concurrent requests
         },
-        debug: true,
+        debug: 3,
     }
 })
 

package/demo/repl-powers.js

@@ -11,7 +11,7 @@ const isolate = new ivm.Isolate({ memoryLimit: 128 }); // 128MB máximo
 async function replPowersExample() {
     console.log('\n=== JavaScript REPL - Potencias de 2 ===\n');
     const gptArgs = { options: { reasoning_effort: "none", verbosity: null } };
-    const mmix = ModelMix.new({ config: { debug: true, max_history: 10 } })
+    const mmix = ModelMix.new({ config: { debug: 2, max_history: 10 } })
         .gpt41nano()
         .gpt52(gptArgs)
         .gemini3flash()

package/demo/short.js

@@ -5,7 +5,7 @@ import { ModelMix } from '../index.js';
 const setup = {
     config: {
         system: "You are ALF, if they ask your name, answer 'ALF'.",
-        debug: true
+        debug: 2
     }
 };
 

package/index.js

@@ -10,6 +10,81 @@ const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
 const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
 const { MCPToolsManager } = require('./mcp-tools');
 
+// Pricing per 1M tokens: [input, output] in USD
+// Based on provider pricing pages linked in README
+const MODEL_PRICING = {
+    // OpenAI
+    'gpt-5.2': [1.75, 14.00],
+    'gpt-5.2-chat-latest': [1.75, 14.00],
+    'gpt-5.1': [1.25, 10.00],
+    'gpt-5': [1.25, 10.00],
+    'gpt-5-mini': [0.25, 2.00],
+    'gpt-5-nano': [0.05, 0.40],
+    'gpt-4.1': [2.00, 8.00],
+    'gpt-4.1-mini': [0.40, 1.60],
+    'gpt-4.1-nano': [0.10, 0.40],
+    // gptOss (Together/Groq/Cerebras/OpenRouter)
+    'openai/gpt-oss-120b': [0.15, 0.60],
+    'gpt-oss-120b': [0.15, 0.60],
+    'openai/gpt-oss-120b:free': [0, 0],
+    // Anthropic
+    'claude-opus-4-6': [5.00, 25.00],
+    'claude-opus-4-5-20251101': [5.00, 25.00],
+    'claude-opus-4-1-20250805': [15.00, 75.00],
+    'claude-sonnet-4-5-20250929': [3.00, 15.00],
+    'claude-sonnet-4-20250514': [3.00, 15.00],
+    'claude-3-5-haiku-20241022': [0.80, 4.00],
+    'claude-haiku-4-5-20251001': [1.00, 5.00],
+    // Google
+    'gemini-3-pro-preview': [2.00, 12.00],
+    'gemini-3-flash-preview': [0.50, 3.00],
+    'gemini-2.5-pro': [1.25, 10.00],
+    'gemini-2.5-flash': [0.30, 2.50],
+    // Grok
+    'grok-4-0709': [3.00, 15.00],
+    'grok-4-1-fast-reasoning': [0.20, 0.50],
+    'grok-4-1-fast-non-reasoning': [0.20, 0.50],
+    // Fireworks
+    'accounts/fireworks/models/deepseek-v3p2': [0.56, 1.68],
+    'accounts/fireworks/models/glm-4p7': [0.55, 2.19],
+    'accounts/fireworks/models/kimi-k2p5': [0.50, 2.80],
+    // MiniMax
+    'MiniMax-M2.1': [0.30, 1.20],
+    // Perplexity
+    'sonar': [1.00, 1.00],
+    'sonar-pro': [3.00, 15.00],
+    // Scout (Groq/Together/Cerebras)
+    'meta-llama/llama-4-scout-17b-16e-instruct': [0.11, 0.34],
+    'meta-llama/Llama-4-Scout-17B-16E-Instruct': [0.11, 0.34],
+    'llama-4-scout-17b-16e-instruct': [0.11, 0.34],
+    // Maverick (Groq/Together/Lambda)
+    'meta-llama/llama-4-maverick-17b-128e-instruct': [0.20, 0.60],
+    'meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8': [0.20, 0.60],
+    'llama-4-maverick-17b-128e-instruct-fp8': [0.20, 0.60],
+    // Hermes3 (Lambda/OpenRouter)
+    'Hermes-3-Llama-3.1-405B-FP8': [0.80, 0.80],
+    'nousresearch/hermes-3-llama-3.1-405b:free': [0, 0],
+    // Qwen3 (Together/Cerebras)
+    'Qwen/Qwen3-235B-A22B-fp8-tput': [0.20, 0.60],
+    'qwen-3-32b': [0.20, 0.60],
+    // Kimi K2 (Together/Groq/OpenRouter)
+    'moonshotai/Kimi-K2-Instruct-0905': [1.00, 3.00],
+    'moonshotai/kimi-k2-instruct-0905': [1.00, 3.00],
+    'moonshotai/kimi-k2:free': [0, 0],
+    'moonshotai/Kimi-K2-Thinking': [1.00, 3.00],
+    'moonshotai/kimi-k2-thinking': [1.00, 3.00],
+    // Kimi K2.5 (Together/Fireworks/OpenRouter)
+    'moonshotai/Kimi-K2.5': [0.50, 2.80],
+    'moonshotai/kimi-k2.5': [0.50, 2.80],
+    // DeepSeek V3.2 (OpenRouter)
+    'deepseek/deepseek-v3.2': [0.56, 1.68],
+    // GLM 4.7 (OpenRouter/Cerebras)
+    'z-ai/glm-4.7': [0.55, 2.19],
+    'zai-glm-4.7': [0.55, 2.19],
+    // DeepSeek R1 (OpenRouter free)
+    'deepseek/deepseek-r1-0528:free': [0, 0],
+};
+
 class ModelMix {
 
     constructor({ options = {}, config = {}, mix = {} } = {}) {
@@ -19,6 +94,7 @@ class ModelMix {
         this.toolClient = {};
         this.mcp = {};
         this.mcpToolsManager = new MCPToolsManager();
+        this.lastRaw = null;
         this.options = {
             max_tokens: 8192,
             temperature: 1, // 1 --> More creative, 0 --> More deterministic.
@@ -82,11 +158,18 @@ class ModelMix {
     }
 
     // debug logging helpers
-    static truncate(str, maxLen = 100) {
+    static truncate(str, maxLen = 1000) {
         if (!str || typeof str !== 'string') return str;
         return str.length > maxLen ? str.substring(0, maxLen) + '...' : str;
     }
 
+    static calculateCost(modelKey, tokens) {
+        const pricing = MODEL_PRICING[modelKey];
+        if (!pricing) return null;
+        const [inputPerMillion, outputPerMillion] = pricing;
+        return (tokens.input * inputPerMillion / 1_000_000) + (tokens.output * outputPerMillion / 1_000_000);
+    }
+
     static formatInputSummary(messages, system) {
         const lastMessage = messages[messages.length - 1];
         let inputText = '';
@@ -98,8 +181,8 @@ class ModelMix {
             inputText = lastMessage.content;
         }
 
-        const systemStr = `System: ${ModelMix.truncate(system, 50)}`;
-        const inputStr = `Input: ${ModelMix.truncate(inputText, 120)}`;
+        const systemStr = `System: ${ModelMix.truncate(system, 500)}`;
+        const inputStr = `Input: ${ModelMix.truncate(inputText, 1200)}`;
         const msgCount = `(${messages.length} msg${messages.length !== 1 ? 's' : ''})`;
 
         return `${systemStr} \n| ${inputStr} ${msgCount}`;
@@ -115,15 +198,15 @@ class ModelMix {
                 if (debug >= 2) {
                     parts.push(`Output (JSON):\n${ModelMix.formatJSON(parsed)}`);
                 } else {
-                    parts.push(`Output: ${ModelMix.truncate(result.message, 150)}`);
+                    parts.push(`Output: ${ModelMix.truncate(result.message, 1500)}`);
                 }
             } catch (e) {
                 // Not JSON, show truncated as before
-                parts.push(`Output: ${ModelMix.truncate(result.message, 150)}`);
+                parts.push(`Output: ${ModelMix.truncate(result.message, 1500)}`);
             }
         }
         if (result.think) {
-            parts.push(`Think: ${ModelMix.truncate(result.think, 80)}`);
+            parts.push(`Think: ${ModelMix.truncate(result.think, 800)}`);
         }
         if (result.toolCalls && result.toolCalls.length > 0) {
             const toolNames = result.toolCalls.map(t => t.function?.name || t.name).join(', ');
@@ -772,6 +855,11 @@ class ModelMix {
 
                     const result = await providerInstance.create({ options: currentOptions, config: currentConfig });
 
+                    // Calculate cost based on model pricing
+                    if (result.tokens) {
+                        result.tokens.cost = ModelMix.calculateCost(currentModelKey, result.tokens);
+                    }
+
                     if (result.toolCalls && result.toolCalls.length > 0) {
 
                         if (result.message) {
@@ -832,6 +920,7 @@ class ModelMix {
 
                     if (currentConfig.debug >= 1) console.log('');
 
+                    this.lastRaw = result;
                     return result;
 
                 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.3.4",
+  "version": "4.3.6",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {
@@ -9,6 +9,7 @@
   },
   "keywords": [
     "mcp",
+    "skill",
     "llm",
     "ai",
     "model",
@@ -72,4 +73,4 @@
     "test:live.mcp": "mocha test/live.mcp.js --timeout 60000 --require dotenv/config --require test/setup.js",
     "test:tokens": "mocha test/tokens.test.js --timeout 10000 --require dotenv/config --require test/setup.js"
   }
-}
+}

package/skills/modelmix/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: modelmix
+description: Instructions for using the ModelMix Node.js library to interact with multiple AI LLM providers through a unified interface. Use when integrating AI models (OpenAI, Anthropic, Google, Groq, Perplexity, Grok, etc.), chaining models with fallback, getting structured JSON from LLMs, adding MCP tools, streaming responses, or managing multi-provider AI workflows in Node.js.
+---
+
+# ModelMix Library Skill
+
+## Overview
+
+ModelMix is a Node.js library that provides a unified fluent API to interact with multiple AI LLM providers. It handles automatic fallback between models, round-robin load balancing, structured JSON output, streaming, MCP tool integration, rate limiting, and token tracking.
+
+Use this skill when:
+- Integrating one or more AI models into a Node.js project
+- Chaining models with automatic fallback
+- Extracting structured JSON from LLMs
+- Adding MCP tools or custom tools to models
+- Working with templates and file-based prompts
+
+Do NOT use this skill for:
+- Python or non-Node.js projects
+- Direct HTTP calls to LLM APIs (use ModelMix instead)
+
+## Installation
+
+```bash
+npm install modelmix
+```
+
+## Core Concepts
+
+### Import
+
+```javascript
+import { ModelMix } from 'modelmix';
+```
+
+### Creating an Instance
+
+```javascript
+// Static factory (preferred)
+const model = ModelMix.new();
+
+// With global options
+const model = ModelMix.new({
+    options: { max_tokens: 4096, temperature: 0.7 },
+    config: {
+        system: "You are a helpful assistant.",
+        max_history: 5,
+        debug: 0,           // 0=silent, 1=minimal, 2=summary, 3=full
+        roundRobin: false    // false=fallback, true=rotate models
+    }
+});
+```
+
+### Attaching Models (Fluent Chain)
+
+Chain shorthand methods to attach providers. First model is primary; others are fallbacks:
+
+```javascript
+const model = ModelMix.new()
+    .sonnet45()        // primary
+    .gpt5mini()        // fallback 1
+    .gemini3flash()    // fallback 2
+    .addText("Hello!")
+```
+
+If `sonnet45` fails, it automatically tries `gpt5mini`, then `gemini3flash`.
+
+## Available Model Shorthands
+
+- **OpenAI**: `gpt52` `gpt51` `gpt5` `gpt5mini` `gpt5nano` `gpt41` `gpt41mini` `gpt41nano`
+- **Anthropic**: `opus46` `opus45` `sonnet45` `sonnet4` `haiku45` `haiku35` (thinking variants: add `think` suffix)
+- **Google**: `gemini3pro` `gemini3flash` `gemini25pro` `gemini25flash`
+- **Grok**: `grok4` `grok41` (thinking variant available)
+- **Perplexity**: `sonar` `sonarPro`
+- **Groq**: `scout` `maverick`
+- **Together**: `qwen3` `kimiK2`
+- **Multi-provider**: `deepseekR1` `gptOss`
+- **MiniMax**: `minimaxM21`
+- **Fireworks**: `deepseekV32` `GLM47`
+
+Each method is called as `mix.methodName()` and accepts optional `{ options, config }` to override per-model settings.
+
+## Common Tasks
+
+### Get a text response
+
+```javascript
+const answer = await ModelMix.new()
+    .gpt5mini()
+    .addText("What is the capital of France?")
+    .message();
+```
+
+### Get structured JSON
+
+```javascript
+const result = await ModelMix.new()
+    .gpt5mini()
+    .addText("Name and capital of 3 South American countries.")
+    .json(
+        { countries: [{ name: "", capital: "" }] },                    // schema example
+        { countries: [{ name: "country name", capital: "in uppercase" }] }, // descriptions
+        { addNote: true }                                               // options
+    );
+// result.countries → [{ name: "Brazil", capital: "BRASILIA" }, ...]
+```
+
+`json()` signature: `json(schemaExample, schemaDescription?, { addSchema, addExample, addNote }?)`
+
+### Stream a response
+
+```javascript
+await ModelMix.new()
+    .gpt5mini()
+    .addText("Tell me a story.")
+    .stream(({ delta, message }) => {
+        process.stdout.write(delta);
+    });
+```
+
+### Get raw response (tokens, thinking, tool calls)
+
+```javascript
+const raw = await ModelMix.new()
+    .sonnet45think()
+    .addText("Solve this step by step: 2+2*3")
+    .raw();
+// raw.message, raw.think, raw.tokens, raw.toolCalls, raw.response
+```
+
+### Access full response after `message()` or `json()` with `lastRaw`
+
+After calling `message()`, `json()`, `block()`, or `stream()`, use `lastRaw` to access the complete response (tokens, thinking, tool calls, etc.). It has the same structure as `raw()`.
+
+```javascript
+const model = ModelMix.new().gpt5mini().addText("Hello!");
+const text = await model.message();
+console.log(model.lastRaw.tokens);
+// { input: 122, output: 86, total: 541, cost: 0.000319 }
+console.log(model.lastRaw.think);    // reasoning content (if available)
+console.log(model.lastRaw.response); // raw API response
+```
+
+### Add images
+
+```javascript
+const model = ModelMix.new().sonnet45();
+model.addImage('./photo.jpg');                         // from file
+model.addImageFromUrl('https://example.com/img.png');  // from URL
+model.addText('Describe this image.');
+const description = await model.message();
+```
+
+### Use templates with placeholders
+
+```javascript
+const model = ModelMix.new().gpt5mini();
+model.setSystemFromFile('./prompts/system.md');
+model.addTextFromFile('./prompts/task.md');
+model.replace({
+    '{role}': 'data analyst',
+    '{language}': 'Spanish'
+});
+model.replaceKeyFromFile('{code}', './src/utils.js');
+console.log(await model.message());
+```
+
+### Round-robin load balancing
+
+```javascript
+const pool = ModelMix.new({ config: { roundRobin: true } })
+    .gpt5mini()
+    .sonnet45()
+    .gemini3flash();
+
+// Each call rotates to the next model
+const r1 = await pool.new().addText("Request 1").message();
+const r2 = await pool.new().addText("Request 2").message();
+```
+
+### MCP integration (external tools)
+
+```javascript
+const model = ModelMix.new({ config: { max_history: 10 } }).gpt5nano();
+model.setSystem('You are an assistant. Today is ' + new Date().toISOString());
+await model.addMCP('@modelcontextprotocol/server-brave-search');
+model.addText('Use Internet: What is the latest news about AI?');
+console.log(await model.message());
+```
+
+Requires `BRAVE_API_KEY` in `.env` for Brave Search MCP.
+
+### Custom local tools (addTool)
+
+```javascript
+const model = ModelMix.new({ config: { max_history: 10 } }).gpt5mini();
+
+model.addTool({
+    name: "get_weather",
+    description: "Get weather for a city",
+    inputSchema: {
+        type: "object",
+        properties: { city: { type: "string" } },
+        required: ["city"]
+    }
+}, async ({ city }) => {
+    return `The weather in ${city} is sunny, 25C`;
+});
+
+model.addText("What's the weather in Tokyo?");
+console.log(await model.message());
+```
+
+### Rate limiting (Bottleneck)
+
+```javascript
+const model = ModelMix.new({
+    config: {
+        bottleneck: {
+            maxConcurrent: 4,
+            minTime: 1000
+        }
+    }
+}).gpt5mini();
+```
+
+### Debug mode
+
+```javascript
+const model = ModelMix.new({
+    config: { debug: 2 }  // 0=silent, 1=minimal, 2=summary, 3=full
+}).gpt5mini();
+```
+
+For full debug output, also set the env: `DEBUG=ModelMix* node script.js`
+
+### Use free-tier models
+
+```javascript
+// These use providers with free quotas (OpenRouter, Groq, Cerebras)
+const model = ModelMix.new()
+    .gptOss()
+    .kimiK2()
+    .deepseekR1()
+    .hermes3()
+    .addText("What is the capital of France?");
+console.log(await model.message());
+```
+
+### Conversation history
+
+```javascript
+const chat = ModelMix.new({ config: { max_history: 10 } }).gpt5mini();
+chat.addText("My name is Martin.");
+await chat.message();
+chat.addText("What's my name?");
+const reply = await chat.message();  // "Martin"
+```
+
+## Agent Usage Rules
+
+- Always check `package.json` for `modelmix` before running `npm install`.
+- Use `ModelMix.new()` static factory to create instances (not `new ModelMix()`).
+- Store API keys in `.env` and load with `dotenv/config` or `process.loadEnvFile()`. Never hardcode keys.
+- Chain models for resilience: primary model first, fallbacks after.
+- When using MCP tools or `addTool()`, set `max_history` to at least 3.
+- Use `.json()` for structured output instead of parsing text manually.
+- Use `.message()` for simple text, `.raw()` when you need tokens/thinking/toolCalls.
+- For thinking models, append `think` to the method name (e.g. `sonnet45think()`).
+- Template placeholders use `{key}` syntax in both system prompts and user messages.
+- The library uses CommonJS internally (`require`) but supports ESM import via `{ ModelMix }`.
+- Available provider Mix classes for custom setups: `MixOpenAI`, `MixAnthropic`, `MixGoogle`, `MixPerplexity`, `MixGroq`, `MixTogether`, `MixGrok`, `MixOpenRouter`, `MixOllama`, `MixLMStudio`, `MixCustom`, `MixCerebras`, `MixFireworks`, `MixMiniMax`.
+
+## API Quick Reference
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `.addText(text)` | `this` | Add user message |
+| `.addTextFromFile(path)` | `this` | Add user message from file |
+| `.setSystem(text)` | `this` | Set system prompt |
+| `.setSystemFromFile(path)` | `this` | Set system prompt from file |
+| `.addImage(path)` | `this` | Add image from file |
+| `.addImageFromUrl(url)` | `this` | Add image from URL or data URI |
+| `.replace({})` | `this` | Set placeholder replacements |
+| `.replaceKeyFromFile(key, path)` | `this` | Replace placeholder with file content |
+| `.message()` | `Promise<string>` | Get text response |
+| `.json(example, desc?, opts?)` | `Promise<object>` | Get structured JSON |
+| `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |
+| `.lastRaw` | `object \| null` | Full response from last `message()`/`json()`/`block()`/`stream()` call |
+| `.stream(callback)` | `Promise` | Stream response |
+| `.block()` | `Promise<string>` | Extract code block from response |
+| `.addMCP(package)` | `Promise` | Add MCP server tools |
+| `.addTool(def, callback)` | `this` | Register custom local tool |
+| `.addTools([{tool, callback}])` | `this` | Register multiple tools |
+| `.removeTool(name)` | `this` | Remove a tool |
+| `.listTools()` | `{local, mcp}` | List registered tools |
+| `.new()` | `ModelMix` | Clone instance sharing models |
+| `.attach(key, provider)` | `this` | Attach custom provider |
+
+## References
+
+- [GitHub Repository](https://github.com/clasen/ModelMix)