@minded-ai/mindedjs 1.0.103 → 1.0.105

package/src/internalTools/documentExtraction/documentExtraction.ts

@@ -0,0 +1,861 @@
+import { ZodSchema, ZodTypeAny } from 'zod';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import * as fs from 'fs';
+import * as path from 'path';
+import { pdfToPng } from 'pdf-to-png-converter';
+import { logger } from '../../utils/logger';
+import * as os from 'os';
+import { DocumentExtractionOptions, DocumentProcessingResult, DocumentProcessorConfig, SUPPORTED_DOCUMENT_TYPES } from './types';
+
+/**
+ * Extract data from documents using AI or return raw text.
+ *
+ * This function allows you to process various document types (PDFs, images, Word docs, etc.)
+ * in multiple ways:
+ * - With LLM + Schema: Extract structured data according to a Zod schema
+ * - With LLM + System Prompt: Extract unstructured data based on prompt instructions
+ * - Without LLM: Extract raw text content using LlamaParse
+ *
+ * @param options - Document extraction options
+ * @param options.llm - Optional language model for AI-powered extraction
+ * @param options.documentPath - Path to the document file
+ * @param options.documentContent - Document content as Buffer or string
+ * @param options.documentUrl - URL to fetch the document from
+ * @param options.schema - Optional Zod schema for structured data extraction
+ * @param options.systemPrompt - Optional prompt for guiding extraction
+ * @param options.config - Optional document processor configuration
+ *
+ * @returns Promise resolving to extracted data/text and metadata
+ *
+ * @example
+ * ```typescript
+ * import { extractFromDocument } from '@minded-ai/mindedjs';
+ * import { z } from 'zod';
+ *
+ * // Extract structured data with schema
+ * const result1 = await extractFromDocument({
+ *   llm: agent.llm,
+ *   documentPath: './invoice.pdf',
+ *   schema: z.object({
+ *     invoiceNumber: z.string(),
+ *     amount: z.number(),
+ *   })
+ * });
+ *
+ * // Extract unstructured data with prompt
+ * const result2 = await extractFromDocument({
+ *   llm: agent.llm,
+ *   documentPath: './contract.pdf',
+ *   systemPrompt: 'Extract all payment terms and conditions'
+ * });
+ *
+ * // Extract raw text without LLM
+ * const result3 = await extractFromDocument({
+ *   documentPath: './document.pdf'
+ * });
+ * ```
+ */
+export async function extractFromDocument<T = string>(options: {
+  llm?: BaseLanguageModel;
+  documentPath?: string;
+  documentContent?: Buffer | string;
+  documentUrl?: string;
+  schema?: ZodSchema<T>;
+  systemPrompt?: string;
+  config?: DocumentProcessorConfig;
+}): Promise<{
+  data: T;
+  metadata: {
+    fileSize?: number;
+    fileType: string;
+    processingTime: number;
+    contentLength: number;
+  };
+}> {
+  // Create a document processor
+  const processor = new DocumentProcessor(options.config, options.llm);
+
+  // Extract from document using the processor
+  return processor.extractFromDocument({
+    documentPath: options.documentPath,
+    documentContent: options.documentContent,
+    documentUrl: options.documentUrl,
+    schema: options.schema,
+    systemPrompt: options.systemPrompt,
+  });
+}
+
+/**
+ * Generic document processor that can extract structured data from various document types
+ * including images, PDFs, Word documents, spreadsheets, and more.
+ */
+export class DocumentProcessor {
+  private config: DocumentProcessorConfig;
+  private llm: BaseLanguageModel | null = null;
+  private llamaCloudApiKey: string | null = null;
+  private sharpModule: any = null;
+  private sharpLoadAttempted = false;
+
+  constructor(config: DocumentProcessorConfig = {}, llm?: BaseLanguageModel) {
+    this.config = {
+      maxImageWidth: 1200,
+      imageQuality: 85,
+      useBase64: false,
+      ...config,
+    };
+
+    this.llm = llm || null;
+    this.llamaCloudApiKey = this.config.llamaCloudApiKey || process.env.LLAMA_CLOUD_API_KEY || null;
+  }
+
+  /**
+   * Parse document using LlamaCloud REST API
+   */
+  private async parseWithLlamaCloud(filePath: string): Promise<string | null> {
+    if (!this.llamaCloudApiKey) {
+      return null;
+    }
+
+    try {
+      // Step 1: Upload file and start parsing
+      const fileContent = fs.readFileSync(filePath);
+      const fileName = path.basename(filePath);
+      const mimeType = this.getMimeType(path.extname(filePath));
+
+      const formData = new FormData();
+      const blob = new Blob([fileContent], { type: mimeType });
+      formData.append('file', blob, fileName);
+
+      const uploadResponse = await fetch('https://api.cloud.llamaindex.ai/api/v1/parsing/upload', {
+        method: 'POST',
+        headers: {
+          Accept: 'application/json',
+          Authorization: `Bearer ${this.llamaCloudApiKey}`,
+        },
+        body: formData,
+      });
+
+      if (!uploadResponse.ok) {
+        const errorText = await uploadResponse.text();
+        throw new Error(`Failed to upload file: ${uploadResponse.status} - ${errorText}`);
+      }
+
+      const uploadResult = await uploadResponse.json();
+      const jobId = uploadResult.id || uploadResult.job_id;
+
+      if (!jobId) {
+        throw new Error('No job ID returned from upload');
+      }
+
+      logger.info({
+        msg: '[DocumentProcessor] File uploaded to LlamaCloud',
+        jobId,
+        fileName,
+      });
+
+      // Step 2: Poll for job completion
+      let attempts = 0;
+      const maxAttempts = 60; // 60 attempts with 2 second delay = 2 minutes max
+      const pollDelay = 2000; // 2 seconds
+
+      while (attempts < maxAttempts) {
+        const statusResponse = await fetch(`https://api.cloud.llamaindex.ai/api/v1/parsing/job/${jobId}`, {
+          method: 'GET',
+          headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${this.llamaCloudApiKey}`,
+          },
+        });
+
+        if (!statusResponse.ok) {
+          throw new Error(`Failed to check job status: ${statusResponse.status}`);
+        }
+
+        const statusResult = await statusResponse.json();
+        const status = statusResult.status || statusResult.job_status;
+
+        if (status === 'SUCCESS' || status === 'COMPLETED' || status === 'completed') {
+          // Step 3: Retrieve results in Markdown
+
+          // Create an AbortController for timeout
+          const controller = new AbortController();
+          const timeout = setTimeout(() => controller.abort(), 20000); // 20 second timeout
+
+          let resultResponse;
+          try {
+            resultResponse = await fetch(`https://api.cloud.llamaindex.ai/api/v1/parsing/job/${jobId}/result/markdown`, {
+              method: 'GET',
+              headers: {
+                Accept: 'application/json',
+                Authorization: `Bearer ${this.llamaCloudApiKey}`,
+              },
+              signal: controller.signal,
+            });
+          } catch (fetchError) {
+            clearTimeout(timeout);
+            if (fetchError instanceof Error && fetchError.name === 'AbortError') {
+              throw new Error('Timeout fetching results from LlamaCloud after 20 seconds');
+            }
+            throw fetchError;
+          }
+
+          clearTimeout(timeout);
+
+          if (!resultResponse.ok) {
+            const errorText = await resultResponse.text();
+            throw new Error(`Failed to retrieve results: ${resultResponse.status} - ${errorText}`);
+          }
+
+          let resultData: any;
+          try {
+            // Read response using manual stream reading (more reliable than text())
+            let responseText;
+            if (resultResponse.body) {
+              const reader = resultResponse.body.getReader();
+              const chunks: Uint8Array[] = [];
+              let totalLength = 0;
+
+              try {
+                while (true) {
+                  const { done, value } = await reader.read();
+                  if (done) break;
+                  if (value) {
+                    chunks.push(value);
+                    totalLength += value.length;
+                  }
+                }
+
+                // Combine chunks
+                const combined = new Uint8Array(totalLength);
+                let offset = 0;
+                for (const chunk of chunks) {
+                  combined.set(chunk, offset);
+                  offset += chunk.length;
+                }
+
+                responseText = new TextDecoder().decode(combined);
+              } finally {
+                reader.releaseLock();
+              }
+            } else {
+              responseText = await resultResponse.text();
+            }
+
+            // Try to parse as JSON, but if it fails, use the text directly
+            try {
+              resultData = JSON.parse(responseText);
+            } catch {
+              // If it's not JSON, assume it's the markdown content directly
+              resultData = responseText;
+            }
+          } catch (textError) {
+            logger.error({
+              msg: '[DocumentProcessor] Failed to read response text',
+              jobId,
+              error: textError instanceof Error ? textError.message : String(textError),
+              stack: textError instanceof Error ? textError.stack : undefined,
+            });
+            throw new Error('Failed to read response from LlamaCloud');
+          }
+
+          logger.debug({
+            msg: '[DocumentProcessor] Result data structure',
+            jobId,
+            dataType: typeof resultData,
+            keys: typeof resultData === 'object' && resultData !== null ? Object.keys(resultData) : [],
+            hasMarkdown: typeof resultData === 'object' && 'markdown' in resultData,
+            hasContent: typeof resultData === 'object' && 'content' in resultData,
+            hasText: typeof resultData === 'object' && 'text' in resultData,
+          });
+
+          // The API might return the markdown directly as a string or nested in an object
+          let markdownContent: string;
+          if (typeof resultData === 'string') {
+            markdownContent = resultData;
+          } else {
+            markdownContent = resultData.markdown || resultData.content || resultData.text || '';
+          }
+
+          if (!markdownContent) {
+            logger.error({
+              msg: '[DocumentProcessor] No content in result',
+              jobId,
+              resultData: JSON.stringify(resultData).substring(0, 500),
+            });
+            throw new Error('No content returned from parsing');
+          }
+
+          logger.info({
+            msg: '[DocumentProcessor] Successfully parsed document with LlamaCloud',
+            jobId,
+            contentLength: markdownContent.length,
+            preview: markdownContent.substring(0, 100),
+          });
+
+          logger.debug({
+            msg: '[DocumentProcessor] About to return markdown content',
+            jobId,
+          });
+
+          return markdownContent;
+        } else if (status === 'FAILED' || status === 'ERROR' || status === 'failed') {
+          throw new Error(`Parsing job failed: ${statusResult.error || 'Unknown error'}`);
+        }
+
+        // Wait before next attempt
+        await new Promise((resolve) => setTimeout(resolve, pollDelay));
+        attempts++;
+      }
+
+      throw new Error('Parsing job timed out after 2 minutes');
+    } catch (error) {
+      logger.warn({
+        msg: '[DocumentProcessor] LlamaCloud parsing failed',
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    } finally {
+      logger.debug({
+        msg: '[DocumentProcessor] parseWithLlamaCloud finished',
+        filePath,
+      });
+    }
+  }
+
+  /**
+   * Get MIME type for file extension
+   */
+  private getMimeType(fileExtension: string): string {
+    const mimeTypes: { [key: string]: string } = {
+      '.pdf': 'application/pdf',
+      '.doc': 'application/msword',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.txt': 'text/plain',
+      '.rtf': 'application/rtf',
+      '.jpg': 'image/jpeg',
+      '.jpeg': 'image/jpeg',
+      '.png': 'image/png',
+      '.gif': 'image/gif',
+      '.bmp': 'image/bmp',
+      '.webp': 'image/webp',
+      '.tiff': 'image/tiff',
+      '.xls': 'application/vnd.ms-excel',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      '.csv': 'text/csv',
+      '.html': 'text/html',
+      '.htm': 'text/html',
+      '.xml': 'application/xml',
+      '.md': 'text/markdown',
+    };
+
+    return mimeTypes[fileExtension.toLowerCase()] || 'application/octet-stream';
+  }
+
+  /**
+   * Extract data from a document - either structured data using AI or raw text
+   */
+  async extractFromDocument<T = string>(options: DocumentExtractionOptions): Promise<DocumentProcessingResult<T>> {
+    logger.debug({
+      msg: '[DocumentProcessor] extractFromDocument called',
+      hasDocumentPath: !!options.documentPath,
+      hasDocumentUrl: !!options.documentUrl,
+      hasDocumentContent: !!options.documentContent,
+      hasLLM: !!this.llm,
+      hasSchema: !!options.schema,
+    });
+
+    const startTime = Date.now();
+
+    try {
+      logger.debug({
+        msg: '[DocumentProcessor] Getting document content',
+      });
+
+      // Determine document source and content
+      const { content, fileType, fileSize } = await this.getDocumentContent(options);
+
+      // Process document content based on type
+      let processedContent: string;
+
+      if (this.isImageFile(fileType)) {
+        processedContent = await this.processImageDocument(content as Buffer, fileType, options.documentPath);
+      } else {
+        processedContent = await this.processTextDocument(content, options.documentPath, fileType);
+      }
+
+      logger.info({
+        msg: '[DocumentProcessor] Document content processed',
+        fileType,
+        contentLength: processedContent.length,
+      });
+
+      const processingTime = Date.now() - startTime;
+
+      // If no LLM is provided, return the raw text content
+      if (!this.llm) {
+        return {
+          data: processedContent as T,
+          metadata: {
+            fileSize,
+            fileType,
+            processingTime,
+            contentLength: processedContent.length,
+          },
+        };
+      }
+
+      // If LLM is provided, extract data (structured or unstructured)
+      const extractedData = await this.extractStructuredData<T>(processedContent, options.schema, options.llmConfig, options.systemPrompt);
+
+      return {
+        data: extractedData,
+        metadata: {
+          fileSize,
+          fileType,
+          processingTime,
+          contentLength: processedContent.length,
+        },
+      };
+    } catch (error) {
+      logger.error({
+        msg: '[DocumentProcessor] Document processing failed',
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw new Error(`Document processing failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Get document content from various sources
+   */
+  private async getDocumentContent(options: DocumentExtractionOptions): Promise<{
+    content: Buffer | string;
+    fileType: string;
+    fileSize?: number;
+  }> {
+    logger.debug({
+      msg: '[DocumentProcessor] getDocumentContent called',
+      hasPath: !!options.documentPath,
+      hasContent: !!options.documentContent,
+      hasUrl: !!options.documentUrl,
+    });
+
+    // From file path
+    if (options.documentPath) {
+      if (!fs.existsSync(options.documentPath)) {
+        throw new Error(`Document not found: ${options.documentPath}`);
+      }
+
+      const content = fs.readFileSync(options.documentPath);
+      const fileType = path.extname(options.documentPath).toLowerCase();
+
+      return {
+        content,
+        fileType,
+        fileSize: content.length,
+      };
+    }
+
+    // From provided content
+    if (options.documentContent) {
+      // Try to infer file type from content if it's a buffer
+      let fileType = '.unknown';
+      if (Buffer.isBuffer(options.documentContent)) {
+        fileType = this.inferFileTypeFromBuffer(options.documentContent);
+      } else if (typeof options.documentContent === 'string') {
+        fileType = '.txt'; // Assume text content
+      }
+
+      return {
+        content: options.documentContent,
+        fileType,
+        fileSize: Buffer.isBuffer(options.documentContent) ? options.documentContent.length : Buffer.byteLength(options.documentContent),
+      };
+    }
+
+    // From URL
+    if (options.documentUrl) {
+      logger.debug({
+        msg: '[DocumentProcessor] Fetching document from URL',
+        url: options.documentUrl,
+      });
+
+      const response = await fetch(options.documentUrl);
+
+      logger.debug({
+        msg: '[DocumentProcessor] URL fetch response',
+        status: response.status,
+        ok: response.ok,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch document from URL: ${response.statusText}`);
+      }
+
+      const arrayBuffer = await response.arrayBuffer();
+      const content = Buffer.from(arrayBuffer);
+      const fileType = this.inferFileTypeFromUrl(options.documentUrl) || this.inferFileTypeFromBuffer(content);
+
+      logger.debug({
+        msg: '[DocumentProcessor] Document fetched from URL',
+        contentSize: content.length,
+        fileType,
+      });
+
+      return {
+        content,
+        fileType,
+        fileSize: content.length,
+      };
+    }
+
+    throw new Error('No document source provided. Specify documentPath, documentContent, or documentUrl.');
+  }
+
+  /**
+   * Process image documents by converting them to a standardized format
+   */
+  private async processImageDocument(content: Buffer, fileType: string, filePath?: string): Promise<string> {
+    try {
+      // First, try to use LlamaParser if available for text extraction
+      if (filePath && this.llamaCloudApiKey) {
+        logger.debug({
+          msg: '[DocumentProcessor] Calling parseWithLlamaCloud for image',
+          filePath,
+        });
+        const parsedContent = await this.parseWithLlamaCloud(filePath);
+        logger.debug({
+          msg: '[DocumentProcessor] parseWithLlamaCloud returned for image',
+          hasContent: !!parsedContent,
+          contentLength: parsedContent?.length,
+        });
+        if (parsedContent) {
+          return parsedContent;
+        }
+      }
+
+      // If no file path, create a temporary file for LlamaCloud parsing
+      if (!filePath && this.llamaCloudApiKey) {
+        const tempDir = os.tmpdir();
+        const tempFileName = `temp_${Date.now()}${fileType}`;
+        const tempFilePath = path.join(tempDir, tempFileName);
+
+        logger.debug({
+          msg: '[DocumentProcessor] Creating temp file for image',
+          tempFilePath,
+          contentSize: content.length,
+        });
+
+        try {
+          fs.writeFileSync(tempFilePath, content);
+          logger.debug({
+            msg: '[DocumentProcessor] Calling parseWithLlamaCloud for temp image',
+            tempFilePath,
+          });
+          const parsedContent = await this.parseWithLlamaCloud(tempFilePath);
+          logger.debug({
+            msg: '[DocumentProcessor] parseWithLlamaCloud returned for temp image',
+            hasContent: !!parsedContent,
+            contentLength: parsedContent?.length,
+          });
+          fs.unlinkSync(tempFilePath);
+
+          if (parsedContent) {
+            return parsedContent;
+          }
+        } catch (error) {
+          // Clean up temp file on error
+          if (fs.existsSync(tempFilePath)) {
+            fs.unlinkSync(tempFilePath);
+          }
+          logger.warn({
+            msg: '[DocumentProcessor] Failed to parse image with LlamaCloud',
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      // Fallback: Convert to image format for LLM processing
+      // For PDFs, convert first page to image
+      if (fileType === '.pdf') {
+        const pngPages = await pdfToPng(content, {
+          disableFontFace: true,
+          useSystemFonts: true,
+          viewportScale: 2.0,
+          pagesToProcess: [1], // Only first page
+        });
+
+        if (pngPages.length === 0) {
+          throw new Error('Failed to convert PDF to image');
+        }
+
+        content = pngPages[0].content;
+      }
+
+      // Check if sharp is available before using it
+      if (!this.sharpLoadAttempted) {
+        this.sharpLoadAttempted = true;
+        try {
+          this.sharpModule = await import('sharp');
+          this.sharpModule = this.sharpModule.default || this.sharpModule;
+        } catch (error) {
+          logger.warn({
+            msg: '[DocumentProcessor] Sharp module not available. Image processing will be limited.',
+            error: error instanceof Error ? error.message : String(error),
+          });
+          this.sharpModule = null; // Ensure it's null if loading fails
+        }
+      }
+
+      if (!this.sharpModule) {
+        logger.warn({
+          msg: '[DocumentProcessor] Sharp module not available. Using original image without optimization.',
+          fileType,
+          contentSize: content.length,
+        });
+
+        // If sharp is not available, use the original image
+        if (this.config.useBase64) {
+          // Return original image as base64
+          const base64Image = content.toString('base64');
+          const mimeType = this.getMimeType(fileType);
+          return `data:${mimeType};base64,${base64Image}`;
+        } else {
+          // Without sharp and without base64, we cannot process the image
+          return `[IMAGE CONTENT - ${fileType.toUpperCase()} file. Size: ${
+            content.length
+          } bytes. Consider using LLAMA_CLOUD_API_KEY for text extraction or set useBase64: true]`;
+        }
+      }
+
+      // Resize and optimize image using sharp
+      const processedImage = await this.sharpModule(content)
+        .resize(this.config.maxImageWidth!, null, {
+          withoutEnlargement: true,
+          fit: 'inside',
+        })
+        .jpeg({
+          quality: this.config.imageQuality!,
+          mozjpeg: true,
+        })
+        .toBuffer();
+
+      if (this.config.useBase64) {
+        const base64Image = processedImage.toString('base64');
+        return `data:image/jpeg;base64,${base64Image}`;
+      } else {
+        // Without LlamaParser, we cannot extract text from images
+        // Return a placeholder that indicates OCR is needed
+        return `[IMAGE CONTENT - ${fileType.toUpperCase()} file. OCR text extraction requires LlamaParser with LLAMA_CLOUD_API_KEY. Size: ${
+          processedImage.length
+        } bytes]`;
+      }
+    } catch (error) {
+      throw new Error(`Failed to process image document: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Process text-based documents using LlamaParser or fallback methods
+   */
+  private async processTextDocument(content: Buffer | string, filePath?: string, fileType?: string): Promise<string> {
+    // Try LlamaCloud parsing if we have a file path
+    if (filePath && this.llamaCloudApiKey) {
+      const parsedContent = await this.parseWithLlamaCloud(filePath);
+      if (parsedContent) {
+        return parsedContent;
+      }
+    }
+
+    // If no file path but we have content and LlamaCloud API key, create a temp file
+    if (!filePath && this.llamaCloudApiKey && Buffer.isBuffer(content)) {
+      const tempDir = os.tmpdir();
+      const tempFileName = `temp_${Date.now()}${fileType || '.txt'}`;
+      const tempFilePath = path.join(tempDir, tempFileName);
+
+      try {
+        fs.writeFileSync(tempFilePath, content);
+        const parsedContent = await this.parseWithLlamaCloud(tempFilePath);
+        fs.unlinkSync(tempFilePath);
+
+        if (parsedContent) {
+          return parsedContent;
+        }
+      } catch (error) {
+        // Clean up temp file on error
+        if (fs.existsSync(tempFilePath)) {
+          fs.unlinkSync(tempFilePath);
+        }
+        logger.warn({
+          msg: '[DocumentProcessor] Failed to parse text document with LlamaCloud',
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    // Fallback: handle based on file type
+    if (typeof content === 'string') {
+      return content;
+    }
+
+    // For binary content, convert to text
+    if (fileType === '.pdf' && !this.llamaCloudApiKey) {
+      throw new Error('PDF processing requires LLAMA_CLOUD_API_KEY environment variable for LlamaParser');
+    }
+
+    // Basic text extraction for simple formats
+    if (['.txt', '.md', '.html', '.htm', '.xml', '.csv'].includes(fileType || '')) {
+      return content.toString('utf-8');
+    }
+
+    // For unsupported binary formats without LlamaParser
+    throw new Error(`Unsupported document type ${fileType}. Please provide LLAMA_CLOUD_API_KEY for advanced document processing.`);
+  }
+
+  /**
+   * Extract data using LLM - either structured with schema or unstructured with prompt
+   */
+  private async extractStructuredData<T>(
+    content: string,
+    schema?: ZodSchema<T> | ZodTypeAny,
+    llmConfig?: { model?: string; temperature?: number },
+    systemPrompt?: string,
+  ): Promise<T> {
+    if (!this.llm) {
+      throw new Error('LLM instance is required for data extraction. Please provide an LLM when creating the DocumentProcessor.');
+    }
+
+    // Note: llmConfig is ignored when using the provided LLM instance
+    // The LLM should already be configured with the desired model and temperature
+
+    const defaultSystemPrompt =
+      'You are an expert data-extraction assistant. ' +
+      'Extract the requested information from the provided document content. ' +
+      'If you cannot find a value for a required field, use "N/A" or a descriptive placeholder. ' +
+      'Be accurate and thorough in your extraction.';
+
+    const finalSystemPrompt = systemPrompt || defaultSystemPrompt;
+
+    try {
+      // If schema is provided, use structured output
+      if (schema) {
+        // Check if the LLM supports withStructuredOutput
+        if (!('withStructuredOutput' in this.llm)) {
+          throw new Error('The provided LLM does not support structured output. Please use a compatible LLM instance.');
+        }
+
+        const structuredLlm = (this.llm as any).withStructuredOutput(schema as any);
+
+        const result = await structuredLlm.invoke([
+          {
+            role: 'system',
+            content: finalSystemPrompt,
+          },
+          {
+            role: 'user',
+            content: `Please extract the following information from this document:\n\n${content}`,
+          },
+        ]);
+
+        logger.debug({
+          msg: '[DocumentProcessor] Structured data extraction completed',
+          extractedData: JSON.stringify(result, null, 2),
+        });
+
+        return result as T;
+      } else {
+        // Without schema, return the LLM's text response
+        const response = await this.llm.invoke([
+          {
+            role: 'system',
+            content: finalSystemPrompt,
+          },
+          {
+            role: 'user',
+            content: `Please analyze and extract information from this document:\n\n${content}`,
+          },
+        ]);
+
+        // Extract the text content from the response
+        let textContent: string;
+        if (typeof response.content === 'string') {
+          textContent = response.content;
+        } else if (Array.isArray(response.content) && response.content.length > 0) {
+          // Handle array of content blocks
+          textContent = response.content.map((block: any) => (typeof block === 'string' ? block : block.text || '')).join('\n');
+        } else {
+          textContent = String(response.content);
+        }
+
+        logger.debug({
+          msg: '[DocumentProcessor] Unstructured data extraction completed',
+          contentLength: textContent.length,
+        });
+
+        return textContent as T;
+      }
+    } catch (error) {
+      throw new Error(`LLM extraction failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Check if file is an image type
+   */
+  private isImageFile(fileType: string): boolean {
+    const imageTypes = ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.tiff'];
+    return imageTypes.includes(fileType.toLowerCase());
+  }
+
+  /**
+   * Infer file type from buffer content
+   */
+  private inferFileTypeFromBuffer(buffer: Buffer): string {
+    // Check common file signatures
+    const signatures: { [key: string]: string } = {
+      '89504E47': '.png',
+      FFD8FF: '.jpg',
+      '47494638': '.gif',
+      '25504446': '.pdf',
+      '504B0304': '.zip', // Also used by docx, xlsx, pptx
+      D0CF11E0: '.doc', // Also xls, ppt
+    };
+
+    const hex = buffer.toString('hex', 0, 4).toUpperCase();
+
+    for (const [signature, type] of Object.entries(signatures)) {
+      if (hex.startsWith(signature)) {
+        return type;
+      }
+    }
+
+    return '.unknown';
+  }
+
+  /**
+   * Infer file type from URL
+   */
+  private inferFileTypeFromUrl(url: string): string | null {
+    try {
+      const pathname = new URL(url).pathname;
+      const extension = path.extname(pathname).toLowerCase();
+      return extension || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get list of supported document types
+   */
+  static getSupportedDocumentTypes(): string[] {
+    return [...SUPPORTED_DOCUMENT_TYPES];
+  }
+
+  /**
+   * Check if a file type is supported
+   */
+  static isDocumentTypeSupported(fileType: string): boolean {
+    return SUPPORTED_DOCUMENT_TYPES.includes(fileType.toLowerCase());
+  }
+}