modelmix 5.0.1 → 5.0.3

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

@@ -0,0 +1,228 @@
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+function roundAverage(total, count) {
+    return count === 0 ? 0 : Number((total / count).toFixed(2));
+}
+
+function numericStats(values) {
+    if (values.length === 0) {
+        return { min: 0, max: 0, average: 0, total: 0 };
+    }
+    let min = values[0];
+    let max = values[0];
+    let total = 0;
+    for (const value of values) {
+        min = Math.min(min, value);
+        max = Math.max(max, value);
+        total += value;
+    }
+    return {
+        min,
+        max,
+        average: roundAverage(total, values.length),
+        total
+    };
+}
+
+function valueType(value) {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    return typeof value;
+}
+
+function primitiveSerializedBytes(value, path) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    } catch (error) {
+        throw new TypeError(`External variable ${path} is not JSON-serializable: ${error.message}`);
+    }
+    if (serialized === undefined) {
+        throw new TypeError(`External variable ${path} is not JSON-serializable.`);
+    }
+    return Buffer.byteLength(serialized, 'utf8');
+}
+
+function objectSerializedBytes(value, childDescriptors) {
+    const keys = Object.keys(value);
+    let bytes = 2;
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
+        bytes += primitiveSerializedBytes(key, key) + 1 + childDescriptors[key].estimatedBytes;
+        if (index > 0) bytes += 1;
+    }
+    return bytes;
+}
+
+function arraySerializedBytes(itemBytes) {
+    if (itemBytes.length === 0) return 2;
+    return 2
+        + itemBytes.reduce((sum, bytes) => sum + bytes, 0)
+        + itemBytes.length - 1;
+}
+
+function countLines(value) {
+    return value.length === 0 ? 0 : value.split(/\r\n|\n|\r/).length;
+}
+
+function countParagraphs(value) {
+    const trimmed = value.trim();
+    return trimmed.length === 0
+        ? 0
+        : trimmed.split(/(?:\r\n|\n|\r)[\t ]*(?:\r\n|\n|\r)+/).length;
+}
+
+function stringMetrics(value) {
+    return {
+        characters: Array.from(value).length,
+        utf16CodeUnits: value.length,
+        utf8Bytes: Buffer.byteLength(value, 'utf8'),
+        lines: countLines(value),
+        paragraphs: countParagraphs(value)
+    };
+}
+
+function incrementType(types, value) {
+    const type = valueType(value);
+    types[type] = (types[type] || 0) + 1;
+}
+
+function summarizeStringValues(values) {
+    const metrics = values.map(stringMetrics);
+    return {
+        characters: numericStats(metrics.map(metric => metric.characters)),
+        utf8Bytes: numericStats(metrics.map(metric => metric.utf8Bytes)),
+        lines: numericStats(metrics.map(metric => metric.lines)),
+        paragraphs: numericStats(metrics.map(metric => metric.paragraphs))
+    };
+}
+
+function summarizeObjectArray(items) {
+    const keys = [...new Set(items.flatMap(item => Object.keys(item)))].sort();
+    const properties = {};
+
+    for (const key of keys) {
+        const values = items
+            .filter(item => Object.prototype.hasOwnProperty.call(item, key))
+            .map(item => item[key]);
+        const types = {};
+        for (const value of values) incrementType(types, value);
+        const property = {
+            present: values.length,
+            missing: items.length - values.length,
+            types
+        };
+        if (values.length > 0 && values.every(value => typeof value === 'string')) {
+            property.stringSize = summarizeStringValues(values);
+        }
+        properties[key] = property;
+    }
+
+    return {
+        type: 'object',
+        properties
+    };
+}
+
+function summarizeArrayItems(items) {
+    const types = {};
+    for (const item of items) incrementType(types, item);
+    const summary = { types };
+
+    if (items.length > 0 && items.every(item => typeof item === 'string')) {
+        summary.type = 'string';
+        summary.stringSize = summarizeStringValues(items);
+    } else if (items.length > 0 && items.every(isPlainObject)) {
+        Object.assign(summary, summarizeObjectArray(items));
+    }
+
+    return summary;
+}
+
+function describeValue(value, path, ancestors) {
+    const type = valueType(value);
+    if (type === 'undefined' || type === 'function' || type === 'symbol' || type === 'bigint') {
+        throw new TypeError(`External variable ${path} has unsupported type ${type}.`);
+    }
+    if (type === 'number' && !Number.isFinite(value)) {
+        throw new TypeError(`External variable ${path} must contain only finite numbers.`);
+    }
+    if (type === 'object' && value !== null && !isPlainObject(value)) {
+        throw new TypeError(`External variable ${path} must contain only plain objects.`);
+    }
+    if (value && typeof value === 'object') {
+        if (ancestors.has(value)) {
+            throw new TypeError(`External variable ${path} contains a circular reference.`);
+        }
+        ancestors.add(value);
+    }
+
+    let descriptor;
+    if (type === 'string') {
+        descriptor = {
+            path,
+            type,
+            estimatedBytes: primitiveSerializedBytes(value, path),
+            ...stringMetrics(value)
+        };
+    } else if (type === 'array') {
+        const itemBytes = [];
+        for (let index = 0; index < value.length; index += 1) {
+            const itemDescriptor = describeValue(value[index], `${path}[${index}]`, ancestors);
+            itemBytes.push(itemDescriptor.estimatedBytes);
+        }
+        descriptor = {
+            path,
+            type,
+            items: value.length,
+            estimatedBytes: arraySerializedBytes(itemBytes),
+            itemSize: numericStats(itemBytes),
+            itemShape: summarizeArrayItems(value)
+        };
+    } else if (type === 'object') {
+        const properties = {};
+        for (const key of Object.keys(value).sort()) {
+            properties[key] = describeValue(value[key], `${path}.${key}`, ancestors);
+        }
+        descriptor = {
+            path,
+            type,
+            properties: Object.keys(properties).length,
+            estimatedBytes: objectSerializedBytes(value, properties),
+            children: properties
+        };
+    } else {
+        descriptor = {
+            path,
+            type,
+            estimatedBytes: primitiveSerializedBytes(value, path)
+        };
+    }
+
+    if (value && typeof value === 'object') ancestors.delete(value);
+    return descriptor;
+}
+
+function describeVariables(variables) {
+    if (!isPlainObject(variables)) {
+        throw new TypeError('External variables must be a plain object.');
+    }
+    const descriptors = {};
+    for (const name of Object.keys(variables).sort()) {
+        descriptors[name] = describeValue(variables[name], name, new WeakSet());
+    }
+    return {
+        sizeBasis: 'serialized-json-utf8',
+        variables: Object.keys(descriptors).length,
+        estimatedBytes: objectSerializedBytes(variables, descriptors),
+        descriptors
+    };
+}
+
+module.exports = {
+    describeVariables
+};

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

@@ -0,0 +1,70 @@
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+function finiteRating(value, path) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${path} must be a non-negative finite number.`);
+    }
+    return value;
+}
+
+function validateModel(value, path) {
+    if (!value || typeof value !== 'object' || !Array.isArray(value.models)) {
+        throw new TypeError(`${path} must be a ModelMix instance.`);
+    }
+    return value;
+}
+
+function createWorkerCatalog(workers) {
+    if (!isPlainObject(workers) || Object.keys(workers).length === 0) {
+        throw new TypeError('workers must be a non-empty plain object.');
+    }
+
+    const models = new Map();
+    const manifest = {};
+    for (const name of Object.keys(workers).sort()) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+            throw new TypeError(`Worker name "${name}" must use letters, numbers, underscores, or hyphens.`);
+        }
+        const worker = workers[name];
+        if (!isPlainObject(worker)) {
+            throw new TypeError(`Worker "${name}" must be a plain object.`);
+        }
+        if (typeof worker.description !== 'string' || worker.description.trim().length === 0) {
+            throw new TypeError(`Worker "${name}" description must be a non-empty string.`);
+        }
+        const usesParent = worker.useParent === true;
+        if (usesParent === (worker.model !== undefined)) {
+            throw new TypeError(
+                `Worker "${name}" must define exactly one of model or useParent: true.`
+            );
+        }
+        models.set(
+            name,
+            usesParent ? undefined : validateModel(worker.model, `Worker "${name}" model`)
+        );
+        manifest[name] = {
+            intelligence: finiteRating(worker.intelligence, `Worker "${name}" intelligence`),
+            cost: finiteRating(worker.cost, `Worker "${name}" cost`),
+            speed: finiteRating(worker.speed, `Worker "${name}" speed`),
+            description: worker.description
+        };
+    }
+
+    return {
+        get(name) {
+            if (typeof name !== 'string' || !models.has(name)) {
+                throw new Error(`Unknown RLM worker "${name}".`);
+            }
+            return models.get(name);
+        },
+        manifest
+    };
+}
+
+module.exports = {
+    createWorkerCatalog
+};

package/plugins/rlm/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@modelmix/rlm",
+  "version": "0.0.0",
+  "description": "Recursive Language Model plugin for ModelMix.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/",
+    "prompts/"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "isolated-vm": "6.0.2",
+    "mdast-util-from-markdown": "2.0.3"
+  }
+}

package/plugins/rlm/prompts/partials/processing-rules.md

@@ -0,0 +1,8 @@
+## Required processing rules
+
+- Never send more than <%- maxQueryBytes %> UTF-8 bytes in one `query()` payload.
+- Split oversized strings and string fields at paragraph or other semantic boundaries.
+- Batch compatible array items when each item fits within the payload limit.
+- Process independent batches concurrently with at most <%- maxConcurrentQueries %> active queries.
+- Preserve source order and complete coverage when reassembling the final output.
+- Inspect external variables in the sandbox; never ask the planner to reproduce hidden content.

package/plugins/rlm/prompts/planner.md

@@ -0,0 +1,53 @@
+# Recursive Language Model Planner
+
+Generate an executable JavaScript orchestration program for the user's task. The source data remains in external sandbox variables and is not present in this prompt.
+
+## External variable manifest
+
+The following JSON contains metadata only. Variable values must be inspected inside the sandbox.
+
+```json
+<%- variableManifest %>
+```
+
+## Processing limits
+
+```json
+<%- processingLimits %>
+```
+
+## Planning hints
+
+These hints are derived from serialized variable sizes and query limits. Apply them to the actual task rather than treating them as mandatory task-specific operations.
+
+```json
+<%- planningHints %>
+```
+
+## Worker catalog
+
+Choose a worker by its registered name for every `query()` call. The catalog contains developer-supplied decision metadata only; model objects, provider configuration, and credentials are not exposed.
+
+```json
+<%- workerManifest %>
+```
+
+## Sandbox API
+
+```js
+const result = await query({
+    worker: 'registered-worker-name',
+    system: 'Focused instructions for this subtask.',
+    message: externalVariableOrFragment
+});
+```
+
+<%- include('partials/processing-rules.md') %>
+
+## Output requirements
+
+```json
+<%- outputRequirements %>
+```
+
+Return only an async JavaScript IIFE. The returned value must be the final result requested by the user. Do not return Markdown fences, explanations, or source data samples.

package/plugins/rlm/test/budget.test.js

@@ -0,0 +1,86 @@
+const { expect } = require('chai');
+const { RlmLimitError } = require('..');
+const { createRuntimeBudget } = require('../lib/budget');
+
+function limits(overrides = {}) {
+    return {
+        maxQueryBytes: 100,
+        sandboxMemoryBytes: 1024 * 1024,
+        maxConcurrentQueries: 2,
+        maxCalls: 4,
+        maxOutputBytes: 100,
+        maxGeneratedTokens: 20,
+        maxWallTimeMs: 1000,
+        ...overrides
+    };
+}
+
+describe('RLM runtime budget', () => {
+    it('limits active queries while allowing queued work to finish', async () => {
+        const budget = createRuntimeBudget(limits());
+        let active = 0;
+        let peak = 0;
+        const operation = async value => budget.runQuery({ payloadBytes: 10 }, async () => {
+            active += 1;
+            peak = Math.max(peak, active);
+            await new Promise(resolve => setTimeout(resolve, 10));
+            active -= 1;
+            return { message: value, tokens: { output: 1 } };
+        });
+
+        const results = await Promise.all([
+            operation('a'),
+            operation('b'),
+            operation('c'),
+            operation('d')
+        ]);
+
+        expect(results.map(result => result.message)).to.deep.equal(['a', 'b', 'c', 'd']);
+        expect(peak).to.equal(2);
+        expect(budget.snapshot()).to.include({
+            calls: 4,
+            active: 0,
+            peakConcurrency: 2,
+            outputBytes: 4,
+            generatedTokens: 4
+        });
+    });
+
+    it('fails clearly on payload, call, output, and token limits', async () => {
+        const payloadBudget = createRuntimeBudget(limits());
+        expect(() => payloadBudget.assertQueryPayload(101))
+            .to.throw(RlmLimitError).with.property('limit', 'maxQueryBytes');
+
+        const callBudget = createRuntimeBudget(limits({ maxCalls: 1 }));
+        await callBudget.runPlanner(async () => ({ message: 'planner' }));
+        let callFailure;
+        try {
+            await callBudget.runPlanner(async () => ({ message: 'again' }));
+        } catch (error) {
+            callFailure = error;
+        }
+        expect(callFailure).to.be.instanceOf(RlmLimitError);
+        expect(callFailure.limit).to.equal('maxCalls');
+
+        const outputBudget = createRuntimeBudget(limits({ maxOutputBytes: 2 }));
+        let outputFailure;
+        try {
+            await outputBudget.runPlanner(async () => ({ message: 'long' }));
+        } catch (error) {
+            outputFailure = error;
+        }
+        expect(outputFailure.limit).to.equal('maxOutputBytes');
+
+        const tokenBudget = createRuntimeBudget(limits({ maxGeneratedTokens: 1 }));
+        let tokenFailure;
+        try {
+            await tokenBudget.runPlanner(async () => ({
+                message: '',
+                tokens: { output: 2 }
+            }));
+        } catch (error) {
+            tokenFailure = error;
+        }
+        expect(tokenFailure.limit).to.equal('maxGeneratedTokens');
+    });
+});

package/plugins/rlm/test/fixtures/book.md

@@ -0,0 +1,24 @@
+Introductory note with a [reference](https://example.com).
+
+- Preface item one
+- Preface item two
+
+# Chapter One
+
+Opening paragraph.
+
+- First point
+- Second point
+  - Nested point
+
+## Scene One
+
+```text
+# This is code, not a chapter
+```
+
+# Chapter One
+
+| Character | Role |
+| --- | --- |
+| Ada | Engineer |

package/plugins/rlm/test/isolated-vm-sandbox.test.js

@@ -0,0 +1,114 @@
+const { expect } = require('chai');
+const {
+    RlmLimitError,
+    createIsolatedVmSandbox
+} = require('..');
+
+function limits(sandboxMemoryBytes = 16 * 1024 * 1024) {
+    return { sandboxMemoryBytes };
+}
+
+describe('RLM isolated-vm sandbox', () => {
+    it('exposes only copied variables and the validated query callback', async () => {
+        const sandbox = createIsolatedVmSandbox();
+        const calls = [];
+        const value = await sandbox.execute({
+            code: `(async () => ({
+                item: variables.items[0],
+                response: await query({ worker: 'fast', system: 'Classify.', message: 'Ada' }),
+                globals: {
+                    process: typeof process,
+                    require: typeof require,
+                    fetch: typeof fetch,
+                    Buffer: typeof Buffer,
+                    query: typeof query
+                }
+            }))()`,
+            variables: { items: ['external'] },
+            query: async input => {
+                calls.push(input);
+                return 'person';
+            },
+            limits: limits(),
+            timeoutMs: 1000
+        });
+
+        expect(value).to.deep.equal({
+            item: 'external',
+            response: 'person',
+            globals: {
+                process: 'undefined',
+                require: 'undefined',
+                fetch: 'undefined',
+                Buffer: 'undefined',
+                query: 'function'
+            }
+        });
+        expect(calls).to.deep.equal([{
+            worker: 'fast',
+            system: 'Classify.',
+            message: 'Ada'
+        }]);
+    });
+
+    it('terminates programs that exceed their wall-time limit', async () => {
+        let failure;
+        try {
+            await createIsolatedVmSandbox().execute({
+                code: '(async () => { while (true) {} })()',
+                variables: {},
+                query: async () => '',
+                limits: limits(),
+                timeoutMs: 20
+            });
+        } catch (error) {
+            failure = error;
+        }
+
+        expect(failure).to.be.instanceOf(RlmLimitError);
+        expect(failure.limit).to.equal('maxWallTimeMs');
+    });
+
+    it('rejects memory limits below the isolated-vm minimum', async () => {
+        let failure;
+        try {
+            await createIsolatedVmSandbox().execute({
+                code: '(async () => "ok")()',
+                variables: {},
+                query: async () => '',
+                limits: limits(1024 * 1024),
+                timeoutMs: 1000
+            });
+        } catch (error) {
+            failure = error;
+        }
+
+        expect(failure).to.be.instanceOf(TypeError);
+        expect(failure.message).to.include('at least 8388608');
+    });
+
+    it('terminates programs that exceed the configured isolate heap', async () => {
+        let failure;
+        try {
+            await createIsolatedVmSandbox().execute({
+                code: `(() => {
+                    const values = [];
+                    while (true) {
+                        const item = new Uint8Array(1024 * 1024);
+                        for (let index = 0; index < item.length; index += 4096) item[index] = 1;
+                        values.push(item);
+                    }
+                })()`,
+                variables: {},
+                query: async () => '',
+                limits: limits(8 * 1024 * 1024),
+                timeoutMs: 2000
+            });
+        } catch (error) {
+            failure = error;
+        }
+
+        expect(failure).to.be.instanceOf(RlmLimitError);
+        expect(failure.limit).to.equal('sandboxMemoryBytes');
+    });
+});

package/plugins/rlm/test/markdown.test.js

@@ -0,0 +1,64 @@
+const fs = require('fs');
+const path = require('path');
+const { expect } = require('chai');
+const {
+    parseMarkdownDocument,
+    reconstructMarkdownDocument
+} = require('..');
+
+const FIXTURE_PATH = path.resolve(__dirname, 'fixtures/book.md');
+
+describe('RLM Markdown document mapping', () => {
+    it('creates a stable semantic tree and preserves exact source order', async () => {
+        const source = fs.readFileSync(FIXTURE_PATH, 'utf8');
+        const document = await parseMarkdownDocument(source);
+
+        expect(document.format).to.equal('markdown');
+        expect(document.stats).to.include({
+            utf8Bytes: Buffer.byteLength(source, 'utf8'),
+            sectionCount: 3
+        });
+        expect(document.preamble.source).to.include('Introductory note');
+        expect(document.preamble.lists[0].items.map(item => item.text)).to.deep.equal([
+            'Preface item one',
+            'Preface item two'
+        ]);
+        expect(document.sections).to.have.length(2);
+        expect(document.sections[0]).to.include({
+            id: 'chapter-one',
+            title: 'Chapter One',
+            depth: 1,
+            order: 0
+        });
+        expect(document.sections[0].path).to.deep.equal(['chapter-one']);
+        expect(document.sections[0].children[0]).to.include({
+            id: 'scene-one',
+            title: 'Scene One',
+            depth: 2,
+            order: 1
+        });
+        expect(document.sections[0].children[0].path).to.deep.equal([
+            'chapter-one',
+            'scene-one'
+        ]);
+        expect(document.sections[1].id).to.equal('chapter-one-2');
+        expect(document.sections[0].body).to.include('Opening paragraph.');
+        expect(document.sections[0].lists[0].items[1].lists[0].items[0].text)
+            .to.equal('Nested point');
+        expect(document.sections[0].children[0].body)
+            .to.include('# This is code, not a chapter');
+        expect(document.sections[1].body).to.include('| Character | Role |');
+        expect(reconstructMarkdownDocument(document)).to.equal(source);
+    });
+
+    it('maps heading-free Markdown to introductory content', async () => {
+        const source = 'Paragraph one.\n\n1. Alpha\n2. Beta\n';
+        const document = await parseMarkdownDocument(source);
+
+        expect(document.sections).to.deep.equal([]);
+        expect(document.preamble.source).to.equal(source);
+        expect(document.preamble.lists[0].items.map(item => item.text))
+            .to.deep.equal(['Alpha', 'Beta']);
+        expect(reconstructMarkdownDocument(document)).to.equal(source);
+    });
+});