modelmix 5.0.6 → 5.1.2

package/lib/template-engine.js

@@ -0,0 +1,168 @@
+const { isPlainObject } = require('./object-utils');
+
+function validateTemplateData(value) {
+    if (!isPlainObject(value)) {
+        throw new TypeError('Template data must be a plain non-null object.');
+    }
+    if (Object.prototype.hasOwnProperty.call(value, '$mix')) {
+        throw new TypeError('Template data key "$mix" is reserved.');
+    }
+}
+
+function validateTemplateDataKey(key) {
+    if (typeof key !== 'string' || key.length === 0) {
+        throw new TypeError('Template data key must be a non-empty string.');
+    }
+    if (key === '$mix') {
+        throw new TypeError('Template data key "$mix" is reserved.');
+    }
+}
+
+function templateLocation({ filename, label }, lineNumber) {
+    return `${filename || label} at line ${lineNumber}`;
+}
+
+function preprocessChoiceDirectives(source, { filename = null, label = 'template' } = {}) {
+    const parts = source.split(/(\r\n|\n|\r)/);
+    const blocks = [];
+
+    for (let index = 0; index < parts.length; index += 2) {
+        const line = parts[index];
+        const trimmed = line.trim();
+        const lineNumber = (index / 2) + 1;
+        const location = templateLocation({ filename, label }, lineNumber);
+        const newline = parts[index + 1] || '';
+
+        if (/^<%\s*choice\s*%>$/.test(trimmed)) {
+            const parent = blocks[blocks.length - 1];
+            if (parent && parent.optionCount === 0) {
+                throw new Error(`A nested choice must be inside an option (${location}).`);
+            }
+            blocks.push({ lineNumber, optionCount: 0, weighted: null });
+            parts[index] = '<% $mix.choice(option => { -%>';
+            continue;
+        }
+
+        const optionMatch = trimmed.match(/^<%\s*option(?:\s+(.+?))?\s*%>$/);
+        if (optionMatch) {
+            const block = blocks[blocks.length - 1];
+            if (!block) {
+                throw new Error(`Option directive must be inside a choice (${location}).`);
+            }
+
+            const weightText = optionMatch[1];
+            const weighted = weightText !== undefined;
+            if (block.weighted !== null && block.weighted !== weighted) {
+                throw new Error(`Choice options must either all have weights or all omit them (${location}).`);
+            }
+
+            let argument = '';
+            if (weighted) {
+                const weight = Number(weightText);
+                if (!Number.isFinite(weight) || weight <= 0) {
+                    throw new Error(`Choice weight must be a positive finite number (${location}).`);
+                }
+                argument = `${weight}, `;
+            }
+
+            block.weighted = weighted;
+            parts[index] = `<% ${block.optionCount > 0 ? '}); ' : ''}option(${argument}() => { -%>`;
+            block.optionCount += 1;
+            continue;
+        }
+
+        if (/^<%\s*\/choice\s*%>$/.test(trimmed)) {
+            const block = blocks.pop();
+            if (!block) {
+                throw new Error(`Closing choice directive has no matching opening directive (${location}).`);
+            }
+            if (block.optionCount === 0) {
+                throw new Error(`Choice must contain at least one option (${location}).`);
+            }
+            parts[index] = '<% }); }); -%>';
+            continue;
+        }
+
+        if (/^<%\s*(?:choice|option|\/choice)(?:\s|%>)/.test(trimmed)) {
+            throw new Error(`Invalid choice directive (${location}).`);
+        }
+
+        const block = blocks[blocks.length - 1];
+        if (block && block.optionCount === 0) {
+            if (trimmed) {
+                throw new Error(`Choice content must be inside an option (${location}).`);
+            }
+            parts[index] = '<%# -%>';
+        }
+
+        if (newline) parts[index + 1] = newline;
+    }
+
+    if (blocks.length > 0) {
+        const block = blocks[blocks.length - 1];
+        throw new Error(`Unclosed choice directive (${templateLocation({ filename, label }, block.lineNumber)}).`);
+    }
+
+    return parts.join('');
+}
+
+function createTemplateRenderContext(random = Math.random) {
+    const choice = defineOptions => {
+        if (typeof defineOptions !== 'function') {
+            throw new TypeError('$mix.choice expects an option definition callback.');
+        }
+
+        const options = [];
+        let weighted = null;
+        const option = (weightOrRender, renderOption) => {
+            const hasWeight = renderOption !== undefined;
+            const weight = hasWeight ? weightOrRender : 1;
+            const render = hasWeight ? renderOption : weightOrRender;
+
+            if (weighted !== null && weighted !== hasWeight) {
+                throw new TypeError('$mix.choice options cannot mix weighted and unweighted forms.');
+            }
+            if (!Number.isFinite(weight) || weight <= 0) {
+                throw new TypeError('$mix.choice weights must be positive finite numbers.');
+            }
+            if (typeof render !== 'function') {
+                throw new TypeError('$mix.choice options require a render callback.');
+            }
+
+            weighted = hasWeight;
+            options.push({ weight, render });
+        };
+
+        defineOptions(option);
+        if (options.length === 0) {
+            throw new Error('$mix.choice requires at least one option.');
+        }
+
+        const totalWeight = options.reduce((sum, current) => sum + current.weight, 0);
+        if (!Number.isFinite(totalWeight)) {
+            throw new TypeError('$mix.choice total weight must be finite.');
+        }
+
+        let target = random() * totalWeight;
+        for (const current of options) {
+            target -= current.weight;
+            if (target < 0) return current.render();
+        }
+        return options[options.length - 1].render();
+    };
+
+    return {
+        helpers: Object.freeze({ choice }),
+        renderedTemplateData: new Map(),
+        renderedMessages: new Map(),
+        renderedSystems: new Map()
+    };
+}
+
+module.exports = {
+    validateTemplateData,
+    validateTemplateDataKey,
+    preprocessChoiceDirectives,
+    createTemplateRenderContext
+};
+

package/lib/token-usage.js

@@ -0,0 +1,299 @@
+const GPT56_LONG_CONTEXT_PRICING = Object.freeze({
+    inputThreshold: 272_000,
+    inputMultiplier: 2,
+    outputMultiplier: 1.5
+});
+
+const GROK46_LONG_CONTEXT_PRICING = Object.freeze({
+    inputThreshold: 200_000,
+    inputMultiplier: 2,
+    outputMultiplier: 2,
+    inclusive: true
+});
+
+function usesLongContextRates(pricing, inputTokens) {
+    const longContext = pricing.longContext;
+    if (!longContext) return false;
+    return longContext.inclusive
+        ? inputTokens >= longContext.inputThreshold
+        : inputTokens > longContext.inputThreshold;
+}
+
+const MODEL_PRICING = {
+    // OpenAI
+    'gpt-realtime-mini': { input: 0.60, cachedInput: 0.06, output: 2.40 },
+    'gpt-realtime': { input: 4.00, cachedInput: 0.40, output: 16.00 },
+    'gpt-5.6-sol': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, output: 30.00, longContext: GPT56_LONG_CONTEXT_PRICING },
+    'gpt-5.6-terra': { input: 2.00, cachedInput: 0.20, cacheWrite: 2.50, output: 12.00, longContext: GPT56_LONG_CONTEXT_PRICING },
+    'gpt-5.6-luna': { input: 0.20, cachedInput: 0.02, cacheWrite: 0.25, output: 1.20, longContext: GPT56_LONG_CONTEXT_PRICING },
+    'gpt-5.5-pro': { input: 30.00, output: 180.00 },
+    'gpt-5.5': { input: 5.00, cachedInput: 0.50, output: 30.00 },
+    'gpt-5.4': { input: 2.50, cachedInput: 0.25, output: 15.00 },
+    'gpt-5.4-pro': { input: 30.00, output: 180.00 },
+    'gpt-5.4-mini': { input: 0.75, cachedInput: 0.075, output: 4.50 },
+    'gpt-5.4-nano': { input: 0.20, cachedInput: 0.02, output: 1.25 },
+    'gpt-5.3-codex': { input: 1.75, cachedInput: 0.175, output: 14.00 },
+    'gpt-5.2': { input: 1.75, cachedInput: 0.175, output: 14.00 },
+    'gpt-5.2-chat-latest': { input: 1.75, cachedInput: 0.175, output: 14.00 },
+    'gpt-5.1': { input: 1.25, cachedInput: 0.125, output: 10.00 },
+    'gpt-5': { input: 1.25, cachedInput: 0.125, output: 10.00 },
+    'gpt-5-mini': { input: 0.25, cachedInput: 0.025, output: 2.00 },
+    'gpt-5-nano': { input: 0.05, cachedInput: 0.005, output: 0.40 },
+    'gpt-4.1': { input: 2.00, cachedInput: 0.50, output: 8.00 },
+    'gpt-4.1-mini': { input: 0.40, cachedInput: 0.10, output: 1.60 },
+    'gpt-4.1-nano': { input: 0.10, cachedInput: 0.025, output: 0.40 },
+    // gptOss (Together/Groq/Cerebras/OpenRouter)
+    'openai/gpt-oss-120b': { input: 0.15, output: 0.60 },
+    'gpt-oss-120b': { input: 0.15, output: 0.60 },
+    // Anthropic
+    'claude-fable-5': { input: 10.00, cachedInput: 1.00, cacheWrite: 12.50, cacheWrite1h: 20.00, output: 50.00 },
+    'claude-opus-5': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-sonnet-5': { input: 3.00, cachedInput: 0.30, cacheWrite: 3.75, cacheWrite1h: 6.00, output: 15.00 },
+    'claude-opus-4-8': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-opus-4-7': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-opus-4-6': { input: 5.00, cachedInput: 0.50, cacheWrite: 6.25, cacheWrite1h: 10.00, output: 25.00 },
+    'claude-sonnet-4-6': { input: 3.00, cachedInput: 0.30, cacheWrite: 3.75, cacheWrite1h: 6.00, output: 15.00 },
+    'claude-sonnet-4-5-20250929': { input: 3.00, cachedInput: 0.30, cacheWrite: 3.75, cacheWrite1h: 6.00, output: 15.00 },
+    'claude-haiku-4-5-20251001': { input: 1.00, cachedInput: 0.10, cacheWrite: 1.25, cacheWrite1h: 2.00, output: 5.00 },
+    // Google
+    'gemini-3.1-pro-preview': { input: 2.00, output: 12.00 },
+    'gemini-3-pro-preview': { input: 2.00, output: 12.00 },
+    'gemini-3-flash-preview': { input: 0.50, output: 3.00 },
+    'gemini-3.7-flash': { input: 0.75, cachedInput: 0.075, output: 3.75 },
+    'gemini-3.6-flash': { input: 0.75, cachedInput: 0.075, output: 3.75 },
+    'gemini-3.5-flash': { input: 0.75, output: 4.50 },
+    'gemini-3.5-flash-lite': { input: 0.30, output: 2.50 },
+    'gemini-2.5-pro': { input: 1.25, output: 10.00 },
+    'gemini-2.5-flash': { input: 0.30, output: 2.50 },
+    'gemini-3.1-flash-lite-preview': { input: 0.25, output: 1.50 },
+    // Grok
+    'grok-4.6': { input: 2.00, cachedInput: 0.50, output: 6.00, longContext: GROK46_LONG_CONTEXT_PRICING },
+    'grok-4.5': { input: 2.00, output: 6.00 },
+    'grok-4.3': { input: 1.25, output: 2.50 },
+    'grok-4.20-multi-agent-0309': { input: 1.25, output: 2.50 },
+    'grok-4.20-0309': { input: 1.25, output: 2.50 },
+    'grok-4.20-0309-reasoning': { input: 1.25, output: 2.50 },
+    'grok-4.20-0309-non-reasoning': { input: 1.25, output: 2.50 },
+    // Fireworks
+    'accounts/fireworks/models/deepseek-v4-flash': { input: 0.14, output: 0.28 },
+    'accounts/fireworks/models/deepseek-v4-pro': { input: 1.74, output: 3.48 },
+    'accounts/fireworks/models/deepseek-v4-pro-0813': { input: 1.32, cachedInput: 0.044, output: 3.96 },
+    'deepseek-ai/DeepSeek-V4-Flash': { input: 0.14, output: 0.28 },
+    'deepseek-ai/DeepSeek-V4-Pro': { input: 2.10, output: 4.40 },
+    'deepseek/deepseek-v4-flash': { input: 0.09, output: 0.18 },
+    'accounts/fireworks/models/glm-4p7': { input: 0.55, output: 2.19 },
+    'accounts/fireworks/models/glm-5p1': { input: 1.05, output: 3.50 },
+    'zai-org/GLM-5.2': { input: 1.40, output: 4.40 },
+    'accounts/fireworks/models/kimi-k2p5': { input: 0.50, output: 2.80 },
+    'qwen/qwen3.5-397b-a17b': { input: 0.385, output: 2.45 },
+    'accounts/fireworks/models/qwen3p6-plus': { input: 0.50, output: 3.00 },
+    'Qwen/Qwen3.6-Plus': { input: 0.50, output: 3.00 },
+    'accounts/fireworks/models/qwen3p7-plus': { input: 0.40, output: 1.60 },
+    'qwen/qwen3.7-plus': { input: 0.32, output: 1.28 },
+    'accounts/fireworks/models/qwen3p8-2p4t-a95b': { input: 2.00, cachedInput: 0.25, output: 6.00 },
+    'qwen/qwen3.8-max': { input: 2.00, output: 6.00 },
+    // MiniMax
+    'MiniMax-M2.5': { input: 0.30, output: 1.20 },
+    'MiniMax-M2.7': { input: 0.30, output: 1.20 },
+    'MiniMax-M3': { input: 0.30, output: 1.20 },
+    'minimax/minimax-m2.7': { input: 0.30, output: 1.20 },
+    'minimax/minimax-m3': { input: 0.30, output: 1.20 },
+    'MiniMaxAI/MiniMax-M3': { input: 0.30, output: 1.20 },
+    // Perplexity
+    'sonar': { input: 1.00, output: 1.00 },
+    'sonar-pro': { input: 3.00, output: 15.00 },
+    // Hermes 4 (OpenRouter)
+    'nousresearch/hermes-4-70b': { input: 0.13, output: 0.40 },
+    'nousresearch/hermes-4-405b': { input: 1.00, output: 3.00 },
+    // Hermes 3 (Lambda/OpenRouter)
+    'Hermes-3-Llama-3.1-405B-FP8': { input: 0.80, output: 0.80 },
+    'nousresearch/hermes-3-llama-3.1-405b:free': { input: 0, output: 0 },
+    // Qwen3 (Together/Cerebras)
+    'Qwen/Qwen3-235B-A22B-fp8-tput': { input: 0.20, output: 0.60 },
+    'qwen-3-32b': { input: 0.20, output: 0.60 },
+    // Kimi K2.5 (Together/Fireworks/OpenRouter)
+    'moonshotai/Kimi-K2.5': { input: 0.50, output: 2.80 },
+    'moonshotai/kimi-k2.5': { input: 0.50, output: 2.80 },
+    // Kimi K3
+    'kimi-k3': { input: 3.00, output: 15.00 },
+    'moonshotai/kimi-k3': { input: 3.00, output: 15.00 },
+    // GLM 4.7 (OpenRouter/Cerebras)
+    'z-ai/glm-4.7': { input: 0.55, output: 2.19 },
+    'zai-glm-4.7': { input: 0.55, output: 2.19 },
+};
+
+function normalizeTokenUsage({ input = 0, output = 0, thinking = 0, total, cached = 0, cacheWrite = 0, cacheWrite5m = 0, cacheWrite1h = 0 } = {}) {
+    const tokenCount = value => Number.isFinite(value) ? Math.max(0, value) : 0;
+    const normalizedInput = tokenCount(input);
+    const normalizedOutput = tokenCount(output);
+    const normalizedThinking = tokenCount(thinking);
+    const normalizedCached = tokenCount(cached);
+    const normalizedCacheWrite5m = tokenCount(cacheWrite5m);
+    const normalizedCacheWrite1h = tokenCount(cacheWrite1h);
+    const normalizedCacheWrite = Math.max(
+        tokenCount(cacheWrite),
+        normalizedCacheWrite5m + normalizedCacheWrite1h
+    );
+    const normalizedTotal = Number.isFinite(total)
+        ? Math.max(0, total)
+        : normalizedInput + normalizedOutput + normalizedThinking;
+    const uncachedInput = Math.max(0, normalizedInput - normalizedCached - normalizedCacheWrite);
+    const cacheHitRate = normalizedInput > 0
+        ? Number((normalizedCached / normalizedInput).toFixed(4))
+        : 0;
+
+    return {
+        input: normalizedInput,
+        output: normalizedOutput,
+        thinking: normalizedThinking,
+        total: normalizedTotal,
+        cached: normalizedCached,
+        cacheWrite: normalizedCacheWrite,
+        cacheWrite5m: normalizedCacheWrite5m,
+        cacheWrite1h: normalizedCacheWrite1h,
+        uncachedInput,
+        cacheHitRate,
+        cacheSavings: 0,
+        cacheWritePremium: 0,
+        breakEvenHits: 0,
+        cost: 0,
+        costBreakdown: {
+            uncachedInput: 0,
+            cachedInput: 0,
+            cacheWrite: 0,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+            output: 0,
+            total: 0
+        }
+    };
+}
+
+function calculateCostBreakdown(modelKey, tokens) {
+    const pricing = MODEL_PRICING[modelKey];
+    if (!pricing) return normalizeTokenUsage().costBreakdown;
+
+    const normalized = normalizeTokenUsage(tokens);
+    const longContext = pricing.longContext;
+    const useLongContextRates = usesLongContextRates(pricing, normalized.input);
+    const inputMultiplier = useLongContextRates ? longContext.inputMultiplier : 1;
+    const outputMultiplier = useLongContextRates ? longContext.outputMultiplier : 1;
+    const {
+        input: inputPerMillion,
+        cachedInput: cachedInputPerMillion = inputPerMillion,
+        cacheWrite: cacheWritePerMillion = inputPerMillion,
+        cacheWrite1h: cacheWrite1hPerMillion = cacheWritePerMillion,
+        output: outputPerMillion
+    } = pricing;
+    const roundCost = value => Number(value.toFixed(12));
+    const genericCacheWrite = Math.max(
+        0,
+        normalized.cacheWrite - normalized.cacheWrite5m - normalized.cacheWrite1h
+    );
+    const cacheWrite5mCost = roundCost(
+        normalized.cacheWrite5m * cacheWritePerMillion * inputMultiplier / 1_000_000
+    );
+    const cacheWrite1hCost = roundCost(
+        normalized.cacheWrite1h * cacheWrite1hPerMillion * inputMultiplier / 1_000_000
+    );
+    const genericCacheWriteCost = roundCost(
+        genericCacheWrite * cacheWritePerMillion * inputMultiplier / 1_000_000
+    );
+    const breakdown = {
+        uncachedInput: roundCost(normalized.uncachedInput * inputPerMillion * inputMultiplier / 1_000_000),
+        cachedInput: roundCost(normalized.cached * cachedInputPerMillion * inputMultiplier / 1_000_000),
+        cacheWrite: roundCost(genericCacheWriteCost + cacheWrite5mCost + cacheWrite1hCost),
+        cacheWrite5m: cacheWrite5mCost,
+        cacheWrite1h: cacheWrite1hCost,
+        output: roundCost(
+            (normalized.output + normalized.thinking) * outputPerMillion * outputMultiplier / 1_000_000
+        )
+    };
+    breakdown.total = roundCost(
+        breakdown.uncachedInput
+        + breakdown.cachedInput
+        + breakdown.cacheWrite
+        + breakdown.output
+    );
+    return breakdown;
+}
+
+function calculateCacheMetrics(modelKey, tokens) {
+    const pricing = MODEL_PRICING[modelKey];
+    const emptyMetrics = {
+        cacheSavings: 0,
+        cacheWritePremium: 0,
+        breakEvenHits: 0
+    };
+    if (!pricing) return emptyMetrics;
+
+    const normalized = normalizeTokenUsage(tokens);
+    const longContext = pricing.longContext;
+    const useLongContextRates = usesLongContextRates(pricing, normalized.input);
+    const inputMultiplier = useLongContextRates ? longContext.inputMultiplier : 1;
+    const cachedInputPerMillion = pricing.cachedInput ?? pricing.input;
+    const cacheWritePerMillion = pricing.cacheWrite ?? pricing.input;
+    const cacheWrite1hPerMillion = pricing.cacheWrite1h ?? cacheWritePerMillion;
+    const readSavingsPerMillion = Math.max(0, pricing.input - cachedInputPerMillion) * inputMultiplier;
+    const writePremiumPerMillion = Math.max(0, cacheWritePerMillion - pricing.input) * inputMultiplier;
+    const write1hPremiumPerMillion = Math.max(0, cacheWrite1hPerMillion - pricing.input) * inputMultiplier;
+    const roundCost = value => Number(value.toFixed(12));
+    const cacheSavings = roundCost(normalized.cached * readSavingsPerMillion / 1_000_000);
+    const genericCacheWrite = Math.max(
+        0,
+        normalized.cacheWrite - normalized.cacheWrite5m - normalized.cacheWrite1h
+    );
+    const cacheWritePremium = roundCost(
+        (
+            (genericCacheWrite + normalized.cacheWrite5m) * writePremiumPerMillion
+            + normalized.cacheWrite1h * write1hPremiumPerMillion
+        ) / 1_000_000
+    );
+    const fullHitSavings = normalized.cacheWrite * readSavingsPerMillion / 1_000_000;
+
+    return {
+        cacheSavings,
+        cacheWritePremium,
+        breakEvenHits: fullHitSavings > 0
+            ? Number((cacheWritePremium / fullHitSavings).toFixed(4))
+            : 0
+    };
+}
+
+function calculateCost(modelKey, tokens) {
+    if (!hasModelPricing(modelKey)) return null;
+    return calculateCostBreakdown(modelKey, tokens).total;
+}
+
+function hasModelPricing(modelKey) {
+    return Object.prototype.hasOwnProperty.call(MODEL_PRICING, modelKey);
+}
+
+function extractCacheTokens(usage = {}) {
+    return usage.input_tokens_details?.cached_tokens
+        ?? usage.prompt_tokens_details?.cached_tokens
+        ?? usage.cache_read_input_tokens
+        ?? usage.cachedContentTokenCount
+        ?? usage.cached_content_token_count
+        ?? 0;
+}
+
+function extractCacheWriteTokens(usage = {}) {
+    return usage.input_tokens_details?.cache_write_tokens
+        ?? usage.prompt_tokens_details?.cache_write_tokens
+        ?? usage.cache_creation_input_tokens
+        ?? usage.cache_write_input_tokens
+        ?? usage.cacheWriteTokenCount
+        ?? usage.cache_write_token_count
+        ?? 0;
+}
+
+module.exports = {
+    normalizeTokenUsage,
+    calculateCostBreakdown,
+    calculateCacheMetrics,
+    calculateCost,
+    hasModelPricing,
+    extractCacheTokens,
+    extractCacheWriteTokens
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "5.0.6",
+  "version": "5.1.2",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/modelmix/SKILL.md

@@ -86,11 +86,11 @@ Chain shorthand methods to attach providers. First model is primary; others are
 const model = ModelMix.new()
     .sonnet46()        // primary
     .gpt52()           // fallback 1
-    .gemini3flash()    // fallback 2
+    .gemini37flash()   // fallback 2
     .addText("Hello!")
 ```
 
-If `sonnet46` fails, it automatically tries `gpt52`, then `gemini3flash`.
+If `sonnet46` fails, it automatically tries `gpt52`, then `gemini37flash`.
 
 The equivalent `chain()` form accepts public shortcut names directly in the
 same order. Append `@effort` for a per-model unified effort override (`-1` or
@@ -99,7 +99,7 @@ provider default when no chain effort is configured:
 
 ```javascript
 const model = ModelMix.new()
-    .chain('sonnet46', 'gpt52@20', 'gemini3flash@-1')
+    .chain('sonnet46', 'gpt52@20', 'gemini37flash@-1')
     .addText('Hello!');
 ```
 
@@ -143,7 +143,7 @@ ModelMix.new({ config: { effort: 80 } })
 | DeepSeek V4 | off | `low`↑ | `high`↑ | `high`↑ | `max`↑ | — |
 | MiniMax M3 | off | adaptive | adaptive | adaptive | adaptive | adaptive |
 
-\* Gemini bands: 0–24 / 25–49 / 50–74 / 75–100. Gemini 3.7 Flash supports only `low` / `medium` / `high`, so the first two bands clamp to `low`; `-1` keeps its native `medium` default. DeepSeek `↑` = thinking on; `off` = thinking disabled. MiniMax `off`/`adaptive` = `thinking.disabled` / `thinking.type=adaptive`. Gemini 2.5 maps 0–100 to `thinkingBudget`. Anthropic: adaptive + `output_config.effort` on Claude 5 / Fable / Opus 4.6+ / Sonnet 4.6+; Sonnet 4.5 / Haiku 4.5 use `thinking.type=enabled` + `budget_tokens`. Grok 4.6 maps 0–39 / 40–59 / 60–79 / 80–100 to `low` / `medium` / `high` / `xhigh`; without effort it uses native `high`. `-1` = adaptive/dynamic when available, else no-op. Levels clamp per model. Former `*think()` methods are removed — use `.effort(n).<model>()`. Kimi: `kimiK25()` / `kimiK26()`. Grok 4.20: `.grok420()` non-reasoning; `.effort(20+|-1).grok420()` selects reasoning.
+\* GPT-5.6 maps `100` to `max`; 80–99 remains `xhigh`. Gemini bands: 0–24 / 25–49 / 50–74 / 75–100. Gemini 3.7 Flash supports only `low` / `medium` / `high`, so the first two bands clamp to `low`; `-1` keeps its native `medium` default. DeepSeek `↑` = thinking on; `off` = thinking disabled. MiniMax `off`/`adaptive` = `thinking.disabled` / `thinking.type=adaptive`. Gemini 2.5 maps 0–100 to `thinkingBudget`. Anthropic: adaptive + `output_config.effort` on Claude 5 / Fable / Opus 4.6+ / Sonnet 4.6+; Sonnet 4.5 / Haiku 4.5 use `thinking.type=enabled` + `budget_tokens`. Grok 4.6 maps 0–39 / 40–59 / 60–79 / 80–100 to `low` / `medium` / `high` / `xhigh`; without effort it uses native `high`. `-1` = adaptive/dynamic when available, else no-op. Levels clamp per model. Former `*think()` methods are removed — use `.effort(n).<model>()`. Kimi: `kimiK25()` / `kimiK26()`. Grok 4.20: `.grok420()` non-reasoning; `.effort(20+|-1).grok420()` selects reasoning.
 
 ## Available Model Shorthands
 
@@ -151,7 +151,7 @@ ModelMix.new({ config: { effort: 80 } })
 
 Use `ModerationMix.new().openai()` with `.raw()` to classify text and images through OpenAI's Moderations endpoint. Read the results from `raw.moderation`. `ModerationMix` accepts moderation providers as ordered fallbacks, rejects generative providers, and does not generate text or support streaming.
 
-`gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `gpt41()` `gpt41mini()` `gpt41nano()` `o3()` `o4mini()`
+`gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `o3()` `o4mini()`
 
 ### Anthropic
 `fable50()` `opus50()` `opus48()` `opus47()` `opus46()` `sonnet5()` `sonnet46()` `sonnet45()` `haiku45()`
@@ -159,7 +159,7 @@ Use `ModerationMix.new().openai()` with `.raw()` to classify text and images thr
 Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.effort(100).opus50()`. `fable5()` and `opus5()` remain available as compatibility aliases.
 
 ### Google
-`gemini3pro()` `gemini3flash()` `gemini37flash()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()` `gemini25pro()` `gemini25flash()`
+`gemini31pro()` `gemini37flash()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()`
 
 ### Grok
 `grok46()` `grok45()` `grok43()` `grok420multiAgent()` `grok420()`
@@ -174,7 +174,7 @@ Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.ef
 `kimiK3()` — requires `MOONSHOT_API_KEY`; use `{ mix: { moonshot: false, openrouter: true } }` for OpenRouter.
 
 ### MiniMax
-`minimaxM25()` `minimaxM27()` `minimaxM3()`
+`minimaxM27()` `minimaxM3()`
 
 ### Fireworks
 `qwen36plus()` `qwen37plus()` `qwen38max()` `deepseekV4Flash()` `deepseekV4Pro()` `kimiK26()`
@@ -460,7 +460,7 @@ Omit all weights for equal probabilities. Otherwise every option needs a positiv
 const pool = ModelMix.new({ config: { roundRobin: true } })
     .gpt5mini()
     .sonnet45()
-    .gemini3flash();
+    .gemini37flash();
 
 const r1 = await pool.new().addText("Request 1").message();
 const r2 = await pool.new().addText("Request 2").message();
@@ -548,7 +548,7 @@ For full debug output, also set: `DEBUG=ModelMix* node script.js`
 ### Free-tier models
 
 ```javascript
-const model = ModelMix.new()
+const model = ModelMix.new({ mix: { openrouter: false } })
     .gptOss()
     .kimiK25()
     .hermes3()
@@ -556,7 +556,7 @@ const model = ModelMix.new()
 console.log(await model.message());
 ```
 
-These use providers with free quotas (OpenRouter, Groq, Cerebras). If one runs out of quota, ModelMix falls back to the next.
+These use providers with free quotas (Groq, Cerebras, and Together). OpenRouter is disabled because its GPT-OSS 120B route is no longer free. If one runs out of quota, ModelMix falls back to the next.
 
 ### Multi-provider routing
 

package/test/effort.test.js

@@ -1,4 +1,5 @@
 const { expect } = require('chai');
+const sinon = require('sinon');
 const {
     normalizeEffort,
     mapEffort,
@@ -69,6 +70,14 @@ describe('Unified effort scale', () => {
             expect(mapEffort('openai', 10)).to.deep.equal({ reasoning_effort: 'none' });
             expect(mapEffort('openai', 50)).to.deep.equal({ reasoning_effort: 'medium' });
             expect(mapEffort('openai', 90)).to.deep.equal({ reasoning_effort: 'xhigh' });
+            expect(mapEffort('openai', 100)).to.deep.equal({ reasoning_effort: 'xhigh' });
+        });
+
+        it('maps GPT-5.6 maximum unified effort to max', () => {
+            expect(mapEffort('openai', 99, 'gpt-5.6-luna')).to.deep.equal({ reasoning_effort: 'xhigh' });
+            for (const model of ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna']) {
+                expect(mapEffort('openai', 100, model)).to.deep.equal({ reasoning_effort: 'max' });
+            }
         });
 
         it('sets OpenAI adaptive only when supported (otherwise no-op)', () => {
@@ -351,6 +360,25 @@ describe('Unified effort scale', () => {
         });
     });
 
+    describe('debug logging', () => {
+        afterEach(() => {
+            sinon.restore();
+        });
+
+        it('includes the unified effort in the model header', async () => {
+            const provider = new MixOpenAIResponses();
+            sinon.stub(provider, 'create').resolves({ message: 'ok', toolCalls: [] });
+            const log = sinon.spy(console, 'log');
+            const model = ModelMix.new({ config: { debug: 1, effort: 60 } })
+                .attach('gpt-5.6-luna', provider)
+                .addText('Hello');
+
+            await model.message();
+
+            expect(log.calledWithMatch(/→ \[openairesponses:gpt-5\.6-luna@60\] #1/)).to.equal(true);
+        });
+    });
+
     describe('provider request wiring', () => {
         it('OpenAI Responses request uses mapped reasoning_effort', () => {
             const options = { model: 'gpt-5.2', messages: [] };
@@ -359,6 +387,14 @@ describe('Unified effort scale', () => {
             expect(request.reasoning).to.deep.equal({ effort: 'none' });
         });
 
+        it('GPT-5.6 Luna .effort(100) sends max reasoning effort', () => {
+            const model = ModelMix.new().effort(100).gpt56luna();
+            const options = { model: 'gpt-5.6-luna', messages: [] };
+            applyUnifiedEffort(options, model.config, 'openai', 'gpt-5.6-luna');
+            const request = MixOpenAIResponses.buildResponsesRequest(options, {});
+            expect(request.reasoning).to.deep.equal({ effort: 'max' });
+        });
+
         it('Anthropic config.effort maps through .effort().opus50()', () => {
             const model = ModelMix.new().effort(100).opus50();
             expect(model.config.effort).to.equal(100);

package/test/fallback.test.js

@@ -60,6 +60,18 @@ describe('Provider Fallback Chain Tests', () => {
                 .to.throw('Invalid chain model at index 0: expected a model shortcut string.');
         });
 
+        it('should reject removed shortcuts from the public chain API', () => {
+            for (const shortcut of [
+                'gpt41', 'gpt41mini', 'gpt41nano',
+                'gemini25flash', 'gemini25pro', 'gemini3pro', 'gemini3flash',
+                'minimaxM25'
+            ]) {
+                expect(model[shortcut]).to.equal(undefined);
+                expect(() => model.chain(shortcut))
+                    .to.throw(`Unknown model shortcut "${shortcut}" in chain().`);
+            }
+        });
+
         it('should use primary provider when available', async () => {
             model.gpt5mini().sonnet46().addText('Hello');
 
@@ -195,7 +207,7 @@ describe('Provider Fallback Chain Tests', () => {
         });
 
         it('should cascade through multiple fallbacks', async () => {
-            model.gpt5mini().sonnet46().gemini3flash().addText('Hello');
+            model.gpt5mini().sonnet46().gemini37flash().addText('Hello');
 
             // Mock failed OpenAI response
             nock('https://api.openai.com')
@@ -279,7 +291,7 @@ describe('Provider Fallback Chain Tests', () => {
         });
 
         it('should fallback from Anthropic to Google', async () => {
-            model.sonnet46().gemini3flash().addText('Test message');
+            model.sonnet46().gemini37flash().addText('Test message');
 
             // Mock Anthropic failure
             nock('https://api.anthropic.com')
@@ -665,7 +677,7 @@ describe('Provider Fallback Chain Tests', () => {
         });
 
         it('should provide detailed error information when all fallbacks fail', async () => {
-            model.gpt5mini().sonnet46().gemini3flash().addText('Test');
+            model.gpt5mini().sonnet46().gemini37flash().addText('Test');
 
             // Mock all providers failing with different errors
             nock('https://api.openai.com')

package/test/history.test.js

@@ -570,7 +570,7 @@ describe('Conversation History Tests', () => {
             const model = ModelMix.new({
                 config: { debug: false, max_history: 10 }
             });
-            model.gemini3flash();
+            model.gemini37flash();
 
             model.addText('Hello');
             nock('https://generativelanguage.googleapis.com')