@minded-ai/mindedjs 2.0.36 → 2.0.39-beta.1

package/docs/tooling/classifier.md

@@ -1,23 +1,10 @@
-# Classifier Tool
+## 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.
+The `minded-classifier` tool categorizes text using AI. It can be used in flows or directly in code.
 
-## Overview
+### Using in Flows
 
-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`:
+Use the tool in your flows by referencing `minded-classifier`:
 
 ```yaml
 - id: classifyUserIntent
@@ -34,21 +21,46 @@ You can use the classifier tool in your flows by referencing `minded-classifier`
 
 ### 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       |
+| Parameter     | Type             | Description                           | Required |
+| ------------- | ---------------- | ------------------------------------- | -------- |
+| content       | string           | Text content to classify              | Yes      |
+| classes       | array            | Classes (strings, tuples, or objects) | No\*     |
+| systemPrompt  | string           | Custom system prompt                  | No       |
+| includeReason | boolean          | Include reasoning (default: true)     | No       |
+| outputFormat  | 'json' \| 'text' | Output format (default: 'json')       | No       |
+| defaultClass  | string           | Fallback class                        | No       |
+| defaultReason | string           | Fallback reason                       | No       |
+
+\*Classes can be provided in parameters or stored in agent memory.
+
+### Overriding Classifier Parameters in Flows
 
-\*Classes can be provided in the tool parameters or stored in agent memory
+You can override classifier parameters directly in your flow YAML for deterministic classification:
+
+```yaml
+- name: 'Classify Support Ticket'
+  type: 'tool'
+  toolName: 'minded-classifier'
+  parameters:
+    # Dynamic - from state
+    content: '{state.memory.ticketDescription}'
+    # Fixed - predefined classes
+    classes:
+      - name: 'urgent'
+        description: 'Requires immediate attention'
+      - name: 'standard'
+        description: 'Normal priority'
+      - name: 'low'
+        description: 'Can be handled later'
+    # Fixed - configuration
+    includeReason: true
+    defaultClass: 'standard'
+    # Let AI infer: systemPrompt (optional override)
+```
 
 ## Using as a Utility
 
-### Import the Utilities
+### Import the utilities
 
 ```typescript
 import { toolsLibrary } from '@minded-ai/mindedjs';
@@ -56,7 +68,7 @@ import { toolsLibrary } from '@minded-ai/mindedjs';
 const { classify, createClassifier, createConversationClassifier, multiClassify } = toolsLibrary.tools['minded-classifier'];
 ```
 
-### Direct Classification
+### Direct classification
 
 ```typescript
 const result = await classify(
@@ -75,7 +87,7 @@ console.log(result);
 // { class: 'Account', reason: 'User cannot access their account', confidence: 0.95 }
 ```
 
-### Create Reusable Classifiers
+### Create reusable classifiers
 
 ```typescript
 // Simple classifier with string classes
@@ -94,9 +106,7 @@ const sentiment = await sentimentClassifier('This is amazing!', agent.llm);
 const intent = await intentClassifier('Hello there!', agent.llm);
 ```
 
-### Conversation Classification
-
-For classifying entire conversations:
+### Conversation classification
 
 ```typescript
 const conversationClassifier = createConversationClassifier([
@@ -108,9 +118,7 @@ const conversationClassifier = createConversationClassifier([
 const result = await conversationClassifier(messages, agent.llm);
 ```
 
-### Multi-Label Classification
-
-When content can belong to multiple categories:
+### Multi-label classification
 
 ```typescript
 const topics = await multiClassify(
@@ -134,9 +142,9 @@ console.log(topics);
 // ]
 ```
 
-## Configuration Options
+## Configuration
 
-### ClassifierConfig Interface
+### `ClassifierConfig` interface
 
 ```typescript
 interface ClassifierConfig {

package/docs/tooling/document-processing.md

@@ -1,106 +1,82 @@
 # Document Processing
 
-MindedJS provides powerful document processing capabilities that allow you to extract data from various document types including images, PDFs, Word documents, spreadsheets, and more.
+Extract data from images, PDFs, Word documents, spreadsheets, and more using AI-powered document processing.
 
 ## Overview
 
-The document processing system supports three modes of operation:
+**Supported formats:** Images (JPG, PNG, GIF, BMP, WebP, TIFF), Documents (PDF, DOC, DOCX, TXT, RTF, ODT), Spreadsheets (XLS, XLSX, CSV, ODS), Presentations (PPT, PPTX, ODP), Web formats (HTML, HTM, MD, XML)
 
-1. **Structured Extraction with Schema**: Extract data into a predefined structure using AI
-2. **Unstructured Extraction with Prompt**: Extract information based on prompt instructions
-3. **Raw Text Extraction**: Extract plain text without AI processing
-
-Supported document types:
-
-- **Images**: JPG, PNG, GIF, BMP, WebP, TIFF
-- **Documents**: PDF, DOC, DOCX, TXT, RTF, ODT
-- **Spreadsheets**: XLS, XLSX, CSV, ODS
-- **Presentations**: PPT, PPTX, ODP
-- **Web formats**: HTML, HTM, MD, XML
-
-## Library Tool Integration
-
-The document processing functionality is available as a **library tool** called `minded-parse-documents` that can be added to your flows through the Minded platform. As a library tool, it provides several configuration advantages:
+**Three extraction modes:**
 
-### System Prompt Configuration
-
-The `systemPrompt` property can be configured directly in the Minded platform's flow editor when adding the parseDocument tool to your flow. This allows you to:
-
-- Set extraction instructions without code changes
-- Customize prompts for different use cases within the same agent
-- Update extraction behavior through the UI without redeployment
-
-**When system prompt is configured in the platform:**
-
-- The platform-configured prompt takes precedence and guides the AI extraction
-- The prompt is automatically applied to all document processing operations in that flow node
+1. **Structured Extraction**: Extract data into a predefined Zod schema using AI
+2. **Unstructured Extraction**: Extract information based on prompt instructions
+3. **Raw Text Extraction**: Extract plain text without AI processing
 
-**When system prompt is not set:**
+## Using in Flows
 
-- The tool falls back to using any Zod schema provided for structured extraction
-- If no schema is provided, the tool performs basic text extraction with minimal AI guidance
-- Raw text extraction mode bypasses AI processing entirely regardless of prompt configuration
+The `minded-parse-documents` library tool is available in the Minded platform. Add it to your flows and configure parameters through the UI or YAML.
 
-### Parameter Configuration
+### Overriding Parameters in Flows
 
-Other tool parameters that can be pre-configured in the platform include:
+```yaml
+- name: 'Parse Invoice Document'
+  type: 'tool'
+  toolName: 'minded-parse-documents'
+  parameters:
+    documentUrl: '{state.memory.invoiceUrl}'
+    loadFrom: 'url'
+    systemPrompt: 'Extract invoice number, amount, date, and vendor name'
+```
 
-- `loadFrom`: Source type (url, path, buffer, string)
-- `extractRaw`: Whether to extract raw text without AI processing
-- `schema`: Zod schema for structured data extraction
+**Available parameters:**
 
-Parameters not set in the platform can still be provided by the LLM during execution, allowing for flexible hybrid configuration.
+- `documentPath`: File path (use with `loadFrom: 'path'`)
+- `documentUrl`: URL to fetch (use with `loadFrom: 'url'`)
+- `documentContent`: Buffer or string (use with `loadFrom: 'buffer'` or `'string'`)
+- `loadFrom`: Source type - `'url'`, `'path'`, `'buffer'`, or `'string'`
+- `extractRaw`: Set to `true` for raw text without AI
+- `schema`: Zod schema for structured extraction
+- `systemPrompt`: Instructions for AI-powered extraction
 
-## Quick Start
+## Programmatic Usage
 
-### Structured Data Extraction (with Schema)
+### Structured Extraction
 
 ```typescript
 import { extractFromDocument } from '@minded-ai/mindedjs';
 import { z } from 'zod';
 
-// Define the data structure you want to extract
 const schema = z.object({
   name: z.string(),
   email: z.string(),
   phoneNumber: z.string().optional(),
 });
 
-// Extract structured data using the agent's LLM
 const result = await extractFromDocument({
   llm: agent.llm,
-  documentPath: './path/to/id-card.jpg',
+  documentPath: './id-card.jpg',
   schema,
   systemPrompt: 'Extract personal information from this ID document',
 });
 
 console.log(result.data.name); // Typed data matching your schema
-console.log(result.metadata.processingTime); // Processing time in ms
 ```
 
-### Unstructured Extraction (Prompt Only)
+### Unstructured Extraction
 
 ```typescript
-// Extract information without a predefined schema
 const result = await extractFromDocument({
   llm: agent.llm,
   documentPath: './contract.pdf',
-  systemPrompt: `
-    Extract and summarize:
-    1. All parties involved
-    2. Key dates and deadlines
-    3. Payment terms
-    4. Termination clauses
-  `,
+  systemPrompt: 'Extract parties involved, key dates, payment terms, and termination clauses',
 });
 
-console.log(result.data); // String containing the extracted information
+console.log(result.data); // String with extracted information
 ```
 
-### Raw Text Extraction (No AI)
+### Raw Text Extraction
 
 ```typescript
-// Extract raw text without AI processing
 const result = await extractFromDocument({
   documentPath: './document.pdf',
   config: {
@@ -108,10 +84,10 @@ const result = await extractFromDocument({
   },
 });
 
-console.log(result.data); // Raw text content from the document
+console.log(result.data); // Raw text content
 ```
 
-### Using Document URLs
+### Using URLs
 
 ```typescript
 const result = await extractFromDocument({
@@ -129,14 +105,12 @@ const result = await extractFromDocument({
 
 ### Environment Variables
 
-Set these environment variables for optimal functionality:
-
 ```bash
-# Required for advanced document parsing (PDFs, Word docs, etc.)
+# Required for PDFs, Word docs, spreadsheets, presentations
 LLAMA_CLOUD_API_KEY=your_llama_cloud_api_key
 ```
 
-### Document Processor Configuration
+### Document Processor Options
 
 ```typescript
 const result = await extractFromDocument({
@@ -144,10 +118,10 @@ const result = await extractFromDocument({
   documentPath: './image.jpg',
   schema: yourSchema,
   config: {
-    llamaCloudApiKey: 'your-key', // Override env variable
-    useBase64: true, // Return images as base64
-    maxImageWidth: 1600, // Max image width for processing
-    imageQuality: 90, // JPEG quality (0-100)
+    llamaCloudApiKey: 'your-key',
+    useBase64: true,
+    maxImageWidth: 1600,
+    imageQuality: 90,
   },
 });
 ```
@@ -160,75 +134,12 @@ const result = await extractFromDocument({
   documentPath: './document.pdf',
   schema: yourSchema,
   llmConfig: {
-    model: 'gpt-4o', // Override default model
-    temperature: 0.1, // Lower temperature for consistent extraction
+    model: 'gpt-4o',
+    temperature: 0.1,
   },
 });
 ```
 
-## Advanced Usage
-
-### Custom System Prompts
-
-Tailor the AI's extraction behavior with custom prompts:
-
-```typescript
-const result = await extractFromDocument({
-  llm: agent.llm,
-  documentPath: './medical-record.pdf',
-  schema: z.object({
-    patientName: z.string(),
-    diagnosis: z.string(),
-    medications: z.array(z.string()),
-  }),
-  systemPrompt: `
-    You are a medical data extraction specialist.
-    Extract information with high accuracy and attention to medical terminology.
-    If any required field is unclear or missing, mark it as "Not clearly specified".
-  `,
-});
-```
-
-### Handling Multiple Document Sources
-
-```typescript
-const processDocuments = async (documents: string[]) => {
-  const results = await Promise.all(
-    documents.map((path) =>
-      extractFromDocument({
-        llm: agent.llm,
-        documentPath: path,
-        schema: invoiceSchema,
-      }),
-    ),
-  );
-
-  return results.map((r) => r.data);
-};
-```
-
-### Error Handling
-
-```typescript
-try {
-  const result = await extractFromDocument({
-    llm: agent.llm,
-    documentPath: './document.pdf',
-    schema: yourSchema,
-  });
-
-  logger.info({ message: 'Extracted', data: result.data });
-} catch (err) {
-  if (err.message.includes('LLAMA_CLOUD_API_KEY')) {
-    logger.error({ message: 'LlamaCloud API key required for PDF processing', err });
-  } else if (err.message.includes('Document not found')) {
-    logger.error({ message: 'File does not exist', err });
-  } else {
-    logger.error({ message: 'Processing failed', err });
-  }
-}
-```
-
 ## Example Use Cases
 
 ### Invoice Processing
@@ -265,7 +176,6 @@ const idSchema = z.object({
   dateOfBirth: z.string(),
   documentNumber: z.string(),
   expiryDate: z.string().optional(),
-  issuingCountry: z.string().optional(),
 });
 
 const result = await extractFromDocument({
@@ -275,71 +185,15 @@ const result = await extractFromDocument({
 });
 ```
 
-### Contract Analysis
-
-```typescript
-const contractSchema = z.object({
-  parties: z.array(z.string()),
-  effectiveDate: z.string(),
-  expiryDate: z.string().optional(),
-  keyTerms: z.array(z.string()),
-  terminationClauses: z.array(z.string()),
-  governingLaw: z.string().optional(),
-});
-
-const result = await extractFromDocument({
-  llm: agent.llm,
-  documentPath: './contract.docx',
-  schema: contractSchema,
-  systemPrompt: 'Focus on legal terms, dates, and parties involved',
-});
-```
-
-## Tool Implementation
-
-### Using the Library Tool
-
-The easiest way to add document processing to your flows is using the **minded-parse-documents library tool** available in the Minded platform. Simply add it to your flow through the platform UI and configure the parameters as needed.
-
-## Standalone Usage
-
-You can also use the document processor independently of the agent:
-
-```typescript
-import { DocumentProcessor, extractFromDocument } from '@minded-ai/mindedjs';
-
-// Using the class directly
-const processor = new DocumentProcessor({
-  llamaCloudApiKey: 'your-key',
-  maxImageWidth: 1200,
-});
-
-const result = await processor.extractFromDocument({
-  documentPath: './document.pdf',
-  schema: yourSchema,
-});
-
-// Using the convenience function
-const result2 = await extractFromDocument({
-  documentPath: './document.pdf',
-  schema: yourSchema,
-  config: {
-    llamaCloudApiKey: 'your-key',
-  },
-});
-```
-
 ## Troubleshooting
 
-### Common Issues
-
 **PDF Processing Fails**
 
 ```
 Error: PDF processing requires LLAMA_CLOUD_API_KEY
 ```
 
-_Solution_: Set the `LLAMA_CLOUD_API_KEY` environment variable.
+Solution: Set the `LLAMA_CLOUD_API_KEY` environment variable.
 
 **Image Too Large**
 
@@ -347,7 +201,7 @@ _Solution_: Set the `LLAMA_CLOUD_API_KEY` environment variable.
 Error: Image processing failed: Input image exceeds pixel limit
 ```
 
-_Solution_: Reduce `maxImageWidth` in configuration or resize images beforehand.
+Solution: Reduce `maxImageWidth` in configuration.
 
 **Schema Validation Errors**
 
@@ -355,28 +209,7 @@ _Solution_: Reduce `maxImageWidth` in configuration or resize images beforehand.
 Error: LLM extraction failed: Invalid schema
 ```
 
-_Solution_: Check that your Zod schema matches expected data structure.
-
-**Network Timeouts**
-
-```
-Error: Failed to fetch document from URL: timeout
-```
-
-_Solution_: Implement retry logic or download files locally first.
-
-### Debugging
-
-Enable debug logging to troubleshoot issues:
-
-```typescript
-// Set LOG_LEVEL environment variable
-process.env.LOG_LEVEL = 'debug';
-
-// Or use the logger directly
-import { logger } from '@minded-ai/mindedjs';
-logger.debug('Processing document:', { path: documentPath });
-```
+Solution: Verify your Zod schema matches the expected data structure.
 
 ## Supported File Types
 

package/docs/tooling/extraction.md

@@ -1,59 +1,65 @@
 # Data Extraction
 
-MindedJS provides a powerful AI-based extraction tool for extracting structured data from unstructured text. The extraction system uses LLM capabilities to parse content and return data in a predefined format.
+Extract structured data from unstructured text using AI. The `minded-extraction` tool uses LLM capabilities to parse content and return data in a predefined format.
 
 ## Overview
 
-The extraction tool (`minded-extraction`) enables you to extract specific information from text using:
-
-- **Structured Extraction with Zod Schema**: Define exact data structure using Zod schemas
+- **Structured Extraction with Zod Schema**: Define exact data structure
 - **Prompt-based Extraction**: Extract information using custom prompts
-- **Validation and Retries**: Automatic validation against schema with retry logic
-
-## Key Features
-
-- **LLM Structured Output Support**: When available, uses the LLM's native structured output capabilities for guaranteed schema compliance
-- **Fallback JSON Parsing**: Automatically falls back to JSON parsing with validation when structured output is unavailable
-- **Schema Validation**: Built-in Zod validation ensures extracted data matches expected structure
-- **Retry Logic**: Configurable retry attempts with error feedback for improved accuracy
-- **Strict and Non-strict Modes**: Choose between validated extraction (strict) or flexible extraction
-
-## Library Tool Integration
+- **Validation and Retries**: Automatic validation with configurable retry logic
+- **Structured Output Support**: Uses LLM native structured output when available
 
-The extraction functionality is available as a library tool called `minded-extraction` that can be added to your flows through the Minded platform.
-
-### Configuration Options
-
-- `content`: The text to extract information from
-- `schema`: Optional Zod-compatible schema defining the structure
-- `systemPrompt`: Custom instructions for extraction
-- `examples`: Input/output examples to guide extraction
-- `strictMode`: Enable/disable schema validation (default: true)
-- `maxRetries`: Number of retry attempts on validation failure (default: 3)
-- `defaultValue`: Fallback value if extraction fails
-
-## How It Works
+## Using in Flows
 
-1. **With Structured Output Support** (when available):
-
-   - The tool uses the LLM's `withStructuredOutput` method for direct schema-compliant extraction
-   - No manual JSON parsing or validation needed
-   - Guaranteed to match the provided Zod schema
-
-2. **Fallback Mode** (JSON parsing):
+```yaml
+- id: extractCustomerInfo
+  type: tool
+  toolName: minded-extraction
+  prompt: Extract customer name, email, and phone number from the message
+```
 
-   - Generates a prompt with schema description
-   - Uses JSON output parser to extract structured data
-   - Validates against Zod schema
-   - Retries with error feedback if validation fails
+### Tool Parameters
+
+| Parameter    | Type    | Description                            | Required |
+| ------------ | ------- | -------------------------------------- | -------- |
+| content      | string  | Text to extract from                   | Yes      |
+| schema       | object  | Zod-compatible schema                  | No       |
+| systemPrompt | string  | Custom instructions                    | No       |
+| examples     | array   | Input/output examples                  | No       |
+| strictMode   | boolean | Enable validation (default: true)      | No       |
+| maxRetries   | number  | Retry attempts on failure (default: 3) | No       |
+| defaultValue | any     | Fallback value                         | No       |
+
+### Overriding Parameters in Flows
+
+```yaml
+- name: 'Extract Customer Info'
+  type: 'tool'
+  toolName: 'minded-extraction'
+  parameters:
+    content: '{state.memory.rawText}'
+    schema:
+      name:
+        type: 'string'
+        description: 'Customer full name'
+      email:
+        type: 'string'
+        description: 'Email address'
+        required: false
+      phone:
+        type: 'string'
+    systemPrompt: 'Extract contact information from the text'
+    strictMode: true
+    maxRetries: 3
+```
 
-3. **Non-strict Mode**:
-   - Skips validation for more flexible extraction
-   - Useful when schema compliance is not critical
+**Available schema field properties:**
 
-## Standalone Usage
+- `type`: `'string'`, `'number'`, `'boolean'`, `'array'`, or `'object'`
+- `description`: Optional field description
+- `required`: Optional boolean (defaults to true)
 
-The extraction utility can also be used programmatically:
+## Programmatic Usage
 
 ```typescript
 import { extract, createExtractor } from '@minded-ai/mindedjs';
@@ -76,3 +82,9 @@ const result = await extract(
 const extractor = createExtractor(schema, { systemPrompt: 'Extract data' });
 const result = await extractor(content, agent.llm);
 ```
+
+## How It Works
+
+1. **With Structured Output Support**: Uses LLM's `withStructuredOutput` for direct schema-compliant extraction
+2. **Fallback Mode**: Generates prompt with schema description, parses JSON, validates against Zod schema, retries with error feedback
+3. **Non-strict Mode**: Skips validation for flexible extraction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "2.0.36",
+  "version": "2.0.39-beta.1",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agent.ts

@@ -488,7 +488,8 @@ export class Agent {
     try {
       await this.waitForInitialization();
     } catch (err) {
-      logger.error({ msg: '[Trigger] Agent initialization failed', err });
+      const { baseUrl } = getConfig();
+      logger.error({ msg: '[Trigger] Agent initialization failed', err, sessionId, baseUrl });
       throw err;
     }
 

package/src/index.ts

@@ -85,7 +85,7 @@ export {
   TriggerEvent,
 } from './types/Agent.types';
 export type { AgentInvokeParams, MindedSDKConfig } from './types/Agent.types';
-export type { Environment } from './types/Platform.types';
+export { Environment } from './types/Platform.types';
 export type { State } from './types/LangGraph.types';
 export { zendesk } from './interfaces/zendesk';