modelmix 4.2.4 → 4.2.8

package/demo/rlm-fast.js

@@ -0,0 +1,239 @@
+process.loadEnvFile();
+import { ModelMix } from '../index.js';
+import ivm from 'isolated-vm';
+
+console.log('🧬 ModelMix - IVM + mmix Callback Demo');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// UTILITIES: Describe data for the model (without exposing raw content)
+// ═══════════════════════════════════════════════════════════════════════════
+
+function describeData(data, name = 'data') {
+    const type = Array.isArray(data) ? 'array' : typeof data;
+
+    if (Array.isArray(data)) {
+        const itemDescriptions = data.map((item, i) => {
+            if (typeof item === 'string') return `[${i}]: string, ${item.length} chars`;
+            if (typeof item === 'object') return `[${i}]: object with keys [${Object.keys(item).join(', ')}]`;
+            return `[${i}]: ${typeof item}`;
+        });
+        return `Variable '${name}' is an array with ${data.length} elements:\n  ${itemDescriptions.join('\n  ')}`;
+    }
+
+    if (typeof data === 'object' && data !== null) {
+        const keys = Object.keys(data);
+        return `Variable '${name}' is an object with keys: [${keys.join(', ')}]`;
+    }
+
+    if (typeof data === 'string') {
+        return `Variable '${name}' is a string with ${data.length} characters`;
+    }
+
+    return `Variable '${name}' is of type ${type}`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// IVM CONTEXT: Setup isolated environment with mmix callback
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function createIvmContext(isolate, contextData, mmixInstance) {
+    const context = await isolate.createContext();
+    const jail = context.global;
+
+    // Expose context data as variables
+    for (const [key, value] of Object.entries(contextData)) {
+        await jail.set(key, new ivm.ExternalCopy(value).copyInto());
+    }
+
+    // Expose mmix as async callback
+    // The callback receives: system prompt, user message, and output schema (as JSON string)
+    await jail.set('__mmixCallback', new ivm.Reference(async (system, message, outputJson) => {
+        const output = JSON.parse(outputJson);
+        const result = await mmixInstance.new()
+            .gpt41nano()
+            .setSystem(system)
+            .addText(message)
+            .json(output, output);
+        return new ivm.ExternalCopy(JSON.stringify(result)).copyInto();
+    }));
+
+    // Create async wrapper for mmix inside the isolate
+    await context.eval(`
+        const mmix = {
+            async query(system, message, output) {
+                const outputJson = JSON.stringify(output);
+                const resultJson = await __mmixCallback.apply(undefined, [system, message, outputJson], { result: { promise: true } });
+                return JSON.parse(resultJson);
+            }
+        };
+    `);
+
+    return context;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN: Execute model-generated code in IVM with mmix access
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function runIvmWithMmix({ task, contextData, model, maxChunkSize = 1500 }) {
+    const isolate = new ivm.Isolate({ memoryLimit: 128 });
+
+    try {
+        // Build data description for the model
+        const dataDescriptions = Object.entries(contextData)
+            .map(([key, value]) => describeData(value, key))
+            .join('\n');
+
+        // System prompt explaining the environment
+        const systemPrompt = `You are a code generator. You have access to an isolated JavaScript environment with:
+
+AVAILABLE DATA:
+${dataDescriptions}
+
+AVAILABLE API:
+- mmix.query(system, message, outputSchema): async function that calls an LLM. Returns a JSON object.
+  - system: the system prompt for the LLM
+  - message: the user message/query
+  - outputSchema: object defining expected output structure (keys are variable names, values are descriptions)
+
+EXAMPLES:
+// Single query - translation
+const result = await mmix.query(
+    'You are a professional translator',
+    'Translate to Spanish: Hello world',
+    { translation: 'text translated to spanish' }
+);
+// Returns: { translation: 'Hola mundo' }
+
+// Single query - summary with metadata
+const summary = await mmix.query(
+    'You are a summarizer',
+    'Summarize: ' + text,
+    { summary: 'brief summary of the text', wordCount: 'number of words in summary' }
+);
+// Returns: { summary: '...', wordCount: 42 }
+
+// Parallel queries (recommended for multiple independent operations)
+const results = await Promise.all([
+    mmix.query('Translator', 'Translate to Spanish: ' + paragraphs[0], { translation: 'text translated to spanish' }),
+    mmix.query('Translator', 'Translate to Spanish: ' + paragraphs[1], { translation: 'text translated to spanish' })
+]);
+
+// Combine results
+return results.map(r => r.translation).join('\\n\\n');
+
+PARALLEL PROCESSING RULES:
+- When processing large texts in parallel, split into chunks of maximum ${maxChunkSize} characters
+- Use Promise.all() to process all chunks simultaneously
+- Example splitting a text:
+  const chunkSize = ${maxChunkSize};
+  const chunks = [];
+  for (let i = 0; i < input.length; i += chunkSize) {
+    chunks.push(input.substring(i, i + chunkSize));
+  }
+  const results = await Promise.all(
+    chunks.map(chunk => mmix.query('System prompt', chunk, outputSchema))
+  );
+  return results.map(r => r.translation).join('');
+
+IMPORTANT:
+- Write an async IIFE that returns the final result directly (string, array, or simple object)
+- mmix.query() returns JSON objects, extract the fields you need (e.g., result.translation)
+- Use Promise.all for parallel operations when possible
+- When splitting text, prefer to split at natural boundaries (paragraphs, sentences) when near the ${maxChunkSize} limit
+- Return ONLY the code, no explanations or markdown`;
+
+        model.setSystem(systemPrompt);
+
+        // Request code generation
+        const code = await model
+            .addText(`Task: ${task}\n\nGenerate the JavaScript code. Return ONLY the async IIFE code, nothing else.`)
+            .message();
+
+        console.log('\n📄 Generated code:');
+        console.log('─'.repeat(60));
+        console.log(code);
+        console.log('─'.repeat(60));
+
+        // Create IVM context with data and mmix callback
+        const context = await createIvmContext(isolate, contextData, model);
+
+        // Execute the generated code (wrap in JSON.stringify for safe transfer)
+        console.log('\n⚡ Executing in IVM...');
+        const wrappedCode = `(async () => {
+            const __result = await ${code};
+            return JSON.stringify(__result);
+        })()`;
+
+        const resultJson = await context.eval(wrappedCode, {
+            timeout: 60000,  // 60s timeout for LLM calls
+            promise: true
+        });
+
+        // Parse result (handle both primitives and objects)
+        try {
+            return JSON.parse(resultJson);
+        } catch {
+            return resultJson;
+        }
+
+    } finally {
+        isolate.dispose();
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DEMO: Summarize paragraphs example
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function demo() {
+    console.log('\n=== Demo: Summarize Paragraphs via IVM + mmix ===\n');
+
+    // Sample data: 3 paragraphs (the model won't see the content, only metadata)
+    const paragraphs = [
+        `Artificial intelligence has transformed numerous industries over the past decade. From healthcare diagnostics to autonomous vehicles, AI systems now perform tasks that were once thought to require human intelligence. Machine learning algorithms can analyze vast amounts of data, identify patterns, and make predictions with remarkable accuracy.`,
+
+        `Climate change represents one of the most pressing challenges facing humanity today. Rising global temperatures are causing more frequent extreme weather events, melting polar ice caps, and threatening biodiversity across the planet. Scientists warn that immediate action is needed to reduce greenhouse gas emissions and transition to renewable energy sources.`,
+
+        `The evolution of remote work has fundamentally changed how businesses operate. Companies have discovered that distributed teams can be highly productive while offering employees better work-life balance. However, this shift also presents challenges in maintaining company culture, ensuring effective communication, and managing across different time zones.`,
+
+        `Artificial intelligence has transformed numerous industries over the past decade. From healthcare diagnostics to autonomous vehicles, AI systems now perform tasks that were once thought to require human intelligence. Machine learning algorithms can analyze vast amounts of data, identify patterns, and make predictions with remarkable accuracy.`,
+
+        `Climate change represents one of the most pressing challenges facing humanity today. Rising global temperatures are causing more frequent extreme weather events, melting polar ice caps, and threatening biodiversity across the planet. Scientists warn that immediate action is needed to reduce greenhouse gas emissions and transition to renewable energy sources.`,
+
+        `The evolution of remote work has fundamentally changed how businesses operate. Companies have discovered that distributed teams can be highly productive while offering employees better work-life balance. However, this shift also presents challenges in maintaining company culture, ensuring effective communication, and managing across different time zones.`
+
+
+    ];
+
+    // Create base mmix instance for the callbacks
+    const model = ModelMix.new({ config: { debug: 2, bottleneck: {} } })
+        .gpt52({ options: { reasoning_effort: 'none', verbosity: null } })
+        .gpt41nano()
+        .gemini3flash();
+
+    // Run the IVM task
+    const result = await runIvmWithMmix({
+        task: 'Translate each paragraph to latin spanish, then return all joined by double newlines.',
+        contextData: { paragraphs },
+        model
+    });
+
+    console.log('\n✅ Final result from IVM:');
+    console.log('═'.repeat(60));
+    console.log(result);
+    console.log('═'.repeat(60));
+
+    return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// RUN
+// ═══════════════════════════════════════════════════════════════════════════
+
+try {
+    await demo();
+    console.log('\n✅ Demo completed successfully');
+} catch (error) {
+    console.error('❌ Error:', error);
+}

package/demo/rlm-simple.js

@@ -0,0 +1,271 @@
+process.loadEnvFile();
+import { ModelMix } from '../index.js';
+import ivm from 'isolated-vm';
+
+console.log('🧬 ModelMix - RLM (Recursive Language Model) Demo');
+console.log('📄 Basado en: https://arxiv.org/html/2512.24601v1\n');
+
+// Simulamos un documento largo que sería demasiado grande para pasar directamente
+const LONG_DOCUMENT = `
+USERS DATABASE - System Report 2025
+====================================
+
+USER_001: Alice Johnson
+Role: Senior Developer
+Department: Engineering
+Location: San Francisco, CA
+Skills: JavaScript, Python, React, Node.js
+Projects: 15 completed, 3 in progress
+Performance Score: 9.2/10
+Last Active: 2025-01-09
+Notes: Excellent team leader, mentors junior developers
+
+USER_002: Bob Smith
+Role: Data Scientist
+Department: Analytics
+Location: New York, NY
+Skills: Python, R, TensorFlow, SQL
+Projects: 8 completed, 2 in progress
+Performance Score: 8.7/10
+Last Active: 2025-01-08
+Notes: Strong statistical background, innovative approaches
+
+USER_003: Carol White
+Role: Product Manager
+Department: Product
+Location: Austin, TX
+Skills: Agile, Jira, User Research, SQL
+Projects: 22 completed, 5 in progress
+Performance Score: 9.5/10
+Last Active: 2025-01-09
+Notes: Exceptional stakeholder management
+
+USER_004: David Chen
+Role: Junior Developer
+Department: Engineering
+Location: San Francisco, CA
+Skills: JavaScript, HTML, CSS, Git
+Projects: 3 completed, 1 in progress
+Performance Score: 7.8/10
+Last Active: 2025-01-07
+Notes: Fast learner, needs more experience with backend
+
+USER_005: Emma Davis
+Role: Senior Data Scientist
+Department: Analytics
+Location: Boston, MA
+Skills: Python, Machine Learning, PyTorch, AWS
+Projects: 12 completed, 4 in progress
+Performance Score: 9.0/10
+Last Active: 2025-01-09
+Notes: Published 5 research papers, conference speaker
+
+USER_006: Frank Martinez
+Role: DevOps Engineer
+Department: Engineering
+Location: Seattle, WA
+Skills: Docker, Kubernetes, AWS, Terraform
+Projects: 18 completed, 2 in progress
+Performance Score: 8.9/10
+Last Active: 2025-01-09
+Notes: Reduced deployment time by 60%
+
+USER_007: Grace Lee
+Role: UX Designer
+Department: Design
+Location: Los Angeles, CA
+Skills: Figma, User Research, Prototyping, CSS
+Projects: 25 completed, 6 in progress
+Performance Score: 9.3/10
+Last Active: 2025-01-08
+Notes: Award-winning designer, excellent user empathy
+
+USER_008: Henry Taylor
+Role: Junior Data Analyst
+Department: Analytics
+Location: Chicago, IL
+Skills: SQL, Excel, Tableau, Python
+Projects: 5 completed, 2 in progress
+Performance Score: 7.5/10
+Last Active: 2025-01-06
+Notes: Good attention to detail, improving Python skills
+`;
+
+// Crear isolate para el REPL
+const isolate = new ivm.Isolate({ memoryLimit: 256 });
+
+// Contador de llamadas recursivas (para demostrar la recursión)
+let recursionDepth = 0;
+const maxDepth = 3;
+
+async function rlmExample() {
+    console.log('=== RLM: Análisis de Documento Largo ===\n');
+    console.log(`📊 Documento: ${LONG_DOCUMENT.length} caracteres`);
+    console.log(`🎯 Tarea: Encontrar usuarios de Engineering con score > 8.5\n`);
+
+    const gptArgs = { options: { reasoning_effort: "none", verbosity: null } };
+    const mmix = ModelMix.new({ config: { debug: false, max_history: 15 } })
+        .gpt41nano()
+        .gpt52(gptArgs)
+        .gemini3flash()
+        .setSystem(`You are an RLM (Recursive Language Model) agent. 
+        
+KEY PRINCIPLE: Instead of processing the entire document directly, you can:
+1. Inspect the document structure using code
+2. Break it into smaller chunks programmatically
+3. Process each chunk recursively if needed
+
+You have access to:
+- inspect_document: Examine parts of the document via JavaScript. The DOCUMENT variable is available. Write code that returns a value (e.g., "return DOCUMENT.length" or just "DOCUMENT.length").
+- recursive_call: Make a recursive call to yourself with a focused sub-task
+
+Current recursion depth: ${recursionDepth}/${maxDepth}`);
+
+    // Variables compartidas
+    let inspectionResults = [];
+
+    // Tool 1: Inspeccionar el documento programáticamente
+    mmix.addTool({
+        name: "inspect_document",
+        description: "Execute JavaScript code to inspect and analyze the document. The document is available as 'DOCUMENT' variable. You can use string methods, regex, parsing, etc. The code should return a value (not just log it).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                code: {
+                    type: "string",
+                    description: "JavaScript code to execute. The DOCUMENT variable contains the full text. Your code should return a value. Example: 'return DOCUMENT.split(\"\\n\").length' or just 'DOCUMENT.length'"
+                },
+                explanation: {
+                    type: "string",
+                    description: "Brief explanation of what this code does"
+                }
+            },
+            required: ["code", "explanation"]
+        }
+    }, async ({ code, explanation }) => {
+        console.log(`\n🔍 [Depth ${recursionDepth}] Inspecting document: ${explanation}`);
+        console.log('─'.repeat(60));
+        console.log(code);
+        console.log('─'.repeat(60));
+
+        try {
+            const context = await isolate.createContext();
+            
+            // Inyectar el documento en el contexto como variable global
+            const jail = context.global;
+            await jail.set('DOCUMENT', LONG_DOCUMENT);
+            
+            // Ejecutar el código y convertir el resultado a JSON dentro del contexto
+            const wrappedCode = `
+                (function() {
+                    const result = (function() {
+                        ${code}
+                    })();
+                    return JSON.stringify(result);
+                })()
+            `;
+            
+            const script = await isolate.compileScript(wrappedCode);
+            const jsonResult = await script.run(context, { timeout: 10000 });
+            
+            // Parsear el resultado JSON
+            const parsedResult = JSON.parse(jsonResult);
+            
+            inspectionResults.push({ explanation, result: parsedResult });
+            
+            console.log('✅ Resultado:', JSON.stringify(parsedResult, null, 2));
+            return JSON.stringify(parsedResult);
+        } catch (error) {
+            console.log('❌ Error:', error.message);
+            return `Error: ${error.message}`;
+        }
+    });
+
+    // Tool 2: Llamada recursiva (simplificada para el ejemplo)
+    mmix.addTool({
+        name: "recursive_call",
+        description: "Make a recursive call to the RLM with a focused sub-task and optional document chunk. Use this to decompose complex queries into simpler ones.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sub_task: {
+                    type: "string",
+                    description: "The focused sub-task to solve recursively"
+                },
+                document_chunk: {
+                    type: "string",
+                    description: "Optional: A smaller chunk of the document to focus on"
+                }
+            },
+            required: ["sub_task"]
+        }
+    }, async ({ sub_task, document_chunk }) => {
+        recursionDepth++;
+        
+        if (recursionDepth > maxDepth) {
+            recursionDepth--;
+            return `Maximum recursion depth reached (${maxDepth}). Please solve this sub-task directly.`;
+        }
+
+        console.log(`\n🔄 [Depth ${recursionDepth}] Recursive call:`);
+        console.log(`📝 Sub-task: ${sub_task}`);
+        if (document_chunk) {
+            console.log(`📄 Chunk size: ${document_chunk.length} chars`);
+        }
+        console.log('─'.repeat(60));
+
+        // Crear una nueva instancia para la llamada recursiva
+        const recursiveMmix = ModelMix.new({ config: { debug: false } })
+            .gpt41nano()
+            .setSystem(`You are processing a sub-task. Be concise and direct.
+Recursion depth: ${recursionDepth}/${maxDepth}
+${document_chunk ? 'Document chunk provided.' : 'No document chunk provided.'}`);
+
+        if (document_chunk) {
+            recursiveMmix.addText(`Document chunk:\n${document_chunk}\n\nTask: ${sub_task}`);
+        } else {
+            recursiveMmix.addText(sub_task);
+        }
+
+        const result = await recursiveMmix.message();
+        
+        recursionDepth--;
+        
+        console.log(`✅ [Depth ${recursionDepth + 1}] Result: ${result.substring(0, 100)}...`);
+        return result;
+    });
+
+    // La tarea principal
+    mmix.addText(`
+Using the RLM approach, find all users in the Engineering department with a Performance Score greater than 8.5.
+
+APPROACH:
+1. First, use inspect_document to understand the document structure
+2. Use inspect_document to extract all user entries
+3. Use inspect_document to filter users by department and score
+4. Optionally use recursive_call if you need to process sub-tasks
+
+Finally, provide a clear summary with the user names and their scores.
+`);
+
+    const result = await mmix.message();
+    
+    console.log('\n' + '='.repeat(60));
+    console.log('💬 FINAL ANSWER:');
+    console.log('='.repeat(60));
+    console.log(result);
+    
+    console.log('\n📊 INSPECTION SUMMARY:');
+    console.log(`Total inspections: ${inspectionResults.length}`);
+    inspectionResults.forEach((r, i) => {
+        console.log(`${i + 1}. ${r.explanation}`);
+    });
+}
+
+try {
+    await rlmExample();
+    console.log('\n✅ RLM Ejemplo completado');
+} catch (error) {
+    console.error('❌ Error:', error);
+    console.error(error.stack);
+}

package/demo/round-robin.js

@@ -0,0 +1,26 @@
+process.loadEnvFile();
+import { ModelMix } from '../index.js';
+
+console.log('\n=== Round Robin Simple Demo ===\n');
+
+// Create instance with round robin enabled
+const ai = ModelMix.new({ 
+    config: { 
+        debug: 2, // Show which model is being used
+        roundRobin: true 
+    },
+    mix: { openrouter: false } // Exclude OpenRouter (free tier often rate-limited)
+})
+    .gptOss();
+
+console.log('Making 6 requests with round robin enabled...\n');
+
+// Make 6 requests to see rotation through all models (cerebras + groq)
+for (let i = 1; i <= 6; i++) {
+    const result = await ai.new()
+        .addText(`Calculate ${i} * 2`)
+        .message();
+    console.log(`  Result: ${result.trim()}\n`);
+}
+
+console.log('✓ Demo completed!\n');

package/demo/verbose.js

@@ -0,0 +1,103 @@
+process.loadEnvFile();
+import { ModelMix, MixOpenAI } from '../index.js';
+
+const prompt = "Say 'Hello World' in exactly 2 words.";
+
+console.log('═══════════════════════════════════════════════════════════════');
+console.log('DEMO: Verbose Modes in ModelMix');
+console.log('═══════════════════════════════════════════════════════════════\n');
+
+
+// ===================================================================
+// VERBOSE LEVEL 0 - Silent Mode
+// ===================================================================
+console.log('─────────────────────────────────────────────────────────────');
+console.log('1. VERBOSE LEVEL 0 - Silent Mode');
+console.log('   No output at all, only the result');
+console.log('─────────────────────────────────────────────────────────────\n');
+
+await ModelMix
+    .new({ config: { verbose: 0 } })
+    .gpt41nano()
+    .addText(prompt)
+    .message();
+
+
+// ===================================================================
+// VERBOSE LEVEL 1 - Minimal Mode
+// ===================================================================
+console.log('─────────────────────────────────────────────────────────────');
+console.log('2. VERBOSE LEVEL 1 - Minimal Mode');
+console.log('   Shows: → [model] #N and ✓ Success');
+console.log('─────────────────────────────────────────────────────────────\n');
+
+await ModelMix
+    .new({ config: { verbose: 1 } })
+    .gpt41nano()
+    .addText(prompt)
+    .message();
+
+// ===================================================================
+// VERBOSE LEVEL 2 - Readable Summary (DEFAULT)
+// ===================================================================
+console.log('─────────────────────────────────────────────────────────────');
+console.log('3. VERBOSE LEVEL 2 - Readable Summary (DEFAULT)');
+console.log('   Shows: model, system prompt, input, message count, output');
+console.log('   Everything in compact format on 2 lines');
+console.log('─────────────────────────────────────────────────────────────\n');
+
+await ModelMix
+    .new({ config: { verbose: 2 } })
+    .gpt41nano()
+    .addText(prompt)
+    .json({ message: 'string' });
+
+// ===================================================================
+// VERBOSE LEVEL 3 - Full Debug
+// ===================================================================
+console.log('─────────────────────────────────────────────────────────────');
+console.log('4. VERBOSE LEVEL 3 - Full Debug Mode');
+console.log('   Shows: everything from level 2 + raw response, full message,');
+console.log('   request details, config, and options');
+console.log('─────────────────────────────────────────────────────────────\n');
+
+await ModelMix
+    .new({ config: { verbose: 3 } })
+    .gpt41nano()
+    .addText(prompt)
+    .message();
+
+// ===================================================================
+// FALLBACK EXAMPLE (with verbose 2)
+// ===================================================================
+console.log('─────────────────────────────────────────────────────────────');
+console.log('5. FALLBACK EXAMPLE (Verbose Level 2)');
+console.log('   Shows how fallback models are displayed');
+console.log('─────────────────────────────────────────────────────────────\n');
+
+try {
+    const resultFallback = await ModelMix
+        .new({ config: { verbose: 2 } })
+        .attach('fake-model-that-will-fail', new MixOpenAI())
+        .gpt41nano() // This will be the fallback
+        .addText(prompt)
+        .message();
+
+    console.log(`Result: ${resultFallback}\n`);
+} catch (error) {
+    console.log(`Error (should not happen): ${error.message}\n`);
+}
+
+
+// ===================================================================
+// SUMMARY
+// ===================================================================
+console.log('═══════════════════════════════════════════════════════════════');
+console.log('DEMO COMPLETED');
+console.log('═══════════════════════════════════════════════════════════════\n');
+console.log('Summary:');
+console.log('  - Level 0: Silent, no logs');
+console.log('  - Level 1: Minimal (→ model, ✓ Success)');
+console.log('  - Level 2: Readable (1 line input + 1 line output) [DEFAULT]');
+console.log('  - Level 3: Full debug (includes raw responses and configs)');
+console.log('');