diff --git a/AUGMENTATION-GUIDE.md b/AUGMENTATION-GUIDE.md new file mode 100644 index 00000000..62e8da53 --- /dev/null +++ b/AUGMENTATION-GUIDE.md @@ -0,0 +1,407 @@ +# 🧩 Brainy Augmentation System - Super Simple Guide + +> **Augmentations = Plugins = Superpowers for your Brain!** + +## 🎯 What Are Augmentations? + +Think of augmentations as **plugins** that give Brainy new abilities: +- 🎭 **Sentiment Analysis** → Understand emotions in text +- 🌍 **Translation** → Work with multiple languages +- 📧 **Email Parser** → Extract structured data from emails +- 🎨 **Image Understanding** → Analyze visual content +- ✨ **Anything You Can Imagine** → Build your own! + +## ⚡ Using Augmentations - It's Just ONE Method! + +```javascript +const brain = new BrainyData() + +// That's it! Just use augment() for everything: +brain.augment(myAugmentation) // Add new capability +brain.augment('sentiment', 'enable') // Turn on +brain.augment('sentiment', 'disable') // Turn off +``` + +## 🚀 Quick Start: Your First Augmentation in 30 Seconds + +```javascript +// 1. Create your augmentation (it's just a class!) +class EmojiAnalyzer { + name = 'emoji-analyzer' + type = 'sense' // When it runs in the pipeline + enabled = true + + async processRawData(data) { + // Your magic happens here! + const emojis = data.match(/[\u{1F300}-\u{1F9FF}]/gu) || [] + + return { + success: true, + data: { + original: data, + emojiCount: emojis.length, + emojis: emojis, + mood: emojis.length > 3 ? 'very expressive!' : 'subtle' + } + } + } +} + +// 2. Add it to Brainy +brain.augment(new EmojiAnalyzer()) + +// 3. Now ALL your data gets emoji analysis automatically! +await brain.add("I love this! 😍🎉🚀") +// Data is automatically enhanced with emoji analysis +``` + +## 📊 The Pipeline - How Data Flows + +Think of it like an **assembly line** where each station adds something: + +``` +Your Data: "Hello World" + ↓ +📥 INPUT → Your raw data enters + ↓ +🧠 SENSE → AI understands it (NeuralImport, EmojiAnalyzer) + ↓ +🔄 CONDUIT → Transform it (Formatters, Converters) + ↓ +💭 COGNITION → Add intelligence (Categorization, Sentiment) + ↓ +💾 MEMORY → Store smartly (Compression, Indexing) + ↓ +📤 OUTPUT → Enhanced data with superpowers! +``` + +## 🎨 Augmentation Types - Where Does Yours Fit? + +### 🧠 **SENSE** - Understanding Raw Data +*First to see the data, extracts meaning* +```javascript +type = 'sense' +// Examples: Language detection, Entity extraction, OCR +// Use when: You need to understand or extract from raw input +``` + +### 🔄 **CONDUIT** - Data Transportation +*Moves and transforms data between systems* +```javascript +type = 'conduit' +// Examples: API connectors, Format converters, Stream processors +// Use when: You need to connect to external systems or transform formats +``` + +### 💭 **COGNITION** - Adding Intelligence +*Makes data smarter with AI and analysis* +```javascript +type = 'cognition' +// Examples: Sentiment analysis, Classification, Recommendations +// Use when: You need to add AI-powered insights +``` + +### 💾 **MEMORY** - Storage Optimization +*Optimizes how data is stored and retrieved* +```javascript +type = 'memory' +// Examples: Compression, Caching strategies, Indexing +// Use when: You need to optimize storage or retrieval +``` + +## 🏗️ Building Augmentations - The Complete Template + +```javascript +class YourAmazingAugmentation { + // Required properties + name = 'your-amazing' // Unique identifier + type = 'cognition' // Where in pipeline (sense|conduit|cognition|memory) + enabled = true // Start enabled? + + // Optional but recommended + description = 'Does amazing things with your data' + version = '1.0.0' + author = 'Your Name' + + // The magic method - called for EVERY piece of data + async processRawData(data, context) { + // 1. Analyze the input + const analysis = await this.analyze(data) + + // 2. Enhance it somehow + const enhanced = this.enhance(analysis) + + // 3. Return the enhanced version + return { + success: true, + data: { + ...enhanced, + _augmentedBy: this.name, + _confidence: 0.95 + } + } + } + + // Optional lifecycle hooks + async initialize() { + // Called once when augmentation is registered + // Load models, connect to services, etc. + } + + async cleanup() { + // Called when augmentation is unregistered + // Close connections, free memory, etc. + } + + // Your helper methods + async analyze(data) { + // Your analysis logic + return { /* analysis results */ } + } + + enhance(analysis) { + // Your enhancement logic + return { /* enhanced data */ } + } +} +``` + +## 🎯 Real-World Examples + +### Example 1: Profanity Filter +```javascript +class ProfanityFilter { + name = 'profanity-filter' + type = 'sense' // Checks data as it comes in + + badWords = ['badword1', 'badword2'] // Your list + + async processRawData(data) { + const text = String(data).toLowerCase() + const found = this.badWords.filter(word => text.includes(word)) + + return { + success: true, + data: { + original: data, + hasProfanity: found.length > 0, + profanityCount: found.length, + cleaned: this.clean(data, found) + } + } + } + + clean(text, words) { + let cleaned = text + words.forEach(word => { + cleaned = cleaned.replace(new RegExp(word, 'gi'), '***') + }) + return cleaned + } +} +``` + +### Example 2: Auto-Tagger +```javascript +class AutoTagger { + name = 'auto-tagger' + type = 'cognition' // Adds intelligence + + async processRawData(data) { + const text = String(data).toLowerCase() + const tags = [] + + // Simple rule-based tagging + if (text.includes('urgent') || text.includes('asap')) { + tags.push('high-priority') + } + if (text.includes('bug') || text.includes('error')) { + tags.push('bug-report') + } + if (text.includes('feature') || text.includes('request')) { + tags.push('feature-request') + } + + return { + success: true, + data: { + original: data, + suggestedTags: tags, + autoTagged: true + } + } + } +} +``` + +### Example 3: Data Compressor +```javascript +class SmartCompressor { + name = 'smart-compressor' + type = 'memory' // Optimizes storage + + async processRawData(data) { + const json = JSON.stringify(data) + + // Only compress if it's worth it + if (json.length < 1000) { + return { success: true, data } + } + + // Simple compression (real implementation would use zlib) + const compressed = this.compress(json) + + return { + success: true, + data: { + _compressed: true, + _originalSize: json.length, + _compressedSize: compressed.length, + _ratio: (compressed.length / json.length).toFixed(2), + data: compressed + } + } + } + + compress(text) { + // Your compression logic here + return text // Placeholder + } +} +``` + +## 🚀 Advanced: Augmentation Coordination + +Augmentations can work together! They see each other's enhancements: + +```javascript +// First augmentation adds sentiment +class SentimentAnalyzer { + async processRawData(data) { + return { + success: true, + data: { + ...data, + sentiment: 'positive', + sentimentScore: 0.8 + } + } + } +} + +// Second augmentation uses sentiment to add emojis +class SmartEmojiAdder { + async processRawData(data) { + // Can see the sentiment from previous augmentation! + const emoji = data.sentiment === 'positive' ? '😊' : '😔' + + return { + success: true, + data: { + ...data, + enhancedText: data.original + ' ' + emoji + } + } + } +} + +// Register both - they work together! +brain.augment(new SentimentAnalyzer()) +brain.augment(new SmartEmojiAdder()) +``` + +## 📦 Sharing Your Augmentation + +### 1. Package It +```json +// package.json +{ + "name": "brainy-emoji-analyzer", + "version": "1.0.0", + "main": "index.js", + "keywords": ["brainy", "augmentation", "emoji"], + "peerDependencies": { + "@soulcraft/brainy": "^1.0.0" + } +} +``` + +### 2. Export It +```javascript +// index.js +export default class EmojiAnalyzer { + // Your augmentation code +} +``` + +### 3. Share It +```bash +npm publish brainy-emoji-analyzer +``` + +### 4. Others Use It +```javascript +import EmojiAnalyzer from 'brainy-emoji-analyzer' +brain.augment(new EmojiAnalyzer()) +``` + +## 🎮 CLI Commands + +```bash +# List all augmentations +brainy augment list + +# Enable/disable +brainy augment enable --name emoji-analyzer +brainy augment disable --name emoji-analyzer + +# Register from file +brainy augment register --path ./my-augmentation.js + +# Enable all of a type +brainy augment enable-type --type sense +``` + +## 💡 Pro Tips + +1. **Start Simple** - Your first augmentation can be 10 lines of code +2. **One Thing Well** - Each augmentation should do ONE thing excellently +3. **Chain Them** - Multiple simple augmentations > one complex augmentation +4. **Use Types** - Pick the right type so your augmentation runs at the right time +5. **Return Quickly** - Don't block the pipeline with slow operations +6. **Handle Errors** - Always return `{success: false, error: message}` on failure +7. **Add Metadata** - Include confidence scores, processing time, etc. +8. **Test in Isolation** - Test your augmentation before registering + +## 🤔 FAQ + +**Q: Can I use external APIs in my augmentation?** +A: Yes! Just handle errors gracefully and consider caching. + +**Q: How many augmentations can I have?** +A: No limit! But each one adds processing time. + +**Q: Can augmentations modify the original data?** +A: They should enhance, not replace. Always include the original. + +**Q: What if my augmentation fails?** +A: Return `{success: false}` and Brainy continues with the original data. + +**Q: Can I use AI models in augmentations?** +A: Absolutely! That's what they're perfect for. + +## 🎯 Your Turn! + +Now you know everything! Build an augmentation and share it with the community. Start with something simple: + +- **Emoji Counter** - Count emojis in text +- **URL Extractor** - Find all URLs in content +- **Word Counter** - Add word/character statistics +- **Language Detector** - Detect text language +- **Markdown Parser** - Extract structure from markdown + +Remember: **Every amazing augmentation started with someone thinking "What if Brainy could..."** + +--- + +*Go build something awesome! The community is waiting for your augmentation!* 🚀 \ No newline at end of file diff --git a/README.md b/README.md index 1fb945a8..7c1e3590 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,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 **7 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 the latest release candidate @@ -35,18 +35,20 @@ import { BrainyData, NounType, VerbType } from '@soulcraft/brainy' const brain = new BrainyData() await brain.init() -// 🎯 THE 7 UNIFIED METHODS: -const id1 = await brain.add("Smart data addition") // 1. Smart addition -const id2 = await brain.addNoun("John Doe", NounType.Person) // 2. Typed entities -const verb = await brain.addVerb(id1, id2, VerbType.CreatedBy) // 3. Relationships -const results = await brain.search("smart data", 10) // 4. Vector search -const ids = await brain.import(["data1", "data2"]) // 5. Bulk import -await brain.update(id1, "Updated data") // 6. Smart updates -await brain.delete(verb) // 7. Soft delete +// 🎯 THE 9 UNIFIED METHODS: +await brain.add("Smart data addition") // 1. Smart addition +await brain.search("smart data", 10) // 2. Vector search +await brain.import(["data1", "data2"]) // 3. Bulk import +await brain.addNoun("John Doe", NounType.Person) // 4. Typed entities +await brain.addVerb(id1, id2, VerbType.CreatedBy) // 5. Relationships +await brain.update(id1, "Updated data") // 6. Smart updates +await brain.delete(id) // 7. Soft delete +brain.augment(myAugmentation) // 8. Add capabilities +await brain.export({ format: 'json' }) // 9. Export data ``` ### ✨ **What's New in 1.0:** -- **🔥 40+ methods consolidated** → 7 unified methods +- **🔥 40+ methods consolidated** → 9 unified methods - **🧠 Smart by default** - `add()` auto-detects and processes intelligently - **🔐 Universal encryption** - Built-in encryption for sensitive data - **🐳 Container ready** - Model preloading for production deployments @@ -96,9 +98,10 @@ Vector + Graph + Search + AI = Brainy (Free & Open Source) = 🧠✨ pinecone.upsert(), neo4j.run(), elasticsearch.search() supabase.insert(), mongodb.find(), redis.set() -// After: 7 methods handle everything -brain.add(), brain.search(), brain.addNoun(), brain.addVerb() -brain.import(), brain.update(), brain.delete() +// After: 9 methods handle EVERYTHING +brain.add(), brain.search(), brain.import() +brain.addNoun(), brain.addVerb(), brain.update() +brain.delete(), brain.augment(), brain.export() ``` #### **🤯 Mind-Blowing Features Out of the Box** @@ -571,10 +574,12 @@ const insights = await agentBrain.getRelated("enterprise plan") ``` ### **What Makes 1.0 Different:** -- **🎯 One API**: 7 methods handle everything (was 40+ methods) +- **🎯 One API**: 9 methods handle everything (was 40+ methods) - **🧠 Smart Core**: Automatic data understanding and processing - **🔗 Graph Built-in**: Relationships are first-class citizens - **🔐 Security Native**: Encryption integrated, not bolted-on +- **🧩 Extensible**: Augment with custom capabilities +- **📤 Portable**: Export in any format (json, csv, graph) - **⚡ Zero Config**: Works perfectly out of the box ### **The Magic:** diff --git a/UNIFIED-API.md b/UNIFIED-API.md index 16bbbe2d..068b8c32 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 @@ -20,7 +20,8 @@ await brain.addNoun("John", NounType.Person) // 4. Typed entities 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 -brain.register(myAugmentation) // 8. Extend capabilities +brain.augment(myAugmentation) // 8. Extend capabilities +await brain.export({ format: 'json' }) // 9. Export data ``` ## 📊 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. @@ -51,7 +52,8 @@ brain.addNoun() // Replaces: createNoun, addEntity, createNode, etc. brain.addVerb() // Replaces: createVerb, addRelationship, connect, etc. brain.update() // Replaces: updateVector, updateMetadata, modify, etc. brain.delete() // Replaces: hardDelete, softDelete, remove, etc. -brain.register() // NEW: Unified augmentation system +brain.augment() // NEW: Unified augmentation system +brain.export() // NEW: Universal data export ``` ## 🔍 Deep Dive: Each Unified Method @@ -177,37 +179,78 @@ await brain.delete(id, { hard: true }) await brain.delete(id, { cascade: true }) ``` -### 8️⃣ **`register()` - Augmentation System** ⭐ NEW! -Extend Brainy with custom capabilities. +### 8️⃣ **`augment()` - Complete Augmentation Management** ⭐ NEW! +One method handles ALL augmentation operations! ```javascript -// Register built-in augmentations +// Register new augmentations import { NeuralImport } from '@soulcraft/brainy' -brain.register(new NeuralImport()) +brain.augment(new NeuralImport()) // Add capability -// Register community augmentations (when available) -// Example: Future community packages -// import SentimentAnalyzer from 'brainy-sentiment' -// brain.register(new SentimentAnalyzer()) +// Manage existing augmentations +brain.augment('enable', 'neural-import') // Enable by name +brain.augment('disable', 'sentiment') // Disable by name +brain.augment('unregister', 'old-augment') // Remove completely -// Register your own augmentation -class MyCustomAugmentation { - name = 'my-custom' - type = 'sense' +// List all augmentations +const all = brain.augment('list') // Returns array with status +// [ +// { name: 'neural-import', type: 'sense', enabled: true }, +// { name: 'sentiment', type: 'cognition', enabled: false } +// ] + +// Bulk operations by type +brain.augment('enable-type', 'sense') // Enable all sense augmentations +brain.augment('disable-type', 'cognition') // Disable all cognition augmentations + +// Create your own augmentation +class MyAugmentation { + name = 'my-augment' + type = 'cognition' async processRawData(data) { - // Your custom logic - return enhancedData + return { ...data, enhanced: true } } } -brain.register(new MyCustomAugmentation()) +// One method, complete control +brain.augment(new MyAugmentation()) // Register +brain.augment('enable', 'my-augment') // Enable +brain.augment('disable', 'my-augment') // Disable +brain.augment('unregister', 'my-augment') // Remove +``` -// Manage augmentations -brain.unregister('my-custom') // Remove -brain.enableAugmentation('neural-import') // Enable -brain.disableAugmentation('sentiment') // Disable -brain.listAugmentations() // List all +### 9️⃣ **`export()` - Universal Data Export** ⭐ NEW! +Export your brain's knowledge in any format. + +```javascript +// Export everything as JSON +const allData = await brain.export() + +// Export with options +const data = await brain.export({ + format: 'csv', // json|csv|graph|embeddings + includeVectors: true, // Include vector embeddings + includeMetadata: true, // Include metadata + includeRelationships: true, // Include graph relationships + filter: { type: 'Person' }, // Filter by metadata + limit: 1000 // Limit results +}) + +// Export formats: +// JSON - Complete data structure +const json = await brain.export({ format: 'json' }) + +// CSV - Spreadsheet compatible +const csv = await brain.export({ format: 'csv' }) + +// Graph - Nodes and edges for visualization +const graph = await brain.export({ format: 'graph' }) +// Returns: { nodes: [...], edges: [...] } + +// Embeddings - Just vectors for ML pipelines +const vectors = await brain.export({ format: 'embeddings' }) +// Returns: [{ id, vector }, ...] ``` ## 🧩 Augmentation Types & Pipeline @@ -286,10 +329,10 @@ brain.register(new MovieRecommender()) ## 🎮 CLI: Unified Commands Match the API -The CLI perfectly mirrors the 8 unified methods: +The CLI perfectly mirrors the 9 unified methods: ```bash -# The 8 CLI commands match the 8 API methods +# The 9 CLI commands match the 9 API methods brainy add "data" # brain.add() brainy search "query" # brain.search() brainy import data.csv # brain.import() @@ -297,7 +340,8 @@ brainy add-noun "John" --type Person # brain.addNoun() brainy add-verb id1 id2 --type WorksWith # brain.addVerb() brainy update id "new data" # brain.update() brainy delete id # brain.delete() -brainy augment register ./my-augmentation.js # brain.register() +brainy augment register ./my-augmentation.js # brain.augment() +brainy export --format json --output data.json # brain.export() ``` ## 🚀 Why This Design? @@ -325,7 +369,7 @@ brainy augment register ./my-augmentation.js # brain.register() | Metric | Before (0.x) | After (1.0) | Improvement | |--------|--------------|-------------|-------------| -| API Methods | 40+ | 8 | **80% reduction** | +| API Methods | 40+ | 9 | **78% reduction** | | Learning Curve | Weeks | Hours | **10x faster** | | Code Complexity | High | Low | **Simplified** | | Package Size | 2.52MB | 2.1MB | **16% smaller** | @@ -337,20 +381,20 @@ brainy augment register ./my-augmentation.js # brain.register() - Simple operations (add, search) are one-liners - Complex operations (graph traversal, AI processing) are still possible -- Everything is discoverable through 8 methods +- Everything is discoverable through 9 methods (odd numbers FTW! 🎯) - Augmentations add power without adding complexity ## 🔮 Future-Proof -The 8 unified methods will remain stable. New features will be added through: +The 9 unified methods will remain stable. New features will be added through: 1. **Method options** - New parameters to existing methods -2. **Augmentations** - Extended capabilities via register() +2. **Augmentations** - Extended capabilities via augment() 3. **Brain Cloud** - Premium features without API changes This ensures your code written today will work with future versions. --- -*The 8 Unified Methods represent the culmination of our learning from thousands of users and millions of operations. This is the API we wish we had from day one.* +*The 9 Unified Methods represent the culmination of our learning from thousands of users and millions of operations. This is the API we wish we had from day one.* **Welcome to Brainy 1.0 - Where complexity becomes simplicity.** 🧠✨ \ No newline at end of file diff --git a/bin/brainy.js b/bin/brainy.js index 09c0e41e..3a26d79c 100755 --- a/bin/brainy.js +++ b/bin/brainy.js @@ -1006,7 +1006,67 @@ program } })) -// Command 7: CLOUD - Premium features connection +// Command 7: EXPORT - Export your data +program + .command('export') + .description('Export your brain data in various formats') + .option('-f, --format ', 'Export format (json, csv, graph, embeddings)', 'json') + .option('-o, --output ', 'Output file path') + .option('--vectors', 'Include vector embeddings') + .option('--no-metadata', 'Exclude metadata') + .option('--no-relationships', 'Exclude relationships') + .option('--filter ', 'Filter by metadata') + .option('-l, --limit ', 'Limit number of items') + .action(wrapAction(async (options) => { + const brainy = await initBrainy() + console.log(colors.brain('📤 Exporting Brain Data')) + + const spinner = ora('Exporting data...').start() + + try { + const exportOptions = { + format: options.format, + includeVectors: options.vectors || false, + includeMetadata: options.metadata !== false, + includeRelationships: options.relationships !== false, + filter: options.filter ? JSON.parse(options.filter) : {}, + limit: options.limit ? parseInt(options.limit) : undefined + } + + const data = await brainy.export(exportOptions) + + spinner.succeed('Export complete') + + if (options.output) { + // Write to file + const fs = require('fs') + const content = typeof data === 'string' ? data : JSON.stringify(data, null, 2) + fs.writeFileSync(options.output, content) + console.log(colors.success(`✅ Exported to: ${options.output}`)) + + // Show summary + const items = Array.isArray(data) ? data.length : (data.nodes ? data.nodes.length : 1) + console.log(colors.info(`📊 Format: ${options.format}`)) + console.log(colors.info(`📁 Items: ${items}`)) + if (options.vectors) { + console.log(colors.info(`🔢 Vectors: Included`)) + } + } else { + // Output to console + if (typeof data === 'string') { + console.log(data) + } else { + console.log(JSON.stringify(data, null, 2)) + } + } + } catch (error) { + spinner.fail('Export failed') + console.error(colors.error(error.message)) + process.exit(1) + } + })) + +// Command 8: CLOUD - Premium features connection program .command('cloud ') .description('Connect to Brain Cloud premium features') diff --git a/src/brainyData.ts b/src/brainyData.ts index 0a98b29f..f3546cc9 100644 --- a/src/brainyData.ts +++ b/src/brainyData.ts @@ -7269,15 +7269,237 @@ export class BrainyData implements BrainyDataInterface { // ===== Augmentation Control Methods ===== /** - * UNIFIED API METHOD #8: Register an augmentation - * Add custom augmentations to extend Brainy's capabilities + * UNIFIED API METHOD #8: Augment - Complete augmentation management + * Register, enable, disable, list, and manage augmentations * - * @param augmentation The augmentation to register - * @returns The BrainyData instance for chaining + * @param action The action to perform or augmentation to register + * @param options Additional options for the action + * @returns Various return types based on action */ - register(augmentation: IAugmentation): this { - augmentationPipeline.register(augmentation) - return this + 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) + return this + } + + // Handle string actions + switch (action) { + case 'list': + // Return list of all augmentations with status + return this.listAugmentations() + + case 'enable': + // Enable specific augmentation by name + if (typeof options === 'string') { + this.enableAugmentation(options) + } else if (options?.name) { + this.enableAugmentation(options.name) + } + return this + + case 'disable': + // Disable specific augmentation by name + if (typeof options === 'string') { + this.disableAugmentation(options) + } else if (options?.name) { + this.disableAugmentation(options.name) + } + return this + + case 'unregister': + // Remove augmentation from pipeline + if (typeof options === 'string') { + this.unregister(options) + } else if (options?.name) { + this.unregister(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) + } + } 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) + } + } + 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) + } + } 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) + } + } + throw new Error('Invalid augmentation type') + + default: + throw new Error(`Unknown augment action: ${action}`) + } + } + + /** + * UNIFIED API METHOD #9: Export - Extract your data in various formats + * Export your brain's knowledge for backup, migration, or integration + * + * @param options Export configuration + * @returns The exported data in the specified format + */ + async export(options: { + format?: 'json' | 'csv' | 'graph' | 'embeddings' + includeVectors?: boolean + includeMetadata?: boolean + includeRelationships?: boolean + filter?: any + limit?: number + } = {}): Promise { + const { + format = 'json', + includeVectors = false, + includeMetadata = true, + includeRelationships = true, + filter = {}, + limit + } = options + + // Get all data with optional filtering + const nounsResult = await this.getNouns() + const allNouns = nounsResult.items || [] + let exportData: any[] = [] + + // Apply filters and limits + let nouns = allNouns + if (Object.keys(filter).length > 0) { + nouns = allNouns.filter((noun: any) => { + return Object.entries(filter).every(([key, value]) => { + return noun.metadata?.[key] === value + }) + }) + } + if (limit) { + nouns = nouns.slice(0, limit) + } + + // Build export data + for (const noun of nouns) { + const exportItem: any = { + id: noun.id, + text: (noun as any).text || (noun.metadata as any)?.text || noun.id + } + + if (includeVectors && noun.vector) { + exportItem.vector = noun.vector + } + + if (includeMetadata && noun.metadata) { + exportItem.metadata = noun.metadata + } + + if (includeRelationships) { + const relationships = await this.getNounWithVerbs(noun.id) + const allVerbs = [ + ...(relationships?.incomingVerbs || []), + ...(relationships?.outgoingVerbs || []) + ] + if (allVerbs.length > 0) { + exportItem.relationships = allVerbs + } + } + + exportData.push(exportItem) + } + + // Format output based on requested format + switch (format) { + case 'csv': + return this.convertToCSV(exportData) + case 'graph': + return this.convertToGraphFormat(exportData) + case 'embeddings': + return exportData.map(item => ({ + id: item.id, + vector: item.vector || [] + })) + case 'json': + default: + return exportData + } + } + + /** + * Helper: Convert data to CSV format + * @private + */ + private convertToCSV(data: any[]): string { + if (data.length === 0) return '' + + // Get all unique keys + const keys = new Set() + data.forEach(item => { + Object.keys(item).forEach(key => keys.add(key)) + }) + + // Create header + const headers = Array.from(keys) + const csv = [headers.join(',')] + + // Add data rows + data.forEach(item => { + const row = headers.map(header => { + const value = item[header] + if (typeof value === 'object') { + return JSON.stringify(value) + } + return value || '' + }) + csv.push(row.join(',')) + }) + + return csv.join('\n') + } + + /** + * Helper: Convert data to graph format + * @private + */ + private convertToGraphFormat(data: any[]): any { + const nodes = data.map(item => ({ + id: item.id, + label: item.text || item.id, + metadata: item.metadata + })) + + const edges: any[] = [] + data.forEach(item => { + if (item.relationships) { + item.relationships.forEach((rel: any) => { + edges.push({ + source: item.id, + target: rel.targetId, + type: rel.verbType, + metadata: rel.metadata + }) + }) + } + }) + + return { nodes, edges } } /**