modelmix 5.0.3 → 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
@@ -982,6 +1047,18 @@ new ModelMix(args = { options: {}, config: {} })
   - `toolCalls`: Array of tool calls made by the model (if any)
   - `tokens`: Normalized token counts (`input`, `output`, `thinking`, `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
+- `ModerationMix` owns moderation-only provider chains. Use `openai()` to attach OpenAI's current `omni-moderation-latest`; `raw()` exposes the results under `moderation` (`flagged`, `categories`, `category_scores`, and `category_applied_input_types`). It uses `/v1/moderations`, rejects generative providers, does not generate text, and does not support streaming. Future moderation providers can be appended as fallbacks.
+  ```javascript
+  const { ModerationMix } = require('modelmix');
+
+  const { moderation: [profile] } = await ModerationMix.new()
+      .openai()
+      .addText(username)
+      .addImageFromUrl(avatarUrl)
+      .raw();
+
+  if (profile.flagged) throw new Error('Profile rejected by moderation');
+  ```
 - `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.
   - `schemaExample`: Example of the JSON structure to be returned. Top-level arrays are auto-wrapped for better LLM compatibility.

package/demo/moderation.js

@@ -0,0 +1,17 @@
+import { ModerationMix } from '../index.js';
+try { process.loadEnvFile(); } catch {}
+
+const username = 'player_name';
+const avatarUrl = 'https://example.com/avatar.png';
+
+const { moderation: [profileModeration] } = await ModerationMix.new()
+    .openai()
+    .addText(username)
+    .addImageFromUrl(avatarUrl)
+    .raw();
+
+console.log({
+    allowed: !profileModeration.flagged,
+    categories: profileModeration.categories,
+    scores: profileModeration.category_scores
+});

package/index.d.ts

@@ -190,9 +190,36 @@ export interface ModelMixResult {
   response?: unknown;
   assistantMessage?: ChatMessage;
   execution?: PluginExecutionMetadata;
+  moderation?: ModerationResult[];
   [key: string]: unknown;
 }
 
+export interface ModerationCategories {
+  harassment: boolean;
+  'harassment/threatening': boolean;
+  hate: boolean;
+  'hate/threatening': boolean;
+  illicit: boolean | null;
+  'illicit/violent': boolean | null;
+  'self-harm': boolean;
+  'self-harm/instructions': boolean;
+  'self-harm/intent': boolean;
+  sexual: boolean;
+  'sexual/minors': boolean;
+  violence: boolean;
+  'violence/graphic': boolean;
+}
+
+export type ModerationCategoryScores = Record<keyof ModerationCategories, number>;
+export type ModerationAppliedInputTypes = Record<keyof ModerationCategories, Array<'text' | 'image'>>;
+
+export interface ModerationResult {
+  flagged: boolean;
+  categories: ModerationCategories;
+  category_scores: ModerationCategoryScores;
+  category_applied_input_types: ModerationAppliedInputTypes;
+}
+
 export type ModelMixOutputMode = 'message' | 'json' | 'block' | 'raw' | 'stream';
 
 export interface PluginExecutionMetadata {
@@ -409,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
@@ -571,7 +600,14 @@ export declare class MixCustom {
 }
 
 export declare class MixOpenAI extends MixCustom {}
+export declare class MixModeration extends MixCustom {}
 export declare class MixOpenAIResponses extends MixOpenAI {}
+export declare class MixOpenAIModeration extends MixModeration {
+  static messagesToModerationInput(messages?: ChatMessage[]): Array<
+    | { type: 'text'; text: string }
+    | { type: 'image_url'; image_url: { url: string } }
+  >;
+}
 export declare class MixOpenAIWebSocket extends MixOpenAIResponses {}
 export declare class MixOpenRouter extends MixOpenAI {}
 export declare class MixKimi extends MixOpenAI {}
@@ -590,6 +626,18 @@ export declare class MixFireworks extends MixCustom {}
 export declare class MixNVIDIA extends MixCustom {}
 export declare class MixGoogle extends MixCustom {}
 
+export declare class ModerationMix extends ModelMix {
+  constructor(setup?: Omit<ModelMixSetup, 'mix'>);
+  static new(setup?: Omit<ModelMixSetup, 'mix'>): ModerationMix;
+  new(setup?: Omit<ModelMixSetup, 'mix'>): ModerationMix;
+  attach(key: string, provider: MixModeration): this;
+  openai(args?: ModelAttachArgs): this;
+  message(): Promise<never>;
+  json(): Promise<never>;
+  block(): Promise<never>;
+  stream(): Promise<never>;
+}
+
 /** Normalize unified effort to integer -1 or 0..100. */
 export function normalizeEffort(value: unknown): EffortValue;
 

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.');
@@ -2602,6 +2658,12 @@ class MixOpenAI extends MixCustom {
     }
 }
 
+class MixModeration extends MixCustom {
+    getOptionsTools() {
+        return {};
+    }
+}
+
 class MixOpenAIResponses extends MixOpenAI {
     async create({ config = {}, options = {} } = {}) {
 
@@ -2833,6 +2895,109 @@ class MixOpenAIResponses extends MixOpenAI {
     }
 }
 
+class MixOpenAIModeration extends MixModeration {
+    getDefaultConfig(customConfig) {
+        const apiKey = customConfig.apiKey || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OpenAI API key not found. Please provide it in config or set OPENAI_API_KEY environment variable.');
+        }
+
+        return super.getDefaultConfig({
+            url: 'https://api.openai.com/v1/moderations',
+            apiKey,
+            ...customConfig
+        });
+    }
+
+    async create({ config = {}, options = {} } = {}) {
+        if (options.stream) {
+            throw new Error('Stream is not supported for OpenAI moderation');
+        }
+
+        const input = MixOpenAIModeration.messagesToModerationInput(options.messages);
+        const response = await fetchJsonResponse(this.config.url, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ model: options.model, input })
+        });
+
+        return {
+            moderation: response.data.results,
+            tokens: ModelMix.normalizeTokenUsage(),
+            response: response.data
+        };
+    }
+
+    static messagesToModerationInput(messages = []) {
+        const input = [];
+
+        for (const message of messages) {
+            if (typeof message.content === 'string') {
+                input.push({ type: 'text', text: message.content });
+                continue;
+            }
+            if (!Array.isArray(message.content)) continue;
+
+            for (const content of message.content) {
+                if (content?.type === 'text') {
+                    input.push({ type: 'text', text: content.text });
+                } else if (content?.type === 'image') {
+                    const { media_type: mediaType, data } = content.source || {};
+                    if (!mediaType || !data) {
+                        throw new Error('OpenAI moderation images must be prepared as base64 data URLs');
+                    }
+                    input.push({
+                        type: 'image_url',
+                        image_url: { url: `data:${mediaType};base64,${data}` }
+                    });
+                }
+            }
+        }
+
+        return input;
+    }
+}
+
+class ModerationMix extends ModelMix {
+    static new(setup = {}) {
+        return new ModerationMix(setup);
+    }
+
+    new({ options = {}, config = {} } = {}) {
+        return new ModerationMix({
+            options: { ...this.options, ...options },
+            config: { ...this.config, ...config }
+        });
+    }
+
+    attach(key, provider) {
+        if (!(provider instanceof MixModeration)) {
+            throw new Error('ModerationMix only accepts moderation providers.');
+        }
+        return super.attach(key, provider);
+    }
+
+    openai({ options = {}, config = {} } = {}) {
+        return this.attach('omni-moderation-latest', new MixOpenAIModeration({ options, config }));
+    }
+
+    async message() {
+        throw new Error('ModerationMix does not generate messages. Use raw() and read result.moderation.');
+    }
+
+    async json() {
+        throw new Error('ModerationMix does not generate JSON. Use raw() and read result.moderation.');
+    }
+
+    async block() {
+        throw new Error('ModerationMix does not generate blocks. Use raw() and read result.moderation.');
+    }
+
+    async stream() {
+        throw new Error('ModerationMix does not support streaming. Use raw().');
+    }
+}
+
 class MixOpenAIWebSocket extends MixOpenAIResponses {
     getDefaultConfig(customConfig) {
         return super.getDefaultConfig({
@@ -4020,4 +4185,4 @@ class MixGoogle extends MixCustom {
     }
 }
 
-module.exports = { MixCustom, ModelMix, MixAnthropic, MixKimi, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA, normalizeEffort, applyUnifiedEffort, resolveProviderFamily };
+module.exports = { MixCustom, ModelMix, ModerationMix, MixModeration, MixAnthropic, MixKimi, MixMiniMax, MixMiMo, MixOpenAI, MixOpenAIResponses, MixOpenAIModeration, MixOpenAIWebSocket, MixOpenRouter, MixPerplexity, MixOllama, MixLMStudio, MixGroq, MixTogether, MixGrok, MixCerebras, MixGoogle, MixFireworks, MixNVIDIA, normalizeEffort, applyUnifiedEffort, resolveProviderFamily };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmix",
-  "version": "5.0.3",
+  "version": "5.0.5",
   "description": "🧬 Reliable interface with automatic fallback for AI LLMs.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -77,7 +77,6 @@
     "test:tokens": "mocha test/tokens.test.js --timeout 10000 --require test/setup.js",
     "test:plugins": "mocha test/plugins.test.js --timeout 10000 --require test/setup.js",
     "test:rlm": "mocha plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js",
-    "test:offline": "mocha test/json.test.js test/fallback.test.js test/templates.test.js test/images.test.js test/bottleneck.test.js test/tokens.test.js test/history.test.js test/anthropic.test.js test/effort.test.js test/grok.test.js test/plugins.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
-  },
-  "packageManager": "pnpm@11.18.0+sha512.33d83c77da82f49fba836925c6f1b841181ec3132b670639bd012f7075f5c7cf634c5f870147c19aae7478fac01df09d8892e880454896edd23ee9b33757563c"
-}
+    "test:offline": "mocha test/json.test.js test/fallback.test.js test/templates.test.js test/images.test.js test/bottleneck.test.js test/tokens.test.js test/history.test.js test/anthropic.test.js test/effort.test.js test/grok.test.js test/moderation.test.js test/plugins.test.js plugins/rlm/test/**/*.test.js --timeout 10000 --require test/setup.js"
+  }
+}

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.
@@ -137,6 +148,9 @@ ModelMix.new({ config: { effort: 80 } })
 ## Available Model Shorthands
 
 ### OpenAI
+
+Use `ModerationMix.new().openai()` with `.raw()` to classify text and images through OpenAI's Moderations endpoint. Read the results from `raw.moderation`. `ModerationMix` accepts moderation providers as ordered fallbacks, rejects generative providers, and does not generate text or support streaming.
+
 `gpt52()` `gpt52chat()` `gpt51()` `gpt5()` `gpt5mini()` `gpt5nano()` `gpt45()` `gpt41()` `gpt41mini()` `gpt41nano()` `o3()` `o4mini()`
 
 ### Anthropic
@@ -610,7 +624,7 @@ const model = ModelMix.new({
 
 ## Available Provider Classes
 
-`MixOpenAI` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixKimi` `MixMiniMax` `MixLambda`
+`ModerationMix` `MixModeration` `MixOpenAI` `MixOpenAIResponses` `MixOpenAIModeration` `MixAnthropic` `MixGoogle` `MixPerplexity` `MixGroq` `MixTogether` `MixGrok` `MixOpenRouter` `MixOllama` `MixLMStudio` `MixCustom` `MixCerebras` `MixFireworks` `MixKimi` `MixMiniMax` `MixLambda`
 
 ## Troubleshooting
 

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');
 

package/test/moderation.test.js

@@ -0,0 +1,135 @@
+const { expect } = require('chai');
+const nock = require('nock');
+const { ModerationMix, MixModeration, MixOpenAIModeration } = require('../index.js');
+
+describe('OpenAI moderation', () => {
+    const moderationResult = {
+        flagged: true,
+        categories: { violence: true },
+        category_scores: { violence: 0.98 },
+        category_applied_input_types: { violence: ['text', 'image'] }
+    };
+
+    it('registers omni-moderation-latest with openai()', () => {
+        const model = ModerationMix.new().openai({ config: { apiKey: 'test-key' } });
+
+        expect(model.models).to.have.length(1);
+        expect(model.models[0].key).to.equal('omni-moderation-latest');
+        expect(model.models[0].provider).to.be.instanceOf(MixOpenAIModeration);
+        expect(model.models[0].provider.config.url).to.equal('https://api.openai.com/v1/moderations');
+    });
+
+    it('accepts an explicit API key without requiring the environment variable', () => {
+        const originalApiKey = process.env.OPENAI_API_KEY;
+        delete process.env.OPENAI_API_KEY;
+
+        try {
+            const model = ModerationMix.new().openai({ config: { apiKey: 'explicit-key' } });
+            expect(model.models[0].provider.config.apiKey).to.equal('explicit-key');
+        } finally {
+            if (originalApiKey === undefined) delete process.env.OPENAI_API_KEY;
+            else process.env.OPENAI_API_KEY = originalApiKey;
+        }
+    });
+
+    it('sends text and image input to the Moderations endpoint', async () => {
+        const api = nock('https://api.openai.com')
+            .post('/v1/moderations', body => {
+                expect(body).to.deep.equal({
+                    model: 'omni-moderation-latest',
+                    input: [
+                        { type: 'text', text: 'Check this' },
+                        {
+                            type: 'image_url',
+                            image_url: { url: 'data:image/png;base64,aW1hZ2U=' }
+                        }
+                    ]
+                });
+                return true;
+            })
+            .reply(200, {
+                id: 'modr-test',
+                model: 'omni-moderation-latest',
+                results: [moderationResult]
+            });
+
+        const result = await ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .addText('Check this')
+            .addImageFromUrl('data:image/png;base64,aW1hZ2U=')
+            .raw();
+
+        expect(result.moderation).to.deep.equal([moderationResult]);
+        api.done();
+    });
+
+    it('exposes the complete API response through raw()', async () => {
+        const response = {
+            id: 'modr-test',
+            model: 'omni-moderation-latest',
+            results: [moderationResult]
+        };
+        const api = nock('https://api.openai.com')
+            .post('/v1/moderations')
+            .reply(200, response);
+
+        const raw = await ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .addText('Check this')
+            .raw();
+
+        expect(raw.moderation).to.deep.equal(response.results);
+        expect(raw.response).to.deep.equal(response);
+        expect(raw.tokens).to.include({ input: 0, output: 0, total: 0, cost: 0 });
+        api.done();
+    });
+
+    it('rejects streaming because the Moderations endpoint does not support it', async () => {
+        const model = ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .addText('Check this');
+
+        try {
+            await model.stream(() => {});
+            throw new Error('Expected stream() to reject');
+        } catch (error) {
+            expect(error.message).to.equal('ModerationMix does not support streaming. Use raw().');
+        }
+    });
+
+    it('rejects generative providers from the moderation chain', () => {
+        const model = ModerationMix.new();
+
+        expect(() => model.gpt41nano()).to.throw(
+            'ModerationMix only accepts moderation providers.'
+        );
+    });
+
+    it('accepts additional moderation providers as fallbacks', () => {
+        class TestModeration extends MixModeration {}
+        const model = ModerationMix.new()
+            .openai({ config: { apiKey: 'test-key' } })
+            .attach('test-moderation', new TestModeration({ config: { apiKey: 'test-key' } }));
+
+        expect(model.models.map(({ key }) => key)).to.deep.equal([
+            'omni-moderation-latest',
+            'test-moderation'
+        ]);
+    });
+
+    for (const method of ['message', 'json', 'block']) {
+        it(`rejects ${method}() because moderation is not generative`, async () => {
+            const model = ModerationMix.new()
+                .openai({ config: { apiKey: 'test-key' } })
+                .addText('Check this');
+
+            try {
+                await model[method]();
+                throw new Error(`Expected ${method}() to reject`);
+            } catch (error) {
+                expect(error.message).to.include('ModerationMix does not generate');
+            }
+        });
+    }
+
+});