@minded-ai/mindedjs 1.0.115 → 1.0.117

package/docs/tooling/classifier.md

@@ -0,0 +1,217 @@
+# Classifier Tool
+
+The classifier tool is a powerful utility in the MindedJS SDK that allows you to categorize text content using AI. It's available both as a tool that can be used in flows and as standalone utility functions that can be imported and used anywhere in your code.
+
+## Overview
+
+The classifier tool provides:
+
+- **Single-label classification**: Categorize content into one class
+- **Multi-label classification**: Categorize content into multiple classes
+- **Conversation classification**: Specialized classification for chat conversations
+- **Configurable output formats**: JSON or plain text
+- **Error handling with fallback defaults**
+- **Confidence scoring**
+
+## Using as a Tool
+
+### In Flows
+
+You can use the classifier tool in your flows by referencing `minded-classifier`:
+
+```yaml
+- id: classifyUserIntent
+  type: tool
+  toolName: minded-classifier
+  prompt: |
+    Classify the user's message into one of these categories:
+    - Technical Issue: Problems with the system
+    - Billing: Payment or pricing questions
+    - Feature Request: Asking for new features
+
+    Content: "{{userMessage}}"
+```
+
+### Tool Parameters
+
+| Parameter     | Type             | Description                                            | Required |
+| ------------- | ---------------- | ------------------------------------------------------ | -------- |
+| content       | string           | The text content to classify                           | Yes      |
+| classes       | array            | Classes to classify into (strings, tuples, or objects) | No\*     |
+| systemPrompt  | string           | Custom system prompt for classification                | No       |
+| includeReason | boolean          | Whether to include reasoning (default: true)           | No       |
+| outputFormat  | 'json' \| 'text' | Output format (default: 'json')                        | No       |
+| defaultClass  | string           | Fallback class if classification fails                 | No       |
+| defaultReason | string           | Fallback reason if classification fails                | No       |
+
+\*Classes can be provided in the tool parameters or stored in agent memory
+
+## Using as a Utility
+
+### Import the Utilities
+
+```typescript
+import { toolsLibrary } from '@minded-ai/mindedjs';
+
+const { classify, createClassifier, createConversationClassifier, multiClassify } = toolsLibrary.tools['minded-classifier'];
+```
+
+### Direct Classification
+
+```typescript
+const result = await classify(
+  "I can't access my account",
+  {
+    classes: [
+      { name: 'Technical', description: 'Technical issues' },
+      { name: 'Account', description: 'Account access problems' },
+    ],
+    includeReason: true,
+  },
+  agent.llm,
+);
+
+console.log(result);
+// { class: 'Account', reason: 'User cannot access their account', confidence: 0.95 }
+```
+
+### Create Reusable Classifiers
+
+```typescript
+// Simple classifier with string classes
+const sentimentClassifier = createClassifier(['positive', 'negative', 'neutral']);
+
+// Classifier with descriptions
+const intentClassifier = createClassifier([
+  ['greeting', 'User is greeting or saying hello'],
+  ['question', 'User is asking a question'],
+  ['complaint', 'User is complaining or expressing dissatisfaction'],
+  ['goodbye', 'User is saying goodbye or ending conversation'],
+]);
+
+// Use the classifier
+const sentiment = await sentimentClassifier('This is amazing!', agent.llm);
+const intent = await intentClassifier('Hello there!', agent.llm);
+```
+
+### Conversation Classification
+
+For classifying entire conversations:
+
+```typescript
+const conversationClassifier = createConversationClassifier([
+  { name: 'Resolved', description: 'Issue was resolved successfully' },
+  { name: 'Escalated', description: 'Needs escalation to human agent' },
+  { name: 'Pending', description: 'Awaiting more information' },
+]);
+
+const result = await conversationClassifier(messages, agent.llm);
+```
+
+### Multi-Label Classification
+
+When content can belong to multiple categories:
+
+```typescript
+const topics = await multiClassify(
+  'The app crashes on login and the UI looks outdated',
+  {
+    classes: [
+      { name: 'Bug', description: 'Software bugs or crashes' },
+      { name: 'UI/UX', description: 'User interface issues' },
+      { name: 'Authentication', description: 'Login or auth problems' },
+    ],
+    maxClasses: 3,
+  },
+  agent.llm,
+);
+
+console.log(topics);
+// [
+//   { class: 'Bug', reason: 'App crashes', confidence: 0.9 },
+//   { class: 'Authentication', reason: 'Login issues', confidence: 0.85 },
+//   { class: 'UI/UX', reason: 'Outdated UI', confidence: 0.7 }
+// ]
+```
+
+## Configuration Options
+
+### ClassifierConfig Interface
+
+```typescript
+interface ClassifierConfig {
+  classes: ClassDefinition[];
+  systemPrompt?: string;
+  outputFormat?: 'json' | 'text';
+  includeReason?: boolean;
+  defaultClass?: string;
+  defaultReason?: string;
+}
+```
+
+### Class Definition Formats
+
+Classes can be defined in multiple ways:
+
+```typescript
+// Simple strings
+['positive', 'negative', 'neutral'][
+  // Tuples with descriptions
+  (['technical', 'Technical problems'], ['billing', 'Payment issues'])
+][
+  // Objects
+  ({ name: 'urgent', description: 'Requires immediate attention' }, { name: 'normal', description: 'Standard priority' })
+];
+```
+
+## Example: Customer Support Bot
+
+```typescript
+import { Agent, toolsLibrary } from '@minded-ai/mindedjs';
+import { z } from 'zod';
+
+const classifierTool = toolsLibrary.tools['minded-classifier'].default;
+
+const agent = new Agent({
+  memorySchema: z.object({
+    ticketPriority: z.string().optional(),
+    ticketCategory: z.string().optional(),
+  }),
+  config: {
+    flows: ['./flows'],
+    llm: { provider: 'openai', model: 'gpt-4' },
+  },
+  tools: [classifierTool],
+});
+
+// Create specialized classifiers
+const priorityClassifier = createClassifier([
+  ['urgent', 'Requires immediate attention'],
+  ['high', 'Important but not critical'],
+  ['normal', 'Standard priority'],
+  ['low', 'Can be handled later'],
+]);
+
+const categoryClassifier = createClassifier([
+  ['technical', 'Technical issues or bugs'],
+  ['billing', 'Payment and subscription issues'],
+  ['feature', 'Feature requests'],
+  ['other', 'General inquiries'],
+]);
+
+// Use in message handler
+agent.on('message', async (message) => {
+  const [priority, category] = await Promise.all([
+    priorityClassifier(message.content, agent.llm),
+    categoryClassifier(message.content, agent.llm),
+  ]);
+
+  // Update agent memory
+  await agent.updateMemory({
+    ticketPriority: priority.class,
+    ticketCategory: category.class,
+  });
+});
+```
+
+`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "1.0.115",
+  "version": "1.0.117",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -66,4 +66,4 @@
     "uuid": "^11.1.0",
     "ws": "^8.15.1"
   }
-}
+}

package/src/agent.ts

@@ -180,6 +180,11 @@ export class Agent {
           await this.restoreCheckpoint(restoreCheckpointMessage.sessionId, restoreCheckpointMessage.checkpointId);
           return { success: true };
         });
+
+        mindedConnection.on(mindedConnectionSocketMessageType.SDK_VERSION_MISMATCH, (data) => {
+          logger.warn(`\x1b[33mMindedJS SDK outdated, we recommend upgrading ${data.currentVersion}->${data.requiredVersion}\x1b[0m`);
+          logger.warn(`\x1b[33mnpm install @minded-ai/mindedjs / yarn upgrade @minded-ai/mindedjs\x1b[0m`);
+        });
       }
 
       const [, flows, playbooks] = await Promise.all([this.loadSecrets(), this.loadFlows(config.flows), loadPlaybooks(config.playbooks)]);
@@ -466,6 +471,11 @@ export class Agent {
       let messages: Array<BaseMessage> = [];
       let memoryUpdate = {};
       let sessionType: SessionType = SessionType.TEXT;
+
+      // Get the current state early to access memory for TRIGGER_EVENT
+      const langraphConfig = this.getLangraphConfig(sessionId);
+      const state = await this.compiledGraph.getState(langraphConfig);
+
       if (triggerName === KnownTriggerNames.DASHBOARD_MESSAGE || triggerName === KnownTriggerNames.VOICE_MESSAGE) {
         // Parse attachments if present
         const attachmentsString = parseAttachments(triggerBody);
@@ -479,6 +489,7 @@ export class Agent {
           triggerName,
           triggerBody,
           sessionId,
+          state: state.values,
         });
         if (results.length === 0) {
           if (appName) {
@@ -503,8 +514,6 @@ export class Agent {
       }
 
       logger.info({ msg: '[Trigger] Received', triggerName, triggerBody, sessionId });
-      const langraphConfig = this.getLangraphConfig(sessionId || uuidv4());
-      const state = await this.compiledGraph.getState(langraphConfig);
       const suffixes = Object.values(internalNodesSuffix);
       let nodeToBeInvoked =
         state.next.length > 0
@@ -570,185 +579,58 @@ export class Agent {
   }
 
   /**
-   * Register an event handler for specific agent events.
+   * Register an event handler for agent events. Multiple handlers can be registered for the same event.
    *
-   * This method allows you to listen for and respond to various events that occur during
-   * agent execution, such as trigger events, memory updates, or custom application events.
-   * Multiple handlers can be registered for the same event type and will be executed in the order they are registered.
-   *
-   * ## Available Event Types
+   * ## Available Events
    *
    * ### INIT
-   * Emitted when the agent's graph state is initialized. This happens when a new session begins
-   * or when the agent starts processing a new conversation context.
-   *
-   * **Input Structure:**
-   * ```typescript
-   * {
-   *   state: {                           // Full initial agent state
-   *     messages: BaseMessage[];         // Empty array - no messages yet
-   *     memory: Memory;                  // Initial memory state (from your schema defaults)
-   *     triggerInvocations: Array<...>;  // Empty array - no triggers invoked yet
-   *     triggerMetadata: null;           // No trigger metadata initially
-   *     history: HistoryStep[];          // Empty array - no flow history yet
-   *     sessionId: string;               // Session identifier (generated or provided)
-   *     sessionType: SessionType;        // Type of session (TEXT, VOICE, etc.)
-   *   }
-   * }
-   * ```
-   *
-   * **Expected Output:** `void` - Handlers are used for side effects like logging, setup, or initialization tasks
-   *
-   * **Common Use Cases:**
-   * - Session logging and analytics tracking
-   * - Resource initialization for new sessions
-   * - State validation and verification
-   * - External service setup and configuration
-   * - Session routing and management
-   * - Debugging and troubleshooting
+   * Fired when a new session starts.
+   * - **Input:** `{ state: AgentState }` - Initial agent state with empty messages/history
+   * - **Output:** `void`
+   * - **Use for:** Session logging, resource initialization, analytics
    *
    * ### AI_MESSAGE
-   * Emitted when an AI generates a message that should be sent to the user.
-   *
-   * **Input Structure:**
-   * ```typescript
-   * {
-   *   message: string;     // The AI-generated message content
-   *   state: {             // Full agent state
-   *     messages: BaseMessage[];           // Conversation messages
-   *     memory: Memory;                    // Current memory state (your defined memory schema)
-   *     triggerInvocations: Array<...>;    // Trigger invocation history
-   *     triggerMetadata: {...} | null;     // Current trigger metadata
-   *     history: HistoryStep[];            // Flow execution history with detailed step information
-   *     sessionId: string;                 // Session identifier
-   *   }
-   * }
-   * ```
-   *
-   * **Expected Output:** `void` - Handlers are used for side effects like sending messages to UI
-   *
-   * **Common Use Cases:**
-   * - Real-time chat UI updates with session context
-   * - Logging AI responses for analytics or debugging
-   * - Message formatting and transformation
-   * - Notifications and alerts based on AI responses
-   * - Session-based message routing
+   * Fired when AI generates a message for the user.
+   * - **Input:** `{ message: string, state: AgentState }` - AI message and current state
+   * - **Output:** `void`
+   * - **Use for:** Sending to UI, logging responses, notifications
    *
    * ### TRIGGER_EVENT
-   * Emitted when a trigger node is executed. Allows you to qualify, transform, and provide
-   * initial state for trigger inputs before they're processed by the agent.
-   *
-   * **Input Structure:**
-   * ```typescript
-   * {
-   *   triggerName: string;  // Name of the trigger being executed
-   *   triggerBody: any;     // The trigger input data (type varies by trigger)
-   * }
-   * ```
-   *
-   * **Expected Output:** One of three possible return types:
-   *
-   * 1. **Provide Initial State:**
-   * ```typescript
-   * {
-   *   messages?: BaseMessage[];  // Initial messages for the conversation
-   *   memory?: Memory;          // Initial memory state
-   *   sessionId?: string;       // Session ID for persistence (resumes existing sessions)
-   * }
-   * ```
-   *
-   * 2. **Disqualify the Trigger:**
-   * ```typescript
-   * false  // Rejects/disqualifies the trigger from processing
-   * ```
-   *
-   * 3. **Qualify without Initial State:**
-   * ```typescript
-   * void  // Qualifies the trigger but provides no initial state
-   * ```
-   *
-   * **Common Use Cases:**
-   * - Input validation and trigger qualification
-   * - Data transformation into standardized formats
-   * - Context setting with initial memory state
-   * - Access control and business rule enforcement
-   * - Routing logic for different trigger types
-   *
-   * @template E - The event type, constrained to known agent event types
-   * @param event - The name of the event to listen for
-   * @param handler - The function to call when the event is emitted
+   * Fired when a trigger executes. Allows qualifying/transforming trigger inputs.
+   * - **Input:** `{ triggerName: string, triggerBody: any }`
+   * - **Output Options:**
+   *   - `{ messages?, memory?, sessionId? }` - Provide initial state
+   *   - `false` - Disqualify the trigger
+   *   - `void` - Qualify without initial state
+   * - **Use for:** Input validation, data transformation, access control
+   *
+   * @template E - The event type
+   * @param event - Event name to listen for
+   * @param handler - Function to call when event fires
    *
    * @example
    * ```typescript
-   * // INIT Event Handler
+   * // Session initialization
    * agent.on('INIT', async ({ state }) => {
-   *   logger.info({ msg: 'Agent initialized for session:', sessionId: state.sessionId });
-   *   logger.info({ msg: 'Session type:', sessionType: state.sessionType });
-   *   logger.info({ msg: 'Initial memory:', memory: state.memory });
-   *
-   *   // Setup session-specific resources
-   *   await initializeSessionResources(state.sessionId);
-   *
-   *   // Log session start for analytics
-   *   await logSessionStart({
-   *     sessionId: state.sessionId,
-   *     sessionType: state.sessionType,
-   *     timestamp: new Date(),
-   *   });
+   *   logger.info({ msg: 'Session started', sessionId: state.sessionId });
+   *   await initializeResources(state.sessionId);
    * });
    *
-   * // AI_MESSAGE Event Handler
+   * // Handle AI messages
    * agent.on('AI_MESSAGE', async ({ message, state }) => {
-   *   logger.info({ msg: 'AI said:', output: message });
-   *   logger.info({ msg: 'Current memory:', output: state.memory });
-   *   logger.info({ msg: 'Session ID:', output: state.sessionId });
-   *
-   *   // Send to user interface with session context
-   *   await sendMessageToUser(message, state.sessionId);
-   *
-   *   // Send via WebSocket
-   *   await websocket.send(JSON.stringify({
-   *     type: 'ai_message',
-   *     content: message,
-   *     sessionId: state.sessionId,
-   *     memory: state.memory
-   *   }));
+   *   await sendToUI(message, state.sessionId);
    * });
    *
-   * // TRIGGER_EVENT Event Handler - Input Validation
+   * // Validate and transform triggers
    * agent.on('TRIGGER_EVENT', async ({ triggerName, triggerBody }) => {
-   *   // Validate trigger input
-   *   if (!isValidInput(triggerBody)) {
-   *     return false; // Disqualify the trigger
-   *   }
-   *
-   *   // Business hours check
-   *   if (triggerName === 'supportRequest' && !isBusinessHours()) {
-   *     return false;
-   *   }
+   *   if (!isValid(triggerBody)) return false;
    *
    *   return {
-   *     memory: { validatedInput: triggerBody },
-   *     messages: [new HumanMessage('Support request received')],
-   *     sessionId: triggerBody.userId // Resume existing session
+   *     memory: { validated: true },
+   *     messages: [new HumanMessage('Request received')],
+   *     sessionId: triggerBody.userId
    *   };
    * });
-   *
-   * // TRIGGER_EVENT Event Handler - Data Transformation
-   * agent.on('TRIGGER_EVENT', async ({ triggerName, triggerBody }) => {
-   *   if (triggerName === 'emailTrigger') {
-   *     // Transform email data into structured format
-   *     const parsedEmail = parseEmailContent(triggerBody);
-   *
-   *     return {
-   *       memory: {
-   *         emailSubject: parsedEmail.subject,
-   *         senderEmail: parsedEmail.from
-   *       },
-   *       messages: [new HumanMessage(parsedEmail.content)],
-   *     };
-   *   }
-   * });
    * ```
    */
   // Public API for registering event listeners

package/src/events/AgentEvents.ts

@@ -25,6 +25,7 @@ export type AgentEventRequestPayloads<Memory> = {
     triggerName: string;
     triggerBody: any;
     sessionId?: string;
+    state?: State<Memory>;
   };
   [AgentEvents.VOICE_SESSION_START]: {
     sessionId: string;

package/src/platform/mindedConnection.ts

@@ -1,12 +1,10 @@
 import { io, Socket } from 'socket.io-client';
-import {
-  mindedConnectionSocketMessageType,
-  mindedConnectionSocketMessageTypeMap,
-} from './mindedConnectionTypes';
+import { mindedConnectionSocketMessageType, mindedConnectionSocketMessageTypeMap } from './mindedConnectionTypes';
 import { stringify } from 'flatted';
 import { getConfig } from './config';
 import { logger } from '../utils/logger';
 import { wait } from '../utils/wait';
+import * as packageJson from '../../package.json';
 
 // Module-level singleton state
 let socket: Socket | null = null;
@@ -28,20 +26,13 @@ export const on = <E extends keyof mindedConnectionSocketMessageTypeMap>(
   listeners[event].push(callback);
 };
 
-export const emit = <E extends keyof mindedConnectionSocketMessageTypeMap>(
-  event: E,
-  message: mindedConnectionSocketMessageTypeMap[E]
-) => {
+export const emit = <E extends keyof mindedConnectionSocketMessageTypeMap>(event: E, message: mindedConnectionSocketMessageTypeMap[E]) => {
   if (socket) {
     socket.emit(event, message);
   }
 };
 
-export const awaitEmit = async <T, R>(
-  event: mindedConnectionSocketMessageType,
-  message: T,
-  timeoutMs: number = 5000
-): Promise<R> => {
+export const awaitEmit = async <T, R>(event: mindedConnectionSocketMessageType, message: T, timeoutMs: number = 5000): Promise<R> => {
   if (!socket) {
     throw new Error('Socket is not connected');
   }
@@ -81,6 +72,15 @@ const waitForConnection = async (): Promise<void> => {
   }
 };
 
+const getSdkVersion = (): string => {
+  try {
+    return packageJson.version;
+  } catch {
+    logger.warn('Could not determine SDK version');
+    return 'unknown';
+  }
+};
+
 const connect = async (token: string): Promise<void> => {
   const { isDeployed, baseUrl } = getConfig();
   return new Promise<void>((resolve, reject) => {
@@ -89,6 +89,7 @@ const connect = async (token: string): Promise<void> => {
       query: {
         isDeployedAgent: isDeployed,
         token,
+        sdkVersion: getSdkVersion(),
       },
     });
 

package/src/platform/mindedConnectionTypes.ts

@@ -39,7 +39,7 @@ export enum mindedConnectionSocketMessageType {
   TIMER_TRIGGER = 'timer-trigger',
   RETELL_CALL = 'retell-call',
   RETELL_GET_CALL = 'retell-get-call',
-
+  SDK_VERSION_MISMATCH = 'sdk-version-mismatch',
 }
 
 export type mindedConnectionSocketMessageTypeMap = {
@@ -67,6 +67,7 @@ export type mindedConnectionSocketMessageTypeMap = {
   [mindedConnectionSocketMessageType.RESTORE_CHECKPOINT]: RestoreCheckpointRequest;
   [mindedConnectionSocketMessageType.RETELL_CALL]: RetellCall;
   [mindedConnectionSocketMessageType.RETELL_GET_CALL]: RetellGetCall;
+  [mindedConnectionSocketMessageType.SDK_VERSION_MISMATCH]: SdkVersionMismatchMessage;
   [mindedConnectionSocketMessageType.UPDATE_STATE]: UpdateStateRequest;
 };
 
@@ -234,7 +235,12 @@ export interface RetellGetCallResponse extends BaseSdkConnectionSocketMessageRes
   error?: string;
 }
 
+export interface SdkVersionMismatchMessage extends BasemindedConnectionSocketMessage {
+  type: mindedConnectionSocketMessageType.SDK_VERSION_MISMATCH;
+  currentVersion: string;
+  requiredVersion: string;
+}
 export interface UpdateStateRequest extends BasemindedConnectionSocketMessage {
   sessionId: string;
   state: Partial<typeof stateAnnotation.State>;
-}
+}