@soulcraft/brainy 3.0.0 → 3.1.0

package/dist/neural/types.d.ts

@@ -0,0 +1,287 @@
+/**
+ * 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 ClusterEdge {
+    id: string;
+    source: string;
+    target: string;
+    type: string;
+    weight?: number;
+    isInterCluster: boolean;
+    sourceCluster?: string;
+    targetCluster?: string;
+}
+export interface EnhancedSemanticCluster extends SemanticCluster {
+    intraClusterEdges: ClusterEdge[];
+    interClusterEdges: ClusterEdge[];
+    relationshipSummary: {
+        totalEdges: number;
+        intraClusterEdges: number;
+        interClusterEdges: number;
+        edgeTypes: Record<string, 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/shared/default-augmentations.d.ts

@@ -4,14 +4,14 @@
  * 🧠⚛️ Pre-installed augmentations that come with every Brainy installation
  * These are the core "sensory organs" of the atomic age brain-in-jar system
  */
-import { BrainyDataInterface } from '../types/brainyDataInterface.js';
+import { BrainyInterface } from '../types/brainyDataInterface.js';
 /**
  * Default augmentations that ship with Brainy
  * These are automatically registered on startup
  */
 export declare class DefaultAugmentationRegistry {
     private brainy;
-    constructor(brainy: BrainyDataInterface);
+    constructor(brainy: BrainyInterface);
     /**
      * Initialize all default augmentations
      * Called during Brainy startup to register core functionality
@@ -38,4 +38,4 @@ export declare class DefaultAugmentationRegistry {
 /**
  * Helper function to initialize default augmentations for any Brainy instance
  */
-export declare function initializeDefaultAugmentations(brainy: BrainyDataInterface): Promise<DefaultAugmentationRegistry>;
+export declare function initializeDefaultAugmentations(brainy: BrainyInterface): Promise<DefaultAugmentationRegistry>;

package/dist/shared/default-augmentations.js

@@ -30,7 +30,7 @@ export class DefaultAugmentationRegistry {
         try {
             // Import the Neural Import augmentation
             const { NeuralImportAugmentation } = await import('../augmentations/neuralImport.js');
-            // Note: The actual registration is commented out since BrainyData doesn't have addAugmentation method yet
+            // Note: The actual registration is commented out since Brainy doesn't have addAugmentation method yet
             // This would create instance with default configuration
             /*
             const neuralImport = new NeuralImportAugmentation(this.brainy as any, {
@@ -48,7 +48,7 @@ export class DefaultAugmentationRegistry {
               })
             }
             */
-            console.log('🧠⚛️ Cortex module loaded (awaiting BrainyData augmentation support)');
+            console.log('🧠⚛️ Cortex module loaded (awaiting Brainy augmentation support)');
         }
         catch (error) {
             console.error('❌ Failed to register Cortex:', error instanceof Error ? error.message : String(error));
@@ -61,11 +61,11 @@ export class DefaultAugmentationRegistry {
     async checkCortexHealth() {
         try {
             // Check if Cortex is registered as an augmentation
-            // Note: hasAugmentation method doesn't exist yet in BrainyData
+            // Note: hasAugmentation method doesn't exist yet in Brainy
             const hasCortex = false; // this.brainy.hasAugmentation && this.brainy.hasAugmentation('SENSE', 'cortex')
             return {
                 available: hasCortex || false,
-                status: hasCortex ? 'active' : 'not registered (awaiting BrainyData support)',
+                status: hasCortex ? 'active' : 'not registered (awaiting Brainy support)',
                 version: '1.0.0'
             };
         }
@@ -82,7 +82,7 @@ export class DefaultAugmentationRegistry {
     async reinstallCortex() {
         try {
             // Remove existing if present
-            // Note: removeAugmentation method doesn't exist yet in BrainyData
+            // Note: removeAugmentation method doesn't exist yet in Brainy
             /*
             if (this.brainy.removeAugmentation) {
               try {

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

@@ -75,6 +75,48 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
         hasMore: boolean;
         nextCursor?: string;
     }>;
+    /**
+     * Get nouns with pagination (internal implementation)
+     * This method should be implemented by storage adapters to support efficient pagination
+     * @param options Pagination options
+     * @returns Promise that resolves to a paginated result of nouns
+     */
+    getNounsWithPagination?(options: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            nounType?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: any[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /**
+     * Get verbs with pagination (internal implementation)
+     * This method should be implemented by storage adapters to support efficient pagination
+     * @param options Pagination options
+     * @returns Promise that resolves to a paginated result of verbs
+     */
+    getVerbsWithPagination?(options: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            verbType?: string | string[];
+            sourceId?: string | string[];
+            targetId?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: any[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     protected statisticsCache: StatisticsData | null;
     protected statisticsBatchUpdateTimerId: NodeJS.Timeout | null;
     protected statisticsModified: boolean;

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
      */
@@ -189,6 +189,26 @@ export declare class FileSystemStorage extends BaseStorage {
      * Get verbs by type
      */
     protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    /**
+     * Get verbs with pagination
+     * This method reads verb files from the filesystem and returns them with pagination
+     */
+    getVerbsWithPagination(options?: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            verbType?: string | string[];
+            sourceId?: string | string[];
+            targetId?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: GraphVerb[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Delete a verb from storage
      */
@@ -227,5 +247,9 @@ export declare class FileSystemStorage extends BaseStorage {
      * Get statistics with backward compatibility (dual read)
      */
     private getStatisticsWithBackwardCompat;
+    /**
+     * Merge statistics from multiple sources
+     */
+    private mergeStatistics;
 }
 export {};