modelmix 5.0.2 → 5.0.3

package/plugins/rlm/test/variable-descriptors.test.js

@@ -0,0 +1,170 @@
+const { expect } = require('chai');
+const { describeVariables, plannerTemplateData } = require('..');
+
+describe('RLM variable metadata', () => {
+    const workerManifest = {
+        fast: {
+            intelligence: 1,
+            cost: 1,
+            speed: 5,
+            description: 'Fast transformations'
+        }
+    };
+    const runtimeLimits = {
+        maxCalls: 20,
+        maxOutputBytes: 1024 * 1024,
+        maxGeneratedTokens: 10000,
+        maxWallTimeMs: 30000
+    };
+    const book = {
+        title: 'A hidden title that must not reach the planner',
+        chapters: [
+            {
+                heading: 'First hidden chapter',
+                content: 'First secret paragraph.\n\nSecond secret paragraph.',
+                tags: ['opening', 'setup']
+            },
+            {
+                heading: 'Second hidden chapter',
+                content: 'Árbol and emoji 😀.\n\nAnother concealed paragraph.',
+                tags: ['middle']
+            }
+        ]
+    };
+
+    it('describes strings, objects, and arrays without exposing their content', () => {
+        const manifest = describeVariables(book);
+        const title = manifest.descriptors.title;
+        const chapters = manifest.descriptors.chapters;
+
+        expect(manifest).to.include({
+            sizeBasis: 'serialized-json-utf8',
+            variables: 2,
+            estimatedBytes: Buffer.byteLength(JSON.stringify(book), 'utf8')
+        });
+        expect(title).to.include({
+            path: 'title',
+            type: 'string',
+            characters: Array.from(book.title).length,
+            utf16CodeUnits: book.title.length,
+            utf8Bytes: Buffer.byteLength(book.title, 'utf8'),
+            lines: 1,
+            paragraphs: 1
+        });
+        expect(chapters).to.include({
+            path: 'chapters',
+            type: 'array',
+            items: 2,
+            estimatedBytes: Buffer.byteLength(JSON.stringify(book.chapters), 'utf8')
+        });
+        expect(chapters.itemSize).to.deep.equal({
+            min: Math.min(...book.chapters.map(chapter => Buffer.byteLength(JSON.stringify(chapter), 'utf8'))),
+            max: Math.max(...book.chapters.map(chapter => Buffer.byteLength(JSON.stringify(chapter), 'utf8'))),
+            average: Number((book.chapters
+                .map(chapter => Buffer.byteLength(JSON.stringify(chapter), 'utf8'))
+                .reduce((sum, bytes) => sum + bytes, 0) / 2).toFixed(2)),
+            total: book.chapters
+                .map(chapter => Buffer.byteLength(JSON.stringify(chapter), 'utf8'))
+                .reduce((sum, bytes) => sum + bytes, 0)
+        });
+        expect(chapters.itemShape.types).to.deep.equal({ object: 2 });
+        expect(chapters.itemShape.properties.content).to.deep.include({
+            present: 2,
+            missing: 0,
+            types: { string: 2 }
+        });
+        expect(chapters.itemShape.properties.content.stringSize.paragraphs).to.deep.equal({
+            min: 2,
+            max: 2,
+            average: 2,
+            total: 4
+        });
+
+        const serializedManifest = JSON.stringify(manifest);
+        expect(serializedManifest).to.not.include(book.title);
+        for (const chapter of book.chapters) {
+            expect(serializedManifest).to.not.include(chapter.heading);
+            expect(serializedManifest).to.not.include(chapter.content);
+            for (const tag of chapter.tags) expect(serializedManifest).to.not.include(tag);
+        }
+    });
+
+    it('keeps exact aggregate sizes for large arrays without listing their items', () => {
+        const values = Array.from({ length: 100000 }, (_, index) => `row-${index}`);
+        const descriptor = describeVariables({ values }).descriptors.values;
+
+        expect(descriptor.items).to.equal(values.length);
+        expect(descriptor.estimatedBytes).to.equal(Buffer.byteLength(JSON.stringify(values), 'utf8'));
+        expect(descriptor).to.not.have.property('children');
+        expect(JSON.stringify(descriptor)).to.not.include('row-99999');
+    });
+
+    it('rejects values that cannot safely enter the sandbox environment', () => {
+        const circular = {};
+        circular.self = circular;
+
+        expect(() => describeVariables({ circular })).to.throw('circular reference');
+        expect(() => describeVariables({ callback() {} })).to.throw('unsupported type function');
+        expect(() => describeVariables({ invalid: Infinity })).to.throw('finite numbers');
+        expect(() => describeVariables({ date: new Date() })).to.throw('plain objects');
+    });
+
+    it('adds limits and actionable partition guidance to the planner prompt', () => {
+        const templateData = plannerTemplateData({
+            variables: book,
+            limits: {
+                ...runtimeLimits,
+                maxQueryBytes: 32,
+                sandboxMemoryBytes: 64 * 1024 * 1024,
+                maxConcurrentQueries: 4
+            },
+            workerManifest
+        });
+
+        expect(templateData.variableManifest).to.include('"items": 2');
+        expect(templateData.processingLimits).to.include('"maxQueryBytes": 32');
+        expect(templateData.processingLimits).to.include('"sandboxMemoryBytes": 67108864');
+        expect(templateData.processingLimits).to.include('"maxConcurrentQueries": 4');
+        expect(templateData.planningHints).to.include('"strategy": "split-oversized-items-semantically"');
+        expect(templateData.planningHints).to.include('"oversizedStringFields"');
+        expect(templateData.planningHints).to.include('"content"');
+        const serializedTemplateData = JSON.stringify(templateData);
+        expect(serializedTemplateData).to.not.include(book.title);
+        for (const chapter of book.chapters) {
+            expect(serializedTemplateData).to.not.include(chapter.heading);
+            expect(serializedTemplateData).to.not.include(chapter.content);
+        }
+    });
+
+    it('distinguishes direct values from arrays that should be batched', () => {
+        const templateData = plannerTemplateData({
+            variables: {
+                instruction: 'short',
+                paragraphs: Array.from({ length: 20 }, () => 'small paragraph')
+            },
+            limits: {
+                ...runtimeLimits,
+                maxQueryBytes: 80,
+                sandboxMemoryBytes: 1024 * 1024,
+                maxConcurrentQueries: 2
+            },
+            workerManifest
+        });
+
+        expect(templateData.planningHints).to.include('"path": "instruction"');
+        expect(templateData.planningHints).to.include('"strategy": "direct"');
+        expect(templateData.planningHints).to.include('"path": "paragraphs"');
+        expect(templateData.planningHints).to.include('"strategy": "batch-array-items"');
+        expect(templateData.planningHints).to.match(/"suggestedMaxItemsPerQuery": [1-9]\d*/);
+    });
+
+    it('requires explicit planning limits instead of silent defaults', () => {
+        expect(() => plannerTemplateData({ variables: {}, limits: {}, workerManifest }))
+            .to.throw('limits.maxQueryBytes');
+        expect(() => plannerTemplateData({
+            variables: {},
+            limits: { maxQueryBytes: 100, sandboxMemoryBytes: 1000 },
+            workerManifest
+        })).to.throw('limits.maxConcurrentQueries');
+    });
+});

package/plugins/rlm/test/worker-catalog.test.js

@@ -0,0 +1,104 @@
+const { expect } = require('chai');
+const { MixCustom, ModelMix } = require('../../../index.js');
+const { createWorkerCatalog } = require('..');
+
+function workerModel(secret = 'worker-secret') {
+    return ModelMix.new().attach('worker-model', new MixCustom({
+        config: { apiKey: secret, url: 'https://private-provider.invalid' }
+    }));
+}
+
+describe('RLM worker catalog', () => {
+    it('exposes decision metadata without models, providers, or credentials', () => {
+        const model = workerModel();
+        const catalog = createWorkerCatalog({
+            expert: {
+                model,
+                intelligence: 5,
+                cost: 4,
+                speed: 2,
+                description: 'Complex synthesis'
+            },
+            fast: {
+                model: workerModel('another-secret'),
+                intelligence: 1,
+                cost: 1,
+                speed: 5,
+                description: 'Extraction and classification'
+            }
+        });
+
+        expect(catalog.get('expert')).to.equal(model);
+        expect(catalog.manifest).to.deep.equal({
+            expert: {
+                intelligence: 5,
+                cost: 4,
+                speed: 2,
+                description: 'Complex synthesis'
+            },
+            fast: {
+                intelligence: 1,
+                cost: 1,
+                speed: 5,
+                description: 'Extraction and classification'
+            }
+        });
+        const serialized = JSON.stringify(catalog.manifest);
+        expect(serialized).to.not.include('worker-secret');
+        expect(serialized).to.not.include('private-provider');
+        expect(serialized).to.not.include('models');
+    });
+
+    it('rejects invalid workers and unknown selections', () => {
+        expect(() => createWorkerCatalog({})).to.throw('non-empty');
+        expect(() => createWorkerCatalog({
+            invalid: {
+                model: {},
+                intelligence: 1,
+                cost: 1,
+                speed: 1,
+                description: 'Invalid model'
+            }
+        })).to.throw('ModelMix instance');
+        const catalog = createWorkerCatalog({
+            valid: {
+                model: workerModel(),
+                intelligence: 1,
+                cost: 1,
+                speed: 1,
+                description: 'Valid worker'
+            }
+        });
+        expect(() => catalog.get('missing')).to.throw('Unknown RLM worker');
+    });
+
+    it('represents the inherited parent chain without exposing a model object', () => {
+        const catalog = createWorkerCatalog({
+            parent: {
+                useParent: true,
+                intelligence: 3,
+                cost: 2,
+                speed: 3,
+                description: 'Use the current ModelMix chain'
+            }
+        });
+
+        expect(catalog.get('parent')).to.equal(undefined);
+        expect(catalog.manifest.parent).to.deep.equal({
+            intelligence: 3,
+            cost: 2,
+            speed: 3,
+            description: 'Use the current ModelMix chain'
+        });
+        expect(() => createWorkerCatalog({
+            invalid: {
+                model: workerModel(),
+                useParent: true,
+                intelligence: 1,
+                cost: 1,
+                speed: 1,
+                description: 'Ambiguous worker'
+            }
+        })).to.throw('exactly one of model or useParent');
+    });
+});

package/pnpm-workspace.yaml

@@ -1,3 +1,9 @@
+packages:
+  - plugins/*
+
+allowBuilds:
+  isolated-vm: true
+
 minimumReleaseAgeExclude:
   - ws@8.21.0
   - hono@4.12.25

package/skills/modelmix/SKILL.md

@@ -92,6 +92,24 @@ const model = ModelMix.new()
 
 If `sonnet46` fails, it automatically tries `gpt52`, then `gemini3flash`.
 
+### 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.
+
+```javascript
+model.use({
+    name: 'metrics',
+    async execute(context, next) {
+        const result = await next();
+        return { ...result, executionId: context.execution.executionId };
+    }
+});
+```
+
+`context.invoke()` starts a child without conversation history. Its `plugins` policy is `'inherit'`, `'none'`, `{ include: [...] }`, or `{ exclude: [...] }`. Passing `model` routes the child through another ModelMix worker chain while preserving execution-tree metadata. Child invocations may pass `assign` with either `system` or `systemFile`; `systemFile` uses the ordinary ModelMix EJS renderer and relative includes.
+
+The optional `@modelmix/rlm` package is a separate workspace/npm package for recursive processing of large structured inputs. Pass Markdown through `documents: { name: { format: 'markdown', content } }`, register named ModelMix worker chains, and provide every runtime limit explicitly. A worker uses either `model: anotherModelMixInstance` or `useParent: true`. Its planner sees content-free variable size/shape metadata, while document values and generated orchestration code stay inside an `isolated-vm` sandbox. RLM planner prompts are Markdown files rendered with the normal child `assign` plus `systemFile` path.
+
 ### Unified effort
 
 Provider-agnostic reasoning intensity. **Not** an `options` field — use `config.effort` or `.effort(n)`.
@@ -114,7 +132,7 @@ ModelMix.new({ config: { effort: 80 } })
 | DeepSeek V4 | off | `low`↑ | `high`↑ | `high`↑ | `max`↑ | — |
 | MiniMax M3 | off | adaptive | adaptive | adaptive | adaptive | adaptive |
 
-\* Gemini bands: 0–24 / 25–49 / 50–74 / 75–100. DeepSeek `↑` = thinking on; `off` = thinking disabled. MiniMax `off`/`adaptive` = `thinking.disabled` / `thinking.type=adaptive`. Gemini 2.5 maps 0–100 to `thinkingBudget`. Anthropic: adaptive + `output_config.effort` on Claude 5 / Fable / Opus 4.6+ / Sonnet 4.6+; Sonnet 4.5 / Haiku 4.5 use `thinking.type=enabled` + `budget_tokens`. Grok 4.6 maps 0–39 / 40–59 / 60–79 / 80–100 to `low` / `medium` / `high` / `xhigh`; without effort it uses native `high`. `-1` = adaptive/dynamic when available, else no-op. Levels clamp per model. Former `*think()` methods are removed — use `.effort(n).<model>()`. Kimi: `kimiK25()` / `kimiK26()`. Grok 4.20: `.grok420()` non-reasoning; `.effort(20+|-1).grok420()` selects reasoning.
+\* Gemini bands: 0–24 / 25–49 / 50–74 / 75–100. Gemini 3.7 Flash supports only `low` / `medium` / `high`, so the first two bands clamp to `low`; `-1` keeps its native `medium` default. DeepSeek `↑` = thinking on; `off` = thinking disabled. MiniMax `off`/`adaptive` = `thinking.disabled` / `thinking.type=adaptive`. Gemini 2.5 maps 0–100 to `thinkingBudget`. Anthropic: adaptive + `output_config.effort` on Claude 5 / Fable / Opus 4.6+ / Sonnet 4.6+; Sonnet 4.5 / Haiku 4.5 use `thinking.type=enabled` + `budget_tokens`. Grok 4.6 maps 0–39 / 40–59 / 60–79 / 80–100 to `low` / `medium` / `high` / `xhigh`; without effort it uses native `high`. `-1` = adaptive/dynamic when available, else no-op. Levels clamp per model. Former `*think()` methods are removed — use `.effort(n).<model>()`. Kimi: `kimiK25()` / `kimiK26()`. Grok 4.20: `.grok420()` non-reasoning; `.effort(20+|-1).grok420()` selects reasoning.
 
 ## Available Model Shorthands
 
@@ -127,7 +145,7 @@ ModelMix.new({ config: { effort: 80 } })
 Use `.effort(n)` (or `config.effort`) to enable Anthropic thinking — e.g. `.effort(100).opus50()`. `fable5()` and `opus5()` remain available as compatibility aliases.
 
 ### Google
-`gemini3pro()` `gemini3flash()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()` `gemini25pro()` `gemini25flash()`
+`gemini3pro()` `gemini3flash()` `gemini37flash()` `gemini36flash()` `gemini35flash()` `gemini35flashLite()` `gemini31flashLite()` `gemini25pro()` `gemini25flash()`
 
 ### Grok
 `grok46()` `grok45()` `grok43()` `grok420multiAgent()` `grok420()`
@@ -302,7 +320,7 @@ const model = ModelMix.new().gpt5mini().addText("Hello!");
 const text = await model.message();
 console.log(model.lastRaw.tokens);
 // {
-//   input: 1200, output: 50, total: 1250,
+//   input: 1200, output: 50, thinking: 0, total: 1250,
 //   cached: 1024, cacheWrite: 0, uncachedInput: 176,
 //   cacheWrite5m: 0, cacheWrite1h: 0,
 //   cacheHitRate: 0.8533, cacheSavings: 0.00018432,
@@ -586,6 +604,7 @@ const model = ModelMix.new({
 | `.addTools([{tool, callback}])` | `this` | Register multiple tools |
 | `.removeTool(name)` | `this` | Remove a tool |
 | `.listTools()` | `{local, mcp}` | List registered tools |
+| `.use(plugin)` | `this` | Register instance-scoped execution middleware |
 | `.new()` | `ModelMix` | Clone instance sharing models |
 | `.attach(key, provider)` | `this` | Attach custom provider |
 

package/test/effort.test.js

@@ -121,6 +121,19 @@ describe('Unified effort scale', () => {
             });
         });
 
+        it('clamps Gemini 3.7 Flash to low, medium, and high', () => {
+            expect(mapEffort('google', 0, 'gemini-3.7-flash')).to.deep.equal({
+                thinkingConfig: { thinkingLevel: 'low' }
+            });
+            expect(mapEffort('google', 50, 'gemini-3.7-flash')).to.deep.equal({
+                thinkingConfig: { thinkingLevel: 'medium' }
+            });
+            expect(mapEffort('google', 100, 'gemini-3.7-flash')).to.deep.equal({
+                thinkingConfig: { thinkingLevel: 'high' }
+            });
+            expect(mapEffort('google', -1, 'gemini-3.7-flash')).to.equal(null);
+        });
+
         it('clamps Gemini levels for models with fewer steps', () => {
             expect(mapEffort('google', 10, 'gemini-3-pro-preview')).to.deep.equal({
                 thinkingConfig: { thinkingLevel: 'low' }
@@ -384,7 +397,7 @@ describe('Unified effort scale', () => {
                 await google.create({
                     config: { system: 'sys' },
                     options: {
-                        model: 'gemini-3.6-flash',
+                        model: 'gemini-3.7-flash',
                         max_tokens: 100,
                         messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
                         thinkingConfig: { thinkingLevel: 'low' }

package/test/live.mcp.js

@@ -181,8 +181,8 @@ describe('Live MCP Integration Tests', function () {
             }
         });
 
-        it('should use custom MCP tools with Gemini 3 Flash', async function () {
-            const model = ModelMix.new(setup).gemini3flash();
+        it('should use custom MCP tools with Gemini 3.7 Flash', async function () {
+            const model = ModelMix.new(setup).gemini37flash();
 
             // Add password generator tool
             model.addTool({
@@ -220,7 +220,7 @@ describe('Live MCP Integration Tests', function () {
             model.addText('Generate a secure password of 16 characters with symbols.');
 
             const response = await model.message();
-            console.log(`Gemini 3 Flash with MCP tools: ${response}`);
+            console.log(`Gemini 3.7 Flash with MCP tools: ${response}`);
 
             expect(response).to.be.a('string');
             // Check password is mentioned and a generated password string is present
@@ -407,8 +407,8 @@ describe('Live MCP Integration Tests', function () {
             expect(result.factorial_result).to.equal(120);
         });
 
-        it('should use MCP tools with JSON output using Gemini 3 Flash', async function () {
-            const model = ModelMix.new(setup).gemini3flash();
+        it('should use MCP tools with JSON output using Gemini 3.7 Flash', async function () {
+            const model = ModelMix.new(setup).gemini37flash();
 
             // Add system info tool
             model.addTool({
@@ -447,7 +447,7 @@ describe('Live MCP Integration Tests', function () {
                 generated_at: ""
             });
 
-            console.log(`Gemini 3 Flash with MCP tools JSON result:`, result);
+            console.log(`Gemini 3.7 Flash with MCP tools JSON result:`, result);
 
             expect(result).to.be.an('object');
             expect(result.timestamp).to.be.a('number');

package/test/live.test.js

@@ -59,7 +59,7 @@ describe('Live Integration Tests', function () {
         });
 
         it('should process images with Google Gemini', async function () {
-            const model = ModelMix.new(setup).gemini3flash();
+            const model = ModelMix.new(setup).gemini37flash();
 
             model.addImageFromUrl(blueSquareBase64)
                 .addText('What color is this image? Answer in one word only.');
@@ -120,7 +120,7 @@ describe('Live Integration Tests', function () {
         });
 
         it('should return structured JSON with Google Gemini', async function () {
-            const model = ModelMix.new(setup).gemini3flash();
+            const model = ModelMix.new(setup).gemini37flash();
 
             model.addText('Generate information about a fictional city.');