David Snelling
c93df7ee8e
- Clearly marked community augmentations as 'Coming Soon!' and ideas - Changed examples to show they are future possibilities, not current packages - Fixed cortex.register() references to use brain.register() consistently - Updated augmentation interface from ISenseAugmentation to IAugmentation - Added proper brain.register() example in augmentation creation section - Added note that community packages are examples of what could be built - Added 'Be the First!' encouragement for community builders This ensures documentation is honest about what exists vs what's possible.
356 lines
No EOL
11 KiB
Markdown
356 lines
No EOL
11 KiB
Markdown
# 🧠 Brainy 1.0: The 8 Unified Methods
|
||
|
||
> **From 40+ scattered methods to 8 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**:
|
||
|
||
```javascript
|
||
import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
|
||
|
||
const brain = new BrainyData()
|
||
await brain.init()
|
||
|
||
// 🎯 THE 8 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
|
||
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
|
||
```
|
||
|
||
## 📊 Before vs After: The Transformation
|
||
|
||
### ❌ **OLD (0.x): Method Chaos**
|
||
```javascript
|
||
// 40+ different methods for different tasks
|
||
brainy.addVector({ vector: [...], text: "..." })
|
||
brainy.addSmart(data, metadata)
|
||
brainy.searchSimilar(query, limit)
|
||
brainy.searchByMetadata(filters)
|
||
brainy.neuralImport(file)
|
||
brainy.createNoun(data, type)
|
||
brainy.createVerb(source, target, type)
|
||
brainy.updateVector(id, vector)
|
||
brainy.hardDelete(id)
|
||
brainy.softDelete(id)
|
||
// ... and 30+ more methods!
|
||
```
|
||
|
||
### ✅ **NEW (1.0): Unified Simplicity**
|
||
```javascript
|
||
// Just 8 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.
|
||
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
|
||
```
|
||
|
||
## 🔍 Deep Dive: Each Unified Method
|
||
|
||
### 1️⃣ **`add()` - Smart Data Addition**
|
||
Automatically detects and processes any data type intelligently.
|
||
|
||
```javascript
|
||
// It just works with anything!
|
||
await brain.add("Text string") // Auto-vectorizes
|
||
await brain.add({ name: "John", age: 30 }) // Auto-structures
|
||
await brain.add(complexDocument) // Auto-extracts
|
||
await brain.add(imageBuffer) // Auto-analyzes
|
||
|
||
// With options
|
||
await brain.add(data, {
|
||
id: 'custom-id', // Optional custom ID
|
||
metadata: { tags: [...] }, // Rich metadata
|
||
encrypted: true, // Encryption flag
|
||
mode: 'literal' // Force literal mode
|
||
})
|
||
```
|
||
|
||
### 2️⃣ **`search()` - Triple-Power Search**
|
||
Combines vector similarity, graph traversal, and metadata filtering.
|
||
|
||
```javascript
|
||
// Simple semantic search
|
||
const results = await brain.search("find similar content")
|
||
|
||
// With all the power
|
||
const results = await brain.search("query", 10, {
|
||
filter: { date: { $gte: "2024-01-01" } }, // Metadata filters
|
||
includeRelationships: true, // Graph context
|
||
threshold: 0.8 // Similarity threshold
|
||
})
|
||
```
|
||
|
||
### 3️⃣ **`import()` - Bulk Data Import**
|
||
Neural import with automatic structure detection.
|
||
|
||
```javascript
|
||
// Import anything
|
||
await brain.import(['item1', 'item2', 'item3']) // Array
|
||
await brain.import('data.csv') // CSV file
|
||
await brain.import('documents.json') // JSON file
|
||
await brain.import(streamSource) // Stream
|
||
|
||
// With options
|
||
await brain.import(data, {
|
||
batchSize: 1000, // Performance tuning
|
||
neural: true, // AI-powered understanding
|
||
onProgress: (p) => {} // Progress callback
|
||
})
|
||
```
|
||
|
||
### 4️⃣ **`addNoun()` - Typed Entity Creation**
|
||
Create strongly-typed entities in your knowledge graph.
|
||
|
||
```javascript
|
||
// Create typed entities
|
||
const personId = await brain.addNoun("Sarah Johnson", NounType.Person)
|
||
const companyId = await brain.addNoun("TechCorp", NounType.Organization)
|
||
const projectId = await brain.addNoun("Project X", NounType.Project)
|
||
|
||
// With rich metadata
|
||
await brain.addNoun("Product Launch", NounType.Event, {
|
||
date: "2025-03-15",
|
||
location: "San Francisco",
|
||
attendees: 500
|
||
})
|
||
```
|
||
|
||
### 5️⃣ **`addVerb()` - Relationship Creation**
|
||
Connect entities with meaningful relationships.
|
||
|
||
```javascript
|
||
// Simple relationship
|
||
await brain.addVerb(personId, companyId, VerbType.WorksFor)
|
||
|
||
// With relationship metadata (searchable!)
|
||
await brain.addVerb(personId, projectId, VerbType.WorksWith, {
|
||
role: "Lead Developer",
|
||
startDate: "2024-01-15",
|
||
allocation: "80%",
|
||
skills: ["TypeScript", "React", "Node.js"]
|
||
})
|
||
|
||
// Query relationships
|
||
const graph = await brain.getNounWithVerbs(personId)
|
||
```
|
||
|
||
### 6️⃣ **`update()` - Smart Updates**
|
||
Intelligently update data while maintaining consistency.
|
||
|
||
```javascript
|
||
// Update content
|
||
await brain.update(id, "New content")
|
||
|
||
// Update metadata only
|
||
await brain.update(id, null, {
|
||
status: "completed",
|
||
reviewedBy: "Sarah"
|
||
})
|
||
|
||
// Full update
|
||
await brain.update(id, "New content", {
|
||
tags: ["important", "reviewed"]
|
||
})
|
||
```
|
||
|
||
### 7️⃣ **`delete()` - Intelligent Deletion**
|
||
Soft delete by default for performance (no reindexing needed).
|
||
|
||
```javascript
|
||
// Soft delete (default - marks as deleted, preserves indexes)
|
||
await brain.delete(id)
|
||
|
||
// Hard delete (permanent removal)
|
||
await brain.delete(id, { hard: true })
|
||
|
||
// Cascade delete (removes relationships)
|
||
await brain.delete(id, { cascade: true })
|
||
```
|
||
|
||
### 8️⃣ **`register()` - Augmentation System** ⭐ NEW!
|
||
Extend Brainy with custom capabilities.
|
||
|
||
```javascript
|
||
// Register built-in augmentations
|
||
import { NeuralImport } from '@soulcraft/brainy'
|
||
brain.register(new NeuralImport())
|
||
|
||
// Register community augmentations (when available)
|
||
// Example: Future community packages
|
||
// import SentimentAnalyzer from 'brainy-sentiment'
|
||
// brain.register(new SentimentAnalyzer())
|
||
|
||
// Register your own augmentation
|
||
class MyCustomAugmentation {
|
||
name = 'my-custom'
|
||
type = 'sense'
|
||
|
||
async processRawData(data) {
|
||
// Your custom logic
|
||
return enhancedData
|
||
}
|
||
}
|
||
|
||
brain.register(new MyCustomAugmentation())
|
||
|
||
// Manage augmentations
|
||
brain.unregister('my-custom') // Remove
|
||
brain.enableAugmentation('neural-import') // Enable
|
||
brain.disableAugmentation('sentiment') // Disable
|
||
brain.listAugmentations() // List all
|
||
```
|
||
|
||
## 🧩 Augmentation Types & Pipeline
|
||
|
||
Augmentations extend Brainy through a pipeline architecture:
|
||
|
||
```
|
||
Data Flow Through Augmentation Pipeline:
|
||
═══════════════════════════════════════
|
||
|
||
Input Data
|
||
↓
|
||
[SENSE] - Data Understanding
|
||
• Neural Import (AI entity/relationship detection)
|
||
• Sentiment Analysis
|
||
• Language Detection
|
||
↓
|
||
[CONDUIT] - Data Transportation
|
||
• Format Conversion
|
||
• Stream Processing
|
||
• API Connectors
|
||
↓
|
||
[COGNITION] - Intelligence Layer
|
||
• Smart Categorization
|
||
• Pattern Recognition
|
||
• Anomaly Detection
|
||
↓
|
||
[MEMORY] - Storage & Retrieval
|
||
• Caching Strategies
|
||
• Compression
|
||
• Indexing
|
||
↓
|
||
Output (Enhanced Data)
|
||
```
|
||
|
||
### Creating Your Own Augmentation
|
||
|
||
```javascript
|
||
import { IAugmentation } from '@soulcraft/brainy'
|
||
|
||
export class MovieRecommender implements IAugmentation {
|
||
name = 'movie-recommender'
|
||
type = 'cognition' // sense|conduit|cognition|memory
|
||
enabled = true
|
||
description = 'AI-powered movie recommendations'
|
||
|
||
async processRawData(data) {
|
||
// Analyze user preferences
|
||
const preferences = await this.analyzePreferences(data)
|
||
|
||
// Generate recommendations
|
||
const recommendations = await this.recommend(preferences)
|
||
|
||
return {
|
||
success: true,
|
||
data: {
|
||
original: data,
|
||
recommendations,
|
||
confidence: 0.95
|
||
}
|
||
}
|
||
}
|
||
|
||
private async analyzePreferences(data) {
|
||
// Your analysis logic
|
||
}
|
||
|
||
private async recommend(preferences) {
|
||
// Your recommendation logic
|
||
}
|
||
}
|
||
|
||
// Register and use
|
||
brain.register(new MovieRecommender())
|
||
```
|
||
|
||
## 🎮 CLI: Unified Commands Match the API
|
||
|
||
The CLI perfectly mirrors the 8 unified methods:
|
||
|
||
```bash
|
||
# The 8 CLI commands match the 8 API methods
|
||
brainy add "data" # brain.add()
|
||
brainy search "query" # brain.search()
|
||
brainy import data.csv # brain.import()
|
||
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()
|
||
```
|
||
|
||
## 🚀 Why This Design?
|
||
|
||
### **Cognitive Load Reduction**
|
||
- **Before**: Remember 40+ methods and when to use each
|
||
- **After**: Master 8 methods that handle everything
|
||
|
||
### **Consistency**
|
||
- Every method follows the same pattern
|
||
- Predictable behavior across all operations
|
||
- One way to do each thing
|
||
|
||
### **Extensibility**
|
||
- Augmentations extend without breaking the core API
|
||
- Community can add features without forking
|
||
- Future-proof architecture
|
||
|
||
### **Performance**
|
||
- Soft delete by default (no reindexing)
|
||
- Smart caching built into every method
|
||
- Automatic optimization based on usage
|
||
|
||
## 📈 Migration Impact
|
||
|
||
| Metric | Before (0.x) | After (1.0) | Improvement |
|
||
|--------|--------------|-------------|-------------|
|
||
| API Methods | 40+ | 8 | **80% reduction** |
|
||
| Learning Curve | Weeks | Hours | **10x faster** |
|
||
| Code Complexity | High | Low | **Simplified** |
|
||
| Package Size | 2.52MB | 2.1MB | **16% smaller** |
|
||
| Performance | Good | Better | **Optimized** |
|
||
|
||
## 🎯 The Philosophy
|
||
|
||
**"Make the simple things simple, and the complex things possible"**
|
||
|
||
- Simple operations (add, search) are one-liners
|
||
- Complex operations (graph traversal, AI processing) are still possible
|
||
- Everything is discoverable through 8 methods
|
||
- Augmentations add power without adding complexity
|
||
|
||
## 🔮 Future-Proof
|
||
|
||
The 8 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()
|
||
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.*
|
||
|
||
**Welcome to Brainy 1.0 - Where complexity becomes simplicity.** 🧠✨ |