modelmix 4.4.32 → 4.5.0

package/README.md

@@ -475,6 +475,29 @@ const setup = {
 
 This integration ensures that your application respects API rate limits while maximizing throughput, providing a robust solution for managing multiple AI model interactions.
 
+## 🔁 Retry (Opt-In)
+
+ModelMix supports optional intra-model retries for transient HTTP failures. When enabled, it retries the same provider before moving to fallback models.
+
+```javascript
+const mix = ModelMix.new({
+  config: {
+    retry: {
+      enabled: true,                 // Default: false (opt-in)
+      retries: 2,                    // Extra attempts after first try
+      baseDelayMs: 500,              // Exponential backoff base delay
+      maxDelayMs: 5000,              // Backoff cap
+      retryableStatusCodes: [408, 425, 429, 500, 502, 503, 504, 529]
+    }
+  }
+});
+```
+
+Behavior summary:
+- If retry is disabled (default), ModelMix keeps current behavior: immediate fallback to next model on failure.
+- If retry is enabled, ModelMix retries the same model only for configured transient status codes.
+- After retries are exhausted (or for non-retryable errors), ModelMix continues with normal fallback chain.
+
 ## 📚 ModelMix Class Overview
 
 ```javascript
@@ -496,6 +519,12 @@ new ModelMix(args = { options: {}, config: {} })
       - `reservoir`: Number of requests allowed in the reservoir period
       - `reservoirRefreshAmount`: How many requests are added when the reservoir refreshes
       - `reservoirRefreshInterval`: Reservoir refresh interval
+    - `retry`: Optional intra-model retry policy before fallback:
+      - `enabled`: Enables retry behavior (`false` by default)
+      - `retries`: Number of retries for retryable failures
+      - `baseDelayMs`: Initial backoff delay in milliseconds
+      - `maxDelayMs`: Maximum backoff delay in milliseconds
+      - `retryableStatusCodes`: HTTP status codes that should trigger retry
     - ...(Additional configuration parameters can be added as needed)
 
 **Methods**

package/demo/images.js

@@ -1,7 +1,7 @@
 import { ModelMix } from '../index.js';
 try { process.loadEnvFile(); } catch {}
 
-const model = ModelMix.new({ config: { max_history: 2, debug: 2 } }).maverick()
+const model = ModelMix.new({ config: { max_history: 2, debug: 2 } }).scout()
 // 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/mcp-tools.js

@@ -1,6 +1,5 @@
 import { ModelMix } from '../index.js';
 import fs from 'fs';
-import axios from 'axios';
 try { process.loadEnvFile(); } catch {}
 
 console.log('🧬 ModelMix - MCP Tools Demo with Callbacks');
@@ -127,8 +126,22 @@ async function example3() {
         }
     }, async ({ url, method = "GET" }) => {
         try {
-            const response = await axios({ method, url, timeout: 5000 });
-            return `HTTP ${method} ${url}\nStatus: ${response.status}\nResponse: ${JSON.stringify(response.data, null, 2)}`;
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5000);
+            const response = await fetch(url, { method, signal: controller.signal });
+            clearTimeout(timeoutId);
+            const contentType = response.headers.get('content-type') || '';
+            let data;
+            if (contentType.includes('application/json')) {
+                try {
+                    data = await response.json();
+                } catch {
+                    data = await response.text();
+                }
+            } else {
+                data = await response.text();
+            }
+            return `HTTP ${method} ${url}\nStatus: ${response.status}\nResponse: ${typeof data === 'string' ? data : JSON.stringify(data, null, 2)}`;
         } catch (error) {
             return `Error making HTTP request to ${url}: ${error.message}`;
         }

package/index.js

@@ -1,8 +1,8 @@
-const axios = require('axios');
 const fs = require('fs');
 const fileType = require('file-type');
 const detectFileTypeFromBuffer = fileType.fileTypeFromBuffer || fileType.fromBuffer;
 const { inspect } = require('util');
+const { Readable } = require('stream');
 const log = require('lemonlog')('ModelMix');
 const Bottleneck = require('bottleneck');
 const path = require('path');
@@ -12,6 +12,89 @@ const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
 const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
 const { MCPToolsManager } = require('./mcp-tools');
 
+function headersToObject(headers) {
+    return Object.fromEntries(headers.entries());
+}
+
+async function parseResponseBody(response) {
+    try {
+        return await response.json();
+    } catch {
+        try {
+            return await response.text();
+        } catch {
+            return null;
+        }
+    }
+}
+
+async function parseJsonBody(response) {
+    const text = await response.text();
+    if (!text) return null;
+    return JSON.parse(text);
+}
+
+async function buildHttpError(url, response) {
+    const details = await parseResponseBody(response);
+    const error = new Error(`Request to ${url} failed with status code ${response.status}`);
+    error.isHttpError = true;
+    error.statusCode = response.status;
+    error.details = details;
+    error.response = { status: response.status, data: details };
+    return error;
+}
+
+async function fetchJsonResponse(url, { method = 'POST', headers = {}, body } = {}) {
+    const response = await fetch(url, { method, headers, body });
+    if (!response.ok) {
+        throw await buildHttpError(url, response);
+    }
+    const data = await parseJsonBody(response);
+    return {
+        data,
+        status: response.status,
+        headers: headersToObject(response.headers)
+    };
+}
+
+async function fetchBinaryResponse(url, { method = 'GET', headers = {}, body } = {}) {
+    const response = await fetch(url, { method, headers, body });
+    if (!response.ok) {
+        throw await buildHttpError(url, response);
+    }
+    const data = Buffer.from(await response.arrayBuffer());
+    return {
+        data,
+        status: response.status,
+        headers: headersToObject(response.headers)
+    };
+}
+
+async function fetchStreamResponse(url, { method = 'POST', headers = {}, body } = {}) {
+    const response = await fetch(url, { method, headers, body });
+    if (!response.ok) {
+        throw await buildHttpError(url, response);
+    }
+    if (!response.body) {
+        throw new Error(`Request to ${url} did not return a readable stream`);
+    }
+    return {
+        data: Readable.fromWeb(response.body),
+        status: response.status,
+        headers: headersToObject(response.headers)
+    };
+}
+
+const DEFAULT_RETRYABLE_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504, 529];
+
+function getErrorStatusCode(error) {
+    return error?.statusCode ?? error?.response?.status ?? error?.response?.statusCode ?? null;
+}
+
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 // Pricing per 1M tokens: [input, output] in USD
 // Based on provider pricing pages linked in README
 const MODEL_PRICING = {
@@ -128,6 +211,13 @@ class ModelMix {
             max_history: 0, // 0=no history (stateless), N=keep last N messages, -1=unlimited
             debug: 0, // 0=silent, 1=minimal, 2=readable summary, 3=full (no truncate), 4=verbose (raw details)
             bottleneck: defaultBottleneckConfig,
+            retry: {
+                enabled: false,
+                retries: 2,
+                baseDelayMs: 500,
+                maxDelayMs: 5000,
+                retryableStatusCodes: [...DEFAULT_RETRYABLE_STATUS_CODES]
+            },
             roundRobin: false, // false=fallback mode, true=round robin rotation
             ...config
         }
@@ -417,7 +507,6 @@ class ModelMix {
     }
     maverick({ options = {}, config = {}, mix = {} } = {}) {
         mix = { ...this.mix, ...mix };
-        if (mix.groq) this.attach('meta-llama/llama-4-maverick-17b-128e-instruct', new MixGroq({ options, config }));
         if (mix.together) this.attach('meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8', new MixTogether({ options, config }));
         if (mix.lambda) this.attach('llama-4-maverick-17b-128e-instruct-fp8', new MixLambda({ options, config }));
         return this;
@@ -634,8 +723,8 @@ class ModelMix {
 
                     switch (content.source.type) {
                         case 'url':
-                            const response = await axios.get(content.source.data, { responseType: 'arraybuffer' });
-                            buffer = Buffer.from(response.data);
+                            const response = await fetchBinaryResponse(content.source.data);
+                            buffer = response.data;
                             mimeType = response.headers['content-type'];
                             break;
 
@@ -869,8 +958,15 @@ class ModelMix {
                 throw new Error("No user messages have been added. Use addText(prompt), addTextFromFile(filePath), addImage(filePath), or addImageFromUrl(url) to add a prompt.");
             }
 
-            // Merge config to get final roundRobin value
-            const finalConfig = { ...this.config, ...config };
+            // Merge config to get final roundRobin value and retry settings
+            const finalConfig = {
+                ...this.config,
+                ...config,
+                retry: {
+                    ...(this.config.retry || {}),
+                    ...(config.retry || {})
+                }
+            };
 
             // Try all models in order (first is primary, rest are fallbacks)
             const modelsToTry = this.models.map((model, index) => ({ model, index }));
@@ -900,9 +996,14 @@ class ModelMix {
                 };
 
                 const currentConfig = {
-                    ...this.config,
+                    ...finalConfig,
                     ...providerInstance.config,
                     ...config,
+                    retry: {
+                        ...(finalConfig.retry || {}),
+                        ...(providerInstance.config?.retry || {}),
+                        ...(config.retry || {})
+                    }
                 };
 
                 if (currentConfig.debug >= 1) {
@@ -927,8 +1028,46 @@ class ModelMix {
                         providerInstance.streamCallback = this.streamCallback;
                     }
 
-                    const startTime = Date.now();
-                    const result = await providerInstance.create({ options: currentOptions, config: currentConfig });
+                    const retryConfig = currentConfig.retry || {};
+                    const retries = retryConfig.enabled ? Math.max(0, retryConfig.retries || 0) : 0;
+                    const baseDelayMs = Math.max(0, retryConfig.baseDelayMs || 0);
+                    const maxDelayMs = Math.max(baseDelayMs, retryConfig.maxDelayMs || baseDelayMs);
+                    const retryableStatusCodes = new Set(
+                        Array.isArray(retryConfig.retryableStatusCodes) && retryConfig.retryableStatusCodes.length > 0
+                            ? retryConfig.retryableStatusCodes
+                            : DEFAULT_RETRYABLE_STATUS_CODES
+                    );
+
+                    let attempt = 0;
+                    let result;
+                    let startTime = 0;
+
+                    while (true) {
+                        try {
+                            startTime = Date.now();
+                            result = await providerInstance.create({ options: currentOptions, config: currentConfig });
+                            break;
+                        } catch (attemptError) {
+                            const statusCode = getErrorStatusCode(attemptError);
+                            const isRetryable = retryableStatusCodes.has(statusCode);
+                            const canRetry = attempt < retries && isRetryable;
+
+                            if (!canRetry) {
+                                throw attemptError;
+                            }
+
+                            if (currentConfig.debug >= 1) {
+                                const nextAttempt = attempt + 2;
+                                const totalAttempts = retries + 1;
+                                console.log(`↺ Retrying [${currentModelKey}] due to status ${statusCode} (${nextAttempt}/${totalAttempts})`);
+                            }
+
+                            const delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+                            await sleep(delay);
+                            attempt += 1;
+                        }
+                    }
+
                     const elapsedMs = Date.now() - startTime;
 
                     if (result.tokens) {
@@ -1269,13 +1408,16 @@ class MixCustom {
             }
 
             if (options.stream) {
-                return this.processStream(await axios.post(this.config.url, options, {
+                return this.processStream(await fetchStreamResponse(this.config.url, {
+                    method: 'POST',
                     headers: this.headers,
-                    responseType: 'stream'
+                    body: JSON.stringify(options)
                 }));
             } else {
-                return this.processResponse(await axios.post(this.config.url, options, {
-                    headers: this.headers
+                return this.processResponse(await fetchJsonResponse(this.config.url, {
+                    method: 'POST',
+                    headers: this.headers,
+                    body: JSON.stringify(options)
                 }));
             }
         } catch (error) {
@@ -1288,10 +1430,12 @@ class MixCustom {
         let statusCode = null;
         let errorDetails = null;
 
-        if (error.isAxiosError) {
-            statusCode = error.response ? error.response.status : null;
-            errorMessage = `Request to ${this.config.url} failed with status code ${statusCode}`;
-            errorDetails = error.response ? error.response.data : null;
+        if (error?.isHttpError || error?.response || typeof error?.statusCode === 'number') {
+            statusCode = error.statusCode ?? error.response?.status ?? null;
+            errorMessage = error.message || `Request to ${this.config.url} failed with status code ${statusCode}`;
+            errorDetails = error.details ?? error.response?.data ?? null;
+        } else if (error?.message) {
+            errorMessage = error.message;
         }
 
         const formattedError = {
@@ -1583,8 +1727,10 @@ class MixOpenAIResponses extends MixOpenAI {
 
         const responsesUrl = this.config.url.replace('/chat/completions', '/responses');
         const request = MixOpenAIResponses.buildResponsesRequest(options, config);
-        const response = await axios.post(responsesUrl, request, {
-            headers: this.headers
+        const response = await fetchJsonResponse(responsesUrl, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(request)
         });
 
         return MixOpenAIResponses.processResponsesResponse(response);
@@ -2615,8 +2761,10 @@ class MixGoogle extends MixCustom {
             if (options.stream) {
                 throw new Error('Stream is not supported for Gemini');
             } else {
-                return this.processResponse(await axios.post(fullUrl, payload, {
-                    headers: this.headers
+                return this.processResponse(await fetchJsonResponse(fullUrl, {
+                    method: 'POST',
+                    headers: this.headers,
+                    body: JSON.stringify(payload)
                 }));
             }
         } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.4.32",
+  "version": "4.5.0",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "repository": {
@@ -48,7 +48,6 @@
   "homepage": "https://github.com/clasen/ModelMix#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "axios": "^1.13.5",
     "bottleneck": "^2.19.5",
     "file-type": "^21.3.3",
     "form-data": "^4.0.4",

package/test/fallback.test.js

@@ -263,6 +263,105 @@ describe('Provider Fallback Chain Tests', () => {
         });
     });
 
+    describe('Retry Opt-In Before Fallback', () => {
+        it('should keep immediate fallback when retry is disabled', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, retry: { enabled: false } }
+            });
+
+            model.gpt5mini().sonnet46().addText('Hello');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(503, { error: 'Service unavailable' });
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages')
+                .reply(200, {
+                    content: [{
+                        type: 'text',
+                        text: 'Fallback without retry'
+                    }]
+                });
+
+            const response = await model.message();
+            expect(response).to.include('Fallback without retry');
+        });
+
+        it('should retry same provider on retryable errors when enabled', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, retry: { enabled: true, retries: 2, baseDelayMs: 0, maxDelayMs: 0 } }
+            });
+
+            model.gpt5mini().addText('Hello');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(503, { error: 'Temporary outage' })
+                .post('/v1/chat/completions')
+                .reply(200, {
+                    choices: [{
+                        message: {
+                            role: 'assistant',
+                            content: 'Recovered after retry'
+                        }
+                    }]
+                });
+
+            const response = await model.message();
+            expect(response).to.include('Recovered after retry');
+        });
+
+        it('should skip retry and fallback immediately on non-retryable errors', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, retry: { enabled: true, retries: 2, baseDelayMs: 0, maxDelayMs: 0 } }
+            });
+
+            model.gpt5mini().sonnet46().addText('Hello');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .reply(401, { error: 'Unauthorized' });
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages')
+                .reply(200, {
+                    content: [{
+                        type: 'text',
+                        text: 'Immediate fallback from non-retryable error'
+                    }]
+                });
+
+            const response = await model.message();
+            expect(response).to.include('Immediate fallback from non-retryable error');
+        });
+
+        it('should fallback after retry attempts are exhausted', async () => {
+            const model = ModelMix.new({
+                config: { debug: false, retry: { enabled: true, retries: 1, baseDelayMs: 0, maxDelayMs: 0 } }
+            });
+
+            model.gpt5mini().sonnet46().addText('Hello');
+
+            nock('https://api.openai.com')
+                .post('/v1/chat/completions')
+                .times(2)
+                .reply(503, { error: 'Still unavailable' });
+
+            nock('https://api.anthropic.com')
+                .post('/v1/messages')
+                .reply(200, {
+                    content: [{
+                        type: 'text',
+                        text: 'Fallback after exhausted retries'
+                    }]
+                });
+
+            const response = await model.message();
+            expect(response).to.include('Fallback after exhausted retries');
+        });
+    });
+
     describe('Fallback Configuration', () => {
         it('should respect custom provider configurations in fallback', async () => {
             const model = ModelMix.new({

package/test/live.mcp.js

@@ -9,6 +9,35 @@ const setup = {
     config: { debug: false, max_history: 3 }
 };
 
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504, 529]);
+
+function getStatusCode(error) {
+    return error?.statusCode ?? error?.response?.status ?? error?.response?.statusCode ?? null;
+}
+
+function isRetryableError(error) {
+    return RETRYABLE_STATUS_CODES.has(getStatusCode(error));
+}
+
+async function withRetry(task, { retries = 2, baseDelayMs = 1000 } = {}) {
+    let attempt = 0;
+    let lastError = null;
+    while (attempt <= retries) {
+        try {
+            return await task();
+        } catch (error) {
+            lastError = error;
+            if (attempt === retries || !isRetryableError(error)) {
+                throw error;
+            }
+            const backoffMs = baseDelayMs * Math.pow(2, attempt);
+            await new Promise(resolve => setTimeout(resolve, backoffMs));
+            attempt += 1;
+        }
+    }
+    throw lastError;
+}
+
 describe('Live MCP Integration Tests', function () {
     // Increase timeout for real API calls
     this.timeout(60000);
@@ -96,7 +125,7 @@ describe('Live MCP Integration Tests', function () {
             model.addText('What time is it right now?');
 
             try {
-                const response = await model.message();
+                const response = await withRetry(() => model.message(), { retries: 2, baseDelayMs: 1500 });
                 console.log(`Claude Sonnet 4 with MCP tools: ${response}`);
 
                 expect(response).to.be.a('string');

package/test/live.test.js

@@ -1,8 +1,6 @@
 const { expect } = require('chai');
 const { ModelMix, MixOpenAI, MixAnthropic, MixGoogle } = require('../index.js');
 const nock = require('nock');
-const path = require('path');
-const fixturesPath = path.join(__dirname, 'fixtures');
 
 const blueSquareBase64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyhpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDkuMS1jMDAzIDc5Ljk2OTBhODdmYywgMjAyNS8wMy8wNi0yMDo1MDoxNiAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIDI2LjkgKE1hY2ludG9zaCkiIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6REM2QzQ3NEQ2Q0I5MTFGMDlBRTVGQzcwQjMyMkY4MDciIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6REM2QzQ3NEU2Q0I5MTFGMDlBRTVGQzcwQjMyMkY4MDciPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDpEQzZDNDc0QjZDQjkxMUYwOUFFNUZDNzBCMzIyRjgwNyIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDpEQzZDNDc0QzZDQjkxMUYwOUFFNUZDNzBCMzIyRjgwNyIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PvArxh0AAAAGUExURQAA/wAAAHtivz4AAAAjSURBVHja7MGBAAAAAMOg+VNf4QBVAQAAAAAAAAAAAI8JMAAndAABi7SX2gAAAABJRU5ErkJggg==';
 
@@ -234,9 +232,9 @@ describe('Live Integration Tests', function () {
 
     describe('Image Processing with JSON Output', function () {
 
-        it('should process images and return JSON with Maverick', async function () {
-            const model = ModelMix.new(setup).maverick();
-            model.addImage(path.join(fixturesPath, 'img.png'))
+        it('should process images and return JSON with Scout', async function () {
+            const model = ModelMix.new(setup).scout();
+            model.addImageFromUrl(blueSquareBase64)
                 .addText('Analyze this image and provide details in JSON format.');
 
             const result = await model.json({
@@ -251,7 +249,7 @@ describe('Live Integration Tests', function () {
             expect(result).to.have.property('color');
             expect(result).to.have.property('shape');
             expect(result).to.have.property('description');
-            expect(result.color.toLowerCase()).to.include('blue');
+            expect(result.color).to.be.a('string').and.not.empty;
         });
 
         it('should process images and return JSON with Grok 4', async function () {