From b01e3340f11f2b185669be8b173d66ec1be78eca Mon Sep 17 00:00:00 2001 From: David Snelling Date: Fri, 15 Aug 2025 11:20:13 -0700 Subject: [PATCH] feat: Complete 9 unified methods with CLI parity and triple-power search - Add missing add-noun and add-verb CLI commands for full API parity - Update CLI documentation to showcase triple-power search capabilities - Add comprehensive type-safe augmentation management system - Verify search supports vector + metadata + graph traversal in one call - All 9 unified methods now available via both API and CLI - Complete documentation accuracy fixes and cleanup --- AUGMENTATIONS.md | 58 +++++++---- README.md | 18 +++- UNIFIED-API.md | 91 +++++++++++++++- bin/brainy.js | 103 +++++++++++++++++- docs/brainy-cli-1.0.md | 60 +++++++++-- docs/getting-started/quick-start-1.0.md | 5 +- src/augmentationManager.ts | 132 ++++++++++++++++++++++++ src/brainyData.ts | 74 +++++++------ src/index.ts | 3 + 9 files changed, 461 insertions(+), 83 deletions(-) create mode 100644 src/augmentationManager.ts diff --git a/AUGMENTATIONS.md b/AUGMENTATIONS.md index b4657ace..f3566cb5 100644 --- a/AUGMENTATIONS.md +++ b/AUGMENTATIONS.md @@ -128,34 +128,48 @@ brain.augment(new EmailParser()) await brain.add(emailContent) // Automatically parsed! ``` -## 🔧 Managing Augmentations +## 🔧 Managing Augmentations (Type-Safe API) -### List Active Augmentations +### The New Type-Safe Way (Recommended) ```javascript -const augmentations = brain.augment('list') -console.log(augmentations) -// [{ name: 'email-parser', type: 'processor', active: true }, ...] +// Access all management through brain.augmentations +const manager = brain.augmentations + +// List all augmentations +const all = manager.list() +console.log(all) +// [{ name: 'email-parser', type: 'processor', enabled: true }, ...] + +// Get specific augmentation info +const emailParser = manager.get('email-parser') +if (manager.isEnabled('email-parser')) { + console.log('Email parser is active') +} + +// Enable/disable augmentations +manager.disable('email-parser') // Temporarily disable +manager.enable('email-parser') // Re-enable +manager.remove('email-parser') // Remove completely + +// Manage by type (with TypeScript enums) +import { AugmentationType } from '@soulcraft/brainy' + +manager.enableType(AugmentationType.PROCESSOR) // Enable all processors +manager.disableType(AugmentationType.MEMORY) // Disable all memory augmentations + +// Get filtered lists +const enabled = manager.listEnabled() // All active augmentations +const disabled = manager.listDisabled() // All inactive augmentations +const processors = manager.listByType(AugmentationType.PROCESSOR) ``` -### Enable/Disable Augmentations +### Legacy String-Based API (Deprecated) ```javascript -// Disable temporarily -brain.augment('disable', 'email-parser') - -// Re-enable +// ⚠️ Deprecated - will show console warnings +brain.augment('list') brain.augment('enable', 'email-parser') - -// Remove completely -brain.augment('unregister', 'email-parser') -``` - -### Enable by Type -```javascript -// Disable all processors -brain.augment('disable-type', { type: 'processor' }) - -// Enable only validators -brain.augment('enable-type', { type: 'validator' }) +brain.augment('disable', 'email-parser') +// Use brain.augmentations.* instead ``` ## 🌟 Ideas for Community Augmentations diff --git a/README.md b/README.md index 7e627d32..72e53ef0 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ ## 🎉 **NEW: Brainy 1.0 - The Unified API** -**The Great Cleanup is complete!** Brainy 1.0 introduces the **unified API** - ONE way to do everything with just **8 core methods**: +**The Great Cleanup is complete!** Brainy 1.0 introduces the **unified API** - ONE way to do everything with just **9 core methods**: ```bash # Install Brainy 1.0 @@ -51,7 +51,7 @@ import { BrainyData, NounType, VerbType } from '@soulcraft/brainy' const brain = new BrainyData() await brain.init() -// 🎯 THE 8 UNIFIED METHODS - One way to do everything! +// 🎯 THE 9 UNIFIED METHODS - One way to do everything! await brain.add("Smart data") // 1. Smart addition await brain.search("query", 10) // 2. Unified search await brain.import(["data1", "data2"]) // 3. Bulk import @@ -60,10 +60,16 @@ await brain.addVerb(id1, id2, VerbType.Knows) // 5. Relationships await brain.update(id, "new data") // 6. Smart updates await brain.delete(id) // 7. Soft delete await brain.export({ format: 'json' }) // 8. Export data +brain.augment(myAugmentation) // 9. Extend infinitely! ♾️ + +// NEW: Type-safe augmentation management via brain.augmentations +brain.augmentations.list() // See all augmentations +brain.augmentations.enable(name) // Enable/disable dynamically ``` ### ✨ **What's New in 1.0:** -- **🔥 40+ methods consolidated** → 8 unified methods +- **🔥 40+ methods consolidated** → 9 unified methods +- **♾️ The 9th method** - `augment()` lets you extend Brainy infinitely! - **🧠 Smart by default** - `add()` auto-detects and processes intelligently - **🔐 Universal encryption** - Built-in encryption for sensitive data - **🐳 Container ready** - Model preloading for production deployments @@ -113,10 +119,12 @@ Vector + Graph + Search + AI = Brainy (Free & Open Source) = 🧠✨ pinecone.upsert(), neo4j.run(), elasticsearch.search() supabase.insert(), mongodb.find(), redis.set() -// After: 8 methods handle EVERYTHING +// After: 9 methods handle EVERYTHING brain.add(), brain.search(), brain.import() brain.addNoun(), brain.addVerb(), brain.update() -brain.delete(), brain.export() +brain.delete(), brain.export(), brain.augment() + +// Why 9? The 9th method (augment) gives you methods 10 → ∞! ``` #### **🤯 Mind-Blowing Features Out of the Box** diff --git a/UNIFIED-API.md b/UNIFIED-API.md index b435066a..47ea39b0 100644 --- a/UNIFIED-API.md +++ b/UNIFIED-API.md @@ -1,10 +1,10 @@ -# 🧠 Brainy 1.0: The 8 Unified Methods +# 🧠 Brainy 1.0: The 9 Unified Methods -> **From 40+ scattered methods to 8 unified operations - ONE way to do everything!** +> **From 40+ scattered methods to 9 unified operations - ONE way to do everything!** ## 🎯 The Complete Unified API -Brainy 1.0 introduces a revolutionary unified API where **EVERYTHING** is accomplished through just **8 core methods**: +Brainy 1.0 introduces a revolutionary unified API where **EVERYTHING** is accomplished through just **9 core methods**: ```javascript import { BrainyData, NounType, VerbType } from '@soulcraft/brainy' @@ -12,7 +12,7 @@ import { BrainyData, NounType, VerbType } from '@soulcraft/brainy' const brain = new BrainyData() await brain.init() -// 🎯 THE 8 UNIFIED METHODS: +// 🎯 THE 9 UNIFIED METHODS: await brain.add("Smart data") // 1. Smart data addition await brain.search("query", 10) // 2. Unified search await brain.import(["data1", "data2"]) // 3. Bulk import @@ -21,6 +21,7 @@ await brain.addVerb(id1, id2, VerbType.Knows) // 5. Relationships await brain.update(id, "new data") // 6. Smart updates await brain.delete(id) // 7. Soft delete await brain.export({ format: 'json' }) // 8. Export data +brain.augment(myAugmentation) // 9. Extend capabilities ``` ## 📊 Before vs After: The Transformation @@ -43,7 +44,7 @@ brainy.softDelete(id) ### ✅ **NEW (1.0): Unified Simplicity** ```javascript -// Just 8 methods handle EVERYTHING +// Just 9 methods handle EVERYTHING brain.add() // Replaces: addVector, addSmart, addText, addLiteral, etc. brain.search() // Replaces: searchSimilar, searchByMetadata, searchText, etc. brain.import() // Replaces: neuralImport, bulkAdd, importCSV, etc. @@ -52,6 +53,7 @@ brain.addVerb() // Replaces: createVerb, addRelationship, connect, etc. brain.update() // Replaces: updateVector, updateMetadata, modify, etc. brain.delete() // Replaces: hardDelete, softDelete, remove, etc. brain.export() // NEW: Universal data export +brain.augment() // NEW: Extend Brainy infinitely! ``` ## 🔍 Deep Dive: Each Unified Method @@ -251,6 +253,85 @@ const vectors = await brain.export({ format: 'embeddings' }) // Returns: [{ id, vector }, ...] ``` +### 9️⃣ **`augment()` - The Infinity Method** ♾️ + +**This is the magic 9th method that makes Brainy infinitely extensible!** + +```javascript +// PRIMARY USE: Add ANY capability you can imagine +brain.augment(new SentimentAnalyzer()) // Add sentiment analysis +brain.augment(new LanguageTranslator()) // Add translation +brain.augment(new CustomProcessor()) // Add your own! +``` + +### 🎯 **NEW: Type-Safe Augmentation Management** + +Brainy 1.0 introduces `brain.augmentations` for type-safe management: + +```typescript +// Full TypeScript support & IDE autocomplete! +brain.augmentations.list() // Returns AugmentationInfo[] +brain.augmentations.enable('sentiment') // Enable specific augmentation +brain.augmentations.disable('sentiment') // Disable temporarily +brain.augmentations.remove('sentiment') // Remove completely + +// Query augmentation status +brain.augmentations.get('sentiment') // Get specific info +brain.augmentations.isEnabled('sentiment') // Check if enabled + +// Manage by type (with enum for type safety) +brain.augmentations.enableType(AugmentationType.PROCESSOR) +brain.augmentations.disableType(AugmentationType.MEMORY) +brain.augmentations.listByType(AugmentationType.DIALOG) + +// Filter augmentations +brain.augmentations.listEnabled() // All active augmentations +brain.augmentations.listDisabled() // All inactive ones + +``` + +### 📝 **Complete Example with TypeScript** + +```typescript +import { BrainyData, AugmentationType, IAugmentation } from '@soulcraft/brainy' + +// Create your augmentation with full type safety +class SentimentAnalyzer implements IAugmentation { + readonly name = 'sentiment-analyzer' + readonly description = 'Analyzes emotional tone of text' + enabled = true + + async initialize() { /* setup */ } + async shutDown() { /* cleanup */ } + async getStatus() { return 'active' as const } + + async analyze(text: string): Promise<'positive' | 'negative' | 'neutral'> { + // Your sentiment logic here + return 'positive' + } +} + +const brain = new BrainyData() +const sentiment = new SentimentAnalyzer() + +// Register with the 9th method +brain.augment(sentiment) + +// Type-safe management +if (brain.augmentations.isEnabled('sentiment-analyzer')) { + console.log('Sentiment analysis is active!') +} + +// List all processor-type augmentations +const processors = brain.augmentations.listByType(AugmentationType.PROCESSOR) +``` + +**Why augment() is special:** +- 🚀 **Infinite Extensibility** - Add any feature you can imagine +- 🧩 **Plugin Architecture** - Share augmentations with the community +- 🔧 **Runtime Flexibility** - Enable/disable features on the fly +- 🎯 **Zero Core Bloat** - Keep Brainy lean, add only what you need + ## 🧩 Augmentation Types & Pipeline Augmentations extend Brainy through a pipeline architecture: diff --git a/bin/brainy.js b/bin/brainy.js index 1c8fa5c7..e3ddc547 100755 --- a/bin/brainy.js +++ b/bin/brainy.js @@ -669,7 +669,108 @@ program } })) -// Command 6: STATUS - Database health & info +// Command 6A: ADD-NOUN - Create typed entities (Method #4) +program + .command('add-noun ') + .description('Add a typed entity to your knowledge graph') + .option('-t, --type ', 'Noun type (Person, Organization, Project, Event, Concept, Location, Product)', 'Concept') + .option('-m, --metadata ', 'Metadata as JSON') + .option('--encrypt', 'Encrypt this entity') + .action(wrapAction(async (name, options) => { + const brainy = await getBrainy() + + // Validate noun type + const validTypes = ['Person', 'Organization', 'Project', 'Event', 'Concept', 'Location', 'Product'] + if (!validTypes.includes(options.type)) { + console.log(colors.error(`❌ Invalid noun type: ${options.type}`)) + console.log(colors.info(`Valid types: ${validTypes.join(', ')}`)) + process.exit(1) + } + + let metadata = {} + if (options.metadata) { + try { + metadata = JSON.parse(options.metadata) + } catch { + console.error(colors.error('❌ Invalid JSON metadata')) + process.exit(1) + } + } + + if (options.encrypt) { + metadata.encrypted = true + } + + try { + const { NounType } = await import('../dist/types/graphTypes.js') + const id = await brainy.addNoun(name, NounType[options.type], metadata) + + console.log(colors.success('✅ Noun added successfully!')) + console.log(colors.info(`🆔 ID: ${id}`)) + console.log(colors.info(`👤 Name: ${name}`)) + console.log(colors.info(`🏷️ Type: ${options.type}`)) + if (Object.keys(metadata).length > 0) { + console.log(colors.info(`📝 Metadata: ${JSON.stringify(metadata, null, 2)}`)) + } + } catch (error) { + console.log(colors.error('❌ Failed to add noun:')) + console.log(colors.error(error.message)) + process.exit(1) + } + })) + +// Command 6B: ADD-VERB - Create relationships (Method #5) +program + .command('add-verb ') + .description('Create a relationship between two entities') + .option('-t, --type ', 'Verb type (WorksFor, Knows, CreatedBy, BelongsTo, Uses, etc.)', 'RelatedTo') + .option('-m, --metadata ', 'Relationship metadata as JSON') + .option('--encrypt', 'Encrypt this relationship') + .action(wrapAction(async (source, target, options) => { + const brainy = await getBrainy() + + // Common verb types for validation + const commonTypes = ['WorksFor', 'Knows', 'CreatedBy', 'BelongsTo', 'Uses', 'LeadsProject', 'MemberOf', 'RelatedTo', 'InteractedWith'] + if (!commonTypes.includes(options.type)) { + console.log(colors.warning(`⚠️ Uncommon verb type: ${options.type}`)) + console.log(colors.info(`Common types: ${commonTypes.join(', ')}`)) + } + + let metadata = {} + if (options.metadata) { + try { + metadata = JSON.parse(options.metadata) + } catch { + console.error(colors.error('❌ Invalid JSON metadata')) + process.exit(1) + } + } + + if (options.encrypt) { + metadata.encrypted = true + } + + try { + const { VerbType } = await import('../dist/types/graphTypes.js') + + // Use the provided type or fall back to RelatedTo + const verbType = VerbType[options.type] || options.type + const id = await brainy.addVerb(source, target, verbType, metadata) + + console.log(colors.success('✅ Relationship added successfully!')) + console.log(colors.info(`🆔 ID: ${id}`)) + console.log(colors.info(`🔗 ${source} --[${options.type}]--> ${target}`)) + if (Object.keys(metadata).length > 0) { + console.log(colors.info(`📝 Metadata: ${JSON.stringify(metadata, null, 2)}`)) + } + } catch (error) { + console.log(colors.error('❌ Failed to add relationship:')) + console.log(colors.error(error.message)) + process.exit(1) + } + })) + +// Command 7: STATUS - Database health & info program .command('status') .description('Show brain status and comprehensive statistics') diff --git a/docs/brainy-cli-1.0.md b/docs/brainy-cli-1.0.md index 9082d361..0165e323 100644 --- a/docs/brainy-cli-1.0.md +++ b/docs/brainy-cli-1.0.md @@ -20,7 +20,7 @@ brainy neural-import data.csv brainy add "data" # Smart by default brainy search "query" # Unified search brainy import data.csv # Neural import built-in -# Just 9 core commands total +# Just 9 unified methods total ``` ## ⚡ Quick Start @@ -40,7 +40,7 @@ brainy init # ✓ Performance tier (small, medium, large, enterprise) ``` -## 🧠 The Core Commands +## 🧠 The 9 Unified Methods ### 1. `brainy add` - Smart Data Addition ```bash @@ -57,19 +57,22 @@ brainy add "Sensitive data" --encrypt brainy add "Raw text data" --literal ``` -### 2. `brainy search` - Unified Search +### 2. `brainy search` - Triple-Power Unified Search ```bash -# Semantic search +# 🎯 Vector/Semantic search brainy search "tech companies and their leaders" -# With filters -brainy search "customer feedback" --filter '{"rating": {"$gte": 4}}' +# 🔍 Metadata/Facet search with MongoDB operators +brainy search "" --filter '{"rating": {"$gte": 4}, "department": "Engineering"}' -# Limit results -brainy search "AI projects" --limit 5 +# 🕸️ Graph traversal with relationships +brainy search "project teams" --include-relationships -# Include metadata in output -brainy search "projects" --include-metadata +# ⚡ TRIPLE POWER: All three combined! +brainy search "engineering leaders" --filter '{"level": {"$gte": 7}}' --include-relationships + +# Limit results and include metadata +brainy search "AI projects" --limit 5 --include-metadata ``` ### 3. `brainy import` - Bulk Data Import @@ -123,6 +126,43 @@ brainy export --format csv --filter '{"type": "person"}' --output people.csv brainy export --include-relationships --output full-backup.json ``` +### 7. `brainy add-noun` - Create Typed Entities +```bash +# Add people with metadata +brainy add-noun "Sarah Johnson" --type Person --metadata '{"role": "CTO", "level": 9}' + +# Add organizations +brainy add-noun "SoulCraft Labs" --type Organization --metadata '{"industry": "AI"}' + +# Add projects with rich metadata +brainy add-noun "AI Platform" --type Project --metadata '{"status": "active", "budget": 500000}' +``` + +### 8. `brainy add-verb` - Create Relationships +```bash +# Connect entities with relationships +brainy add-verb person_123 org_456 --type WorksFor --metadata '{"since": "2023-01-01"}' + +# Project relationships +brainy add-verb person_123 project_789 --type LeadsProject + +# Any relationship type +brainy add-verb entity_1 entity_2 --type CustomRelation --metadata '{"strength": 0.9}' +``` + +### 9. `brainy augment` - Extend Your Brain +```bash +# List all augmentations +brainy augment list + +# Enable/disable augmentations +brainy augment enable sentiment-analyzer +brainy augment disable sentiment-analyzer + +# Install community augmentations (future) +brainy augment install brainy-sentiment +``` + ## 🎮 Interactive Commands ### `brainy chat` - Talk to Your Data diff --git a/docs/getting-started/quick-start-1.0.md b/docs/getting-started/quick-start-1.0.md index df65d478..7e4b2bbb 100644 --- a/docs/getting-started/quick-start-1.0.md +++ b/docs/getting-started/quick-start-1.0.md @@ -4,10 +4,10 @@ Get up and running with Brainy 1.0's unified API in just a few minutes! ## 🎉 What's New in 1.0? -Brainy 1.0 introduces the **unified API** - ONE way to do everything with just **8 core methods**: +Brainy 1.0 introduces the **unified API** - ONE way to do everything with just **9 core methods**: ```javascript -// 🎯 THE 8 UNIFIED METHODS: +// 🎯 THE 9 UNIFIED METHODS: await brain.add("Smart data addition") // 1. Smart addition await brain.addNoun("John Doe", NounType.Person) // 2. Typed entities await brain.addVerb(id1, id2, VerbType.CreatedBy) // 3. Relationships @@ -16,6 +16,7 @@ await brain.import(["data1", "data2"]) // 5. Bulk import await brain.update(id1, "Updated data") // 6. Smart updates await brain.delete(verb) // 7. Soft delete await brain.export({ format: 'json' }) // 8. Export data +brain.augment(myAugmentation) // 9. Extend infinitely! ``` ## ⚡ The 2-Minute Setup diff --git a/src/augmentationManager.ts b/src/augmentationManager.ts new file mode 100644 index 00000000..ab570c51 --- /dev/null +++ b/src/augmentationManager.ts @@ -0,0 +1,132 @@ +/** + * Type-safe augmentation management system for Brainy + * Provides a clean API for managing augmentations without string literals + */ + +import { IAugmentation, AugmentationType } from './types/augmentations.js' +import { augmentationPipeline } from './augmentationPipeline.js' + +export interface AugmentationInfo { + name: string + type: string + enabled: boolean + description: string +} + +/** + * Type-safe augmentation manager + * Accessed via brain.augmentations for all management operations + */ +export class AugmentationManager { + private pipeline = augmentationPipeline + + /** + * List all registered augmentations with their status + * @returns Array of augmentation information + */ + list(): AugmentationInfo[] { + return this.pipeline.listAugmentationsWithStatus() + } + + /** + * Get information about a specific augmentation + * @param name The augmentation name + * @returns Augmentation info or undefined if not found + */ + get(name: string): AugmentationInfo | undefined { + const all = this.list() + return all.find(a => a.name === name) + } + + /** + * Check if an augmentation is enabled + * @param name The augmentation name + * @returns True if enabled, false otherwise + */ + isEnabled(name: string): boolean { + const aug = this.get(name) + return aug?.enabled ?? false + } + + /** + * Enable a specific augmentation + * @param name The augmentation name + * @returns True if successfully enabled + */ + enable(name: string): boolean { + return this.pipeline.enableAugmentation(name) + } + + /** + * Disable a specific augmentation + * @param name The augmentation name + * @returns True if successfully disabled + */ + disable(name: string): boolean { + return this.pipeline.disableAugmentation(name) + } + + /** + * Remove an augmentation from the pipeline + * @param name The augmentation name + * @returns True if successfully removed + */ + remove(name: string): boolean { + this.pipeline.unregister(name) + return true + } + + /** + * Enable all augmentations of a specific type + * @param type The augmentation type + * @returns Number of augmentations enabled + */ + enableType(type: AugmentationType): number { + return this.pipeline.enableAugmentationType(type as any) + } + + /** + * Disable all augmentations of a specific type + * @param type The augmentation type + * @returns Number of augmentations disabled + */ + disableType(type: AugmentationType): number { + return this.pipeline.disableAugmentationType(type as any) + } + + /** + * Get all augmentations of a specific type + * @param type The augmentation type + * @returns Array of augmentations of that type + */ + listByType(type: AugmentationType): AugmentationInfo[] { + return this.list().filter(a => a.type === type) + } + + /** + * Get all enabled augmentations + * @returns Array of enabled augmentations + */ + listEnabled(): AugmentationInfo[] { + return this.list().filter(a => a.enabled) + } + + /** + * Get all disabled augmentations + * @returns Array of disabled augmentations + */ + listDisabled(): AugmentationInfo[] { + return this.list().filter(a => !a.enabled) + } + + /** + * Register a new augmentation (internal use) + * @param augmentation The augmentation to register + */ + register(augmentation: IAugmentation): void { + this.pipeline.register(augmentation) + } +} + +// Export types for external use +export { AugmentationType } from './types/augmentations.js' \ No newline at end of file diff --git a/src/brainyData.ts b/src/brainyData.ts index f3546cc9..fb39c2fe 100644 --- a/src/brainyData.ts +++ b/src/brainyData.ts @@ -64,6 +64,7 @@ import { import { SearchCache, SearchCacheConfig } from './utils/searchCache.js' import { CacheAutoConfigurator } from './utils/cacheAutoConfig.js' import { StatisticsCollector } from './utils/statisticsCollector.js' +import { AugmentationManager } from './augmentationManager.js' export interface BrainyDataConfig { /** @@ -470,6 +471,12 @@ export class BrainyData implements BrainyDataInterface { private loggingConfig: BrainyDataConfig['logging'] = { verbose: true } private defaultService: string = 'default' private searchCache: SearchCache + + /** + * Type-safe augmentation management + * Access all augmentation operations through this property + */ + public readonly augmentations: AugmentationManager private cacheAutoConfigurator: CacheAutoConfigurator // Timeout and retry configuration @@ -691,6 +698,9 @@ export class BrainyData implements BrainyDataInterface { // Initialize search cache with final configuration this.searchCache = new SearchCache(finalSearchCacheConfig) + + // Initialize augmentation manager + this.augmentations = new AugmentationManager() // Initialize intelligent verb scoring if enabled if (config.intelligentVerbScoring?.enabled) { @@ -7269,83 +7279,71 @@ export class BrainyData implements BrainyDataInterface { // ===== Augmentation Control Methods ===== /** - * UNIFIED API METHOD #8: Augment - Complete augmentation management - * Register, enable, disable, list, and manage augmentations + * UNIFIED API METHOD #9: Augment - Register new augmentations * - * @param action The action to perform or augmentation to register - * @param options Additional options for the action - * @returns Various return types based on action + * For registration: brain.augment(new MyAugmentation()) + * For management: Use brain.augmentations.enable(), .disable(), .list() etc. + * + * @param action The augmentation to register OR legacy string command + * @param options Legacy options for string commands (deprecated) + * @returns this for chaining when registering, various for legacy commands + * + * @deprecated String-based commands are deprecated. Use brain.augmentations.* instead */ augment( action: IAugmentation | 'list' | 'enable' | 'disable' | 'unregister' | 'enable-type' | 'disable-type', options?: string | { name?: string; type?: string } ): this | any { - // If it's an augmentation object, register it - if (typeof action === 'object' && 'name' in action && 'type' in action) { - augmentationPipeline.register(action as IAugmentation) + // PRIMARY USE: Register new augmentation + if (typeof action === 'object' && 'name' in action) { + this.augmentations.register(action as IAugmentation) return this } - // Handle string actions + // LEGACY: Handle string actions (deprecated - use brain.augmentations instead) + console.warn(`Deprecated: brain.augment('${action}') - Use brain.augmentations.${action}() instead`) + switch (action) { case 'list': - // Return list of all augmentations with status - return this.listAugmentations() + return this.augmentations.list() case 'enable': - // Enable specific augmentation by name if (typeof options === 'string') { - this.enableAugmentation(options) + this.augmentations.enable(options) } else if (options?.name) { - this.enableAugmentation(options.name) + this.augmentations.enable(options.name) } return this case 'disable': - // Disable specific augmentation by name if (typeof options === 'string') { - this.disableAugmentation(options) + this.augmentations.disable(options) } else if (options?.name) { - this.disableAugmentation(options.name) + this.augmentations.disable(options.name) } return this case 'unregister': - // Remove augmentation from pipeline if (typeof options === 'string') { - this.unregister(options) + this.augmentations.remove(options) } else if (options?.name) { - this.unregister(options.name) + this.augmentations.remove(options.name) } return this case 'enable-type': - // Enable all augmentations of a type if (typeof options === 'string') { - const validTypes = ['sense', 'conduit', 'cognition', 'memory', 'perception', 'dialog', 'activation', 'webSocket'] as const - if (validTypes.includes(options as any)) { - return this.enableAugmentationType(options as any) - } + return this.augmentations.enableType(options as any) } else if (options?.type) { - const validTypes = ['sense', 'conduit', 'cognition', 'memory', 'perception', 'dialog', 'activation', 'webSocket'] as const - if (validTypes.includes(options.type as any)) { - return this.enableAugmentationType(options.type as any) - } + return this.augmentations.enableType(options.type as any) } throw new Error('Invalid augmentation type') case 'disable-type': - // Disable all augmentations of a type if (typeof options === 'string') { - const validTypes = ['sense', 'conduit', 'cognition', 'memory', 'perception', 'dialog', 'activation', 'webSocket'] as const - if (validTypes.includes(options as any)) { - return this.disableAugmentationType(options as any) - } + return this.augmentations.disableType(options as any) } else if (options?.type) { - const validTypes = ['sense', 'conduit', 'cognition', 'memory', 'perception', 'dialog', 'activation', 'webSocket'] as const - if (validTypes.includes(options.type as any)) { - return this.disableAugmentationType(options.type as any) - } + return this.augmentations.disableType(options.type as any) } throw new Error('Invalid augmentation type') diff --git a/src/index.ts b/src/index.ts index f76ff7b8..b29a2c2d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -339,6 +339,9 @@ import type { } from './types/augmentations.js' import { AugmentationType, BrainyAugmentations } from './types/augmentations.js' +// Export augmentation manager for type-safe augmentation management +export { AugmentationManager, type AugmentationInfo } from './augmentationManager.js' + export type { IAugmentation, AugmentationResponse, IWebSocketSupport } export { AugmentationType,