@soulcraft/brainy 3.0.0 → 3.0.1

package/dist/augmentations/brainyAugmentation.d.ts

@@ -5,12 +5,12 @@
  * Each augmentation knows its place and when to execute automatically.
  *
  * The Vision: Components that enhance Brainy's capabilities seamlessly
- * - WAL: Adds durability to storage operations
  * - RequestDeduplicator: Prevents duplicate concurrent requests
  * - ConnectionPool: Optimizes cloud storage throughput
  * - IntelligentVerbScoring: Enhances relationship analysis
  * - StreamingPipeline: Enables unlimited data processing
  */
+import { AugmentationManifest } from './manifest.js';
 /**
  * Metadata access declaration for augmentations
  */
@@ -43,10 +43,10 @@ export interface BrainyAugmentation {
      * Which operations this augmentation applies to
      * Granular operation matching for precise augmentation targeting
      */
-    operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'findSimilar' | 'searchWithCursor' | 'relate' | 'getConnections' | 'storage' | 'backup' | 'restore' | 'all')[];
+    operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'update' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'find' | 'findSimilar' | 'searchWithCursor' | 'similar' | 'relate' | 'unrelate' | 'getConnections' | 'getRelations' | 'storage' | 'backup' | 'restore' | 'all')[];
     /**
      * Priority for execution order (higher numbers execute first)
-     * - 100: Critical system operations (WAL, ConnectionPool)
+     * - 100: Critical system operations (ConnectionPool)
      * - 50: Performance optimizations (RequestDeduplicator, Caching)
      * - 10: Enhancement features (IntelligentVerbScoring)
      * - 1: Optional features (Logging, Analytics)
@@ -54,9 +54,9 @@ export interface BrainyAugmentation {
     priority: number;
     /**
      * Initialize the augmentation
-     * Called once during BrainyData initialization
+     * Called once during Brainy initialization
      *
-     * @param context - The BrainyData instance and storage
+     * @param context - The Brainy instance and storage
      */
     initialize(context: AugmentationContext): Promise<void>;
     /**
@@ -74,16 +74,38 @@ export interface BrainyAugmentation {
      */
     shouldExecute?(operation: string, params: any): boolean;
     /**
-     * Optional: Cleanup when BrainyData is destroyed
+     * Optional: Cleanup when Brainy is destroyed
      */
     shutdown?(): Promise<void>;
+    /**
+     * Optional: Computed fields this augmentation provides
+     * Used for discovery, TypeScript support, and API documentation
+     */
+    computedFields?: {
+        [namespace: string]: {
+            [field: string]: {
+                type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+                description: string;
+                confidence?: number;
+            };
+        };
+    };
+    /**
+     * Optional: Compute fields for a result entity
+     * Called when user accesses getDisplay(), getSchema(), etc.
+     *
+     * @param result - The result entity (VectorDocument, GraphVerb, etc.)
+     * @param namespace - The namespace being requested ('display', 'schema', etc.)
+     * @returns Computed fields for the namespace
+     */
+    computeFields?(result: any, namespace: string): Promise<Record<string, any>> | Record<string, any>;
 }
 /**
  * Context provided to augmentations
  */
 export interface AugmentationContext {
     /**
-     * The BrainyData instance (for accessing methods and config)
+     * The Brainy instance (for accessing methods and config)
      */
     brain: any;
     /**
@@ -101,15 +123,69 @@ export interface AugmentationContext {
 }
 /**
  * Base class for augmentations with common functionality
+ *
+ * This is the unified base class that combines the features of both
+ * BaseAugmentation and ConfigurableAugmentation. All augmentations
+ * should extend this class for consistent configuration support.
  */
 export declare abstract class BaseAugmentation implements BrainyAugmentation {
     abstract name: string;
     abstract timing: 'before' | 'after' | 'around' | 'replace';
     abstract metadata: 'none' | 'readonly' | MetadataAccess;
-    abstract operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'findSimilar' | 'searchWithCursor' | 'relate' | 'getConnections' | 'storage' | 'backup' | 'restore' | 'all')[];
+    abstract operations: ('add' | 'addNoun' | 'addVerb' | 'saveNoun' | 'saveVerb' | 'updateMetadata' | 'update' | 'delete' | 'deleteVerb' | 'clear' | 'get' | 'search' | 'searchText' | 'searchByNounTypes' | 'find' | 'findSimilar' | 'searchWithCursor' | 'similar' | 'relate' | 'unrelate' | 'getConnections' | 'getRelations' | 'storage' | 'backup' | 'restore' | 'all')[];
     abstract priority: number;
+    category: 'internal' | 'core' | 'premium' | 'community' | 'external';
+    description: string;
+    enabled: boolean;
     protected context?: AugmentationContext;
     protected isInitialized: boolean;
+    protected config: any;
+    private configResolver?;
+    /**
+     * Constructor with optional configuration
+     * @param config Optional configuration to override defaults
+     */
+    constructor(config?: any);
+    /**
+     * Get the augmentation manifest for discovery
+     * Override this to enable configuration support
+     * CRITICAL: This enables tools to discover parameters and configuration
+     */
+    getManifest?(): AugmentationManifest;
+    /**
+     * Get parameter schema for operations
+     * Enables tools to know what parameters each operation needs
+     */
+    getParameterSchema?(operation: string): any;
+    /**
+     * Get operation descriptions
+     * Enables tools to show what each operation does
+     */
+    getOperationInfo?(): Record<string, {
+        description: string;
+        parameters?: any;
+        returns?: any;
+        examples?: any[];
+    }>;
+    /**
+     * Get current configuration
+     */
+    getConfig(): any;
+    /**
+     * Update configuration at runtime
+     * @param partial Partial configuration to merge
+     */
+    updateConfig(partial: any): Promise<void>;
+    /**
+     * Optional: Handle configuration changes
+     * Override this to react to runtime configuration updates
+     */
+    protected onConfigChange?(newConfig: any, oldConfig: any): Promise<void>;
+    /**
+     * Resolve configuration from all sources
+     * Priority: constructor > env > files > defaults
+     */
+    private resolveConfiguration;
     initialize(context: AugmentationContext): Promise<void>;
     /**
      * Override this in subclasses for initialization logic
@@ -122,11 +198,36 @@ export declare abstract class BaseAugmentation implements BrainyAugmentation {
      * Override this in subclasses for cleanup logic
      */
     protected onShutdown(): Promise<void>;
+    /**
+     * Optional computed fields declaration (override in subclasses)
+     */
+    computedFields?: {
+        [namespace: string]: {
+            [field: string]: {
+                type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+                description: string;
+                confidence?: number;
+            };
+        };
+    };
+    /**
+     * Optional computed fields implementation (override in subclasses)
+     * @param result The result entity
+     * @param namespace The requested namespace
+     * @returns Computed fields for the namespace
+     */
+    computeFields?(result: any, namespace: string): Promise<Record<string, any>> | Record<string, any>;
     /**
      * Log a message with the augmentation name
      */
     protected log(message: string, level?: 'info' | 'warn' | 'error'): void;
 }
+/**
+ * Alias for backward compatibility
+ * ConfigurableAugmentation is now merged into BaseAugmentation
+ * @deprecated Use BaseAugmentation instead
+ */
+export declare const ConfigurableAugmentation: typeof BaseAugmentation;
 /**
  * Registry for managing augmentations
  */
@@ -158,10 +259,43 @@ export declare class AugmentationRegistry {
      * Get all registered augmentations
      */
     getAll(): BrainyAugmentation[];
+    /**
+     * Get augmentation info for listing
+     */
+    getInfo(): Array<{
+        name: string;
+        type: string;
+        enabled: boolean;
+        description: string;
+        category: string;
+        priority: number;
+    }>;
     /**
      * Get augmentations by name
      */
     get(name: string): BrainyAugmentation | undefined;
+    /**
+     * Discover augmentation parameters and schemas
+     * Critical for tools like brain-cloud to generate UIs
+     */
+    discover(name?: string): any;
+    /**
+     * Get configuration schema for an augmentation
+     * Enables UI generation for configuration
+     */
+    getConfigSchema(name: string): any;
+    /**
+     * Configure an augmentation at runtime
+     */
+    configure(name: string, config: any): Promise<void>;
+    /**
+     * Get metrics for an augmentation
+     */
+    metrics(name?: string): any;
+    /**
+     * Get health status
+     */
+    health(): any;
     /**
      * Shutdown all augmentations
      */

package/dist/augmentations/brainyAugmentation.js

@@ -5,18 +5,89 @@
  * Each augmentation knows its place and when to execute automatically.
  *
  * The Vision: Components that enhance Brainy's capabilities seamlessly
- * - WAL: Adds durability to storage operations
  * - RequestDeduplicator: Prevents duplicate concurrent requests
  * - ConnectionPool: Optimizes cloud storage throughput
  * - IntelligentVerbScoring: Enhances relationship analysis
  * - StreamingPipeline: Enables unlimited data processing
  */
+import { AugmentationConfigResolver } from './configResolver.js';
 /**
  * Base class for augmentations with common functionality
+ *
+ * This is the unified base class that combines the features of both
+ * BaseAugmentation and ConfigurableAugmentation. All augmentations
+ * should extend this class for consistent configuration support.
  */
 export class BaseAugmentation {
-    constructor() {
+    /**
+     * Constructor with optional configuration
+     * @param config Optional configuration to override defaults
+     */
+    constructor(config) {
+        // Metadata for augmentation listing and management
+        this.category = 'core';
+        this.description = '';
+        this.enabled = true;
         this.isInitialized = false;
+        this.config = {};
+        // Only resolve configuration if getManifest is implemented
+        if (this.getManifest) {
+            this.config = this.resolveConfiguration(config);
+        }
+        else if (config) {
+            // Legacy support: direct config assignment for augmentations without manifests
+            this.config = config;
+        }
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration at runtime
+     * @param partial Partial configuration to merge
+     */
+    async updateConfig(partial) {
+        if (!this.configResolver) {
+            // For legacy augmentations without manifest, just merge config
+            const oldConfig = this.config;
+            this.config = { ...this.config, ...partial };
+            if (this.onConfigChange) {
+                await this.onConfigChange(this.config, oldConfig);
+            }
+            return;
+        }
+        const oldConfig = this.config;
+        try {
+            // Use resolver to update and validate
+            this.config = this.configResolver.updateRuntime(partial);
+            // Call config change handler if implemented
+            if (this.onConfigChange) {
+                await this.onConfigChange(this.config, oldConfig);
+            }
+        }
+        catch (error) {
+            // Revert on error
+            this.config = oldConfig;
+            throw error;
+        }
+    }
+    /**
+     * Resolve configuration from all sources
+     * Priority: constructor > env > files > defaults
+     */
+    resolveConfiguration(constructorConfig) {
+        const manifest = this.getManifest();
+        // Create config resolver
+        this.configResolver = new AugmentationConfigResolver({
+            augmentationId: manifest.id,
+            schema: manifest.configSchema,
+            defaults: manifest.configDefaults
+        });
+        // Resolve configuration from all sources
+        return this.configResolver.resolve(constructorConfig);
     }
     async initialize(context) {
         this.context = context;
@@ -54,6 +125,12 @@ export class BaseAugmentation {
         }
     }
 }
+/**
+ * Alias for backward compatibility
+ * ConfigurableAugmentation is now merged into BaseAugmentation
+ * @deprecated Use BaseAugmentation instead
+ */
+export const ConfigurableAugmentation = BaseAugmentation;
 /**
  * Registry for managing augmentations
  */
@@ -124,12 +201,112 @@ export class AugmentationRegistry {
     getAll() {
         return [...this.augmentations];
     }
+    /**
+     * Get augmentation info for listing
+     */
+    getInfo() {
+        return this.augmentations.map(aug => {
+            const baseAug = aug;
+            return {
+                name: aug.name,
+                type: baseAug.category || 'core',
+                enabled: baseAug.enabled !== false,
+                description: baseAug.description || `${aug.name} augmentation`,
+                category: baseAug.category || 'core',
+                priority: aug.priority
+            };
+        });
+    }
     /**
      * Get augmentations by name
      */
     get(name) {
         return this.augmentations.find(aug => aug.name === name);
     }
+    /**
+     * Discover augmentation parameters and schemas
+     * Critical for tools like brain-cloud to generate UIs
+     */
+    discover(name) {
+        if (name) {
+            const aug = this.get(name);
+            if (!aug)
+                return null;
+            const baseAug = aug;
+            return {
+                name: aug.name,
+                operations: aug.operations,
+                priority: aug.priority,
+                timing: aug.timing,
+                metadata: aug.metadata,
+                manifest: baseAug.getManifest ? baseAug.getManifest() : undefined,
+                parameters: baseAug.getParameterSchema ?
+                    aug.operations.reduce((acc, op) => {
+                        acc[op] = baseAug.getParameterSchema(op);
+                        return acc;
+                    }, {}) : undefined,
+                operationInfo: baseAug.getOperationInfo ? baseAug.getOperationInfo() : undefined,
+                config: baseAug.getConfig ? baseAug.getConfig() : undefined
+            };
+        }
+        // Return all augmentations discovery info
+        return this.augmentations.map(aug => this.discover(aug.name));
+    }
+    /**
+     * Get configuration schema for an augmentation
+     * Enables UI generation for configuration
+     */
+    getConfigSchema(name) {
+        const aug = this.get(name);
+        if (!aug || !aug.getManifest)
+            return null;
+        const manifest = aug.getManifest();
+        return manifest?.configSchema;
+    }
+    /**
+     * Configure an augmentation at runtime
+     */
+    async configure(name, config) {
+        const aug = this.get(name);
+        if (!aug || !aug.updateConfig) {
+            throw new Error(`Augmentation ${name} does not support configuration`);
+        }
+        await aug.updateConfig(config);
+    }
+    /**
+     * Get metrics for an augmentation
+     */
+    metrics(name) {
+        if (name) {
+            const aug = this.get(name);
+            if (!aug || !aug.metrics)
+                return null;
+            return aug.metrics();
+        }
+        // Return all metrics
+        const allMetrics = {};
+        for (const aug of this.augmentations) {
+            const a = aug;
+            if (a.metrics) {
+                allMetrics[aug.name] = a.metrics();
+            }
+        }
+        return allMetrics;
+    }
+    /**
+     * Get health status
+     */
+    health() {
+        const health = {
+            overall: 'healthy',
+            augmentations: {}
+        };
+        for (const aug of this.augmentations) {
+            const a = aug;
+            health.augmentations[aug.name] = a.health ? a.health() : 'unknown';
+        }
+        return health;
+    }
     /**
      * Shutdown all augmentations
      */

package/dist/augmentations/cacheAugmentation.d.ts

@@ -1,13 +1,14 @@
 /**
  * Cache Augmentation - Optional Search Result Caching
  *
- * Replaces the hardcoded SearchCache in BrainyData with an optional augmentation.
+ * Replaces the hardcoded SearchCache in Brainy with an optional augmentation.
  * This reduces core size and allows custom cache implementations.
  *
  * Zero-config: Automatically enabled with sensible defaults
  * Can be disabled or customized via augmentation registry
  */
 import { BaseAugmentation } from './brainyAugmentation.js';
+import { AugmentationManifest } from './manifest.js';
 import { SearchCache } from '../utils/searchCache.js';
 import type { GraphNoun } from '../types/graphTypes.js';
 export interface CacheConfig {
@@ -29,11 +30,13 @@ export declare class CacheAugmentation extends BaseAugmentation {
     readonly name = "cache";
     readonly timing: "around";
     readonly metadata: "none";
-    operations: ("search" | "add" | "delete" | "clear" | "all")[];
+    operations: ("search" | "find" | "similar" | "add" | "update" | "delete" | "clear" | "all")[];
     readonly priority = 50;
+    readonly category: "core";
+    readonly description = "Transparent search result caching with automatic invalidation";
     private searchCache;
-    private config;
     constructor(config?: CacheConfig);
+    getManifest(): AugmentationManifest;
     protected onInitialize(): Promise<void>;
     protected onShutdown(): Promise<void>;
     /**
@@ -68,9 +71,9 @@ export declare class CacheAugmentation extends BaseAugmentation {
      */
     clear(): void;
     /**
-     * Update cache configuration
+     * Handle runtime configuration changes
      */
-    updateConfig(config: Partial<CacheConfig>): void;
+    protected onConfigChange(newConfig: CacheConfig, oldConfig: CacheConfig): Promise<void>;
     /**
      * Clean up expired entries
      */

package/dist/augmentations/cacheAugmentation.js

@@ -1,7 +1,7 @@
 /**
  * Cache Augmentation - Optional Search Result Caching
  *
- * Replaces the hardcoded SearchCache in BrainyData with an optional augmentation.
+ * Replaces the hardcoded SearchCache in Brainy with an optional augmentation.
  * This reduces core size and allows custom cache implementations.
  *
  * Zero-config: Automatically enabled with sensible defaults
@@ -19,20 +19,116 @@ import { SearchCache } from '../utils/searchCache.js';
  * - Zero-config with smart defaults
  */
 export class CacheAugmentation extends BaseAugmentation {
-    constructor(config = {}) {
-        super();
+    constructor(config) {
+        super(config);
         this.name = 'cache';
         this.timing = 'around';
         this.metadata = 'none'; // Cache doesn't access metadata
-        this.operations = ['search', 'add', 'delete', 'clear', 'all'];
+        this.operations = ['search', 'find', 'similar', 'add', 'update', 'delete', 'clear', 'all'];
         this.priority = 50; // Mid-priority, runs after data operations
+        // Augmentation metadata
+        this.category = 'core';
+        this.description = 'Transparent search result caching with automatic invalidation';
         this.searchCache = null;
-        this.config = {
-            maxSize: 1000,
-            ttl: 300000, // 5 minutes default
-            enabled: true,
-            invalidateOnWrite: true,
-            ...config
+    }
+    getManifest() {
+        return {
+            id: 'cache',
+            name: 'Cache',
+            version: '2.0.0',
+            description: 'Intelligent caching for search and query operations',
+            longDescription: 'Provides transparent caching for search results with automatic invalidation on data changes. Significantly improves performance for repeated queries while maintaining data consistency.',
+            category: 'performance',
+            configSchema: {
+                type: 'object',
+                properties: {
+                    enabled: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Enable or disable caching'
+                    },
+                    maxSize: {
+                        type: 'number',
+                        default: 1000,
+                        minimum: 10,
+                        maximum: 100000,
+                        description: 'Maximum number of cached entries'
+                    },
+                    ttl: {
+                        type: 'number',
+                        default: 300000, // 5 minutes
+                        minimum: 1000, // 1 second
+                        maximum: 3600000, // 1 hour
+                        description: 'Time to live for cache entries in milliseconds'
+                    },
+                    invalidateOnWrite: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Automatically invalidate cache on data modifications'
+                    }
+                },
+                additionalProperties: false
+            },
+            configDefaults: {
+                enabled: true,
+                maxSize: 1000,
+                ttl: 300000,
+                invalidateOnWrite: true
+            },
+            configExamples: [
+                {
+                    name: 'High Performance',
+                    description: 'Large cache with longer TTL for read-heavy workloads',
+                    config: {
+                        enabled: true,
+                        maxSize: 10000,
+                        ttl: 1800000, // 30 minutes
+                        invalidateOnWrite: true
+                    }
+                },
+                {
+                    name: 'Conservative',
+                    description: 'Small cache with short TTL for frequently changing data',
+                    config: {
+                        enabled: true,
+                        maxSize: 100,
+                        ttl: 60000, // 1 minute
+                        invalidateOnWrite: true
+                    }
+                }
+            ],
+            minBrainyVersion: '2.0.0',
+            keywords: ['cache', 'performance', 'search', 'optimization'],
+            documentation: 'https://docs.brainy.dev/augmentations/cache',
+            status: 'stable',
+            performance: {
+                memoryUsage: 'medium',
+                cpuUsage: 'low',
+                networkUsage: 'none'
+            },
+            features: ['search-caching', 'auto-invalidation', 'ttl-support', 'memory-management'],
+            enhancedOperations: ['search', 'searchText', 'findSimilar'],
+            metrics: [
+                {
+                    name: 'cache_hits',
+                    type: 'counter',
+                    description: 'Number of cache hits'
+                },
+                {
+                    name: 'cache_misses',
+                    type: 'counter',
+                    description: 'Number of cache misses'
+                },
+                {
+                    name: 'cache_size',
+                    type: 'gauge',
+                    description: 'Current cache size'
+                }
+            ],
+            ui: {
+                icon: '⚡',
+                color: '#FFC107'
+            }
         };
     }
     async onInitialize() {
@@ -157,18 +253,21 @@ export class CacheAugmentation extends BaseAugmentation {
         }
     }
     /**
-     * Update cache configuration
+     * Handle runtime configuration changes
      */
-    updateConfig(config) {
-        this.config = { ...this.config, ...config };
-        if (this.searchCache && this.config.enabled) {
+    async onConfigChange(newConfig, oldConfig) {
+        if (this.searchCache && newConfig.enabled) {
             this.searchCache.updateConfig({
-                maxSize: this.config.maxSize,
-                maxAge: this.config.ttl, // SearchCache uses maxAge
-                enabled: this.config.enabled
+                maxSize: newConfig.maxSize,
+                maxAge: newConfig.ttl, // SearchCache uses maxAge
+                enabled: newConfig.enabled
             });
             this.log('Cache configuration updated');
         }
+        else if (!newConfig.enabled && this.searchCache) {
+            this.searchCache.clear();
+            this.log('Cache disabled and cleared');
+        }
     }
     /**
      * Clean up expired entries

package/dist/augmentations/conduitAugmentations.d.ts

@@ -52,12 +52,12 @@ export {};
  * Example usage:
  *
  * // Server instance
- * const serverBrain = new BrainyData()
+ * const serverBrain = new Brainy()
  * serverBrain.augmentations.register(new APIServerAugmentation())
  * await serverBrain.init()
  *
  * // Client instance
- * const clientBrain = new BrainyData()
+ * const clientBrain = new Brainy()
  * const conduit = new WebSocketConduitAugmentation()
  * clientBrain.augmentations.register(conduit)
  * await clientBrain.init()

package/dist/augmentations/conduitAugmentations.js

@@ -213,12 +213,12 @@ export class WebSocketConduitAugmentation extends BaseConduitAugmentation {
  * Example usage:
  *
  * // Server instance
- * const serverBrain = new BrainyData()
+ * const serverBrain = new Brainy()
  * serverBrain.augmentations.register(new APIServerAugmentation())
  * await serverBrain.init()
  *
  * // Client instance
- * const clientBrain = new BrainyData()
+ * const clientBrain = new Brainy()
  * const conduit = new WebSocketConduitAugmentation()
  * clientBrain.augmentations.register(conduit)
  * await clientBrain.init()