modelmix 4.7.4 → 5.0.1

package/AGENTS.md

@@ -0,0 +1,43 @@
+# Repository Guidelines
+
+## Project Overview
+
+ModelMix is a CommonJS Node.js library for LLM providers, fallback chains, rate limiting, templates, multimodal requests, and MCP tools. Node is not pinned; the root uses pnpm 11.18 and requires no compilation.
+
+## Project Structure & Module Organization
+
+- `index.js` owns the public API and provider classes; synchronize public contracts with `index.d.ts`.
+- Root helper modules isolate effort mapping, schemas, HTTP, multipart, and MCP behavior.
+- `test/*.test.js` contains Mocha suites; fixtures and setup live under `test/`.
+- `demo/` holds examples and a separate npm manifest; `skills/modelmix/` contains the published skill.
+- `node_modules/` is generated and ignored. Update `pnpm-lock.yaml` only through pnpm.
+
+## Build, Test, and Development Commands
+
+- `pnpm install` installs locked root dependencies.
+- `pnpm test` runs the complete Mocha suite with shared setup.
+- `pnpm run test:offline` runs the main mocked regressions without intentional live-provider coverage.
+- `pnpm run test:templates`, `pnpm run test:fallback`, and `pnpm run test:watch` support focused development.
+- `pnpm run test:live` and `pnpm run test:live.mcp` require real credentials, may incur costs, and must be reported separately.
+
+No build, lint, formatter, or standalone typecheck command is configured. Do not add tooling or dependencies without approval.
+
+## Coding Style & Naming Conventions
+
+Use four-space indentation, semicolons, single quotes, CommonJS `require`, `camelCase`, and `PascalCase` classes. Keep provider behavior in `Mix*` classes. Public shortcut changes must update implementation, declarations, tests, docs, demos, and the skill together. Add aliases only with approval.
+
+## Testing Guidelines
+
+Use Mocha, Chai, Sinon, and Nock. Name regression files `*.test.js`; reproduce bugs before fixing them. Offline tests must not depend on order or real keys. Prefer instance seams such as `_choiceRandom()` over global stubs.
+
+## Configuration & Security
+
+There is no configuration module: callers pass policy through `ModelMix.new({ config, options })`; credentials come from environment variables. Never commit `.env` files, credentials, secret payloads, or unrequested defaults.
+
+## Commit & Pull Request Guidelines
+
+History favors short imperative subjects, commonly `feat:`, `fix:`, or `chore:`. Keep commits scoped and do not commit unless requested. Pull requests should explain behavior and compatibility impact, link issues, and list exact test commands and results; include screenshots only for visible changes.
+
+## Domain & Contributor Conventions
+
+A **provider** is an API backend, a **model shortcut** is a fluent method, and a **fallback chain** is ordered. Write code and docs in English; reply in the contributor's language.

package/README.md

@@ -163,54 +163,54 @@ Here's a comprehensive list of available methods:
 
 | Method              | Provider   | Model                        | Price (I/O) per 1 M tokens |
 | ------------------- | ---------- | ---------------------------- | -------------------------- |
-| `gpt56sol()`        | OpenAI     | gpt-5.6-sol                  | [\$5.00 / \$30.00][1]      |
-| `gpt56terra()`      | OpenAI     | gpt-5.6-terra                | [\$2.00 / \$12.00][1]      |
-| `gpt56luna()`       | OpenAI     | gpt-5.6-luna                 | [\$0.20 / \$1.20][1]       |
-| `gpt55()`           | OpenAI     | gpt-5.5                      | [\$5.00 / \$30.00][1]      |
-| `gpt54()`           | OpenAI     | gpt-5.4                      | [\$2.50 / \$15.00][1]      |
-| `gpt54mini()`       | OpenAI     | gpt-5.4-mini                 | [\$0.75 / \$4.50][1]       |
-| `gpt54nano()`       | OpenAI     | gpt-5.4-nano                 | [\$0.20 / \$1.25][1]       |
-| `gpt53codex()`      | OpenAI     | gpt-5.3-codex                | [\$1.25 / \$14.00][1]      |
-| `gpt52()`           | OpenAI     | gpt-5.2                      | [\$1.75 / \$14.00][1]      |
-| `gpt51()`           | OpenAI     | gpt-5.1                      | [\$1.25 / \$10.00][1]      |
-| `gpt5mini()`        | OpenAI     | gpt-5-mini                   | [\$0.25 / \$2.00][1]       |
-| `gpt5nano()`        | OpenAI     | gpt-5-nano                   | [\$0.05 / \$0.40][1]       |
-| `gpt41()`           | OpenAI     | gpt-4.1                      | [\$2.00 / \$8.00][1]       |
-| `gpt41mini()`       | OpenAI     | gpt-4.1-mini                 | [\$0.40 / \$1.60][1]       |
-| `gpt41nano()`       | OpenAI     | gpt-4.1-nano                 | [\$0.10 / \$0.40][1]       |
-| `gptOss()`          | Together   | gpt-oss-120B                 | [\$0.15 / \$0.60][7]       |
-| `fable5()`          | Anthropic  | claude-fable-5               | [\$10.00 / \$50.00][2]     |
-| `opus5()`           | Anthropic  | claude-opus-5                | [\$5.00 / \$25.00][2]      |
-| `opus48()`          | Anthropic  | claude-opus-4-8              | [\$5.00 / \$25.00][2]      |
-| `opus47()`          | Anthropic  | claude-opus-4-7              | [\$5.00 / \$25.00][2]      |
-| `opus46()`          | Anthropic  | claude-opus-4-6              | [\$5.00 / \$25.00][2]      |
-| `sonnet5()`         | Anthropic  | claude-sonnet-5              | [\$3.00 / \$15.00][2]      |
-| `sonnet46()`        | Anthropic  | claude-sonnet-4-6            | [\$3.00 / \$15.00][2]      |
-| `haiku45()`         | Anthropic  | claude-haiku-4-5-20251001    | [\$1.00 / \$5.00][2]       |
-| `gemini31pro()`     | Google     | gemini-3.1-pro-preview       | [\$2.00 / \$12.00][3]      |
-| `gemini36flash()`   | Google     | gemini-3.6-flash             | [\$1.50 / \$7.50][3]       |
-| `gemini35flash()`   | Google     | gemini-3.5-flash             | [\$0.75 / \$4.50][3]       |
-| `gemini35flashLite()`| Google    | gemini-3.5-flash-lite        | [\$0.30 / \$2.50][3]       |
-| `gemini31flashLite()`| Google     | gemini-3.1-flash-lite-preview | [\$0.25 / \$1.50][3]       |
-| `grok45()`          | Grok       | grok-4.5                     | [\$2.00 / \$6.00][6]       |
-| `grok43()`          | Grok       | grok-4.3                     | [\$1.25 / \$2.50][6]       |
-| `grok420multiAgent()`| Grok      | grok-4.20-multi-agent-0309   | [\$1.25 / \$2.50][6]       |
-| `grok420()`         | Grok       | grok-4.20-0309 (†)           | [\$1.25 / \$2.50][6]       |
-| `qwen36plus()`      | Fireworks/Together | qwen3p6-plus / Qwen3.6-Plus | [\$0.50 / \$3.00][10] |
-| `qwen37plus()`      | Fireworks  | models/qwen3p7-plus          | [\$0.40 / \$1.60][10]      |
-| `qwen38max()`       | OpenRouter | qwen/qwen3.8-max             | [\$2.00 / \$6.00][12]      |
-| `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]      |
-| `minimaxM3()`       | MiniMax    | MiniMax-M3                   | [\$0.30 / \$1.20][9]       |
-| `minimaxM27()`      | MiniMax    | MiniMax-M2.7                 | [\$0.30 / \$1.20][9]       |
-| `sonar()`           | Perplexity | sonar                        | [\$1.00 / \$1.00][4]       |
-| `sonarPro()`        | Perplexity | sonar-pro                    | [\$3.00 / \$15.00][4]      |
-| `hermes3()`         | Lambda     | Hermes-3-Llama-3.1-405B-FP8  | [\$0.80 / \$0.80][8]       |
-| `kimiK3()`          | Moonshot   | kimi-k3                      | [\$3.00 / \$15.00][11]     |
-| `kimiK25()`         | Together   | Kimi-K2.5                    | [\$0.50 / \$2.80][7]       |
-| `kimiK26()`         | Fireworks  | models/kimi-k2p6             | [\$0.95 / \$4.00][10]      |
+| `gpt56sol()`        | OpenAI     | gpt-5.6-sol                  | [\$5.00/\$30.00][1]      |
+| `gpt56terra()`      | OpenAI     | gpt-5.6-terra                | [\$2.00/\$12.00][1]      |
+| `gpt56luna()`       | OpenAI     | gpt-5.6-luna                 | [\$0.20/\$1.20][1]       |
+| `gpt55()`           | OpenAI     | gpt-5.5                      | [\$5.00/\$30.00][1]      |
+| `gpt54()`           | OpenAI     | gpt-5.4                      | [\$2.50/\$15.00][1]      |
+| `gpt54mini()`       | OpenAI     | gpt-5.4-mini                 | [\$0.75/\$4.50][1]       |
+| `gpt54nano()`       | OpenAI     | gpt-5.4-nano                 | [\$0.20/\$1.25][1]       |
+| `gpt53codex()`      | OpenAI     | gpt-5.3-codex                | [\$1.25/\$14.00][1]      |
+| `gpt52()`           | OpenAI     | gpt-5.2                      | [\$1.75/\$14.00][1]      |
+| `gpt51()`           | OpenAI     | gpt-5.1                      | [\$1.25/\$10.00][1]      |
+| `gpt5mini()`        | OpenAI     | gpt-5-mini                   | [\$0.25/\$2.00][1]       |
+| `gpt5nano()`        | OpenAI     | gpt-5-nano                   | [\$0.05/\$0.40][1]       |
+| `gpt41()`           | OpenAI     | gpt-4.1                      | [\$2.00/\$8.00][1]       |
+| `gpt41mini()`       | OpenAI     | gpt-4.1-mini                 | [\$0.40/\$1.60][1]       |
+| `gpt41nano()`       | OpenAI     | gpt-4.1-nano                 | [\$0.10/\$0.40][1]       |
+| `gptOss()`          | Together   | gpt-oss-120B                 | [\$0.15/\$0.60][7]       |
+| `fable5()`          | Anthropic  | claude-fable-5               | [\$10.00/\$50.00][2]     |
+| `opus5()`           | Anthropic  | claude-opus-5                | [\$5.00/\$25.00][2]      |
+| `opus48()`          | Anthropic  | claude-opus-4-8              | [\$5.00/\$25.00][2]      |
+| `opus47()`          | Anthropic  | claude-opus-4-7              | [\$5.00/\$25.00][2]      |
+| `opus46()`          | Anthropic  | claude-opus-4-6              | [\$5.00/\$25.00][2]      |
+| `sonnet5()`         | Anthropic  | claude-sonnet-5              | [\$3.00/\$15.00][2]      |
+| `sonnet46()`        | Anthropic  | claude-sonnet-4-6            | [\$3.00/\$15.00][2]      |
+| `haiku45()`         | Anthropic  | claude-haiku-4-5-20251001    | [\$1.00/\$5.00][2]       |
+| `gemini31pro()`     | Google     | gemini-3.1-pro-preview       | [\$2.00/\$12.00][3]      |
+| `gemini36flash()`    | Google     | gemini-3.6-flash              | [\$1.50/\$7.50][3]       |
+| `gemini35flash()`    | Google     | gemini-3.5-flash              | [\$0.75/\$4.50][3]       |
+| `gemini35flashLite()`| Google     | gemini-3.5-flash-lite          | [\$0.30/\$2.50][3]       |
+| `gemini31flashLite()`| Google     | gemini-3.1-flash-lite-preview | [\$0.25/\$1.50][3]       |
+| `grok45()`          | Grok       | grok-4.5                     | [\$2.00/\$6.00][6]       |
+| `grok43()`          | Grok       | grok-4.3                     | [\$1.25/\$2.50][6]       |
+| `grok420multiAgent()`| Grok      | grok-4.20-multi-agent-0309   | [\$1.25/\$2.50][6]       |
+| `grok420()`         | Grok       | grok-4.20-0309 (†)           | [\$1.25/\$2.50][6]       |
+| `qwen36plus()`      | Fireworks  | qwen3p6-plus                 | [\$0.50/\$3.00][10]      |
+| `qwen37plus()`      | Fireworks  | models/qwen3p7-plus          | [\$0.40/\$1.60][10]      |
+| `qwen38max()`       | OpenRouter | qwen/qwen3.8-max             | [\$2.00/\$6.00][12]      |
+| `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]      |
+| `minimaxM3()`       | MiniMax    | MiniMax-M3                   | [\$0.30/\$1.20][9]       |
+| `minimaxM27()`      | MiniMax    | MiniMax-M2.7                 | [\$0.30/\$1.20][9]       |
+| `sonar()`           | Perplexity | sonar                        | [\$1.00/\$1.00][4]       |
+| `sonarPro()`        | Perplexity | sonar-pro                    | [\$3.00/\$15.00][4]      |
+| `hermes3()`         | Lambda     | Hermes-3-Llama-3.1-405B-FP8  | [\$0.80/\$0.80][8]       |
+| `kimiK3()`          | Moonshot   | kimi-k3                      | [\$3.00/\$15.00][11]     |
+| `kimiK25()`         | Together   | Kimi-K2.5                    | [\$0.50/\$2.80][7]       |
+| `kimiK26()`         | Fireworks  | models/kimi-k2p6             | [\$0.95/\$4.00][10]      |
 
 [1]: https://platform.openai.com/docs/pricing "Pricing | OpenAI"
 [2]: https://docs.anthropic.com/en/docs/about-claude/pricing "Pricing - Anthropic"
@@ -226,11 +226,6 @@ Here's a comprehensive list of available methods:
 [12]: https://openrouter.ai/qwen/qwen3.8-max "OpenRouter Pricing"
 
 Each method accepts optional `options`, `config`, and (for multi-provider methods) `mix` parameters to customize behavior.  
-† `grok420()` resolves to `grok-4.20-0309-non-reasoning` by default, or `grok-4.20-0309-reasoning` when `.effort(20+)` / `-1` (or native non-`none` `reasoning_effort`) is set.  
-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 on Qwen 3.7 Plus, use `qwen37plus({ mix: { fireworks: false, openrouter: true } })`.
-For OpenRouter instead of Moonshot's native API, use `kimiK3({ mix: { moonshot: false, openrouter: true } })`.
 
 ```javascript
 const result = await ModelMix.new({ 
@@ -244,7 +239,9 @@ const result = await ModelMix.new({
 
 ## 🔄 Templates
 
-ModelMix includes a simple but powerful templating system. You can write your system prompts and user messages in external `.md` files with placeholders, then use `replace` to fill them in at runtime.
+ModelMix renders system prompts and user messages with [EJS](https://ejs.co/). Templates can be inline or stored in external files, and support variables, conditionals, loops, and relative includes.
+
+Templates are executable JavaScript and must be controlled by the developer. Pass untrusted content only as template data, never as the template source.
 
 ### Core methods
 
@@ -252,35 +249,42 @@ ModelMix includes a simple but powerful templating system. You can write your sy
 | --- | --- |
 | `setSystemFromFile(path)` | Load the system prompt from a file |
 | `addTextFromFile(path)` | Load a user message from a file |
-| `replace({ key: value })` | Replace placeholders in all messages and the system prompt |
-| `replaceKeyFromFile(key, path)` | Replace a placeholder with the contents of a file |
+| `assign({ key: value })` | Assign EJS template data |
+| `assignKey(key, value)` | Assign one EJS template-data value |
+| `assignKeyFromFile(key, path)` | Assign an EJS-rendered file to one template-data key |
 
-### Basic example with `replace`
+### Basic example with `assign`
 
 ```javascript
 const gpt = ModelMix.new().gpt52();
 
-gpt.addText('Write a short story about a {animal} that lives in {place}.');
-gpt.replace({ '{animal}': 'cat', '{place}': 'a haunted castle' });
+gpt.addText('Write a short story about a <%- animal %> that lives in <%- place %>.');
+gpt.assign({ animal: 'cat', place: 'a haunted castle' });
 
 console.log(await gpt.message());
 ```
 
+Use `assignKey()` when assigning a single value:
+
+```javascript
+gpt.assignKey('animal', 'cat');
+```
+
 ### Loading prompts from `.md` files
 
 Instead of writing long prompts inline, keep them in separate Markdown files. This makes them easier to read, edit, and version control.
 
 **`prompts/system.md`**
 ```markdown
-You are {role}, an expert in {topic}.
-Always respond in {language}.
+You are <%- role %>, an expert in <%- topic %>.
+Always respond in <%- language %>.
 ```
 
 **`prompts/task.md`**
 ```markdown
 Analyze the following and provide 3 key insights:
 
-{content}
+<%- content %>
 ```
 
 **`app.js`**
@@ -290,25 +294,48 @@ const gpt = ModelMix.new().gpt56luna();
 gpt.setSystemFromFile('./prompts/system.md');
 gpt.addTextFromFile('./prompts/task.md');
 
-gpt.replace({
-    '{role}': 'a senior analyst',
-    '{topic}': 'market trends',
-    '{language}': 'Spanish',
-    '{content}': 'Bitcoin surpassed $100,000 in December 2024...'
+gpt.assign({
+    role: 'a senior analyst',
+    topic: 'market trends',
+    language: 'Spanish',
+    content: 'Bitcoin surpassed $100,000 in December 2024...'
 });
 
 console.log(await gpt.message());
 ```
 
-### Injecting file contents into a placeholder
+### Simple includes
+
+Use EJS `include` to compose a prompt from other files. Include paths are resolved relative to the template containing them.
+
+```ejs
+<%- include('shared/rules.md') %>
+```
+
+For example:
+
+**`prompts/task.md`**
+```markdown
+Analyze the request following these rules:
+
+<%- include('shared/rules.md') %>
+```
+
+**`prompts/shared/rules.md`**
+```markdown
+- Be concise
+- Explain assumptions
+```
 
-Use `replaceKeyFromFile` when the replacement value itself is a large text stored in a file.
+### Dynamic includes
+
+When the file changes at runtime, pass its path as template data and call `include` with that variable. This replaces the file-injection use case while keeping composition inside the template.
 
 **`prompts/summarize.md`**
 ```markdown
 Summarize the following article in 3 bullet points:
 
-{article}
+<%- include(articleFile) %>
 ```
 
 **`app.js`**
@@ -316,28 +343,51 @@ Summarize the following article in 3 bullet points:
 const gpt = ModelMix.new().gpt5mini();
 
 gpt.addTextFromFile('./prompts/summarize.md');
-gpt.replaceKeyFromFile('{article}', './data/article.md');
+gpt.assign({ articleFile: '../data/article.md' });
+
+console.log(await gpt.message());
+```
+
+Static and dynamic include paths are resolved relative to the containing template. Included files are EJS template source, so both the path and file must be controlled by the developer. Pass untrusted runtime content through ordinary `assign()` values instead of using it as an include path.
+
+### Assigning a rendered file to a key
+
+Use `assignKeyFromFile()` when the outer template needs the rendered contents of a file as one data value:
+
+```javascript
+const gpt = ModelMix.new().gpt5mini();
+
+gpt.assign({ language: 'Spanish' });
+gpt.assignKeyFromFile('rules', './prompts/rules.md');
+gpt.addText('Follow these rules:\n<%- rules %>');
 
 console.log(await gpt.message());
 ```
 
+`assignKeyFromFile()` uses EJS `include` internally. The assigned file can access ordinary `assign()` data and use includes relative to its own path. It is rendered once per request and reused across the system prompt and messages in that request. The file is template source and must be developer-controlled.
+
 ### Full template workflow
 
 Combine all methods to build reusable, file-based prompt pipelines:
 
 **`prompts/system.md`**
 ```markdown
-You are {role}. Follow these rules:
+You are <%- role %>. Follow these rules:
+<%- include('partials/rules.md') %>
+- Respond in <%- language %>
+```
+
+**`prompts/partials/rules.md`**
+```markdown
 - Be concise
 - Use examples when possible
-- Respond in {language}
 ```
 
 **`prompts/review.md`**
 ```markdown
 Review the following code and suggest improvements:
 
-{code}
+<%- include('../src/utils.js') %>
 ```
 
 **`app.js`**
@@ -347,12 +397,79 @@ const gpt = ModelMix.new().gpt5mini();
 gpt.setSystemFromFile('./prompts/system.md');
 gpt.addTextFromFile('./prompts/review.md');
 
-gpt.replace({ '{role}': 'a senior code reviewer', '{language}': 'English' });
-gpt.replaceKeyFromFile('{code}', './src/utils.js');
+gpt.assign({ role: 'a senior code reviewer', language: 'English' });
 
 console.log(await gpt.message());
 ```
 
+### EJS output and control flow
+
+Use `<%- value %>` for raw prompt content and `<%= value %>` only when XML escaping is intentional. Missing variables and missing files throw immediately.
+
+```ejs
+<% if (user.active) { %>
+Review these roles:
+<% user.roles.forEach(role => { %>
+- <%- role %>
+<% }) %>
+<% } %>
+```
+
+### Random prompt choices
+
+Use a `choice` block to include exactly one prompt variant. When no weights are present, every option has the same probability:
+
+```ejs
+<% choice %>
+<% option %>
+Use emojis.
+<% option %>
+Use few emojis.
+<% option %>
+Do not use emojis.
+<% /choice %>
+```
+
+Add a positive weight after every `option` when the probabilities should differ:
+
+```ejs
+<% choice %>
+<% option 20 %>
+Use emojis.
+<% option 40 %>
+Use few emojis.
+<% option 40 %>
+Do not use emojis.
+<% /choice %>
+```
+
+Weights are relative and do not need to total 100. A block must either give every option a weight or omit all weights. Directives must be on their own lines; choices can be nested and can also appear inside relative includes. Each new request makes a new selection, while retries, provider fallbacks, and tool continuations keep the original selection.
+
+### Recursive includes
+
+An included template can include itself to render recursive data. Always define a 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 }) %>
+<% } %>
+<% } %>
+```
+
+```javascript
+const gpt = ModelMix.new().gpt5mini();
+
+gpt.addTextFromFile('./prompts/tree.ejs');
+gpt.assign({ node: promptTree, depth: 0, maxDepth: 10 });
+
+console.log(await gpt.message());
+```
+
+Content supplied through `assign()` remains data. EJS tags inside that content are not executed recursively; use `assignKeyFromFile()` only for developer-controlled EJS files that should be rendered.
+
 ## 🧩 JSON Structured Output
 
 The `json` method forces the model to return a structured JSON response. You define the shape with an example object and optionally describe each field.
@@ -541,12 +658,29 @@ Every response from `raw()` now includes a `tokens` object with the following st
 ```javascript
 {
   tokens: {
-    input: 150,    // Number of tokens in the prompt/input
-    output: 75,    // Number of tokens in the completion/output
-    total: 225,    // Total tokens used (input + output)
-    cached: 100,   // Cached input tokens reported by the provider (0 when absent)
-    cost: 0.0012,  // Estimated cost in USD (null if model not in pricing table)
-    speed: 42      // Output tokens per second (int)
+    input: 1200,          // Total input tokens, including cache reads and writes
+    output: 50,           // Number of output tokens
+    total: 1250,          // Total tokens used
+    cached: 1024,         // Input tokens read from cache
+    cacheWrite: 0,        // Input tokens written to cache
+    cacheWrite5m: 0,      // Anthropic writes using the 5-minute TTL
+    cacheWrite1h: 0,      // Anthropic writes using the 1-hour TTL
+    uncachedInput: 176,   // max(0, input - cached - cacheWrite)
+    cacheHitRate: 0.8533, // cached / input, rounded to 4 decimals
+    cacheSavings: 0.00018432, // USD saved by cache reads
+    cacheWritePremium: 0, // Extra USD paid to write this cache entry
+    breakEvenHits: 0,     // Full future hits needed to recover that premium
+    cost: 0.00011568,     // Total estimated cost in USD
+    costBreakdown: {
+      uncachedInput: 0.0000352,
+      cachedInput: 0.00002048,
+      cacheWrite: 0,
+      cacheWrite5m: 0,
+      cacheWrite1h: 0,
+      output: 0.00006,
+      total: 0.00011568
+    },
+    speed: 42             // Output tokens per second (int)
   }
 }
 ```
@@ -558,10 +692,66 @@ After calling `message()` or `json()`, use `lastRaw` to access the complete resp
 ```javascript
 const text = await model.message();
 console.log(model.lastRaw.tokens);
-// { input: 122, output: 86, total: 208, cached: 41, cost: 0.000319, speed: 38 }
+// Same normalized token and cost structure returned by raw()
+```
+
+`cached` aggregates cache reads reported by the provider, while `cacheWrite` aggregates cache writes. Anthropic additionally exposes `cacheWrite5m` and `cacheWrite1h` because those writes cost 1.25× and 2× the normal input rate, respectively. `cacheSavings` compares cache reads with the normal input rate, `cacheWritePremium` compares writes with that rate, and `breakEvenHits` estimates how many complete future hits recover the current write premium. For Anthropic, `input` is normalized to include uncached input, cache reads, and cache writes. Missing usage or pricing categories return `0`. The `speed` field is the generation speed measured in output tokens per second (integer).
+
+### GPT-5.6 prompt caching
+
+GPT-5.6 supports implicit or explicit caching through `prompt_cache_options`. Put the explicit breakpoint at the end of the stable prefix; the provider only caches prompts with at least 1,024 tokens.
+
+```javascript
+const model = ModelMix.new()
+  .gpt56luna({
+    options: {
+      prompt_cache_key: 'support-agent-v1',
+      prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+    }
+  })
+  .addText(longStableInstructions, {
+    cache: { breakpoint: true }
+  })
+  .addText('Answer this variable request.');
+
+const result = await model.raw();
+console.log(result.tokens.cached, result.tokens.cacheWrite, result.tokens.cost);
+```
+
+The provider-neutral `cache: { breakpoint: true }` option is accepted by `addTextFromFile()`, `addImage()`, `addImageFromUrl()`, and `addImageFromBuffer()`. Responses-native `input_text`, `input_image`, and `input_file` blocks preserve the native `prompt_cache_breakpoint` field when supplied directly through `options.messages`.
+
+GPT-5.6 uses `prompt_cache_options.ttl`; `prompt_cache_retention` remains available for earlier OpenAI models. ModelMix rejects the incompatible control instead of silently dropping it. For GPT-5.6 requests over 272K input tokens, the cost calculation applies the documented 2× input and 1.5× output multipliers to the complete request, including cache reads and writes.
+
+GPT-5.6 prices per 1M tokens:
+
+| Model | Input | Cached input | Cache write | Output |
+| --- | ---: | ---: | ---: | ---: |
+| `gpt-5.6-sol` | $5.00 | $0.50 | $6.25 | $30.00 |
+| `gpt-5.6-terra` | $2.00 | $0.20 | $2.50 | $12.00 |
+| `gpt-5.6-luna` | $0.20 | $0.02 | $0.25 | $1.20 |
+
+### Cross-provider cache fallback
+
+Neutral breakpoints are translated at the last moment by each provider adapter. Native request policies remain scoped to their model, so they cannot leak into a fallback request:
+
+```javascript
+const model = ModelMix.new()
+  .gpt56luna({
+    options: {
+      prompt_cache_key: 'support-agent-v1',
+      prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+    }
+  })
+  .haiku45({
+    options: {
+      cache_control: { type: 'ephemeral', ttl: '1h' }
+    }
+  })
+  .addText(longStableInstructions, { cache: { breakpoint: true } })
+  .addText('Answer this variable request.');
 ```
 
-The `cached` field is a single aggregated count of cached input tokens reported by the provider. The `cost` field is the estimated cost in USD based on the model's pricing per 1M tokens (input/output). If the model is not found in the pricing table, `cost` will be `null`. The `speed` field is the generation speed measured in output tokens per second (integer).
+GPT-5.6 receives `prompt_cache_breakpoint`; Anthropic receives `cache_control`; older OpenAI models and providers without an equivalent omit the marker. When a neutral explicit breakpoint is present for Anthropic, its model-scoped `cache_control` becomes that block's policy instead of adding an automatic breakpoint after the variable suffix.
 
 ## 🐛 Enabling Debug Mode
 
@@ -675,18 +865,19 @@ new ModelMix(args = { options: {}, config: {} })
 
 - `setSystem(text)`: Sets the system prompt.
 - `setSystemFromFile(filePath)`: Sets the system prompt from a file.
-- `addText(text, config = { role: "user" })`: Adds a text message.
-- `addTextFromFile(filePath, config = { role: "user" })`: Adds a text message from a file.
-- `addImage(filePath, config = { role: "user" })`: Adds an image message from a file path.
-- `addImageFromUrl(url, config = { role: "user" })`: Adds an image message from URL.
-- `replace(keyValues)`: Defines placeholder replacements for messages and system prompt.
-- `replaceKeyFromFile(key, filePath)`: Defines a placeholder replacement with file contents as value.
+- `addText(text, config = { role: "user", cache? })`: Adds a text message.
+- `addTextFromFile(filePath, config = { role: "user", cache? })`: Adds a text message from a file.
+- `addImage(filePath, config = { role: "user", cache? })`: Adds an image message from a file path.
+- `addImageFromUrl(url, config = { role: "user", cache? })`: Adds an image message from URL.
+- `assign(keyValues)`: Assigns EJS data for messages and system prompts.
+- `assignKey(key, value)`: Assigns one EJS data value.
+- `assignKeyFromFile(key, filePath)`: Renders an EJS file through `include` and assigns its output to one key.
 - `message()`: Sends the message and returns the response.
 - `raw()`: Sends the message and returns the complete response data including:
   - `message`: The text response from the model
   - `think`: Reasoning/thinking content (if available)
   - `toolCalls`: Array of tool calls made by the model (if any)
-  - `tokens`: Object with `input`, `output`, `total`, and `cached` token counts, plus `cost` (USD) and `speed` (output tokens/sec)
+  - `tokens`: Normalized token counts (`input`, `output`, `total`, `cached`, `cacheWrite`, `cacheWrite5m`, `cacheWrite1h`, `uncachedInput`, `cacheHitRate`), cache economics (`cacheSavings`, `cacheWritePremium`, `breakEvenHits`), plus `cost`, `costBreakdown` (USD), and `speed` (output tokens/sec)
   - `response`: The raw API response
 - `stream(callback)`: Sends the message and streams the response, invoking the callback with each streamed part.
 - `json(schemaExample, descriptions = {}, options = {})`: Forces the model to return a response in a specific JSON format.
@@ -829,4 +1020,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/demo/demo.js

@@ -6,7 +6,7 @@ const mmix = new ModelMix({
         temperature: 0.5,
     },
     config: {
-        system: 'You are {name} from Melmac.',
+        system: 'You are <%- name %> from Melmac.',
         max_history: 2,
         bottleneck: { maxConcurrent: 1 },
         debug: 3,
@@ -22,12 +22,12 @@ const pplxSettings = {
 };
 
 
-mmix.replace({ '{name}': 'ALF' });
+mmix.assign({ name: 'ALF' });
 
 console.log("\n" + '--------| gpt51() |--------');
 const gptArgs = { options: { reasoning_effort: "none", verbosity: "low" } };
-const gpt = mmix.gpt51(gptArgs).addText("Have you ever eaten a {animal}?");
-gpt.replace({ '{animal}': 'cat' });
+const gpt = mmix.gpt51(gptArgs).addText("Have you ever eaten a <%- animal %>?");
+gpt.assignKey('animal', 'cat');
 await gpt.json({ time: '24:00:00', message: 'Hello' }, { time: 'Time in format HH:MM:SS' });
 
 console.log("\n" + '--------| sonnet45() |--------');

package/demo/prompt.md

@@ -1,4 +1,4 @@
-# Writing Prompt: {story_title}
+# Writing Prompt: <%- storyTitle %>
 
 ## Setting
 A small, quiet town where nothing unusual ever happens.
@@ -22,4 +22,4 @@ Write a short story (500-1000 words) that explores:
 ### Additional Elements to Consider
 - The reactions of other townspeople
 - Any changes in the town's atmosphere after the package's arrival
-- Your character's internal conflict between curiosity and duty
+- Your character's internal conflict between curiosity and duty

package/http-client.js

@@ -4,6 +4,19 @@ function headersToObject(headers) {
     return Object.fromEntries(headers.entries());
 }
 
+function sanitizeUrl(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        parsed.search = '';
+        parsed.hash = '';
+        return parsed.toString();
+    } catch {
+        return String(url).replace(/[?#].*$/, '');
+    }
+}
+
 async function parseResponseBody(response) {
     try {
         return await response.json();
@@ -24,7 +37,7 @@ async function parseJsonBody(response) {
 
 async function buildHttpError(url, response) {
     const details = await parseResponseBody(response);
-    const error = new Error(`Request to ${url} failed with status code ${response.status}`);
+    const error = new Error(`Request to ${sanitizeUrl(url)} failed with status code ${response.status}`);
     error.isHttpError = true;
     error.statusCode = response.status;
     error.details = details;
@@ -64,7 +77,7 @@ async function fetchStreamResponse(url, { method = 'POST', headers = {}, body }
         throw await buildHttpError(url, response);
     }
     if (!response.body) {
-        throw new Error(`Request to ${url} did not return a readable stream`);
+        throw new Error(`Request to ${sanitizeUrl(url)} did not return a readable stream`);
     }
     return {
         data: Readable.fromWeb(response.body),