David Snelling
b01e3340f1
- Add missing add-noun and add-verb CLI commands for full API parity - Update CLI documentation to showcase triple-power search capabilities - Add comprehensive type-safe augmentation management system - Verify search supports vector + metadata + graph traversal in one call - All 9 unified methods now available via both API and CLI - Complete documentation accuracy fixes and cleanup
479 lines
No EOL
15 KiB
Markdown
479 lines
No EOL
15 KiB
Markdown
# 🧠 Brainy 1.0: The 9 Unified Methods
|
||
|
||
> **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 **9 core methods**:
|
||
|
||
```javascript
|
||
import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
|
||
|
||
const brain = new BrainyData()
|
||
await brain.init()
|
||
|
||
// 🎯 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
|
||
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
|
||
await brain.export({ format: 'json' }) // 8. Export data
|
||
brain.augment(myAugmentation) // 9. 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 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.
|
||
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.export() // NEW: Universal data export
|
||
brain.augment() // NEW: Extend Brainy infinitely!
|
||
```
|
||
|
||
## 🔍 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️⃣ **`augment()` - Complete Augmentation Management** ⭐ NEW!
|
||
One method handles ALL augmentation operations!
|
||
|
||
```javascript
|
||
// Register new augmentations
|
||
import { NeuralImport } from '@soulcraft/brainy'
|
||
brain.augment(new NeuralImport()) // Add capability
|
||
|
||
// 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
|
||
|
||
// 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) {
|
||
return { ...data, enhanced: true }
|
||
}
|
||
}
|
||
|
||
// 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
|
||
```
|
||
|
||
### 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 }, ...]
|
||
```
|
||
|
||
### 9️⃣ **`augment()` - The Infinity Method** ♾️
|
||
|
||
**This is the magic 9th method that makes Brainy infinitely extensible!**
|
||
|
||
```javascript
|
||
// PRIMARY USE: Add ANY capability you can imagine
|
||
brain.augment(new SentimentAnalyzer()) // Add sentiment analysis
|
||
brain.augment(new LanguageTranslator()) // Add translation
|
||
brain.augment(new CustomProcessor()) // Add your own!
|
||
```
|
||
|
||
### 🎯 **NEW: Type-Safe Augmentation Management**
|
||
|
||
Brainy 1.0 introduces `brain.augmentations` for type-safe management:
|
||
|
||
```typescript
|
||
// Full TypeScript support & IDE autocomplete!
|
||
brain.augmentations.list() // Returns AugmentationInfo[]
|
||
brain.augmentations.enable('sentiment') // Enable specific augmentation
|
||
brain.augmentations.disable('sentiment') // Disable temporarily
|
||
brain.augmentations.remove('sentiment') // Remove completely
|
||
|
||
// Query augmentation status
|
||
brain.augmentations.get('sentiment') // Get specific info
|
||
brain.augmentations.isEnabled('sentiment') // Check if enabled
|
||
|
||
// Manage by type (with enum for type safety)
|
||
brain.augmentations.enableType(AugmentationType.PROCESSOR)
|
||
brain.augmentations.disableType(AugmentationType.MEMORY)
|
||
brain.augmentations.listByType(AugmentationType.DIALOG)
|
||
|
||
// Filter augmentations
|
||
brain.augmentations.listEnabled() // All active augmentations
|
||
brain.augmentations.listDisabled() // All inactive ones
|
||
|
||
```
|
||
|
||
### 📝 **Complete Example with TypeScript**
|
||
|
||
```typescript
|
||
import { BrainyData, AugmentationType, IAugmentation } from '@soulcraft/brainy'
|
||
|
||
// Create your augmentation with full type safety
|
||
class SentimentAnalyzer implements IAugmentation {
|
||
readonly name = 'sentiment-analyzer'
|
||
readonly description = 'Analyzes emotional tone of text'
|
||
enabled = true
|
||
|
||
async initialize() { /* setup */ }
|
||
async shutDown() { /* cleanup */ }
|
||
async getStatus() { return 'active' as const }
|
||
|
||
async analyze(text: string): Promise<'positive' | 'negative' | 'neutral'> {
|
||
// Your sentiment logic here
|
||
return 'positive'
|
||
}
|
||
}
|
||
|
||
const brain = new BrainyData()
|
||
const sentiment = new SentimentAnalyzer()
|
||
|
||
// Register with the 9th method
|
||
brain.augment(sentiment)
|
||
|
||
// Type-safe management
|
||
if (brain.augmentations.isEnabled('sentiment-analyzer')) {
|
||
console.log('Sentiment analysis is active!')
|
||
}
|
||
|
||
// List all processor-type augmentations
|
||
const processors = brain.augmentations.listByType(AugmentationType.PROCESSOR)
|
||
```
|
||
|
||
**Why augment() is special:**
|
||
- 🚀 **Infinite Extensibility** - Add any feature you can imagine
|
||
- 🧩 **Plugin Architecture** - Share augmentations with the community
|
||
- 🔧 **Runtime Flexibility** - Enable/disable features on the fly
|
||
- 🎯 **Zero Core Bloat** - Keep Brainy lean, add only what you need
|
||
|
||
## 🧩 Augmentation Types & Pipeline
|
||
|
||
Augmentations extend Brainy through a pipeline architecture:
|
||
|
||
```
|
||
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 9 unified methods:
|
||
|
||
```bash
|
||
# 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()
|
||
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.augment()
|
||
brainy export --format json --output data.json # brain.export()
|
||
```
|
||
|
||
## 🚀 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+ | 9 | **78% 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 9 methods (odd numbers FTW! 🎯)
|
||
- Augmentations add power without adding complexity
|
||
|
||
## 🔮 Future-Proof
|
||
|
||
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 augment()
|
||
3. **Brain Cloud** - Premium features without API changes
|
||
|
||
This ensures your code written today will work with future versions.
|
||
|
||
---
|
||
|
||
*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.** 🧠✨ |