@minded-ai/mindedjs 1.0.101 → 1.0.103-beta-1

package/docs/platform/parallel-llm.md

@@ -1,242 +0,0 @@
-# Parallel LLM Requests
-
-Parallel LLM requests can significantly reduce latency by sending multiple identical requests and using the fastest response. This feature can reduce response times by 30-50% in scenarios with variable network conditions.
-
-## Quick Start
-
-The easiest way to enable parallel requests is through your `minded.json` configuration:
-
-```json
-{
-  "flows": ["./src/flows"],
-  "tools": ["./src/tools"],
-  "agent": "./src/agent.ts",
-  "llm": {
-    "name": "MindedChatOpenAI",
-    "properties": {
-      "model": "gpt-4o",
-      "numParallelRequests": 3,
-      "logTimings": true
-    }
-  }
-}
-```
-
-Your agent will automatically use parallel requests for all LLM calls:
-
-```typescript
-import { Agent } from '@minded-ai/mindedjs';
-import memorySchema from './agentMemorySchema';
-import config from '../minded.json';
-import tools from './tools';
-
-const agent = new Agent({
-  memorySchema,
-  config, // Parallel configuration is automatically applied
-  tools,
-});
-```
-
-## Configuration Options
-
-### MindedChatOpenAI (Recommended)
-
-For agents running on the Minded platform, use `MindedChatOpenAI` with parallel configuration:
-
-```json
-{
-  "llm": {
-    "name": "MindedChatOpenAI",
-    "properties": {
-      "model": "gpt-4o",
-      "numParallelRequests": 3,
-      "logTimings": true,
-      "temperature": 0.7
-    }
-  }
-}
-```
-
-### AzureChatOpenAI
-
-For Azure OpenAI deployments:
-
-```json
-{
-  "llm": {
-    "name": "AzureChatOpenAI",
-    "properties": {
-      "model": "gpt-4o",
-      "numParallelRequests": 3,
-      "logTimings": true,
-      "azureOpenAIApiVersion": "2024-02-01"
-    }
-  }
-}
-```
-
-Required environment variables:
-
-```env
-AZURE_OPENAI_API_KEY=your_azure_key
-AZURE_OPENAI_API_INSTANCE_NAME=your_instance_name
-AZURE_OPENAI_API_DEPLOYMENT_NAME=your_deployment_name
-```
-
-### ChatOpenAI
-
-For standard OpenAI API:
-
-```json
-{
-  "llm": {
-    "name": "ChatOpenAI",
-    "properties": {
-      "model": "gpt-4o",
-      "numParallelRequests": 3,
-      "logTimings": true,
-      "openAIApiKey": "${OPENAI_API_KEY}"
-    }
-  }
-}
-```
-
-## Configuration Parameters
-
-| Parameter             | Type    | Default | Description                                   |
-| --------------------- | ------- | ------- | --------------------------------------------- |
-| `numParallelRequests` | number  | 1       | Number of parallel requests (2-5 recommended) |
-| `logTimings`          | boolean | false   | Enable detailed timing logs                   |
-
-## Performance Notes
-
-- **Optimal Range**: 2-3 parallel requests usually provide the best latency/cost balance
-- **Cost Impact**: You pay for all parallel requests made
-- **Best Use Cases**: Variable network conditions, consistency requirements
-- **Latency Reduction**: Typically 30-50% faster response times
-
-## Monitoring Performance
-
-When `logTimings: true` is enabled, you'll see detailed performance logs:
-
-```
-[Model] Fastest request completed { requestTime: 1.234, numParallelRequests: 3 }
-[Model] Time saved using parallel requests {
-  fastestRequestTime: 1.234,
-  secondFastestRequestTime: 1.567,
-  allFinishTime: 2.345,
-  timeSaved: 1.111,
-  timeSavedFromSecond: 0.333
-}
-```
-
-## Advanced Usage
-
-### Dynamic Configuration
-
-You can adjust parallel requests based on environment:
-
-```json
-{
-  "llm": {
-    "name": "MindedChatOpenAI",
-    "properties": {
-      "model": "gpt-4o",
-      "numParallelRequests": "${NODE_ENV === 'production' ? 3 : 1}",
-      "logTimings": "${NODE_ENV === 'development'}"
-    }
-  }
-}
-```
-
-### Manual Instantiation with createParallelWrapper
-
-For advanced use cases where you need direct control over the LLM instance, you can manually apply parallel wrapping:
-
-```typescript
-import { createParallelWrapper } from '@minded-ai/mindedjs';
-import { ChatOpenAI, AzureChatOpenAI } from '@langchain/openai';
-
-// Manual wrapping for ChatOpenAI
-const parallelOpenAI = createParallelWrapper(
-  new ChatOpenAI({
-    openAIApiKey: process.env.OPENAI_API_KEY,
-    model: 'gpt-4o',
-    temperature: 0.7,
-  }),
-  {
-    numParallelRequests: 3,
-    logTimings: true,
-  },
-);
-
-// Manual wrapping for AzureChatOpenAI
-const parallelAzure = createParallelWrapper(
-  new AzureChatOpenAI({
-    azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,
-    azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_INSTANCE!,
-    azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_DEPLOYMENT!,
-    azureOpenAIApiVersion: '2024-02-01',
-  }),
-  {
-    numParallelRequests: 2,
-    logTimings: false,
-  },
-);
-
-// Use directly with Agent (bypassing configuration)
-const agent = new Agent({
-  memorySchema,
-  config: {
-    flows: ['./flows'],
-    tools: [],
-    llm: parallelOpenAI as any, // Direct LLM instance
-  },
-  tools: [],
-});
-```
-
-**Note**: The configuration-based approach is recommended for most use cases as it's simpler and more maintainable. Use manual instantiation only when you need specific control over LLM creation or are integrating with existing LangChain workflows.
-
-## How It Works
-
-### MindedChatOpenAI (Backend Processing)
-
-- Parallel requests are handled on the Minded platform backend
-- Multiple requests sent to Azure OpenAI from the backend
-- Fastest response returned to your agent
-- Optimal for production deployments
-
-### Other LLM Providers (Client-Side Processing)
-
-- Parallel requests handled in your application
-- Multiple requests sent directly to the LLM provider
-- Good for development and custom deployments
-
-## Best Practices
-
-1. **Start Small**: Begin with 2-3 parallel requests
-2. **Monitor Costs**: Each parallel request counts toward your usage
-3. **Enable Logging**: Use `logTimings: true` during development to measure improvements
-4. **Environment-Specific**: Use fewer parallel requests in development
-5. **Configuration Over Code**: Prefer `minded.json` configuration over manual instantiation
-
-## Troubleshooting
-
-### No Performance Improvement
-
-- Check network latency variability
-- Ensure `numParallelRequests > 1`
-- Verify timing logs are showing multiple requests
-
-### Increased Costs
-
-- Reduce `numParallelRequests`
-- Consider cost vs. latency trade-offs
-- Monitor usage patterns
-
-### Rate Limiting
-
-- Lower `numParallelRequests`
-- Implement backoff strategies
-- Contact provider about rate limits

package/src/browserTask/executeBrowserTask.ts

@@ -1,213 +0,0 @@
-import { logger } from '../utils/logger';
-
-// Browser Use Cloud API configuration
-const BROWSER_USE_API_BASE_URL = 'https://api.browser-use.com/api/v1';
-
-// Types for Browser Use Cloud API
-export interface CloudTaskResponse {
-  id: string;
-  status: string;
-  live_url?: string;
-  steps?: any[];
-  output?: string;
-}
-
-// Browser Use Cloud API methods
-export const createCloudTask = async (prompt: string, model?: string): Promise<string> => {
-  const apiKey = process.env.BROWSER_USE_API_KEY;
-  if (!apiKey) {
-    throw new Error('BROWSER_USE_API_KEY environment variable is required');
-  }
-
-  logger.debug({ msg: 'Creating cloud browser task', prompt: prompt.substring(0, 100) + '...' });
-
-  const response = await fetch(`${BROWSER_USE_API_BASE_URL}/run-task`, {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      task: prompt,
-      use_proxy: false,
-      llm_model: model || 'gpt-4o',
-    }),
-  });
-
-  if (!response.ok) {
-    logger.error({ msg: 'Failed to create cloud browser task', status: response.status, statusText: response.statusText });
-    throw new Error(`Failed to create browser task: ${response.statusText}`);
-  }
-
-  const data = await response.json();
-  logger.debug({ msg: 'Cloud browser task created', taskId: data.id });
-  return data.id;
-};
-
-export const getTaskDetails = async (taskId: string): Promise<CloudTaskResponse> => {
-  const apiKey = process.env.BROWSER_USE_API_KEY;
-  if (!apiKey) {
-    throw new Error('BROWSER_USE_API_KEY environment variable is required');
-  }
-
-  const response = await fetch(`${BROWSER_USE_API_BASE_URL}/task/${taskId}`, {
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-    },
-  });
-
-  if (!response.ok) {
-    logger.error({ msg: 'Failed to get task details', taskId, status: response.status, statusText: response.statusText });
-    throw new Error(`Failed to get task details: ${response.statusText}`);
-  }
-
-  return response.json();
-};
-
-export const waitForLiveUrl = async (taskId: string, maxWaitTime: number = 30000): Promise<CloudTaskResponse> => {
-  const startTime = Date.now();
-  const pollInterval = 2000; // 2 seconds
-  let pollCount = 0;
-
-  logger.debug({ msg: 'Starting to poll for live_url', taskId, maxWaitTime, pollInterval });
-
-  while (Date.now() - startTime < maxWaitTime) {
-    pollCount++;
-    const elapsedTime = Date.now() - startTime;
-
-    logger.trace({
-      msg: 'Polling for live_url',
-      taskId,
-      pollCount,
-      elapsedTime,
-      remainingTime: maxWaitTime - elapsedTime,
-    });
-
-    const taskDetails = await getTaskDetails(taskId);
-
-    logger.trace({
-      msg: 'Task details received',
-      taskId,
-      status: taskDetails.status,
-      hasLiveUrl: !!taskDetails.live_url,
-      pollCount,
-    });
-
-    if (taskDetails.live_url) {
-      logger.debug({
-        msg: 'Live URL available',
-        taskId,
-        liveUrl: taskDetails.live_url,
-        pollCount,
-        totalTime: elapsedTime,
-      });
-      return taskDetails;
-    }
-
-    if (taskDetails.status === 'failed' || taskDetails.status === 'stopped') {
-      logger.error({
-        msg: 'Task failed while waiting for live_url',
-        taskId,
-        status: taskDetails.status,
-        pollCount,
-        elapsedTime,
-      });
-      throw new Error(`Task failed with status: ${taskDetails.status}`);
-    }
-
-    logger.trace({
-      msg: 'Live URL not yet available, continuing to poll',
-      taskId,
-      status: taskDetails.status,
-      pollCount,
-      nextPollIn: pollInterval,
-    });
-
-    await new Promise((resolve) => setTimeout(resolve, pollInterval));
-  }
-
-  logger.error({
-    msg: 'Timeout waiting for live_url',
-    taskId,
-    pollCount,
-    totalTime: Date.now() - startTime,
-    maxWaitTime,
-  });
-  throw new Error('Timeout waiting for live_url to become available');
-};
-
-export const waitForCompletion = async (taskId: string, maxWaitTime: number = 300000): Promise<CloudTaskResponse> => {
-  const startTime = Date.now();
-  const pollInterval = 3000; // 3 seconds for completion polling
-  let pollCount = 0;
-
-  logger.debug({ msg: 'Starting to poll for task completion', taskId, maxWaitTime, pollInterval });
-
-  while (Date.now() - startTime < maxWaitTime) {
-    pollCount++;
-    const elapsedTime = Date.now() - startTime;
-
-    logger.trace({
-      msg: 'Polling for task completion',
-      taskId,
-      pollCount,
-      elapsedTime,
-      remainingTime: maxWaitTime - elapsedTime,
-    });
-
-    const taskDetails = await getTaskDetails(taskId);
-
-    logger.trace({
-      msg: 'Task completion status received',
-      taskId,
-      status: taskDetails.status,
-      pollCount,
-      hasOutput: !!taskDetails.output,
-      stepCount: taskDetails.steps?.length || 0,
-    });
-
-    if (taskDetails.status === 'finished') {
-      logger.debug({
-        msg: 'Task completed successfully',
-        taskId,
-        pollCount,
-        totalTime: elapsedTime,
-        stepCount: taskDetails.steps?.length || 0,
-        hasOutput: !!taskDetails.output,
-      });
-      return taskDetails;
-    }
-
-    if (taskDetails.status === 'failed' || taskDetails.status === 'stopped') {
-      logger.error({
-        msg: 'Task failed during completion polling',
-        taskId,
-        status: taskDetails.status,
-        pollCount,
-        elapsedTime,
-        stepCount: taskDetails.steps?.length || 0,
-      });
-      throw new Error(`Task failed with status: ${taskDetails.status}`);
-    }
-
-    logger.trace({
-      msg: 'Task still in progress, continuing to poll',
-      taskId,
-      status: taskDetails.status,
-      pollCount,
-      stepCount: taskDetails.steps?.length || 0,
-      nextPollIn: pollInterval,
-    });
-
-    await new Promise((resolve) => setTimeout(resolve, pollInterval));
-  }
-
-  logger.error({
-    msg: 'Timeout waiting for task completion',
-    taskId,
-    pollCount,
-    totalTime: Date.now() - startTime,
-    maxWaitTime,
-  });
-  throw new Error('Timeout waiting for task completion');
-};

package/src/nodes/addBrowserTaskNode.ts

@@ -1,114 +0,0 @@
-import { RunnableLike } from '@langchain/core/runnables';
-import { BrowserTaskNode, NodeType } from '../types/Flows.types';
-import { PreCompiledGraph, stateAnnotation } from '../types/LangGraph.types';
-import { HistoryStep } from '../types/Agent.types';
-import { logger } from '../utils/logger';
-import { createHistoryStep } from '../utils/history';
-import { AIMessage } from '@langchain/core/messages';
-import { v4 as uuidv4 } from 'uuid';
-import { Agent } from '../agent';
-import { createCloudTask, waitForLiveUrl } from '../browserTask/executeBrowserTask';
-
-type AddBrowserTaskNodeParams = {
-  graph: PreCompiledGraph;
-  node: BrowserTaskNode;
-  agent: Agent;
-};
-
-export const addBrowserTaskNode = async ({ graph, node }: AddBrowserTaskNodeParams) => {
-  const callback: RunnableLike = async (state: typeof stateAnnotation.State) => {
-    logger.info({ msg: `Executing browser task node ${node.displayName}`, prompt: node.prompt });
-    logger.info({ msg: `Executing browser task node ${node.displayName}`, prompt: node.prompt });
-
-    const prompt = `
-    Follow the instructions. Any retrieved data should be printed as string and not saved to a file
-    # Task instructions:\n${node.prompt}\n\n
-    ${state.memory ? `# Task context:\n${JSON.stringify(state.memory)}\n\n` : ''}
-    # Conversation history:\n${state.messages.map((m) => `${m.getType()}: ${m.content}`).join('\n')}
-    `;
-
-    const toolCallId = uuidv4();
-    const toolCallingMessageId = uuidv4();
-
-    try {
-      // Create the browser task in the cloud
-      const taskId = await createCloudTask(
-        `Follow the instructions. Any retrieved data should be printed as string and not saved to a file.\n${node.prompt}`,
-        node.model,
-      );
-      logger.debug({ msg: 'Browser task created', taskId });
-
-      // Wait for live_url to become available
-      const taskDetails = await waitForLiveUrl(taskId);
-      logger.debug({ msg: 'Live URL available', taskId, liveUrl: taskDetails.live_url });
-
-      const toolCallingMessage = new AIMessage({
-        id: toolCallingMessageId,
-        content: '',
-        tool_calls: [
-          {
-            id: toolCallId,
-            name: 'browser-task',
-            args: {
-              prompt,
-              taskId,
-            },
-          },
-        ],
-        additional_kwargs: {
-          mindedMetadata: {
-            nodeType: NodeType.BROWSER_TASK,
-            taskId,
-            liveUrl: taskDetails.live_url,
-          },
-        },
-      });
-
-      return {
-        history: createHistoryStep<HistoryStep>(state.history, {
-          type: NodeType.BROWSER_TASK,
-          nodeId: node.name,
-          nodeDisplayName: node.displayName,
-          raw: { taskId, liveUrl: taskDetails.live_url },
-          messageIds: [toolCallingMessageId],
-        }),
-        messages: [toolCallingMessage],
-      };
-    } catch (error: any) {
-      logger.error(`Error creating browser task node ${node.displayName}: ${error}`);
-
-      const toolCallingMessage = new AIMessage({
-        id: toolCallingMessageId,
-        content: '',
-        tool_calls: [
-          {
-            id: toolCallId,
-            name: 'browser-task',
-            args: {
-              prompt,
-              error: error.message,
-            },
-          },
-        ],
-        additional_kwargs: {
-          mindedMetadata: {
-            nodeType: NodeType.BROWSER_TASK,
-            error: error.message,
-          },
-        },
-      });
-
-      return {
-        history: createHistoryStep<HistoryStep>(state.history, {
-          type: NodeType.BROWSER_TASK,
-          nodeId: node.name,
-          nodeDisplayName: node.displayName,
-          raw: error,
-          messageIds: [toolCallingMessageId],
-        }),
-        messages: [toolCallingMessage],
-      };
-    }
-  };
-  graph.addNode(node.name, callback);
-};

package/src/nodes/addBrowserTaskRunNode.ts

@@ -1,138 +0,0 @@
-import { PreCompiledGraph, stateAnnotation } from '../types/LangGraph.types';
-import { RunnableLike } from '@langchain/core/runnables';
-import { internalNodesSuffix, NodeType, BrowserTaskNode } from '../types/Flows.types';
-import { ToolMessage, AIMessage } from '@langchain/core/messages';
-import { Agent } from '../agent';
-import { logger } from '../utils/logger';
-import { createHistoryStep } from '../utils/history';
-import { HistoryStep } from '../types/Agent.types';
-import { v4 as uuidv4 } from 'uuid';
-import { waitForCompletion } from '../browserTask/executeBrowserTask';
-
-type AddBrowserTaskRunNodeParams = {
-  graph: PreCompiledGraph;
-  browserTaskNode: BrowserTaskNode;
-  attachedToNodeName: string;
-  agent: Agent;
-};
-
-export const buildBrowserTaskRunNodeName = (nodeName: string) => `${nodeName}${internalNodesSuffix.BROWSER_TASK_RUN}`;
-
-export const addBrowserTaskRunNode = async ({ graph, browserTaskNode, attachedToNodeName }: AddBrowserTaskRunNodeParams) => {
-  const callback: RunnableLike = async (state: typeof stateAnnotation.State) => {
-    logger.info(`Executing browser task run node for ${browserTaskNode.displayName}`);
-
-    const toolCallObj = state.messages[state.messages.length - 1] as any;
-    if (!toolCallObj.tool_calls) {
-      throw new Error('Tool call not found');
-    }
-
-    const toolCall = toolCallObj.tool_calls[0];
-    const taskId = toolCall.args.taskId;
-
-    if (!taskId) {
-      throw new Error('Task ID not found in tool call arguments');
-    }
-
-    try {
-      // Wait for task completion
-      const completedTask = await waitForCompletion(taskId);
-      logger.debug({ msg: 'Browser task completed', taskId, output: completedTask.output });
-
-      // Create tool message with the result
-      const toolMessage = new ToolMessage({
-        id: uuidv4(),
-        content: JSON.stringify({
-          result: completedTask.output || 'Task completed successfully',
-          steps: completedTask.steps || [],
-        }),
-        name: 'browser-task',
-        tool_call_id: toolCall.id,
-        status: 'success',
-        additional_kwargs: {
-          mindedMetadata: {
-            nodeType: NodeType.BROWSER_TASK,
-            taskId,
-            steps: completedTask.steps,
-          },
-        },
-      });
-
-      // Update the AI message with steps using the message reducer pattern
-      const updatedAIMessage = new AIMessage({
-        id: toolCallObj.id,
-        content: toolCallObj.content,
-        tool_calls: toolCallObj.tool_calls,
-        additional_kwargs: {
-          ...toolCallObj.additional_kwargs,
-          mindedMetadata: {
-            ...toolCallObj.additional_kwargs?.mindedMetadata,
-            steps: completedTask.steps,
-            status: 'completed',
-          },
-          update: true, // This triggers the message reducer to update the existing message
-        },
-      });
-
-      return {
-        messages: [toolMessage, updatedAIMessage],
-        history: createHistoryStep<HistoryStep>(state.history, {
-          type: NodeType.BROWSER_TASK,
-          nodeId: browserTaskNode.name,
-          nodeDisplayName: browserTaskNode.displayName,
-          raw: completedTask,
-          messageIds: [],
-        }),
-      };
-    } catch (error: any) {
-      logger.error({ msg: 'Error executing browser task run node', error });
-
-      const errorToolMessage = new ToolMessage({
-        id: uuidv4(),
-        content: JSON.stringify({
-          error: error instanceof Error ? error.message : error.toString(),
-        }),
-        status: 'error',
-        name: 'browser-task',
-        tool_call_id: toolCall.id,
-        additional_kwargs: {
-          mindedMetadata: {
-            nodeType: NodeType.BROWSER_TASK,
-            taskId,
-            error: error.message,
-          },
-        },
-      });
-
-      // Update the AI message with error status
-      const updatedAIMessage = new AIMessage({
-        id: toolCallObj.id,
-        content: toolCallObj.content,
-        tool_calls: toolCallObj.tool_calls,
-        additional_kwargs: {
-          ...toolCallObj.additional_kwargs,
-          mindedMetadata: {
-            ...toolCallObj.additional_kwargs?.mindedMetadata,
-            status: 'failed',
-            error: error.message,
-          },
-          update: true,
-        },
-      });
-
-      return {
-        messages: [errorToolMessage, updatedAIMessage],
-        history: createHistoryStep<HistoryStep>(state.history, {
-          type: NodeType.BROWSER_TASK,
-          nodeId: browserTaskNode.name,
-          nodeDisplayName: browserTaskNode.displayName,
-          raw: error,
-          messageIds: [],
-        }),
-      };
-    }
-  };
-
-  graph.addNode(buildBrowserTaskRunNodeName(attachedToNodeName), callback);
-  graph.addEdge(attachedToNodeName as any, buildBrowserTaskRunNodeName(attachedToNodeName) as any);
-};