modelmix 5.0.2 → 5.0.3

package/plugins/rlm/index.d.ts

@@ -0,0 +1,194 @@
+export interface NumericStats {
+  min: number;
+  max: number;
+  average: number;
+  total: number;
+}
+
+export interface StringSizeStats {
+  characters: NumericStats;
+  utf8Bytes: NumericStats;
+  lines: NumericStats;
+  paragraphs: NumericStats;
+}
+
+export interface VariableDescriptor {
+  path: string;
+  type: string;
+  estimatedBytes: number;
+  characters?: number;
+  utf16CodeUnits?: number;
+  utf8Bytes?: number;
+  lines?: number;
+  paragraphs?: number;
+  items?: number;
+  itemSize?: NumericStats;
+  itemShape?: Record<string, unknown>;
+  properties?: number;
+  children?: Record<string, VariableDescriptor>;
+}
+
+export interface VariableManifest {
+  sizeBasis: 'serialized-json-utf8';
+  variables: number;
+  estimatedBytes: number;
+  descriptors: Record<string, VariableDescriptor>;
+}
+
+export interface PlannerLimits {
+  maxQueryBytes: number;
+  sandboxMemoryBytes: number;
+  maxConcurrentQueries: number;
+  maxCalls: number;
+  maxOutputBytes: number;
+  maxGeneratedTokens: number;
+  maxWallTimeMs: number;
+}
+
+export interface MarkdownListItem {
+  text: string;
+  source: string;
+  lists: MarkdownList[];
+}
+
+export interface MarkdownList {
+  ordered: boolean;
+  start: number | null;
+  items: MarkdownListItem[];
+}
+
+export interface MarkdownSection {
+  id: string;
+  path: string[];
+  title: string;
+  depth: number;
+  order: number;
+  heading: string;
+  body: string;
+  lists: MarkdownList[];
+  children: MarkdownSection[];
+}
+
+export interface MarkdownDocument {
+  format: 'markdown';
+  preamble: {
+    source: string;
+    lists: MarkdownList[];
+  };
+  sections: MarkdownSection[];
+  stats: {
+    characters: number;
+    utf16CodeUnits: number;
+    utf8Bytes: number;
+    lines: number;
+    sectionCount: number;
+  };
+}
+
+export declare function parseMarkdownDocument(source: string): Promise<MarkdownDocument>;
+
+export declare function reconstructMarkdownDocument(document: MarkdownDocument): string;
+
+export declare function describeVariables(
+  variables: Record<string, unknown>
+): VariableManifest;
+
+export interface PlannerTemplateData {
+  variableManifest: string;
+  processingLimits: string;
+  planningHints: string;
+  workerManifest: string;
+  outputRequirements: string;
+  maxQueryBytes: number;
+  maxConcurrentQueries: number;
+}
+
+export interface PlannerInvocation {
+  systemFile: string;
+  assign: PlannerTemplateData;
+  messages: Array<{
+    role: 'user';
+    content: Array<{ type: 'text'; text: string }>;
+  }>;
+  plugins: { exclude: ['rlm'] };
+  history: false;
+  outputMode: 'raw';
+}
+
+export declare function plannerTemplateData(input: {
+  variables: Record<string, unknown>;
+  limits: PlannerLimits;
+  workerManifest: Record<string, unknown>;
+  outputMode?: 'message' | 'json' | 'block' | 'raw';
+  outputSchema?: Record<string, unknown> | null;
+}): PlannerTemplateData;
+
+export declare function createPlannerInvocation(input: {
+  task: string;
+  variables: Record<string, unknown>;
+  limits: PlannerLimits;
+  workerManifest: Record<string, unknown>;
+  outputMode?: 'message' | 'json' | 'block' | 'raw';
+  outputSchema?: Record<string, unknown> | null;
+}): PlannerInvocation;
+
+export interface RlmWorkerMetadata {
+  intelligence: number;
+  cost: number;
+  speed: number;
+  description: string;
+}
+
+export type RlmWorker = RlmWorkerMetadata & (
+  | { model: object; useParent?: never }
+  | { model?: never; useParent: true }
+);
+
+export interface RlmSandbox {
+  execute(input: {
+    code: string;
+    variables: Record<string, unknown>;
+    query: (input: {
+      worker: string;
+      system: string;
+      message: string;
+    }) => Promise<string>;
+    limits: PlannerLimits;
+    execution: {
+      executionId: string;
+      parentExecutionId: string | null;
+      depth: number;
+    };
+    timeoutMs: number;
+  }): Promise<unknown>;
+}
+
+export declare function createIsolatedVmSandbox(): RlmSandbox;
+
+export interface RlmDocumentInput {
+  format: 'markdown';
+  content: string;
+}
+
+export interface RlmOptions {
+  maxDepth: number;
+  variables?: Record<string, unknown>;
+  documents?: Record<string, RlmDocumentInput>;
+  workers: Record<string, RlmWorker>;
+  limits: PlannerLimits;
+  sandbox?: RlmSandbox;
+}
+
+export declare class RlmLimitError extends Error {
+  limit: string;
+}
+
+export declare function createWorkerCatalog(workers: Record<string, RlmWorker>): {
+  get(name: string): object | undefined;
+  manifest: Record<string, RlmWorkerMetadata>;
+};
+
+export declare function rlm(options: RlmOptions): {
+  name: 'rlm';
+  execute(context: unknown): Promise<Record<string, unknown>>;
+};

package/plugins/rlm/index.js

@@ -0,0 +1,25 @@
+const { describeVariables } = require('./lib/variable-descriptors');
+const {
+    createPlannerInvocation,
+    plannerTemplateData
+} = require('./lib/planner-prompt');
+const { rlm } = require('./lib/plugin');
+const { RlmLimitError } = require('./lib/budget');
+const { createIsolatedVmSandbox } = require('./lib/isolated-vm-sandbox');
+const {
+    parseMarkdownDocument,
+    reconstructMarkdownDocument
+} = require('./lib/markdown');
+const { createWorkerCatalog } = require('./lib/worker-catalog');
+
+module.exports = {
+    RlmLimitError,
+    createIsolatedVmSandbox,
+    createWorkerCatalog,
+    describeVariables,
+    createPlannerInvocation,
+    plannerTemplateData,
+    parseMarkdownDocument,
+    reconstructMarkdownDocument,
+    rlm
+};

package/plugins/rlm/lib/budget.js

@@ -0,0 +1,153 @@
+class RlmLimitError extends Error {
+    constructor(limit, message) {
+        super(message);
+        this.name = 'RlmLimitError';
+        this.limit = limit;
+    }
+}
+
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive integer.`);
+    }
+    return value;
+}
+
+function validateRuntimeLimits(limits) {
+    if (!limits || typeof limits !== 'object' || Array.isArray(limits)) {
+        throw new TypeError('limits must be a plain object.');
+    }
+    return Object.freeze({
+        maxQueryBytes: positiveInteger(limits.maxQueryBytes, 'limits.maxQueryBytes'),
+        sandboxMemoryBytes: positiveInteger(limits.sandboxMemoryBytes, 'limits.sandboxMemoryBytes'),
+        maxConcurrentQueries: positiveInteger(
+            limits.maxConcurrentQueries,
+            'limits.maxConcurrentQueries'
+        ),
+        maxCalls: positiveInteger(limits.maxCalls, 'limits.maxCalls'),
+        maxOutputBytes: positiveInteger(limits.maxOutputBytes, 'limits.maxOutputBytes'),
+        maxGeneratedTokens: positiveInteger(
+            limits.maxGeneratedTokens,
+            'limits.maxGeneratedTokens'
+        ),
+        maxWallTimeMs: positiveInteger(limits.maxWallTimeMs, 'limits.maxWallTimeMs')
+    });
+}
+
+function createRuntimeBudget(limits, now = Date.now) {
+    const validated = validateRuntimeLimits(limits);
+    const startedAt = now();
+    const queue = [];
+    let calls = 0;
+    let active = 0;
+    let peakConcurrency = 0;
+    let outputBytes = 0;
+    let generatedTokens = 0;
+
+    const checkTime = () => {
+        if (now() - startedAt > validated.maxWallTimeMs) {
+            throw new RlmLimitError('maxWallTimeMs', 'RLM wall-time limit exceeded.');
+        }
+    };
+    const acquire = () => new Promise(resolve => {
+        if (active < validated.maxConcurrentQueries) {
+            active += 1;
+            peakConcurrency = Math.max(peakConcurrency, active);
+            resolve();
+        } else {
+            queue.push(resolve);
+        }
+    });
+    const release = () => {
+        const next = queue.shift();
+        if (next) {
+            next();
+        } else {
+            active -= 1;
+        }
+    };
+
+    const accountResult = result => {
+        const message = result?.message ?? '';
+        const resultBytes = Buffer.byteLength(
+            typeof message === 'string' ? message : JSON.stringify(message),
+            'utf8'
+        );
+        outputBytes += resultBytes;
+        generatedTokens += Number.isFinite(result?.tokens?.output)
+            ? Math.max(0, result.tokens.output)
+            : 0;
+        if (outputBytes > validated.maxOutputBytes) {
+            throw new RlmLimitError('maxOutputBytes', 'RLM output byte limit exceeded.');
+        }
+        if (generatedTokens > validated.maxGeneratedTokens) {
+            throw new RlmLimitError(
+                'maxGeneratedTokens',
+                'RLM generated-token limit exceeded.'
+            );
+        }
+    };
+    const runCall = async ({ payloadBytes, enforcePayload }, operation) => {
+        checkTime();
+        if (enforcePayload && payloadBytes > validated.maxQueryBytes) {
+            throw new RlmLimitError(
+                'maxQueryBytes',
+                `RLM query payload is ${payloadBytes} bytes; limit is ${validated.maxQueryBytes}.`
+            );
+        }
+        if (calls >= validated.maxCalls) {
+            throw new RlmLimitError('maxCalls', 'RLM call limit exceeded.');
+        }
+        calls += 1;
+        await acquire();
+        try {
+            checkTime();
+            const result = await operation();
+            checkTime();
+            accountResult(result);
+            return result;
+        } finally {
+            release();
+        }
+    };
+
+    return {
+        limits: validated,
+        assertQueryPayload(payloadBytes) {
+            checkTime();
+            if (payloadBytes > validated.maxQueryBytes) {
+                throw new RlmLimitError(
+                    'maxQueryBytes',
+                    `RLM query payload is ${payloadBytes} bytes; limit is ${validated.maxQueryBytes}.`
+                );
+            }
+        },
+        async runQuery({ payloadBytes }, operation) {
+            return runCall({ payloadBytes, enforcePayload: true }, operation);
+        },
+        async runPlanner(operation) {
+            return runCall({ payloadBytes: 0, enforcePayload: false }, operation);
+        },
+        accountFinalOutput(value) {
+            const message = typeof value === 'string' ? value : JSON.stringify(value);
+            accountResult({ message });
+            checkTime();
+        },
+        snapshot() {
+            return {
+                calls,
+                active,
+                peakConcurrency,
+                outputBytes,
+                generatedTokens,
+                elapsedMs: now() - startedAt
+            };
+        }
+    };
+}
+
+module.exports = {
+    RlmLimitError,
+    createRuntimeBudget,
+    validateRuntimeLimits
+};

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

@@ -0,0 +1,90 @@
+const ivm = require('isolated-vm');
+const { RlmLimitError } = require('./budget');
+
+const MINIMUM_ISOLATE_MEMORY_BYTES = 8 * 1024 * 1024;
+
+function timeoutError() {
+    return new RlmLimitError('maxWallTimeMs', 'RLM wall-time limit exceeded.');
+}
+
+function memoryError(error) {
+    return /memory|heap|array buffer allocation/i.test(error.message);
+}
+
+function executionTimeoutError(error) {
+    return /timed out|execution terminated/i.test(error.message);
+}
+
+function sandboxSource(code) {
+    return `'use strict';\n${code}`;
+}
+
+function createIsolatedVmSandbox() {
+    return {
+        async execute({ code, variables, query, limits, timeoutMs }) {
+            if (limits.sandboxMemoryBytes < MINIMUM_ISOLATE_MEMORY_BYTES) {
+                throw new TypeError(
+                    `limits.sandboxMemoryBytes must be at least ${MINIMUM_ISOLATE_MEMORY_BYTES}.`
+                );
+            }
+            const isolate = new ivm.Isolate({
+                memoryLimit: Math.ceil(limits.sandboxMemoryBytes / (1024 * 1024))
+            });
+            let timedOut = false;
+            const timeout = setTimeout(() => {
+                timedOut = true;
+                if (!isolate.isDisposed) isolate.dispose();
+            }, timeoutMs);
+
+            try {
+                const context = await isolate.createContext();
+                const jail = context.global;
+                await jail.set(
+                    'variables',
+                    new ivm.ExternalCopy(variables).copyInto()
+                );
+                await jail.set('__queryReference', new ivm.Reference(query));
+                await context.eval(`
+                    (() => {
+                        const queryReference = globalThis.__queryReference;
+                        Object.defineProperty(globalThis, 'query', {
+                            configurable: false,
+                            enumerable: true,
+                            writable: false,
+                            value(input) {
+                                return queryReference.apply(undefined, [input], {
+                                    arguments: { copy: true },
+                                    result: { promise: true, copy: true }
+                                });
+                            }
+                        });
+                        delete globalThis.__queryReference;
+                    })();
+                `, { timeout: timeoutMs });
+                return await context.eval(sandboxSource(code), {
+                    copy: true,
+                    filename: 'rlm-planner.js',
+                    promise: true,
+                    timeout: timeoutMs
+                });
+            } catch (error) {
+                if (memoryError(error)) {
+                    throw new RlmLimitError(
+                        'sandboxMemoryBytes',
+                        'RLM sandbox memory limit exceeded.'
+                    );
+                }
+                if (timedOut || executionTimeoutError(error)) throw timeoutError();
+                throw error;
+            } finally {
+                clearTimeout(timeout);
+                if (!isolate.isDisposed) isolate.dispose();
+            }
+        }
+    };
+}
+
+module.exports = {
+    MINIMUM_ISOLATE_MEMORY_BYTES,
+    createIsolatedVmSandbox
+};

package/plugins/rlm/lib/markdown.js

@@ -0,0 +1,156 @@
+let parserPromise;
+
+function loadParser() {
+    if (!parserPromise) {
+        parserPromise = import('mdast-util-from-markdown')
+            .then(module => module.fromMarkdown);
+    }
+    return parserPromise;
+}
+
+function nodeText(node) {
+    if (typeof node.value === 'string') return node.value;
+    if (!Array.isArray(node.children)) return '';
+    return node.children.map(nodeText).join('');
+}
+
+function sourceSlice(source, node) {
+    const start = node.position?.start?.offset;
+    const end = node.position?.end?.offset;
+    if (!Number.isInteger(start) || !Number.isInteger(end)) return '';
+    return source.slice(start, end);
+}
+
+function listValue(node, source) {
+    return {
+        ordered: node.ordered,
+        start: node.ordered ? (node.start || 1) : null,
+        items: node.children.map(item => {
+            const nestedLists = (item.children || [])
+                .filter(child => child.type === 'list')
+                .map(child => listValue(child, source));
+            const text = (item.children || [])
+                .filter(child => child.type !== 'list')
+                .map(nodeText)
+                .join('\n');
+            return {
+                text,
+                source: sourceSlice(source, item),
+                lists: nestedLists
+            };
+        })
+    };
+}
+
+function listsBetween(children, startIndex, endIndex, source) {
+    return children
+        .slice(startIndex, endIndex)
+        .filter(node => node.type === 'list')
+        .map(node => listValue(node, source));
+}
+
+function slugify(value) {
+    const slug = value
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'section';
+}
+
+function uniqueId(title, counts) {
+    const base = slugify(title);
+    const count = (counts.get(base) || 0) + 1;
+    counts.set(base, count);
+    return count === 1 ? base : `${base}-${count}`;
+}
+
+function markdownStats(source, sectionCount) {
+    return {
+        characters: Array.from(source).length,
+        utf16CodeUnits: source.length,
+        utf8Bytes: Buffer.byteLength(source, 'utf8'),
+        lines: source.length === 0 ? 0 : source.split(/\r\n|\n|\r/).length,
+        sectionCount
+    };
+}
+
+async function parseMarkdownDocument(source) {
+    if (typeof source !== 'string') {
+        throw new TypeError('Markdown document content must be a string.');
+    }
+    const fromMarkdown = await loadParser();
+    const tree = fromMarkdown(source);
+    const headings = [];
+    for (let index = 0; index < tree.children.length; index += 1) {
+        const node = tree.children[index];
+        if (node.type === 'heading') headings.push({ index, node });
+    }
+
+    const firstHeadingOffset = headings[0]?.node.position?.start?.offset ?? source.length;
+    const preambleEndIndex = headings[0]?.index ?? tree.children.length;
+    const document = {
+        format: 'markdown',
+        preamble: {
+            source: source.slice(0, firstHeadingOffset),
+            lists: listsBetween(tree.children, 0, preambleEndIndex, source)
+        },
+        sections: [],
+        stats: markdownStats(source, headings.length)
+    };
+    const stack = [];
+    const counts = new Map();
+
+    for (let headingIndex = 0; headingIndex < headings.length; headingIndex += 1) {
+        const { index, node } = headings[headingIndex];
+        const next = headings[headingIndex + 1];
+        const headingStart = node.position.start.offset;
+        const headingEnd = node.position.end.offset;
+        const bodyEnd = next?.node.position.start.offset ?? source.length;
+        const bodyEndIndex = next?.index ?? tree.children.length;
+        const title = nodeText(node);
+        const id = uniqueId(title, counts);
+
+        while (stack.length > 0 && stack[stack.length - 1].depth >= node.depth) {
+            stack.pop();
+        }
+        const parent = stack[stack.length - 1] || null;
+        const section = {
+            id,
+            path: parent ? [...parent.path, id] : [id],
+            title,
+            depth: node.depth,
+            order: headingIndex,
+            heading: source.slice(headingStart, headingEnd),
+            body: source.slice(headingEnd, bodyEnd),
+            lists: listsBetween(tree.children, index + 1, bodyEndIndex, source),
+            children: []
+        };
+        if (parent) parent.children.push(section);
+        else document.sections.push(section);
+        stack.push(section);
+    }
+
+    return document;
+}
+
+function renderSections(sections) {
+    return sections.map(section => (
+        section.heading
+        + section.body
+        + renderSections(section.children)
+    )).join('');
+}
+
+function reconstructMarkdownDocument(document) {
+    if (!document || document.format !== 'markdown' || !Array.isArray(document.sections)) {
+        throw new TypeError('document must be a parsed Markdown document.');
+    }
+    return `${document.preamble?.source || ''}${renderSections(document.sections)}`;
+}
+
+module.exports = {
+    parseMarkdownDocument,
+    reconstructMarkdownDocument
+};