@soulcraft/brainy 2.15.0 → 3.0.1

package/dist/augmentations/monitoringAugmentation.d.ts

@@ -1,7 +1,7 @@
 /**
  * Monitoring Augmentation - Optional Health & Performance Monitoring
  *
- * Replaces the hardcoded HealthMonitor in BrainyData with an optional augmentation.
+ * Replaces the hardcoded HealthMonitor in Brainy with an optional augmentation.
  * Provides health checks, performance monitoring, and distributed system tracking.
  *
  * Zero-config: Automatically enabled for distributed deployments
@@ -31,11 +31,11 @@ export declare class MonitoringAugmentation extends BaseAugmentation {
     readonly metadata: "readonly";
     readonly name = "monitoring";
     readonly timing: "after";
-    operations: ("search" | "add" | "delete" | "all")[];
+    operations: ("search" | "find" | "similar" | "add" | "update" | "delete" | "relate" | "unrelate" | "all")[];
     readonly priority = 30;
     private healthMonitor;
     private configManager;
-    private config;
+    protected config: MonitoringConfig;
     private requestStartTimes;
     constructor(config?: MonitoringConfig);
     protected onInitialize(): Promise<void>;

package/dist/augmentations/monitoringAugmentation.js

@@ -1,7 +1,7 @@
 /**
  * Monitoring Augmentation - Optional Health & Performance Monitoring
  *
- * Replaces the hardcoded HealthMonitor in BrainyData with an optional augmentation.
+ * Replaces the hardcoded HealthMonitor in Brainy with an optional augmentation.
  * Provides health checks, performance monitoring, and distributed system tracking.
  *
  * Zero-config: Automatically enabled for distributed deployments
@@ -26,7 +26,7 @@ export class MonitoringAugmentation extends BaseAugmentation {
         this.metadata = 'readonly'; // Reads metadata for monitoring
         this.name = 'monitoring';
         this.timing = 'after';
-        this.operations = ['search', 'add', 'delete', 'all'];
+        this.operations = ['search', 'find', 'similar', 'add', 'update', 'delete', 'relate', 'unrelate', 'all'];
         this.priority = 30; // Low priority, observability layer
         this.healthMonitor = null;
         this.configManager = null;

package/dist/augmentations/neuralImport.d.ts

@@ -61,7 +61,7 @@ export declare class NeuralImportAugmentation extends BaseAugmentation {
     };
     operations: ("add" | "addNoun" | "addVerb" | "all")[];
     readonly priority = 80;
-    private config;
+    protected config: NeuralImportConfig;
     private analysisCache;
     private typeMatcher;
     constructor(config?: Partial<NeuralImportConfig>);

package/dist/augmentations/rateLimitAugmentation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Rate Limiting Augmentation
+ * Provides configurable rate limiting for Brainy operations
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { AugmentationManifest } from './manifest.js';
+export interface RateLimitConfig {
+    enabled?: boolean;
+    limits?: {
+        searches?: number;
+        writes?: number;
+        reads?: number;
+        deletes?: number;
+    };
+    windowMs?: number;
+    skipSuccessfulRequests?: boolean;
+    skipFailedRequests?: boolean;
+    keyGenerator?: (context: any) => string;
+}
+/**
+ * Rate Limit Augmentation
+ */
+export declare class RateLimitAugmentation extends BaseAugmentation {
+    readonly name = "rateLimiter";
+    readonly timing: "before";
+    readonly metadata: "none";
+    operations: any;
+    readonly priority = 10;
+    readonly category: "core";
+    readonly description = "Provides rate limiting for Brainy operations";
+    private limiters;
+    private windowMs;
+    constructor(config?: RateLimitConfig);
+    getManifest(): AugmentationManifest;
+    /**
+     * Initialize rate limiters for each operation type
+     */
+    private initializeLimiters;
+    /**
+     * Default key generator (could be IP, user ID, etc.)
+     */
+    private defaultKeyGenerator;
+    /**
+     * Check if request should be rate limited
+     */
+    private checkRateLimit;
+    /**
+     * Get remaining requests for an operation
+     */
+    private getRemainingRequests;
+    /**
+     * Get time until reset
+     */
+    private getResetTime;
+    protected onInitialize(): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    /**
+     * Execute augmentation - apply rate limiting
+     */
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    /**
+     * Get rate limit statistics
+     */
+    getStats(): {
+        operations: Record<string, {
+            activeKeys: number;
+            totalRequests: number;
+        }>;
+    };
+    /**
+     * Clear all rate limit entries
+     */
+    clear(): void;
+    /**
+     * Clear expired entries (cleanup)
+     */
+    cleanup(): void;
+}
+/**
+ * Create rate limit augmentation
+ */
+export declare function createRateLimitAugmentation(config?: RateLimitConfig): RateLimitAugmentation;

package/dist/augmentations/rateLimitAugmentation.js

@@ -0,0 +1,321 @@
+/**
+ * Rate Limiting Augmentation
+ * Provides configurable rate limiting for Brainy operations
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+/**
+ * Rate Limit Augmentation
+ */
+export class RateLimitAugmentation extends BaseAugmentation {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'rateLimiter';
+        this.timing = 'before';
+        this.metadata = 'none';
+        this.operations = ['search', 'find', 'add', 'update', 'delete', 'get'];
+        this.priority = 10; // High priority, runs early
+        // Augmentation metadata
+        this.category = 'core'; // Use 'core' as security isn't a valid category
+        this.description = 'Provides rate limiting for Brainy operations';
+        this.limiters = new Map();
+        // Merge with defaults
+        this.config = {
+            enabled: config.enabled ?? true,
+            limits: {
+                searches: config.limits?.searches ?? 1000,
+                writes: config.limits?.writes ?? 100,
+                reads: config.limits?.reads ?? 5000,
+                deletes: config.limits?.deletes ?? 50
+            },
+            windowMs: config.windowMs ?? 60000, // 1 minute default
+            skipSuccessfulRequests: config.skipSuccessfulRequests ?? false,
+            skipFailedRequests: config.skipFailedRequests ?? true,
+            keyGenerator: config.keyGenerator || this.defaultKeyGenerator
+        };
+        this.windowMs = this.config.windowMs;
+        // Initialize operation limiters
+        this.initializeLimiters();
+    }
+    getManifest() {
+        return {
+            id: 'rate-limiter',
+            name: 'Rate Limiter',
+            version: '1.0.0',
+            description: 'Configurable rate limiting for API operations',
+            longDescription: 'Provides per-operation rate limiting with configurable windows and limits. Helps prevent abuse and ensures fair resource usage.',
+            category: 'core',
+            configSchema: {
+                type: 'object',
+                properties: {
+                    enabled: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Enable or disable rate limiting'
+                    },
+                    limits: {
+                        type: 'object',
+                        properties: {
+                            searches: {
+                                type: 'number',
+                                default: 1000,
+                                description: 'Search operations per minute'
+                            },
+                            writes: {
+                                type: 'number',
+                                default: 100,
+                                description: 'Write operations per minute'
+                            },
+                            reads: {
+                                type: 'number',
+                                default: 5000,
+                                description: 'Read operations per minute'
+                            },
+                            deletes: {
+                                type: 'number',
+                                default: 50,
+                                description: 'Delete operations per minute'
+                            }
+                        }
+                    },
+                    windowMs: {
+                        type: 'number',
+                        default: 60000,
+                        description: 'Time window in milliseconds'
+                    }
+                }
+            },
+            configDefaults: {
+                enabled: true,
+                limits: {
+                    searches: 1000,
+                    writes: 100,
+                    reads: 5000,
+                    deletes: 50
+                },
+                windowMs: 60000
+            },
+            minBrainyVersion: '3.0.0',
+            keywords: ['rate-limit', 'security', 'throttle'],
+            documentation: 'https://docs.brainy.dev/augmentations/rate-limit',
+            status: 'stable',
+            performance: {
+                memoryUsage: 'low',
+                cpuUsage: 'low',
+                networkUsage: 'none'
+            },
+            features: ['per-operation-limits', 'configurable-windows', 'key-based-limiting'],
+            enhancedOperations: ['search', 'add', 'update', 'delete', 'get'],
+            metrics: [
+                {
+                    name: 'rate_limit_exceeded',
+                    type: 'counter',
+                    description: 'Number of rate limit violations'
+                },
+                {
+                    name: 'rate_limit_requests',
+                    type: 'counter',
+                    description: 'Total requests checked'
+                }
+            ]
+        };
+    }
+    /**
+     * Initialize rate limiters for each operation type
+     */
+    initializeLimiters() {
+        const operations = ['searches', 'writes', 'reads', 'deletes'];
+        for (const op of operations) {
+            this.limiters.set(op, new Map());
+        }
+    }
+    /**
+     * Default key generator (could be IP, user ID, etc.)
+     */
+    defaultKeyGenerator(_context) {
+        // In a real implementation, this would extract IP or user ID
+        return 'default';
+    }
+    /**
+     * Check if request should be rate limited
+     */
+    checkRateLimit(operation, key) {
+        const limiter = this.limiters.get(operation);
+        if (!limiter)
+            return false;
+        const limit = this.config.limits[operation];
+        if (!limit)
+            return false;
+        const now = Date.now();
+        let entry = limiter.get(key);
+        // Initialize or reset entry
+        if (!entry || now >= entry.resetTime) {
+            entry = {
+                count: 0,
+                resetTime: now + this.windowMs
+            };
+            limiter.set(key, entry);
+        }
+        // Check if limit exceeded
+        if (entry.count >= limit) {
+            return true; // Rate limited
+        }
+        // Increment counter
+        entry.count++;
+        return false;
+    }
+    /**
+     * Get remaining requests for an operation
+     */
+    getRemainingRequests(operation, key) {
+        const limiter = this.limiters.get(operation);
+        if (!limiter)
+            return -1;
+        const limit = this.config.limits[operation];
+        if (!limit)
+            return -1;
+        const entry = limiter.get(key);
+        if (!entry)
+            return limit;
+        const now = Date.now();
+        if (now >= entry.resetTime)
+            return limit;
+        return Math.max(0, limit - entry.count);
+    }
+    /**
+     * Get time until reset
+     */
+    getResetTime(operation, key) {
+        const limiter = this.limiters.get(operation);
+        if (!limiter)
+            return 0;
+        const entry = limiter.get(key);
+        if (!entry)
+            return 0;
+        const now = Date.now();
+        return Math.max(0, entry.resetTime - now);
+    }
+    async onInitialize() {
+        if (!this.config.enabled) {
+            this.log('Rate limiter disabled by configuration');
+            return;
+        }
+        this.log(`Rate limiter initialized (window: ${this.windowMs}ms)`);
+        // Start cleanup timer
+        setInterval(() => {
+            this.cleanup();
+        }, this.windowMs);
+    }
+    async onShutdown() {
+        this.clear();
+        this.log('Rate limiter shut down');
+    }
+    /**
+     * Execute augmentation - apply rate limiting
+     */
+    async execute(operation, params, next) {
+        // If rate limiting is disabled, just pass through
+        if (!this.config.enabled) {
+            return next();
+        }
+        // Map operations to rate limit categories
+        let rateLimitOperation;
+        switch (operation) {
+            case 'search':
+            case 'find':
+            case 'similar':
+                rateLimitOperation = 'searches';
+                break;
+            case 'add':
+            case 'update':
+                rateLimitOperation = 'writes';
+                break;
+            case 'delete':
+                rateLimitOperation = 'deletes';
+                break;
+            case 'get':
+                rateLimitOperation = 'reads';
+                break;
+            default:
+                return next(); // Don't rate limit unknown operations
+        }
+        const key = this.config.keyGenerator(params);
+        if (this.checkRateLimit(rateLimitOperation, key)) {
+            const error = new Error(`Rate limit exceeded for ${operation}`);
+            error.statusCode = 429;
+            error.retryAfter = this.getResetTime(rateLimitOperation, key);
+            error.rateLimit = {
+                limit: this.config.limits[rateLimitOperation],
+                remaining: 0,
+                reset: Date.now() + this.getResetTime(rateLimitOperation, key)
+            };
+            throw error;
+        }
+        try {
+            const result = await next();
+            // Add rate limit info to result if possible
+            if (result && typeof result === 'object' && !Array.isArray(result)) {
+                result._rateLimit = {
+                    limit: this.config.limits[rateLimitOperation],
+                    remaining: this.getRemainingRequests(rateLimitOperation, key),
+                    reset: Date.now() + this.getResetTime(rateLimitOperation, key)
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            // Optionally don't count failed requests
+            if (this.config.skipFailedRequests) {
+                const limiter = this.limiters.get(rateLimitOperation);
+                const entry = limiter.get(key);
+                if (entry && entry.count > 0)
+                    entry.count--;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get rate limit statistics
+     */
+    getStats() {
+        const stats = { operations: {} };
+        for (const [operation, limiter] of this.limiters) {
+            let totalRequests = 0;
+            for (const entry of limiter.values()) {
+                totalRequests += entry.count;
+            }
+            stats.operations[operation] = {
+                activeKeys: limiter.size,
+                totalRequests
+            };
+        }
+        return stats;
+    }
+    /**
+     * Clear all rate limit entries
+     */
+    clear() {
+        for (const limiter of this.limiters.values()) {
+            limiter.clear();
+        }
+    }
+    /**
+     * Clear expired entries (cleanup)
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const limiter of this.limiters.values()) {
+            for (const [key, entry] of limiter) {
+                if (now >= entry.resetTime) {
+                    limiter.delete(key);
+                }
+            }
+        }
+    }
+}
+/**
+ * Create rate limit augmentation
+ */
+export function createRateLimitAugmentation(config) {
+    return new RateLimitAugmentation(config);
+}
+//# sourceMappingURL=rateLimitAugmentation.js.map

package/dist/augmentations/requestDeduplicatorAugmentation.d.ts

@@ -14,10 +14,10 @@ export declare class RequestDeduplicatorAugmentation extends BaseAugmentation {
     name: string;
     timing: "around";
     metadata: "none";
-    operations: ("search" | "searchText" | "searchByNounTypes" | "findSimilar" | "get")[];
+    operations: ("search" | "find" | "similar" | "searchText" | "searchByNounTypes" | "findSimilar" | "get")[];
     priority: number;
     private pendingRequests;
-    private config;
+    protected config: Required<DeduplicatorConfig>;
     private cleanupInterval?;
     constructor(config?: DeduplicatorConfig);
     protected onInitialize(): Promise<void>;

package/dist/augmentations/requestDeduplicatorAugmentation.js

@@ -11,7 +11,7 @@ export class RequestDeduplicatorAugmentation extends BaseAugmentation {
         this.name = 'RequestDeduplicator';
         this.timing = 'around';
         this.metadata = 'none'; // Doesn't access metadata
-        this.operations = ['search', 'searchText', 'searchByNounTypes', 'findSimilar', 'get'];
+        this.operations = ['search', 'find', 'similar', 'searchText', 'searchByNounTypes', 'findSimilar', 'get'];
         this.priority = 50; // Performance optimization
         this.pendingRequests = new Map();
         this.config = {

package/dist/augmentations/storageAugmentation.d.ts

@@ -16,7 +16,7 @@ export declare abstract class StorageAugmentation extends BaseAugmentation imple
     operations: ("storage")[];
     readonly priority = 100;
     protected storageAdapter: StorageAdapter | null;
-    constructor();
+    constructor(config?: any);
     /**
      * Provide the storage adapter before full initialization
      * This is called during the storage resolution phase

package/dist/augmentations/storageAugmentation.js

@@ -11,8 +11,8 @@ import { BaseAugmentation } from './brainyAugmentation.js';
  */
 export class StorageAugmentation extends BaseAugmentation {
     // Storage augmentations must provide their name via readonly property
-    constructor() {
-        super();
+    constructor(config) {
+        super(config);
         this.timing = 'replace';
         this.metadata = 'none'; // Storage doesn't directly access metadata
         this.operations = ['storage']; // Make mutable for TypeScript compatibility

package/dist/augmentations/storageAugmentations.d.ts

@@ -6,12 +6,16 @@
  */
 import { StorageAugmentation } from './storageAugmentation.js';
 import { StorageAdapter } from '../coreTypes.js';
+import { AugmentationManifest } from './manifest.js';
 /**
  * Memory Storage Augmentation - Fast in-memory storage
  */
 export declare class MemoryStorageAugmentation extends StorageAugmentation {
     readonly name = "memory-storage";
-    constructor();
+    readonly category: "core";
+    readonly description = "High-performance in-memory storage for development and testing";
+    constructor(config?: any);
+    getManifest(): AugmentationManifest;
     provideStorage(): Promise<StorageAdapter>;
     protected onInitialize(): Promise<void>;
 }
@@ -20,8 +24,10 @@ export declare class MemoryStorageAugmentation extends StorageAugmentation {
  */
 export declare class FileSystemStorageAugmentation extends StorageAugmentation {
     readonly name = "filesystem-storage";
-    private rootDirectory;
-    constructor(rootDirectory?: string);
+    readonly category: "core";
+    readonly description = "Persistent file-based storage for Node.js environments";
+    constructor(config?: any);
+    getManifest(): AugmentationManifest;
     provideStorage(): Promise<StorageAdapter>;
     protected onInitialize(): Promise<void>;
 }
@@ -30,8 +36,10 @@ export declare class FileSystemStorageAugmentation extends StorageAugmentation {
  */
 export declare class OPFSStorageAugmentation extends StorageAugmentation {
     readonly name = "opfs-storage";
-    private requestPersistent;
-    constructor(requestPersistent?: boolean);
+    readonly category: "core";
+    readonly description = "Persistent browser storage using Origin Private File System";
+    constructor(config?: any);
+    getManifest(): AugmentationManifest;
     provideStorage(): Promise<StorageAdapter>;
     protected onInitialize(): Promise<void>;
 }
@@ -40,7 +48,15 @@ export declare class OPFSStorageAugmentation extends StorageAugmentation {
  */
 export declare class S3StorageAugmentation extends StorageAugmentation {
     readonly name = "s3-storage";
-    private config;
+    protected config: {
+        bucketName: string;
+        region?: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+        cacheConfig?: any;
+        operationConfig?: any;
+    };
     constructor(config: {
         bucketName: string;
         region?: string;
@@ -58,7 +74,13 @@ export declare class S3StorageAugmentation extends StorageAugmentation {
  */
 export declare class R2StorageAugmentation extends StorageAugmentation {
     readonly name = "r2-storage";
-    private config;
+    protected config: {
+        bucketName: string;
+        accountId: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        cacheConfig?: any;
+    };
     constructor(config: {
         bucketName: string;
         accountId: string;
@@ -74,7 +96,14 @@ export declare class R2StorageAugmentation extends StorageAugmentation {
  */
 export declare class GCSStorageAugmentation extends StorageAugmentation {
     readonly name = "gcs-storage";
-    private config;
+    protected config: {
+        bucketName: string;
+        region?: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        endpoint?: string;
+        cacheConfig?: any;
+    };
     constructor(config: {
         bucketName: string;
         region?: string;