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

package/src/toolsLibrary/classifier.ts

@@ -0,0 +1,326 @@
+import { z } from 'zod';
+import { Tool } from '../types/Tools.types';
+import { logger } from '../utils/logger';
+import { SystemMessage } from '@langchain/core/messages';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+
+// Type guard for checking if LLM supports structured output
+interface StructuredOutputLLM extends BaseLanguageModel {
+  withStructuredOutput<T extends z.ZodType>(schema: T): BaseLanguageModel;
+}
+
+function supportsStructuredOutput(llm: BaseLanguageModel): llm is StructuredOutputLLM {
+  return 'withStructuredOutput' in llm && typeof (llm as any).withStructuredOutput === 'function';
+}
+
+// Type definitions for classifier configuration
+export interface ClassDefinition {
+  name: string;
+  description: string;
+}
+
+export interface ClassifierConfig {
+  classes: ClassDefinition[];
+  systemPrompt?: string;
+  defaultClass: string;
+  defaultReason: string;
+}
+
+export interface ClassificationResult {
+  class: string;
+  reason: string;
+  confidence: number;
+  [key: string]: any; // Allow additional fields
+}
+
+/**
+ * Create a dynamic Zod schema for classification result based on valid classes
+ */
+function createClassificationSchema(config: ClassifierConfig): z.ZodSchema {
+  const validClassNames = config.classes.map((c) => c.name);
+
+  // Validate that we have at least one class (z.enum requires at least one value)
+  if (validClassNames.length === 0) {
+    throw new Error('Cannot create classification schema with empty classes array');
+  }
+
+  // Create a union type for valid class names
+  const classEnum = z.enum(validClassNames as [string, ...string[]]);
+
+  // Build the schema - always include all fields
+  const schemaShape: Record<string, z.ZodTypeAny> = {
+    class: classEnum.describe('The selected classification category'),
+    reason: z.string().describe('Explanation for the classification'),
+    confidence: z.number().min(0).max(1).describe('Confidence score between 0 and 1'),
+  };
+
+  return z.object(schemaShape);
+}
+
+/**
+ * Generic classifier utility that can be used standalone
+ * @param content The content to classify
+ * @param config The classifier configuration
+ * @param llm The language model to use for classification
+ * @returns The classification result
+ */
+export async function classify(content: string, config: ClassifierConfig, llm: BaseLanguageModel): Promise<ClassificationResult> {
+  const MAX_RETRIES = 3;
+  let lastError: Error | null = null;
+
+  // Validate that classes array is not empty
+  if (!config.classes || config.classes.length === 0) {
+    throw new Error('At least one class must be provided for classification');
+  }
+
+  // Check if LLM supports structured output upfront
+  if (!supportsStructuredOutput(llm)) {
+    throw new Error('LLM does not support structured output, which is required for classification');
+  }
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      // Build the classification prompt
+      const classesDescription = config.classes.map((c) => `${c.name}: ${c.description}`).join('\n');
+
+      const basePrompt =
+        config.systemPrompt || 'You are a classifier. Your task is to classify the given content into one of the following categories:';
+
+      let prompt = `${basePrompt}\n\n${classesDescription}\n\n`;
+
+      // Add retry feedback if this is not the first attempt
+      if (attempt > 1) {
+        const validClassNames = config.classes.map((c) => c.name);
+        prompt += `\n⚠️ IMPORTANT: Your previous classification attempt failed. `;
+        prompt += `You MUST select ONLY from these valid classes:\n${validClassNames.join(', ')}\n\n`;
+      }
+
+      // Create dynamic schema based on valid classes
+      const classificationSchema = createClassificationSchema(config);
+
+      // Add content to classify to the prompt
+      prompt += `\n\nContent to classify:\n${content}`;
+
+      // Use structured output for guaranteed compliance
+      const structuredLLM = llm.withStructuredOutput(classificationSchema);
+      const messages = [new SystemMessage(prompt)];
+      const result = (await structuredLLM.invoke(messages)) as ClassificationResult;
+
+      // The result is already validated by withStructuredOutput
+      logger.debug({
+        message: 'Classification successful with structured output',
+        attempt,
+        class: result.class,
+      });
+
+      return result;
+    } catch (err) {
+      lastError = err as Error;
+      logger.warn({
+        message: `Classification attempt ${attempt} failed`,
+        attempt,
+        maxRetries: MAX_RETRIES,
+        error: lastError.message,
+      });
+    }
+  }
+
+  // All retries exhausted - fallback to default
+  logger.warn({
+    message: 'Classification failed after max retries, using default class',
+    maxRetries: MAX_RETRIES,
+    lastError: lastError?.message,
+    defaultClass: config.defaultClass,
+    defaultReason: config.defaultReason,
+  });
+
+  // Return default classification
+  return {
+    class: config.defaultClass,
+    reason: config.defaultReason,
+    confidence: 0,
+  };
+}
+
+/**
+ * Create a classifier from a simple class list
+ * @param classes Array of class names or [name, description] tuples
+ * @param options Configuration options (includeReason, defaultClass, defaultReason are required)
+ * @returns A configured classify function
+ */
+export function createClassifier(classes: string[] | [string, string][], options: Omit<ClassifierConfig, 'classes'>) {
+  const classDefinitions: ClassDefinition[] = classes.map((c) => {
+    if (typeof c === 'string') {
+      return { name: c, description: '' };
+    }
+    return { name: c[0], description: c[1] };
+  });
+
+  const config: ClassifierConfig = {
+    ...options,
+    classes: classDefinitions,
+  };
+
+  return (content: string, llm: BaseLanguageModel) => classify(content, config, llm);
+}
+
+// Schema for the classifier tool
+export const schema = z.object({
+  content: z.string().describe('The content to classify'),
+  classes: z
+    .array(
+      z.union([
+        z.string(),
+        z.tuple([z.string(), z.string()]),
+        z.object({
+          name: z.string(),
+          description: z.string(),
+        }),
+      ]),
+    )
+    .optional()
+    .describe('Classes to classify into. Can be strings, [name, description] tuples, or objects with name and description'),
+  systemPrompt: z.string().optional().describe('Custom system prompt for classification'),
+  defaultClass: z.string().describe('Default class to use if classification fails'),
+  defaultReason: z.string().describe('Default reason to use if classification fails'),
+});
+
+const classifierTool: Tool<typeof schema, any> = {
+  name: 'minded-classifier',
+  description:
+    'Classify content into predefined categories using AI. Supports custom classes and system prompts. Uses structured output for guaranteed schema compliance. Requires default fallback values.',
+  input: schema,
+  isGlobal: false,
+  execute: async ({ input, state, agent }) => {
+    const { content, classes, systemPrompt, defaultClass, defaultReason } = input;
+
+    logger.info({
+      message: 'Classifying content',
+      sessionId: state.sessionId,
+      contentLength: content.length,
+      classCount: classes?.length,
+    });
+
+    // Convert input classes to ClassDefinition format
+    let classDefinitions: ClassDefinition[] = [];
+    if (classes) {
+      classDefinitions = classes.map((c) => {
+        if (typeof c === 'string') {
+          return { name: c, description: '' };
+        } else if (Array.isArray(c)) {
+          return { name: c[0], description: c[1] };
+        } else {
+          return c as ClassDefinition;
+        }
+      });
+    }
+
+    // If no classes provided, try to get from state memory
+    if (classDefinitions.length === 0 && state.memory?.classifierConfig?.classes) {
+      classDefinitions = state.memory.classifierConfig.classes;
+    }
+
+    if (classDefinitions.length === 0) {
+      throw new Error('No classes provided for classification');
+    }
+
+    const config: ClassifierConfig = {
+      classes: classDefinitions,
+      systemPrompt,
+      defaultClass,
+      defaultReason,
+    };
+
+    try {
+      const result = await classify(content, config, agent.llm);
+
+      logger.info({
+        message: 'Classification completed',
+        sessionId: state.sessionId,
+        class: result.class,
+        confidence: result.confidence,
+      });
+
+      state.memory.lastClassification = {
+        content: content.substring(0, 100) + (content.length > 100 ? '...' : ''),
+        result,
+        timestamp: new Date().toISOString(),
+      };
+
+      return {
+        result,
+      };
+    } catch (err) {
+      logger.error({
+        message: 'Classification failed',
+        sessionId: state.sessionId,
+        err,
+      });
+
+      throw err;
+    }
+  },
+};
+
+export default classifierTool;
+
+// Export utility for multi-label classification
+export async function multiClassify(
+  content: string,
+  config: ClassifierConfig & { maxClasses?: number },
+  llm: BaseLanguageModel,
+): Promise<ClassificationResult[]> {
+  const maxClasses = config.maxClasses || 3;
+
+  // Validate that classes array is not empty
+  if (!config.classes || config.classes.length === 0) {
+    throw new Error('At least one class must be provided for multi-classification');
+  }
+
+  // Check if LLM supports structured output
+  if (!supportsStructuredOutput(llm)) {
+    throw new Error('LLM does not support structured output, which is required for multi-classification');
+  }
+
+  try {
+    const classesDescription = config.classes.map((c) => `${c.name}: ${c.description}`).join('\n');
+    const validClassNames = config.classes.map((c) => c.name);
+
+    const basePrompt = config.systemPrompt || 'You are a multi-label classifier. Select all applicable categories for the given content:';
+
+    const prompt = `${basePrompt}\n\n${classesDescription}\n\n
+Select up to ${maxClasses} classifications, ordered by relevance.
+
+Content to classify:
+${content}`;
+
+    // Create schema for array of classifications
+    const classEnum = z.enum(validClassNames as [string, ...string[]]);
+    const multiClassSchema = z
+      .array(
+        z.object({
+          class: classEnum.describe('The selected classification category'),
+          reason: z.string().describe('Explanation for the classification'),
+          confidence: z.number().min(0).max(1).describe('Confidence score between 0 and 1'),
+        }),
+      )
+      .min(1)
+      .max(maxClasses);
+
+    const structuredLLM = llm.withStructuredOutput(multiClassSchema);
+    const messages = [new SystemMessage(prompt)];
+    const result = (await structuredLLM.invoke(messages)) as ClassificationResult[];
+
+    return result;
+  } catch (err) {
+    logger.error({ message: 'Multi-classification failed', err });
+
+    return [
+      {
+        class: config.defaultClass,
+        reason: config.defaultReason,
+        confidence: 0,
+      },
+    ];
+  }
+}