modelmix 4.7.4 → 5.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "4.7.4",
+  "version": "5.0.1",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,7 +25,9 @@
     "kimi",
     "mythos",
     "gpt5",
+    "opus50",
     "opus5",
+    "fable50",
     "fable",
     "sonnet",
     "openrouter",
@@ -51,6 +53,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "bottleneck": "^2.19.5",
+    "ejs": "6.0.1",
     "file-type": "^21.3.4",
     "lemonlog": "^1.2.2",
     "ws": "^8.21.1"

package/skills/modelmix/SKILL.md

@@ -37,7 +37,7 @@ Do NOT use for:
 - [Get raw response (tokens, thinking, tool calls)](#get-raw-response)
 - [Access full response with lastRaw](#access-full-response-with-lastraw)
 - [Add images](#add-images)
-- [Templates with placeholders](#templates-with-placeholders)
+- [EJS templates](#ejs-templates)
 - [Round-robin load balancing](#round-robin-load-balancing)
 - [MCP integration](#mcp-integration)
 - [Custom local tools](#custom-local-tools)
@@ -122,9 +122,9 @@ ModelMix.new({ config: { effort: 80 } })
 `gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `gpt41()` `gpt41mini()` `gpt41nano()` `o3()` `o4mini()`
 
 ### Anthropic
-`fable5()` `opus5()` `opus48()` `opus47()` `opus46()` `sonnet5()` `sonnet46()` `sonnet45()` `haiku45()`
+`fable50()` `opus50()` `opus48()` `opus47()` `opus46()` `sonnet5()` `sonnet46()` `sonnet45()` `haiku45()`
 
-Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.effort(100).opus5()`.
+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()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()` `gemini25pro()` `gemini25flash()`
@@ -301,11 +301,51 @@ After calling `message()`, `json()`, `block()`, or `stream()`, use `lastRaw` to
 const model = ModelMix.new().gpt5mini().addText("Hello!");
 const text = await model.message();
 console.log(model.lastRaw.tokens);
-// { input: 122, output: 86, total: 541, cost: 0.000319, speed: 38 }
+// {
+//   input: 1200, output: 50, total: 1250,
+//   cached: 1024, cacheWrite: 0, uncachedInput: 176,
+//   cacheWrite5m: 0, cacheWrite1h: 0,
+//   cacheHitRate: 0.8533, cacheSavings: 0.00018432,
+//   cacheWritePremium: 0, breakEvenHits: 0,
+//   cost: 0.00011568,
+//   costBreakdown: {
+//     uncachedInput: 0.0000352, cachedInput: 0.00002048,
+//     cacheWrite: 0, cacheWrite5m: 0, cacheWrite1h: 0,
+//     output: 0.00006, total: 0.00011568
+//   },
+//   speed: 38
+// }
 console.log(model.lastRaw.think);    // reasoning content (if available)
 console.log(model.lastRaw.response); // raw API response
 ```
 
+### GPT-5.6 explicit prompt caching
+
+```javascript
+const model = ModelMix.new()
+  .gpt56luna({
+    options: {
+      prompt_cache_key: 'stable-prefix-v1',
+      prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+    }
+  })
+  .haiku45({
+    options: {
+      cache_control: { type: 'ephemeral', ttl: '1h' }
+    }
+  })
+  .addText(longStableInstructions, {
+    cache: { breakpoint: true }
+  })
+  .addText('Handle this variable request.');
+
+const result = await model.raw();
+```
+
+`cache: { breakpoint: true }` is provider-neutral: GPT-5.6 receives `prompt_cache_breakpoint`, Anthropic receives `cache_control`, and unsupported providers omit it. Keep native request policies inside each model shorthand so they do not leak across fallbacks. Anthropic usage separates `cacheWrite5m` and `cacheWrite1h`; `cacheWrite` stays as their compatible aggregate.
+
+GPT-5.6 replaces `prompt_cache_retention` with `prompt_cache_options.ttl`. Explicit breakpoints also work on image methods and Responses-native `input_text`, `input_image`, and `input_file` blocks. Prompts need at least 1,024 tokens to be cached. Requests over 272K input tokens use 2× input and 1.5× output prices for the complete request; ModelMix applies these multipliers to `cost`, `costBreakdown`, and cache economics.
+
 ### Add images
 
 ```javascript
@@ -319,20 +359,69 @@ const description = await model.message();
 
 All image methods accept an optional second argument `{ role }` (default `"user"`).
 
-### Templates with placeholders
+### EJS templates
 
 ```javascript
 const model = ModelMix.new().gpt5mini();
 model.setSystemFromFile('./prompts/system.md');
 model.addTextFromFile('./prompts/task.md');
-model.replace({
-    '{role}': 'data analyst',
-    '{language}': 'Spanish'
+model.assign({
+    role: 'data analyst',
+    language: 'Spanish'
 });
-model.replaceKeyFromFile('{code}', './src/utils.js');
 console.log(await model.message());
 ```
 
+Templates use standard EJS syntax. Use `<%- value %>` for raw prompt content and `<%= value %>` only when XML escaping is intentional. Missing variables and files throw. Templates may contain JavaScript, so the template source must be developer-controlled; untrusted content belongs only in `assign()` data.
+
+Use `assignKey(key, value)` for one value and `assign({ ... })` for several values.
+
+Start with a static include. Paths are resolved relative to the containing template:
+
+```ejs
+<%- include('shared/rules.md') %>
+```
+
+Use a variable when the included file must be selected dynamically:
+
+```ejs
+Analyze the following source:
+
+<%- include(sourceFile) %>
+```
+
+```javascript
+model.assign({ sourceFile: '../src/utils.js' });
+```
+
+Included files are EJS source, so the path and file must be developer-controlled. Untrusted runtime content belongs in ordinary `assign()` values, not include paths. To expose a rendered file as a data key, call `assignKeyFromFile(key, filePath)`; it uses EJS `include`, supports includes relative to that file, and renders once per request. For recursive data, a template may include itself with an explicit stopping condition:
+
+```ejs
+<%- node.text %>
+<% if (node.children?.length && depth < maxDepth) { %>
+<% for (const child of node.children) { %>
+<%- include('tree.ejs', { node: child, depth: depth + 1, maxDepth }) %>
+<% } %>
+<% } %>
+```
+
+Initialize it with `assign({ node, depth: 0, maxDepth: 10 })`. Values supplied through `assign()` remain data and are never interpreted recursively as EJS.
+
+Use ModelMix choice directives for random prompt variants:
+
+```ejs
+<% choice %>
+<% option 20 %>
+Use emojis.
+<% option 40 %>
+Use few emojis.
+<% option 40 %>
+Do not use emojis.
+<% /choice %>
+```
+
+Omit all weights for equal probabilities. Otherwise every option needs a positive relative weight; weights do not need to total 100. Keep directives on their own lines. Nested choices and choices inside includes are supported. A request keeps its selections through retries, provider fallbacks, and tool continuations.
+
 ### Round-robin load balancing
 
 ```javascript
@@ -464,27 +553,28 @@ const model = ModelMix.new({
 - When using MCP tools or `addTool()`, set `max_history` to at least 3 — tool call/response pairs consume history slots.
 - Use `.json()` for structured output instead of parsing text manually. Use descriptor objects `{ description, required, enum, default, nullable }` for richer schema control.
 - Use `.message()` for simple text, `.raw()` when you need tokens/thinking/toolCalls.
-- For Anthropic thinking, use unified `effort` (`-1` or `0`–`100`) via `config.effort` or `.effort(n)` — e.g. `.effort(100).opus5()`. Never put `effort` in `options`. Native fields win if already set.
-- Template placeholders use `{key}` syntax in both system prompts and user messages.
+- For Anthropic thinking, use unified `effort` (`-1` or `0`–`100`) via `config.effort` or `.effort(n)` — e.g. `.effort(100).opus50()`. Never put `effort` in `options`. Native fields win if already set.
+- Templates use EJS syntax in both system prompts and user messages; prefer `<%- key %>` for raw prompt data.
 - The library uses CommonJS internally but supports ESM import via `{ ModelMix }`.
 - GPT-5+ models automatically use `max_completion_tokens` instead of `max_tokens`.
 - o-series models (o3, o4mini) automatically strip `max_tokens` and `temperature` since those APIs don't support them.
 - Anthropic Opus 4.7+ / Claude 5 family automatically strip `temperature`, `top_p`, and `top_k` (API rejects them).
-- `addText()`, `addImage()`, `addImageFromUrl()`, and `addImageFromBuffer()` all accept `{ role }` as second argument (default `"user"`).
+- `addText()`, `addImage()`, `addImageFromUrl()`, and `addImageFromBuffer()` accept `{ role, cache?: { breakpoint: true } }` as the second argument (default role: `"user"`). Adapters translate or omit the neutral marker by provider.
 
 ## API Quick Reference
 
 | Method | Returns | Description |
 | --- | --- | --- |
-| `.addText(text, {role?})` | `this` | Add user message |
-| `.addTextFromFile(path, {role?})` | `this` | Add user message from file |
+| `.addText(text, {role?, cache?})` | `this` | Add user message |
+| `.addTextFromFile(path, {role?, cache?})` | `this` | Add user message from file |
 | `.setSystem(text)` | `this` | Set system prompt |
 | `.setSystemFromFile(path)` | `this` | Set system prompt from file |
-| `.addImage(path, {role?})` | `this` | Add image from file |
-| `.addImageFromUrl(url, {role?})` | `this` | Add image from URL or data URI |
-| `.addImageFromBuffer(buffer, {role?})` | `this` | Add image from Buffer |
-| `.replace({})` | `this` | Set placeholder replacements |
-| `.replaceKeyFromFile(key, path)` | `this` | Replace placeholder with file content |
+| `.addImage(path, {role?, cache?})` | `this` | Add image from file |
+| `.addImageFromUrl(url, {role?, cache?})` | `this` | Add image from URL or data URI |
+| `.addImageFromBuffer(buffer, {role?, cache?})` | `this` | Add image from Buffer |
+| `.assign({})` | `this` | Assign EJS template data |
+| `.assignKey(key, value)` | `this` | Assign one EJS template-data value |
+| `.assignKeyFromFile(key, path)` | `this` | Assign the rendered output of an EJS file to one key |
 | `.message()` | `Promise<string>` | Get text response |
 | `.json(example, desc?, opts?)` | `Promise<object\|array>` | Get structured JSON |
 | `.raw()` | `Promise<{message, think, toolCalls, tokens, response}>` | Full response |

package/test/README.md

@@ -9,7 +9,7 @@ This comprehensive test suite provides complete coverage for the ModelMix librar
 These tests require actual API keys and test the complete integration:
 - Real image processing with multiple providers
 - Actual JSON structured output  
-- Template replacement with real models
+- EJS template rendering with real models
 - Multi-modal combinations
 - Performance testing with real APIs
 
@@ -45,13 +45,14 @@ npm test -- --grep "Live Integration"
 - ✅ Context preservation through fallbacks
 - ✅ Provider-specific configurations
 
-### 3. File Operations and Templates (`templates.test.js`)
-- ✅ Template variable replacement
-- ✅ Template file loading
-- ✅ JSON file processing
-- ✅ Absolute and relative paths
-- ✅ File error handling
-- ✅ Complex template + file integration
+### 3. File Operations and EJS Templates (`templates.test.js`)
+- ✅ Raw and XML-escaped EJS output
+- ✅ Nested data, conditionals, and loops
+- ✅ Uniform, weighted, nested, and included choice blocks
+- ✅ File templates and relative includes
+- ✅ Raw file and JSON data injection
+- ✅ Missing-variable and missing-file errors
+- ✅ JSON, block, system, and multi-turn integration
 
 ### 4. Image Processing and Multimodal (`images.test.js`)
 - ✅ Base64 data handling
@@ -155,4 +156,4 @@ DEBUG_TESTS=true npm test
 - All tests use API mocking to avoid real calls
 - Test environment variables are configured in `setup.js`
 - Tests are independent and can run in any order
-- Automatic cleanup prevents interference between tests
+- Automatic cleanup prevents interference between tests

package/test/anthropic.test.js

@@ -5,15 +5,29 @@ const { ModelMix, MixAnthropic } = require('../index.js');
 describe('Anthropic Model Registration Tests', () => {
     it('should register Claude Fable 5', () => {
         const model = ModelMix.new();
-        model.fable5();
+        model.fable50();
 
         expect(model.models).to.have.length(1);
         expect(model.models[0].key).to.equal('claude-fable-5');
         expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
     });
 
-    it('should apply max effort thinking via .effort(100).fable5()', () => {
-        const model = ModelMix.new().effort(100).fable5();
+    it('should keep fable5() as an alias for fable50()', () => {
+        const model = ModelMix.new();
+
+        expect(model.fable5({
+            options: { max_tokens: 123 },
+            config: { url: 'https://anthropic.example.test' }
+        })).to.equal(model);
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('claude-fable-5');
+        expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+        expect(model.models[0].provider.options.max_tokens).to.equal(123);
+        expect(model.models[0].provider.config.url).to.equal('https://anthropic.example.test');
+    });
+
+    it('should apply max effort thinking via .effort(100).fable50()', () => {
+        const model = ModelMix.new().effort(100).fable50();
         const { applyUnifiedEffort } = require('../effort.js');
 
         expect(model.config.effort).to.equal(100);
@@ -25,15 +39,29 @@ describe('Anthropic Model Registration Tests', () => {
 
     it('should register Claude Opus 5', () => {
         const model = ModelMix.new();
-        model.opus5();
+        model.opus50();
 
         expect(model.models).to.have.length(1);
         expect(model.models[0].key).to.equal('claude-opus-5');
         expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
     });
 
-    it('should apply max effort thinking via .effort(100).opus5()', () => {
-        const model = ModelMix.new().effort(100).opus5();
+    it('should keep opus5() as an alias for opus50()', () => {
+        const model = ModelMix.new();
+
+        expect(model.opus5({
+            options: { max_tokens: 123 },
+            config: { url: 'https://anthropic.example.test' }
+        })).to.equal(model);
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('claude-opus-5');
+        expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+        expect(model.models[0].provider.options.max_tokens).to.equal(123);
+        expect(model.models[0].provider.config.url).to.equal('https://anthropic.example.test');
+    });
+
+    it('should apply max effort thinking via .effort(100).opus50()', () => {
+        const model = ModelMix.new().effort(100).opus50();
         const { applyUnifiedEffort } = require('../effort.js');
 
         expect(model.config.effort).to.equal(100);
@@ -133,6 +161,101 @@ describe('Anthropic Model Registration Tests', () => {
         });
     });
 
+    describe('Provider-neutral prompt caching', () => {
+        it('should translate neutral breakpoints and remove foreign OpenAI controls', async () => {
+            const originalApiKey = process.env.ANTHROPIC_API_KEY;
+            process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+
+            try {
+                const provider = new MixAnthropic();
+                let requestBody;
+                nock('https://api.anthropic.com')
+                    .post('/v1/messages', body => {
+                        requestBody = body;
+                        return true;
+                    })
+                    .reply(200, {
+                        content: [{ type: 'text', text: 'Done' }],
+                        usage: { input_tokens: 1, output_tokens: 1 }
+                    });
+
+                await provider.create({
+                    config: { system: 'You are an assistant.' },
+                    options: {
+                        model: 'claude-haiku-4-5-20251001',
+                        max_tokens: 16,
+                        cache_control: { type: 'ephemeral', ttl: '1h' },
+                        prompt_cache_key: 'openai-only',
+                        prompt_cache_options: { mode: 'explicit', ttl: '30m' },
+                        messages: [{
+                            role: 'user',
+                            content: [
+                                { type: 'text', text: 'Stable', cache: { breakpoint: true } },
+                                {
+                                    type: 'text',
+                                    text: 'Variable',
+                                    prompt_cache_breakpoint: { mode: 'explicit' }
+                                }
+                            ]
+                        }]
+                    }
+                });
+
+                expect(requestBody).to.not.have.property('prompt_cache_key');
+                expect(requestBody).to.not.have.property('prompt_cache_options');
+                expect(requestBody).to.not.have.property('cache_control');
+                expect(requestBody.messages[0].content[0]).to.deep.equal({
+                    type: 'text',
+                    text: 'Stable',
+                    cache_control: { type: 'ephemeral', ttl: '1h' }
+                });
+                expect(requestBody.messages[0].content[1]).to.deep.equal({
+                    type: 'text',
+                    text: 'Variable'
+                });
+            } finally {
+                if (originalApiKey === undefined) delete process.env.ANTHROPIC_API_KEY;
+                else process.env.ANTHROPIC_API_KEY = originalApiKey;
+                nock.cleanAll();
+            }
+        });
+
+        it('should preserve top-level automatic caching when there is no explicit breakpoint', async () => {
+            const originalApiKey = process.env.ANTHROPIC_API_KEY;
+            process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+
+            try {
+                const provider = new MixAnthropic();
+                let requestBody;
+                nock('https://api.anthropic.com')
+                    .post('/v1/messages', body => {
+                        requestBody = body;
+                        return true;
+                    })
+                    .reply(200, {
+                        content: [{ type: 'text', text: 'Done' }],
+                        usage: { input_tokens: 1, output_tokens: 1 }
+                    });
+
+                await provider.create({
+                    config: { system: 'You are an assistant.' },
+                    options: {
+                        model: 'claude-haiku-4-5-20251001',
+                        max_tokens: 16,
+                        cache_control: { type: 'ephemeral' },
+                        messages: [{ role: 'user', content: 'Hello' }]
+                    }
+                });
+
+                expect(requestBody.cache_control).to.deep.equal({ type: 'ephemeral' });
+            } finally {
+                if (originalApiKey === undefined) delete process.env.ANTHROPIC_API_KEY;
+                else process.env.ANTHROPIC_API_KEY = originalApiKey;
+                nock.cleanAll();
+            }
+        });
+    });
+
     it('should register Claude Opus 4.8', () => {
         const model = ModelMix.new();
         model.opus48();
@@ -154,15 +277,29 @@ describe('Anthropic Model Registration Tests', () => {
 
     it('should register Claude Sonnet 5', () => {
         const model = ModelMix.new();
-        model.sonnet5();
+        model.sonnet50();
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('claude-sonnet-5');
+        expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+    });
+
+    it('should keep sonnet5() as an alias for sonnet50()', () => {
+        const model = ModelMix.new();
 
+        expect(model.sonnet5({
+            options: { max_tokens: 123 },
+            config: { url: 'https://anthropic.example.test' }
+        })).to.equal(model);
         expect(model.models).to.have.length(1);
         expect(model.models[0].key).to.equal('claude-sonnet-5');
         expect(model.models[0].provider).to.be.instanceOf(MixAnthropic);
+        expect(model.models[0].provider.options.max_tokens).to.equal(123);
+        expect(model.models[0].provider.config.url).to.equal('https://anthropic.example.test');
     });
 
-    it('should apply adaptive thinking via .effort(100).sonnet5()', () => {
-        const model = ModelMix.new().effort(100).sonnet5();
+    it('should apply adaptive thinking via .effort(100).sonnet50()', () => {
+        const model = ModelMix.new().effort(100).sonnet50();
         const { applyUnifiedEffort } = require('../effort.js');
 
         const options = { model: 'claude-sonnet-5' };

package/test/effort.test.js

@@ -336,8 +336,8 @@ describe('Unified effort scale', () => {
             expect(request.reasoning).to.deep.equal({ effort: 'none' });
         });
 
-        it('Anthropic config.effort maps through .effort().opus5()', () => {
-            const model = ModelMix.new().effort(100).opus5();
+        it('Anthropic config.effort maps through .effort().opus50()', () => {
+            const model = ModelMix.new().effort(100).opus50();
             expect(model.config.effort).to.equal(100);
 
             const options = {