@soulcraft/brainy 0.63.0 → 1.0.0-rc.2

package/README.md

@@ -3,9 +3,10 @@
 ![Brainy Logo](brainy.png)
 
 [![npm version](https://badge.fury.io/js/%40soulcraft%2Fbrainy.svg)](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
+[![1.0 RC](https://img.shields.io/badge/1.0-Release%20Candidate-orange.svg)](https://github.com/soulcraftlabs/brainy/releases/tag/v1.0.0-rc.1)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Try Demo](https://img.shields.io/badge/Try%20Demo-Live-green.svg)](https://soulcraft.com)
-[![Brain Cloud](https://img.shields.io/badge/Brain%20Cloud-Early%20Access-blue.svg)](https://soulcraft.com/brain-cloud)
+[![Website](https://img.shields.io/badge/Website-soulcraft.com-green.svg)](https://soulcraft.com)
+[![Brain Cloud](https://img.shields.io/badge/Brain%20Cloud-Coming%20Soon-blue.svg)](https://soulcraft.com)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.4.1-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4.5-blue.svg)](https://www.typescriptlang.org/)
 
@@ -19,6 +20,61 @@
 
 ---
 
+## 💖 **Support Brainy's Development**
+
+<div align="center">
+
+**Brainy is 100% open source and free forever!** Help us keep it that way:
+
+[![Sponsor](https://img.shields.io/badge/💖_Sponsor_Brainy-Support_Development-ff69b4?style=for-the-badge)](https://github.com/soulcraftlabs/brainy)
+[![Brain Cloud](https://img.shields.io/badge/☁️_Try_Brain_Cloud-Coming_Soon-4A90E2?style=for-the-badge)](https://soulcraft.com)
+[![Star](https://img.shields.io/badge/⭐_Star_on_GitHub-Show_Support-FFC107?style=for-the-badge)](https://github.com/soulcraftlabs/brainy)
+
+**Every sponsorship helps us:** Build more features • Fix bugs faster • Keep Brainy free
+
+</div>
+
+---
+
+## 🎉 **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 **9 core methods**:
+
+```bash
+# Install the latest release candidate
+npm install @soulcraft/brainy@rc
+```
+
+```javascript
+import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
+
+const brain = new BrainyData()
+await brain.init()
+
+// 🎯 THE 9 UNIFIED METHODS - One way to do everything!
+await brain.add("Smart data")                    // 1. Smart 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.augment(myAugmentation)                   // 8. Extend capabilities
+await brain.export({ format: 'json' })          // 9. Export data
+```
+
+### ✨ **What's New in 1.0:**
+- **🔥 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
+- **📦 16% smaller package** despite major new features
+- **🔄 Soft delete default** - Better performance, no reindexing needed
+
+**Breaking Changes:** See [MIGRATION.md](MIGRATION.md) for complete upgrade guide.
+
+---
+
 ## ✅ 100% Free & Open Source
 
 **Brainy is completely free. No license keys. No limits. No catch.**
@@ -35,11 +91,57 @@ Every feature you see here works without any payment or registration:
 
 ---
 
+## 💫 Why Brainy? The Problem We Solve
+
+### ❌ **The Old Way: Database Frankenstein**
+```
+Pinecone ($750/mo) + Neo4j ($500/mo) + Elasticsearch ($300/mo) + 
+Sync nightmares + 3 different APIs + Vendor lock-in = 😱💸
+```
+
+### ✅ **The Brainy Way: One Brain, All Dimensions**
+```
+Vector + Graph + Search + AI = Brainy (Free & Open Source) = 🧠✨
+```
+
+**Your data gets superpowers. Your wallet stays happy.**
+
+### 🧠 **Why Developers Love Brainy 1.0**
+
+#### **⚡ One API to Rule Them All**
+```javascript
+// Before: Learning 10+ different database APIs
+pinecone.upsert(), neo4j.run(), elasticsearch.search()
+supabase.insert(), mongodb.find(), redis.set()
+
+// 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**
+- **Smart by Default**: `add()` automatically understands your data
+- **Graph + Vector**: Relationships AND semantic similarity in one query  
+- **Zero Config**: Works instantly, optimizes itself
+- **Universal Encryption**: Secure everything with one flag
+- **Perfect Memory**: Nothing ever gets lost or forgotten
+
+#### **💰 Cost Comparison**
+| Traditional Stack | Monthly Cost | Brainy 1.0 |
+|------------------|--------------|-------------|
+| Pinecone + Neo4j + Search | $1,500+ | **$0** |
+| 3 different APIs to learn | Weeks | **Minutes** |
+| Sync complexity | High | **None** |
+| Vendor lock-in | Yes | **MIT License** |
+
+---
+
 ## 🚀 What Can You Build?
 
 ### 💬 **AI Chat Apps** - That Actually Remember
 ```javascript
-// Your users' conversations persist across sessions
+// Your users' conversations persist across sessions  
 const brain = new BrainyData()
 await brain.add("User prefers dark mode")
 await brain.add("User is learning Spanish")
@@ -51,17 +153,30 @@ const context = await brain.search("user preferences")
 
 ### 🤖 **Smart Assistants** - With Real Knowledge Graphs
 ```javascript
-// Build assistants that understand relationships
-await brain.add("Sarah manages the design team")
-await brain.addVerb("Sarah", "reports_to", "John")
-await brain.addVerb("Sarah", "works_on", "Project Apollo")
-
-// Query complex relationships
-const team = await brain.getRelated("Project Apollo", {
-  verb: "works_on",
-  depth: 2
+// Build assistants that understand relationships (NEW 1.0 API!)
+import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
+
+const brain = new BrainyData()
+await brain.init()
+
+// Create typed entities
+const sarahId = await brain.addNoun("Sarah Thompson", NounType.Person)
+const johnId = await brain.addNoun("John Davis", NounType.Person) 
+const projectId = await brain.addNoun("Project Apollo", NounType.Project)
+
+// Create relationships with metadata
+await brain.addVerb(sarahId, johnId, VerbType.ReportsTo, {
+  role: "Design Manager",
+  startDate: "2024-01-15"
 })
-// Returns: entire team structure with relationships
+await brain.addVerb(sarahId, projectId, VerbType.WorksWith, {
+  responsibility: "Lead Designer",
+  allocation: "75%"
+})
+
+// Query complex relationships with graph traversal
+const sarahData = await brain.getNounWithVerbs(sarahId)
+// Returns: complete graph view with all relationships and metadata
 ```
 
 ### 📊 **RAG Applications** - Without the Complexity
@@ -84,19 +199,77 @@ const results = await brain.search("premium smartphones with metal build")
 
 ### 🎯 **Recommendation Engines** - With Graph Intelligence
 ```javascript
-// Netflix-style recommendations with relationships
-await brain.addVerb("User123", "watched", "Inception")
-await brain.addVerb("User123", "liked", "Inception")
-await brain.addVerb("Inception", "similar_to", "Interstellar")
+// Netflix-style recommendations with 1.0 unified API
+import { BrainyData, NounType, VerbType } from '@soulcraft/brainy'
 
-const recommendations = await brain.getRelated("User123", {
-  verb: ["liked", "watched"],
+const brain = new BrainyData()
+await brain.init()
+
+// Create entities and relationships
+const userId = await brain.addNoun("User123", NounType.Person)
+const movieId = await brain.addNoun("Inception", NounType.Content)
+
+// Track user behavior with metadata
+await brain.addVerb(userId, movieId, VerbType.InteractedWith, {
+  action: "watched",
+  rating: 5,
+  timestamp: new Date(),
+  genre: "sci-fi"
+})
+
+// Get intelligent recommendations based on relationships
+const recommendations = await brain.getNounWithVerbs(userId, {
+  verbTypes: [VerbType.InteractedWith],
   depth: 2
 })
-// Returns: Interstellar and other related content
+// Returns: Similar movies based on rating patterns and genre preferences
 ```
 
-## 💫 Why Brainy? The Problem We Solve
+### 🤖 **Multi-Agent AI Systems** - With Shared Memory
+```javascript
+// Multiple AI agents sharing the same brain
+const sharedBrain = new BrainyData({ instance: 'multi-agent-brain' })
+await sharedBrain.init()
+
+// Sales Agent adds customer intelligence 
+const customerId = await sharedBrain.addNoun("Acme Corp", NounType.Organization)
+await sharedBrain.addVerb(customerId, "enterprise-plan", VerbType.InterestedIn, {
+  priority: "high",
+  budget: "$50k",
+  timeline: "Q2 2025"
+})
+
+// Support Agent instantly sees the context
+const customerData = await sharedBrain.getNounWithVerbs(customerId)
+// Support knows: customer interested in enterprise plan with $50k budget
+
+// Marketing Agent learns from both
+const insights = await sharedBrain.search("enterprise customers budget 50k", 10)
+// Marketing can create targeted campaigns for similar prospects
+```
+
+### 🏥 **Customer Support Bots** - With Perfect Memory
+```javascript
+// Support bot that remembers every interaction
+const customerId = await brain.addNoun("Customer_456", NounType.Person)
+
+// Track support history with rich metadata
+await brain.addVerb(customerId, "password-reset", VerbType.RequestedHelp, {
+  issue: "Password reset",
+  resolved: true,
+  date: "2025-01-10",
+  satisfaction: 5,
+  agent: "Sarah"
+})
+
+// Next conversation - bot instantly knows history
+const history = await brain.getNounWithVerbs(customerId)
+// Bot: "I see you had a password issue last week. Everything working smoothly now?"
+
+// Proactive insights
+const commonIssues = await brain.search("password reset common issues", 5)
+// Bot offers preventive tips before problems occur
+```
 
 ### ❌ **The Old Way: Database Frankenstein**
 ```
@@ -111,15 +284,6 @@ Vector + Graph + Search + AI = Brainy (Free & Open Source) = 🧠✨
 
 **Your data gets superpowers. Your wallet stays happy.**
 
-## 🎮 Try It Now - No Install Required!
-
-<div align="center">
-
-### [**→ Live Demo at soulcraft.com/console ←**](https://soulcraft.com/console)
-
-Try Brainy instantly in your browser. No signup. No credit card.
-
-</div>
 
 ## ⚡ Quick Start (60 Seconds)
 
@@ -161,9 +325,9 @@ import { BrainyData, Cortex } from '@soulcraft/brainy'
 const brain = new BrainyData()
 const cortex = new Cortex()
 
-// Add premium augmentations (requires Early Access license)
-cortex.register(new AIMemory())
-cortex.register(new AgentCoordinator())
+// Add premium augmentations (requires Brain Cloud subscription)
+brain.register(new AIMemory())
+brain.register(new AgentCoordinator())
 
 // Now your AI remembers everything across all sessions!
 await brain.add("User prefers TypeScript over JavaScript")
@@ -199,30 +363,49 @@ await neural.neuralImport('data.csv')  // Automatically extracts entities & rela
 - ✅ **Simple Search** - Text and vector search
 - ✅ **Graph Traversal** - Relationship queries
 
-### 🌟 **Community Augmentations** (Free, Open Source)
-```bash
-npm install brainy-sentiment  # Community created
-npm install brainy-translate  # Community maintained
+### 🌟 **Community Augmentations** (Coming Soon!)
+```javascript
+// 🚧 FUTURE: Community augmentations will be available soon!
+// These are examples of what the community could build:
+
+// Example: Sentiment Analysis (not yet available)
+// npm install brainy-sentiment
+// brain.register(new SentimentAnalyzer())
+
+// Example: Translation (not yet available)  
+// npm install brainy-translate
+// brain.register(new Translator())
 ```
 
-```javascript
-import { SentimentAnalyzer } from 'brainy-sentiment'
-import { Translator } from 'brainy-translate'
+**Ideas for Community Augmentations:**
+*Want to build one of these? We'll help promote it!*
+- 🎭 Sentiment Analysis - Analyze emotional tone
+- 🌍 Translation - Multi-language support
+- 📧 Email Parser - Extract structured data from emails
+- 🔗 URL Extractor - Find and validate URLs
+- 📊 Data Visualizer - Generate charts from data
+- 🎨 Image Understanding - Analyze image content
+
+**Be the First!** Create an augmentation and we'll feature it here.
+[See how to build augmentations →](UNIFIED-API.md#creating-your-own-augmentation)
 
-cortex.register(new SentimentAnalyzer())  // Analyze emotions
-cortex.register(new Translator())         // Multi-language support
+### ☁️ **Brain Cloud** - Power Up Your Brain! 🚀
+**Try it FREE:** Get persistent memory, team sync, and enterprise connectors!
+
+```bash
+# Coming Soon! Brain Cloud is in development
+# Join the waitlist:
+# Visit: soulcraft.com
 ```
 
-**Popular community augmentations:**
-- 🎭 Sentiment Analysis
-- 🌍 Translation (50+ languages)
-- 📧 Email Parser
-- 🔗 URL Extractor
-- 📊 Data Visualizer
-- 🎨 Image Understanding
+**Why Brain Cloud?**
+- 🧠 **AI Memory That Never Forgets** - Conversations persist across sessions
+- 🤝 **Multi-Agent Coordination** - AI agents work together seamlessly
+- 💾 **Automatic Backups** - Never lose your brain's knowledge
+- 🔄 **Team Sync** - Share knowledge across your organization
+- 🔌 **Premium Connectors** - Notion, Slack, Salesforce, and more!
 
-### ☁️ **Brain Cloud** (Optional Add-On)
-🌟 **Brainy works perfectly without this!** Brain Cloud adds team features:
+**Special Offer:** First 100GB FREE, then just $9/month for individuals, $49/team
 
 ```javascript
 // Brain Cloud features are in the main package
@@ -234,7 +417,7 @@ const brain = new BrainyVectorDB({
   cloud: { apiKey: process.env.BRAIN_CLOUD_KEY }  // Optional
 })
 
-cortex.register(aiMemory)  // AI remembers everything
+brain.register(aiMemory)  // AI remembers everything
 ```
 
 **AI Memory & Coordination:**
@@ -250,20 +433,6 @@ cortex.register(aiMemory)  // AI remembers everything
 - 🔄 **Postgres** - Real-time replication
 - 🏢 **Slack** - Team knowledge base
 
-### 🎮 **Try Online** (Free Playground)
-Test Brainy instantly without installing:
-
-```javascript
-// Visit soulcraft.com/console
-// No signup required - just start coding!
-// Perfect for:
-// - Testing Brainy before installing
-// - Prototyping ideas quickly  
-// - Learning the API
-// - Sharing examples with others
-```
-
-**[→ Open Console](https://soulcraft.com/console)** - Your code runs locally, data stays private
 
 ### ☁️ **Brain Cloud** (Managed Service)
 For teams that want zero-ops:
@@ -303,27 +472,31 @@ await brain.connect('brain-cloud.soulcraft.com', {
 ### Build & Share Your Augmentation
 
 ```typescript
-import { ISenseAugmentation } from '@soulcraft/brainy'
+import { IAugmentation } from '@soulcraft/brainy'
 
-export class MovieRecommender implements ISenseAugmentation {
+export class MovieRecommender implements IAugmentation {
   name = 'movie-recommender'
+  type = 'cognition' // sense|conduit|cognition|memory
   description = 'AI-powered movie recommendations'
   enabled = true
   
-  async processRawData(data: string) {
+  async processRawData(data: any) {
     // Your recommendation logic
     const movies = await this.analyzePreferences(data)
     
     return {
       success: true,
       data: {
-        nouns: movies.map(m => m.title),
-        verbs: movies.map(m => `similar_to:${m.genre}`),
-        metadata: { genres: movies.map(m => m.genre) }
+        recommendations: movies,
+        confidence: 0.95
       }
     }
   }
 }
+
+// Register with Brainy
+const brain = new BrainyData()
+brain.register(new MovieRecommender())
 ```
 
 **Share with the community:**
@@ -380,22 +553,50 @@ const context = await agentBrain.search("customer plan interest")
 const insights = await agentBrain.getRelated("enterprise plan")
 ```
 
-## 🏗️ Architecture
+## 🏗️ Architecture - Unified & Simple
 
 ```
-Your App
-    ↓
-BrainyData (The Brain)
-    ↓
-Cortex (Orchestrator)
-    ↓
-Augmentations (Capabilities)
-    ├── Built-in (Free)
-    ├── Community (Free) 
-    ├── Premium (Paid)
-    └── Custom (Yours)
+┌─────────────────────────────────────────────┐
+│  🎯 YOUR APP - One Simple API              │
+│  brain.add() brain.search() brain.addVerb() │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│  🧠 BRAINY 1.0 - THE UNIFIED BRAIN         │
+│                                             │
+│  ┌─────────────┐ ┌─────────────┐ ┌────────┐ │
+│  │   Vector    │ │    Graph    │ │ Facets │ │
+│  │   Search    │ │Relationships│ │Metadata│ │
+│  └─────────────┘ └─────────────┘ └────────┘ │
+│                                             │
+│  ┌─────────────┐ ┌─────────────┐ ┌────────┐ │
+│  │ Encryption  │ │   Memory    │ │ Cache  │ │
+│  │ Universal   │ │ Management  │ │ 3-Tier │ │
+│  └─────────────┘ └─────────────┘ └────────┘ │
+└─────────────────┬───────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────┐
+│  💾 STORAGE - Universal Adapters           │
+│  Memory • FileSystem • S3 • OPFS • Custom  │
+└─────────────────────────────────────────────┘
 ```
 
+### **What Makes 1.0 Different:**
+- **🎯 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:**
+1. **You call** `brain.add("complex data")`
+2. **Brainy understands** → detects type, extracts meaning
+3. **Brainy stores** → vector + graph + metadata simultaneously  
+4. **Brainy optimizes** → indexes, caches, tunes performance
+5. **You get superpowers** → semantic search + graph traversal + more
+
 ## 💡 Core Features
 
 ### 🔍 Multi-Dimensional Search
@@ -404,11 +605,12 @@ Augmentations (Capabilities)
 - **Faceted**: Metadata filtering (property-based)
 - **Hybrid**: All combined (maximum power)
 
-### ⚡ Performance
-- **Speed**: 100,000+ ops/second
-- **Scale**: Millions of embeddings
-- **Memory**: ~100MB for 1M vectors
-- **Latency**: <10ms searches
+### ⚡ Performance - Production Ready
+- **Speed**: 100,000+ ops/second (faster with 1.0 optimizations)
+- **Scale**: Millions of entities + relationships
+- **Memory**: ~100MB for 1M vectors (16% smaller than 0.x)
+- **Latency**: <10ms searches with 3-tier caching
+- **Intelligence**: Auto-tuning learns from your usage patterns
 
 ### 🔒 Production Ready
 - **Encryption**: End-to-end available
@@ -455,10 +657,9 @@ Augmentations (Capabilities)
 - 📢 Spread the word
 
 ### Get Help & Connect
-- 💬 [Discord Community](https://discord.gg/brainy)
-- 🐦 [Twitter Updates](https://twitter.com/soulcraftlabs)
 - 📧 [Email Support](mailto:support@soulcraft.com)
-- 🎓 [Video Tutorials](https://youtube.com/@soulcraft)
+- 🐛 [GitHub Issues](https://github.com/soulcraftlabs/brainy/issues)
+- 💬 [GitHub Discussions](https://github.com/soulcraftlabs/brainy/discussions)
 
 ## 📈 Who's Using Brainy?
 
@@ -480,10 +681,10 @@ Premium augmentations available at [soulcraft.com](https://soulcraft.com)
 
 ### 🧠⚛️ **Give Your Data a Brain Upgrade**
 
-**[Get Started](docs/getting-started/quick-start.md)** • 
+**[Get Started](docs/getting-started/quick-start-1.0.md)** • 
 **[Examples](examples/)** • 
-**[API Docs](docs/api/BRAINY-API-REFERENCE.md)** • 
-**[Discord](https://discord.gg/brainy)**
+**[API Docs](UNIFIED-API.md)** • 
+**[GitHub](https://github.com/soulcraftlabs/brainy)**
 
 ⭐ **Star us on GitHub to support open source AI!** ⭐