feat: Complete the 9 Unified Methods with augment() and export()! 🎯
BREAKING CHANGE: Brainy 1.0 now has 9 unified methods (odd numbers FTW!) THE 9 UNIFIED METHODS: 1. add() - Smart data addition 2. search() - Unified search 3. import() - Bulk import 4. addNoun() - Typed entities 5. addVerb() - Relationships 6. update() - Smart updates 7. delete() - Soft delete 8. augment() - Complete augmentation management ⭐ 9. export() - Universal data export ⭐ Key improvements: - Renamed register() to augment() for consistency - Made augment() super flexible - handles ALL operations: - augment(new MyAugmentation()) - Register - augment('list') - List all with status - augment('enable', 'name') - Enable - augment('disable', 'name') - Disable - augment('unregister', 'name') - Remove - augment('enable-type', 'sense') - Bulk enable - Added export() as 9th method for data portability: - Export as JSON, CSV, Graph, or Embeddings - Filter, limit, include/exclude options - Perfect for backups, migrations, integrations Documentation: - Created AUGMENTATION-GUIDE.md - Super simple guide - Updated UNIFIED-API.md for all 9 methods - Fixed misleading community package references - Updated README with 9 methods everywhere CLI commands now perfectly mirror the API: - brainy augment <action> - Matches augment() method - brainy export - Matches export() method From 40+ methods → 9 unified methods (78% reduction!) 'Make the simple things simple, and the complex things possible'
This commit is contained in:
parent
c93df7ee8e
commit
98bf98a228
5 changed files with 795 additions and 57 deletions
407
AUGMENTATION-GUIDE.md
Normal file
407
AUGMENTATION-GUIDE.md
Normal file
|
|
@ -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!* 🚀
|
||||
33
README.md
33
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:**
|
||||
|
|
|
|||
114
UNIFIED-API.md
114
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.** 🧠✨
|
||||
|
|
@ -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 <format>', 'Export format (json, csv, graph, embeddings)', 'json')
|
||||
.option('-o, --output <file>', 'Output file path')
|
||||
.option('--vectors', 'Include vector embeddings')
|
||||
.option('--no-metadata', 'Exclude metadata')
|
||||
.option('--no-relationships', 'Exclude relationships')
|
||||
.option('--filter <json>', 'Filter by metadata')
|
||||
.option('-l, --limit <number>', '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 <action>')
|
||||
.description('Connect to Brain Cloud premium features')
|
||||
|
|
|
|||
|
|
@ -7269,15 +7269,237 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
|
|||
// ===== 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<any> {
|
||||
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<string>()
|
||||
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 }
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue