From b3579d917e76218b7b8f24c5d626c48462ec9d05 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Wed, 6 Aug 2025 16:38:52 -0700 Subject: [PATCH] feat: restore comprehensive feature sections to README - Add back MAJOR UPDATES section highlighting v0.51, v0.49, v0.48, v0.46 - Include Build Amazing Things section with comprehensive use cases - Restore framework examples (React, Angular, Vue) with full code samples - Add Distributed Mode section with multi-instance coordination - Keep problem-focused opening while providing deep feature coverage - Balance quick start with comprehensive capabilities showcase --- README.md | 253 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 244 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ed2c8e5a..833fe83d 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,66 @@ const results = await brainy.search("AI language models", 5, { **That's it. You just built a knowledge graph with semantic search and faceted filtering in 8 lines.** +## πŸ”₯ MAJOR UPDATES: What's New in v0.51, v0.49 & v0.48 + +### 🎯 **v0.51: Revolutionary Developer Experience** + +**Problem-focused approach that gets you productive in seconds!** + +- βœ… **Problem-Solution Narrative** - Immediately understand why Brainy exists +- βœ… **8-Line Quickstart** - Three search types in one simple demo +- βœ… **Streamlined Documentation** - Focus on what matters most +- βœ… **Clear Positioning** - The only true Vector + Graph database + +### 🎯 **v0.49: Filter Discovery & Performance Improvements** + +**Discover available filters and scale to millions of items!** + +```javascript +// Discover what filters are available - O(1) field lookup +const categories = await brainy.getFilterValues('category') +// Returns: ['electronics', 'books', 'clothing', ...] + +const fields = await brainy.getFilterFields() // O(1) operation +// Returns: ['category', 'price', 'brand', 'rating', ...] +``` + +- βœ… **Filter Discovery API**: O(1) field discovery for instant filter UI generation +- βœ… **Improved Performance**: Removed deprecated methods, now uses pagination everywhere +- βœ… **Better Scalability**: Hybrid indexing with O(1) field access scales to millions +- βœ… **Smart Caching**: LRU cache for frequently accessed filters +- βœ… **Zero Configuration**: Everything auto-optimizes based on usage patterns + +### πŸš€ **v0.48: MongoDB-Style Metadata Filtering** + +**Powerful querying with familiar syntax - filter DURING search for maximum performance!** + +```javascript +const results = await brainy.search("wireless headphones", 10, { + metadata: { + category: { $in: ["electronics", "audio"] }, + price: { $lte: 200 }, + rating: { $gte: 4.0 }, + brand: { $ne: "Generic" } + } +}) +``` + +- βœ… **15+ MongoDB Operators**: `$gt`, `$in`, `$regex`, `$and`, `$or`, `$includes`, etc. +- βœ… **Automatic Indexing**: Zero configuration, maximum performance +- βœ… **Nested Fields**: Use dot notation for complex objects +- βœ… **100% Backward Compatible**: Your existing code works unchanged + +### ⚑ **v0.46: Transformers.js Migration** + +**Replaced TensorFlow.js for better performance and true offline operation!** + +- βœ… **95% Smaller Package**: 643 kB vs 12.5 MB +- βœ… **84% Smaller Models**: 87 MB vs 525 MB models +- βœ… **True Offline**: Zero network calls after initial download +- βœ… **5x Fewer Dependencies**: Clean tree, no peer dependency issues +- βœ… **Same API**: Drop-in replacement, existing code works unchanged + ## πŸ† Why Brainy Wins - 🧠 **Triple Search Power** - Vector + Graph + Faceted filtering in one query @@ -84,27 +144,164 @@ const results = await brainy.search("AI language models", 5, { - **⚑ LLM Generation** - Built-in content generation powered by your knowledge graph - **🌊 Real-time Sync** - Live updates across distributed instances -## 🎯 Perfect For +## 🎨 Build Amazing Things -**πŸ€– AI Chat Applications** - ChatGPT-like apps with long-term memory and context -**πŸ” Semantic Search** - Find "that thing like a cat but bigger" β†’ returns "tiger" -**🧬 Knowledge Graphs** - Connect everything. Wikipedia meets Neo4j meets magic +**πŸ€– AI Chat Applications** - Build ChatGPT-like apps with long-term memory and context awareness +**πŸ” Semantic Search Engines** - Search by meaning, not keywords. Find "that thing that's like a cat but bigger" β†’ returns "tiger" **🎯 Recommendation Engines** - "Users who liked this also liked..." but actually good -**πŸ“š Smart Documentation** - Docs that answer questions before you ask them +**🧬 Knowledge Graphs** - Connect everything to everything. Wikipedia meets Neo4j meets magic +**πŸ‘οΈ Computer Vision Apps** - Store and search image embeddings. "Find all photos with dogs wearing hats" +**🎡 Music Discovery** - Find songs that "feel" similar. Spotify's Discover Weekly in your app +**πŸ“š Smart Documentation** - Docs that answer questions. "How do I deploy to production?" β†’ relevant guides +**πŸ›‘οΈ Fraud Detection** - Find patterns humans can't see. Anomaly detection on steroids +**🌐 Real-Time Collaboration** - Sync vector data across devices. Figma for AI data +**πŸ₯ Medical Diagnosis Tools** - Match symptoms to conditions using embedding similarity ## 🌍 Works Everywhere - Same Code +**Write once, run anywhere.** Brainy auto-detects your environment and optimizes automatically: + +### 🌐 Browser Frameworks (React, Angular, Vue) + ```javascript -// This EXACT code works in ALL environments import { BrainyData } from '@soulcraft/brainy' +// SAME CODE in React, Angular, Vue, Svelte, etc. const brainy = new BrainyData() -await brainy.init() +await brainy.init() // Auto-uses OPFS in browsers -// Works in: React, Vue, Angular, Node.js, Deno, Bun, -// Cloudflare Workers, Vercel Edge, AWS Lambda, browsers, anywhere +// Add entities and relationships +const john = await brainy.add("John is a software engineer", { type: "person" }) +const jane = await brainy.add("Jane is a data scientist", { type: "person" }) +const ai = await brainy.add("AI Project", { type: "project" }) + +await brainy.relate(john, ai, "works_on") +await brainy.relate(jane, ai, "leads") + +// Search by meaning +const engineers = await brainy.search("software developers", 5) + +// Traverse relationships +const team = await brainy.getVerbsByTarget(ai) // Who works on AI Project? ``` +
+πŸ“¦ Full React Component Example + +```jsx +import { BrainyData } from '@soulcraft/brainy' +import { useEffect, useState } from 'react' + +function Search() { + const [brainy, setBrainy] = useState(null) + const [results, setResults] = useState([]) + + useEffect(() => { + const init = async () => { + const db = new BrainyData() + await db.init() + // Add your data... + setBrainy(db) + } + init() + }, []) + + const search = async (query) => { + const results = await brainy?.search(query, 5) || [] + setResults(results) + } + + return search(e.target.value)} placeholder="Search..." /> +} +``` + +
+ +
+πŸ“¦ Full Angular Component Example + +```typescript +import { Component, signal, OnInit } from '@angular/core' +import { BrainyData } from '@soulcraft/brainy' + +@Component({ + selector: 'app-search', + template: `` +}) +export class SearchComponent implements OnInit { + brainy = new BrainyData() + + async ngOnInit() { + await this.brainy.init() + // Add your data... + } + + async search(query: string) { + const results = await this.brainy.search(query, 5) + // Display results... + } +} +``` + +
+ +
+πŸ“¦ Full Vue Example + +```vue + + + +``` + +
+ +### 🟒 Node.js / Serverless / Edge + +```javascript +import { BrainyData } from '@soulcraft/brainy' + +// SAME CODE works in Node.js, Vercel, Netlify, Cloudflare Workers, Deno, Bun +const brainy = new BrainyData() +await brainy.init() // Auto-detects environment and optimizes + +// Add entities and relationships +await brainy.add("Python is great for data science", { type: "fact" }) +await brainy.add("JavaScript rules the web", { type: "fact" }) + +// Search by meaning +const results = await brainy.search("programming languages", 5) + +// Optional: Production with S3/R2 storage (auto-detected in cloud environments) +const productionBrainy = new BrainyData({ + storage: { + s3Storage: { bucketName: process.env.BUCKET_NAME } + } +}) +``` + +**That's it! Same code, everywhere. Zero-to-Smartβ„’** + Brainy automatically detects and optimizes for your environment: | Environment | Storage | Optimization | @@ -114,6 +311,44 @@ Brainy automatically detects and optimizes for your environment: | ⚑ Serverless | S3 / Memory | Cold Start Optimization | | πŸ”₯ Edge | Memory / KV | Minimal Footprint | +## 🌐 Distributed Mode (NEW!) + +**Scale horizontally with zero configuration!** Brainy now supports distributed deployments with automatic coordination: + +- **🌐 Multi-Instance Coordination** - Multiple readers and writers working in harmony +- **🏷️ Smart Domain Detection** - Automatically categorizes data (medical, legal, product, etc.) +- **πŸ“Š Real-Time Health Monitoring** - Track performance across all instances +- **πŸ”„ Automatic Role Optimization** - Readers optimize for cache, writers for throughput +- **πŸ—‚οΈ Intelligent Partitioning** - Hash-based partitioning for perfect load distribution + +```javascript +// Writer Instance - Ingests data from multiple sources +const writer = new BrainyData({ + storage: { s3Storage: { bucketName: 'my-bucket' } }, + distributed: { role: 'writer' } // Explicit role for safety +}) + +// Reader Instance - Optimized for search queries +const reader = new BrainyData({ + storage: { s3Storage: { bucketName: 'my-bucket' } }, + distributed: { role: 'reader' } // 80% memory for cache +}) + +// Data automatically gets domain tags +await writer.add("Patient shows symptoms of...", { + diagnosis: "flu" // Auto-tagged as 'medical' domain +}) + +// Domain-aware search across all partitions +const results = await reader.search("medical symptoms", 10, { + filter: { domain: 'medical' } // Only search medical data +}) + +// Monitor health across all instances +const health = reader.getHealthStatus() +console.log(`Instance ${health.instanceId}: ${health.status}`) +``` + ## πŸ†š Why Not Just Use...? ### vs. Multiple Databases