@minded-ai/mindedjs 1.0.0-ec2-beta-1

package/src/debugging/llmCallbackHandler.ts

@@ -0,0 +1,125 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable no-debugger */
+
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+import { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * A callback handler for debugging LLM interactions in MindedJS agents.
+ * This handler allows you to inspect messages before they are sent to the LLM
+ * and see the responses received.
+ *
+ * This class extends BaseCallbackHandler from LangChain and provides several
+ * callback methods. You can override additional methods for more comprehensive debugging:
+ *
+ * Available LangChain Callback Methods:
+ * - handleChatModelStart - For chat model requests (receives BaseMessage arrays)
+ * - handleLLMStart - For standard LLM requests (receives string prompts)
+ * - handleLLMNewToken - For streaming tokens as they're generated
+ * - handleLLMEnd - When LLM finishes generating
+ * - handleLLMError - When LLM encounters an error
+ * - handleChainStart - When a LangChain chain starts execution
+ * - handleChainEnd - When a chain completes execution
+ * - handleChainError - When a chain encounters an error
+ * - handleToolStart - When a tool/function starts execution
+ * - handleToolEnd - When a tool completes execution
+ * - handleToolError - When a tool encounters an error
+ * - handleAgentAction - When an agent takes an action
+ * - handleAgentFinish - When an agent completes its task
+ *
+ * For more details on all available callbacks and their signatures, see the LangChain documentation:
+ * https://js.langchain.com/docs/modules/callbacks/
+ *
+ * @example
+ * ```typescript
+ * import { Agent, LLMDebugCallbackHandler } from '@minded-ai/mindedjs';
+ *
+ * const debugHandler = new LLMDebugCallbackHandler();
+ *
+ * const agent = new Agent({
+ *   config: {
+ *     ...config,
+ *     llm: {
+ *       ...config.llm,
+ *       properties: {
+ *         ...config.llm.properties,
+ *         callbacks: [debugHandler],
+ *       },
+ *     },
+ *   },
+ *   // ... other agent configuration
+ * });
+ * ```
+ */
+import { logger } from '../utils/logger';
+export class LLMDebugCallbackHandler extends BaseCallbackHandler {
+  name = 'LLMDebugCallbackHandler';
+
+  constructor() {
+    super();
+  }
+
+  /**
+   * Called when a chat model (like GPT-4) starts processing.
+   * This is triggered before the messages are sent to the LLM.
+   * The messages parameter contains the full conversation history.
+   */
+  async handleChatModelStart(
+    llm: Serialized,
+    messages: BaseMessage[][],
+    runId: string,
+    parentRunId?: string,
+    extraParams?: Record<string, unknown>,
+    tags?: string[],
+    metadata?: Record<string, unknown>,
+    name?: string,
+  ): Promise<void> {
+    logger.info({ msg: 'handleChatModelStart called with messages:', messages });
+    // Set a breakpoint here to inspect messages
+    debugger;
+  }
+
+  /**
+   * Called when any LLM starts processing (including non-chat models).
+   * For chat models, the messages are available in extraParams.messages.
+   * This is a more general callback that works with all LLM types.
+   */
+  async handleLLMStart(
+    llm: Serialized,
+    prompts: string[],
+    runId: string,
+    parentRunId?: string,
+    extraParams?: Record<string, unknown>,
+    tags?: string[],
+    metadata?: Record<string, unknown>,
+    name?: string,
+  ): Promise<void> {
+    logger.info({ msg: 'handleLLMStart called with extraParams.messages:', messages: extraParams?.messages });
+  }
+
+  /**
+   * Called when a chat model finishes processing and returns a response.
+   * The output contains the generated message and metadata.
+   */
+  async handleChatModelEnd(output: LLMResult, runId: string, parentRunId?: string): Promise<void> {
+    logger.info({ msg: 'handleChatModelEnd called with output:', output });
+  }
+
+  /**
+   * Called when any LLM finishes processing and returns a response.
+   * This is called for all LLM types, including chat models.
+   */
+  async handleLLMEnd(output: LLMResult, runId: string, parentRunId?: string): Promise<void> {
+    logger.info({ msg: 'handleLLMEnd called with output:', output });
+  }
+
+  /**
+   * Called when an error occurs during LLM processing.
+   * This captures any errors that happen during the LLM call.
+   */
+  async handleLLMError(err: Error, runId: string, parentRunId?: string): Promise<void> {
+    logger.info({ msg: 'handleLLMError called with error:', err });
+  }
+}

package/src/edges/createDirectEdge.ts

@@ -0,0 +1,22 @@
+import { StepForwardEdge } from '../types/Flows.types';
+import { stateAnnotation } from '../types/LangGraph.types';
+import { logger } from '../utils/logger';
+
+export const createDirectEdge = (edge: StepForwardEdge) => {
+  return async (state: typeof stateAnnotation.State) => {
+    if (state.goto) {
+      logger.info({
+        msg: 'Jumping to node',
+        node: state.goto,
+        sessionId: state.sessionId,
+        edgeSource: edge.source,
+        edgeTarget: edge.target,
+      });
+      return state.goto;
+    }
+    // For direct edges, we just return the target of the first edge
+    // since there's no conditional logic needed
+    logger.info({ message: `[Router] Direct edge`, edgeTarget: edge.target, edgeSource: edge.source, sessionId: state.sessionId });
+    return edge.target;
+  };
+};

package/src/edges/createLogicalRouter.ts

@@ -0,0 +1,182 @@
+import { LogicalConditionEdge } from '../types/Flows.types';
+import { stateAnnotation } from '../types/LangGraph.types';
+import { logger } from '../utils/logger';
+import { Agent } from '../agent';
+import { AgentEvents } from '../events/AgentEvents';
+import * as vm from 'vm';
+
+// Default timeout for condition evaluation (in milliseconds)
+const CONDITION_TIMEOUT = 5000; // 5 seconds
+
+export const createLogicalRouter = ({ edges, agent }: { edges: LogicalConditionEdge[]; agent: Agent }) => {
+  return async (state: typeof stateAnnotation.State) => {
+    logger.debug({ msg: `[Router] Evaluating logical conditions for ${edges.length} edges`, sessionId: state.sessionId, edges });
+
+    if (state.goto) {
+      logger.debug({ msg: `[Router] Jumping to node`, node: state.goto, sessionId: state.sessionId, edges });
+      return state.goto;
+    }
+
+    // Separate regular conditions from "else" conditions
+    const regularEdges = edges.filter((edge) => edge.condition.trim() !== 'else');
+    const elseEdges = edges.filter((edge) => edge.condition.trim() === 'else');
+
+    // First, evaluate all regular conditions
+    for (const edge of regularEdges) {
+      const startTime = Date.now();
+
+      try {
+        // Log condition start if in debug mode
+        logger.debug({ msg: '[LogicalCondition] Evaluating condition', edge, sessionId: state.sessionId });
+
+        // Emit ON_LOGICAL_CONDITION event
+        await agent.emit(AgentEvents.ON_LOGICAL_CONDITION, {
+          edge,
+          state,
+          condition: edge.condition,
+        });
+
+        // Customer is responsible for providing valid JavaScript syntax
+        // We execute their condition in a sandboxed VM with timeout protection
+        const conditionCode = `
+          (function({ state }) {
+            return ${edge.condition}
+          })
+        `;
+
+        // Create a sandboxed context with limited access
+        const context = vm.createContext({
+          // Provide safe utilities that customers might need
+          console: {
+            log: (...args: any[]) => logger.debug('Customer condition log:', ...args),
+            error: (...args: any[]) => logger.debug('Customer condition error:', ...args),
+          },
+          // Add other safe globals if needed
+          JSON,
+          Math,
+          Date,
+          // Prevent access to dangerous globals
+          process: undefined,
+          require: undefined,
+          global: undefined,
+          Buffer: undefined,
+        });
+
+        // Compile and run the condition with timeout
+        const script = new vm.Script(conditionCode, {
+          filename: `edge-condition-${edge.source}-to-${edge.target}`,
+        });
+
+        const conditionFn = script.runInContext(context, {
+          timeout: CONDITION_TIMEOUT,
+        });
+
+        // Execute the customer's condition with the current state
+        const result = await Promise.race([
+          Promise.resolve(conditionFn({ state })),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('Condition execution timeout')), CONDITION_TIMEOUT)),
+        ]);
+
+        const executionTime = Date.now() - startTime;
+        const booleanResult = result === true;
+
+        // Log condition result if in debug mode
+        logger.debug({
+          msg: '[LogicalCondition] Condition evaluated',
+          edge,
+          result: booleanResult,
+          executionTimeMs: executionTime,
+          nextNode: booleanResult ? edge.target : null,
+          sessionId: state.sessionId,
+        });
+
+        // Emit ON_LOGICAL_CONDITION_RESULT event
+        await agent.emit(AgentEvents.ON_LOGICAL_CONDITION_RESULT, {
+          edge,
+          state,
+          condition: edge.condition,
+          result: booleanResult,
+          executionTimeMs: executionTime,
+        });
+
+        const goto = state.goto;
+        state.goto = null;
+
+        if (goto) {
+          logger.debug({ msg: `[Router] Jumping to node`, node: goto, sessionId: state.sessionId });
+          return goto;
+        }
+
+        if (booleanResult) {
+          if (edge.source == edge.target) {
+            logger.info({ msg: `[Router] Stay at node ${edge.source}`, node: edge.source, condition: edge.condition });
+          } else {
+            logger.info({
+              msg: `[Router] Logical condition matched`,
+              transitionFrom: edge.source,
+              transitionTo: edge.target,
+              condition: edge.condition,
+              sessionId: state.sessionId,
+            });
+          }
+          return edge.target;
+        }
+      } catch (err) {
+        const executionTime = Date.now() - startTime;
+        const errorObj = err instanceof Error ? err : new Error(String(err));
+
+        const conditionPreview = edge.condition.length > 100 ? `${edge.condition.substring(0, 100)}...` : edge.condition;
+
+        logger.error({
+          msg: `[Router] Error evaluating condition for edge ${edge.source} → ${edge.target}`,
+          condition: conditionPreview,
+          err,
+          edgeIndex: edges.indexOf(edge),
+          timeout: CONDITION_TIMEOUT,
+        });
+
+        // Emit ON_LOGICAL_CONDITION_RESULT event with error
+        const onLogicalConditionResultRes = await agent.emit(AgentEvents.ON_LOGICAL_CONDITION_RESULT, {
+          edge,
+          state,
+          condition: edge.condition,
+          result: false,
+          executionTimeMs: executionTime,
+          error: errorObj,
+        });
+
+        const onLogicalConditionResultHandlerResult = onLogicalConditionResultRes.find((r) => r !== undefined);
+        let throwError = false;
+        throwError = onLogicalConditionResultHandlerResult?.throwError == true;
+
+        // Continue to next edge instead of failing completely
+        // This allows other conditions to be evaluated even if one fails
+        if (throwError) {
+          throw errorObj;
+        }
+        continue;
+      }
+    }
+
+    // If no regular conditions matched, check for "else" conditions
+    if (elseEdges.length > 0) {
+      // Return the first "else" condition's target
+      const elseEdge = elseEdges[0];
+      logger.info({
+        msg: `[Router] Else condition matched`,
+        transitionFrom: elseEdge.source,
+        transitionTo: elseEdge.target,
+        sessionId: state.sessionId,
+      });
+      return elseEdge.target;
+    }
+
+    // If no conditions matched or all failed, return to the source node
+    logger.info({
+      msg: `[Router] Stay at node ${edges[0].source}, no conditions matched`,
+      node: edges[0].source,
+      sessionId: state.sessionId,
+    });
+    return null;
+  };
+};

package/src/edges/createPromptRouter.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+import { PromptConditionEdge } from '../types/Flows.types';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { SystemMessage } from '@langchain/core/messages';
+import { stateAnnotation } from '../types/LangGraph.types';
+import { logger } from '../utils/logger';
+import { compilePrompt } from '../nodes/compilePrompt';
+
+const ROUTER_PROMPT = `
+You are a routing agent that decides which node to take in a flow based on the current state.
+Based on the conversation history and memory state, you should classify the next step for the conversation.
+Each step has a nodeId and a condition. You should decide to move to the right step based on the condition.
+
+Here are the available options and their conditions:
+<%= steps %>
+
+Recent messages:
+<%= messages %>
+
+You MUST respond with the exact nodeId from the options above. Do not use step numbers or any other identifiers.
+
+You should output the result in the following JSON format:
+{
+    "nextNodeId": "exact_node_name_from_options_above",
+    "reasoning": "I think the next step should be exact_node_name_from_options_above because of the following reasons: ..."
+}
+
+Return JSON and nothing more.
+`;
+
+const ROUTER_PROMPT_WITHOUT_REASONING = `
+You are a routing agent that decides which node to take in a flow based on the current state.
+Based on the conversation history and memory state, you should classify the next step for the conversation.
+Each step has a nodeId and a condition. You should decide to move to the right step based on the condition.
+
+Here are the available options and their conditions:
+<%= steps %>
+
+Recent messages:
+<%= messages %>
+
+You MUST respond with the exact nodeId from the options above. Do not use step numbers or any other identifiers.
+
+You should output the result in the following JSON format:
+{
+    "nextNodeId": "exact_node_name_from_options_above"
+}
+
+Return JSON and nothing more.
+`;
+
+export const createPromptRouter = ({
+  edges,
+  llm,
+  includeReasoning = true,
+  maxRetries = 3,
+  canStayInCurrentNode = false,
+  currentNodeName,
+}: {
+  edges: PromptConditionEdge[];
+  llm: BaseLanguageModel;
+  includeReasoning?: boolean;
+  maxRetries?: number;
+  canStayInCurrentNode?: boolean;
+  currentNodeName?: string;
+}) => {
+  return async (state: typeof stateAnnotation.State) => {
+    logger.debug({ msg: `[Router] Executing prompt router`, currentNodeName, sessionId: state.sessionId, edges });
+
+    if (state.goto) {
+      logger.debug({ msg: `[Router] Jumping to node`, node: state.goto, sessionId: state.sessionId, edges });
+      return state.goto;
+    }
+
+    // If canStayInCurrentNode is true and there are no edges, return current node immediately
+    if (canStayInCurrentNode && edges.length === 0 && currentNodeName) {
+      logger.info({
+        msg: `[Router] Stay at node, No edges available and canStayInCurrentNode==true`,
+        node: currentNodeName,
+        sessionId: state.sessionId,
+      });
+      return currentNodeName;
+    }
+
+    // Prepare the steps string
+    let stepsStr = '';
+
+    // Add "stay in current node" option if enabled
+    if (canStayInCurrentNode && currentNodeName) {
+      stepsStr = `- Node: "${currentNodeName}" (stay in current node)\n`;
+    }
+
+    // Add the edge options
+    stepsStr += edges.map((edge) => `- Node: "${edge.target}" - Condition: "${edge.prompt}"`).join('\n');
+
+    // Prepare recent messages (last 10 messages for context)
+    const recentMessages = state.messages.slice(-10);
+    const messagesStr = recentMessages
+      .map((msg) => {
+        const role = msg.getType();
+        const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+        return `${role}: ${content}`;
+      })
+      .join('\n');
+
+    // Select prompt based on reasoning preference
+    const promptTemplate = includeReasoning ? ROUTER_PROMPT : ROUTER_PROMPT_WITHOUT_REASONING;
+
+    // Compile prompt with EJS and parameters
+    const routerPrompt = compilePrompt(promptTemplate, {
+      steps: stepsStr,
+      messages: messagesStr,
+      memory: state.memory,
+      state: state,
+      env: process.env,
+    });
+
+    // Define response schema
+    const responseSchema = includeReasoning
+      ? z.object({
+          nextNodeId: z.string(),
+          reasoning: z.string(),
+        })
+      : z.object({
+          nextNodeId: z.string(),
+        });
+
+    let attempts = 0;
+    let lastError: Error | null = null;
+
+    while (attempts < maxRetries) {
+      try {
+        attempts++;
+
+        // Create messages for the LLM
+        const messages = [new SystemMessage(routerPrompt)];
+
+        // If this is a retry, add the error message
+        if (lastError) {
+          messages.push(
+            new SystemMessage(`Previous attempt failed with error: ${lastError.message}. Please provide a valid JSON response.`),
+          );
+        }
+
+        // Call the LLM with structured output
+        const response = await llm.invoke(messages);
+
+        // Extract content from response
+        let content = '';
+        if (typeof response.content === 'string') {
+          content = response.content;
+        } else if (response.content && typeof response.content === 'object' && 'text' in response.content) {
+          content = (response.content as any).text;
+        }
+
+        // Try to parse JSON from the response
+        let parsedResponse;
+        try {
+          // Clean the response - remove markdown code blocks if present
+          content = content
+            .replace(/```json\n?/g, '')
+            .replace(/```\n?/g, '')
+            .trim();
+          parsedResponse = JSON.parse(content);
+        } catch {
+          throw new Error(`Failed to parse JSON response: ${content}`);
+        }
+
+        // Validate the response
+        const validatedResponse = responseSchema.parse(parsedResponse);
+
+        // Check if the selected node is valid
+        const validTargets = edges.map((e) => e.target);
+        if (canStayInCurrentNode && currentNodeName) {
+          validTargets.push(currentNodeName);
+        }
+
+        if (!validTargets.includes(validatedResponse.nextNodeId)) {
+          throw new Error(`Invalid nextNodeId: ${validatedResponse.nextNodeId}. Must be one of: ${validTargets.join(', ')}`);
+        }
+
+        const decision = validatedResponse.nextNodeId === currentNodeName ? 'stay in current node' : validatedResponse.nextNodeId;
+        const reasoning = includeReasoning && 'reasoning' in validatedResponse ? ` - Reasoning: ${validatedResponse.reasoning}` : '';
+        logger.debug({ msg: `[Router] Decision: ${decision}`, reasoning, sessionId: state.sessionId, edges });
+
+        return validatedResponse.nextNodeId;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        logger.warn({
+          message: `[Router] Prompt router attempt ${attempts} failed`,
+          err: lastError,
+          attempt: attempts,
+          maxRetries,
+          sessionId: state.sessionId,
+          edges,
+        });
+
+        if (attempts >= maxRetries) {
+          logger.error({
+            msg: '[Router] Prompt router reached max retries',
+            lastError: lastError.message,
+            sessionId: state.sessionId,
+            edges,
+          });
+          throw new Error('Prompt router reached max retries, no edges available for routing');
+        }
+      }
+    }
+
+    // This should never be reached, but TypeScript needs it
+    throw new Error('Unexpected error in prompt router');
+  };
+};