fix(MultiModalModel): Lazy-load SmartPdf and guard document processing across providers; ensure SmartPdf is initialized only when needed

changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2025-10-10 - 0.7.7 - fix(MultiModalModel)
+Lazy-load SmartPdf and guard document processing across providers; ensure SmartPdf is initialized only when needed
+
+- Make SmartPdf lazy-loaded: smartpdfInstance is now nullable and no longer started automatically in start()
+- Add ensureSmartpdfReady() to initialize and start SmartPdf on demand before document processing
+- Providers updated (OpenAI, Anthropic, Ollama, xAI) to call ensureSmartpdfReady() and use the smartpdfInstance for PDF -> image conversion
+- stop() now cleans up and nullifies smartpdfInstance to release resources
+- Avoids starting a browser/process unless document() is actually used (reduces unnecessary resource usage)
+- Add local Claude permissions file (.claude/settings.local.json) for tooling/configuration
+
 ## 2025-10-09 - 0.7.6 - fix(provider.elevenlabs)
 Provide default ElevenLabs TTS voice fallback and add local tool/project configs
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartai',
-  version: '0.7.6',
+  version: '0.7.7',
   description: 'SmartAi is a versatile TypeScript library designed to facilitate integration and interaction with various AI models, offering functionalities for chat, audio generation, document processing, and vision tasks.'
 }

ts/abstract.classes.multimodal.ts

@@ -111,17 +111,28 @@ export interface ImageResponse {
 export abstract class MultiModalModel {
   /**
    * SmartPdf instance for document processing
-   * Shared across all methods that need PDF functionality
+   * Lazy-loaded only when PDF processing is needed to avoid starting browser unnecessarily
    */
-  protected smartpdfInstance: plugins.smartpdf.SmartPdf;
+  protected smartpdfInstance: plugins.smartpdf.SmartPdf | null = null;
+
+  /**
+   * Ensures SmartPdf instance is initialized and ready
+   * Call this before using smartpdfInstance in document processing methods
+   */
+  protected async ensureSmartpdfReady(): Promise<void> {
+    if (!this.smartpdfInstance) {
+      this.smartpdfInstance = new plugins.smartpdf.SmartPdf();
+      await this.smartpdfInstance.start();
+    }
+  }
 
   /**
    * Initializes the model and any necessary resources
    * Should be called before using any other methods
    */
   public async start(): Promise<void> {
-    this.smartpdfInstance = new plugins.smartpdf.SmartPdf();
+    // SmartPdf is now lazy-loaded only when needed for PDF processing
-    await this.smartpdfInstance.start();
+    // This avoids starting a browser unless document() method is actually used
   }
 
   /**
@@ -131,6 +142,7 @@ export abstract class MultiModalModel {
   public async stop(): Promise<void> {
     if (this.smartpdfInstance) {
       await this.smartpdfInstance.stop();
+      this.smartpdfInstance = null;
     }
   }
 

ts/provider.anthropic.ts

@@ -192,11 +192,14 @@ export class AnthropicProvider extends MultiModalModel {
     pdfDocuments: Uint8Array[];
     messageHistory: ChatMessage[];
   }): Promise<{ message: any }> {
+    // Ensure SmartPdf is initialized before processing documents
+    await this.ensureSmartpdfReady();
+
     // Convert PDF documents to images using SmartPDF
     let documentImageBytesArray: Uint8Array[] = [];
 
     for (const pdfDocument of optionsArg.pdfDocuments) {
-      const documentImageArray = await this.smartpdfInstance.convertPDFToPngBytes(pdfDocument);
+      const documentImageArray = await this.smartpdfInstance!.convertPDFToPngBytes(pdfDocument);
       documentImageBytesArray = documentImageBytesArray.concat(documentImageArray);
     }
 

ts/provider.ollama.ts

@@ -216,11 +216,14 @@ export class OllamaProvider extends MultiModalModel {
     pdfDocuments: Uint8Array[];
     messageHistory: ChatMessage[];
   }): Promise<{ message: any }> {
+    // Ensure SmartPdf is initialized before processing documents
+    await this.ensureSmartpdfReady();
+
     // Convert PDF documents to images using SmartPDF
     let documentImageBytesArray: Uint8Array[] = [];
 
     for (const pdfDocument of optionsArg.pdfDocuments) {
-      const documentImageArray = await this.smartpdfInstance.convertPDFToPngBytes(pdfDocument);
+      const documentImageArray = await this.smartpdfInstance!.convertPDFToPngBytes(pdfDocument);
       documentImageBytesArray = documentImageBytesArray.concat(documentImageArray);
     }
 

ts/provider.openai.ts

@@ -173,11 +173,14 @@ export class OpenAiProvider extends MultiModalModel {
       content: any;
     }[];
   }) {
+    // Ensure SmartPdf is initialized before processing documents
+    await this.ensureSmartpdfReady();
+
     let pdfDocumentImageBytesArray: Uint8Array[] = [];
 
     // Convert each PDF into one or more image byte arrays.
     for (const pdfDocument of optionsArg.pdfDocuments) {
-      const documentImageArray = await this.smartpdfInstance.convertPDFToPngBytes(pdfDocument);
+      const documentImageArray = await this.smartpdfInstance!.convertPDFToPngBytes(pdfDocument);
       pdfDocumentImageBytesArray = pdfDocumentImageBytesArray.concat(documentImageArray);
     }
 

ts/provider.xai.ts

@@ -149,11 +149,14 @@ export class XAIProvider extends MultiModalModel {
     pdfDocuments: Uint8Array[];
     messageHistory: { role: string; content: string; }[];
   }): Promise<{ message: any }> {
+    // Ensure SmartPdf is initialized before processing documents
+    await this.ensureSmartpdfReady();
+
     // First convert PDF documents to images
     let pdfDocumentImageBytesArray: Uint8Array[] = [];
 
     for (const pdfDocument of optionsArg.pdfDocuments) {
-      const documentImageArray = await this.smartpdfInstance.convertPDFToPngBytes(pdfDocument);
+      const documentImageArray = await this.smartpdfInstance!.convertPDFToPngBytes(pdfDocument);
       pdfDocumentImageBytesArray = pdfDocumentImageBytesArray.concat(documentImageArray);
     }