modelmix 4.3.0 → 4.3.2

package/README.md

@@ -92,6 +92,7 @@ This pattern allows you to:
 - Chain multiple models together
 - Automatically fall back to the next model if one fails
 - Get structured JSON responses when needed
+- Track token usage across all providers
 - Keep your code clean and maintainable
 
 ## 🔧 Model Context Protocol (MCP) Integration
@@ -291,6 +292,24 @@ const result = await model.json(
 
 These options give you fine-grained control over how much guidance you provide to the model for generating properly formatted JSON responses.
 
+## 📊 Token Usage Tracking
+
+ModelMix automatically tracks token usage for all requests across different providers, providing a unified format regardless of the underlying API.
+
+### How it works
+
+Every response from `raw()` now includes a `tokens` object with the following structure:
+
+```javascript
+{
+  tokens: {
+    input: 150,    // Number of tokens in the prompt/input
+    output: 75,    // Number of tokens in the completion/output
+    total: 225     // Total tokens used (input + output)
+  }
+}
+```
+
 ## 🐛 Enabling Debug Mode
 
 To activate debug mode in ModelMix and view detailed request information, follow these two steps:
@@ -375,7 +394,12 @@ new ModelMix(args = { options: {}, config: {} })
 - `addImage(filePath, config = { role: "user" })`: Adds an image message from a file path.
 - `addImageFromUrl(url, config = { role: "user" })`: Adds an image message from URL.
 - `message()`: Sends the message and returns the response.
-- `raw()`: Sends the message and returns the raw response data.
+- `raw()`: Sends the message and returns the complete response data including:
+  - `message`: The text response from the model
+  - `think`: Reasoning/thinking content (if available)
+  - `toolCalls`: Array of tool calls made by the model (if any)
+  - `tokens`: Object with `input`, `output`, and `total` token counts
+  - `response`: The raw API response
 - `stream(callback)`: Sends the message and streams the response, invoking the callback with each streamed part.
 - `json(schemaExample, descriptions = {})`: Forces the model to return a response in a specific JSON format.
   - `schemaExample`: Optional example of the JSON structure to be returned.

package/demo/tokens-simple.js

@@ -0,0 +1,18 @@
+process.loadEnvFile();
+import { ModelMix } from '../index.js';
+
+// Ejemplo simple: obtener información de tokens
+const model = ModelMix.new()
+    .gpt5nano()
+    .addText('What is 2+2?');
+
+const result = await model.raw();
+
+console.log('\n📊 Token Usage Information:');
+console.log('━'.repeat(50));
+console.log(`Input tokens:  ${result.tokens.input}`);
+console.log(`Output tokens: ${result.tokens.output}`);
+console.log(`Total tokens:  ${result.tokens.total}`);
+console.log('━'.repeat(50));
+console.log('\n💬 Response:', result.message);
+console.log();

package/demo/tokens.js

@@ -0,0 +1,109 @@
+process.loadEnvFile();
+import { ModelMix } from '../index.js';
+
+console.log('\n🔢 Token Usage Tracking Demo\n');
+console.log('='.repeat(60));
+
+// Example 1: Get token usage from a simple request
+console.log('\n📝 Example 1: Basic token usage tracking');
+console.log('-'.repeat(60));
+
+const model1 = ModelMix.new({ config: { debug: 1 } })
+    .gpt5nano()
+    .addText('What is 2+2?');
+
+const result1 = await model1.raw();
+console.log('\n📊 Token Usage:');
+console.log('  Input tokens:', result1.tokens.input);
+console.log('  Output tokens:', result1.tokens.output);
+console.log('  Total tokens:', result1.tokens.total);
+console.log('\n💬 Response:', result1.message);
+
+// Example 2: Compare token usage across different providers
+console.log('\n\n📝 Example 2: Token usage across providers');
+console.log('-'.repeat(60));
+
+const providers = [
+    { name: 'OpenAI GPT-5-nano', fn: (m) => m.gpt5nano() },
+    { name: 'Anthropic Haiku', fn: (m) => m.haiku35() },
+    { name: 'Google Gemini', fn: (m) => m.gemini25flash() }
+];
+
+const prompt = 'Explain quantum computing in one sentence.';
+
+for (const provider of providers) {
+    try {
+        const model = ModelMix.new({ config: { debug: 0 } });
+        provider.fn(model).addText(prompt);
+        
+        const result = await model.raw();
+        
+        console.log(`\n🤖 ${provider.name}`);
+        console.log(`  Input: ${result.tokens.input} | Output: ${result.tokens.output} | Total: ${result.tokens.total}`);
+        console.log(`  Response: ${result.message.substring(0, 80)}...`);
+    } catch (error) {
+        console.log(`\n❌ ${provider.name}: ${error.message}`);
+    }
+}
+
+// Example 3: Track tokens in a conversation
+console.log('\n\n📝 Example 3: Token usage in conversation history');
+console.log('-'.repeat(60));
+
+const conversation = ModelMix.new({ config: { debug: 0, max_history: 10 } })
+    .gpt5nano();
+
+let totalInput = 0;
+let totalOutput = 0;
+
+// First message
+conversation.addText('Hi! My name is Alice.');
+let result = await conversation.raw();
+totalInput += result.tokens.input;
+totalOutput += result.tokens.output;
+console.log(`\n💬 Turn 1: ${result.tokens.input} in, ${result.tokens.output} out`);
+
+// Second message (includes history)
+conversation.addText('What is my name?');
+result = await conversation.raw();
+totalInput += result.tokens.input;
+totalOutput += result.tokens.output;
+console.log(`💬 Turn 2: ${result.tokens.input} in, ${result.tokens.output} out`);
+
+// Third message (includes more history)
+conversation.addText('Tell me a joke about my name.');
+result = await conversation.raw();
+totalInput += result.tokens.input;
+totalOutput += result.tokens.output;
+console.log(`💬 Turn 3: ${result.tokens.input} in, ${result.tokens.output} out`);
+
+console.log('\n📊 Conversation totals:');
+console.log(`  Total input tokens: ${totalInput}`);
+console.log(`  Total output tokens: ${totalOutput}`);
+console.log(`  Grand total: ${totalInput + totalOutput}`);
+
+// Example 4: JSON response with token tracking
+console.log('\n\n📝 Example 4: JSON response with token tracking');
+console.log('-'.repeat(60));
+
+const jsonModel = ModelMix.new({ config: { debug: 0 } })
+    .gpt5nano()
+    .addText('List 3 programming languages');
+
+const jsonResult = await jsonModel.json(
+    { languages: [{ name: '', year: 0 }] }
+);
+
+// Get raw result for token info
+const rawJsonModel = ModelMix.new({ config: { debug: 0 } })
+    .gpt5nano()
+    .addText('List 3 programming languages');
+
+const rawJsonResult = await rawJsonModel.raw();
+
+console.log('\n📊 Token Usage for JSON response:');
+console.log(`  Input: ${rawJsonResult.tokens.input} | Output: ${rawJsonResult.tokens.output} | Total: ${rawJsonResult.tokens.total}`);
+console.log('\n📋 JSON Result:', jsonResult);
+
+console.log('\n' + '='.repeat(60));
+console.log('✅ Token tracking demo complete!\n');

package/index.js

@@ -1135,7 +1135,8 @@ class MixCustom {
                 response: raw,
                 message: message.trim(),
                 toolCalls: [],
-                think: null
+                think: null,
+                tokens: raw.length > 0 ? MixCustom.extractTokens(raw[raw.length - 1]) : { input: 0, output: 0, total: 0 }
             }));
             response.data.on('error', reject);
         });
@@ -1181,11 +1182,28 @@ class MixCustom {
         })) || []
     }
 
+    static extractTokens(data) {
+        // OpenAI/Groq/Together/Lambda/Cerebras/Fireworks format
+        if (data.usage) {
+            return {
+                input: data.usage.prompt_tokens || 0,
+                output: data.usage.completion_tokens || 0,
+                total: data.usage.total_tokens || 0
+            };
+        }
+        return {
+            input: 0,
+            output: 0,
+            total: 0
+        };
+    }
+
     processResponse(response) {
         return {
             message: MixCustom.extractMessage(response.data),
             think: MixCustom.extractThink(response.data),
             toolCalls: MixCustom.extractToolCalls(response.data),
+            tokens: MixCustom.extractTokens(response.data),
             response: response.data
         }
     }
@@ -1478,11 +1496,28 @@ class MixAnthropic extends MixCustom {
         return data.content[0]?.signature || null;
     }
 
+    static extractTokens(data) {
+        // Anthropic format
+        if (data.usage) {
+            return {
+                input: data.usage.input_tokens || 0,
+                output: data.usage.output_tokens || 0,
+                total: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0)
+            };
+        }
+        return {
+            input: 0,
+            output: 0,
+            total: 0
+        };
+    }
+
     processResponse(response) {
         return {
             message: MixAnthropic.extractMessage(response.data),
             think: MixAnthropic.extractThink(response.data),
             toolCalls: MixAnthropic.extractToolCalls(response.data),
+            tokens: MixAnthropic.extractTokens(response.data),
             response: response.data,
             signature: MixAnthropic.extractSignature(response.data)
         }
@@ -1706,6 +1741,7 @@ class MixLMStudio extends MixCustom {
             message: MixLMStudio.extractMessage(response.data),
             think: MixLMStudio.extractThink(response.data),
             toolCalls: MixCustom.extractToolCalls(response.data),
+            tokens: MixCustom.extractTokens(response.data),
             response: response.data
         };
     }
@@ -1926,6 +1962,7 @@ class MixGoogle extends MixCustom {
             message: MixGoogle.extractMessage(response.data),
             think: null,
             toolCalls: MixGoogle.extractToolCalls(response.data),
+            tokens: MixGoogle.extractTokens(response.data),
             response: response.data
         }
     }
@@ -1951,6 +1988,22 @@ class MixGoogle extends MixCustom {
         return data.candidates?.[0]?.content?.parts?.[0]?.text;
     }
 
+    static extractTokens(data) {
+        // Google Gemini format
+        if (data.usageMetadata) {
+            return {
+                input: data.usageMetadata.promptTokenCount || 0,
+                output: data.usageMetadata.candidatesTokenCount || 0,
+                total: data.usageMetadata.totalTokenCount || 0
+            };
+        }
+        return {
+            input: 0,
+            output: 0,
+            total: 0
+        };
+    }
+
     static getOptionsTools(tools) {
         const functionDeclarations = [];
         for (const tool in tools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.3.0",
+  "version": "4.3.2",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {
@@ -46,7 +46,7 @@
   },
   "homepage": "https://github.com/clasen/ModelMix#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "axios": "^1.12.2",
     "bottleneck": "^2.19.5",
     "file-type": "^16.5.4",
@@ -69,6 +69,7 @@
     "test:images": "mocha test/images.test.js --timeout 10000 --require test/setup.js",
     "test:bottleneck": "mocha test/bottleneck.test.js --timeout 10000 --require test/setup.js",
     "test:live": "mocha test/live.test.js --timeout 10000 --require dotenv/config --require test/setup.js",
-    "test:live.mcp": "mocha test/live.mcp.js --timeout 60000 --require dotenv/config --require test/setup.js"
+    "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/test/tokens.test.js

@@ -0,0 +1,135 @@
+import { expect } from 'chai';
+import { ModelMix } from '../index.js';
+
+describe('Token Usage Tracking', () => {
+
+    it('should track tokens in OpenAI response', async function () {
+        this.timeout(30000);
+
+        const model = ModelMix.new()
+            .gpt5nano()
+            .addText('Say hi');
+
+        const result = await model.raw();
+
+        expect(result).to.have.property('tokens');
+        expect(result.tokens).to.have.property('input');
+        expect(result.tokens).to.have.property('output');
+        expect(result.tokens).to.have.property('total');
+        
+        expect(result.tokens.input).to.be.a('number');
+        expect(result.tokens.output).to.be.a('number');
+        expect(result.tokens.total).to.be.a('number');
+        
+        expect(result.tokens.input).to.be.greaterThan(0);
+        expect(result.tokens.output).to.be.greaterThan(0);
+        expect(result.tokens.total).to.be.greaterThan(0);
+    });
+
+    it('should track tokens in Anthropic response', async function () {
+        this.timeout(30000);
+
+        const model = ModelMix.new()
+            .haiku35()
+            .addText('Say hi');
+
+        const result = await model.raw();
+
+        expect(result).to.have.property('tokens');
+        expect(result.tokens).to.have.property('input');
+        expect(result.tokens).to.have.property('output');
+        expect(result.tokens).to.have.property('total');
+        
+        expect(result.tokens.input).to.be.greaterThan(0);
+        expect(result.tokens.output).to.be.greaterThan(0);
+        expect(result.tokens.total).to.equal(result.tokens.input + result.tokens.output);
+    });
+
+    it('should track tokens in Google Gemini response', async function () {
+        this.timeout(30000);
+
+        const model = ModelMix.new()
+            .gemini25flash()
+            .addText('Say hi');
+
+        const result = await model.raw();
+
+        expect(result).to.have.property('tokens');
+        expect(result.tokens).to.have.property('input');
+        expect(result.tokens).to.have.property('output');
+        expect(result.tokens).to.have.property('total');
+        
+        expect(result.tokens.input).to.be.greaterThan(0);
+        expect(result.tokens.output).to.be.greaterThan(0);
+        expect(result.tokens.total).to.be.greaterThan(0);
+    });
+
+    it('should accumulate tokens across conversation turns', async function () {
+        this.timeout(60000);
+
+        const conversation = ModelMix.new({ config: { max_history: 10 } })
+            .gpt5nano();
+
+        // First turn
+        conversation.addText('My name is Alice');
+        const result1 = await conversation.raw();
+        
+        expect(result1.tokens.input).to.be.greaterThan(0);
+        expect(result1.tokens.output).to.be.greaterThan(0);
+
+        // Second turn (should have more input tokens due to history)
+        conversation.addText('What is my name?');
+        const result2 = await conversation.raw();
+        
+        expect(result2.tokens.input).to.be.greaterThan(result1.tokens.input);
+        expect(result2.tokens.output).to.be.greaterThan(0);
+
+        // Verify both results have valid token counts
+        expect(result1.tokens.total).to.equal(result1.tokens.input + result1.tokens.output);
+        expect(result2.tokens.total).to.be.greaterThan(0);
+    });
+
+    it('should track tokens with JSON responses', async function () {
+        this.timeout(30000);
+
+        const model = ModelMix.new()
+            .gpt5nano()
+            .addText('Return a simple greeting');
+
+        // Using raw() to get token info
+        const result = await model.raw();
+
+        expect(result).to.have.property('tokens');
+        expect(result.tokens.input).to.be.greaterThan(0);
+        expect(result.tokens.output).to.be.greaterThan(0);
+        expect(result.tokens.total).to.be.greaterThan(0);
+    });
+
+    it('should have consistent token format across providers', async function () {
+        this.timeout(90000);
+
+        const providers = [
+            { name: 'OpenAI', create: (m) => m.gpt5nano() },
+            { name: 'Anthropic', create: (m) => m.haiku35() },
+            { name: 'Google', create: (m) => m.gemini25flash() }
+        ];
+
+        for (const provider of providers) {
+            const model = ModelMix.new();
+            provider.create(model).addText('Hi');
+
+            const result = await model.raw();
+
+            // Verify consistent structure
+            expect(result.tokens, `${provider.name} should have tokens object`).to.exist;
+            expect(result.tokens.input, `${provider.name} should have input`).to.be.a('number');
+            expect(result.tokens.output, `${provider.name} should have output`).to.be.a('number');
+            expect(result.tokens.total, `${provider.name} should have total`).to.be.a('number');
+            
+            // Verify values are positive
+            expect(result.tokens.input, `${provider.name} input should be > 0`).to.be.greaterThan(0);
+            expect(result.tokens.output, `${provider.name} output should be > 0`).to.be.greaterThan(0);
+            expect(result.tokens.total, `${provider.name} total should be > 0`).to.be.greaterThan(0);
+        }
+    });
+});