modelmix 4.6.6 → 4.6.8

package/README.md

@@ -90,7 +90,6 @@ console.log(ETH.price);
 ModelMix.new()
   .gptOss()
   .kimiK25think()
-  .deepseekR1()
   .hermes3()
   .addText('What is the capital of France?');
 ```
@@ -102,6 +101,32 @@ This pattern allows you to:
 - Track token usage across all providers
 - Keep your code clean and maintainable
 
+## 🎛️ Unified Effort Scale
+
+Control reasoning depth with one ModelMix policy value (`-1` adaptive, or `0`–`100`). It lives **outside** native `options` and is mapped to each provider’s effort API at request time.
+
+```javascript
+// In config (ModelMix.new or per-model shorthand)
+ModelMix.new({ config: { effort: 50 } }).sonnet46().addText('...').message();
+ModelMix.new().deepseekV4Flash({ config: { effort: 100 } }).addText('...').message();
+
+// Fluent
+ModelMix.new().effort(-1).minimaxM3().addText('...').message();
+```
+
+**Native wins:** if you already set a provider-native field (`reasoning_effort`, `output_config.effort`, `thinkingConfig`, etc.), unified `effort` is ignored for that request.
+
+| Scale | OpenAI | Anthropic | Gemini 3+ | DeepSeek V4 | MiniMax M3 |
+|------|--------|-----------|-----------|-------------|------------|
+| 0–19 / 0–24* | `none` | `low` | `minimal` | thinking `disabled` | `thinking.disabled` |
+| 20–39 / 25–49* | `low` | `medium` | `low` | `low` + thinking on | `thinking.adaptive` |
+| 40–59 / 50–74* | `medium` | `high` | `medium` | `high` + thinking on | `thinking.adaptive` |
+| 60–79 / 75–100* | `high` | `xhigh` | `high` | `high` + thinking on | `thinking.adaptive` |
+| 80–100 | `xhigh` | `max` | — | `max` + thinking on | `thinking.adaptive` |
+| `-1` | no-op (no adaptive API) | `thinking.type = adaptive` | `thinkingBudget: -1` | no-op (no adaptive API) | `thinking.type = adaptive` |
+
+\* Gemini bands use 0–24 / 25–49 / 50–74 / 75–100. Gemini 2.5 maps 0–100 to `thinkingBudget` (0→0, 100→model max). `-1` sets the provider’s adaptive/dynamic control when it exists; otherwise it is a no-op. Levels are clamped to what each model supports. Providers without effort control are a no-op.
+
 ## 🔧 Model Context Protocol (MCP) Integration
 
 ModelMix makes it incredibly easy to enhance your AI models with powerful capabilities through the Model Context Protocol. With just a few lines of code, you can add features like web search, code execution, or any custom functionality to your models.
@@ -170,6 +195,7 @@ Here's a comprehensive list of available methods:
 | `grok420[think]()`  | Grok       | grok-4.20-0309               | [\$1.25 / \$2.50][6]       |
 | `grok41[think]()`   | Grok       | grok-4-1-fast                | [\$0.20 / \$0.50][6]       |
 | `qwen36plus()`      | Fireworks/Together | qwen3p6-plus / Qwen3.6-Plus | [\$0.50 / \$3.00][10] |
+| `deepseekV4Flash()` | Fireworks  | models/deepseek-v4-flash     | [\$0.14 / \$0.28][10]      |
 | `deepseekV4Pro()`   | Fireworks  | models/deepseek-v4-pro       | [\$1.74 / \$3.48][10]      |
 | `GLM52()`           | Together   | zai-org/GLM-5.2              | [\$1.40 / \$4.40][7]       |
 | `GLM51()`           | Fireworks  | models/glm-5p1               | [\$1.05 / \$3.50][10]      |
@@ -195,7 +221,7 @@ Here's a comprehensive list of available methods:
 [11]: https://platform.kimi.ai/docs/guide/kimi-k3-pricing "Kimi K3 Pricing"
 
 Each method accepts optional `options`, `config`, and (for multi-provider methods) `mix` parameters to customize behavior.  
-For NVIDIA on DeepSeek V4 Pro, use `deepseekV4Pro({ mix: { nvidia: true } })`.
+For NVIDIA on DeepSeek V4 Flash/Pro, use `deepseekV4Flash({ mix: { nvidia: true } })` or `deepseekV4Pro({ mix: { nvidia: true } })`.
 For Together on Qwen 3.6 Plus, use `qwen36plus({ mix: { fireworks: false, together: true } })`.
 For OpenRouter instead of Moonshot's native API, use `kimiK3({ mix: { moonshot: false, openrouter: true } })`.
 
@@ -617,6 +643,7 @@ new ModelMix(args = { options: {}, config: {} })
   - **config**: This object contains configuration settings that control the behavior of the `ModelMix` instance. These settings can also be overridden for specific model instances. Examples of configuration settings include:
     - `system`: Sets the default system message for the model, e.g., "You are an assistant."
     - `max_history`: Limits the number of historical messages to retain, e.g., 1.
+    - `effort`: Unified reasoning effort (`-1` adaptive, or `0`–`100`). Not a native provider field — use `config.effort` or `.effort(n)`.
     - `roundRobin`: When `true`, rotates through attached models on each request for load balancing. When `false` (default), uses fallback mode where models are tried sequentially only if previous ones fail.
     - `bottleneck`: Configures the rate limiting behavior using Bottleneck. For example:
       - `maxConcurrent`: Maximum number of concurrent requests
@@ -637,6 +664,7 @@ new ModelMix(args = { options: {}, config: {} })
 - `attach(modelKey, modelInstance)`: Attaches a model instance to the `ModelMix`.
 - `new()`: `static` Creates a new `ModelMix`.
 - `new()`: Creates a new `ModelMix` using instance setup.
+- `effort(n)`: Sets unified effort (`-1` or `0`–`100`) on `config.effort`.
 
 - `setSystem(text)`: Sets the system prompt.
 - `setSystemFromFile(filePath)`: Sets the system prompt from a file.

package/demo/fireworks.js

@@ -1,14 +1,12 @@
 import { ModelMix } from '../index.js';
-try { process.loadEnvFile(); } catch {}
+try { process.loadEnvFile(); } catch { }
 
 async function main() {
     try {
         const ai = ModelMix.new();
 
-        const response = await ai
-            .GLM46()
-            .deepseekV32()
-            .GLM47()
+        const response = await ai.effort(50)
+            .deepseekV4Flash()
             .addText('What is the capital of France?')
             .message();
 
@@ -20,4 +18,3 @@ async function main() {
 }
 
 main();
-

package/demo/free.js

@@ -4,7 +4,6 @@ try { process.loadEnvFile(); } catch {}
 const ai = ModelMix.new({ config: { debug: 2 } })
     .gptOss()
     .kimiK25think()
-    .deepseekR1()
     .hermes3()
     .addText('What is the capital of France?');
 

package/demo/groq.js

@@ -13,7 +13,7 @@ const mmix = new ModelMix({
     }
 });
 
-mmix.attach('deepseek-r1-distill-llama-70b', new MixGroq({
+mmix.attach('openai/gpt-oss-120b', new MixGroq({
     config: {
         apiKey: env.GROQ_API_KEY,
     }

package/demo/nvidia.js

@@ -2,7 +2,7 @@ import { ModelMix } from '../index.js';
 try { process.loadEnvFile(); } catch { }
 
 const model = ModelMix.new()
-    .deepseekV4Flash()
+    .deepseekV4Flash({ mix: { nvidia: true } })
     .addText("Create exactly 5 characters for a narrative game.")
 
 const jsonResult = await model.json([], [{

package/demo/opus5.js

@@ -0,0 +1,23 @@
+import { ModelMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
+
+
+const mmix = new ModelMix({
+    config: {
+        debug: 3,
+    }
+});
+
+console.log("\n" + '--------| opus5() |--------');
+
+const opus = mmix.opus5();
+opus.addText("Explain quantum entanglement in simple terms.");
+const response = await opus.message();
+console.log(response);
+
+console.log("\n" + '--------| opus5think() |--------');
+
+const opusThink = mmix.new().opus5think();
+opusThink.addText("A bat and a ball cost $1.10 in total. The bat costs $1.00 more than the ball. How much does the ball cost?");
+const thinkResponse = await opusThink.raw();
+console.log(thinkResponse);

package/demo/together.js

@@ -4,7 +4,7 @@ try { process.loadEnvFile(); } catch {}
 const setup = { config: { system: "You are ALF from Melmac." } };
 
 let r = ModelMix.new()
-    .attach('deepseek-ai/DeepSeek-R1', new MixTogether(setup))
+    .attach('deepseek-ai/DeepSeek-V4-Flash', new MixTogether(setup))
     .addText('hi there')
     .addText('do you like cats?')
     .message();

package/effort.js

@@ -0,0 +1,370 @@
+/**
+ * Unified effort scale for ModelMix.
+ *
+ * Policy value: integer -1 (adaptive) or 0..100.
+ * Stored in config.effort (never in native options).
+ * Mapped to provider-native fields only when native effort controls are absent.
+ */
+
+const OPENAI_LEVELS = ['none', 'low', 'medium', 'high', 'xhigh'];
+const ANTHROPIC_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const GEMINI_LEVELS = ['minimal', 'low', 'medium', 'high'];
+
+const OPENAI_BANDS = [
+    [0, 19, 'none'],
+    [20, 39, 'low'],
+    [40, 59, 'medium'],
+    [60, 79, 'high'],
+    [80, 100, 'xhigh'],
+];
+
+const ANTHROPIC_BANDS = [
+    [0, 19, 'low'],
+    [20, 39, 'medium'],
+    [40, 59, 'high'],
+    [60, 79, 'xhigh'],
+    [80, 100, 'max'],
+];
+
+const GEMINI_BANDS = [
+    [0, 24, 'minimal'],
+    [25, 49, 'low'],
+    [50, 74, 'medium'],
+    [75, 100, 'high'],
+];
+
+/** Exact model → supported OpenAI reasoning_effort values */
+const OPENAI_MODEL_LEVELS = {
+    'gpt-5': ['minimal', 'low', 'medium', 'high'],
+    'gpt-5-mini': ['minimal', 'low', 'medium', 'high'],
+    'gpt-5-nano': ['minimal', 'low', 'medium', 'high'],
+    'gpt-5.3-codex': ['low', 'medium', 'high', 'xhigh'],
+    'gpt-oss-120b': ['low', 'medium', 'high'],
+    'openai/gpt-oss-120b': ['low', 'medium', 'high'],
+    'openai/gpt-oss-120b:free': ['low', 'medium', 'high'],
+};
+
+/**
+ * DeepSeek V4 (OpenAI-compatible): reasoning_effort low|high|max + thinking toggle.
+ * Official mapping: low/high/max; xhigh remaps per model (flash→high, pro→max).
+ * @see https://api-docs.deepseek.com/guides/thinking_mode
+ */
+const DEEPSEEK_LEVELS = ['none', 'low', 'high', 'max'];
+const DEEPSEEK_BANDS = [
+    [0, 19, 'none'],
+    [20, 39, 'low'],
+    [40, 79, 'high'],
+    [80, 100, 'max'],
+];
+
+/**
+ * MiniMax M3 (OpenAI-compatible): thinking.type disabled | adaptive.
+ * @see https://platform.minimax.io/docs/api-reference/text-openai-api
+ */
+const MINIMAX_LEVELS = ['disabled', 'adaptive'];
+const MINIMAX_BANDS = [
+    [0, 19, 'disabled'],
+    [20, 100, 'adaptive'],
+];
+
+/** Exact model → supported Gemini thinkingLevel values */
+const GEMINI_MODEL_LEVELS = {
+    'gemini-3-pro-preview': ['low', 'high'],
+    'gemini-3.1-pro-preview': ['low', 'medium', 'high'],
+    'gemini-2.5-pro': ['low', 'medium', 'high'],
+    'gemini-2.5-flash': ['low', 'medium', 'high'],
+    'gemini-2.5-flash-lite': ['low', 'medium', 'high'],
+};
+
+const GEMINI_25_BUDGET_MAX = {
+    'gemini-2.5-pro': 32768,
+    'gemini-2.5-flash': 24576,
+    'gemini-2.5-flash-lite': 24576,
+};
+
+const PROVIDER_FAMILY_BY_CLASS = {
+    MixAnthropic: 'anthropic',
+    MixGoogle: 'google',
+    MixOpenAI: 'openai',
+    MixOpenAIResponses: 'openai',
+    MixOpenAIWebSocket: 'openai',
+    MixOpenRouter: 'openai',
+    MixKimi: 'openai',
+    MixMiniMax: 'openai',
+    MixMiMo: 'openai',
+    MixGrok: 'openai',
+    MixGroq: 'openai',
+    MixTogether: 'openai',
+    MixCerebras: 'openai',
+    MixFireworks: 'openai',
+    MixNVIDIA: 'openai',
+    MixPerplexity: null,
+    MixOllama: null,
+    MixLMStudio: null,
+    MixLambda: null,
+    MixCustom: null,
+};
+
+function normalizeEffort(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new Error(`Invalid effort: expected integer -1 or 0..100, got ${JSON.stringify(value)}`);
+    }
+    if (value === -1) return -1;
+    if (value < 0 || value > 100) {
+        throw new Error(`Invalid effort: expected integer -1 or 0..100, got ${value}`);
+    }
+    return value;
+}
+
+function levelFromBands(effort, bands) {
+    for (const [lo, hi, level] of bands) {
+        if (effort >= lo && effort <= hi) return level;
+    }
+    return bands[bands.length - 1][2];
+}
+
+function pickNearestLevel(desired, ladder, supported) {
+    if (supported.includes(desired)) return desired;
+    const desiredIdx = ladder.indexOf(desired);
+    if (desiredIdx === -1) return supported[Math.floor(supported.length / 2)];
+
+    let best = supported[0];
+    let bestDist = Infinity;
+    for (const level of supported) {
+        const idx = ladder.indexOf(level);
+        if (idx === -1) continue;
+        const dist = Math.abs(idx - desiredIdx);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = level;
+        }
+    }
+    return best;
+}
+
+function supportedOpenAILevels(modelKey) {
+    if (modelKey && OPENAI_MODEL_LEVELS[modelKey]) {
+        return OPENAI_MODEL_LEVELS[modelKey];
+    }
+    return OPENAI_LEVELS;
+}
+
+function supportedGeminiLevels(modelKey) {
+    if (modelKey && GEMINI_MODEL_LEVELS[modelKey]) {
+        return GEMINI_MODEL_LEVELS[modelKey];
+    }
+    return GEMINI_LEVELS;
+}
+
+function isGemini25(modelKey) {
+    return typeof modelKey === 'string' && modelKey.includes('2.5');
+}
+
+function isDeepSeekV4(modelKey) {
+    if (typeof modelKey !== 'string') return false;
+    const key = modelKey.toLowerCase();
+    return key.includes('deepseek-v4') || key.includes('deepseek_v4');
+}
+
+function isMiniMax(modelKey) {
+    return typeof modelKey === 'string' && modelKey.toLowerCase().includes('minimax');
+}
+
+function mapDeepSeekEffort(normalized) {
+    // DeepSeek V4 has no adaptive mode (only enabled/disabled + low|high|max)
+    if (normalized === -1) return null;
+    const level = levelFromBands(normalized, DEEPSEEK_BANDS);
+    if (level === 'none') {
+        return { thinking: { type: 'disabled' } };
+    }
+    return {
+        reasoning_effort: level,
+        thinking: { type: 'enabled' }
+    };
+}
+
+function mapMiniMaxEffort(normalized) {
+    if (normalized === -1) {
+        return { thinking: { type: 'adaptive' } };
+    }
+    const level = levelFromBands(normalized, MINIMAX_BANDS);
+    return { thinking: { type: level } };
+}
+
+/**
+ * Explicit adaptive mapping when the provider/model exposes it.
+ * Returns null when adaptive is not a settable native control.
+ */
+function mapAdaptiveEffort(providerFamily, modelKey) {
+    if (providerFamily === 'anthropic') {
+        return { thinking: { type: 'adaptive' } };
+    }
+    if (providerFamily === 'google') {
+        // Gemini dynamic thinking: thinkingBudget -1 (2.5 official; accepted on 3.x as dynamic)
+        return { thinkingConfig: { thinkingBudget: -1 } };
+    }
+    if (providerFamily === 'openai' && isMiniMax(modelKey)) {
+        return { thinking: { type: 'adaptive' } };
+    }
+    // OpenAI / DeepSeek: no adaptive enum — cannot set adaptive
+    return null;
+}
+
+function gemini25BudgetMax(modelKey) {
+    if (modelKey && GEMINI_25_BUDGET_MAX[modelKey] != null) {
+        return GEMINI_25_BUDGET_MAX[modelKey];
+    }
+    return 24576;
+}
+
+/**
+ * @returns {'openai'|'anthropic'|'google'|null}
+ */
+function resolveProviderFamily(providerInstance) {
+    if (!providerInstance || !providerInstance.constructor) return null;
+    let proto = providerInstance;
+    while (proto) {
+        const name = proto.constructor?.name;
+        if (name && Object.prototype.hasOwnProperty.call(PROVIDER_FAMILY_BY_CLASS, name)) {
+            return PROVIDER_FAMILY_BY_CLASS[name];
+        }
+        proto = Object.getPrototypeOf(proto);
+        if (!proto || proto === Object.prototype) break;
+    }
+    return null;
+}
+
+function hasNativeEffort(family, options = {}, modelKey) {
+    if (family === 'openai') {
+        if (options.reasoning_effort != null && options.reasoning_effort !== '') return true;
+        // DeepSeek / MiniMax use thinking.type as the on/off (or adaptive) control
+        if ((isDeepSeekV4(modelKey) || isMiniMax(modelKey)) && options.thinking != null) return true;
+        return false;
+    }
+    if (family === 'anthropic') {
+        return options.output_config?.effort != null && options.output_config.effort !== '';
+    }
+    if (family === 'google') {
+        if (options.thinkingConfig != null) return true;
+        if (options.thinkingLevel != null) return true;
+        if (options.thinkingBudget != null) return true;
+        return false;
+    }
+    return false;
+}
+
+/**
+ * Map unified effort to a provider-native patch object.
+ * Returns null when there is nothing to set (unsupported family, or -1 on a
+ * model with no adaptive control).
+ *
+ * @returns {object|null}
+ */
+function mapEffort(providerFamily, effort, modelKey) {
+    const normalized = normalizeEffort(effort);
+
+    if (!providerFamily) return null;
+
+    if (normalized === -1) {
+        return mapAdaptiveEffort(providerFamily, modelKey);
+    }
+
+    if (providerFamily === 'openai') {
+        if (isDeepSeekV4(modelKey)) {
+            return mapDeepSeekEffort(normalized);
+        }
+        if (isMiniMax(modelKey)) {
+            return mapMiniMaxEffort(normalized);
+        }
+        const desired = levelFromBands(normalized, OPENAI_BANDS);
+        const level = pickNearestLevel(desired, OPENAI_LEVELS, supportedOpenAILevels(modelKey));
+        return { reasoning_effort: level };
+    }
+
+    if (providerFamily === 'anthropic') {
+        const desired = levelFromBands(normalized, ANTHROPIC_BANDS);
+        const level = pickNearestLevel(desired, ANTHROPIC_LEVELS, ANTHROPIC_LEVELS);
+        return { output_config: { effort: level } };
+    }
+
+    if (providerFamily === 'google') {
+        if (isGemini25(modelKey)) {
+            const max = gemini25BudgetMax(modelKey);
+            const budget = Math.round((normalized / 100) * max);
+            return { thinkingConfig: { thinkingBudget: budget } };
+        }
+        const desired = levelFromBands(normalized, GEMINI_BANDS);
+        const level = pickNearestLevel(desired, GEMINI_LEVELS, supportedGeminiLevels(modelKey));
+        return { thinkingConfig: { thinkingLevel: level } };
+    }
+
+    return null;
+}
+
+/**
+ * Apply config.effort onto options when native controls are absent.
+ * Mutates and returns options. Never writes ModelMix `effort` into the HTTP body.
+ */
+function applyUnifiedEffort(options, config, providerFamily, modelKey) {
+    if (!config || config.effort === undefined || config.effort === null) {
+        return options;
+    }
+    if (!providerFamily) return options;
+    if (hasNativeEffort(providerFamily, options, modelKey)) return options;
+
+    const patch = mapEffort(providerFamily, config.effort, modelKey);
+    if (!patch) return options;
+
+    if (patch.reasoning_effort !== undefined) {
+        options.reasoning_effort = patch.reasoning_effort;
+    }
+    if (patch.output_config) {
+        options.output_config = {
+            ...(options.output_config || {}),
+            ...patch.output_config
+        };
+    }
+    if (patch.thinking) {
+        options.thinking = {
+            ...(options.thinking || {}),
+            ...patch.thinking
+        };
+        // Adaptive thinking rejects budget_tokens; drop it if we switched mode.
+        if (patch.thinking.type === 'adaptive') {
+            delete options.thinking.budget_tokens;
+        }
+        // DeepSeek non-thinking: do not send reasoning_effort
+        if (patch.thinking.type === 'disabled') {
+            delete options.reasoning_effort;
+        }
+    }
+    if (patch.thinkingConfig) {
+        options.thinkingConfig = {
+            ...(options.thinkingConfig || {}),
+            ...patch.thinkingConfig
+        };
+    }
+
+    return options;
+}
+
+module.exports = {
+    normalizeEffort,
+    mapEffort,
+    mapAdaptiveEffort,
+    applyUnifiedEffort,
+    hasNativeEffort,
+    resolveProviderFamily,
+    isDeepSeekV4,
+    isMiniMax,
+    levelFromBands,
+    pickNearestLevel,
+    OPENAI_BANDS,
+    ANTHROPIC_BANDS,
+    GEMINI_BANDS,
+    DEEPSEEK_BANDS,
+    OPENAI_LEVELS,
+    ANTHROPIC_LEVELS,
+    GEMINI_LEVELS,
+    DEEPSEEK_LEVELS,
+};