@soulcraft/brainy 0.9.5

package/dist/pipeline.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Unified Pipeline
+ *
+ * This module combines the functionality of the primary augmentation pipeline and the streamlined pipeline
+ * into a single, unified pipeline system. It provides both the registry functionality of the primary pipeline
+ * and the simplified execution API of the streamlined pipeline.
+ */
+import { IAugmentation, AugmentationType, AugmentationResponse, IWebSocketSupport, BrainyAugmentations } from './types/augmentations.js';
+import { IPipeline } from './types/pipelineTypes.js';
+/**
+ * Execution mode for the pipeline
+ */
+export declare enum ExecutionMode {
+    SEQUENTIAL = "sequential",
+    PARALLEL = "parallel",
+    FIRST_SUCCESS = "firstSuccess",
+    FIRST_RESULT = "firstResult",
+    THREADED = "threaded"
+}
+/**
+ * Options for pipeline execution
+ */
+export interface PipelineOptions {
+    mode?: ExecutionMode;
+    timeout?: number;
+    stopOnError?: boolean;
+    forceThreading?: boolean;
+    disableThreading?: boolean;
+}
+/**
+ * Result of a pipeline execution
+ */
+export interface PipelineResult<T> {
+    results: AugmentationResponse<T>[];
+    errors: Error[];
+    successful: AugmentationResponse<T>[];
+}
+/**
+ * Pipeline class
+ *
+ * Manages multiple augmentations of each type and provides methods to execute them.
+ * Implements the IPipeline interface to avoid circular dependencies.
+ */
+export declare class Pipeline implements IPipeline {
+    private registry;
+    /**
+     * Register an augmentation with the pipeline
+     *
+     * @param augmentation The augmentation to register
+     * @returns The pipeline instance for chaining
+     */
+    register<T extends IAugmentation>(augmentation: T): Pipeline;
+    /**
+     * Unregister an augmentation from the pipeline
+     *
+     * @param augmentationName The name of the augmentation to unregister
+     * @returns The pipeline instance for chaining
+     */
+    unregister(augmentationName: string): Pipeline;
+    /**
+     * Initialize all registered augmentations
+     *
+     * @returns A promise that resolves when all augmentations are initialized
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shut down all registered augmentations
+     *
+     * @returns A promise that resolves when all augmentations are shut down
+     */
+    shutDown(): Promise<void>;
+    /**
+     * Get all registered augmentations
+     *
+     * @returns An array of all registered augmentations
+     */
+    getAllAugmentations(): IAugmentation[];
+    /**
+     * Get all augmentations of a specific type
+     *
+     * @param type The type of augmentation to get
+     * @returns An array of all augmentations of the specified type
+     */
+    getAugmentationsByType(type: AugmentationType): IAugmentation[];
+    /**
+     * Get all available augmentation types
+     *
+     * @returns An array of all augmentation types that have at least one registered augmentation
+     */
+    getAvailableAugmentationTypes(): AugmentationType[];
+    /**
+     * Get all WebSocket-supporting augmentations
+     *
+     * @returns An array of all augmentations that support WebSocket connections
+     */
+    getWebSocketAugmentations(): IWebSocketSupport[];
+    /**
+     * Check if an augmentation is of a specific type
+     *
+     * @param augmentation The augmentation to check
+     * @param methods The methods that should be present on the augmentation
+     * @returns True if the augmentation is of the specified type
+     */
+    private isAugmentationType;
+    /**
+     * Determines if threading should be used based on options and environment
+     *
+     * @param options The pipeline options
+     * @returns True if threading should be used, false otherwise
+     */
+    private shouldUseThreading;
+    /**
+     * Executes a method on multiple augmentations using the specified execution mode
+     *
+     * @param augmentations The augmentations to execute the method on
+     * @param method The method to execute
+     * @param args The arguments to pass to the method
+     * @param options Options for the execution
+     * @returns A promise that resolves with the results
+     */
+    execute<T>(augmentations: IAugmentation[], method: string, args?: any[], options?: PipelineOptions): Promise<PipelineResult<T>>;
+    /**
+     * Executes a method on augmentations of a specific type
+     *
+     * @param type The type of augmentations to execute the method on
+     * @param method The method to execute
+     * @param args The arguments to pass to the method
+     * @param options Options for the execution
+     * @returns A promise that resolves with the results
+     */
+    executeByType<T>(type: AugmentationType, method: string, args?: any[], options?: PipelineOptions): Promise<PipelineResult<T>>;
+    /**
+     * Executes a method on a single augmentation with automatic error handling
+     *
+     * @param augmentation The augmentation to execute the method on
+     * @param method The method to execute
+     * @param args The arguments to pass to the method
+     * @returns A promise that resolves with the result
+     */
+    executeSingle<T>(augmentation: IAugmentation, method: string, ...args: any[]): Promise<AugmentationResponse<T>>;
+    /**
+     * Process static data through a pipeline of augmentations
+     *
+     * @param data The data to process
+     * @param pipeline An array of processing steps, each with an augmentation, method, and optional args transformer
+     * @param options Options for the execution
+     * @returns A promise that resolves with the final result
+     */
+    processStaticData<T, R = any>(data: T, pipeline: Array<{
+        augmentation: IAugmentation;
+        method: string;
+        transformArgs?: (data: any, prevResult?: any) => any[];
+    }>, options?: PipelineOptions): Promise<AugmentationResponse<R>>;
+    /**
+     * Process streaming data through a pipeline of augmentations
+     *
+     * @param source The source augmentation that provides the data stream
+     * @param sourceMethod The method on the source augmentation that provides the data stream
+     * @param sourceArgs The arguments to pass to the source method
+     * @param pipeline An array of processing steps, each with an augmentation, method, and optional args transformer
+     * @param callback Function to call with the results of processing each data item
+     * @param options Options for the execution
+     * @returns A promise that resolves when the pipeline is set up
+     */
+    processStreamingData<T>(source: IAugmentation, sourceMethod: string, sourceArgs: any[], pipeline: Array<{
+        augmentation: IAugmentation;
+        method: string;
+        transformArgs?: (data: any, prevResult?: any) => any[];
+    }>, callback: (result: AugmentationResponse<T>) => void, options?: PipelineOptions): Promise<void>;
+    /**
+     * Create a reusable pipeline for processing data
+     *
+     * @param pipeline An array of processing steps
+     * @param options Options for the execution
+     * @returns A function that processes data through the pipeline
+     */
+    createPipeline<T, R>(pipeline: Array<{
+        augmentation: IAugmentation;
+        method: string;
+        transformArgs?: (data: any, prevResult?: any) => any[];
+    }>, options?: PipelineOptions): (data: T) => Promise<AugmentationResponse<R>>;
+    /**
+     * Create a reusable streaming pipeline
+     *
+     * @param source The source augmentation
+     * @param sourceMethod The method on the source augmentation
+     * @param pipeline An array of processing steps
+     * @param options Options for the execution
+     * @returns A function that sets up the streaming pipeline
+     */
+    createStreamingPipeline<T, R>(source: IAugmentation, sourceMethod: string, pipeline: Array<{
+        augmentation: IAugmentation;
+        method: string;
+        transformArgs?: (data: any, prevResult?: any) => any[];
+    }>, options?: PipelineOptions): (sourceArgs: any[], callback: (result: AugmentationResponse<R>) => void) => Promise<void>;
+    /**
+     * Execute a sense pipeline (legacy method)
+     */
+    executeSensePipeline<M extends keyof BrainyAugmentations.ISenseAugmentation & string, R extends BrainyAugmentations.ISenseAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.ISenseAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.ISenseAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+    /**
+     * Execute a conduit pipeline (legacy method)
+     */
+    executeConduitPipeline<M extends keyof BrainyAugmentations.IConduitAugmentation & string, R extends BrainyAugmentations.IConduitAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.IConduitAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.IConduitAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+    /**
+     * Execute a cognition pipeline (legacy method)
+     */
+    executeCognitionPipeline<M extends keyof BrainyAugmentations.ICognitionAugmentation & string, R extends BrainyAugmentations.ICognitionAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.ICognitionAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.ICognitionAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+    /**
+     * Execute a memory pipeline (legacy method)
+     */
+    executeMemoryPipeline<M extends keyof BrainyAugmentations.IMemoryAugmentation & string, R extends BrainyAugmentations.IMemoryAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.IMemoryAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.IMemoryAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+    /**
+     * Execute a perception pipeline (legacy method)
+     */
+    executePerceptionPipeline<M extends keyof BrainyAugmentations.IPerceptionAugmentation & string, R extends BrainyAugmentations.IPerceptionAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.IPerceptionAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.IPerceptionAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+    /**
+     * Execute a dialog pipeline (legacy method)
+     */
+    executeDialogPipeline<M extends keyof BrainyAugmentations.IDialogAugmentation & string, R extends BrainyAugmentations.IDialogAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.IDialogAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.IDialogAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+    /**
+     * Execute an activation pipeline (legacy method)
+     */
+    executeActivationPipeline<M extends keyof BrainyAugmentations.IActivationAugmentation & string, R extends BrainyAugmentations.IActivationAugmentation[M] extends (...args: any[]) => AugmentationResponse<infer U> ? U : never>(method: M & (BrainyAugmentations.IActivationAugmentation[M] extends (...args: any[]) => any ? M : never), args: Parameters<Extract<BrainyAugmentations.IActivationAugmentation[M], (...args: any[]) => any>>, options?: PipelineOptions): Promise<Promise<{
+        success: boolean;
+        data: R;
+        error?: string;
+    }>[]>;
+}
+export declare const pipeline: Pipeline;
+export declare const augmentationPipeline: Pipeline;
+export declare const executeStreamlined: <T>(augmentations: IAugmentation[], method: string, args?: any[], options?: PipelineOptions) => Promise<PipelineResult<T>>;
+export declare const executeByType: <T>(type: AugmentationType, method: string, args?: any[], options?: PipelineOptions) => Promise<PipelineResult<T>>;
+export declare const executeSingle: <T>(augmentation: IAugmentation, method: string, ...args: any[]) => Promise<AugmentationResponse<T>>;
+export declare const processStaticData: <T, R = any>(data: T, pipelineSteps: Array<{
+    augmentation: IAugmentation;
+    method: string;
+    transformArgs?: (data: any, prevResult?: any) => any[];
+}>, options?: PipelineOptions) => Promise<AugmentationResponse<R>>;
+export declare const processStreamingData: <T>(source: IAugmentation, sourceMethod: string, sourceArgs: any[], pipelineSteps: Array<{
+    augmentation: IAugmentation;
+    method: string;
+    transformArgs?: (data: any, prevResult?: any) => any[];
+}>, callback: (result: AugmentationResponse<T>) => void, options?: PipelineOptions) => Promise<void>;
+export declare const createPipeline: <T, R>(pipelineSteps: Array<{
+    augmentation: IAugmentation;
+    method: string;
+    transformArgs?: (data: any, prevResult?: any) => any[];
+}>, options?: PipelineOptions) => (data: T) => Promise<AugmentationResponse<R>>;
+export declare const createStreamingPipeline: <T, R>(source: IAugmentation, sourceMethod: string, pipelineSteps: Array<{
+    augmentation: IAugmentation;
+    method: string;
+    transformArgs?: (data: any, prevResult?: any) => any[];
+}>, options?: PipelineOptions) => (sourceArgs: any[], callback: (result: AugmentationResponse<R>) => void) => Promise<void>;
+export declare const StreamlinedExecutionMode: typeof ExecutionMode;
+export type StreamlinedPipelineOptions = PipelineOptions;
+export type StreamlinedPipelineResult<T> = PipelineResult<T>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/sequentialPipeline.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Sequential Augmentation Pipeline
+ *
+ * This module provides a pipeline for executing augmentations in a specific sequence:
+ * ISense -> IMemory -> ICognition -> IConduit -> IActivation -> IPerception
+ *
+ * It supports high-performance streaming data from WebSockets without blocking.
+ * Optimized for Node.js 23.11+ using native WebStreams API.
+ */
+import { AugmentationResponse, WebSocketConnection } from './types/augmentations.js';
+import { BrainyData } from './brainyData.js';
+/**
+ * Options for sequential pipeline execution
+ */
+export interface SequentialPipelineOptions {
+    /**
+     * Timeout for each augmentation execution in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Whether to stop execution if an error occurs
+     */
+    stopOnError?: boolean;
+    /**
+     * BrainyData instance to use for storage
+     */
+    brainyData?: BrainyData;
+}
+/**
+ * Result of a pipeline execution
+ */
+export interface PipelineResult<T> {
+    /**
+     * Whether the pipeline execution was successful
+     */
+    success: boolean;
+    /**
+     * The data returned by the pipeline
+     */
+    data: T;
+    /**
+     * Error message if the pipeline execution failed
+     */
+    error?: string;
+    /**
+     * Results from each stage of the pipeline
+     */
+    stageResults: {
+        sense?: AugmentationResponse<unknown>;
+        memory?: AugmentationResponse<unknown>;
+        cognition?: AugmentationResponse<unknown>;
+        conduit?: AugmentationResponse<unknown>;
+        activation?: AugmentationResponse<unknown>;
+        perception?: AugmentationResponse<unknown>;
+    };
+}
+/**
+ * SequentialPipeline class
+ *
+ * Executes augmentations in a specific sequence:
+ * ISense -> IMemory -> ICognition -> IConduit -> IActivation -> IPerception
+ */
+export declare class SequentialPipeline {
+    private brainyData;
+    /**
+     * Create a new sequential pipeline
+     *
+     * @param options Options for the pipeline
+     */
+    constructor(options?: SequentialPipelineOptions);
+    /**
+     * Ensure stream classes are initialized
+     * @private
+     */
+    private ensureStreamClassesInitialized;
+    /**
+     * Initialize the pipeline
+     *
+     * @returns A promise that resolves when initialization is complete
+     */
+    initialize(): Promise<void>;
+    /**
+     * Process data through the sequential pipeline
+     *
+     * @param rawData The raw data to process
+     * @param dataType The type of data (e.g., 'text', 'image', 'audio')
+     * @param options Options for pipeline execution
+     * @returns A promise that resolves with the pipeline result
+     */
+    processData(rawData: Buffer | string, dataType: string, options?: SequentialPipelineOptions): Promise<PipelineResult<unknown>>;
+    /**
+     * Process WebSocket data through the sequential pipeline
+     *
+     * @param connection The WebSocket connection
+     * @param dataType The type of data (e.g., 'text', 'image', 'audio')
+     * @param options Options for pipeline execution
+     * @returns A function to handle incoming WebSocket messages
+     */
+    createWebSocketHandler(connection: WebSocketConnection, dataType: string, options?: SequentialPipelineOptions): Promise<(data: unknown) => void>;
+    /**
+     * Set up a WebSocket connection to process data through the pipeline
+     *
+     * @param url The WebSocket URL to connect to
+     * @param dataType The type of data (e.g., 'text', 'image', 'audio')
+     * @param options Options for pipeline execution
+     * @returns A promise that resolves with the WebSocket connection and associated streams
+     */
+    setupWebSocketPipeline(url: string, dataType: string, options?: SequentialPipelineOptions): Promise<WebSocketConnection & {
+        readableStream?: ReadableStream<unknown>;
+        writableStream?: WritableStream<unknown>;
+    }>;
+}
+export declare const sequentialPipeline: SequentialPipeline;
+//# sourceMappingURL=sequentialPipeline.d.ts.map

package/dist/storage/fileSystemStorage.d.ts

@@ -0,0 +1,123 @@
+import { GraphVerb, HNSWNoun, StorageAdapter } from '../coreTypes.js';
+/**
+ * File system storage adapter for Node.js environments
+ */
+export declare class FileSystemStorage implements StorageAdapter {
+    private rootDir;
+    private nounsDir;
+    private verbsDir;
+    private metadataDir;
+    private personDir;
+    private placeDir;
+    private thingDir;
+    private eventDir;
+    private conceptDir;
+    private contentDir;
+    private defaultDir;
+    private isInitialized;
+    constructor(rootDirectory?: string);
+    /**
+     * Initialize the storage adapter
+     */
+    init(): Promise<void>;
+    /**
+     * Save a node to storage
+     */
+    saveNoun(noun: HNSWNoun): Promise<void>;
+    /**
+     * Get a node from storage
+     */
+    getNoun(id: string): Promise<HNSWNoun | null>;
+    /**
+     * Get nodes by noun type
+     * @param nounType The noun type to filter by
+     * @returns Promise that resolves to an array of nodes of the specified noun type
+     */
+    getNounsByNounType(nounType: string): Promise<HNSWNoun[]>;
+    /**
+     * Get all nodes from storage
+     */
+    getAllNouns(): Promise<HNSWNoun[]>;
+    /**
+     * Read a node from a file
+     */
+    private readNodeFromFile;
+    /**
+     * Delete a node from storage
+     */
+    deleteNoun(id: string): Promise<void>;
+    /**
+     * Save an edge to storage
+     */
+    saveVerb(verb: GraphVerb): Promise<void>;
+    /**
+     * Get an edge from storage
+     */
+    getVerb(id: string): Promise<GraphVerb | null>;
+    /**
+     * Get all edges from storage
+     */
+    getAllVerbs(): Promise<GraphVerb[]>;
+    /**
+     * Get edges by source node ID
+     */
+    getVerbsBySource(sourceId: string): Promise<GraphVerb[]>;
+    /**
+     * Get edges by target node ID
+     */
+    getVerbsByTarget(targetId: string): Promise<GraphVerb[]>;
+    /**
+     * Get edges by type
+     */
+    getVerbsByType(type: string): Promise<GraphVerb[]>;
+    /**
+     * Delete an edge from storage
+     */
+    deleteVerb(id: string): Promise<void>;
+    /**
+     * Save metadata to storage
+     */
+    saveMetadata(id: string, metadata: any): Promise<void>;
+    /**
+     * Get metadata from storage
+     */
+    getMetadata(id: string): Promise<any | null>;
+    /**
+     * Clear all data from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Ensure the storage adapter is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Ensure a directory exists, creating it if necessary
+     */
+    private ensureDirectoryExists;
+    /**
+     * Delete a directory and all its contents recursively
+     */
+    private deleteDirectory;
+    /**
+     * Count the number of JSON files in a directory
+     */
+    private countFilesInDirectory;
+    /**
+     * Convert a Map to a plain object for serialization
+     */
+    private mapToObject;
+    /**
+     * Get the appropriate directory for a node based on its metadata
+     */
+    private getNodeDirectory;
+    /**
+     * Get information about storage usage and capacity
+     */
+    getStorageStatus(): Promise<{
+        type: string;
+        used: number;
+        quota: number | null;
+        details?: Record<string, any>;
+    }>;
+}
+//# sourceMappingURL=fileSystemStorage.d.ts.map