llmjs2 1.3.8 → 1.6.1

package/chain/examples.js

@@ -0,0 +1,314 @@
+/**
+ * Advanced examples showing llmjs-chain capabilities
+ */
+const { Step, Flow, Agent, Graph, InMemory, completion } = require('./index');
+
+/**
+ * Example 1: Simple LLM Chain
+ * Chain multiple LLM calls together
+ */
+async function example1_SimpleChain() {
+  console.log('\n=== Example 1: Simple LLM Chain ===');
+
+  // Step 1: Generate a story premise
+  const premiseStep = new Step('premise', {
+    processor: async (context, inputs) => {
+      const messages = [{
+        role: 'user',
+        content: `Generate a creative premise for a ${inputs.genre} story.`
+      }];
+      const result = await completion({ messages, model: 'openai/gpt-3.5-turbo' });
+      return { premise: result };
+    }
+  });
+
+  // Step 2: Expand the premise into a short story
+  const storyStep = new Step('story', {
+    processor: async (context, inputs) => {
+      const messages = [{
+        role: 'user',
+        content: `Write a short story based on this premise: ${inputs.premise.premise}`
+      }];
+      const result = await completion({ messages, model: 'openai/gpt-3.5-turbo' });
+      return { story: result };
+    }
+  });
+
+  // Create and execute flow
+  const flow = new Flow('story-generator');
+  flow.addStep(premiseStep);
+  flow.addStep(storyStep);
+
+  const result = await flow.execute({ genre: 'science fiction' });
+  console.log('Generated story:', result.story);
+}
+
+/**
+ * Example 2: Agent with Tools
+ * Create an agent that can perform calculations and get current time
+ */
+async function example2_AgentWithTools() {
+  console.log('\n=== Example 2: Agent with Tools ===');
+
+  const agent = new Agent({
+    model: 'openai/gpt-4',
+    instruction: 'You are a helpful math assistant. Use tools when needed to solve problems.',
+    tools: [
+      {
+        name: 'calculate',
+        description: 'Perform mathematical calculations',
+        parameters: {
+          type: 'object',
+          properties: {
+            expression: { type: 'string', description: 'Mathematical expression to evaluate' }
+          },
+          required: ['expression']
+        },
+        execute: async ({ expression }) => {
+          try {
+            // Simple eval for demo - in production use a safe math library
+            const result = eval(expression);
+            return JSON.stringify({ result });
+          } catch (error) {
+            return JSON.stringify({ error: error.message });
+          }
+        }
+      },
+      {
+        name: 'get_current_time',
+        description: 'Get the current date and time',
+        parameters: {
+          type: 'object',
+          properties: {}
+        },
+        execute: async () => {
+          return JSON.stringify({ time: new Date().toISOString() });
+        }
+      }
+    ]
+  });
+
+  const result = await agent.generate('Calculate the area of a circle with radius 5, and tell me what time it is.');
+  console.log('Agent response:', result);
+}
+
+/**
+ * Example 3: Complex Graph with Branching
+ * A graph that processes data differently based on conditions
+ */
+async function example3_ComplexGraph() {
+  console.log('\n=== Example 3: Complex Graph with Branching ===');
+
+  const graph = new Graph('data-processor');
+
+  // Input validation step
+  const validateStep = new Step('validate', {
+    processor: async (context, inputs) => {
+      const data = inputs.data;
+      const isValid = Array.isArray(data) && data.length > 0;
+      return { data, isValid };
+    }
+  });
+
+  // Process array data
+  const processArrayStep = new Step('process-array', {
+    processor: async (context, inputs) => {
+      const data = inputs.validate.data;
+      const sum = data.reduce((a, b) => a + b, 0);
+      const average = sum / data.length;
+      return { sum, average, processed: true };
+    }
+  });
+
+  // Process single value
+  const processSingleStep = new Step('process-single', {
+    processor: async (context, inputs) => {
+      const data = inputs.validate.data;
+      const value = data;
+      const doubled = value * 2;
+      return { original: value, doubled, processed: true };
+    }
+  });
+
+  // Format results
+  const formatStep = new Step('format', {
+    processor: async (context, inputs) => {
+      let result = 'Processing failed';
+
+      if (inputs['process-array']) {
+        const { sum, average } = inputs['process-array'];
+        result = `Array processed - Sum: ${sum}, Average: ${average}`;
+      } else if (inputs['process-single']) {
+        const { original, doubled } = inputs['process-single'];
+        result = `Single value processed - Original: ${original}, Doubled: ${doubled}`;
+      }
+
+      return { result };
+    }
+  });
+
+  // Add nodes
+  graph.addNode(validateStep);
+  graph.addNode(processArrayStep);
+  graph.addNode(processSingleStep);
+  graph.addNode(formatStep);
+
+  // Add edges with conditions
+  graph.addEdge('validate', 'process-array', (result) => result.isValid && Array.isArray(result.data));
+  graph.addEdge('validate', 'process-single', (result) => result.isValid && !Array.isArray(result.data));
+  graph.addEdge('validate', 'format', (result) => !result.isValid); // Invalid data goes directly to format
+  graph.addEdge('process-array', 'format');
+  graph.addEdge('process-single', 'format');
+
+  // Test with array data
+  console.log('Testing with array data:');
+  const arrayResult = await graph.execute(['validate'], { data: [1, 2, 3, 4, 5] });
+  console.log('Array result:', arrayResult.format.result);
+
+  // Test with single value
+  console.log('\nTesting with single value:');
+  const singleResult = await graph.execute(['validate'], { data: 10 });
+  console.log('Single value result:', singleResult.format.result);
+
+  // Test with invalid data
+  console.log('\nTesting with invalid data:');
+  const invalidResult = await graph.execute(['validate'], { data: null });
+  console.log('Invalid data result:', invalidResult.format?.result || 'No result');
+}
+
+/**
+ * Example 4: Multi-Agent Collaboration
+ * Agents working together through a flow
+ */
+async function example4_MultiAgentCollaboration() {
+  console.log('\n=== Example 4: Multi-Agent Collaboration ===');
+
+  // Agent 1: Research specialist
+  const researcher = new Agent({
+    model: 'openai/gpt-3.5-turbo',
+    instruction: 'You are a research specialist. Provide detailed information on requested topics.'
+  });
+
+  // Agent 2: Writer
+  const writer = new Agent({
+    model: 'openai/gpt-3.5-turbo',
+    instruction: 'You are a skilled writer. Create engaging content based on provided information.'
+  });
+
+  // Agent 3: Editor
+  const editor = new Agent({
+    model: 'openai/gpt-3.5-turbo',
+    instruction: 'You are an editor. Review and improve the quality of written content.'
+  });
+
+  // Create steps that use agents
+  const researchStep = new Step('research', {
+    processor: async (context, inputs) => {
+      const research = await researcher.generate(`Research key facts about ${inputs.topic}`);
+      return { research };
+    }
+  });
+
+  const writeStep = new Step('write', {
+    processor: async (context, inputs) => {
+      const article = await writer.generate(
+        `Write a 300-word article about ${inputs.topic} using this research: ${inputs.research.research}`
+      );
+      return { article };
+    }
+  });
+
+  const editStep = new Step('edit', {
+    processor: async (context, inputs) => {
+      const edited = await editor.generate(
+        `Edit and improve this article: ${inputs.write.article}`
+      );
+      return { finalArticle: edited };
+    }
+  });
+
+  // Create and execute collaboration flow
+  const collaborationFlow = new Flow('article-creation');
+  collaborationFlow.addStep(researchStep);
+  collaborationFlow.addStep(writeStep);
+  collaborationFlow.addStep(editStep);
+
+  const result = await collaborationFlow.execute({ topic: 'artificial intelligence' });
+  console.log('Final article:', result.finalArticle);
+}
+
+/**
+ * Example 5: Agent with Memory
+ * Demonstrates how agents can use memory for conversation persistence
+ */
+async function example5_AgentWithMemory() {
+  console.log('\n=== Example 5: Agent with Memory ===');
+
+  // Create memory instance
+  const memory = new InMemory();
+
+  // Create agent with memory
+  const agent = new Agent({
+    model: 'openai/gpt-3.5-turbo',
+    instruction: 'You are a helpful assistant with conversation memory.',
+    memory: memory
+  });
+
+  // Simulate a conversation with memory
+  console.log('Starting conversation...');
+
+  // First interaction
+  const response1 = await agent.generate({
+    userPrompt: 'My name is Alice and I love programming.',
+    memory: { resourceId: 'alice-session', threadId: 'conversation-1', session: false }
+  });
+  console.log('Agent response 1:', response1);
+
+  // Second interaction - should remember the name
+  const response2 = await agent.generate({
+    userPrompt: 'What programming language do you recommend for beginners?',
+    memory: { resourceId: 'alice-session', threadId: 'conversation-1', session: true }
+  });
+  console.log('Agent response 2:', response2);
+
+  // Search memory
+  const searchResults = await memory.search('programming', 'alice-session', 5);
+  console.log('Found', searchResults.length, 'messages mentioning programming');
+
+  // Get session history
+  const history = await memory.getSessionHistory('alice-session', 'conversation-1', 10);
+  console.log('Session has', history.length, 'total messages');
+}
+
+/**
+ * Run all examples
+ */
+async function runExamples() {
+  console.log('Running llmjs-chain advanced examples...');
+
+  try {
+    await example1_SimpleChain();
+    await example2_AgentWithTools();
+    await example3_ComplexGraph();
+    await example4_MultiAgentCollaboration();
+    await example5_AgentWithMemory();
+  } catch (error) {
+    console.error('Example failed:', error.message);
+  }
+
+  console.log('\n=== All examples completed ===');
+}
+
+// Run examples if this file is executed directly
+if (require.main === module) {
+  runExamples().catch(console.error);
+}
+
+module.exports = {
+  example1_SimpleChain,
+  example2_AgentWithTools,
+  example3_ComplexGraph,
+  example4_MultiAgentCollaboration,
+  example5_AgentWithMemory,
+  runExamples
+};

package/chain/index.js

@@ -0,0 +1,31 @@
+// Re-export everything from core runtime
+const llmjs2 = require('../core');
+
+// Import chain components
+const { Step, Flow, Graph, Edge, AgentStep } = require('./lib/flow/');
+const { Agent } = require('./lib/agent');
+const { memory, InMemory, LanceMemory, SQLiteMemory } = require('./lib/memory/');
+
+// Export everything
+module.exports = {
+  // llmjs2 exports
+  ...llmjs2,
+
+  // Chain components
+  Step,
+  Flow,
+  Graph,
+  Edge,
+  AgentStep,
+  Agent,
+  InMemory,
+  LanceMemory,
+  SQLiteMemory,
+  memory,
+
+  // Convenience functions
+  createStep: (name, config) => new Step(name, config),
+  createFlow: (name, steps) => new Flow(name, steps || []),
+  createGraph: (name) => new Graph(name),
+  createAgent: (name, config) => new Agent(name, config)
+};

package/chain/lib/agent.js

@@ -0,0 +1,338 @@
+const { completion } = require('llmjs2');
+const crypto = require('crypto');
+const { InMemory } = require('./memory/in-memory');
+
+/**
+ * Agent class for AI interactions with tool support
+ */
+class Agent {
+  /**
+   * Create a new Agent instance
+   * @param {Object} options - Agent configuration
+   * @param {string} options.model - Model name to use (optional, auto-detected if not provided)
+   * @param {string} options.instruction - System instruction
+   * @param {string} options.apikey - API key for the LLM (optional, auto-detected from environment)
+   * @param {Array} options.tools - Array of tool definitions
+   * @param {Object} options.memory - Memory instance for conversation history
+   */
+  constructor({ model, instruction, apikey, tools, memory }) {
+    this.model = model; // Can be undefined, let llmjs2 auto-detect
+    this.instruction = instruction;
+    this.apikey = apikey; // Can be undefined, let llmjs2 auto-detect
+    this.tools = this.normalizeTools(tools || []);
+    this.memory = memory;
+  }
+
+  /**
+   * Normalize tool definitions to ensure consistent format and add error handling
+   * @param {Array} tools - Array of tool objects
+   * @returns {Array} Normalized tools array
+   */
+  normalizeTools(tools) {
+    return tools.map(tool => {
+      // If tool already has the full format, use it as-is
+      if (tool.parameters && tool.parameters.type === 'object' && tool.parameters.properties) {
+        return {
+          ...tool,
+          execute: this.wrapExecute(tool.execute)
+        };
+      }
+
+      // Convert simplified format to full OpenAI format
+      const properties = {};
+      const required = [];
+
+      for (const [paramName, paramDef] of Object.entries(tool.parameters || {})) {
+        properties[paramName] = {
+          type: paramDef.type,
+          description: paramDef.description
+        };
+        if (paramDef.required) {
+          required.push(paramName);
+        }
+      }
+
+      return {
+        name: tool.name,
+        description: tool.description,
+        parameters: {
+          type: 'object',
+          properties,
+          required
+        },
+        execute: this.wrapExecute(tool.execute)
+      };
+    });
+  }
+
+  /**
+   * Wrap execute function with try-catch error handling
+   * @param {Function} executeFn - The original execute function
+   * @returns {Function} Wrapped execute function
+   */
+  wrapExecute(executeFn) {
+    return async (args) => {
+      try {
+        return await executeFn(args);
+      } catch (error) {
+        return JSON.stringify({
+          error: error.message,
+          stack: error.stack
+        });
+      }
+    };
+  }
+
+  /**
+   * Convert tool definitions to the format expected by llmjs2
+   * @param {Array} tools - Array of tool objects with execute method
+   * @returns {Array} Formatted tools array
+   */
+  static formatTools(tools) {
+    return tools.map(tool => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters
+      }
+    }));
+  }
+
+  /**
+   * Generate a random unique ID
+   * @returns {string} Random unique string
+   */
+  #generateId() {
+    return crypto.randomBytes(8).toString('hex');
+  }
+
+  /**
+   * Execute a tool call
+   * @param {Object} toolCall - The tool call object from the AI
+   * @returns {Promise<string>} The result of the tool execution
+   */
+  async executeToolCall(toolCall) {
+    const functionName = toolCall.function.name;
+    const args = toolCall.function.arguments;
+
+    console.log(`[Tool Call] ${functionName}(${JSON.stringify(args)})`);
+
+    // Find the tool with the matching name
+    const tool = this.tools.find(t => t.name === functionName);
+
+    if (!tool) {
+      return `Unknown tool: ${functionName}`;
+    }
+
+    try {
+      // Execute the tool's async execute method
+      const result = await tool.execute(args);
+      return result;
+    } catch (error) {
+      return `Error executing tool: ${error.message}`;
+    }
+  }
+
+  /**
+   * Process a single chat turn with automatic tool execution
+   * @param {Array} messages - Conversation history
+   * @param {string} [apikey] - Optional API key override
+   * @param {Object} memoryOptions - Memory options (resourceId, threadId)
+   * @returns {Promise<Object>} The AI response with full conversation history
+   */
+  async processChat(messages, apikey, memoryOptions = {}) {
+    const apiKey = apikey || this.apikey;
+
+    try {
+      // Get AI response
+      const result = await completion({
+        model: this.model,
+        messages: messages,
+        apiKey: apiKey,
+        tools: Agent.formatTools(this.tools),
+        final: false // Get full result object including tool_calls
+      });
+
+
+      // Check if we got tool calls
+      if (result.tool_calls && result.tool_calls.length > 0) {
+        // Add assistant message with tool calls to history
+        const assistantMessage = {
+          role: 'assistant',
+          content: result.content || 'Tool calls executed.'
+        };
+
+        console.log(`[tool_calls] ${result.tool_calls.length} tool call(s) detected.`);
+
+        // Execute each tool call and add results to history
+        for (const toolCall of result.tool_calls) {
+          const toolResult = await this.executeToolCall(toolCall);
+
+          messages.push(assistantMessage);
+
+          // Add tool result as a system message since llmjs2 doesn't support 'tool' role yet
+          messages.push({
+            role: 'tool',
+            content: `Tool result for ${toolCall.function.name}: ${toolResult}`
+          });
+
+          // Save tool result to memory if memoryOptions provided (non-blocking)
+          if (memoryOptions.resourceId && memoryOptions.threadId && this.memory) {
+            this.memory.save(
+              toolResult,
+              memoryOptions.resourceId,
+              memoryOptions.threadId,
+              'tool',
+              'tool_result',
+              this.#generateId(),
+              toolCall.function.name
+            );
+          }
+
+          // Recursively process to get next response
+          return this.processChat(messages, apiKey, memoryOptions);
+        }
+      } else {
+        // Final response - no tool calls
+        const assistantMessage = {
+          role: 'assistant',
+          content: result.content
+        };
+        messages.push(assistantMessage);
+
+        // Save assistant message to memory if memoryOptions provided (non-blocking)
+        if (memoryOptions.resourceId && memoryOptions.threadId && this.memory) {
+          this.memory.save(
+            result.content,
+            memoryOptions.resourceId,
+            memoryOptions.threadId,
+            'assistant',
+            'text',
+            this.#generateId(),
+            null
+          );
+        }
+
+        return {
+          response: result.content,
+          messages: messages
+        };
+      }
+    } catch (error) {
+      return {
+        response: `Error: ${error.message}`,
+        messages: messages
+      };
+    }
+  }
+
+  /**
+   * Generate a response from the AI
+   * @param {string|Object} input - User prompt string or object with userPrompt, memory options, and optional apikey
+   * @returns {Promise<string>} The AI response
+   */
+  async generate(input) {
+    let userPrompt;
+    let apiKey;
+    let memoryOptions = {};
+
+    if (typeof input === 'string') {
+      // Simple string prompt
+      userPrompt = input;
+      apiKey = this.apikey;
+    } else if (typeof input === 'object') {
+      // Object with userPrompt and optional memory/apikey
+      userPrompt = input.userPrompt;
+      apiKey = input.apikey || this.apikey;
+      memoryOptions = input.memory || {};
+    } else {
+      return 'Invalid input format. Expected string or object with userPrompt.';
+    }
+
+    // Build messages array with system instruction and user prompt
+    const messages = [];
+
+    // Add system instruction if provided
+    if (this.instruction) {
+      messages.push({
+        role: 'system',
+        content: this.instruction
+      });
+    }
+
+    // Load conversation history from memory if memoryOptions provided
+    if (memoryOptions.resourceId && memoryOptions.threadId && this.memory) {
+      // Check if session history should be loaded
+      const loadSession = memoryOptions.session !== undefined ? memoryOptions.session : false;
+
+      // Check if relevance search should be performed
+      const loadRelevance = memoryOptions.relevance !== undefined ? memoryOptions.relevance : false;
+
+      if (loadSession) {
+        const history = await this.memory.getSessionHistory(
+          memoryOptions.resourceId,
+          memoryOptions.threadId,
+          10
+        );
+
+        console.log("history: ", history); // Debug log for session history
+
+        // Add history messages (excluding system message and tool message)
+        for (const msg of history) {
+          if (msg.role !== 'tool') {
+            messages.push({
+              role: msg.role,
+              content: msg.content
+            });
+          }
+        }
+      }
+
+      if (loadRelevance) {
+        // Search for relevant past history
+        const relevant = await this.memory.search(
+          userPrompt,
+          memoryOptions.resourceId,
+          5
+        );
+
+        // Combine relevant history into a string and append to user prompt
+        let referenceContent = '';
+        for (const msg of relevant) {
+          referenceContent += `[${msg.role.toUpperCase()}]: ${msg.content}\n\n`;
+        }
+
+        if (referenceContent) {
+          userPrompt = `${userPrompt}\n\n--- Reference History ---\n${referenceContent}`;
+        }
+      }
+    }
+
+    // Add user message
+    messages.push({
+      role: 'user',
+      content: userPrompt
+    });
+
+    // Save user message to memory if memoryOptions provided (non-blocking)
+    if (memoryOptions.resourceId && memoryOptions.threadId && this.memory) {
+      this.memory.save(
+        userPrompt,
+        memoryOptions.resourceId,
+        memoryOptions.threadId,
+        'user',
+        'text',
+        this.#generateId(),
+        null
+      );
+    }
+
+    // Process the chat
+    const result = await this.processChat(messages, apiKey, memoryOptions);
+
+    return result.response;
+  }
+}
+
+module.exports = { Agent };