@soulcraft/brainy 5.7.4 → 5.7.6

package/README.md

@@ -135,6 +135,50 @@ const results = await brain.find({
 
 ---
 
+## Entity Extraction (NEW in v5.7.6)
+
+**Extract entities from text with AI-powered classification:**
+
+```javascript
+import { Brainy, NounType } from '@soulcraft/brainy'
+
+const brain = new Brainy()
+await brain.init()
+
+// Extract all entities
+const entities = await brain.extractEntities('John Smith founded Acme Corp in New York')
+// Returns:
+// [
+//   { text: 'John Smith', type: NounType.Person, confidence: 0.95 },
+//   { text: 'Acme Corp', type: NounType.Organization, confidence: 0.92 },
+//   { text: 'New York', type: NounType.Location, confidence: 0.88 }
+// ]
+
+// Extract with filters
+const people = await brain.extractEntities(resume, {
+  types: [NounType.Person],
+  confidence: 0.8
+})
+
+// Advanced: Direct access to extractors
+import { SmartExtractor } from '@soulcraft/brainy'
+
+const extractor = new SmartExtractor(brain, { minConfidence: 0.7 })
+const result = await extractor.extract('CEO', {
+  formatContext: { format: 'excel', columnHeader: 'Title' }
+})
+```
+
+**Features:**
+- 🎯 **4-Signal Ensemble** - ExactMatch (40%) + Embedding (35%) + Pattern (20%) + Context (5%)
+- 📊 **Format Intelligence** - Adapts to Excel, CSV, PDF, YAML, DOCX, JSON, Markdown
+- ⚡ **Fast** - ~15-20ms per extraction with LRU caching
+- 🌍 **42 Types** - Person, Organization, Location, Document, and 38 more
+
+**→ [Neural Extraction Guide](docs/neural-extraction.md)** | **[Import Preview Mode](docs/neural-extraction.md#import-preview-mode)**
+
+---
+
 ## From Prototype to Planet Scale
 
 **The same API. Zero rewrites. Any scale.**

package/dist/brainy.d.ts

@@ -1075,6 +1075,35 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
         includeVectors?: boolean;
         neuralMatching?: boolean;
     }): Promise<ExtractedEntity[]>;
+    /**
+     * Extract entities from text (alias for extract())
+     * v5.7.6: Added for API clarity and Workshop team request
+     *
+     * Uses NeuralEntityExtractor with SmartExtractor ensemble (4-signal architecture):
+     * - ExactMatch (40%) - Dictionary lookups
+     * - Embedding (35%) - Semantic similarity
+     * - Pattern (20%) - Regex patterns
+     * - Context (5%) - Contextual hints
+     *
+     * @param text - Text to extract entities from
+     * @param options - Extraction options
+     * @returns Array of extracted entities with types and confidence scores
+     *
+     * @example
+     * ```typescript
+     * const entities = await brain.extractEntities('John Smith founded Acme Corp', {
+     *   confidence: 0.7,
+     *   types: [NounType.Person, NounType.Organization],
+     *   neuralMatching: true
+     * })
+     * ```
+     */
+    extractEntities(text: string, options?: {
+        types?: NounType[];
+        confidence?: number;
+        includeVectors?: boolean;
+        neuralMatching?: boolean;
+    }): Promise<ExtractedEntity[]>;
     /**
      * Extract concepts from text
      *

package/dist/brainy.js

@@ -2742,6 +2742,32 @@ export class Brainy {
         }
         return await this._extractor.extract(text, options);
     }
+    /**
+     * Extract entities from text (alias for extract())
+     * v5.7.6: Added for API clarity and Workshop team request
+     *
+     * Uses NeuralEntityExtractor with SmartExtractor ensemble (4-signal architecture):
+     * - ExactMatch (40%) - Dictionary lookups
+     * - Embedding (35%) - Semantic similarity
+     * - Pattern (20%) - Regex patterns
+     * - Context (5%) - Contextual hints
+     *
+     * @param text - Text to extract entities from
+     * @param options - Extraction options
+     * @returns Array of extracted entities with types and confidence scores
+     *
+     * @example
+     * ```typescript
+     * const entities = await brain.extractEntities('John Smith founded Acme Corp', {
+     *   confidence: 0.7,
+     *   types: [NounType.Person, NounType.Organization],
+     *   neuralMatching: true
+     * })
+     * ```
+     */
+    async extractEntities(text, options) {
+        return this.extract(text, options);
+    }
     /**
      * Extract concepts from text
      *

package/dist/index.d.ts

@@ -15,6 +15,12 @@ export { PresetName, ModelPrecision, StorageOption, FeatureSet, DistributedRole,
 export { Cortex, cortex } from './cortex.js';
 export { NeuralImport } from './cortex/neuralImport.js';
 export type { NeuralAnalysisResult, DetectedEntity, DetectedRelationship, NeuralInsight, NeuralImportOptions } from './cortex/neuralImport.js';
+export { NeuralEntityExtractor } from './neural/entityExtractor.js';
+export { SmartExtractor } from './neural/SmartExtractor.js';
+export { SmartRelationshipExtractor } from './neural/SmartRelationshipExtractor.js';
+export type { ExtractedEntity } from './neural/entityExtractor.js';
+export type { ExtractionResult, SmartExtractorOptions, FormatContext } from './neural/SmartExtractor.js';
+export type { RelationshipExtractionResult, SmartRelationshipExtractorOptions } from './neural/SmartRelationshipExtractor.js';
 import { euclideanDistance, cosineDistance, manhattanDistance, dotProductDistance } from './utils/index.js';
 export { euclideanDistance, cosineDistance, manhattanDistance, dotProductDistance };
 export { getBrainyVersion } from './utils/version.js';

package/dist/index.js

@@ -31,6 +31,10 @@ getPreset, isValidPreset, getPresetsByCategory, getAllPresetNames, getPresetDesc
 export { Cortex, cortex } from './cortex.js';
 // Export Neural Import (AI data understanding)
 export { NeuralImport } from './cortex/neuralImport.js';
+// Export Neural Entity Extraction (v5.7.6 - Workshop request)
+export { NeuralEntityExtractor } from './neural/entityExtractor.js';
+export { SmartExtractor } from './neural/SmartExtractor.js';
+export { SmartRelationshipExtractor } from './neural/SmartRelationshipExtractor.js';
 // Import Manager removed - use brain.import() instead (available on all Brainy instances)
 // Augmentation types are already exported later in the file
 // Export distance functions for convenience

package/dist/storage/baseStorage.js

@@ -238,6 +238,11 @@ export class BaseStorage extends BaseStorageAdapter {
                     if (Buffer.isBuffer(data)) {
                         return data;
                     }
+                    // v5.7.5: Unwrap binary data stored as {_binary: true, data: "base64..."}
+                    // Fixes "Blob integrity check failed" - hash must be calculated on original content
+                    if (data._binary && typeof data.data === 'string') {
+                        return Buffer.from(data.data, 'base64');
+                    }
                     return Buffer.from(JSON.stringify(data));
                 }
                 catch (error) {

package/dist/storage/cow/BlobStorage.d.ts

@@ -84,6 +84,7 @@ export declare class BlobStorage {
     private stats;
     private zstdCompress?;
     private zstdDecompress?;
+    private compressionReady;
     private readonly CACHE_MAX_SIZE;
     private readonly MULTIPART_THRESHOLD;
     private readonly COMPRESSION_THRESHOLD;
@@ -96,6 +97,11 @@ export declare class BlobStorage {
      * (Avoids loading if not needed)
      */
     private initCompression;
+    /**
+     * v5.7.5: Ensure compression is ready before write operations
+     * Fixes race condition where write happens before async compression init completes
+     */
+    private ensureCompressionReady;
     /**
      * Compute SHA-256 hash of data
      *

package/dist/storage/cow/BlobStorage.js

@@ -29,6 +29,7 @@ import { NULL_HASH, isNullHash } from './constants.js';
  */
 export class BlobStorage {
     constructor(adapter, options) {
+        this.compressionReady = false;
         // Configuration
         this.CACHE_MAX_SIZE = 100 * 1024 * 1024; // 100MB default
         this.MULTIPART_THRESHOLD = 5 * 1024 * 1024; // 5MB
@@ -74,6 +75,16 @@ export class BlobStorage {
             this.zstdDecompress = undefined;
         }
     }
+    /**
+     * v5.7.5: Ensure compression is ready before write operations
+     * Fixes race condition where write happens before async compression init completes
+     */
+    async ensureCompressionReady() {
+        if (this.compressionReady)
+            return;
+        await this.initCompression();
+        this.compressionReady = true;
+    }
     /**
      * Compute SHA-256 hash of data
      *
@@ -107,6 +118,9 @@ export class BlobStorage {
             this.stats.dedupSavings += data.length;
             return hash;
         }
+        // v5.7.5: Ensure compression is initialized before writing
+        // Fixes race condition where write happens before async init completes
+        await this.ensureCompressionReady();
         // Determine compression strategy
         const compression = this.selectCompression(data, options);
         // Compress if needed
@@ -117,11 +131,14 @@ export class BlobStorage {
             compressedSize = finalData.length;
         }
         // Create metadata
+        // v5.7.5: Store ACTUAL compression state, not intended
+        // Prevents corruption if compression failed to initialize
+        const actualCompression = finalData === data ? 'none' : compression;
         const metadata = {
             hash,
             size: data.length,
             compressedSize,
-            compression,
+            compression: actualCompression,
             type: options.type || 'blob', // CRITICAL FIX: Use 'blob' default to match storage prefix
             createdAt: Date.now(),
             refCount: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.7.4",
+  "version": "5.7.6",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -39,6 +39,18 @@
     "./universal": {
       "import": "./dist/universal/index.js",
       "types": "./dist/universal/index.d.ts"
+    },
+    "./neural/entityExtractor": {
+      "import": "./dist/neural/entityExtractor.js",
+      "types": "./dist/neural/entityExtractor.d.ts"
+    },
+    "./neural/SmartExtractor": {
+      "import": "./dist/neural/SmartExtractor.js",
+      "types": "./dist/neural/SmartExtractor.d.ts"
+    },
+    "./neural/SmartRelationshipExtractor": {
+      "import": "./dist/neural/SmartRelationshipExtractor.js",
+      "types": "./dist/neural/SmartRelationshipExtractor.d.ts"
     }
   },
   "browser": {