modelmix 5.0.4 → 5.0.5

package/README.md

@@ -4,6 +4,25 @@
 
 Ever found yourself wanting to integrate AI models into your projects but worried about reliability? ModelMix helps you build resilient AI applications by chaining multiple models together. If one model fails, it automatically switches to the next one, ensuring your application keeps running smoothly.
 
+## 📑 Table of Contents
+
+- [Features](#-features)
+- [Usage](#-usage)
+- [Shorthand Methods](#-shorthand-methods)
+- [Unified Effort Scale](#-unified-effort-scale)
+- [Templates](#-templates)
+- [JSON Structured Output](#-json-structured-output)
+- [Token Usage Tracking](#-token-usage-tracking)
+- [Prompt Caching](#-prompt-caching)
+- [Model Context Protocol (MCP) Integration](#-model-context-protocol-mcp-integration)
+- [Enabling Debug Mode](#-enabling-debug-mode)
+- [Bottleneck Integration](#-bottleneck-integration)
+- [Retry (Opt-In)](#-retry-optin)
+- [Instance Plugins](#-instance-plugins)
+- [ModelMix Class Overview](#-modelmix-class-overview)
+- [Contributing](#-contributing)
+- [License](#-license)
+
 ## ✨ Features
 
 - **Unified Interface**: Interact with multiple AI models through a single, coherent API.
@@ -76,6 +95,19 @@ const model = await ModelMix.new(setup)
 console.log(await model.message());
 ```
 
+The same ordered chain can be attached by passing model shortcuts directly to
+`chain()`. Add `@effort` to override unified effort for one model; entries
+without it inherit the chain effort, or use the provider default when the chain
+has no configured effort:
+
+```javascript
+const model = ModelMix.new(setup)
+    .chain('sonnet5', 'gpt56luna@20', 'gemini37flash@-1')
+    .addText("What's your name?");
+
+console.log(await model.message());
+```
+
 **Use Perplexity to get the price of ETH**
 ```javascript
 const ETH = ModelMix.new()
@@ -101,159 +133,6 @@ This pattern allows you to:
 - Track token usage across all providers
 - Keep your code clean and maintainable
 
-## 🔌 Instance Plugins
-
-Plugins wrap one ModelMix instance without changing global behavior. They run in registration order after templates are rendered and before provider-specific request conversion:
-
-```javascript
-const metrics = {
-    name: 'metrics',
-    async execute(context, next) {
-        const startedAt = Date.now();
-        const result = await next();
-        return { ...result, elapsedMs: Date.now() - startedAt };
-    }
-};
-
-const model = ModelMix.new()
-    .gpt56luna()
-    .use(metrics)
-    .addText('Summarize this request.');
-```
-
-A plugin may edit `context.request`, call `next()`, or return a complete ModelMix result itself. It can also create history-free child executions with `context.invoke()` and choose plugin inheritance:
-
-```javascript
-const child = await context.invoke({
-    systemFile: './prompts/extract-entities.md',
-    assign: { outputLanguage: 'Spanish' },
-    messages: [{ role: 'user', content: section }],
-    plugins: { exclude: ['recursive-plugin'] },
-    history: false
-});
-```
-
-Supported policies are `'inherit'`, `'none'`, `{ include: [...] }`, and `{ exclude: [...] }`. Child metadata exposes `executionId`, `parentExecutionId`, and `depth` to middleware. `.new()` inherits registered plugins but not message history.
-
-Child `systemFile` templates use the same EJS engine, `assign()` data contract, and relative Markdown includes as ordinary ModelMix templates. Use either `system` or `systemFile`, not both.
-
-### Recursive Language Model plugin
-
-The separately publishable `@modelmix/rlm` workspace package keeps document parsing, planner prompts, and `isolated-vm` out of the core `modelmix` dependency tree. It requires Node.js 22 or newer.
-
-```javascript
-const { ModelMix } = require('modelmix');
-const { rlm } = require('@modelmix/rlm');
-
-const fast = ModelMix.new().gpt41mini();
-
-const result = await ModelMix.new()
-    .gpt56luna()
-    .use(rlm({
-        maxDepth: 2,
-        documents: {
-            book: {
-                format: 'markdown',
-                content: markdownBook
-            }
-        },
-        workers: {
-            fast: {
-                model: fast,
-                intelligence: 2,
-                cost: 1,
-                speed: 4,
-                description: 'Translation, extraction, and simple transformations'
-            }
-        },
-        limits: {
-            maxQueryBytes: 64 * 1024,
-            sandboxMemoryBytes: 64 * 1024 * 1024,
-            maxConcurrentQueries: 4,
-            maxCalls: 100,
-            maxOutputBytes: 8 * 1024 * 1024,
-            maxGeneratedTokens: 100000,
-            maxWallTimeMs: 120000
-        }
-    }))
-    .addText('Translate this book to neutral Latin American Spanish.')
-    .message();
-```
-
-Markdown headings become stable nested sections, lists expose item arrays, and the original source order remains reconstructable. The planner receives only a content-free variable manifest: paths, types, array item counts, serialized UTF-8 byte estimates, string lengths, line and paragraph counts, structural summaries, and partition hints. The document values enter only the isolated sandbox, where generated JavaScript can inspect `variables` and call registered workers through `query()`.
-
-A worker normally supplies `model: anotherModelMixInstance`. To offer the current parent chain under a name, register it with `useParent: true` instead; defining both is rejected.
-
-Planner instructions live in Markdown templates under `plugins/rlm/prompts/`. The plugin supplies manifests and limits through ModelMix `assign()` and loads the system prompt through `systemFile`, so relative includes work and runtime values are rendered exactly once.
-
-## 🎛️ Unified Effort Scale
-
-Control reasoning depth with one ModelMix policy value (`-1` adaptive, or `0`–`100`). It lives **outside** native `options` and is mapped to each provider’s effort API at request time.
-
-```javascript
-// In config (ModelMix.new or per-model shorthand)
-ModelMix.new({ config: { effort: 50 } }).opus5().addText('...').message();
-ModelMix.new().deepseekV4Flash({ config: { effort: 100 } }).addText('...').message();
-
-// Fluent
-ModelMix.new().effort(-1).minimaxM3().addText('...').message();
-```
-
-**Native wins:** if you already set a provider-native field (`reasoning_effort`, `output_config.effort`, `thinkingConfig`, etc.), unified `effort` is ignored for that request.
-
-| | 0–19 | 20–39 | 40–59 | 60–79 | 80–100 | `-1` |
-|--|------|-------|-------|-------|--------|------|
-| OpenAI | `none` | `low` | `medium` | `high` | `xhigh` | — |
-| Anthropic | `low` | `medium` | `high` | `xhigh` | `max` | adaptive |
-| Gemini 3+ | `minimal` | `low` | `medium` | `high` | — | dynamic |
-| DeepSeek V4 | off | `low`↑ | `high`↑ | `high`↑ | `max`↑ | — |
-| MiniMax M3 | off | adaptive | adaptive | adaptive | adaptive | adaptive |
-
-### Provider-specific behavior
-
-- **Gemini:** Gemini 3+ uses bands 0–24 / 25–49 / 50–74 / 75–100. Gemini 3.7 Flash clamps these bands to `low` / `low` / `medium` / `high`; `-1` leaves its native `medium` default unchanged. Gemini 2.5 maps 0–100 to `thinkingBudget`.
-- **DeepSeek:** `↑` means thinking is enabled; `off` means it is disabled.
-- **MiniMax:** `off` maps to `thinking.disabled`; `adaptive` maps to `thinking.type=adaptive`.
-- **Anthropic:** Claude 5, Fable, Opus 4.6+, and Sonnet 4.6+ use adaptive thinking with `output_config.effort`. Sonnet 4.5 and Haiku 4.5 use `thinking.type=enabled` with `budget_tokens`.
-- **Grok 4.6:** 0–39 / 40–59 / 60–79 / 80–100 map to `low` / `medium` / `high` / `xhigh`. Without effort, Grok uses its native `high` default.
-
-`-1` uses the provider's adaptive or dynamic mode when available; otherwise it is a no-op. Effort levels are clamped to each model's supported range.
-
-### Migrating from thinking shorthands
-
-The former `*think()` methods were removed. Use `.effort(n).<model>()` with `0`–`100` or `-1` instead.
-
-- **Kimi:** use `kimiK25()` or `kimiK26()`.
-- **Grok 4.20:** `.grok420()` selects the non-reasoning model. Use `.effort(20+).grok420()` or `.effort(-1).grok420()` to select the reasoning model.
-
-## 🔧 Model Context Protocol (MCP) Integration
-
-ModelMix makes it incredibly easy to enhance your AI models with powerful capabilities through the Model Context Protocol. With just a few lines of code, you can add features like web search, code execution, or any custom functionality to your models.
-
-### Example: Adding Web Search Capability
-
-Include the API key for Brave Search in your .env file.
-```
-BRAVE_API_KEY="BSA0..._fm"
-```
-
-```javascript
-const mmix = ModelMix.new({ config: { max_history: 10 } }).gpt56sol();
-mmix.setSystem('You are an assistant and today is ' + new Date().toISOString());
-
-// Add web search capability through MCP
-await mmix.addMCP('@modelcontextprotocol/server-brave-search');
-mmix.addText('Use Internet: When did the last Christian pope die?');
-console.log(await mmix.message());
-```
-
-This simple integration allows your model to:
-- Search the web in real-time
-- Access up-to-date information
-- Combine AI reasoning with external data
-
-The Model Context Protocol makes it easy to add any capability to your models, from web search to code execution, database queries, or custom functions. All with just a few lines of code!
-
 ## ⚡️ Shorthand Methods
 
 ModelMix provides convenient shorthand methods for quickly accessing different AI models.
@@ -339,6 +218,46 @@ const result = await ModelMix.new({
     .message();
 ```
 
+## 🎛️ Unified Effort Scale
+
+Control reasoning depth with one ModelMix policy value (`-1` adaptive, or `0`–`100`). It lives **outside** native `options` and is mapped to each provider’s effort API at request time.
+
+```javascript
+// In config (ModelMix.new or per-model shorthand)
+ModelMix.new({ config: { effort: 50 } }).opus5().addText('...').message();
+ModelMix.new().deepseekV4Flash({ config: { effort: 100 } }).addText('...').message();
+
+// Fluent
+ModelMix.new().effort(-1).minimaxM3().addText('...').message();
+```
+
+**Native wins:** if you already set a provider-native field (`reasoning_effort`, `output_config.effort`, `thinkingConfig`, etc.), unified `effort` is ignored for that request.
+
+| | 0–19 | 20–39 | 40–59 | 60–79 | 80–100 | `-1` |
+|--|------|-------|-------|-------|--------|------|
+| OpenAI | `none` | `low` | `medium` | `high` | `xhigh` | — |
+| Anthropic | `low` | `medium` | `high` | `xhigh` | `max` | adaptive |
+| Gemini 3+ | `minimal` | `low` | `medium` | `high` | — | dynamic |
+| DeepSeek V4 | off | `low`↑ | `high`↑ | `high`↑ | `max`↑ | — |
+| MiniMax M3 | off | adaptive | adaptive | adaptive | adaptive | adaptive |
+
+### Provider-specific behavior
+
+- **Gemini:** Gemini 3+ uses bands 0–24 / 25–49 / 50–74 / 75–100. Gemini 3.7 Flash clamps these bands to `low` / `low` / `medium` / `high`; `-1` leaves its native `medium` default unchanged. Gemini 2.5 maps 0–100 to `thinkingBudget`.
+- **DeepSeek:** `↑` means thinking is enabled; `off` means it is disabled.
+- **MiniMax:** `off` maps to `thinking.disabled`; `adaptive` maps to `thinking.type=adaptive`.
+- **Anthropic:** Claude 5, Fable, Opus 4.6+, and Sonnet 4.6+ use adaptive thinking with `output_config.effort`. Sonnet 4.5 and Haiku 4.5 use `thinking.type=enabled` with `budget_tokens`.
+- **Grok 4.6:** 0–39 / 40–59 / 60–79 / 80–100 map to `low` / `medium` / `high` / `xhigh`. Without effort, Grok uses its native `high` default.
+
+`-1` uses the provider's adaptive or dynamic mode when available; otherwise it is a no-op. Effort levels are clamped to each model's supported range.
+
+### Migrating from thinking shorthands
+
+The former `*think()` methods were removed. Use `.effort(n).<model>()` with `0`–`100` or `-1` instead.
+
+- **Kimi:** use `kimiK25()` or `kimiK26()`.
+- **Grok 4.20:** `.grok420()` selects the non-reasoning model. Use `.effort(20+).grok420()` or `.effort(-1).grok420()` to select the reasoning model.
+
 ## 🔄 Templates
 
 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.
@@ -800,6 +719,39 @@ console.log(model.lastRaw.tokens);
 
 `thinking` contains internal reasoning tokens when a provider reports them separately; cost calculation bills them at the output rate. `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).
 
+## 🧠 Prompt Caching
+
+Prompt caching reuses the stable beginning of a prompt at the provider level. It does not cache the answer: every call still generates a new response.
+
+For GPT-5.6, keep the long, reusable instructions first, mark the end of that stable prefix, and add the changing request afterward:
+
+```javascript
+async function ask(question) {
+    const model = ModelMix.new()
+        .gpt56luna({
+            options: {
+                prompt_cache_key: 'support-rules-v1',
+                prompt_cache_options: { mode: 'explicit', ttl: '30m' }
+            }
+        })
+        .addTextFromFile('./prompts/support.md', {
+            role: 'developer',
+            cache: { breakpoint: true }
+        })
+        .addText(question);
+
+    const answer = await model.message();
+    const { cached, cacheWrite, cacheHitRate } = model.lastRaw.tokens;
+    console.log({ cached, cacheWrite, cacheHitRate });
+    return answer;
+}
+
+await ask('Summarize support ticket 123.');
+await ask('Summarize support ticket 456.');
+```
+
+The contents of `support.md` and the cache key stay the same between calls; only the final question changes. The first request may report `cacheWrite > 0`, while later requests confirm reuse with `cached > 0`. For GPT-5.6, the stable prefix must contain at least 1,024 tokens. Keep all variable content after the breakpoint, and change `prompt_cache_key` when the stable instructions change.
+
 ### 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.
@@ -856,6 +808,34 @@ const model = ModelMix.new()
 
 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.
 
+## 🔧 Model Context Protocol (MCP) Integration
+
+ModelMix makes it incredibly easy to enhance your AI models with powerful capabilities through the Model Context Protocol. With just a few lines of code, you can add features like web search, code execution, or any custom functionality to your models.
+
+### Example: Adding Web Search Capability
+
+Include the API key for Brave Search in your .env file.
+```
+BRAVE_API_KEY="BSA0..._fm"
+```
+
+```javascript
+const mmix = ModelMix.new({ config: { max_history: 10 } }).gpt56sol();
+mmix.setSystem('You are an assistant and today is ' + new Date().toISOString());
+
+// Add web search capability through MCP
+await mmix.addMCP('@modelcontextprotocol/server-brave-search');
+mmix.addText('Use Internet: When did the last Christian pope die?');
+console.log(await mmix.message());
+```
+
+This simple integration allows your model to:
+- Search the web in real-time
+- Access up-to-date information
+- Combine AI reasoning with external data
+
+The Model Context Protocol makes it easy to add any capability to your models, from web search to code execution, database queries, or custom functions. All with just a few lines of code!
+
 ## 🐛 Enabling Debug Mode
 
 To activate debug mode in ModelMix and view detailed request information, follow these two steps:
@@ -929,6 +909,91 @@ Behavior summary:
 - If retry is enabled, ModelMix retries the same model only for configured transient status codes.
 - After retries are exhausted (or for non-retryable errors), ModelMix continues with normal fallback chain.
 
+## 🔌 Instance Plugins
+
+Plugins wrap one ModelMix instance without changing global behavior. They run in registration order after templates are rendered and before provider-specific request conversion:
+
+```javascript
+const metrics = {
+    name: 'metrics',
+    async execute(context, next) {
+        const startedAt = Date.now();
+        const result = await next();
+        return { ...result, elapsedMs: Date.now() - startedAt };
+    }
+};
+
+const model = ModelMix.new()
+    .gpt56luna()
+    .use(metrics)
+    .addText('Summarize this request.');
+```
+
+A plugin may edit `context.request`, call `next()`, or return a complete ModelMix result itself. It can also create history-free child executions with `context.invoke()` and choose plugin inheritance:
+
+```javascript
+const child = await context.invoke({
+    systemFile: './prompts/extract-entities.md',
+    assign: { outputLanguage: 'Spanish' },
+    messages: [{ role: 'user', content: section }],
+    plugins: { exclude: ['recursive-plugin'] },
+    history: false
+});
+```
+
+Supported policies are `'inherit'`, `'none'`, `{ include: [...] }`, and `{ exclude: [...] }`. Child metadata exposes `executionId`, `parentExecutionId`, and `depth` to middleware. `.new()` inherits registered plugins but not message history.
+
+Child `systemFile` templates use the same EJS engine, `assign()` data contract, and relative Markdown includes as ordinary ModelMix templates. Use either `system` or `systemFile`, not both.
+
+### Recursive Language Model plugin
+
+The separately publishable `@modelmix/rlm` workspace package keeps document parsing, planner prompts, and `isolated-vm` out of the core `modelmix` dependency tree. It requires Node.js 22 or newer.
+
+```javascript
+const { ModelMix } = require('modelmix');
+const { rlm } = require('@modelmix/rlm');
+
+const fast = ModelMix.new().gpt41mini();
+
+const result = await ModelMix.new()
+    .gpt56luna()
+    .use(rlm({
+        maxDepth: 2,
+        documents: {
+            book: {
+                format: 'markdown',
+                content: markdownBook
+            }
+        },
+        workers: {
+            fast: {
+                model: fast,
+                intelligence: 2,
+                cost: 1,
+                speed: 4,
+                description: 'Translation, extraction, and simple transformations'
+            }
+        },
+        limits: {
+            maxQueryBytes: 64 * 1024,
+            sandboxMemoryBytes: 64 * 1024 * 1024,
+            maxConcurrentQueries: 4,
+            maxCalls: 100,
+            maxOutputBytes: 8 * 1024 * 1024,
+            maxGeneratedTokens: 100000,
+            maxWallTimeMs: 120000
+        }
+    }))
+    .addText('Translate this book to neutral Latin American Spanish.')
+    .message();
+```
+
+Markdown headings become stable nested sections, lists expose item arrays, and the original source order remains reconstructable. The planner receives only a content-free variable manifest: paths, types, array item counts, serialized UTF-8 byte estimates, string lengths, line and paragraph counts, structural summaries, and partition hints. The document values enter only the isolated sandbox, where generated JavaScript can inspect `variables` and call registered workers through `query()`.
+
+A worker normally supplies `model: anotherModelMixInstance`. To offer the current parent chain under a name, register it with `useParent: true` instead; defining both is rejected.
+
+Planner instructions live in Markdown templates under `plugins/rlm/prompts/`. The plugin supplies manifests and limits through ModelMix `assign()` and loads the system prompt through `systemFile`, so relative includes work and runtime values are rendered exactly once.
+
 ## 📚 ModelMix Class Overview
 
 ```javascript

package/index.d.ts

@@ -436,6 +436,8 @@ export declare class ModelMix {
   assign(keyValues: Record<string, unknown>): this;
   assignKey(key: string, value: unknown): this;
   effort(value: EffortValue): this;
+  /** Attach an ordered model chain. Use `shortcut@effort` for a per-model override. */
+  chain(...modelSpecs: string[]): this;
   attach(key: string, provider: MixCustom): this;
 
   // OpenAI

package/index.js

@@ -401,6 +401,50 @@ const MODEL_PRICING = {
     'zai-glm-4.7': { input: 0.55, output: 2.19 },
 };
 
+const CHAIN_MODEL_SHORTCUTS = new Set([
+    'gpt41', 'gpt41mini', 'gpt41nano', 'gpt5', 'gpt5mini', 'gpt5nano',
+    'gpt51', 'gpt52', 'gpt54', 'gpt54mini', 'gpt54nano', 'gpt54pro',
+    'gpt55', 'gpt55pro', 'gpt56sol', 'gpt56terra', 'gpt56luna',
+    'gptRealtime', 'gptRealtimeMini', 'gpt53codex', 'gpt53chat', 'gptOss',
+    'fable50', 'fable5', 'opus50', 'opus5', 'opus48', 'opus47', 'opus46',
+    'sonnet50', 'sonnet5', 'sonnet46', 'sonnet45', 'haiku45',
+    'gemini25flash', 'gemini31pro', 'gemini3pro', 'gemini3flash',
+    'gemini37flash', 'gemini36flash', 'gemini35flash', 'gemini35flashLite',
+    'gemini31flashLite', 'gemini25pro', 'sonarPro', 'sonar',
+    'grok46', 'grok45', 'grok43', 'grok420multiAgent', 'grok420',
+    'qwen3', 'qwen36plus', 'qwen37plus', 'qwen38max', 'hermes3',
+    'kimiK26', 'kimiK27Code', 'kimiK3', 'kimiK25',
+    'minimaxM25', 'minimaxM27', 'minimaxM3', 'mimo25', 'mimo25pro',
+    'deepseekV4Pro', 'deepseekV4Flash', 'GLM51', 'GLM52'
+]);
+
+function parseChainModels(modelSpecs) {
+    if (modelSpecs.length === 0) {
+        throw new TypeError('chain() requires at least one model shortcut string.');
+    }
+
+    return modelSpecs.map((modelSpec, index) => {
+        if (typeof modelSpec !== 'string') {
+            throw new TypeError(`Invalid chain model at index ${index}: expected a model shortcut string.`);
+        }
+
+        const match = /^([A-Za-z_$][A-Za-z0-9_$]*)(?:@(-?\d+))?$/.exec(modelSpec);
+        if (!match) {
+            throw new TypeError(`Invalid chain model "${modelSpec}": expected "shortcut" or "shortcut@effort".`);
+        }
+
+        const shortcut = match[1];
+        if (!CHAIN_MODEL_SHORTCUTS.has(shortcut)) {
+            throw new Error(`Unknown model shortcut "${shortcut}" in chain().`);
+        }
+
+        return {
+            shortcut,
+            effort: match[2] === undefined ? undefined : normalizeEffort(Number(match[2]))
+        };
+    });
+}
+
 class ModelMix {
 
     constructor({ options = {}, config = {}, mix = {} } = {}) {
@@ -483,6 +527,18 @@ class ModelMix {
         return this;
     }
 
+    chain(...modelSpecs) {
+        const models = parseChainModels(modelSpecs);
+        for (const { shortcut, effort } of models) {
+            if (effort === undefined) {
+                this[shortcut]();
+            } else {
+                this[shortcut]({ config: { effort } });
+            }
+        }
+        return this;
+    }
+
     use(plugin) {
         if (!isPlainObject(plugin)) {
             throw new TypeError('plugin must be a plain object.');

package/package.json

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

package/skills/modelmix/SKILL.md

@@ -92,6 +92,17 @@ const model = ModelMix.new()
 
 If `sonnet46` fails, it automatically tries `gpt52`, then `gemini3flash`.
 
+The equivalent `chain()` form accepts public shortcut names directly in the
+same order. Append `@effort` for a per-model unified effort override (`-1` or
+`0`–`100`). Without the suffix, the entry inherits `config.effort`, or keeps the
+provider default when no chain effort is configured:
+
+```javascript
+const model = ModelMix.new()
+    .chain('sonnet46', 'gpt52@20', 'gemini3flash@-1')
+    .addText('Hello!');
+```
+
 ### Instance plugins
 
 Register middleware with `.use({ name, execute })`. Plugins are scoped to the instance, run in registration order, and receive the rendered provider-neutral request. They may edit `context.request`, call `next()`, or return a complete ModelMix result.

package/test/fallback.test.js

@@ -26,6 +26,40 @@ describe('Provider Fallback Chain Tests', () => {
             });
         });
 
+        it('should attach chain shortcuts from arguments with optional per-model effort', () => {
+            model.chain('sonnet5', 'gpt56luna@20', 'gemini37flash@-1');
+
+            expect(model.models.map(({ key }) => key)).to.deep.equal([
+                'claude-sonnet-5',
+                'gpt-5.6-luna',
+                'gemini-3.7-flash'
+            ]);
+            expect(model.models[0].provider.config).to.not.have.property('effort');
+            expect(model.models[1].provider.config.effort).to.equal(20);
+            expect(model.models[2].provider.config.effort).to.equal(-1);
+        });
+
+        it('should keep the chain default effort when an entry omits it', () => {
+            model.effort(60).chain('gpt56luna', 'sonnet5@20');
+
+            expect(model.config.effort).to.equal(60);
+            expect(model.models[0].provider.config).to.not.have.property('effort');
+            expect(model.models[1].provider.config.effort).to.equal(20);
+        });
+
+        it('should reject invalid chains before attaching any model', () => {
+            expect(() => model.chain('gpt56luna', 'unknownModel'))
+                .to.throw('Unknown model shortcut "unknownModel" in chain().');
+            expect(model.models).to.have.length(0);
+
+            expect(() => model.chain('gpt56luna@101'))
+                .to.throw(/Invalid effort/);
+            expect(() => model.chain())
+                .to.throw('chain() requires at least one model shortcut string.');
+            expect(() => model.chain(['gpt56luna']))
+                .to.throw('Invalid chain model at index 0: expected a model shortcut string.');
+        });
+
         it('should use primary provider when available', async () => {
             model.gpt5mini().sonnet46().addText('Hello');