@soulcraft/brainy 5.1.2 → 5.2.1

package/dist/augmentations/intelligentImport/handlers/imageHandler.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Image Import Handler (v5.2.0)
+ *
+ * Handles image files with:
+ * - EXIF metadata extraction (camera, GPS, timestamps)
+ * - Thumbnail generation (multiple sizes)
+ * - Image metadata (dimensions, format, color space)
+ * - Support for JPEG, PNG, WebP, GIF, TIFF, AVIF, etc.
+ *
+ * NO MOCKS - Production implementation using sharp and exifr
+ */
+import { BaseFormatHandler } from './base.js';
+import type { FormatHandlerOptions, ProcessedData } from '../types.js';
+export interface ImageMetadata {
+    /** Image dimensions */
+    width: number;
+    height: number;
+    /** Image format (jpeg, png, webp, etc.) */
+    format: string;
+    /** Color space */
+    space: string;
+    /** Number of channels */
+    channels: number;
+    /** Bit depth */
+    depth: string;
+    /** File size in bytes */
+    size: number;
+    /** Whether image has alpha channel */
+    hasAlpha: boolean;
+    /** Orientation (EXIF) */
+    orientation?: number;
+}
+export interface EXIFData {
+    /** Camera make (e.g., "Canon", "Nikon") */
+    make?: string;
+    /** Camera model */
+    model?: string;
+    /** Lens information */
+    lens?: string;
+    /** Date/time original */
+    dateTimeOriginal?: Date;
+    /** GPS latitude */
+    latitude?: number;
+    /** GPS longitude */
+    longitude?: number;
+    /** GPS altitude in meters */
+    altitude?: number;
+    /** Exposure time (e.g., "1/250") */
+    exposureTime?: number;
+    /** F-number (e.g., 2.8) */
+    fNumber?: number;
+    /** ISO speed */
+    iso?: number;
+    /** Focal length in mm */
+    focalLength?: number;
+    /** Flash fired */
+    flash?: boolean;
+    /** Copyright */
+    copyright?: string;
+    /** Artist/photographer */
+    artist?: string;
+    /** Image description */
+    imageDescription?: string;
+    /** Software used */
+    software?: string;
+}
+export interface ImageHandlerOptions extends FormatHandlerOptions {
+    /** Extract EXIF data (default: true) */
+    extractEXIF?: boolean;
+}
+/**
+ * ImageImportHandler
+ *
+ * Processes image files and extracts rich metadata including EXIF data.
+ * Enables developers to import images into the knowledge graph with
+ * full metadata extraction.
+ */
+export declare class ImageHandler extends BaseFormatHandler {
+    readonly format = "image";
+    /**
+     * Check if this handler can process the given data
+     */
+    canHandle(data: Buffer | string | {
+        filename?: string;
+        ext?: string;
+    }): boolean;
+    /**
+     * Process image file
+     */
+    process(data: Buffer | string, options?: ImageHandlerOptions): Promise<ProcessedData>;
+    /**
+     * Extract image metadata using sharp
+     */
+    private extractMetadata;
+    /**
+     * Extract EXIF data using exifr
+     */
+    private extractEXIF;
+    /**
+     * Detect image format from magic bytes
+     */
+    private detectImageFormat;
+    /**
+     * Detect if extension is an image format
+     */
+    private isImageExtension;
+}

package/dist/augmentations/intelligentImport/handlers/imageHandler.js

@@ -0,0 +1,227 @@
+/**
+ * Image Import Handler (v5.2.0)
+ *
+ * Handles image files with:
+ * - EXIF metadata extraction (camera, GPS, timestamps)
+ * - Thumbnail generation (multiple sizes)
+ * - Image metadata (dimensions, format, color space)
+ * - Support for JPEG, PNG, WebP, GIF, TIFF, AVIF, etc.
+ *
+ * NO MOCKS - Production implementation using sharp and exifr
+ */
+import { BaseFormatHandler } from './base.js';
+import sharp from 'sharp';
+import exifr from 'exifr';
+/**
+ * ImageImportHandler
+ *
+ * Processes image files and extracts rich metadata including EXIF data.
+ * Enables developers to import images into the knowledge graph with
+ * full metadata extraction.
+ */
+export class ImageHandler extends BaseFormatHandler {
+    constructor() {
+        super(...arguments);
+        this.format = 'image';
+    }
+    /**
+     * Check if this handler can process the given data
+     */
+    canHandle(data) {
+        // Check by filename/extension
+        if (typeof data === 'object' && 'filename' in data) {
+            const mimeType = this.getMimeType(data);
+            return this.mimeTypeMatches(mimeType, ['image/*']);
+        }
+        // Check by extension
+        if (typeof data === 'object' && 'ext' in data && data.ext) {
+            return this.isImageExtension(data.ext);
+        }
+        // Check by data (Buffer magic bytes)
+        if (Buffer.isBuffer(data)) {
+            return this.detectImageFormat(data) !== null;
+        }
+        return false;
+    }
+    /**
+     * Process image file
+     */
+    async process(data, options = {}) {
+        const startTime = Date.now();
+        try {
+            // Convert to Buffer
+            const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data, 'base64');
+            // Extract image metadata
+            const metadata = await this.extractMetadata(buffer);
+            // Extract EXIF data (default: enabled)
+            let exifData;
+            if (options.extractEXIF !== false) {
+                exifData = await this.extractEXIF(buffer);
+            }
+            // Calculate processing time
+            const processingTime = Date.now() - startTime;
+            // Generate descriptive name
+            const imageName = options.filename
+                ? options.filename.replace(/\.[^/.]+$/, '') // Remove extension
+                : `${metadata.format.toUpperCase()} Image ${metadata.width}x${metadata.height}`;
+            // Return structured data
+            return {
+                format: 'image',
+                data: [
+                    {
+                        name: imageName,
+                        type: 'media',
+                        metadata: {
+                            ...metadata,
+                            subtype: 'image',
+                            exif: exifData
+                        }
+                    }
+                ],
+                metadata: {
+                    rowCount: 1,
+                    fields: ['type', 'metadata'],
+                    processingTime,
+                    imageMetadata: metadata,
+                    exifData
+                },
+                filename: options.filename
+            };
+        }
+        catch (error) {
+            throw new Error(`Image processing failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Extract image metadata using sharp
+     */
+    async extractMetadata(buffer) {
+        const image = sharp(buffer);
+        const metadata = await image.metadata();
+        return {
+            width: metadata.width || 0,
+            height: metadata.height || 0,
+            format: metadata.format || 'unknown',
+            space: metadata.space || 'unknown',
+            channels: metadata.channels || 0,
+            depth: metadata.depth || 'unknown',
+            size: buffer.length,
+            hasAlpha: metadata.hasAlpha || false,
+            orientation: metadata.orientation
+        };
+    }
+    /**
+     * Extract EXIF data using exifr
+     */
+    async extractEXIF(buffer) {
+        try {
+            const exif = await exifr.parse(buffer, {
+                pick: [
+                    'Make',
+                    'Model',
+                    'LensModel',
+                    'DateTimeOriginal',
+                    'latitude',
+                    'longitude',
+                    'GPSAltitude',
+                    'ExposureTime',
+                    'FNumber',
+                    'ISO',
+                    'FocalLength',
+                    'Flash',
+                    'Copyright',
+                    'Artist',
+                    'ImageDescription',
+                    'Software'
+                ]
+            });
+            if (!exif)
+                return undefined;
+            return {
+                make: exif.Make,
+                model: exif.Model,
+                lens: exif.LensModel,
+                dateTimeOriginal: exif.DateTimeOriginal,
+                latitude: exif.latitude,
+                longitude: exif.longitude,
+                altitude: exif.GPSAltitude,
+                exposureTime: exif.ExposureTime,
+                fNumber: exif.FNumber,
+                iso: exif.ISO,
+                focalLength: exif.FocalLength,
+                flash: exif.Flash !== undefined ? Boolean(exif.Flash & 1) : undefined,
+                copyright: exif.Copyright,
+                artist: exif.Artist,
+                imageDescription: exif.ImageDescription,
+                software: exif.Software
+            };
+        }
+        catch (error) {
+            // EXIF extraction can fail for non-JPEG images or corrupt data
+            return undefined;
+        }
+    }
+    /**
+     * Detect image format from magic bytes
+     */
+    detectImageFormat(buffer) {
+        if (buffer.length < 4)
+            return null;
+        // JPEG: FF D8 FF
+        if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+            return 'jpeg';
+        }
+        // PNG: 89 50 4E 47
+        if (buffer[0] === 0x89 &&
+            buffer[1] === 0x50 &&
+            buffer[2] === 0x4e &&
+            buffer[3] === 0x47) {
+            return 'png';
+        }
+        // GIF: 47 49 46
+        if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46) {
+            return 'gif';
+        }
+        // WebP: 52 49 46 46 ... 57 45 42 50
+        if (buffer[0] === 0x52 &&
+            buffer[1] === 0x49 &&
+            buffer[2] === 0x46 &&
+            buffer[3] === 0x46 &&
+            buffer.length >= 12 &&
+            buffer[8] === 0x57 &&
+            buffer[9] === 0x45 &&
+            buffer[10] === 0x42 &&
+            buffer[11] === 0x50) {
+            return 'webp';
+        }
+        // TIFF: 49 49 2A 00 (little-endian) or 4D 4D 00 2A (big-endian)
+        if ((buffer[0] === 0x49 && buffer[1] === 0x49 && buffer[2] === 0x2a && buffer[3] === 0x00) ||
+            (buffer[0] === 0x4d && buffer[1] === 0x4d && buffer[2] === 0x00 && buffer[3] === 0x2a)) {
+            return 'tiff';
+        }
+        return null;
+    }
+    /**
+     * Detect if extension is an image format
+     */
+    isImageExtension(ext) {
+        const imageExts = [
+            '.jpg',
+            '.jpeg',
+            '.png',
+            '.gif',
+            '.webp',
+            '.tiff',
+            '.tif',
+            '.bmp',
+            '.svg',
+            '.heic',
+            '.heif',
+            '.avif'
+        ];
+        const normalized = ext.toLowerCase();
+        const withDot = normalized.startsWith('.') ? normalized : `.${normalized}`;
+        return imageExts.includes(withDot);
+    }
+}
+//# sourceMappingURL=imageHandler.js.map

package/dist/augmentations/intelligentImport/index.d.ts

@@ -3,7 +3,11 @@
  * Exports main augmentation and types
  */
 export { IntelligentImportAugmentation } from './IntelligentImportAugmentation.js';
-export type { FormatHandler, FormatHandlerOptions, ProcessedData, IntelligentImportConfig } from './types.js';
+export type { FormatHandler, FormatHandlerOptions, ProcessedData, IntelligentImportConfig, HandlerRegistry } from './types.js';
 export { CSVHandler } from './handlers/csvHandler.js';
 export { ExcelHandler } from './handlers/excelHandler.js';
 export { PDFHandler } from './handlers/pdfHandler.js';
+export { ImageHandler } from './handlers/imageHandler.js';
+export { FormatHandlerRegistry, globalHandlerRegistry } from './FormatHandlerRegistry.js';
+export type { HandlerRegistration } from './FormatHandlerRegistry.js';
+export type { ImageMetadata, EXIFData, ImageHandlerOptions } from './handlers/imageHandler.js';

package/dist/augmentations/intelligentImport/index.js

@@ -3,7 +3,11 @@
  * Exports main augmentation and types
  */
 export { IntelligentImportAugmentation } from './IntelligentImportAugmentation.js';
+// Format Handlers
 export { CSVHandler } from './handlers/csvHandler.js';
 export { ExcelHandler } from './handlers/excelHandler.js';
 export { PDFHandler } from './handlers/pdfHandler.js';
+export { ImageHandler } from './handlers/imageHandler.js';
+// Format Handler Registry (v5.2.0)
+export { FormatHandlerRegistry, globalHandlerRegistry } from './FormatHandlerRegistry.js';
 //# sourceMappingURL=index.js.map

package/dist/augmentations/intelligentImport/types.d.ts

@@ -129,12 +129,16 @@ export interface IntelligentImportConfig {
     enableExcel: boolean;
     /** Enable PDF handler */
     enablePDF: boolean;
+    /** Enable Image handler (v5.2.0) */
+    enableImage: boolean;
     /** Default options for CSV */
     csvDefaults?: Partial<FormatHandlerOptions>;
     /** Default options for Excel */
     excelDefaults?: Partial<FormatHandlerOptions>;
     /** Default options for PDF */
     pdfDefaults?: Partial<FormatHandlerOptions>;
+    /** Default options for Image (v5.2.0) */
+    imageDefaults?: Partial<FormatHandlerOptions>;
     /** Maximum file size to process (bytes) */
     maxFileSize?: number;
     /** Enable caching of processed data */

package/dist/brainy.d.ts

@@ -1111,7 +1111,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * - Reduced confusion (removed redundant options)
      */
     import(source: Buffer | string | object, options?: {
-        format?: 'excel' | 'pdf' | 'csv' | 'json' | 'markdown' | 'yaml' | 'docx';
+        format?: 'excel' | 'pdf' | 'csv' | 'json' | 'markdown' | 'yaml' | 'docx' | 'image';
         vfsPath?: string;
         groupBy?: 'type' | 'sheet' | 'flat' | 'custom';
         customGrouping?: (entity: any) => string;

package/dist/brainy.js

@@ -141,6 +141,14 @@ export class Brainy {
                 this.registerShutdownHooks();
                 Brainy.shutdownHooksRegisteredGlobally = true;
             }
+            // v5.2.0: Initialize COW (BlobStorage) before VFS
+            // VFS now requires BlobStorage for unified file storage
+            if (typeof this.storage.initializeCOW === 'function') {
+                await this.storage.initializeCOW({
+                    branch: this.config.storage?.branch || 'main',
+                    enableCompression: true
+                });
+            }
             // Mark as initialized BEFORE VFS init (v5.0.1)
             // VFS.init() needs brain to be marked initialized to call brain methods
             this.initialized = true;
@@ -1860,7 +1868,20 @@ export class Brainy {
             }
             const refManager = this.storage.refManager;
             const currentBranch = this.storage.currentBranch || 'main';
-            // Step 1: Copy storage ref (COW layer - instant!)
+            // Step 1: Ensure initial commit exists (required for fork)
+            const currentRef = await refManager.getRef(currentBranch);
+            if (!currentRef) {
+                // Auto-create initial commit if none exists
+                await this.commit({
+                    message: `Initial commit on ${currentBranch}`,
+                    author: options?.author || 'Brainy',
+                    metadata: { timestamp: Date.now() }
+                });
+                if (!this.config.silent) {
+                    console.log(`📝 Auto-created initial commit on ${currentBranch} (required for fork)`);
+                }
+            }
+            // Step 2: Copy storage ref (COW layer - instant!)
             await refManager.copyRef(currentBranch, branchName);
             // Step 2: Create new Brainy instance pointing to fork branch
             const forkConfig = {
@@ -2651,11 +2672,19 @@ export class Brainy {
      * - Reduced confusion (removed redundant options)
      */
     async import(source, options) {
-        // Lazy load ImportCoordinator
-        const { ImportCoordinator } = await import('./import/ImportCoordinator.js');
-        const coordinator = new ImportCoordinator(this);
-        await coordinator.init();
-        return await coordinator.import(source, options);
+        // Execute through augmentation pipeline (v5.2.0: Enables IntelligentImportAugmentation)
+        // If source is an ImportSource object (not a Buffer), spread it so augmentations can access properties
+        const params = typeof source === 'object' && !Buffer.isBuffer(source)
+            ? { ...source, ...options } // Spread ImportSource: { type, data, filename, ...options }
+            : { source, ...options }; // Wrap Buffer/string: { source, ...options }
+        return this.augmentationRegistry.execute('import', params, async () => {
+            // Lazy load ImportCoordinator
+            const { ImportCoordinator } = await import('./import/ImportCoordinator.js');
+            const coordinator = new ImportCoordinator(this);
+            await coordinator.init();
+            // Pass augmentation-modified params (contains _intelligentImport, _extractedData, etc)
+            return await coordinator.import(source, { ...options, ...params });
+        });
     }
     /**
      * Virtual File System API - Knowledge Operating System (v5.0.1+)
@@ -3695,12 +3724,19 @@ export class Brainy {
             const graphIndexSize = await this.graphIndex.size();
             const needsRebuild = metadataStats.totalEntries === 0 ||
                 hnswIndexSize === 0 ||
-                graphIndexSize === 0 ||
-                this.config.disableAutoRebuild === false; // Explicitly enabled
+                graphIndexSize === 0;
             if (!needsRebuild) {
                 // All indexes already populated, no rebuild needed
                 return;
             }
+            // BUG FIX: If disableAutoRebuild is truthy, skip rebuild even if indexes are empty
+            // Indexes will load lazily on first query
+            if (this.config.disableAutoRebuild) {
+                if (!this.config.silent) {
+                    console.log('⚡ Indexes empty but auto-rebuild disabled - using lazy loading');
+                }
+                return;
+            }
             // Small dataset: Rebuild all indexes for best performance
             if (totalCount < AUTO_REBUILD_THRESHOLD || this.config.disableAutoRebuild === false) {
                 if (!this.config.silent) {

package/dist/import/FormatDetector.d.ts

@@ -2,13 +2,14 @@
  * Format Detector
  *
  * Unified format detection for all import types using:
+ * - MIME type detection (via MimeTypeDetector service)
  * - Magic byte signatures (PDF, Excel, images)
- * - File extensions
+ * - File extensions (via MimeTypeDetector)
  * - Content analysis (JSON, Markdown, CSV)
  *
  * NO MOCKS - Production-ready implementation
  */
-export type SupportedFormat = 'excel' | 'pdf' | 'csv' | 'json' | 'markdown' | 'yaml' | 'docx';
+export type SupportedFormat = 'excel' | 'pdf' | 'csv' | 'json' | 'markdown' | 'yaml' | 'docx' | 'image';
 export interface DetectionResult {
     format: SupportedFormat;
     confidence: number;
@@ -24,8 +25,16 @@ export declare class FormatDetector {
     detectFromBuffer(buffer: Buffer): DetectionResult | null;
     /**
      * Detect format from file path
+     *
+     * Uses MimeTypeDetector (2000+ types) and maps to SupportedFormat
      */
     detectFromPath(path: string): DetectionResult | null;
+    /**
+     * Map MIME type to SupportedFormat
+     *
+     * Supports all variations of Excel, PDF, CSV, JSON, Markdown, YAML, DOCX
+     */
+    private mimeTypeToFormat;
     /**
      * Detect format from string content
      */

package/dist/import/FormatDetector.js

@@ -2,12 +2,14 @@
  * Format Detector
  *
  * Unified format detection for all import types using:
+ * - MIME type detection (via MimeTypeDetector service)
  * - Magic byte signatures (PDF, Excel, images)
- * - File extensions
+ * - File extensions (via MimeTypeDetector)
  * - Content analysis (JSON, Markdown, CSV)
  *
  * NO MOCKS - Production-ready implementation
  */
+import { mimeDetector } from '../vfs/MimeTypeDetector.js';
 /**
  * FormatDetector - Detect file format from various inputs
  */
@@ -28,32 +30,68 @@ export class FormatDetector {
     }
     /**
      * Detect format from file path
+     *
+     * Uses MimeTypeDetector (2000+ types) and maps to SupportedFormat
      */
     detectFromPath(path) {
-        const ext = this.getExtension(path).toLowerCase();
-        const extensionMap = {
-            '.xlsx': 'excel',
-            '.xls': 'excel',
-            '.pdf': 'pdf',
-            '.csv': 'csv',
-            '.json': 'json',
-            '.md': 'markdown',
-            '.markdown': 'markdown',
-            '.yaml': 'yaml',
-            '.yml': 'yaml',
-            '.docx': 'docx',
-            '.doc': 'docx'
-        };
-        const format = extensionMap[ext];
+        // Get MIME type from MimeTypeDetector
+        const mimeType = mimeDetector.detectMimeType(path);
+        // Map MIME type to SupportedFormat
+        const format = this.mimeTypeToFormat(mimeType);
         if (format) {
+            const ext = this.getExtension(path);
             return {
                 format,
                 confidence: 0.9,
-                evidence: [`File extension: ${ext}`]
+                evidence: [`MIME type: ${mimeType}`, `File extension: ${ext}`]
             };
         }
         return null;
     }
+    /**
+     * Map MIME type to SupportedFormat
+     *
+     * Supports all variations of Excel, PDF, CSV, JSON, Markdown, YAML, DOCX
+     */
+    mimeTypeToFormat(mimeType) {
+        // Excel formats (Office Open XML + legacy)
+        if (mimeType === 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' ||
+            mimeType === 'application/vnd.ms-excel' ||
+            mimeType === 'application/vnd.ms-excel.sheet.macroEnabled.12' ||
+            mimeType === 'application/vnd.openxmlformats-officedocument.spreadsheetml.template') {
+            return 'excel';
+        }
+        // PDF
+        if (mimeType === 'application/pdf') {
+            return 'pdf';
+        }
+        // CSV
+        if (mimeType === 'text/csv') {
+            return 'csv';
+        }
+        // JSON
+        if (mimeType === 'application/json') {
+            return 'json';
+        }
+        // Markdown
+        if (mimeType === 'text/markdown' || mimeType === 'text/x-markdown') {
+            return 'markdown';
+        }
+        // YAML
+        if (mimeType === 'text/yaml' || mimeType === 'text/x-yaml' || mimeType === 'application/x-yaml') {
+            return 'yaml';
+        }
+        // Word documents (Office Open XML)
+        if (mimeType === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' ||
+            mimeType === 'application/msword') {
+            return 'docx';
+        }
+        // Images (v5.2.0: ImageHandler support)
+        if (mimeType.startsWith('image/')) {
+            return 'image';
+        }
+        return null;
+    }
     /**
      * Detect format from string content
      */
@@ -132,6 +170,50 @@ export class FormatDetector {
                 };
             }
         }
+        // Image formats (v5.2.0)
+        // JPEG: FF D8 FF
+        if (buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
+            return {
+                format: 'image',
+                confidence: 1.0,
+                evidence: ['JPEG magic bytes: FF D8 FF']
+            };
+        }
+        // PNG: 89 50 4E 47
+        if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47) {
+            return {
+                format: 'image',
+                confidence: 1.0,
+                evidence: ['PNG magic bytes: 89 50 4E 47']
+            };
+        }
+        // GIF: 47 49 46 38
+        if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
+            return {
+                format: 'image',
+                confidence: 1.0,
+                evidence: ['GIF magic bytes: GIF8']
+            };
+        }
+        // BMP: 42 4D
+        if (buffer[0] === 0x42 && buffer[1] === 0x4D) {
+            return {
+                format: 'image',
+                confidence: 1.0,
+                evidence: ['BMP magic bytes: BM']
+            };
+        }
+        // WebP: RIFF....WEBP
+        if (buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 && buffer.length >= 12) {
+            const webpCheck = buffer.toString('utf8', 8, 12);
+            if (webpCheck === 'WEBP') {
+                return {
+                    format: 'image',
+                    confidence: 1.0,
+                    evidence: ['WebP magic bytes: RIFF...WEBP']
+                };
+            }
+        }
         return null;
     }
     /**