@soulcraft/brainy 0.9.5

package/cli-wrapper.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Wrapper Script
+ *
+ * This script serves as a wrapper for the Brainy CLI, ensuring that command-line arguments
+ * are properly passed to the CLI when invoked through npm scripts.
+ */
+
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import fs from 'fs'
+
+// Get the directory of the current module
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Path to the actual CLI script
+const cliPath = join(__dirname, 'dist', 'cli.js')
+
+// Check if the CLI script exists
+if (!fs.existsSync(cliPath)) {
+  console.error(`Error: CLI script not found at ${cliPath}`)
+  console.error('Make sure you have built the project with "npm run build"')
+  process.exit(1)
+}
+
+// Special handling for version flags
+if (process.argv.includes('--version') || process.argv.includes('-V')) {
+  // Read version directly from package.json to ensure it's always correct
+  try {
+    const packageJsonPath = join(__dirname, 'package.json')
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+    console.log(packageJson.version)
+    process.exit(0)
+  } catch (error) {
+    console.error('Error loading version information:', error.message)
+    process.exit(1)
+  }
+}
+
+// Forward all arguments to the CLI script
+const args = process.argv.slice(2)
+
+// Check if npm is passing --force flag
+// When npm runs with --force, it sets the npm_config_force environment variable
+if (process.env.npm_config_force === 'true' && args.includes('clear') && !args.includes('--force') && !args.includes('-f')) {
+  args.push('--force')
+}
+
+const cli = spawn('node', [cliPath, ...args], { stdio: 'inherit' })
+
+cli.on('close', (code) => {
+  process.exit(code)
+})

package/dist/augmentationFactory.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Augmentation Factory
+ *
+ * This module provides a simplified factory for creating augmentations with minimal boilerplate.
+ * It reduces the complexity of creating and using augmentations by providing a fluent API
+ * and handling common patterns automatically.
+ */
+import { IAugmentation, AugmentationResponse, ISenseAugmentation, IConduitAugmentation, IMemoryAugmentation, IWebSocketSupport, WebSocketConnection } from './types/augmentations.js';
+/**
+ * Options for creating an augmentation
+ */
+export interface AugmentationOptions {
+    name: string;
+    description?: string;
+    enabled?: boolean;
+    autoRegister?: boolean;
+    autoInitialize?: boolean;
+}
+/**
+ * Factory for creating sense augmentations
+ */
+export declare function createSenseAugmentation(options: AugmentationOptions & {
+    processRawData?: (rawData: Buffer | string, dataType: string) => Promise<AugmentationResponse<{
+        nouns: string[];
+        verbs: string[];
+    }>> | AugmentationResponse<{
+        nouns: string[];
+        verbs: string[];
+    }>;
+    listenToFeed?: (feedUrl: string, callback: (data: {
+        nouns: string[];
+        verbs: string[];
+    }) => void) => Promise<void>;
+}): ISenseAugmentation;
+/**
+ * Factory for creating conduit augmentations
+ */
+export declare function createConduitAugmentation(options: AugmentationOptions & {
+    establishConnection?: (targetSystemId: string, config: Record<string, unknown>) => Promise<AugmentationResponse<WebSocketConnection>> | AugmentationResponse<WebSocketConnection>;
+    readData?: (query: Record<string, unknown>, options?: Record<string, unknown>) => Promise<AugmentationResponse<unknown>> | AugmentationResponse<unknown>;
+    writeData?: (data: Record<string, unknown>, options?: Record<string, unknown>) => Promise<AugmentationResponse<unknown>> | AugmentationResponse<unknown>;
+    monitorStream?: (streamId: string, callback: (data: unknown) => void) => Promise<void>;
+}): IConduitAugmentation;
+/**
+ * Factory for creating memory augmentations
+ */
+export declare function createMemoryAugmentation(options: AugmentationOptions & {
+    storeData?: (key: string, data: unknown, options?: Record<string, unknown>) => Promise<AugmentationResponse<boolean>> | AugmentationResponse<boolean>;
+    retrieveData?: (key: string, options?: Record<string, unknown>) => Promise<AugmentationResponse<unknown>> | AugmentationResponse<unknown>;
+    updateData?: (key: string, data: unknown, options?: Record<string, unknown>) => Promise<AugmentationResponse<boolean>> | AugmentationResponse<boolean>;
+    deleteData?: (key: string, options?: Record<string, unknown>) => Promise<AugmentationResponse<boolean>> | AugmentationResponse<boolean>;
+    listDataKeys?: (pattern?: string, options?: Record<string, unknown>) => Promise<AugmentationResponse<string[]>> | AugmentationResponse<string[]>;
+    search?: (query: unknown, k?: number, options?: Record<string, unknown>) => Promise<AugmentationResponse<Array<{
+        id: string;
+        score: number;
+        data: unknown;
+    }>>> | AugmentationResponse<Array<{
+        id: string;
+        score: number;
+        data: unknown;
+    }>>;
+}): IMemoryAugmentation;
+/**
+ * Factory for creating WebSocket-enabled augmentations
+ * This can be combined with other augmentation factories to create WebSocket-enabled versions
+ */
+export declare function addWebSocketSupport<T extends IAugmentation>(augmentation: T, options: {
+    connectWebSocket?: (url: string, protocols?: string | string[]) => Promise<WebSocketConnection>;
+    sendWebSocketMessage?: (connectionId: string, data: unknown) => Promise<void>;
+    onWebSocketMessage?: (connectionId: string, callback: (data: unknown) => void) => Promise<void>;
+    offWebSocketMessage?: (connectionId: string, callback: (data: unknown) => void) => Promise<void>;
+    closeWebSocket?: (connectionId: string, code?: number, reason?: string) => Promise<void>;
+}): T & IWebSocketSupport;
+/**
+ * Simplified function to execute an augmentation method with automatic error handling
+ * This provides a more concise way to execute augmentation methods compared to the full pipeline
+ */
+export declare function executeAugmentation<T, R>(augmentation: IAugmentation, method: string, ...args: any[]): Promise<AugmentationResponse<R>>;
+/**
+ * Dynamically load augmentations from a module at runtime
+ * This allows for lazy-loading augmentations when needed instead of at build time
+ */
+export declare function loadAugmentationModule(modulePromise: Promise<any>, options?: {
+    autoRegister?: boolean;
+    autoInitialize?: boolean;
+}): Promise<IAugmentation[]>;
+//# sourceMappingURL=augmentationFactory.d.ts.map

package/dist/augmentationPipeline.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Augmentation Event Pipeline
+ *
+ * This module provides a pipeline for managing and executing multiple augmentations
+ * of each type. It allows registering multiple augmentations and executing them
+ * in sequence or in parallel.
+ */
+import { BrainyAugmentations, IAugmentation, IWebSocketSupport, AugmentationResponse, AugmentationType } from './types/augmentations.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;
+}
+/**
+ * AugmentationPipeline class
+ *
+ * Manages multiple augmentations of each type and provides methods to execute them.
+ */
+export declare class AugmentationPipeline {
+    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): AugmentationPipeline;
+    /**
+     * Unregister an augmentation from the pipeline
+     *
+     * @param augmentationName The name of the augmentation to unregister
+     * @returns The pipeline instance for chaining
+     */
+    unregister(augmentationName: string): AugmentationPipeline;
+    /**
+     * 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>;
+    /**
+     * Execute a sense pipeline
+     *
+     * @param method The method to execute on each sense augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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
+     *
+     * @param method The method to execute on each conduit augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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
+     *
+     * @param method The method to execute on each cognition augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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
+     *
+     * @param method The method to execute on each memory augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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
+     *
+     * @param method The method to execute on each perception augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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
+     *
+     * @param method The method to execute on each dialog augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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
+     *
+     * @param method The method to execute on each activation augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    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;
+    }>[]>;
+    /**
+     * 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;
+    /**
+     * Execute a pipeline for a specific augmentation type
+     *
+     * @param augmentations The augmentations to execute
+     * @param method The method to execute on each augmentation
+     * @param args The arguments to pass to the method
+     * @param options The pipeline execution options
+     * @returns A promise that resolves with the results from all augmentations
+     */
+    private executeTypedPipeline;
+}
+export declare const augmentationPipeline: AugmentationPipeline;
+//# sourceMappingURL=augmentationPipeline.d.ts.map

package/dist/augmentationRegistry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Augmentation Registry
+ *
+ * This module provides a registry for augmentations that are loaded at build time.
+ * It replaces the dynamic loading mechanism in pluginLoader.ts.
+ */
+import { IPipeline } from './types/pipelineTypes.js';
+import { AugmentationType, IAugmentation } from './types/augmentations.js';
+/**
+ * Sets the default pipeline instance
+ * This function should be called from pipeline.ts after the pipeline is created
+ */
+export declare function setDefaultPipeline(pipeline: IPipeline): void;
+/**
+ * Registry of all available augmentations
+ */
+export declare const availableAugmentations: IAugmentation[];
+/**
+ * Registers an augmentation with the registry
+ *
+ * @param augmentation The augmentation to register
+ * @returns The augmentation that was registered
+ */
+export declare function registerAugmentation<T extends IAugmentation>(augmentation: T): T;
+/**
+ * Initializes the augmentation pipeline with all registered augmentations
+ *
+ * @param pipeline Optional custom pipeline to use instead of the default
+ * @returns The pipeline that was initialized
+ * @throws Error if no pipeline is provided and the default pipeline hasn't been set
+ */
+export declare function initializeAugmentationPipeline(pipelineInstance?: IPipeline): IPipeline;
+/**
+ * Enables or disables an augmentation by name
+ *
+ * @param name The name of the augmentation to enable/disable
+ * @param enabled Whether to enable or disable the augmentation
+ * @returns True if the augmentation was found and updated, false otherwise
+ */
+export declare function setAugmentationEnabled(name: string, enabled: boolean): boolean;
+/**
+ * Gets all augmentations of a specific type
+ *
+ * @param type The type of augmentation to get
+ * @returns An array of all augmentations of the specified type
+ */
+export declare function getAugmentationsByType(type: AugmentationType): IAugmentation[];
+//# sourceMappingURL=augmentationRegistry.d.ts.map

package/dist/augmentationRegistryLoader.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Augmentation Registry Loader
+ *
+ * This module provides functionality for loading augmentation registrations
+ * at build time. It's designed to be used with build tools like webpack or rollup
+ * to automatically discover and register augmentations.
+ */
+import { IAugmentation } from './types/augmentations.js';
+/**
+ * Options for the augmentation registry loader
+ */
+export interface AugmentationRegistryLoaderOptions {
+    /**
+     * Whether to automatically initialize the augmentations after loading
+     * @default false
+     */
+    autoInitialize?: boolean;
+    /**
+     * Whether to log debug information during loading
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Result of loading augmentations
+ */
+export interface AugmentationLoadResult {
+    /**
+     * The augmentations that were loaded
+     */
+    augmentations: IAugmentation[];
+    /**
+     * Any errors that occurred during loading
+     */
+    errors: Error[];
+}
+/**
+ * Loads augmentations from the specified modules
+ *
+ * This function is designed to be used with build tools like webpack or rollup
+ * to automatically discover and register augmentations.
+ *
+ * @param modules An object containing modules with augmentations to register
+ * @param options Options for the loader
+ * @returns A promise that resolves with the result of loading the augmentations
+ *
+ * @example
+ * ```typescript
+ * // webpack.config.js
+ * const { AugmentationRegistryPlugin } = require('brainy/dist/webpack');
+ *
+ * module.exports = {
+ *   // ... other webpack config
+ *   plugins: [
+ *     new AugmentationRegistryPlugin({
+ *       // Pattern to match files containing augmentations
+ *       pattern: /augmentation\.js$/,
+ *       // Options for the loader
+ *       options: {
+ *         autoInitialize: true,
+ *         debug: true
+ *       }
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+export declare function loadAugmentationsFromModules(modules: Record<string, any>, options?: AugmentationRegistryLoaderOptions): Promise<AugmentationLoadResult>;
+/**
+ * Creates a webpack plugin for automatically loading augmentations
+ *
+ * @param options Options for the plugin
+ * @returns A webpack plugin
+ *
+ * @example
+ * ```typescript
+ * // webpack.config.js
+ * const { createAugmentationRegistryPlugin } = require('brainy/dist/webpack');
+ *
+ * module.exports = {
+ *   // ... other webpack config
+ *   plugins: [
+ *     createAugmentationRegistryPlugin({
+ *       pattern: /augmentation\.js$/,
+ *       options: {
+ *         autoInitialize: true,
+ *         debug: true
+ *       }
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+export declare function createAugmentationRegistryPlugin(options: {
+    /**
+     * Pattern to match files containing augmentations
+     */
+    pattern: RegExp;
+    /**
+     * Options for the loader
+     */
+    options?: AugmentationRegistryLoaderOptions;
+}): {
+    name: string;
+    pattern: RegExp;
+    options: AugmentationRegistryLoaderOptions;
+};
+/**
+ * Creates a rollup plugin for automatically loading augmentations
+ *
+ * @param options Options for the plugin
+ * @returns A rollup plugin
+ *
+ * @example
+ * ```typescript
+ * // rollup.config.js
+ * import { createAugmentationRegistryRollupPlugin } from 'brainy/dist/rollup';
+ *
+ * export default {
+ *   // ... other rollup config
+ *   plugins: [
+ *     createAugmentationRegistryRollupPlugin({
+ *       pattern: /augmentation\.js$/,
+ *       options: {
+ *         autoInitialize: true,
+ *         debug: true
+ *       }
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+export declare function createAugmentationRegistryRollupPlugin(options: {
+    /**
+     * Pattern to match files containing augmentations
+     */
+    pattern: RegExp;
+    /**
+     * Options for the loader
+     */
+    options?: AugmentationRegistryLoaderOptions;
+}): {
+    name: string;
+    pattern: RegExp;
+    options: AugmentationRegistryLoaderOptions;
+};
+//# sourceMappingURL=augmentationRegistryLoader.d.ts.map