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!* 🚀
|
||||
Loading…
Add table
Add a link
Reference in a new issue