modelmix 5.1.20 → 5.2.1

package/.gitignore

@@ -0,0 +1,138 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+.DS_Store
+demo/jailbreak.mjs
+CLAUDE.md
+demo/jailbreak.js
+/demo/lab
+/demo/results
+/.pnpm-store/

package/README.md

@@ -53,6 +53,7 @@ OPENAI_API_KEY="sk-proj-..."
 OPENROUTER_API_KEY="sk-or-..."
 MOONSHOT_API_KEY="your-moonshot-key..."
 MINIMAX_API_KEY="your-minimax-key..."
+DEEPSEEK_API_KEY="your-deepseek-key..."
 NVIDIA_API_KEY="nvapi-..."
 ...
 GEMINI_API_KEY="AIza..."
@@ -209,7 +210,9 @@ ModelMix provides convenient shorthand methods for quickly accessing different A
 | `qwen3827b()` | OpenRouter | qwen/qwen3.8-27b | [\$0.45][15] | [\$3.20][15] |
 | `qwen38flash()` | OpenRouter | qwen/qwen3.8-flash | [\$0.16][19] | [\$0.47][19] |
 | `deepseekV4Flash()` | Fireworks | models/deepseek-v4-flash | [\$0.14][10] | [\$0.28][10] |
+| `deepseekV41Flash()` | OpenRouter | deepseek/deepseek-v4.1-flash | [\$0.15][27] | [\$0.60][27] |
 | `deepseekV4Pro()` | Fireworks | models/deepseek-v4-pro-0813 | [\$1.32][12] | [\$3.96][12] |
+| `deepseekPro()` | OpenRouter | deepseek/deepseek-v4-pro-0813 | [\$0.5808][28] | [\$1.7424][28] |
 | `GLM53()` | OpenRouter | z-ai/glm-5.3 | [\$1.40][16] | [\$4.40][16] |
 | `GLM53Flash()` | OpenRouter | z-ai/glm-5.3-flash | [\$0.075][20] | [\$0.25][20] |
 | `GLM52()` | Together | zai-org/GLM-5.2 | [\$1.40][7] | [\$4.40][7] |
@@ -262,6 +265,16 @@ OpenRouter fallbacks are disabled globally by default and are appended only with
 
 [25]: https://openrouter.ai/meta/muse-spark-1.2 "Muse Spark 1.2 on OpenRouter"
 [26]: https://openrouter.ai/meta/muse-spark-1.3-contributor "Muse Spark 1.3 Contributor on OpenRouter"
+[27]: https://openrouter.ai/deepseek/deepseek-v4.1-flash "DeepSeek V4.1 Flash on OpenRouter"
+[28]: https://openrouter.ai/deepseek/deepseek-v4-pro-0813 "DeepSeek V4 Pro 0813 on OpenRouter"
+
+`deepseekPro()` uses the pinned OpenRouter model `deepseek/deepseek-v4-pro-0813` and requires `OPENROUTER_API_KEY`. Use `chain('deepseekPro@100')` for maximum reasoning effort. Cost estimates use the listed base rates and $0.05808/M cached input tokens; actual rates may change, including provider and time-based pricing.
+
+`deepseekV41Flash()` supports text and image input through OpenRouter and requires `OPENROUTER_API_KEY`. Use `chain('deepseekV41Flash@100')` for maximum reasoning effort. Cost estimates use the listed base rates and $0.015/M cached input tokens; actual OpenRouter pricing varies by provider and time.
+
+For direct Fireworks access, use `deepseekV41Flash({ mix: { fireworks: true, openrouter: false } })` with `FIREWORKS_API_KEY`. This selects `accounts/fireworks/models/deepseek-v4p1-flash`, priced at [$0.22 input / $0.007 cached input / $0.66 output per 1M tokens](https://fireworks.ai/models/deepseek-ai/deepseek-v4p1-flash). Set both providers to `true` to try Fireworks first and fall back to OpenRouter.
+
+For the native DeepSeek API, use `deepseekV41Flash({ mix: { deepseek: true, openrouter: false } })` with `DEEPSEEK_API_KEY`. It calls `https://api.deepseek.com/chat/completions` with `deepseek-flash`, currently DeepSeek V4.1 Flash. `MixDeepSeek` is also available for explicit `.attach()` calls. Native cost estimates use [peak rates](https://api-docs.deepseek.com/quick_start/pricing/): $0.30 input / $0.006 cached input / $1.20 output per 1M tokens; actual off-peak charges are half. When all three providers are enabled, the order is DeepSeek → Fireworks → OpenRouter.
 
 Muse Spark methods ending in `c` select Contributor: prompts and outputs may be used to improve Meta products. Methods without `c` select the standard tier. `museSpark12()` now selects standard; use `museSpark12c()` for the previous Contributor behavior.
 
@@ -755,7 +768,7 @@ Every response from `raw()` now includes a `tokens` object with the following st
     cacheSavings: 0.00018432, // USD saved by cache reads
     cacheWritePremium: 0, // Extra USD paid to write this cache entry
     breakEvenHits: 0,     // Full future hits needed to recover that premium
-    cost: 0.00011568,     // Total estimated cost in USD
+    cost: 0.00011568,     // OpenRouter charge when reported; otherwise estimated USD
     costBreakdown: {
       uncachedInput: 0.0000352,
       cachedInput: 0.00002048,
@@ -780,7 +793,7 @@ console.log(model.lastRaw.tokens);
 // Same normalized token and cost structure returned by raw()
 ```
 
-`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).
+`thinking` contains internal reasoning tokens when a provider reports them separately; `output` excludes those tokens. Cost calculation bills `output + thinking` once at the output rate. OpenAI Chat/Responses and Anthropic include reasoning in their native output totals; native Grok reports it separately, while Gemini uses `thoughtsTokenCount`. `cost` uses OpenRouter's reported charge when available (including zero); otherwise it uses catalog pricing. `costBreakdown` and cache savings remain catalog estimates and can differ from the actual charge. `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
 
@@ -987,6 +1000,60 @@ Supported policies are `'inherit'`, `'none'`, `{ include: [...] }`, and `{ exclu
 
 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.
 
+Plugins may append `{ tool, callback }` entries to `context.request.tools` using the same definitions as `addTools()`. These tools are available for that execution and its tool continuations, alongside registered local/MCP tools. They do not change the instance's tool registry. Duplicate names are rejected before calling a provider. Child invocations rebuild their tools through the selected plugins or explicit `tools` input.
+
+When plugins add tools, native `options.tools` entries are combined with registered and plugin tools; duplicate function names are rejected. OpenAI Responses converts function definitions and preserves tool calls, results, and accompanying reasoning across continuations.
+
+### Skills plugin
+
+The included plugin loads local [Agent Skills](https://agentskills.io/specification). Pass explicit skill directories or `SKILL.md` files:
+
+```javascript
+import { ModelMix } from 'modelmix';
+import { skills } from 'modelmix/plugins/skills/index.js';
+
+const model = ModelMix.new()
+    .gpt6astra()
+    .opus5()
+    .use(await skills({ paths: ['./skills/writing', './skills/research/SKILL.md'] }))
+    .addText('Use the writing skill to improve this paragraph: ...');
+
+console.log(await model.message());
+```
+
+`skills()` is asynchronous. Each file must have YAML frontmatter with non-empty string `name` and `description` fields; duplicate names and malformed files fail during loading. Relative paths resolve from `process.cwd()`.
+
+Only names and descriptions are appended to the system prompt. A model supporting tool calls can select a skill with `read_skill({ name })`, then load supporting UTF-8 text files with `read_skill({ name, path: 'references/style.md' })`. Full instructions are returned literally, including any EJS syntax. Existing system instructions and tools are preserved; `read_skill` is reserved while this plugin runs.
+
+Skill metadata and `SKILL.md` content are snapshots taken when creating the plugin; recreate it to reload edits. Supporting files are read on demand. Reads must stay inside the registered skill directory, including resolved symlinks. Files are returned in full, so callers should register appropriately sized, trusted skills. The plugin does not execute scripts, install tools, or grant permissions from `allowed-tools` metadata. Skills requiring additional capabilities need tools supplied by the application.
+
+### Benchmark plugin
+
+The included benchmark plugin derives task-specific criteria, runs each configured model independently, and uses the other distinct models as anonymous judges. Model specifications use the same `shortcut@effort` syntax as `chain()`:
+
+```javascript
+const { ModelMix } = require('modelmix');
+const { benchmark } = require('modelmix/plugins/benchmark');
+
+const report = await ModelMix.new()
+    .use(benchmark({
+        criteriaModel: 'gpt56luna@20',
+        models: ['gpt56luna@20', 'sonnet5@20', 'gemini38flash@20']
+    }))
+    .addText('Your benchmark task')
+    .json();
+```
+
+Each criterion is scored from 0 to 10 with equal weight. The report contains the original task, criteria, responses, individual evaluations, averages, errors, elapsed time, token usage, and available cost estimates. Failed responses or evaluations are recorded while the remaining models continue; criteria-generation failures and cancellation stop the run. The first version accepts text tasks, runs sequentially, and does not support streaming.
+
+Set `config.debug: 1` to print progress and failure reasons. Failed model outputs retain their text and provider finish reason in `errors[].error.details`; outputs marked as truncated are excluded from scoring. Adjust `options.max_tokens` to allow enough room for reasoning and output.
+
+Pass `mix` to `benchmark()` to select providers for the criteria model, participants, and judges using each shortcut's provider flags. For example, `mix: { deepseek: true, openrouter: false }` routes `deepseekV41Flash` directly to the official DeepSeek API using `DEEPSEEK_API_KEY`. Omitting `mix` preserves each shortcut's default providers.
+
+JSON parsing accepts a Markdown code block or a lone closing triple-backtick delimiter after valid JSON. Other extra content, malformed JSON, and invalid evaluation scores remain errors.
+
+Run `node demo/benchmark.js` for a complete five-model comparison. It allows up to 32,768 output tokens per call, prints intermediate progress, a final ranking and error details, then saves each response as Markdown together with the full JSON report under `demo/results/`.
+
 ### 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.

package/demo/benchmark.js

@@ -0,0 +1,83 @@
+import { ModelMix } from '../index.js';
+import benchmarkPlugin from '../plugins/benchmark/index.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+try { process.loadEnvFile(); } catch {}
+
+const { benchmark } = benchmarkPlugin;
+
+const task = await readFile(process.argv[2] || new URL('./prompts/story.txt', import.meta.url), 'utf8');
+
+const models = [
+    // 'opus50@20',
+    'gpt6astra@0',
+    'gpt6astra@20',
+    'gpt56sol@40',
+    // 'gemini38flash@20',
+    // 'grok46@20',
+    'deepseekV41Flash@60'
+];
+
+console.log(`Running benchmark: ${models.length} models, 26 sequential model calls.`);
+
+const report = await ModelMix.new({
+    config: { debug: 1 },
+    options: { max_tokens: 65536 }
+})
+    .use(benchmark({
+        criteriaModel: 'opus50@20',
+        models,
+        mix: { deepseek: true, openrouter: false }
+    }))
+    .assign({ task })
+    .addText('<%- task %>')
+    .json();
+
+const runId = new Date().toISOString().replace(/[:.]/g, '-');
+const demoDirectory = path.dirname(fileURLToPath(import.meta.url));
+const resultsDirectory = path.join(demoDirectory, 'results', runId);
+await mkdir(resultsDirectory, { recursive: true });
+
+for (const result of report.results) {
+    if (result.response === null) continue;
+    const filename = result.id.replace(/[^A-Za-z0-9_-]/g, '_');
+    const contents = `# ${result.id}\n\nScore: ${result.score === null ? 'N/A' : Math.round(result.score * 10)}/100\n\nEstimated generation cost (USD): ${result.responseMetrics?.cost ?? 'N/A'}\n\n---\n\n${result.response}\n`;
+    await writeFile(path.join(resultsDirectory, `${filename}.md`), contents, 'utf8');
+}
+
+await writeFile(
+    path.join(resultsDirectory, 'report.json'),
+    `${JSON.stringify(report, null, 2)}\n`,
+    'utf8'
+);
+
+const ranking = report.results
+    .map(result => ({
+        model: result.id,
+        score: result.score,
+        cost: result.responseMetrics?.cost?.toFixed(2) ?? 'N/A',
+        timeSeconds: Number.isFinite(result.responseMetrics?.elapsedMs)
+            ? (result.responseMetrics.elapsedMs / 1000).toFixed(2)
+            : 'N/A',
+        evaluations: `${result.evaluationCount.valid}/${result.evaluationCount.expected}`
+    }))
+    .sort((left, right) => {
+        if (left.score === right.score) return 0;
+        if (left.score === null) return 1;
+        if (right.score === null) return -1;
+        return right.score - left.score;
+    })
+    .map(row => ({ ...row, score: row.score === null ? null : Math.round(row.score * 10) }));
+
+console.table(ranking);
+if (report.errors.length > 0) {
+    console.table(report.errors.map(({ stage, participant, judge, error }) => ({
+        stage,
+        participant,
+        judge,
+        error: error.details?.error?.message ?? error.message
+    })));
+}
+console.log(`Full responses and report saved to ${resultsDirectory}`);

package/demo/package.json

@@ -6,6 +6,8 @@
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
+    "benchmark": "node benchmark.js",
+    "benchmark:template-engine": "node benchmark.js prompts/template-engine.txt",
     "rlm-basic": "node rlm-basic.js",
     "rlm-simple": "node rlm-simple.js",
     "repl-powers": "node repl-powers.js"

package/demo/prompts/story.txt

@@ -0,0 +1,35 @@
+Escribí un cuento breve (600–900 palabras), de cualquier género y ambientación, que cumpla estas restricciones de construcción:
+
+ESTRUCTURA
+
+- Circular: el protagonista termina en el mismo lugar físico donde empieza, pero al final ese lugar significa lo contrario (refugio → trampa, punto de partida → castigo, etc.).
+- El protagonista enfrenta una prueba o rito con una regla explícita. El criterio real de evaluación es otro, nunca se enuncia, y solo se revela en la última línea de diálogo.
+- El protagonista cumple la tarea visible, pagando un costo moral o físico real, y aun así fracasa en la prueba verdadera.
+- El final muestra la inminencia de la consecuencia, no la consecuencia. Cortar justo antes.
+- La consecuencia final es simétrica: lo que el protagonista dañó durante la prueba vuelve contra él.
+
+SIEMBRA
+
+- Un personaje marginal y sin peso aparente (un loco, un borracho, un niño, una voz anónima) anuncia el final con una frase críptica. El protagonista lo ignora.
+- Al menos dos detalles que parecen ambientales o caprichosos deben resultar funcionales al final (por ejemplo, algo que impide al protagonista orientarse, o una marca física que lo delata).
+- El momento en que el protagonista falla debe estar a la vista del lector, sin ser señalado como decisivo. Debe resignificarse en la relectura.
+- Una frase o instrucción repetida al principio y al final que enmarque el recorrido.
+
+PERSONAJES
+
+- Protagonista sin nombre, designado por su función o rol.
+- Antagonista/evaluador con apodo, lacónico, no explica nada y tiene un rasgo físico que oculta (algo que nunca se saca o nunca muestra).
+- La crueldad o arbitrariedad del evaluador se muestra con acciones, sin juicio del narrador.
+- El protagonista enfrenta una elección concreta dentro de la prueba (no si hacerlo, sino cómo o a quién), que lo hace más responsable.
+- Hacia el final, el protagonista hace preguntas que asumen su éxito y no reciben respuesta.
+
+VOZ Y TONO
+
+- Narrador en primera persona, en pasado, con tono de anécdota oral o leyenda urbana; registro coloquial.
+- El primer párrafo resume la premisa sin rodeos. El suspenso no depende de ocultar de qué trata.
+- Contraste entre un marco cotidiano o burocrático y un contenido brutal o extraño, contado con naturalidad.
+- Al menos una secuencia de diálogo con repetición y escalada (la misma orden dicha varias veces, subiendo de intensidad).
+- Remate: una línea de diálogo muy breve (dos o tres palabras) que explica el fracaso, seguida de la revelación espacial y la amenaza.
+- Economía: descripción mínima, acceso limitado a la mente del protagonista, sin moraleja explícita.
+
+No imites la trama de ningún cuento existente. Inventá la prueba, el mundo y la consecuencia desde cero.

package/demo/prompts/template-engine.txt

@@ -0,0 +1,41 @@
+Develop a minimalist template engine as a Node.js library using ES modules and no external dependencies.
+
+The complete implementation must fit within 200 physical lines, including comments and blank lines. Do not minify the code or artificially pack statements onto single lines. Write code and identifiers in English, and explanations in Spanish.
+
+Implement these three features:
+
+1. Compilation to JavaScript
+   - `compile(template, options)` returns a reusable function that accepts data and produces a string.
+   - Support `<% code %>` for executing JavaScript, `<%= expression %>` for HTML-escaped output, and `<%- expression %>` for unescaped output.
+   - Allow conditionals and loops to open and close across separate tags, with text between them.
+   - Correctly preserve quotes, backslashes, and line breaks in literal text.
+2. Errors linked to the original template
+   - Runtime errors must report the filename, original line number, and a short template excerpt.
+   - Preserve the original error as `cause`.
+   - For errors inside includes, identify the file where the failure actually occurred.
+   - For syntax errors, report at least the filename. Do not invent a line number if it cannot be determined accurately.
+3. Nested includes
+   - Provide an `include(path, data)` function inside templates.
+   - Resolve each relative path from the file containing the include call.
+   - Includes inherit parent data and may override values locally without mutating the parent data.
+   - Support multiple nesting levels.
+   - Detect inclusion cycles and report the chain of files involved.
+   - Provide clear errors for missing files.
+
+Public API:
+
+- `compile(template, options)`
+- `render(template, data, options)`
+- `renderFile(filename, data)`
+
+Keep everything synchronous. Require explicit property access through the `data` object inside templates, without `with`. Do not add caching, layouts, plugins, configurable delimiters, or browser support.
+
+Templates are trusted code. Explicitly document that the engine provides no sandbox and must not execute templates supplied by untrusted users.
+
+Deliver only:
+
+- The complete implementation in a single file.
+- The actual line count of the implementation file.
+- A brief explanation of limitations.
+
+Do not include tests, examples, sample templates, or demonstration code. Prioritize clarity and correctness over additional features.

package/demo/short.js

@@ -28,6 +28,8 @@ const mmix = await ModelMix.new(setup)
     .museSpark12() // (fallback 17) OpenRouter meta/muse-spark-1.2
     .museSpark13c() // (fallback 18) OpenRouter meta/muse-spark-1.3-contributor
     .gpt6astra() // (fallback 19) OpenAI gpt-6-astra
+    .deepseekV41Flash({ mix: { deepseek: true, fireworks: true, openrouter: true } }) // (fallback 20 + provider fallback) DeepSeek/Fireworks/OpenRouter V4.1 Flash
+    .deepseekPro() // (fallback 21) OpenRouter deepseek/deepseek-v4-pro-0813
     .addText("What's your name?");
 
 console.log(await mmix.message());

package/effort.js

@@ -125,6 +125,7 @@ const PROVIDER_FAMILY_BY_CLASS = {
     MixKimi: 'openai',
     MixMiniMax: 'openai',
     MixMiMo: 'openai',
+    MixDeepSeek: 'openai',
     MixGrok: 'openai',
     MixGroq: 'openai',
     MixTogether: 'openai',
@@ -232,7 +233,8 @@ function isGemini25(modelKey) {
 function isDeepSeekV4(modelKey) {
     if (typeof modelKey !== 'string') return false;
     const key = modelKey.toLowerCase();
-    return key.includes('deepseek-v4') || key.includes('deepseek_v4');
+    return key === 'deepseek-flash' || key === '~deepseek/deepseek-pro-latest'
+        || key.includes('deepseek-v4') || key.includes('deepseek_v4');
 }
 
 function isMiniMax(modelKey) {

package/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * Type definitions for modelmix
- * @see https://github.com/clasen/ModelMix
- */
-
 export type MessageRole = 'user' | 'assistant' | 'system' | 'tool' | string;
 
 export type DebugLevel = 0 | 1 | 2 | 3 | 4;
@@ -87,6 +82,7 @@ export interface ModelMixMixFlags {
   moonshot?: boolean;
   minimax?: boolean;
   mimo?: boolean;
+  deepseek?: boolean;
   [key: string]: boolean | undefined;
 }
 
@@ -161,6 +157,7 @@ export interface TokenCostBreakdown {
 
 export interface TokenUsage {
   input: number;
+  /** Generated tokens excluding separately reported reasoning. */
   output: number;
   /** Internal reasoning tokens billed at the output rate when reported separately. */
   thinking: number;
@@ -177,7 +174,9 @@ export interface TokenUsage {
   cacheWritePremium: number;
   /** Full future cache hits needed to recover the current write premium. */
   breakEvenHits: number;
+  /** USD charged by OpenRouter when available, otherwise the catalog estimate. */
   cost: number;
+  /** Catalog-based estimate; its total can differ from the reported charge in cost. */
   costBreakdown: TokenCostBreakdown;
   speed?: number;
 }
@@ -254,6 +253,7 @@ export interface PluginExecutionContext {
   request: {
     system: string;
     messages: ChatMessage[];
+    tools: ToolWithCallback[];
     options: ModelMixOptions;
     config: ModelMixConfig;
     outputMode: ModelMixOutputMode;
@@ -527,7 +527,10 @@ export declare class ModelMix {
   mimo25(args?: ModelAttachArgs): this;
   mimo25pro(args?: ModelAttachArgs): this;
   deepseekV4Pro(args?: ModelAttachArgs): this;
+  /** Uses deepseek/deepseek-v4-pro-0813 through OpenRouter. */
+  deepseekPro(args?: ModelAttachArgs): this;
   deepseekV4Flash(args?: ModelAttachArgs): this;
+  deepseekV41Flash(args?: ModelAttachArgs): this;
   GLM52(args?: ModelAttachArgs): this;
   GLM53(args?: ModelAttachArgs): this;
   GLM53Flash(args?: ModelAttachArgs): this;
@@ -624,6 +627,7 @@ export declare class MixKimi extends MixOpenAI {}
 export declare class MixAnthropic extends MixCustom {}
 export declare class MixMiniMax extends MixOpenAI {}
 export declare class MixMiMo extends MixOpenAI {}
+export declare class MixDeepSeek extends MixOpenAI {}
 export declare class MixPerplexity extends MixCustom {}
 export declare class MixOllama extends MixCustom {}
 export declare class MixGrok extends MixOpenAI {}