@soulcraft/brainy 2.10.1 → 2.12.0

package/dist/neural/types.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Neural API Type Definitions
+ * Comprehensive interfaces for clustering, similarity, and analysis
+ */
+export interface Vector {
+    [index: number]: number;
+    length: number;
+}
+export interface SemanticCluster {
+    id: string;
+    centroid: Vector;
+    members: string[];
+    size: number;
+    confidence: number;
+    label?: string;
+    metadata?: Record<string, any>;
+    cohesion?: number;
+    level?: number;
+}
+export interface DomainCluster extends SemanticCluster {
+    domain: string;
+    domainConfidence: number;
+    crossDomainMembers?: string[];
+}
+export interface TemporalCluster extends SemanticCluster {
+    timeWindow: TimeWindow;
+    trend?: 'increasing' | 'decreasing' | 'stable';
+    temporal: {
+        startTime: Date;
+        endTime: Date;
+        peakTime?: Date;
+        frequency?: number;
+    };
+}
+export interface ExplainableCluster extends SemanticCluster {
+    explanation: {
+        primaryFeatures: string[];
+        commonTerms: string[];
+        reasoning: string;
+        confidence: number;
+    };
+    subClusters?: ExplainableCluster[];
+}
+export interface ConfidentCluster extends SemanticCluster {
+    minConfidence: number;
+    uncertainMembers: string[];
+    certainMembers: string[];
+}
+export interface BaseClusteringOptions {
+    maxClusters?: number;
+    minClusterSize?: number;
+    threshold?: number;
+    cacheResults?: boolean;
+}
+export interface ClusteringOptions extends BaseClusteringOptions {
+    algorithm?: 'auto' | 'hierarchical' | 'kmeans' | 'dbscan' | 'sample' | 'semantic' | 'graph' | 'multimodal';
+    sampleSize?: number;
+    strategy?: 'random' | 'diverse' | 'recent' | 'important';
+    memoryLimit?: string;
+    includeOutliers?: boolean;
+    maxIterations?: number;
+    tolerance?: number;
+}
+export interface DomainClusteringOptions extends BaseClusteringOptions {
+    domainField?: string;
+    crossDomainThreshold?: number;
+    preserveDomainBoundaries?: boolean;
+}
+export interface TemporalClusteringOptions extends BaseClusteringOptions {
+    timeField: string;
+    windows: TimeWindow[];
+    overlapStrategy?: 'merge' | 'separate' | 'hierarchical';
+    trendAnalysis?: boolean;
+}
+export interface StreamClusteringOptions extends BaseClusteringOptions {
+    batchSize?: number;
+    updateInterval?: number;
+    adaptiveThreshold?: boolean;
+    decayFactor?: number;
+}
+export interface SimilarityOptions {
+    detailed?: boolean;
+    metric?: 'cosine' | 'euclidean' | 'manhattan' | 'jaccard';
+    normalized?: boolean;
+}
+export interface SimilarityResult {
+    score: number;
+    confidence: number;
+    explanation?: string;
+    metric?: string;
+}
+export interface NeighborOptions {
+    limit?: number;
+    radius?: number;
+    minSimilarity?: number;
+    includeMetadata?: boolean;
+    sortBy?: 'similarity' | 'importance' | 'recency';
+}
+export interface Neighbor {
+    id: string;
+    similarity: number;
+    data?: any;
+    metadata?: Record<string, any>;
+    distance?: number;
+}
+export interface NeighborsResult {
+    neighbors: Neighbor[];
+    queryId: string;
+    totalFound: number;
+    averageSimilarity: number;
+}
+export interface SemanticHierarchy {
+    self: {
+        id: string;
+        vector?: Vector;
+        metadata?: any;
+    };
+    parent?: {
+        id: string;
+        similarity: number;
+    };
+    children?: Array<{
+        id: string;
+        similarity: number;
+    }>;
+    siblings?: Array<{
+        id: string;
+        similarity: number;
+    }>;
+    level?: number;
+    depth?: number;
+}
+export interface HierarchyOptions {
+    maxDepth?: number;
+    minSimilarity?: number;
+    includeMetadata?: boolean;
+    buildStrategy?: 'similarity' | 'metadata' | 'mixed';
+}
+export interface VisualizationOptions {
+    maxNodes?: number;
+    dimensions?: 2 | 3;
+    algorithm?: 'force' | 'spring' | 'circular' | 'hierarchical';
+    includeEdges?: boolean;
+    clusterColors?: boolean;
+    nodeSize?: 'uniform' | 'importance' | 'connections';
+}
+export interface VisualizationNode {
+    id: string;
+    x: number;
+    y: number;
+    z?: number;
+    cluster?: string;
+    size?: number;
+    color?: string;
+    metadata?: Record<string, any>;
+}
+export interface VisualizationEdge {
+    source: string;
+    target: string;
+    weight: number;
+    color?: string;
+    type?: string;
+}
+export interface VisualizationResult {
+    nodes: VisualizationNode[];
+    edges: VisualizationEdge[];
+    clusters?: Array<{
+        id: string;
+        color: string;
+        size: number;
+        label?: string;
+    }>;
+    metadata: {
+        algorithm: string;
+        dimensions: number;
+        totalNodes: number;
+        totalEdges: number;
+        generatedAt: Date;
+    };
+}
+export interface TimeWindow {
+    start: Date;
+    end: Date;
+    label?: string;
+    weight?: number;
+}
+export interface ClusterFeedback {
+    clusterId: string;
+    action: 'merge' | 'split' | 'relabel' | 'adjust';
+    parameters?: Record<string, any>;
+    confidence?: number;
+}
+export interface OutlierOptions {
+    threshold?: number;
+    method?: 'isolation' | 'statistical' | 'cluster-based';
+    minNeighbors?: number;
+    includeReasons?: boolean;
+}
+export interface Outlier {
+    id: string;
+    score: number;
+    reasons?: string[];
+    nearestNeighbors?: Neighbor[];
+    metadata?: Record<string, any>;
+}
+export interface PerformanceMetrics {
+    executionTime: number;
+    memoryUsed: number;
+    itemsProcessed: number;
+    cacheHits: number;
+    cacheMisses: number;
+    algorithm: string;
+}
+export interface ClusteringResult<T = SemanticCluster> {
+    clusters: T[];
+    metrics: PerformanceMetrics;
+    metadata: {
+        totalItems: number;
+        clustersFound: number;
+        averageClusterSize: number;
+        silhouetteScore?: number;
+        timestamp: Date;
+        semanticTypes?: number;
+        hnswLevel?: number;
+        kValue?: number;
+        hasConverged?: boolean;
+        outlierCount?: number;
+        eps?: number;
+        minPts?: number;
+        averageModularity?: number;
+        fusionMethod?: string;
+        componentAlgorithms?: string[];
+        sampleSize?: number;
+        samplingStrategy?: string;
+    };
+}
+export interface StreamingBatch<T = SemanticCluster> {
+    clusters: T[];
+    batchNumber: number;
+    isComplete: boolean;
+    progress: {
+        processed: number;
+        total: number;
+        percentage: number;
+    };
+    metrics: PerformanceMetrics;
+}
+export declare class NeuralAPIError extends Error {
+    code: string;
+    context?: Record<string, any> | undefined;
+    constructor(message: string, code: string, context?: Record<string, any> | undefined);
+}
+export declare class ClusteringError extends NeuralAPIError {
+    constructor(message: string, context?: Record<string, any>);
+}
+export declare class SimilarityError extends NeuralAPIError {
+    constructor(message: string, context?: Record<string, any>);
+}
+export interface NeuralAPIConfig {
+    cacheSize?: number;
+    defaultAlgorithm?: string;
+    similarityMetric?: 'cosine' | 'euclidean' | 'manhattan';
+    performanceTracking?: boolean;
+    maxMemoryUsage?: string;
+    parallelProcessing?: boolean;
+    streamingBatchSize?: number;
+}

package/dist/neural/types.js

@@ -0,0 +1,24 @@
+/**
+ * Neural API Type Definitions
+ * Comprehensive interfaces for clustering, similarity, and analysis
+ */
+// ===== ERROR TYPES =====
+export class NeuralAPIError extends Error {
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'NeuralAPIError';
+    }
+}
+export class ClusteringError extends NeuralAPIError {
+    constructor(message, context) {
+        super(message, 'CLUSTERING_ERROR', context);
+    }
+}
+export class SimilarityError extends NeuralAPIError {
+    constructor(message, context) {
+        super(message, 'SIMILARITY_ERROR', context);
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/storage/adapters/fileSystemStorage.d.ts

@@ -105,7 +105,7 @@ export declare class FileSystemStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      */
@@ -113,7 +113,7 @@ export declare class FileSystemStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */

package/dist/storage/adapters/fileSystemStorage.js

@@ -433,7 +433,7 @@ export class FileSystemStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const filePath = path.join(this.nounMetadataDir, `${id}.json`);
         await fs.promises.writeFile(filePath, JSON.stringify(metadata, null, 2));
@@ -458,7 +458,7 @@ export class FileSystemStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const filePath = path.join(this.verbMetadataDir, `${id}.json`);
         await fs.promises.writeFile(filePath, JSON.stringify(metadata, null, 2));

package/dist/storage/adapters/memoryStorage.d.ts

@@ -131,17 +131,17 @@ export declare class MemoryStorage extends BaseStorage {
      */
     getMetadataBatch(ids: string[]): Promise<Map<string, any>>;
     /**
-     * Save noun metadata to storage
+     * Save noun metadata to storage (internal implementation)
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      */
     getNounMetadata(id: string): Promise<any | null>;
     /**
-     * Save verb metadata to storage
+     * Save verb metadata to storage (internal implementation)
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */

package/dist/storage/adapters/memoryStorage.js

@@ -424,9 +424,9 @@ export class MemoryStorage extends BaseStorage {
         return results;
     }
     /**
-     * Save noun metadata to storage
+     * Save noun metadata to storage (internal implementation)
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         this.nounMetadata.set(id, JSON.parse(JSON.stringify(metadata)));
     }
     /**
@@ -440,9 +440,9 @@ export class MemoryStorage extends BaseStorage {
         return JSON.parse(JSON.stringify(metadata));
     }
     /**
-     * Save verb metadata to storage
+     * Save verb metadata to storage (internal implementation)
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         this.verbMetadata.set(id, JSON.parse(JSON.stringify(metadata)));
     }
     /**

package/dist/storage/adapters/opfsStorage.d.ts

@@ -144,7 +144,7 @@ export declare class OPFSStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */
@@ -152,7 +152,7 @@ export declare class OPFSStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      */

package/dist/storage/adapters/opfsStorage.js

@@ -540,7 +540,7 @@ export class OPFSStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const fileName = `${id}.json`;
         const fileHandle = await this.verbMetadataDir.getFileHandle(fileName, { create: true });
@@ -570,7 +570,7 @@ export class OPFSStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         const fileName = `${id}.json`;
         const fileHandle = await this.nounMetadataDir.getFileHandle(fileName, { create: true });

package/dist/storage/adapters/s3CompatibleStorage.d.ts

@@ -328,7 +328,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    protected saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      */
@@ -336,7 +336,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    protected saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get multiple metadata objects in batches (CRITICAL: Prevents socket exhaustion)
      * This is the solution to the metadata reading socket exhaustion during initialization

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -1450,7 +1450,7 @@ export class S3CompatibleStorage extends BaseStorage {
     /**
      * Save verb metadata to storage
      */
-    async saveVerbMetadata(id, metadata) {
+    async saveVerbMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         try {
             // Import the PutObjectCommand only when needed
@@ -1523,7 +1523,7 @@ export class S3CompatibleStorage extends BaseStorage {
     /**
      * Save noun metadata to storage
      */
-    async saveNounMetadata(id, metadata) {
+    async saveNounMetadata_internal(id, metadata) {
         await this.ensureInitialized();
         try {
             // Import the PutObjectCommand only when needed

package/dist/storage/baseStorage.d.ts

@@ -172,7 +172,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Save noun metadata to storage
      * This method should be implemented by each specific adapter
      */
-    abstract saveNounMetadata(id: string, metadata: any): Promise<void>;
+    saveNounMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Internal method for saving noun metadata
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract saveNounMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get noun metadata from storage
      * This method should be implemented by each specific adapter
@@ -182,7 +187,12 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Save verb metadata to storage
      * This method should be implemented by each specific adapter
      */
-    abstract saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    saveVerbMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Internal method for saving verb metadata
+     * This method should be implemented by each specific adapter
+     */
+    protected abstract saveVerbMetadata_internal(id: string, metadata: any): Promise<void>;
     /**
      * Get verb metadata from storage
      * This method should be implemented by each specific adapter

package/dist/storage/baseStorage.js

@@ -3,6 +3,7 @@
  * Provides common functionality for all storage adapters
  */
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
+import { validateNounType, validateVerbType } from '../utils/typeValidation.js';
 // Common directory/prefix names
 // Option A: Entity-Based Directory Structure
 export const ENTITIES_DIR = 'entities';
@@ -71,6 +72,11 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async saveNoun(noun) {
         await this.ensureInitialized();
+        // Validate noun type before saving - storage boundary protection
+        const metadata = await this.getNounMetadata(noun.id);
+        if (metadata?.noun) {
+            validateNounType(metadata.noun);
+        }
         return this.saveNoun_internal(noun);
     }
     /**
@@ -101,6 +107,10 @@ export class BaseStorage extends BaseStorageAdapter {
      */
     async saveVerb(verb) {
         await this.ensureInitialized();
+        // Validate verb type before saving - storage boundary protection
+        if (verb.verb) {
+            validateVerbType(verb.verb);
+        }
         // Extract the lightweight HNSWVerb data
         const hnswVerb = {
             id: verb.id,
@@ -488,6 +498,28 @@ export class BaseStorage extends BaseStorageAdapter {
         await this.ensureInitialized();
         return this.deleteVerb_internal(id);
     }
+    /**
+     * Save noun metadata to storage
+     * This method should be implemented by each specific adapter
+     */
+    async saveNounMetadata(id, metadata) {
+        // Validate noun type in metadata - storage boundary protection
+        if (metadata?.noun) {
+            validateNounType(metadata.noun);
+        }
+        return this.saveNounMetadata_internal(id, metadata);
+    }
+    /**
+     * Save verb metadata to storage
+     * This method should be implemented by each specific adapter
+     */
+    async saveVerbMetadata(id, metadata) {
+        // Validate verb type in metadata - storage boundary protection
+        if (metadata?.verb) {
+            validateVerbType(metadata.verb);
+        }
+        return this.saveVerbMetadata_internal(id, metadata);
+    }
     /**
      * Helper method to convert a Map to a plain object for serialization
      */

package/dist/types/brainyDataInterface.d.ts

@@ -18,14 +18,11 @@ export interface BrainyDataInterface<T = unknown> {
     /**
      * Add a noun (entity with vector and metadata) to the database
      * @param data Text string or vector representation (will auto-embed strings)
+     * @param nounType Required noun type (one of 31 types)
      * @param metadata Optional metadata to associate with the noun
-     * @param options Optional configuration including custom ID
      * @returns The ID of the added noun
      */
-    addNoun(data: string | Vector, metadata?: T, options?: {
-        id?: string;
-        [key: string]: any;
-    }): Promise<string>;
+    addNoun(data: string | Vector, nounType: string, metadata?: T): Promise<string>;
     /**
      * Search for text in the database
      * @param text The text to search for