llmjs2 1.3.8 → 1.6.1

package/chain/simple-agent-step-example.js

@@ -0,0 +1,168 @@
+/**
+ * Simple AgentStep Example (Mock Agents)
+ *
+ * This example demonstrates AgentStep usage with mock agents that don't make real AI calls.
+ * Perfect for understanding the API without waiting for AI responses.
+ */
+
+const { AgentStep, Graph } = require('./index');
+
+// Mock Agent class for demonstration (simulates AI responses)
+class MockAgent {
+  constructor(responses) {
+    this.responses = responses;
+    this.callCount = 0;
+  }
+
+  async generate(input) {
+    // Simulate processing time
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    const response = this.responses[this.callCount % this.responses.length];
+    this.callCount++;
+
+    console.log(`🤖 MockAgent responding to: "${input.substring(0, 50)}..."`);
+    return `${response} (Response #${this.callCount})`;
+  }
+}
+
+async function runSimpleAgentStepExample() {
+  console.log('🚀 Simple AgentStep Example with Mock Agents\n');
+
+  // ============================================================================
+  // Create Mock Agents with Predefined Responses
+  // ============================================================================
+
+  const dataProcessorAgent = new MockAgent([
+    'Data processed successfully. Found 150 records with 95% quality score.',
+    'Analysis complete. Key insights: trend increasing by 23% monthly.',
+    'Validation passed. No anomalies detected in the dataset.'
+  ]);
+
+  const reportGeneratorAgent = new MockAgent([
+    'Generated comprehensive report with charts and recommendations.',
+    'Created executive summary highlighting key performance indicators.',
+    'Compiled detailed analysis report with actionable insights.'
+  ]);
+
+  const qualityCheckerAgent = new MockAgent([
+    'Quality check passed. Content meets all standards.',
+    'Minor issues found and corrected. Quality improved by 15%.',
+    'High-quality content validated. Ready for publication.'
+  ]);
+
+  // ============================================================================
+  // Create AgentSteps with Different Mapping Strategies
+  // ============================================================================
+
+  // Example 1: Function-based input mapping
+  const processDataStep = new AgentStep({
+    name: 'process-data',
+    agent: dataProcessorAgent,
+    inputMapper: (context) => {
+      const data = context.rawData || [];
+      return `Process this dataset with ${data.length} items: ${data.slice(0, 3).join(', ')}...`;
+    },
+    outputMapper: (response, context) => ({
+      processedData: response,
+      recordCount: context.rawData?.length || 0,
+      processingTimestamp: new Date().toISOString()
+    })
+  });
+
+  // Example 2: Template-based input mapping
+  const generateReportStep = new AgentStep({
+    name: 'generate-report',
+    agent: reportGeneratorAgent,
+    inputMapper: 'Create a report based on: {{processedData}} from {{recordCount}} records',
+    outputMapper: (response, context) => ({
+      report: response,
+      basedOn: context['process-data'].processedData,
+      generatedAt: new Date().toISOString()
+    })
+  });
+
+  // Example 3: Default mapping (no custom mappers)
+  const qualityCheckStep = new AgentStep({
+    name: 'quality-check',
+    agent: qualityCheckerAgent
+    // Uses default input/output mapping
+  });
+
+  // ============================================================================
+  // Build and Execute Workflow
+  // ============================================================================
+
+  console.log('🏗️  Building workflow with AgentSteps...');
+
+  const workflow = new Graph({ name: 'agent-step-demo' })
+    .step(processDataStep, generateReportStep, qualityCheckStep)
+    .edge(processDataStep, generateReportStep)
+    .edge(generateReportStep, qualityCheckStep)
+    .compile();
+
+  console.log('▶️  Executing workflow...\n');
+
+  // Test with different datasets
+  const testDatasets = [
+    { rawData: [10, 20, 30, 40, 50] },
+    { rawData: ['apple', 'banana', 'cherry', 'date'] },
+    { rawData: [1.5, 2.7, 3.9, 4.2, 5.8, 6.1] }
+  ];
+
+  for (let i = 0; i < testDatasets.length; i++) {
+    console.log(`📊 Test Dataset ${i + 1}:`);
+    console.log(`   Input: ${JSON.stringify(testDatasets[i])}`);
+
+    const result = await workflow.run(testDatasets[i]);
+
+    console.log(`   ✓ Data Processing: ${result['process-data'].processedData.substring(0, 60)}...`);
+    console.log(`   ✓ Report Generation: ${result['generate-report'].report.substring(0, 60)}...`);
+    console.log(`   ✓ Quality Check: ${result['quality-check'].response.substring(0, 60)}...`);
+    console.log('   ✅ Workflow completed\n');
+  }
+
+  // ============================================================================
+  // Demonstrate Parallel Agent Execution
+  // ============================================================================
+
+  console.log('🔀 Demonstrating Parallel Agent Execution...\n');
+
+  // Create parallel workflow
+  const parallelWorkflow = new Graph({ name: 'parallel-agents' })
+    .step(
+      new AgentStep({ name: 'agent-a', agent: new MockAgent(['Task A completed']) }),
+      new AgentStep({ name: 'agent-b', agent: new MockAgent(['Task B completed']) }),
+      new AgentStep({ name: 'agent-c', agent: new MockAgent(['Task C completed']) }),
+      new AgentStep({
+        name: 'combiner',
+        agent: new MockAgent(['Combined all parallel results successfully'])
+      })
+    )
+    .edge('agent-a', 'combiner')
+    .edge('agent-b', 'combiner')
+    .edge('agent-c', 'combiner')
+    .compile();
+
+  console.log('▶️  Running parallel agent workflow...');
+  const parallelResult = await parallelWorkflow.run({});
+
+  console.log('   Parallel Results:');
+  Object.keys(parallelResult).forEach(key => {
+    if (parallelResult[key].response) {
+      console.log(`   ✓ ${key}: ${parallelResult[key].response}`);
+    }
+  });
+
+  console.log('\n🎉 AgentStep examples completed successfully!');
+  console.log('\n💡 Demonstrated Features:');
+  console.log('  • Function-based input/output mapping');
+  console.log('  • Template-based input mapping');
+  console.log('  • Default mapping behavior');
+  console.log('  • Sequential workflow execution');
+  console.log('  • Parallel agent execution');
+  console.log('  • Context passing between steps');
+}
+
+// Run the example
+runSimpleAgentStepExample().catch(console.error);

package/chain/workflow-example-usage.js

@@ -0,0 +1,70 @@
+/**
+ * Example: Loading and running a workflow from JSON configuration
+ */
+
+const { Graph } = require('./index');
+const fs = require('fs');
+
+// Load workflow from JSON file
+function loadWorkflowFromFile(filename) {
+  try {
+    const config = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    return Graph.load(config);
+  } catch (error) {
+    throw new Error(`Failed to load workflow from ${filename}: ${error.message}`);
+  }
+}
+
+// Example usage
+async function runExampleWorkflow() {
+  console.log('Loading simple workflow from JSON configuration...\n');
+
+  // Load the workflow
+  const workflow = loadWorkflowFromFile('./workflow-example.json').compile();
+
+  // Test with small data (should succeed)
+  console.log('=== Testing with small data (success path) ===');
+  const smallData = [1, 2, 3, 4]; // Sum = 20, should be < 100
+
+  const result1 = await workflow.run({ input: smallData });
+  console.log('\n=== Small Data Results ===');
+  console.log('Validation passed:', result1.validate?.valid);
+  console.log('Processing completed:', !!result1['check-result']);
+  console.log('Success handler triggered:', !!result1['success-handler']);
+  console.log('Warning handler triggered:', !!result1['warning-handler']);
+  console.log('Final result:', result1['success-handler']?.result);
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Test with large data (should trigger warning)
+  console.log('=== Testing with large data (warning path) ===');
+  const largeData = [20, 30, 40, 50]; // Sum = 140, should be > 100
+
+  const result2 = await workflow.run({ input: largeData });
+  console.log('\n=== Large Data Results ===');
+  console.log('Validation passed:', result2.validate?.valid);
+  console.log('Processing completed:', !!result2['check-result']);
+  console.log('Success handler triggered:', !!result2['success-handler']);
+  console.log('Warning handler triggered:', !!result2['warning-handler']);
+  if (result2['warning-handler']) {
+    console.log('Warning message:', result2['warning-handler'].message);
+    console.log('Final result:', result2['warning-handler'].result);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Test validation failure
+  console.log('=== Testing validation failure ===');
+  try {
+    await workflow.run({ input: [] }); // Empty array should fail
+    console.log('Unexpected success');
+  } catch (error) {
+    console.log('\n=== Validation Error (Expected) ===');
+    console.log('Error:', error.message);
+  }
+
+  console.log('\nWorkflow example completed successfully!');
+}
+
+// Run the example
+runExampleWorkflow().catch(console.error);

package/chain/workflow-example.json

@@ -0,0 +1,59 @@
+{
+  "name": "simple-workflow",
+  "description": "A simple workflow demonstrating JSON loading, parallel execution, conditional logic, and agent integration",
+  "steps": [
+    {
+      "name": "validate",
+      "description": "Validate input data",
+      "execute": "async (context) => { console.log('Validating input...'); const data = context.input; if (!data || data.length === 0) { throw new Error('No input data'); } return { valid: true, data: data }; }"
+    },
+    {
+      "name": "analyze-data",
+      "type": "agent",
+      "description": "Analyze the processed data using AI",
+      "instruction": "You are a data analysis expert. Analyze the provided data and provide insights.",
+      "tools": [],
+      "model": "gpt-4",
+      "userPrompt": "Analyze this data: {{validate.data}}. Provide insights about patterns, trends, and recommendations."
+    },
+    {
+      "name": "process-a",
+      "description": "Process data - path A",
+      "execute": "async (context) => { console.log('Processing path A...'); const result = context.validate.data.map(x => x * 2); return { processed: result, path: 'A' }; }"
+    },
+    {
+      "name": "process-b",
+      "description": "Process data - path B",
+      "execute": "async (context) => { console.log('Processing path B...'); const result = context.validate.data.map(x => x + 10); return { processed: result, path: 'B' }; }"
+    },
+    {
+      "name": "check-result",
+      "description": "Check processing result and analysis",
+      "execute": "async (context) => { console.log('Checking result...'); const resultA = context['process-a'].processed; const resultB = context['process-b'].processed; const sumA = resultA.reduce((a, b) => a + b, 0); const sumB = resultB.reduce((a, b) => a + b, 0); const totalSum = sumA + sumB; const analysis = context['analyze-data'] || 'No analysis available'; return { sum: totalSum, isLarge: totalSum > 100, analysis: analysis }; }"
+    },
+    {
+      "name": "success-handler",
+      "description": "Handle successful processing",
+      "execute": "async (context) => { console.log('SUCCESS: Processing completed!'); const result = context['check-result']; return { status: 'success', result: result.sum, analysis: result.analysis }; }"
+    },
+    {
+      "name": "warning-handler",
+      "description": "Handle large result warning",
+      "execute": "async (context) => { console.log('WARNING: Large result detected!'); const result = context['check-result']; return { status: 'warning', message: 'Result exceeds threshold', result: result.sum, analysis: result.analysis }; }"
+    }
+  ],
+  "edges": [
+    { "from": "validate", "to": "process-a" },
+    { "from": "validate", "to": "process-b" },
+    { "from": "validate", "to": "analyze-data" },
+    { "from": "process-a", "to": "check-result" },
+    { "from": "process-b", "to": "check-result" },
+    { "from": "analyze-data", "to": "check-result" },
+    { "from": "check-result", "to": "success-handler", "condition": "(result) => !result.isLarge" },
+    { "from": "check-result", "to": "warning-handler", "condition": "(result) => result.isLarge" }
+  ],
+  "metadata": {
+    "version": "1.0.0",
+    "description": "Demonstrates JSON workflow loading, parallel processing, and conditional branching"
+  }
+}