brainy/UNIFIED-API.md

🧠 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:

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
await brain.export({ format: 'json' })          // 8. Export data

📊 Before vs After: The Transformation

❌ OLD (0.x): Method Chaos

// 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

// 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.export()    // NEW: Universal data export

🔍 Deep Dive: Each Unified Method

1️⃣ add() - Smart Data Addition

Automatically detects and processes any data type intelligently.

// 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.

// 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.

// 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.

// 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.

// 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.

// 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).

// 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!

// 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.

// 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

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

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:

# 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. 🧠✨