llmjs2 1.3.9 → 1.6.1

package/chain/lib/flow/agent-step.js

@@ -0,0 +1,119 @@
+const { Step } = require('./step');
+const { Agent } = require('../agent');
+
+/**
+ * AgentStep - A specialized step that wraps an AI agent for use in graph workflows
+ * Allows seamless integration of AI agents into workflow execution
+ */
+class AgentStep extends Step {
+  /**
+    * Create a new AgentStep
+    * @param {Object} options - Step configuration
+    * @param {string} options.name - Step name
+    * @param {string} options.instruction - System instruction for the agent
+    * @param {Array} options.tools - Array of tool definitions
+    * @param {string} options.model - Model name (optional)
+    * @param {string} options.apikey - API key (optional)
+    * @param {Object} options.memory - Memory instance (optional)
+    * @param {string} options.userPrompt - Template string to map workflow context to agent input
+    */
+  constructor(options = {}) {
+    super({
+      name: options.name,
+      execute: options.execute || (async (context) => {
+        return this._defaultExecute(context);
+      })
+    });
+
+    this.agent = new Agent({
+      model: options.model,
+      instruction: options.instruction,
+      apikey: options.apikey,
+      tools: options.tools || [],
+      memory: options.memory
+    });
+    this.userPrompt = options.userPrompt || '';
+  }
+
+  /**
+   * Default execute method for AgentStep
+   * @param {Object} context - Workflow context
+   * @returns {Promise<Object>} Agent response mapped to workflow context
+   */
+  async _defaultExecute(context) {
+    if (!this.agent) {
+      throw new Error(`AgentStep ${this.name}: No agent provided`);
+    }
+
+    // Map workflow context to agent input
+    let agentInput;
+    if (this.userPrompt) {
+      // userPrompt is a template string with {{variable}} placeholders
+      agentInput = this._interpolateTemplate(this.userPrompt, context);
+    } else {
+      // Default: pass the entire context as a formatted string
+      agentInput = this._contextToString(context);
+    }
+
+    console.log(`[${this.name}] Agent input:`, agentInput);
+
+    // Call the agent
+    const agentResponse = await this.agent.generate(agentInput);
+
+    console.log(`[${this.name}] Agent response:`, agentResponse);
+
+    return agentResponse;
+  }
+
+  /**
+   * Convert workflow context to a readable string for agent input
+   * @param {Object} context - Workflow context
+   * @returns {string} Formatted context string
+   */
+  _contextToString(context) {
+    const relevantKeys = Object.keys(context).filter(key =>
+      !key.startsWith('_') && key !== 'executedSteps' && key !== 'results'
+    );
+
+    if (relevantKeys.length === 0) {
+      return "Please process the available data.";
+    }
+
+    let result = "Based on the following context:\n";
+    for (const key of relevantKeys) {
+      const value = context[key];
+      if (typeof value === 'object' && value !== null) {
+        result += `${key}: ${JSON.stringify(value, null, 2)}\n`;
+      } else {
+        result += `${key}: ${value}\n`;
+      }
+    }
+    result += "\nPlease provide your analysis or response.";
+    return result;
+  }
+
+  /**
+   * Simple template interpolation
+   * @param {string} template - Template string with {{variable}} placeholders
+   * @param {Object} context - Context object for interpolation
+   * @returns {string} Interpolated string
+   */
+  _interpolateTemplate(template, context) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+      const value = context[key];
+      return value !== undefined ? String(value) : match;
+    });
+  }
+
+  /**
+   * Get the agent instance
+   * @returns {Agent} The wrapped agent
+   */
+  getAgent() {
+    return this.agent;
+  }
+
+
+}
+
+module.exports = { AgentStep };

package/chain/lib/flow/edge.js

@@ -0,0 +1,24 @@
+/**
+ * Edge - Represents a connection between nodes in a graph
+ */
+class Edge {
+  constructor(from, to, condition = null) {
+    this.from = from;
+    this.to = to;
+    this.condition = condition; // Optional condition function
+  }
+
+  /**
+   * Check if this edge should be followed based on result and context
+   */
+  shouldFollow(result, context) {
+    // Handle both direct function and {when: function} format
+    const conditionFn = typeof this.condition === 'function'
+      ? this.condition
+      : this.condition?.when;
+
+    return !conditionFn || conditionFn(result, context);
+  }
+}
+
+module.exports = { Edge };

package/chain/lib/flow/flow.js

@@ -0,0 +1,76 @@
+const { Step } = require('./step');
+
+/**
+ * Flow - Linear sequence of steps
+ */
+class Flow {
+  constructor(name, steps = []) {
+    this.name = name;
+    this.steps = steps;
+    this.context = {
+      executedSteps: new Set(),
+      results: new Map(),
+      variables: new Map()
+    };
+  }
+
+  /**
+   * Add a step to the flow
+   */
+  addStep(step) {
+    this.steps.push(step);
+  }
+
+  /**
+   * Execute the flow sequentially
+   */
+  async execute(initialInputs = {}) {
+    console.log(`[${this.name}] Starting flow execution`);
+
+    this.context.variables.set('initial', initialInputs);
+
+    for (const step of this.steps) {
+      if (!step.canExecute(this.context)) {
+        throw new Error(`Cannot execute step ${step.name}: dependencies not satisfied`);
+      }
+
+      const inputs = this.prepareInputs(step, initialInputs);
+      const result = await step.execute(this.context, inputs);
+
+      this.context.executedSteps.add(step.name);
+      this.context.results.set(step.name, result);
+
+      // Store result in variables for use by subsequent steps
+      this.context.variables.set(step.name, result);
+    }
+
+    console.log(`[${this.name}] Flow execution completed`);
+    return this.getFinalResult();
+  }
+
+  /**
+   * Prepare inputs for a step based on context
+   */
+  prepareInputs(step, initialInputs) {
+    const inputs = { ...initialInputs };
+
+    // Include results from previous steps if needed
+    for (const [key, value] of this.context.variables) {
+      if (key !== 'initial') {
+        inputs[key] = value;
+      }
+    }
+
+    return inputs;
+  }
+
+  /**
+   * Get the final result of the flow
+   */
+  getFinalResult() {
+    if (this.steps.length === 0) return null;
+    return this.context.results.get(this.steps[this.steps.length - 1].name);
+  }
+}
+
+module.exports = { Flow };

package/chain/lib/flow/graph.js

@@ -0,0 +1,331 @@
+const fs = require('fs');
+const { Step } = require('./step');
+const { Edge } = require('./edge');
+const { AgentStep } = require('./agent-step');
+const { Agent } = require('../agent');
+
+/**
+ * Graph - Graph-flow execution system
+ */
+class Graph {
+  constructor(options = {}) {
+    const normalizedOptions = typeof options === 'string' ? { name: options } : (options || {});
+
+    this.name = normalizedOptions.name || 'graph';
+    this.nodes = new Map(); // step name -> step
+    this.edges = new Map(); // from -> [Edge]
+    this.startNodes = new Set();
+    this.compiled = false;
+  }
+
+  /**
+    * Load a graph from JSON configuration file
+    * @param {string} path - Path to JSON configuration file
+    * @returns {Graph} Configured Graph instance
+    *
+    * JSON format:
+    * {
+    *   "name": "graph-name",
+    *   "steps": [
+    *     {
+    *       "name": "step-name",
+    *       "execute": "async (context) => { ... }"
+    *     },
+    *     {
+    *       "name": "agent-step-name",
+    *       "type": "agent",
+    *       "instruction": "You are a helpful assistant",
+    *       "tools": [...],
+    *       "model": "gpt-4",
+    *       "userPrompt": "template string with {{variable}} placeholders"
+    *     }
+    *   ],
+    *   "edges": [...]
+    * }
+    */
+  static load(path) {
+    const config = JSON.parse(fs.readFileSync(path, 'utf8'));
+    const { name, steps = [], edges = [] } = config;
+    const graph = new Graph({ name });
+
+    // Load steps
+    for (const stepConfig of steps) {
+      const { name: stepName, type, execute, instruction, tools, model, apikey, memory, userPrompt } = stepConfig;
+
+      let step;
+
+      if (type === 'agent') {
+        // Create agent step
+        if (!instruction) {
+          throw new Error(`Instruction required for agent step ${stepName}`);
+        }
+
+        step = new AgentStep({
+          name: stepName,
+          instruction,
+          tools,
+          model,
+          apikey,
+          memory,
+          userPrompt
+        });
+      } else {
+        // Create regular step
+        // Handle execute function - can be string or function
+        let executeFn;
+        if (typeof execute === 'string') {
+          // If execute is a string, create a function from it
+          try {
+            executeFn = new Function('context', `return (${execute})(context);`);
+          } catch (error) {
+            throw new Error(`Invalid execute function for step ${stepName}: ${error.message}`);
+          }
+        } else if (typeof execute === 'function') {
+          executeFn = execute;
+        } else {
+          throw new Error(`Execute must be a function or string for step ${stepName}`);
+        }
+
+        step = new Step({
+          name: stepName,
+          execute: executeFn
+        });
+      }
+
+      graph.step(step);
+    }
+
+    // Load edges
+    for (const edgeConfig of edges) {
+      const { from, to, condition } = edgeConfig;
+
+      let conditionFn = null;
+      if (condition) {
+        if (typeof condition === 'string') {
+          try {
+            conditionFn = new Function('result', 'context', `return (${condition})(result, context);`);
+          } catch (error) {
+            throw new Error(`Invalid condition function for edge ${from}->${to}: ${error.message}`);
+          }
+        } else if (typeof condition === 'function') {
+          conditionFn = condition;
+        }
+      }
+
+      graph.edge(from, to, conditionFn ? { when: conditionFn } : {});
+    }
+
+    return graph;
+  }
+
+  /**
+   * Add steps to the graph (fluent API)
+   * Can add single step or multiple steps
+   */
+  step(...steps) {
+    for (const step of steps) {
+      if (step instanceof Step) {
+        this.nodes.set(step.name, step);
+        if (!this.edges.has(step.name)) {
+          this.edges.set(step.name, []);
+        }
+        // Mark as potential start node if no incoming edges
+        this.startNodes.add(step.name);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Backward-compatible alias for adding a single node.
+   */
+  addNode(step) {
+    this.step(step);
+    return this;
+  }
+
+  /**
+   * Add an edge between steps (fluent API)
+   * Supports conditional edges with {when: condition}
+   * Can connect to single step or array of steps for parallel execution
+   */
+  edge(from, to, options = {}) {
+    if (typeof from === 'string') {
+      from = this.nodes.get(from);
+    }
+
+    if (!from) {
+      throw new Error('Source step must exist in the graph');
+    }
+
+    if (!this.edges.has(from.name)) {
+      this.edges.set(from.name, []);
+    }
+
+    // Handle both single step and array of steps
+    const targets = Array.isArray(to) ? to : [to];
+    const condition = options.when || null;
+
+    for (const target of targets) {
+      let targetStep = target;
+      if (typeof target === 'string') {
+        targetStep = this.nodes.get(target);
+      }
+
+      if (!targetStep) {
+        throw new Error(`Target step ${target} must exist in the graph`);
+      }
+
+      const edge = new Edge(from.name, targetStep.name, condition);
+      this.edges.get(from.name).push(edge);
+
+      // Remove target from start nodes since it has incoming edges
+      this.startNodes.delete(targetStep.name);
+    }
+
+    return this;
+  }
+
+  /**
+   * Backward-compatible alias for adding edges with an optional condition function.
+   */
+  addEdge(from, to, conditionOrOptions) {
+    if (typeof conditionOrOptions === 'function') {
+      return this.edge(from, to, { when: conditionOrOptions });
+    }
+
+    return this.edge(from, to, conditionOrOptions || {});
+  }
+
+  /**
+   * Compile the graph (fluent API)
+   */
+  compile() {
+    this.compiled = true;
+    console.log(`[${this.name}] Graph compiled with ${this.nodes.size} steps`);
+    return this;
+  }
+
+  /**
+   * Run the graph with initial context
+   */
+  async run(initialContext = {}) {
+    if (!this.compiled) {
+      throw new Error('Graph must be compiled before running. Call .compile() first.');
+    }
+
+    console.log(`[${this.name}] Starting graph execution`);
+
+    const context = {
+      ...initialContext,
+      executedSteps: new Set(),
+      results: new Map(),
+      pendingNodes: new Set(this.startNodes)
+    };
+
+    const maxIterations = 1000; // Prevent infinite loops
+    let iterations = 0;
+
+    while (context.pendingNodes.size > 0 && iterations < maxIterations) {
+      iterations++;
+      const currentNodeName = Array.from(context.pendingNodes)[0];
+      context.pendingNodes.delete(currentNodeName);
+
+      if (context.executedSteps.has(currentNodeName)) {
+        continue; // Already executed
+      }
+
+      const step = this.nodes.get(currentNodeName);
+      if (!step) {
+        throw new Error(`Step ${currentNodeName} not found in graph`);
+      }
+
+      // Check if all dependencies are satisfied
+      const dependencies = this.getDependencies(currentNodeName);
+      const depsSatisfied = dependencies.every(dep => context.executedSteps.has(dep));
+
+      if (!depsSatisfied) {
+        // Put back in pending and try later
+        context.pendingNodes.add(currentNodeName);
+        continue;
+      }
+
+      // Execute the step
+      console.log(`[${this.name}] Executing step: ${currentNodeName}`);
+      const result = await step.run(context, context);
+
+      // Store result in context
+      context[currentNodeName] = result;
+      context.results.set(currentNodeName, result);
+      context.executedSteps.add(currentNodeName);
+
+      // Determine next nodes to execute
+      const outgoingEdges = this.edges.get(currentNodeName) || [];
+      for (const edge of outgoingEdges) {
+        if (edge.shouldFollow(result, context)) {
+          context.pendingNodes.add(edge.to);
+        }
+      }
+    }
+
+    if (iterations >= maxIterations) {
+      throw new Error('Graph execution exceeded maximum iterations (possible infinite loop)');
+    }
+
+    console.log(`[${this.name}] Graph execution completed`);
+    return this.getFinalResults(context);
+  }
+
+  /**
+   * Backward-compatible execute entrypoint.
+   * Supports execute(startNodes, initialContext) and execute(initialContext).
+   */
+  async execute(startNodesOrContext = [], maybeInitialContext = {}) {
+    let startNodes = [];
+    let initialContext = maybeInitialContext;
+
+    if (Array.isArray(startNodesOrContext)) {
+      startNodes = startNodesOrContext;
+    } else {
+      initialContext = startNodesOrContext || {};
+    }
+
+    if (startNodes.length > 0) {
+      this.startNodes = new Set(startNodes);
+    }
+
+    if (!this.compiled) {
+      this.compile();
+    }
+
+    return this.run(initialContext);
+  }
+
+  /**
+   * Get dependencies for a node
+   */
+  getDependencies(nodeName) {
+    const dependencies = [];
+    for (const [fromNode, edges] of this.edges) {
+      for (const edge of edges) {
+        if (edge.to === nodeName) {
+          dependencies.push(fromNode);
+        }
+      }
+    }
+    return dependencies;
+  }
+
+  /**
+   * Get final results from graph execution
+   */
+  getFinalResults(context) {
+    const results = {};
+    for (const [nodeName, result] of context.results) {
+      results[nodeName] = result;
+    }
+    return results;
+  }
+}
+
+module.exports = { Graph };

package/chain/lib/flow/index.js

@@ -0,0 +1,7 @@
+const { Step } = require('./step');
+const { Flow } = require('./flow');
+const { Graph } = require('./graph');
+const { Edge } = require('./edge');
+const { AgentStep } = require('./agent-step');
+
+module.exports = { Step, Flow, Graph, Edge, AgentStep };

package/chain/lib/flow/step.js

@@ -0,0 +1,63 @@
+/**
+ * Step - Basic unit of work in a graph-flow system
+ * A step executes a function with the current context
+ */
+class Step {
+  constructor(nameOrOptions = {}, config = {}) {
+    const options = typeof nameOrOptions === 'string'
+      ? { ...config, name: nameOrOptions }
+      : (nameOrOptions || {});
+
+    this.name = options.name;
+    this.dependsOn = Array.isArray(options.dependsOn) ? options.dependsOn : [];
+
+    const executeFn = typeof options.execute === 'function'
+      ? options.execute
+      : (typeof options.processor === 'function'
+        ? options.processor
+        : async () => ({}));
+
+    this._execute = executeFn;
+  }
+
+  /**
+   * Check whether this step can execute with current flow context.
+   * If no dependencies are configured, the step can always execute.
+   */
+  canExecute(flowContext = {}) {
+    if (this.dependsOn.length === 0) {
+      return true;
+    }
+
+    const executedSteps = flowContext.executedSteps;
+    if (!(executedSteps instanceof Set)) {
+      return false;
+    }
+
+    return this.dependsOn.every((dependency) => executedSteps.has(dependency));
+  }
+
+  /**
+   * Execute this step with the given context and inputs
+   */
+  async execute(context = {}, inputs = {}) {
+    return this._execute(context, inputs);
+  }
+
+  /**
+   * Run with logging and error handling
+   */
+  async run(context = {}, inputs = context) {
+    try {
+      console.log(`[${this.name}] Executing step`);
+      const result = await this.execute(context, inputs);
+      console.log(`[${this.name}] Step completed`);
+      return result;
+    } catch (error) {
+      console.error(`[${this.name}] Step failed:`, error.message);
+      throw error;
+    }
+  }
+}
+
+module.exports = { Step };