llmjs2 1.3.9 → 1.6.1

package/chain/README.md

@@ -0,0 +1,257 @@
+# llmjs-chain
+
+An extension of llmjs2 that provides chaining capabilities for building complex LLM workflows with Agents, Graphs, Steps, and Flows.
+
+## Features
+
+- **Step**: Basic unit of work that can execute LLM calls or custom processing
+- **Flow**: Linear sequence of steps that execute in order
+- **Agent**: Intelligent entity that can make decisions and use tools
+- **Graph**: Complex execution graph with branching and parallelism
+- **Full llmjs2 compatibility**: All llmjs2 features are available
+
+## Installation
+
+```bash
+npm install llmjs-chain
+```
+
+This will automatically install llmjs2 as a dependency.
+
+## Quick Start
+
+```javascript
+import { Step, Flow, Agent, Graph, completion } from 'llmjs-chain';
+
+// Set API keys (same as llmjs2)
+process.env.OPENAI_API_KEY = 'your-openai-key';
+
+// Basic completion (from llmjs2)
+const response = await completion('Hello, how are you?');
+console.log(response);
+```
+
+## Terminal Chat App
+
+Experience llmjs-chain with an interactive terminal chat interface that automatically detects available API keys and models:
+
+```bash
+npm run chat
+```
+
+Features:
+- Conversational chat with memory persistence
+- Built-in tools: `get_current_time`, `calculate`
+- Commands: `/help`, `/history`, `/memory`, `/clear`, `/exit`
+- Automatic API key and model detection (no configuration needed)
+- Automatic model routing and tool execution
+
+The chat app will automatically use whichever API keys are available in your environment variables, following the same auto-detection logic as llmjs2.
+
+## Components
+
+### Step
+
+A Step is the basic unit of work in a chain. It can execute an LLM call or custom processing logic.
+
+```javascript
+import { Step } from 'llmjs-chain';
+
+const step = new Step('my-step', {
+  processor: async (context, inputs) => {
+    // Custom processing logic
+    return { result: `Processed: ${inputs.data}` };
+  }
+});
+
+const result = await step.execute({}, { data: 'Hello World' });
+```
+
+### Flow
+
+A Flow executes steps in a linear sequence.
+
+```javascript
+import { Step, Flow } from 'llmjs-chain';
+
+const step1 = new Step('step1', {
+  processor: async (context, inputs) => {
+    return { data: inputs.input.toUpperCase() };
+  }
+});
+
+const step2 = new Step('step2', {
+  processor: async (context, inputs) => {
+    return { result: `Final: ${inputs.step1.data}` };
+  }
+});
+
+const flow = new Flow('my-flow');
+flow.addStep(step1);
+flow.addStep(step2);
+
+const result = await flow.execute({ input: 'hello' });
+console.log(result); // { result: 'Final: HELLO' }
+```
+
+### Agent
+
+An Agent is an intelligent entity that can make decisions and use tools.
+
+```javascript
+import { Agent } from 'llmjs-chain';
+
+const agent = new Agent({
+  model: 'openai/gpt-4',
+  instruction: 'You are a helpful coding assistant.',
+  tools: [
+    {
+      name: 'run_code',
+      description: 'Execute JavaScript code',
+      parameters: {
+        type: 'object',
+        properties: {
+          code: { type: 'string' }
+        }
+      },
+      execute: async ({ code }) => {
+        return eval(code);
+      }
+    }
+  ]
+});
+
+// Execute task
+const result = await agent.generate('Calculate 2 + 2 and tell me the result');
+```
+
+### Memory Factory
+
+llmjs-chain provides a memory factory for creating different types of memory storage:
+
+```javascript
+import { memory } from 'llmjs-chain';
+
+// In-memory storage (default)
+const inMemory = memory.create();
+
+// LanceDB vector storage
+const lanceMemory = memory.create({ type: 'lancedb', config: { db: 'my_db', dir: './data' } });
+
+// SQLite storage with vector support
+const sqliteMemory = memory.create({ type: 'sqlite', config: { db: './memory.db' } });
+
+// Direct class instantiation (alternative)
+import { InMemory, LanceMemory, SQLiteMemory } from 'llmjs-chain';
+const directMemory = new InMemory();
+```
+
+### Memory Classes
+
+#### InMemory
+Basic in-memory storage for conversation history:
+
+```javascript
+const memory = new InMemory();
+
+// Save messages
+await memory.save('Hello!', 'user123', 'thread456', 'user', 'text');
+await memory.save('Hi there!', 'user123', 'thread456', 'assistant', 'text');
+
+// Get session history
+const history = await memory.getSessionHistory('user123', 'thread456', 10);
+
+// Search messages
+const results = await memory.search('hello', 'user123', 5);
+```
+
+### Graph
+
+A Graph allows complex execution with branching and parallelism.
+
+```javascript
+import { Step, Graph } from 'llmjs-chain';
+
+const graph = new Graph('my-graph');
+
+// Create nodes
+const start = new Step('start', {
+  processor: async (context, inputs) => ({ value: inputs.number })
+});
+
+const double = new Step('double', {
+  processor: async (context, inputs) => ({ result: inputs.start.value * 2 })
+});
+
+const square = new Step('square', {
+  processor: async (context, inputs) => ({ result: inputs.start.value ** 2 })
+});
+
+// Add nodes and edges
+graph.addNode(start);
+graph.addNode(double);
+graph.addNode(square);
+
+graph.addEdge('start', 'double');
+graph.addEdge('start', 'square');
+
+// Execute graph
+const results = await graph.execute(['start'], { number: 5 });
+console.log(results);
+// {
+//   start: { value: 5 },
+//   double: { result: 10 },
+//   square: { result: 25 }
+// }
+```
+
+## Advanced Usage
+
+### Conditional Graph Execution
+
+```javascript
+graph.addEdge('start', 'path-a', (result, context) => result.value > 10);
+graph.addEdge('start', 'path-b', (result, context) => result.value <= 10);
+```
+
+### Agent with Memory
+
+```javascript
+agent.remember({ role: 'user', content: 'Remember that I like coffee' });
+agent.remember({ role: 'assistant', content: 'Got it, you like coffee!' });
+
+// Later conversations will include this memory
+const response = await agent.execute('What do I like to drink?');
+```
+
+### Step Dependencies
+
+```javascript
+const step = new Step('dependent-step', {
+  dependencies: ['previous-step'],
+  processor: async (context, inputs) => {
+    // This step will only execute after 'previous-step' has completed
+    return { result: inputs['previous-step'].data };
+  }
+});
+```
+
+## API Keys Setup
+
+Same as llmjs2:
+
+```bash
+export OPENAI_API_KEY=your_openai_api_key
+export OLLAMA_API_KEY=your_ollama_api_key
+export OPEN_ROUTER_API_KEY=your_openrouter_api_key
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/chain/WORKFLOW_README.md

@@ -0,0 +1,85 @@
+# Workflow Example
+
+This directory contains a complete example of defining and running workflows using llmjs-chain's Graph system.
+
+## Files
+
+- **`workflow-example.json`** - JSON definition of a sample workflow
+- **`workflow-example-usage.js`** - Usage example showing how to load and run the workflow
+
+## Running the Example
+
+```bash
+node workflow-example-usage.js
+```
+
+## Workflow Description
+
+The example workflow demonstrates:
+
+1. **Input Validation** - Validates that input data exists and is valid
+2. **Parallel Processing** - Two different processing paths run simultaneously
+   - Path A: Multiplies each value by 2
+   - Path B: Adds 10 to each value
+3. **Result Checking** - Sums all processed values and checks if total exceeds threshold
+4. **Conditional Branching** - Routes to success or warning handler based on result size
+
+## Workflow Structure
+
+```
+validate → [process-a, process-b] → check-result → [success-handler | warning-handler]
+```
+
+## JSON Configuration Format
+
+```json
+{
+  "name": "workflow-name",
+  "description": "Workflow description",
+  "steps": [
+    {
+      "name": "step-name",
+      "description": "Step description",
+      "execute": "async (context) => { /* step logic as string */ }"
+    }
+  ],
+  "edges": [
+    { "from": "step1", "to": "step2" },
+    { "from": "step2", "to": "step3", "condition": "(result) => result.success" }
+  ]
+}
+```
+
+## Key Features Demonstrated
+
+- ✅ **JSON Workflow Definition** - Define complete workflows in JSON
+- ✅ **Parallel Execution** - Multiple steps can run simultaneously
+- ✅ **Conditional Edges** - Branch workflow based on step results
+- ✅ **Context Passing** - Steps can access results from previous steps
+- ✅ **Error Handling** - Validation and error propagation
+- ✅ **Dynamic Loading** - Load workflows from files at runtime
+
+## Customizing the Example
+
+1. **Modify Steps**: Edit the `execute` functions in `workflow-example.json`
+2. **Change Logic**: Update conditions and processing logic
+3. **Add Steps**: Extend the workflow with additional processing steps
+4. **Create New Workflows**: Use this as a template for your own workflows
+
+## Integration with Agents
+
+This workflow system can be combined with AI agents for intelligent processing:
+
+```javascript
+// Agent step that uses AI for decision making
+{
+  "name": "analyze-data",
+  "execute": "async (context) => {
+    const agent = new Agent({ instruction: 'Analyze this data...' });
+    const result = await agent.generate(context.previousStep.data);
+    return { analysis: result };
+  }"
+}
+```
+
+The JSON-based workflow system makes it easy to define, version, and deploy complex processing pipelines with conditional logic and parallel execution.

package/chain/agent-step-example.js

@@ -0,0 +1,232 @@
+/**
+ * AgentStep Example Program
+ *
+ * This example demonstrates how to use AgentStep in llmjs-chain workflows.
+ * It creates a multi-agent workflow for content creation and analysis.
+ */
+
+const { Agent, AgentStep, Graph } = require('./index');
+
+async function runAgentStepExample() {
+  console.log('🚀 Starting AgentStep Workflow Example\n');
+
+  // ============================================================================
+  // 1. Create Specialized AI Agents
+  // ============================================================================
+
+  console.log('📝 Creating specialized AI agents...');
+
+  // Content Creator Agent - generates creative content
+  const contentCreator = new Agent({
+    instruction: `You are a creative content writer. Generate engaging, well-structured content based on the given topic.
+    Focus on being informative yet entertaining. Keep responses concise but comprehensive.`,
+    tools: [
+      {
+        name: 'get_word_count',
+        description: 'Count words in a text',
+        parameters: { text: { type: 'string', required: true } },
+        execute: async ({ text }) => `Word count: ${text.split(/\s+/).length}`
+      }
+    ]
+  });
+
+  // Content Analyzer Agent - analyzes and provides feedback
+  const contentAnalyzer = new Agent({
+    instruction: `You are a content quality analyst. Analyze the provided content for:
+    - Engagement and readability
+    - Structure and flow
+    - Key strengths and areas for improvement
+    - SEO considerations
+    Provide specific, actionable feedback.`,
+    tools: [
+      {
+        name: 'analyze_sentiment',
+        description: 'Analyze sentiment of text',
+        parameters: { text: { type: 'string', required: true } },
+        execute: async ({ text }) => {
+          // Simple sentiment analysis simulation
+          const positiveWords = ['good', 'great', 'excellent', 'amazing', 'wonderful'];
+          const negativeWords = ['bad', 'poor', 'terrible', 'awful', 'horrible'];
+
+          const words = text.toLowerCase().split(/\s+/);
+          const positiveCount = words.filter(w => positiveWords.includes(w)).length;
+          const negativeCount = words.filter(w => negativeWords.includes(w)).length;
+
+          if (positiveCount > negativeCount) return 'Positive sentiment';
+          if (negativeCount > positiveCount) return 'Negative sentiment';
+          return 'Neutral sentiment';
+        }
+      }
+    ]
+  });
+
+  // Content Editor Agent - refines and improves content
+  const contentEditor = new Agent({
+    instruction: `You are an expert content editor. Review and improve the provided content based on:
+    - Clarity and conciseness
+    - Grammar and style
+    - Engagement improvements
+    - Call-to-action additions
+    Provide the improved version along with change explanations.`,
+    tools: [
+      {
+        name: 'check_grammar',
+        description: 'Check grammar in text',
+        parameters: { text: { type: 'string', required: true } },
+        execute: async ({ text }) => 'Grammar check completed - no major issues found'
+      }
+    ]
+  });
+
+  // ============================================================================
+  // 2. Create AgentSteps with Input/Output Mapping
+  // ============================================================================
+
+  console.log('🔧 Creating AgentSteps with specialized mappings...');
+
+  // Step 1: Content Creation
+  const createContentStep = new AgentStep({
+    name: 'create-content',
+    agent: contentCreator,
+    inputMapper: (context) => {
+      const topic = context.topic || 'Artificial Intelligence';
+      const audience = context.audience || 'general public';
+      const wordCount = context.targetWordCount || 300;
+
+      return `Create an engaging article about "${topic}" for a ${audience} audience.
+      Target word count: approximately ${wordCount} words.
+      Make it informative, entertaining, and well-structured with a clear introduction, body, and conclusion.`;
+    },
+    outputMapper: (response, context) => ({
+      originalContent: response,
+      createdAt: new Date().toISOString(),
+      topic: context.topic,
+      stage: 'created'
+    })
+  });
+
+  // Step 2: Content Analysis
+  const analyzeContentStep = new AgentStep({
+    name: 'analyze-content',
+    agent: contentAnalyzer,
+    inputMapper: (context) => {
+      const content = context['create-content'].originalContent;
+      return `Please analyze this content for quality, engagement, and improvement opportunities:
+
+${content}
+
+Provide specific feedback on strengths, weaknesses, and suggestions for enhancement.`;
+    },
+    outputMapper: (response, context) => ({
+      analysis: response,
+      analyzedAt: new Date().toISOString(),
+      stage: 'analyzed'
+    })
+  });
+
+  // Step 3: Content Editing
+  const editContentStep = new AgentStep({
+    name: 'edit-content',
+    agent: contentEditor,
+    inputMapper: (context) => {
+      const originalContent = context['create-content'].originalContent;
+      const analysis = context['analyze-content'].analysis;
+
+      return `Please edit and improve this content based on the analysis provided:
+
+ORIGINAL CONTENT:
+${originalContent}
+
+ANALYSIS/FEEDBACK:
+${analysis}
+
+Provide an improved version that addresses the feedback, along with explanations of your changes.`;
+    },
+    outputMapper: (response, context) => ({
+      finalContent: response,
+      editedAt: new Date().toISOString(),
+      stage: 'final'
+    })
+  });
+
+  // ============================================================================
+  // 3. Build and Execute the Multi-Agent Workflow
+  // ============================================================================
+
+  console.log('🏗️  Building multi-agent workflow...');
+
+  const contentWorkflow = new Graph({
+    name: 'content-creation-pipeline'
+  })
+    .step(createContentStep, analyzeContentStep, editContentStep)
+    .edge(createContentStep, analyzeContentStep)
+    .edge(analyzeContentStep, editContentStep)
+    .compile();
+
+  console.log('▶️  Executing content creation workflow...\n');
+
+  // Execute with different topics to show flexibility
+  const topics = [
+    {
+      topic: 'The Future of Renewable Energy',
+      audience: 'tech-savvy professionals',
+      targetWordCount: 400
+    },
+    {
+      topic: 'Healthy Eating Habits',
+      audience: 'busy parents',
+      targetWordCount: 350
+    }
+  ];
+
+  for (let i = 0; i < topics.length; i++) {
+    const topicConfig = topics[i];
+    console.log(`📝 Processing Topic ${i + 1}: "${topicConfig.topic}"`);
+    console.log('═'.repeat(60));
+
+    try {
+      const result = await contentWorkflow.run(topicConfig);
+
+      // Display results
+      console.log('\n📄 ORIGINAL CONTENT:');
+      console.log(result['create-content'].originalContent.substring(0, 200) + '...');
+
+      console.log('\n🔍 ANALYSIS:');
+      console.log(result['analyze-content'].analysis.substring(0, 150) + '...');
+
+      console.log('\n✨ FINAL EDITED CONTENT:');
+      console.log(result['edit-content'].finalContent.substring(0, 200) + '...');
+
+      console.log('\n✅ Workflow completed successfully!');
+      console.log('═'.repeat(60));
+      console.log();
+
+    } catch (error) {
+      console.error(`❌ Error processing topic ${i + 1}:`, error.message);
+    }
+  }
+
+  // ============================================================================
+  // 4. Demonstrate Error Handling
+  // ============================================================================
+
+  console.log('🧪 Testing error handling...');
+
+  try {
+    // This should fail due to missing topic
+    await contentWorkflow.run({});
+  } catch (error) {
+    console.log('✅ Error handling works:', error.message);
+  }
+
+  console.log('\n🎉 AgentStep example completed successfully!');
+  console.log('\n💡 Key Features Demonstrated:');
+  console.log('  • Multiple specialized AI agents in one workflow');
+  console.log('  • Custom input/output mapping for each agent');
+  console.log('  • Sequential processing with context passing');
+  console.log('  • Real-world content creation pipeline');
+  console.log('  • Error handling and validation');
+}
+
+// Run the example
+runAgentStepExample().catch(console.error);

package/chain/docs/AGENT.md

@@ -0,0 +1,126 @@
+# Agent Usage Guide
+
+The Agent class provides AI interactions with tool support and conversation memory.
+
+## Table of Contents
+- [Basic Usage](#basic-agent-usage)
+- [Tool Definition](#tool-definition)
+- [Memory Integration](#memory-integration)
+- [Advanced Configuration](#advanced-agent-configuration)
+
+## Basic Agent Usage
+
+```javascript
+const { Agent } = require('llmjs-chain');
+
+// Create a simple agent
+const agent = new Agent({
+  instruction: 'You are a helpful AI assistant.',
+  model: 'openai/gpt-4' // Optional - auto-detected if not provided
+});
+
+// Generate a response
+async function chat() {
+  const response = await agent.generate('Hello, how are you?');
+  console.log(response);
+}
+
+chat();
+```
+
+## Tool Definition
+
+Agents can use tools to perform actions. Tools can be defined in a simplified format:
+
+```javascript
+const agent = new Agent({
+  instruction: 'You are a helpful assistant with access to tools.',
+  tools: [
+    {
+      name: 'calculate',
+      description: 'Perform mathematical calculations',
+      parameters: {
+        expression: { type: 'string', description: 'Math expression to evaluate', required: true }
+      },
+      execute: async ({ expression }) => {
+        const result = eval(expression);
+        return JSON.stringify({ result, expression });
+      }
+    },
+    {
+      name: 'get_weather',
+      description: 'Get current weather for a location',
+      parameters: {
+        location: { type: 'string', description: 'City name', required: true }
+      },
+      execute: async ({ location }) => {
+        // Implement weather API call
+        return JSON.stringify({ location, temperature: 22, condition: 'sunny' });
+      }
+    }
+  ]
+});
+
+// The agent will automatically use tools when needed
+agent.generate('What is 15 + 27?').then(console.log);
+agent.generate('What is the weather in Tokyo?').then(console.log);
+```
+
+## Memory Integration
+
+Agents can maintain conversation history using the InMemory class:
+
+```javascript
+const { Agent, InMemory } = require('llmjs-chain');
+
+const memory = new InMemory();
+const agent = new Agent({
+  instruction: 'You are a helpful assistant with memory.',
+  memory: memory
+});
+
+// Start a conversation session
+const response1 = await agent.generate({
+  userPrompt: 'My name is Alice.',
+  memory: {
+    resourceId: 'user_alice',
+    threadId: 'conversation_1',
+    session: true // Include session history
+  }
+});
+
+const response2 = await agent.generate({
+  userPrompt: 'What is my name?',
+  memory: {
+    resourceId: 'user_alice',
+    threadId: 'conversation_1',
+    session: true
+  }
+});
+// Agent will remember your name from the previous message
+```
+
+## Advanced Agent Configuration
+
+```javascript
+const agent = new Agent({
+  model: 'ollama/llama2', // Specific model
+  apikey: 'your-api-key', // Override auto-detected API key
+  instruction: `You are an expert software developer.
+                Always provide detailed explanations and code examples.`,
+  tools: [/* tool definitions */],
+  memory: new InMemory()
+});
+
+// Advanced generation with memory options
+const response = await agent.generate({
+  userPrompt: 'Help me debug this JavaScript code...',
+  apikey: 'override-key', // Override API key for this call
+  memory: {
+    resourceId: 'debug_session',
+    threadId: 'js_debug_001',
+    session: true,     // Include conversation history
+    relevance: true    // Also search for relevant past conversations
+  }
+});
+```