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

package/src/internalTools/documentExtraction/types.ts

@@ -0,0 +1,59 @@
+import { ZodType as ZodSchema, ZodTypeAny } from 'zod';
+
+export interface DocumentProcessorConfig {
+  llamaCloudApiKey?: string;
+  useBase64?: boolean;
+  maxImageWidth?: number;
+  imageQuality?: number;
+}
+export interface DocumentExtractionOptions {
+  documentPath?: string;
+  documentContent?: Buffer | string;
+  documentUrl?: string;
+  schema?: ZodSchema<any> | ZodTypeAny;
+  llmConfig?: {
+    model?: string;
+    temperature?: number;
+  };
+  systemPrompt?: string;
+}
+export interface DocumentProcessingResult<T = any> {
+  data: T;
+  metadata: {
+    fileSize?: number;
+    fileType: string;
+    processingTime: number;
+    contentLength: number;
+  };
+}
+export const SUPPORTED_DOCUMENT_TYPES = [
+  // Images
+  '.jpg',
+  '.jpeg',
+  '.png',
+  '.gif',
+  '.bmp',
+  '.webp',
+  '.tiff',
+  // Documents
+  '.pdf',
+  '.doc',
+  '.docx',
+  '.txt',
+  '.rtf',
+  '.odt',
+  // Spreadsheets
+  '.xls',
+  '.xlsx',
+  '.csv',
+  '.ods',
+  // Presentations
+  '.ppt',
+  '.pptx',
+  '.odp',
+  // Other formats
+  '.html',
+  '.htm',
+  '.md',
+  '.xml',
+];

package/src/internalTools/libraryActionRunnerTool.ts

@@ -0,0 +1,62 @@
+import { Tool, ToolExecuteInput } from '../types/Tools.types';
+import { tools } from '../toolsLibrary';
+import { logger } from '../utils/logger';
+
+const libraryActionRunnerToolCreator = (actionKey: string, nodeTitle: string): Tool<any, any> => {
+  // Find the corresponding library tool by key name (e.g., "parseDocument")
+  const libraryTool = (tools as any)[actionKey];
+
+  if (!libraryTool?.default) {
+    throw new Error(`Library tool '${actionKey}' not found in toolsLibrary`);
+  }
+
+  if (!libraryTool.schema) {
+    throw new Error(`Schema not found for library tool '${actionKey}'. Make sure the tool exports a 'schema' object.`);
+  }
+
+  const zodSchema = libraryTool.schema;
+
+  // Create a description using the library tool's own description
+  const description = libraryTool.default.description || `Run ${nodeTitle} action from Minded Tools library.`;
+
+  const tool = {
+    name: nodeTitle,
+    description,
+    input: zodSchema,
+    execute: async ({ input, state, agent }: ToolExecuteInput<typeof zodSchema>) => {
+      try {
+        // Find the corresponding library tool
+        const libraryTool = Object.values(tools).find((toolModule) => toolModule.default && toolModule.default.name === actionKey);
+
+        if (!libraryTool?.default) {
+          throw new Error(`Library tool '${actionKey}' not found in toolsLibrary`);
+        }
+
+        logger.debug({
+          msg: `[Tool] Executing library tool`,
+          toolName: actionKey,
+          nodeTitle,
+        });
+
+        // Execute the library tool directly
+        const result = await libraryTool.default.execute({ input, state, agent });
+
+        return {
+          result: result?.result,
+        };
+      } catch (err) {
+        logger.error({
+          message: `[Tool] Error executing library tool`,
+          err,
+          toolName: actionKey,
+          nodeTitle,
+        });
+        throw err;
+      }
+    },
+  };
+
+  return tool;
+};
+
+export default libraryActionRunnerToolCreator;

package/src/internalTools/timer.ts

@@ -0,0 +1,125 @@
+import * as mindedConnection from '../platform/mindedConnection';
+import { mindedConnectionSocketMessageType, TimerResetResponse, TimerCancelResponse } from '../platform/mindedConnectionTypes';
+import { State } from '../types/LangGraph.types';
+
+// Store timer handlers by timer name (one handler per timer name)
+export const timerHandlers = new Map<
+  string,
+  {
+    handler: (params: { sessionId: string; payload: Record<string, any>; state: State<any> }) => void | Promise<void>;
+  }
+>();
+
+/**
+ * Reset or set a timer for a specific session.
+ * When the timer expires, the registered timer handler will be called.
+ *
+ * @param params - The timer configuration
+ * @param params.sessionId - The session ID to associate the timer with
+ * @param params.seconds - Number of seconds until the timer expires
+ * @param params.timerName - Unique name for this timer (used for cancellation and identification)
+ * @param params.payload - Additional data to pass to the timer handler when it triggers
+ * @returns Promise resolving to timer reset response
+ * @throws {Error} When the Minded connection is not established
+ *
+ * @example
+ * ```typescript
+ * import { resetTimer } from '@minded-ai/mindedjs';
+ *
+ * // Set a timer to follow up in 10 seconds
+ * await resetTimer({
+ *   sessionId: 'session-123',
+ *   seconds: 10,
+ *   timerName: 'followup',
+ *   payload: {
+ *     message: 'Are you still there?'
+ *   }
+ * });
+ * ```
+ */
+export async function resetTimer({
+  sessionId,
+  seconds,
+  timerName,
+  payload = {},
+}: {
+  sessionId: string;
+  seconds: number;
+  timerName: string;
+  payload?: Record<string, any>;
+}): Promise<TimerResetResponse> {
+  return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.TIMER_RESET, {
+    sessionId,
+    seconds,
+    timerName,
+    eventArgs: payload,
+  });
+}
+
+/**
+ * Cancel an existing timer for a specific session.
+ *
+ * @param sessionId - The session ID the timer is associated with
+ * @param timerName - The name of the timer to cancel
+ * @returns Promise resolving to timer cancel response
+ * @throws {Error} When the Minded connection is not established
+ *
+ * @example
+ * ```typescript
+ * import { cancelTimer } from '@minded-ai/mindedjs';
+ *
+ * // Cancel a previously set timer
+ * await cancelTimer('session-123', 'followup');
+ * ```
+ */
+export async function cancelTimer(sessionId: string, timerName: string): Promise<TimerCancelResponse> {
+  if (!mindedConnection.isConnected()) {
+    throw new Error('Minded connection is not established when trying to cancel timer');
+  }
+  return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.TIMER_CANCEL, {
+    sessionId,
+    timerName,
+  });
+}
+
+/**
+ * Register a handler for timer trigger events for a specific timer name.
+ * The handler will be called when the specified timer expires for any session.
+ *
+ * Note: Only one handler per timer name is supported. Calling this function multiple times
+ * with the same timer name will replace the previous handler.
+ *
+ * @param params - The configuration for the timer handler
+ * @param params.timerName - The name of the timer to handle
+ * @param params.handler - Function to call when the timer triggers
+ *
+ * @example
+ * ```typescript
+ * import { onTimer } from '@minded-ai/mindedjs';
+ *
+ * // Register a handler for the 'followup' timer
+ * onTimer({
+ *   timerName: 'followup',
+ *   handler: async ({ sessionId, payload }) => {
+ *     logger.info({ msg: `Followup timer triggered for session ${sessionId}` });
+ *
+ *     // Handle the followup timer
+ *     await agent.invoke({
+ *       triggerName: 'timerFollowup',
+ *       triggerBody: { message: payload.message },
+ *       sessionId
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export function onTimer({
+  timerName,
+  handler,
+}: {
+  timerName: string;
+  handler: (params: { sessionId: string; payload: Record<string, any>; state: State<any> }) => void | Promise<void>;
+}): void {
+  // Set the handler for this timer name (replaces any existing handler)
+  timerHandlers.set(timerName, { handler });
+}

package/src/internalTools/voice/escalateVoiceCall.ts

@@ -0,0 +1,15 @@
+import * as mindedConnection from '../../platform/mindedConnection';
+import { mindedConnectionSocketMessageType } from '../../platform/mindedConnectionTypes';
+
+/* 
+ * Escalate the voice session
+ * @param parameters - The parameters to escalate the voice session. Parameters will be handeled differently according to the VOIP provider.
+ */
+export const escalateVoiceCall = (sessionId: string, parameters: any): void => {
+  mindedConnection.emit(mindedConnectionSocketMessageType.VOICE_ESCALATE, {
+    type: mindedConnectionSocketMessageType.VOICE_ESCALATE,
+    sessionId,
+    timestamp: Date.now(),
+    parameters,
+  });
+};

package/src/internalTools/voice/retell.ts

@@ -0,0 +1,28 @@
+import * as mindedConnection from '../../platform/mindedConnection';
+import { mindedConnectionSocketMessageType, TimerResetResponse, RetellGetCallResponse } from '../../platform/mindedConnectionTypes';
+
+export async function retellCall({
+  sessionId,
+  callName,
+  callAgentId,
+  vars = {},
+}: {
+  sessionId: string;
+  callName: string;
+  callAgentId: string;
+  vars?: Record<string, any>;
+}): Promise<TimerResetResponse> {
+  return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.RETELL_CALL, {
+    sessionId,
+    callName,
+    callAgentId,
+    vars,
+  });
+}
+
+export async function retellGetCall({ sessionId, callId }: { sessionId: string; callId: string }): Promise<RetellGetCallResponse> {
+  return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.RETELL_GET_CALL, {
+    sessionId,
+    callId,
+  });
+}

package/src/internalTools/voice/sendPlaceholderMessage.ts

@@ -0,0 +1,27 @@
+import * as mindedConnection from '../../platform/mindedConnection';
+import { mindedConnectionSocketMessageType } from '../../platform/mindedConnectionTypes';
+
+/**
+ * Send a placeholder message to the dashboard voice session.
+ * This is typically used for voice sessions to provide immediate feedback to users.
+ * 
+ * @param params - The parameters for sending the placeholder message
+ * @param params.sessionId - The session ID of the voice session
+ * @param params.message - The placeholder message to send
+ * @throws {Error} When the Minded connection is not established
+ */
+export async function sendPlaceholderMessage(params: { sessionId: string; message: string }): Promise<void> {
+  const { sessionId, message } = params;
+
+  if (!mindedConnection.isConnected()) {
+    throw new Error('Minded connection is not established when trying to send placeholder message');
+  }
+
+  const connection = mindedConnection;
+  connection.emit(mindedConnectionSocketMessageType.VOICE_PLACEHOLDER_MESSAGES, {
+    sessionId,
+    message,
+    timestamp: Date.now(),
+    type: mindedConnectionSocketMessageType.VOICE_PLACEHOLDER_MESSAGES,
+  });
+} 

package/src/interrupts/BaseInterruptSessionManager.ts

@@ -0,0 +1,80 @@
+import { State } from '../types/LangGraph.types';
+import { GraphInterrupt } from '@langchain/langgraph';
+import { logger } from '../utils/logger';
+import { TriggerEvent } from '../types/Agent.types';
+
+export enum InterruptType {
+  NEW_TRIGGERS = 'NEW_TRIGGERS',
+  HUMAN_IN_THE_LOOP = 'HUMAN_IN_THE_LOOP',
+}
+
+export const QUEUE_INTERRUPT_DETECTED_BEFORE_SPEECH = 'QUEUE_INTERRUPT_DETECTED_BEFORE_SPEECH';
+
+export type QueuedMessage = TriggerEvent;
+
+export interface InterruptPayload {
+  type: InterruptType;
+  updateStateObject?: State;
+  id?: string;
+}
+
+export interface InterruptSessionManager {
+  isProcessed(sessionId: string): boolean | Promise<boolean>;
+  /**
+   * Atomically attempts to acquire a lock for the given session.
+   * This method should only succeed if the session is not already being processed.
+   *
+   * @param sessionId - The session ID to lock
+   * @returns true if the lock was successfully acquired, false if the session is already locked
+   */
+  lock(sessionId: string): boolean | Promise<boolean>;
+  release(sessionId: string): void | Promise<void>;
+  enqueueMessage(sessionId: string, message: QueuedMessage): void | Promise<void>;
+  dequeueAll(sessionId: string): QueuedMessage[] | Promise<QueuedMessage[]>;
+  dequeue(sessionId: string): QueuedMessage | null | Promise<QueuedMessage | null>;
+  checkQueueAndInterrupt(sessionId: string, updateStateObject?: State): Promise<boolean>;
+}
+
+export abstract class BaseInterruptSessionManager implements InterruptSessionManager {
+  // Abstract methods that subclasses must implement for queue management
+  abstract isProcessed(sessionId: string): boolean | Promise<boolean>;
+  /**
+   * Atomically attempts to acquire a lock for the given session.
+   * This method should only succeed if the session is not already being processed.
+   * Implementations must ensure this operation is atomic to prevent race conditions.
+   *
+   * @param sessionId - The session ID to lock
+   * @returns true if the lock was successfully acquired, false if the session is already locked
+   */
+  abstract lock(sessionId: string): boolean | Promise<boolean>;
+  abstract release(sessionId: string): void | Promise<void>;
+  abstract enqueueMessage(sessionId: string, message: QueuedMessage): void | Promise<void>;
+  abstract dequeueAll(sessionId: string): QueuedMessage[] | Promise<QueuedMessage[]>;
+  abstract dequeue(sessionId: string): QueuedMessage | null | Promise<QueuedMessage | null>;
+
+  // Abstract method to check if queue has messages - this is the only queue-specific part
+  protected abstract hasQueuedMessages(sessionId: string): boolean | Promise<boolean>;
+  protected abstract getQueuedMessages(sessionId: string): QueuedMessage[] | Promise<QueuedMessage[]>;
+
+  // Common implementation of checkQueueAndInterrupt
+  async checkQueueAndInterrupt(sessionId: string, updateStateObject?: State): Promise<boolean> {
+    if (await this.hasQueuedMessages(sessionId)) {
+      logger.trace({ msg: 'graph has queued messagess, interrupting graph', sessionId });
+
+      // Interrupt the graph with NEW_TRIGGERS flag and optional updateStateObject
+      const interruptPayload: InterruptPayload = { type: InterruptType.NEW_TRIGGERS };
+      if (updateStateObject) {
+        interruptPayload.updateStateObject = updateStateObject;
+      }
+
+      throw new GraphInterrupt([
+        {
+          value: interruptPayload,
+          when: 'during',
+          resumable: true,
+        },
+      ]);
+    }
+    return false;
+  }
+}

package/src/interrupts/MemoryInterruptSessionManager.ts

@@ -0,0 +1,63 @@
+import { BaseInterruptSessionManager, QueuedMessage, QUEUE_INTERRUPT_DETECTED_BEFORE_SPEECH } from './BaseInterruptSessionManager';
+
+export class MemoryInterruptSessionManager extends BaseInterruptSessionManager {
+  private sessionProcessing: Map<string, boolean> = new Map();
+  private sessionMessageQueues: Map<string, QueuedMessage[]> = new Map();
+
+  isProcessed(sessionId: string): boolean {
+    return this.sessionProcessing.get(sessionId) || false;
+  }
+
+  lock(sessionId: string): boolean {
+    const isCurrentlyProcessed = this.sessionProcessing.get(sessionId) || false;
+    if (isCurrentlyProcessed) {
+      return false; // Could not acquire lock
+    }
+    this.sessionProcessing.set(sessionId, true);
+    return true; // Successfully acquired lock
+  }
+
+  release(sessionId: string): void {
+    this.sessionProcessing.delete(sessionId);
+  }
+
+  enqueueMessage(sessionId: string, message: QueuedMessage): void {
+    if (!this.sessionMessageQueues.has(sessionId)) {
+      this.sessionMessageQueues.set(sessionId, []);
+    }
+    this.sessionMessageQueues.get(sessionId)!.push(message);
+  }
+
+  dequeueAll(sessionId: string): QueuedMessage[] {
+    const messages = this.sessionMessageQueues.get(sessionId) || [];
+    const result = [...messages];
+    this.sessionMessageQueues.set(sessionId, []);
+    return result;
+  }
+
+  dequeue(sessionId: string): QueuedMessage | null {
+    const messages = this.sessionMessageQueues.get(sessionId) || [];
+    if (messages.length === 0) {
+      return null;
+    }
+    const firstMessage = messages.shift()!;
+    this.sessionMessageQueues.set(sessionId, messages);
+
+    // If the dequeued message has the special trigger name, recursively dequeue the next one
+    if (firstMessage.triggerName === QUEUE_INTERRUPT_DETECTED_BEFORE_SPEECH) {
+      return this.dequeue(sessionId);
+    }
+
+    return firstMessage;
+  }
+
+  // Implementation of abstract methods from BaseInterruptSessionManager
+  protected hasQueuedMessages(sessionId: string): boolean {
+    const queue = this.sessionMessageQueues.get(sessionId) || [];
+    return queue.length > 0;
+  }
+
+  protected getQueuedMessages(sessionId: string): QueuedMessage[] {
+    return this.sessionMessageQueues.get(sessionId) || [];
+  }
+}

package/src/interrupts/MindedInterruptSessionManager.ts

@@ -0,0 +1,163 @@
+import { BaseInterruptSessionManager, QueuedMessage, QUEUE_INTERRUPT_DETECTED_BEFORE_SPEECH } from './BaseInterruptSessionManager';
+import * as mindedConnection from '../platform/mindedConnection';
+import { logger } from '../utils/logger';
+import {
+  mindedConnectionSocketMessageType,
+  InterruptSessionIsProcessedRequest,
+  InterruptSessionIsProcessedResponse,
+  InterruptSessionLockRequest,
+  InterruptSessionLockResponse,
+  InterruptSessionReleaseRequest,
+  InterruptSessionReleaseResponse,
+  InterruptSessionEnqueueRequest,
+  InterruptSessionEnqueueResponse,
+  InterruptSessionDequeueAllRequest,
+  InterruptSessionDequeueAllResponse,
+  InterruptSessionDequeueRequest,
+  InterruptSessionDequeueResponse,
+  InterruptSessionHasMessagesRequest,
+  InterruptSessionHasMessagesResponse,
+  InterruptSessionGetMessagesRequest,
+  InterruptSessionGetMessagesResponse,
+} from '../platform/mindedConnectionTypes';
+
+export class MindedInterruptSessionManager extends BaseInterruptSessionManager {
+  constructor() {
+    super();
+  }
+
+  async isProcessed(sessionId: string): Promise<boolean> {
+    try {
+      const response = await mindedConnection.awaitEmit<InterruptSessionIsProcessedRequest, InterruptSessionIsProcessedResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_IS_PROCESSED,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_IS_PROCESSED,
+          sessionId,
+        },
+      );
+      return response.isProcessed ?? false;
+    } catch (err) {
+      logger.error({ message: 'Error checking if session is processed', err });
+      return false;
+    }
+  }
+
+  async lock(sessionId: string): Promise<boolean> {
+    try {
+      const response = await mindedConnection.awaitEmit<InterruptSessionLockRequest, InterruptSessionLockResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_LOCK,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_LOCK,
+          sessionId,
+        },
+      );
+      return response.lockAcquired ?? false;
+    } catch (err) {
+      logger.error({ message: 'Error locking session', err });
+      return false;
+    }
+  }
+
+  async release(sessionId: string): Promise<void> {
+    try {
+      await mindedConnection.awaitEmit<InterruptSessionReleaseRequest, InterruptSessionReleaseResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_RELEASE,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_RELEASE,
+          sessionId,
+        },
+      );
+    } catch (err) {
+      logger.error({ message: 'Error releasing session', err });
+      throw err;
+    }
+  }
+
+  async enqueueMessage(sessionId: string, message: QueuedMessage): Promise<void> {
+    try {
+      await mindedConnection.awaitEmit<InterruptSessionEnqueueRequest, InterruptSessionEnqueueResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_ENQUEUE,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_ENQUEUE,
+          sessionId,
+          message,
+        },
+      );
+    } catch (err) {
+      logger.error({ message: 'Error enqueuing message', err });
+      throw err;
+    }
+  }
+
+  async dequeueAll(sessionId: string): Promise<QueuedMessage[]> {
+    try {
+      const response = await mindedConnection.awaitEmit<InterruptSessionDequeueAllRequest, InterruptSessionDequeueAllResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_DEQUEUE_ALL,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_DEQUEUE_ALL,
+          sessionId,
+        },
+      );
+      return response.messages ?? [];
+    } catch (err) {
+      logger.error({ message: 'Error dequeuing all messages', err });
+      return [];
+    }
+  }
+
+  async dequeue(sessionId: string): Promise<QueuedMessage | null> {
+    try {
+      const response = await mindedConnection.awaitEmit<InterruptSessionDequeueRequest, InterruptSessionDequeueResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_DEQUEUE,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_DEQUEUE,
+          sessionId,
+        },
+      );
+      const message = response.message ?? null;
+
+      // If the dequeued message has the special trigger name, recursively dequeue the next one
+      if (message && message.triggerName === QUEUE_INTERRUPT_DETECTED_BEFORE_SPEECH) {
+        return this.dequeue(sessionId);
+      }
+
+      return message;
+    } catch (err) {
+      logger.error({ message: 'Error dequeuing message', err });
+      return null;
+    }
+  }
+
+  // Implementation of abstract methods from BaseInterruptSessionManager
+  protected async hasQueuedMessages(sessionId: string): Promise<boolean> {
+    try {
+      const response = await mindedConnection.awaitEmit<InterruptSessionHasMessagesRequest, InterruptSessionHasMessagesResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_HAS_MESSAGES,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_HAS_MESSAGES,
+          sessionId,
+        },
+      );
+      return response.hasMessages ?? false;
+    } catch (err) {
+      logger.error({ message: 'Error checking if session has messages', err });
+      return false;
+    }
+  }
+
+  protected async getQueuedMessages(sessionId: string): Promise<QueuedMessage[]> {
+    try {
+      const response = await mindedConnection.awaitEmit<InterruptSessionGetMessagesRequest, InterruptSessionGetMessagesResponse>(
+        mindedConnectionSocketMessageType.INTERRUPT_SESSION_GET_MESSAGES,
+        {
+          type: mindedConnectionSocketMessageType.INTERRUPT_SESSION_GET_MESSAGES,
+          sessionId,
+        },
+      );
+      return response.messages ?? [];
+    } catch (err) {
+      logger.error({ message: 'Error getting queued messages', err });
+      return [];
+    }
+  }
+}

package/src/interrupts/interruptSessionManagerFactory.ts

@@ -0,0 +1,20 @@
+import { InterruptSessionManager } from './BaseInterruptSessionManager';
+import { MemoryInterruptSessionManager } from './MemoryInterruptSessionManager';
+import { MindedInterruptSessionManager } from './MindedInterruptSessionManager';
+import * as mindedConnection from '../platform/mindedConnection';
+import { getConfig } from '../platform/config';
+import { logger } from '../utils/logger';
+
+export function createInterruptSessionManager(): InterruptSessionManager {
+  const { runLocally } = getConfig();
+  if (runLocally) {
+    logger.info({ msg: '[Agent] Using memory interrupt session manager' });
+    return new MemoryInterruptSessionManager();
+  } else {
+    if (!mindedConnection.isConnected()) {
+      throw new Error('MindedConnection is required for platform interrupt session manager');
+    }
+    logger.info({ msg: '[Agent] Using Minded interrupt session manager' });
+    return new MindedInterruptSessionManager();
+  }
+}

package/src/llm/createLlmInstance.ts

@@ -0,0 +1,33 @@
+import { LLMConfig, LLMProviders, LLMProvider } from '../types/LLM.types';
+import { createParallelWrapper, BaseParallelChatFields } from '../platform/models/parallelWrapper';
+
+export const createLlmInstance = (llmConfig: LLMConfig) => {
+  const { name, properties } = llmConfig;
+  const LLMClass = LLMProviders[name as LLMProvider];
+  if (!LLMClass) {
+    throw new Error(`Unsupported LLM provider: ${name}`);
+  }
+
+  // Create the base LLM instance
+  const llmInstance = new LLMClass(properties);
+
+  // Check if parallel configuration is present
+  const hasParallelConfig = properties.numParallelRequests && properties.numParallelRequests > 1;
+
+  // For MindedChatOpenAI, parallel functionality is handled on the backend
+  if (name === 'MindedChatOpenAI') {
+    return llmInstance;
+  }
+
+  // For other LLM providers, apply client-side parallel wrapper if configured
+  if (hasParallelConfig) {
+    const parallelOptions: BaseParallelChatFields = {
+      numParallelRequests: properties.numParallelRequests,
+      logTimings: properties.logTimings,
+    };
+
+    return createParallelWrapper(llmInstance, parallelOptions);
+  }
+
+  return llmInstance;
+};