modelmix 4.7.2 → 5.0.0

package/README.md

@@ -163,53 +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]       |
-| `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"
@@ -225,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({ 
@@ -243,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
 
@@ -251,16 +249,16 @@ 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 |
+| `replace({ key: value })` | Add EJS template data |
+| `replaceKeyFromFile(key, path)` | Add a file's raw contents as template data |
 
 ### Basic example with `replace`
 
 ```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.replace({ animal: 'cat', place: 'a haunted castle' });
 
 console.log(await gpt.message());
 ```
@@ -271,15 +269,15 @@ Instead of writing long prompts inline, keep them in separate Markdown files. Th
 
 **`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,16 +288,16 @@ 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...'
+    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
+### Injecting file contents as template data
 
 Use `replaceKeyFromFile` when the replacement value itself is a large text stored in a file.
 
@@ -307,7 +305,7 @@ Use `replaceKeyFromFile` when the replacement value itself is a large text store
 ```markdown
 Summarize the following article in 3 bullet points:
 
-{article}
+<%- article %>
 ```
 
 **`app.js`**
@@ -315,7 +313,7 @@ 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.replaceKeyFromFile('article', './data/article.md');
 
 console.log(await gpt.message());
 ```
@@ -326,17 +324,17 @@ 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:
 - Be concise
 - Use examples when possible
-- Respond in {language}
+- Respond in <%- language %>
 ```
 
 **`prompts/review.md`**
 ```markdown
 Review the following code and suggest improvements:
 
-{code}
+<%- code %>
 ```
 
 **`app.js`**
@@ -346,12 +344,63 @@ 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.replace({ role: 'a senior code reviewer', language: 'English' });
+gpt.replaceKeyFromFile('code', './src/utils.js');
 
 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.
+
+File templates can include files relative to their own path:
+
+```ejs
+<%- include('shared/rules.md') %>
+```
+
+Content supplied through `replace()` or `replaceKeyFromFile()` is rendered once as data. EJS tags inside that content are not executed recursively.
+
 ## 🧩 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.
@@ -540,12 +589,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)
   }
 }
 ```
@@ -557,10 +623,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
 
@@ -674,18 +796,18 @@ 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.
+- `replace(keyValues)`: Adds EJS data for messages and system prompts.
+- `replaceKeyFromFile(key, filePath)`: Adds raw file contents as an EJS data value.
 - `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.
@@ -828,4 +950,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.replace({ 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.replace({ 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),