llmjs2 1.3.8 → 1.6.1

package/chain/docs/GRAPH.md

@@ -0,0 +1,490 @@
+# Graph & Flow Usage Guide
+
+The Graph class enables complex execution flows with branching and parallelism using a fluent API or JSON configuration.
+
+## Table of Contents
+
+- [Step Class](#step-class)
+- [Graph Class](#graph-class)
+  - [Basic Usage](#basic-graph-usage)
+  - [JSON Configuration](#json-configuration)
+  - [Conditional Edges](#conditional-edges)
+  - [Parallel Execution](#parallel-execution)
+  - [Complex Workflows](#complex-workflows)
+
+## Step Classes
+
+### Basic Step
+
+The Step class represents a node in the graph that executes a function with the current context.
+
+```javascript
+const { Step } = require('llmjs-chain');
+
+// Create a step with custom execute function
+const plusStep = new Step({
+  name: 'plus',
+  execute: async (context) => {
+    const a = context.a;
+    const b = context.b;
+    return a + b;
+  }
+});
+
+// Execute the step directly
+const result = await plusStep.run({ a: 5, b: 3 });
+console.log(result); // 8
+```
+
+### AgentStep
+
+The AgentStep class integrates AI agents directly into workflows as specialized steps.
+
+```javascript
+const { Agent, AgentStep, Graph } = require('llmjs-chain');
+
+// Create an AI agent
+const analyzerAgent = new Agent({
+  instruction: 'You are a data analyst. Analyze provided data and provide insights.',
+  tools: [
+    {
+      name: 'calculate_average',
+      description: 'Calculate average of numbers',
+      parameters: { numbers: { type: 'array', required: true } },
+      execute: async ({ numbers }) => {
+        const avg = numbers.reduce((a, b) => a + b, 0) / numbers.length;
+        return `Average: ${avg}`;
+      }
+    }
+  ]
+});
+
+// Create agent step with custom input/output mapping
+const analyzeStep = new AgentStep({
+  name: 'analyze-data',
+  agent: analyzerAgent,
+  inputMapper: (context) => {
+    const data = context.previousStep?.data || [];
+    return `Analyze this data: ${JSON.stringify(data)}`;
+  },
+  outputMapper: (response, context) => ({
+    analysis: response,
+    analyzedAt: new Date().toISOString(),
+    dataSize: context.previousStep?.data?.length || 0
+  })
+});
+
+// Use in workflow
+const workflow = new Graph({ name: 'ai-workflow' })
+  .step(analyzeStep)
+  .compile();
+
+const result = await workflow.run({ previousStep: { data: [1, 2, 3, 4, 5] } });
+```
+
+#### AgentStep Configuration Options
+
+- **`name`**: Step identifier in the workflow
+- **`agent`**: AI Agent instance to execute
+- **`inputMapper`**: Function or template to transform workflow context to agent input
+- **`outputMapper`**: Function to transform agent response to workflow context
+
+#### Input Mapping Examples
+
+```javascript
+// Function mapper
+inputMapper: (context) => `Process: ${context.data.join(', ')}`
+
+// Template mapper (simple string interpolation)
+inputMapper: 'Analyze data: {{data}} from step: {{stepName}}'
+
+// Default: converts entire context to readable string
+```
+
+#### Output Mapping Examples
+
+```javascript
+// Custom output transformation
+outputMapper: (agentResponse, context) => ({
+  result: agentResponse,
+  confidence: 0.95,
+  processingTime: Date.now() - context.startTime
+})
+
+// Default: returns { response, agent, timestamp }
+```
+
+## Graph Class
+
+The Graph class enables complex execution flows with branching and parallelism using a fluent API.
+
+### Basic Graph Usage
+
+```javascript
+const { Graph, Step } = require('llmjs-chain');
+
+// Create steps
+const validateStep = new Step({
+  name: 'validate',
+  execute: async (context) => {
+    if (!context.data) throw new Error('No data provided');
+    return { validated: true, data: context.data };
+  }
+});
+
+const processStep = new Step({
+  name: 'process',
+  execute: async (context) => {
+    const processed = context.validate.data.map(item => item * 2);
+    return { processed };
+  }
+});
+
+const saveStep = new Step({
+  name: 'save',
+  execute: async (context) => {
+    console.log('Saving:', context.process.processed);
+    return { saved: true };
+  }
+});
+
+// Create and configure graph using fluent API
+const flow = new Graph({ name: 'data-processing-pipeline' })
+  .step(validateStep)           // Add single step
+  .step(processStep, saveStep)  // Add multiple steps
+  .edge(validateStep, processStep)  // Connect steps
+  .edge(processStep, saveStep)
+  .compile();
+
+// Execute the graph
+const result = await flow.run({ data: [1, 2, 3, 4] });
+console.log('Graph execution result:', result);
+```
+
+### JSON Configuration
+
+Load graphs from JSON configuration for dynamic workflow definition:
+
+```javascript
+const { Graph } = require('llmjs-chain');
+
+// Define workflow as JSON
+const workflowConfig = {
+  name: 'data-processing-pipeline',
+  steps: [
+    {
+      name: 'validate',
+      execute: `async (context) => {
+        if (!context.data) throw new Error('No data provided');
+        return { validated: true, data: context.data };
+      }`
+    },
+    {
+      name: 'process',
+      execute: `async (context) => {
+        const processed = context.validate.data.map(item => item * 2);
+        return { processed };
+      }`
+    },
+    {
+      name: 'save',
+      execute: `async (context) => {
+        console.log('Saving:', context.process.processed);
+        return { saved: true };
+      }`
+    }
+  ],
+  edges: [
+    { from: 'validate', to: 'process' },
+    { from: 'process', to: 'save' }
+  ]
+};
+
+// Load and compile graph from JSON
+const flow = Graph.load(workflowConfig).compile();
+
+// Execute the loaded graph
+const result = await flow.run({ data: [1, 2, 3, 4] });
+console.log('Loaded graph result:', result);
+```
+
+### Conditional Edges in JSON
+
+```javascript
+const conditionalConfig = {
+  name: 'decision-workflow',
+  steps: [
+    {
+      name: 'evaluate',
+      execute: `async (context) => {
+        return { score: context.input, approved: context.input > 70 };
+      }`
+    },
+    {
+      name: 'approve',
+      execute: `async (context) => ({ status: 'approved', message: 'High score!' })`
+    },
+    {
+      name: 'reject',
+      execute: `async (context) => ({ status: 'rejected', message: 'Try again' })`
+    }
+  ],
+  edges: [
+    { from: 'evaluate', to: 'approve', condition: '(result) => result.approved' },
+    { from: 'evaluate', to: 'reject', condition: '(result) => !result.approved' }
+  ]
+};
+
+const conditionalFlow = Graph.load(conditionalConfig).compile();
+const result = await conditionalFlow.run({ input: 85 }); // Goes to 'approve'
+```
+
+### Parallel Execution
+
+Connect a single step to multiple steps for parallel execution:
+
+```javascript
+const { Graph, Step } = require('llmjs-chain');
+
+const startStep = new Step({
+  name: 'start',
+  execute: async (context) => ({ started: true })
+});
+
+const taskA = new Step({
+  name: 'taskA',
+  execute: async (context) => {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    return { result: 'Task A completed' };
+  }
+});
+
+const taskB = new Step({
+  name: 'taskB',
+  execute: async (context) => {
+    await new Promise(resolve => setTimeout(resolve, 150));
+    return { result: 'Task B completed' };
+  }
+});
+
+const combineStep = new Step({
+  name: 'combine',
+  execute: async (context) => ({
+    final: [context.taskA.result, context.taskB.result]
+  })
+});
+
+// Use array syntax for parallel execution
+const parallelFlow = new Graph({ name: 'parallel-workflow' })
+  .step(startStep, taskA, taskB, combineStep)
+  .edge(startStep, [taskA, taskB])  // Both taskA and taskB run in parallel
+  .edge(taskA, combineStep)
+  .edge(taskB, combineStep)
+  .compile();
+
+const result = await parallelFlow.run();
+console.log('Parallel result:', result);
+```
+
+### Conditional Edges
+
+Edges can include conditions to control execution flow using the `{when: condition}` syntax:
+
+```javascript
+const { Graph, Step } = require('llmjs-chain');
+
+// Create decision step
+const checkValue = new Step({
+  name: 'check',
+  execute: async (context) => {
+    const isLarge = context.value > 100;
+    return { value: context.value, isLarge };
+  }
+});
+
+const largeProcessor = new Step({
+  name: 'large',
+  execute: async (context) => {
+    return { result: `Large value: ${context.check.value}`, category: 'large' };
+  }
+});
+
+const smallProcessor = new Step({
+  name: 'small',
+  execute: async (context) => {
+    return { result: `Small value: ${context.check.value}`, category: 'small' };
+  }
+});
+
+// Create graph with conditional edges
+const flow = new Graph({ name: 'conditional-workflow' })
+  .step(checkValue, largeProcessor, smallProcessor)
+  .edge(checkValue, largeProcessor, { when: (result, context) => result.isLarge })
+  .edge(checkValue, smallProcessor, { when: (result, context) => !result.isLarge })
+  .compile();
+
+// Execute - will follow different paths based on input value
+const result1 = await flow.run({ value: 150 }); // Goes to 'large'
+console.log('Large value result:', result1);
+
+const result2 = await flow.run({ value: 50 });  // Goes to 'small'
+console.log('Small value result:', result2);
+```
+
+### Complex Workflows
+
+Create sophisticated workflows with multiple paths, loops, and integrations:
+
+```javascript
+const { Graph, Step, Agent } = require('llmjs-chain');
+
+// Create a graph that combines AI analysis with processing steps
+const analyzeStep = new Step({
+  name: 'analyze',
+  execute: async (context) => {
+    const agent = new Agent({
+      instruction: 'Analyze the provided data and provide insights.',
+      model: 'openai/gpt-4'
+    });
+
+    const analysis = await agent.generate(
+      `Analyze this data: ${JSON.stringify(context.data)}`
+    );
+
+    return { analysis, status: 'completed' };
+  }
+});
+
+const validateStep = new Step({
+  name: 'validate',
+  execute: async (context) => {
+    // Validation logic
+    return { valid: true, data: context.data };
+  }
+});
+
+const reportStep = new Step({
+  name: 'report',
+  execute: async (context) => {
+    return {
+      report: `Analysis Report:\n${context.analyze.analysis}\nData validated: ${context.validate.valid}`
+    };
+  }
+});
+
+const errorStep = new Step({
+  name: 'error',
+  execute: async (context) => {
+    console.error('Analysis failed');
+    return { error: 'Analysis failed' };
+  }
+});
+
+// Create complex workflow with conditional branching
+const workflow = new Graph({ name: 'ai-analysis-workflow' })
+  .step(validateStep, analyzeStep, reportStep, errorStep)
+  .edge(validateStep, analyzeStep)
+  .edge(analyzeStep, reportStep, { when: (result) => result.status === 'completed' })
+  .edge(analyzeStep, errorStep, { when: (result) => result.status === 'failed' })
+  .compile();
+
+// Execute the workflow
+const result = await workflow.run({
+  data: { metrics: [1, 2, 3], status: 'active' }
+});
+
+console.log('Workflow result:', result);
+```
+
+## Integration Examples
+
+### Agent as a Graph Step
+
+Integrate AI agents directly into your workflow as steps:
+
+```javascript
+const { Agent, Graph, Step } = require('llmjs-chain');
+
+// Create an AI agent
+const analyzerAgent = new Agent({
+  instruction: 'You are a data analyst. Analyze the provided data and provide insights.',
+  tools: [
+    {
+      name: 'calculate_average',
+      description: 'Calculate the average of a list of numbers',
+      parameters: {
+        numbers: { type: 'array', description: 'Array of numbers', required: true }
+      },
+      execute: async ({ numbers }) => {
+        const avg = numbers.reduce((a, b) => a + b, 0) / numbers.length;
+        return JSON.stringify({ average: avg });
+      }
+    }
+  ]
+});
+
+// Create agent as a step in the workflow
+const agentStep = new Step({
+  name: 'analyze',
+  execute: async (context) => {
+    const data = context.prepare.data;
+    const prompt = `Analyze this dataset: ${JSON.stringify(data)}`;
+    const analysis = await analyzerAgent.generate(prompt);
+    return { analysis, analyzed: true };
+  }
+});
+
+// Build workflow with agent step
+const workflow = new Graph({ name: 'data-analysis-workflow' })
+  .step(prepareStep, agentStep, reportStep)
+  .edge(prepareStep, agentStep)
+  .edge(agentStep, reportStep)
+  .compile();
+
+// Execute workflow
+const result = await workflow.run({ rawData: [1, 2, 3, 4, 5] });
+```
+
+### Multiple Agents in Workflow
+
+Use different specialized agents for different workflow stages:
+
+```javascript
+const validationAgent = new Agent({
+  instruction: 'Validate data quality and completeness.',
+  // validation tools...
+});
+
+const processingAgent = new Agent({
+  instruction: 'Process and transform validated data.',
+  // processing tools...
+});
+
+const reportingAgent = new Agent({
+  instruction: 'Generate reports from processed data.',
+  // reporting tools...
+});
+
+// Create agent steps
+const validateStep = new Step({
+  name: 'validate',
+  execute: async (context) => validationAgent.generate(context.rawData)
+});
+
+const processStep = new Step({
+  name: 'process',
+  execute: async (context) => processingAgent.generate(context.validate)
+});
+
+const reportStep = new Step({
+  name: 'report',
+  execute: async (context) => reportingAgent.generate(context.process)
+});
+
+// Orchestrate multi-agent workflow
+const multiAgentWorkflow = new Graph({ name: 'multi-agent-pipeline' })
+  .step(validateStep, processStep, reportStep)
+  .edge(validateStep, processStep)
+  .edge(processStep, reportStep)
+  .compile();
+```