modelmix 5.0.0 → 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

@@ -249,20 +249,27 @@ Templates are executable JavaScript and must be controlled by the developer. Pas
 | --- | --- |
 | `setSystemFromFile(path)` | Load the system prompt from a file |
 | `addTextFromFile(path)` | Load a user message from a file |
-| `replace({ key: value })` | Add EJS template data |
-| `replaceKeyFromFile(key, path)` | Add a file's raw contents as template data |
+| `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.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.
@@ -287,7 +294,7 @@ const gpt = ModelMix.new().gpt56luna();
 gpt.setSystemFromFile('./prompts/system.md');
 gpt.addTextFromFile('./prompts/task.md');
 
-gpt.replace({
+gpt.assign({
     role: 'a senior analyst',
     topic: 'market trends',
     language: 'Spanish',
@@ -297,15 +304,38 @@ gpt.replace({
 console.log(await gpt.message());
 ```
 
-### Injecting file contents as template data
+### Simple includes
 
-Use `replaceKeyFromFile` when the replacement value itself is a large text stored in a file.
+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
+```
+
+### 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`**
@@ -313,11 +343,29 @@ 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:
@@ -325,16 +373,21 @@ Combine all methods to build reusable, file-based prompt pipelines:
 **`prompts/system.md`**
 ```markdown
 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`**
@@ -344,8 +397,7 @@ 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());
 ```
@@ -393,13 +445,30 @@ Do not use emojis.
 
 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:
+### Recursive includes
+
+An included template can include itself to render recursive data. Always define a stopping condition:
 
 ```ejs
-<%- include('shared/rules.md') %>
+<%- 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 `replace()` or `replaceKeyFromFile()` is rendered once as data. EJS tags inside that content are not executed recursively.
+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
 
@@ -800,8 +869,9 @@ new ModelMix(args = { options: {}, config: {} })
 - `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.
+- `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

package/demo/demo.js

@@ -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' });
+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/index.d.ts

@@ -70,7 +70,7 @@ export interface ModelMixConfig {
   roundRobin?: boolean;
   /** Unified effort (-1 adaptive, or 0–100). Not a native provider field. */
   effort?: EffortValue | null;
-  replace?: Record<string, unknown>;
+  templateData?: Record<string, unknown>;
   schema?: Record<string, unknown>;
   [key: string]: unknown;
 }
@@ -347,7 +347,8 @@ export declare class ModelMix {
   static hasToolInteraction(message: ChatMessage | null | undefined): boolean;
 
   new(setup?: ModelMixSetup): ModelMix;
-  replace(keyValues: Record<string, unknown>): this;
+  assign(keyValues: Record<string, unknown>): this;
+  assignKey(key: string, value: unknown): this;
   effort(value: EffortValue): this;
   attach(key: string, provider: MixCustom): this;
 
@@ -451,7 +452,7 @@ export declare class ModelMix {
   raw(): Promise<ModelMixResult>;
   stream(callback: StreamCallback): Promise<ModelMixResult>;
 
-  replaceKeyFromFile(key: string, filePath: string): this;
+  assignKeyFromFile(key: string, filePath: string): this;
   groupByRoles(messages: ChatMessage[]): ChatMessage[];
   prepareMessages(): Promise<void>;
   readFile(filePath: string, options?: { encoding?: BufferEncoding | null }): string | Buffer;

package/index.js

@@ -79,6 +79,15 @@ function validateTemplateData(value) {
     }
 }
 
+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}`;
 }
@@ -214,6 +223,7 @@ function createTemplateRenderContext(random = Math.random) {
 
     return {
         helpers: Object.freeze({ choice }),
+        renderedTemplateData: new Map(),
         renderedMessages: new Map(),
         renderedSystems: new Map()
     };
@@ -354,6 +364,7 @@ class ModelMix {
         this.toolClient = {};
         this.mcp = {};
         this.mcpToolsManager = new MCPToolsManager();
+        this.templateFileAssignments = new Map();
         this.messageTemplates = new WeakMap();
         this.lastRaw = null;
         this.options = {
@@ -387,8 +398,8 @@ class ModelMix {
             source: this.config.system,
             filename: null
         };
-        if (this.config.replace !== undefined) {
-            validateTemplateData(this.config.replace);
+        if (this.config.templateData !== undefined) {
+            validateTemplateData(this.config.templateData);
         }
         // Unified effort is ModelMix policy (config.effort / .effort()), not a native option.
         if (this.config.effort !== undefined && this.config.effort !== null) {
@@ -401,12 +412,20 @@ class ModelMix {
 
     }
 
-    replace(keyValues) {
+    assign(keyValues) {
         validateTemplateData(keyValues);
-        this.config.replace = { ...this.config.replace, ...keyValues };
+        for (const key of Object.keys(keyValues)) {
+            this.templateFileAssignments.delete(key);
+        }
+        this.config.templateData = { ...this.config.templateData, ...keyValues };
         return this;
     }
 
+    assignKey(key, value) {
+        validateTemplateDataKey(key);
+        return this.assign({ [key]: value });
+    }
+
     /**
      * Set unified reasoning effort: -1 (adaptive) or 0..100.
      * Stored in config.effort; mapped to provider-native fields at request time
@@ -431,6 +450,10 @@ class ModelMix {
         if (!hasSystemOverride) {
             instance.systemTemplate = { ...this.systemTemplate };
         }
+        instance.templateFileAssignments = new Map(this.templateFileAssignments);
+        for (const key of Object.keys(config.templateData || {})) {
+            instance.templateFileAssignments.delete(key);
+        }
         instance.models = this.models; // Share models array for round-robin rotation
         return instance;
     }
@@ -1217,27 +1240,71 @@ class ModelMix {
         return this.execute({ options: { stream: true } });
     }
 
-    replaceKeyFromFile(key, filePath) {
-        const content = this.readFile(filePath);
-        return this.replace({ [key]: content });
+    assignKeyFromFile(key, filePath) {
+        validateTemplateDataKey(key);
+        this.readFile(filePath);
+
+        const templateData = { ...this.config.templateData };
+        delete templateData[key];
+        this.config.templateData = templateData;
+        this.templateFileAssignments.set(key, Object.freeze({
+            key,
+            filename: path.resolve(filePath)
+        }));
+        return this;
     }
 
     _choiceRandom() {
         return Math.random();
     }
 
+    _templateData(renderContext) {
+        const assigned = { ...(this.config.templateData || {}), $mix: renderContext.helpers };
+        const data = { ...assigned };
+
+        for (const [key, assignment] of this.templateFileAssignments) {
+            data[key] = this._renderAssignedTemplate(assignment, assigned, renderContext);
+        }
+
+        return data;
+    }
+
+    _renderAssignedTemplate(assignment, data, renderContext) {
+        if (renderContext.renderedTemplateData.has(assignment)) {
+            return renderContext.renderedTemplateData.get(assignment);
+        }
+
+        const rendered = this._renderTemplateWithData(
+            `<%- include(${JSON.stringify(assignment.filename)}) %>`,
+            {
+                filename: assignment.filename,
+                label: `template data "${assignment.key}"`
+            },
+            data
+        );
+        renderContext.renderedTemplateData.set(assignment, rendered);
+        return rendered;
+    }
+
     _renderTemplate(
         source,
         { filename = null, label = 'template' } = {},
         renderContext = createTemplateRenderContext(() => this._choiceRandom())
     ) {
+        return this._renderTemplateWithData(
+            source,
+            { filename, label },
+            this._templateData(renderContext)
+        );
+    }
+
+    _renderTemplateWithData(source, { filename = null, label = 'template' }, data) {
         if (typeof source !== 'string') {
             throw new TypeError(`${label} source must be a string.`);
         }
 
         try {
             const template = preprocessChoiceDirectives(source, { filename, label });
-            const data = { ...(this.config.replace || {}), $mix: renderContext.helpers };
             return ejs.render(template, data, {
                 ...(filename && { filename }),
                 async: false,

package/package.json

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

package/skills/modelmix/SKILL.md

@@ -365,15 +365,47 @@ All image methods accept an optional second argument `{ role }` (default `"user"
 const model = ModelMix.new().gpt5mini();
 model.setSystemFromFile('./prompts/system.md');
 model.addTextFromFile('./prompts/task.md');
-model.replace({
+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 `replace()` data. Relative includes work in templates loaded from files.
+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:
 
@@ -540,8 +572,9 @@ const model = ModelMix.new({
 | `.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 |
-| `.replace({})` | `this` | Add EJS template data |
-| `.replaceKeyFromFile(key, path)` | `this` | Add raw file content as EJS template data |
+| `.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/fixtures/dynamic-include.txt

@@ -0,0 +1,2 @@
+Rules:
+<%- include(rulesFile) %>

package/test/fixtures/tree.ejs

@@ -0,0 +1,6 @@
+<%- node.text %>
+<% if (node.children?.length && depth < maxDepth) { %>
+<% for (const child of node.children) { %>
+<%- include('tree.ejs', { node: child, depth: depth + 1, maxDepth }) %>
+<% } %>
+<% } %>

package/test/templates.test.js

@@ -1,6 +1,8 @@
 const { expect } = require('chai');
 const sinon = require('sinon');
 const nock = require('nock');
+const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { ModelMix } = require('../index.js');
 
@@ -37,7 +39,7 @@ describe('EJS Template and File Operations Tests', () => {
         it('renders inline variables with plain data keys', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replace({ name: 'Alice', age: 30, city: 'New York' })
+                .assign({ name: 'Alice', age: 30, city: 'New York' })
                 .addText('Hello <%- name %>, you are <%- age %> years old and live in <%- city %>.');
 
             mockOpenAI(body => {
@@ -49,10 +51,23 @@ describe('EJS Template and File Operations Tests', () => {
             await model.message();
         });
 
+        it('assigns one template data key', async () => {
+            const model = ModelMix.new()
+                .gpt51()
+                .assignKey('name', 'Martin')
+                .addText('Hello <%- name %>.');
+
+            mockOpenAI(body => {
+                expect(userTexts(body)).to.deep.equal(['Hello Martin.']);
+            });
+
+            await model.message();
+        });
+
         it('supports nested data, conditionals, and loops', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replace({
+                .assign({
                     user: {
                         name: 'Charlie',
                         active: true,
@@ -72,7 +87,7 @@ describe('EJS Template and File Operations Tests', () => {
             const value = 'Hello & "World" <test>';
             const model = ModelMix.new()
                 .gpt51()
-                .replace({ value })
+                .assign({ value })
                 .addText('Escaped: <%= value %>\nRaw: <%- value %>');
 
             mockOpenAI(body => {
@@ -87,7 +102,7 @@ describe('EJS Template and File Operations Tests', () => {
         it('does not execute EJS received through template data', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replace({ payload: '<%- secret %>', secret: 'must-not-render' })
+                .assign({ payload: '<%- secret %>', secret: 'must-not-render' })
                 .addText('Payload: <%- payload %>');
 
             mockOpenAI(body => {
@@ -120,7 +135,7 @@ Do not use emojis.
         it('selects weighted options using relative weights', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replace({ language: 'Spanish' })
+                .assign({ language: 'Spanish' })
                 .addText(`<% choice %>
 <% option 20 %>
 Use emojis in <%- language %>.
@@ -194,7 +209,7 @@ second
         it('fails before the request when a variable is missing', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replace({ name: 'David' })
+                .assign({ name: 'David' })
                 .addText('Hello <%- name %>, status: <%- status %>');
 
             let error;
@@ -212,14 +227,22 @@ second
         it('rejects invalid template data immediately', () => {
             const model = ModelMix.new().gpt51();
 
-            expect(() => model.replace(null)).to.throw(TypeError, 'Template data must be a plain non-null object.');
-            expect(() => model.replace(undefined)).to.throw(TypeError, 'Template data must be a plain non-null object.');
-            expect(() => model.replace([])).to.throw(TypeError, 'Template data must be a plain non-null object.');
-            expect(() => ModelMix.new({ config: { replace: null } })).to.throw(
+            expect(() => model.assign(null)).to.throw(TypeError, 'Template data must be a plain non-null object.');
+            expect(() => model.assign(undefined)).to.throw(TypeError, 'Template data must be a plain non-null object.');
+            expect(() => model.assign([])).to.throw(TypeError, 'Template data must be a plain non-null object.');
+            expect(() => ModelMix.new({ config: { templateData: null } })).to.throw(
                 TypeError,
                 'Template data must be a plain non-null object.'
             );
-            expect(() => model.replace({ $mix: 'reserved' })).to.throw(
+            expect(() => model.assign({ $mix: 'reserved' })).to.throw(
+                TypeError,
+                'Template data key "$mix" is reserved.'
+            );
+            expect(() => model.assignKey('', 'value')).to.throw(
+                TypeError,
+                'Template data key must be a non-empty string.'
+            );
+            expect(() => model.assignKey('$mix', 'value')).to.throw(
                 TypeError,
                 'Template data key "$mix" is reserved.'
             );
@@ -291,7 +314,7 @@ B
             expect(error).to.be.instanceOf(Error);
             expect(model.messages[0].content[0].text).to.include('<% choice %>');
 
-            model.replace({ missing: 'ready' });
+            model.assign({ missing: 'ready' });
             mockOpenAI(body => {
                 const text = userTexts(body).join('\n').trim();
                 expect(text).to.include('B');
@@ -374,7 +397,7 @@ B
         it('renders a file template with a relative include', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replace({
+                .assign({
                     name: 'Eve',
                     platform: 'ModelMix',
                     username: 'eve_user',
@@ -398,6 +421,19 @@ B
             await model.message();
         });
 
+        it('resolves a dynamic include path relative to its template', async () => {
+            const model = ModelMix.new()
+                .gpt51()
+                .assign({ rulesFile: 'system-rules.txt', language: 'Spanish' })
+                .addTextFromFile(path.join(fixturesPath, 'dynamic-include.txt'));
+
+            mockOpenAI(body => {
+                expect(userTexts(body)[0].trim()).to.equal('Rules:\nAlways respond in Spanish.');
+            });
+
+            await model.message();
+        });
+
         it('processes choice directives inside relative includes', async () => {
             const model = ModelMix.new()
                 .gpt51()
@@ -411,10 +447,40 @@ B
             await model.message();
         });
 
+        it('supports recursive includes with an explicit depth limit', async () => {
+            const model = ModelMix.new()
+                .gpt51()
+                .assign({
+                    node: {
+                        text: 'Root',
+                        children: [{
+                            text: 'Child',
+                            children: [{
+                                text: 'Grandchild',
+                                children: [{ text: 'Too deep', children: [] }]
+                            }]
+                        }]
+                    },
+                    depth: 0,
+                    maxDepth: 2
+                })
+                .addTextFromFile(path.join(fixturesPath, 'tree.ejs'));
+
+            mockOpenAI(body => {
+                const content = userTexts(body)[0];
+                expect(content).to.include('Root');
+                expect(content).to.include('Child');
+                expect(content).to.include('Grandchild');
+                expect(content).to.not.include('Too deep');
+            });
+
+            await model.message();
+        });
+
         it('preserves a system template filename through new instances', async () => {
             const base = ModelMix.new()
                 .setSystemFromFile(path.join(fixturesPath, 'system-template.txt'))
-                .replace({ role: 'data analyst', language: 'Spanish' });
+                .assign({ role: 'data analyst', language: 'Spanish' });
             const model = base.new().gpt51().addText('Analyze this.');
 
             mockOpenAI(body => {
@@ -426,26 +492,75 @@ B
             await model.message();
         });
 
-        it('injects file contents as raw data without recursively rendering them', async () => {
+        it('renders assigned files through EJS includes, including their relative includes', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replaceKeyFromFile('templateSource', path.join(fixturesPath, 'template.txt'))
-                .replace({ name: 'must-not-render' })
+                .assign({
+                    name: 'Eve',
+                    platform: 'ModelMix',
+                    username: 'eve_user',
+                    role: 'developer',
+                    createdDate: '2026-08-07',
+                    website: 'https://modelmix.dev',
+                    company: 'AI Solutions',
+                    showAccount: true
+                })
+                .assignKeyFromFile('templateSource', path.join(fixturesPath, 'template.txt'))
                 .addText('Source:\n<%- templateSource %>');
 
             mockOpenAI(body => {
                 const content = userTexts(body)[0];
-                expect(content).to.include('Hello <%- name %>, welcome to <%- platform %>!');
-                expect(content).to.not.include('Hello must-not-render');
+                expect(content).to.include('Hello Eve, welcome to ModelMix!');
+                expect(content).to.include('Username: eve_user');
+                expect(content).to.include('The AI Solutions Team');
+                expect(content).to.not.include('<%-');
+            });
+
+            await model.message();
+        });
+
+        it('inherits assigned files through new instances', async () => {
+            const base = ModelMix.new()
+                .assign({ language: 'Spanish' })
+                .assignKeyFromFile('rules', path.join(fixturesPath, 'system-rules.txt'));
+            const model = base.new().gpt51().addText('Rules:\n<%- rules %>');
+
+            mockOpenAI(body => {
+                expect(userTexts(body)[0].trim()).to.equal('Rules:\nAlways respond in Spanish.');
             });
 
             await model.message();
         });
 
+        it('uses the latest assignment when a plain value and a file share a key', async () => {
+            const plainValue = ModelMix.new()
+                .gpt51()
+                .assign({ language: 'Spanish' })
+                .assignKeyFromFile('rules', path.join(fixturesPath, 'system-rules.txt'))
+                .assignKey('rules', 'Use the plain value.')
+                .addText('<%- rules %>');
+
+            mockOpenAI(body => {
+                expect(userTexts(body)).to.deep.equal(['Use the plain value.']);
+            }, 'Plain response');
+            await plainValue.message();
+
+            const fileValue = ModelMix.new()
+                .gpt51()
+                .assign({ language: 'Spanish', rules: 'Ignore this value.' })
+                .assignKeyFromFile('rules', path.join(fixturesPath, 'system-rules.txt'))
+                .addText('<%- rules %>');
+
+            mockOpenAI(body => {
+                expect(userTexts(body)[0].trim()).to.equal('Always respond in Spanish.');
+            }, 'File response');
+            await fileValue.message();
+        });
+
         it('injects JSON file contents without XML escaping', async () => {
             const model = ModelMix.new()
                 .gpt51()
-                .replaceKeyFromFile('data', path.join(fixturesPath, 'data.json'))
+                .assignKeyFromFile('data', path.join(fixturesPath, 'data.json'))
                 .addText('Process this data:\n<%- data %>');
 
             mockOpenAI(body => {
@@ -458,12 +573,48 @@ B
             await model.message();
         });
 
+        it('reloads an assigned file for each request', async () => {
+            const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'modelmix-template-'));
+            const assignedFile = path.join(temporaryDirectory, 'assigned.ejs');
+
+            try {
+                fs.writeFileSync(assignedFile, 'Version one for <%- name %>.');
+                const model = ModelMix.new()
+                    .gpt51()
+                    .assign({ name: 'Eve' })
+                    .assignKeyFromFile('content', assignedFile)
+                    .addText('<%- content %>');
+
+                mockOpenAI(body => {
+                    expect(userTexts(body)).to.deep.equal(['Version one for Eve.']);
+                }, 'First response');
+                await model.message();
+
+                fs.writeFileSync(assignedFile, 'Version two for <%- name %>.');
+                model.assign({ name: 'Ada' }).addText('<%- content %>');
+                mockOpenAI(body => {
+                    expect(userTexts(body)).to.deep.equal(['Version two for Ada.']);
+                }, 'Second response');
+                await model.message();
+            } finally {
+                fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+            }
+        });
+
         it('throws immediately when a template or data file is missing', () => {
             const model = ModelMix.new().gpt51();
             const missingPath = path.join(fixturesPath, 'nonexistent.txt');
 
             expect(() => model.addTextFromFile(missingPath)).to.throw(`File not found: ${missingPath}`);
-            expect(() => model.replaceKeyFromFile('missing', missingPath)).to.throw(`File not found: ${missingPath}`);
+            expect(() => model.assignKeyFromFile('missing', missingPath)).to.throw(`File not found: ${missingPath}`);
+            expect(() => model.assignKeyFromFile('', missingPath)).to.throw(
+                TypeError,
+                'Template data key must be a non-empty string.'
+            );
+            expect(() => model.assignKeyFromFile('$mix', missingPath)).to.throw(
+                TypeError,
+                'Template data key "$mix" is reserved.'
+            );
         });
     });
 
@@ -473,8 +624,8 @@ B
             const model = ModelMix.new()
                 .gpt51()
                 .setSystem('You are a <%- role %>.')
-                .replace({ role: 'data analyst', instruction: 'Count active users' })
-                .replaceKeyFromFile('data', path.join(fixturesPath, 'data.json'))
+                .assign({ role: 'data analyst', instruction: 'Count active users' })
+                .assignKeyFromFile('data', path.join(fixturesPath, 'data.json'))
                 .addText('<%- instruction %> from this data: <%- data %>');
 
             nock('https://api.openai.com')
@@ -504,7 +655,7 @@ B
             const model = ModelMix.new()
                 .gpt51()
                 .setSystem('Act as <%- role %>.')
-                .replace({ role: 'reviewer' })
+                .assign({ role: 'reviewer' })
                 .addText('Review this.');
 
             mockOpenAI(body => {
@@ -520,7 +671,7 @@ B
         it('keeps rendered history snapshots when template data changes', async () => {
             const model = ModelMix.new({ config: { max_history: 10 } })
                 .gpt51()
-                .replace({ name: 'Alice' })
+                .assign({ name: 'Alice' })
                 .addText('Hello <%- name %>.');
 
             mockOpenAI(body => {
@@ -528,7 +679,7 @@ B
             }, 'First response');
             await model.message();
 
-            model.replace({ name: 'Bob' }).addText('Hello <%- name %>.');
+            model.assign({ name: 'Bob' }).addText('Hello <%- name %>.');
             mockOpenAI(body => {
                 expect(userTexts(body)).to.deep.equal(['Hello Alice.', 'Hello Bob.']);
             }, 'Second response');