David Snelling
89413ebec2
- Move "Get Started in 30 Seconds" section higher for immediate engagement - Add "The Magic: Vector + Graph Database" section highlighting unique value - Update code examples with real API methods (addNoun, addVerb, getVerbsBySource) - Add "Advanced Features" teaser section - Improve overall organization for better user excitement and adoption
1473 lines
44 KiB
Markdown
1473 lines
44 KiB
Markdown
<div align="center">
|
||
<img src="./brainy.png" alt="Brainy Logo" width="200"/>
|
||
<br/><br/>
|
||
|
||
[](LICENSE)
|
||
[](https://nodejs.org/)
|
||
[](https://www.typescriptlang.org/)
|
||
[](CONTRIBUTING.md)
|
||
|
||
**A powerful graph & vector data platform for AI applications across any environment**
|
||
|
||
</div>
|
||
|
||
## ✨ What is Brainy?
|
||
|
||
Imagine a database that thinks like you do - connecting ideas, finding patterns, and getting smarter over time. Brainy
|
||
is the **AI-native database** that brings vector search and knowledge graphs together in one powerful, ridiculously
|
||
easy-to-use package.
|
||
|
||
### 🆕 NEW: Distributed Mode (v0.38+)
|
||
|
||
**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
|
||
|
||
### 🚀 Why Developers Love Brainy
|
||
|
||
- **🧠 Zero-to-Smart™** - No config files, no tuning parameters, no DevOps headaches. Brainy auto-detects your
|
||
environment and optimizes itself
|
||
- **🌍 True Write-Once, Run-Anywhere** - Same code runs in Angular, React, Vue, Node.js, Deno, Bun, serverless, edge workers, and web workers with automatic environment detection
|
||
- **⚡ Scary Fast** - Handles millions of vectors with sub-millisecond search. Built-in GPU acceleration when available
|
||
- **🎯 Self-Learning** - Like having a database that goes to the gym. Gets faster and smarter the more you use it
|
||
- **🔮 AI-First Design** - Built for the age of embeddings, RAG, and semantic search. Your LLMs will thank you
|
||
- **🎮 Actually Fun to Use** - Clean API, great DX, and it does the heavy lifting so you can build cool stuff
|
||
|
||
### 🚀 NEW: Ultra-Fast Search Performance + Auto-Configuration
|
||
|
||
**Your searches just got 100x faster AND Brainy now configures itself!** Advanced performance with zero setup:
|
||
|
||
- **🤖 Intelligent Auto-Configuration** - Detects environment and usage patterns, optimizes automatically
|
||
- **⚡ Smart Result Caching** - Repeated queries return in <1ms with automatic cache invalidation
|
||
- **📄 Cursor-Based Pagination** - Navigate millions of results with constant O(k) performance
|
||
- **🔄 Real-Time Data Sync** - Cache automatically updates when data changes, even in distributed scenarios
|
||
- **📊 Performance Monitoring** - Built-in hit rate and memory usage tracking with adaptive optimization
|
||
- **🎯 Zero Breaking Changes** - All existing code works unchanged, just faster and smarter
|
||
|
||
## 📦 Get Started in 30 Seconds
|
||
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
```javascript
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
|
||
const brainy = new BrainyData()
|
||
await brainy.init() // Auto-detects your environment
|
||
|
||
// Add some data
|
||
await brainy.add("The quick brown fox jumps over the lazy dog")
|
||
await brainy.add("A fast fox leaps over a sleeping dog")
|
||
await brainy.add("Cats are independent and mysterious animals")
|
||
|
||
// Vector search finds similar content
|
||
const results = await brainy.search("speedy animals jumping", 2)
|
||
console.log(results) // Finds the fox sentences!
|
||
```
|
||
|
||
**🎯 That's it!** You just built semantic search in 4 lines. Works in Angular, React, Vue, Node.js, browsers, serverless - everywhere.
|
||
|
||
## 🚀 The Magic: Vector + Graph Database
|
||
|
||
**Most databases do one thing.** Brainy does both vector similarity AND graph relationships:
|
||
|
||
```javascript
|
||
// Add entities with relationships
|
||
const companyId = await brainy.addNoun("OpenAI creates powerful AI models", "company")
|
||
const productId = await brainy.addNoun("GPT-4 is a large language model", "product")
|
||
|
||
// Connect them with relationships
|
||
await brainy.addVerb(companyId, productId, undefined, { type: "develops" })
|
||
|
||
// Now you can do BOTH:
|
||
const similar = await brainy.search("AI language models") // Vector similarity
|
||
const products = await brainy.getVerbsByType("develops") // Graph traversal
|
||
```
|
||
|
||
**Why this matters:** Find content by meaning AND follow relationships. It's like having PostgreSQL and Pinecone working together seamlessly.
|
||
|
||
### 🔍 Want More Power?
|
||
- **Advanced graph traversal** - Complex relationship queries and multi-hop searches
|
||
- **Distributed clustering** - Scale across multiple instances with automatic coordination
|
||
- **Real-time syncing** - WebSocket and WebRTC for live data updates
|
||
- **Custom augmentations** - Extend Brainy with your own functionality
|
||
|
||
*[See full API documentation below](#-installation) for advanced features*
|
||
|
||
## 🎨 Build Amazing Things
|
||
|
||
**🤖 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
|
||
**🧬 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
|
||
|
||
## 🚀 Write-Once, Run-Anywhere Quick Start
|
||
|
||
Brainy uses the same code across all environments with automatic detection. **Framework-optimized** for the best developer experience. Choose your environment:
|
||
|
||
### 🅰️ Angular (Latest)
|
||
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
```typescript
|
||
import { Component, signal, OnInit } from '@angular/core'
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
|
||
@Component({
|
||
selector: 'app-search',
|
||
template: `
|
||
<div class="search-container">
|
||
<input [(ngModel)]="query"
|
||
(input)="search($event.target.value)"
|
||
placeholder="Search by meaning (try 'pets' or 'food')..."
|
||
class="search-input">
|
||
|
||
<div class="results">
|
||
@for (result of results(); track result.id) {
|
||
<div class="result-item">
|
||
<strong>{{result.metadata?.category}}</strong>: {{result.metadata?.originalData}}
|
||
<small>Similarity: {{result.score | number:'1.2-2'}}</small>
|
||
</div>
|
||
}
|
||
</div>
|
||
</div>
|
||
`
|
||
})
|
||
export class SearchComponent implements OnInit {
|
||
private brainy: BrainyData | null = null
|
||
results = signal<any[]>([])
|
||
query = ''
|
||
|
||
async ngOnInit() {
|
||
// Auto-detects environment and uses OPFS storage in browsers
|
||
this.brainy = new BrainyData({
|
||
defaultService: 'my-app'
|
||
})
|
||
await this.brainy.init()
|
||
|
||
// Add sample data
|
||
await this.brainy.add("Cats are amazing pets", { category: "animals" })
|
||
await this.brainy.add("Dogs love to play fetch", { category: "animals" })
|
||
await this.brainy.add("Pizza is delicious food", { category: "food" })
|
||
}
|
||
|
||
async search(query: string) {
|
||
if (!query.trim() || !this.brainy) {
|
||
this.results.set([])
|
||
return
|
||
}
|
||
|
||
const searchResults = await this.brainy.search(query, 5)
|
||
this.results.set(searchResults)
|
||
}
|
||
}
|
||
```
|
||
|
||
### ⚛️ React
|
||
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
```jsx
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
import { useEffect, useState } from 'react'
|
||
|
||
function SemanticSearch() {
|
||
const [brainy, setBrainy] = useState(null)
|
||
const [results, setResults] = useState([])
|
||
const [query, setQuery] = useState('')
|
||
const [loading, setLoading] = useState(true)
|
||
|
||
useEffect(() => {
|
||
async function initBrainy() {
|
||
// Auto-detects environment and uses OPFS storage in browsers
|
||
const db = new BrainyData({
|
||
defaultService: 'my-app'
|
||
})
|
||
await db.init()
|
||
|
||
// Add sample data
|
||
await db.add("Cats are amazing pets", { category: "animals" })
|
||
await db.add("Dogs love to play fetch", { category: "animals" })
|
||
await db.add("Pizza is delicious food", { category: "food" })
|
||
|
||
setBrainy(db)
|
||
setLoading(false)
|
||
}
|
||
|
||
initBrainy()
|
||
}, [])
|
||
|
||
const search = async (searchQuery) => {
|
||
if (!searchQuery.trim() || !brainy) return setResults([])
|
||
|
||
const searchResults = await brainy.search(searchQuery, 5)
|
||
setResults(searchResults)
|
||
}
|
||
|
||
if (loading) return <div>Initializing Brainy...</div>
|
||
|
||
return (
|
||
<div className="search-container">
|
||
<input
|
||
value={query}
|
||
onChange={(e) => {
|
||
setQuery(e.target.value)
|
||
search(e.target.value)
|
||
}}
|
||
placeholder="Search by meaning (try 'pets' or 'food')..."
|
||
className="search-input"
|
||
/>
|
||
|
||
<div className="results">
|
||
{results.map((result, i) => (
|
||
<div key={result.id} className="result-item">
|
||
<strong>{result.metadata?.category}</strong>: {result.metadata?.originalData}
|
||
<small>Similarity: {result.score.toFixed(2)}</small>
|
||
</div>
|
||
))}
|
||
</div>
|
||
</div>
|
||
)
|
||
}
|
||
|
||
export default SemanticSearch
|
||
```
|
||
|
||
### 🌟 Vue 3
|
||
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
```vue
|
||
<template>
|
||
<div class="search-container">
|
||
<input
|
||
v-model="query"
|
||
@input="search"
|
||
placeholder="Search by meaning (try 'pets' or 'food')..."
|
||
class="search-input"
|
||
/>
|
||
|
||
<div v-if="loading" class="loading">
|
||
Initializing Brainy...
|
||
</div>
|
||
|
||
<div v-else class="results">
|
||
<div
|
||
v-for="result in results"
|
||
:key="result.id"
|
||
class="result-item"
|
||
>
|
||
<strong>{{ result.metadata?.category }}</strong>: {{ result.metadata?.originalData }}
|
||
<small>Similarity: {{ result.score.toFixed(2) }}</small>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
import { ref, onMounted } from 'vue'
|
||
|
||
const brainy = ref(null)
|
||
const results = ref([])
|
||
const query = ref('')
|
||
const loading = ref(true)
|
||
|
||
onMounted(async () => {
|
||
// Auto-detects environment and uses OPFS storage in browsers
|
||
const db = new BrainyData({
|
||
defaultService: 'my-app'
|
||
})
|
||
await db.init()
|
||
|
||
// Add sample data
|
||
await db.add("Cats are amazing pets", { category: "animals" })
|
||
await db.add("Dogs love to play fetch", { category: "animals" })
|
||
await db.add("Pizza is delicious food", { category: "food" })
|
||
|
||
brainy.value = db
|
||
loading.value = false
|
||
})
|
||
|
||
const search = async () => {
|
||
if (!query.value.trim() || !brainy.value) {
|
||
results.value = []
|
||
return
|
||
}
|
||
|
||
const searchResults = await brainy.value.search(query.value, 5)
|
||
results.value = searchResults
|
||
}
|
||
</script>
|
||
|
||
<style scoped>
|
||
.search-container { max-width: 600px; margin: 0 auto; padding: 20px; }
|
||
.search-input { width: 100%; padding: 12px; margin-bottom: 20px; border: 2px solid #ddd; border-radius: 8px; }
|
||
.result-item { padding: 12px; border: 1px solid #eee; margin-bottom: 8px; border-radius: 6px; }
|
||
.loading { text-align: center; color: #666; }
|
||
</style>
|
||
```
|
||
|
||
### 🟢 Node.js Server
|
||
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
```javascript
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
|
||
// Auto-detects Node.js → FileSystem (local) or S3 (production), Worker threads
|
||
const brainy = new BrainyData({
|
||
defaultService: 'my-app',
|
||
// Optional: Production S3 storage
|
||
storage: {
|
||
s3Storage: {
|
||
bucketName: process.env.S3_BUCKET,
|
||
region: process.env.AWS_REGION,
|
||
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
|
||
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
|
||
}
|
||
}
|
||
})
|
||
await brainy.init()
|
||
|
||
// Same API everywhere
|
||
await brainy.add("Cats are amazing pets", { category: "animals" })
|
||
const results = await brainy.search("pets", 5)
|
||
console.log('Search results:', results)
|
||
```
|
||
|
||
### ⚡ Serverless (Vercel/Netlify)
|
||
|
||
```javascript
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
|
||
export default async function handler(req, res) {
|
||
// Auto-detects serverless → S3/R2 storage for persistence, or Memory for temp
|
||
const brainy = new BrainyData({
|
||
defaultService: 'my-app',
|
||
// Optional: Explicit S3-compatible storage
|
||
storage: {
|
||
r2Storage: {
|
||
bucketName: process.env.R2_BUCKET,
|
||
accessKeyId: process.env.R2_ACCESS_KEY_ID,
|
||
secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
|
||
accountId: process.env.R2_ACCOUNT_ID
|
||
}
|
||
}
|
||
})
|
||
await brainy.init()
|
||
|
||
// Same API everywhere
|
||
const results = await brainy.search(req.query.q, 5)
|
||
res.json({ results })
|
||
}
|
||
```
|
||
|
||
### 🔥 Cloudflare Workers
|
||
|
||
```javascript
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
|
||
export default {
|
||
async fetch(request) {
|
||
// Auto-detects edge → Minimal footprint, KV storage
|
||
const brainy = new BrainyData({
|
||
defaultService: 'edge-app'
|
||
})
|
||
await brainy.init()
|
||
|
||
// Same API everywhere
|
||
const url = new URL(request.url)
|
||
const results = await brainy.search(url.searchParams.get('q'), 5)
|
||
return Response.json({ results })
|
||
}
|
||
}
|
||
```
|
||
|
||
### 🦕 Deno
|
||
|
||
```typescript
|
||
import { BrainyData } from 'https://esm.sh/@soulcraft/brainy'
|
||
|
||
// Auto-detects Deno → Native compatibility, FileSystem storage
|
||
const brainy = new BrainyData({
|
||
defaultService: 'deno-app'
|
||
})
|
||
await brainy.init()
|
||
|
||
// Same API everywhere
|
||
await brainy.add("Deno is awesome", { category: "tech" })
|
||
const results = await brainy.search("technology", 5)
|
||
console.log(results)
|
||
```
|
||
|
||
**That's it! Same code, everywhere. Zero-to-Smart™**
|
||
|
||
Brainy automatically detects and optimizes for:
|
||
- 🌐 **Browser frameworks** → OPFS storage, Web Workers, memory optimization
|
||
- 🟢 **Node.js servers** → FileSystem or S3/R2 storage, Worker threads, cluster support
|
||
- ⚡ **Serverless functions** → S3/R2 or Memory storage, cold start optimization
|
||
- 🔥 **Edge workers** → Memory or KV storage, minimal footprint
|
||
- 🧵 **Web/Worker threads** → Shared storage, thread-safe operations
|
||
- 🦕 **Deno/Bun runtimes** → FileSystem or S3-compatible storage, native performance
|
||
|
||
|
||
### 🐳 NEW: Zero-Config Docker Deployment
|
||
|
||
**Deploy to any cloud with embedded models - no runtime downloads needed!**
|
||
|
||
```dockerfile
|
||
# One line extracts models automatically during build
|
||
RUN npm run extract-models
|
||
|
||
# Deploy anywhere: Google Cloud, AWS, Azure, Cloudflare, etc.
|
||
```
|
||
|
||
- **⚡ 7x Faster Cold Starts** - Models embedded in container, no downloads
|
||
- **🌐 Universal Cloud Support** - Same Dockerfile works everywhere
|
||
- **🔒 Offline Ready** - No external dependencies at runtime
|
||
- **📦 Zero Configuration** - Automatic model detection and loading
|
||
|
||
See [Docker Deployment Guide](./docs/docker-deployment.md) for complete examples.
|
||
|
||
```javascript
|
||
// Zero configuration - everything optimized automatically!
|
||
const brainy = new BrainyData() // Auto-detects environment & optimizes
|
||
await brainy.init()
|
||
|
||
// Caching happens automatically - no setup needed!
|
||
const results1 = await brainy.search('query', 10) // ~50ms first time
|
||
const results2 = await brainy.search('query', 10) // <1ms cached hit!
|
||
|
||
// Advanced pagination works instantly
|
||
const page1 = await brainy.searchWithCursor('query', 100)
|
||
const page2 = await brainy.searchWithCursor('query', 100, {
|
||
cursor: page1.cursor // Constant time, no matter how deep!
|
||
})
|
||
|
||
// Monitor auto-optimized performance
|
||
const stats = brainy.getCacheStats()
|
||
console.log(`Auto-tuned cache hit rate: ${(stats.search.hitRate * 100).toFixed(1)}%`)
|
||
```
|
||
|
||
### 🌐 Distributed Mode Example (NEW!)
|
||
|
||
```javascript
|
||
// Writer Instance - Ingests data from multiple sources
|
||
const writer = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } },
|
||
distributed: { role: 'writer' } // Explicit role for safety
|
||
})
|
||
|
||
// Reader Instance - Optimized for search queries
|
||
const reader = createAutoBrainy({
|
||
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}`)
|
||
```
|
||
|
||
## 🎭 Key Features
|
||
|
||
### Core Capabilities
|
||
|
||
- **Vector Search** - Find semantically similar content using embeddings
|
||
- **Graph Relationships** - Connect data with meaningful relationships
|
||
- **JSON Document Search** - Search within specific fields with prioritization
|
||
- **Distributed Mode** - Scale horizontally with automatic coordination between instances
|
||
- **Real-Time Syncing** - WebSocket and WebRTC for distributed instances
|
||
- **Streaming Pipeline** - Process data in real-time as it flows through
|
||
- **Model Control Protocol** - Let AI models access your data
|
||
|
||
### Developer Experience
|
||
|
||
- **TypeScript Support** - Fully typed API with generics
|
||
- **Extensible Augmentations** - Customize and extend functionality
|
||
- **REST API** - Web service wrapper for HTTP endpoints
|
||
- **Auto-Complete** - IntelliSense for all APIs and types
|
||
|
||
## 📦 Installation
|
||
|
||
### Development: Quick Start
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
### ✨ Write-Once, Run-Anywhere Architecture
|
||
|
||
**Same code, every environment.** Brainy auto-detects and optimizes for your runtime:
|
||
|
||
```javascript
|
||
// This exact code works in Angular, React, Vue, Node.js, Deno, Bun,
|
||
// serverless functions, edge workers, and web workers
|
||
import { BrainyData } from '@soulcraft/brainy'
|
||
|
||
const brainy = new BrainyData()
|
||
await brainy.init() // Auto-detects environment and chooses optimal storage
|
||
|
||
// Vector + Graph: Add entities (nouns) with relationships (verbs)
|
||
const companyId = await brainy.addNoun("OpenAI creates powerful AI models", "company", {
|
||
founded: "2015", industry: "AI"
|
||
})
|
||
const productId = await brainy.addNoun("GPT-4 is a large language model", "product", {
|
||
type: "LLM", parameters: "1.7T"
|
||
})
|
||
|
||
// Create relationships between entities
|
||
await brainy.addVerb(companyId, productId, undefined, { type: "develops" })
|
||
|
||
// Vector search finds semantically similar content
|
||
const similar = await brainy.search("AI language models", 5)
|
||
|
||
// Graph operations: explore relationships
|
||
const relationships = await brainy.getVerbsBySource(companyId)
|
||
const allProducts = await brainy.getVerbsByType("develops")
|
||
```
|
||
|
||
### 🔍 Advanced Graph Operations
|
||
|
||
```javascript
|
||
// Vector search with graph filtering
|
||
const results = await brainy.search("AI models", 10, {
|
||
searchVerbs: true, // Search relationships directly
|
||
verbTypes: ["develops"], // Filter by relationship types
|
||
searchConnectedNouns: true, // Find entities connected by relationships
|
||
verbDirection: "outgoing" // Direction: outgoing, incoming, or both
|
||
})
|
||
|
||
// Graph traversal methods
|
||
const outgoing = await brainy.getVerbsBySource(entityId) // What this entity relates to
|
||
const incoming = await brainy.getVerbsByTarget(entityId) // What relates to this entity
|
||
const byType = await brainy.getVerbsByType("develops") // All relationships of this type
|
||
|
||
// Combined vector + graph search
|
||
const connected = await brainy.searchNounsByVerbs("machine learning", 5, {
|
||
verbTypes: ["develops", "uses"],
|
||
direction: "both"
|
||
})
|
||
|
||
// Get related entities through specific relationships
|
||
const related = await brainy.getRelatedNouns(companyId, { relationType: "develops" })
|
||
```
|
||
|
||
**Universal benefits:**
|
||
- ✅ **Auto-detects everything** - Environment, storage, threading, optimization
|
||
- ✅ **Framework-optimized** - Best experience with Angular, React, Vue bundlers
|
||
- ✅ **Runtime-agnostic** - Node.js, Deno, Bun, browsers, serverless, edge
|
||
- ✅ **TypeScript-first** - Full types everywhere, IntelliSense support
|
||
- ✅ **Tree-shaking ready** - Modern bundlers import only what you need
|
||
- ✅ **ES Modules architecture** - Individual modules for better optimization by modern frameworks
|
||
|
||
### Production: Add Offline Model Reliability
|
||
```bash
|
||
# For development (online model loading)
|
||
npm install @soulcraft/brainy
|
||
|
||
# For production (offline reliability)
|
||
npm install @soulcraft/brainy @soulcraft/brainy-models
|
||
```
|
||
|
||
**Why use offline models in production?**
|
||
- **🛡️ 100% Reliability** - No network timeouts or blocked URLs
|
||
- **⚡ Instant Startup** - Models load in ~100ms vs 5-30 seconds
|
||
- **🐳 Docker Ready** - Perfect for Cloud Run, Lambda, Kubernetes
|
||
- **🔒 Zero Dependencies** - No external network calls required
|
||
- **🎯 Zero Configuration** - Automatic detection with graceful fallback
|
||
- **🔐 Enhanced Security** - Complete air-gapping support for sensitive environments
|
||
- **🏢 Enterprise Ready** - Works behind corporate firewalls and restricted networks
|
||
|
||
The offline models provide the **same functionality** with maximum reliability. Your existing code works unchanged - Brainy automatically detects and uses bundled models when available.
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
import { BundledUniversalSentenceEncoder } from '@soulcraft/brainy-models'
|
||
|
||
// Use the bundled model for offline operation
|
||
const brainy = createAutoBrainy({
|
||
embeddingModel: BundledUniversalSentenceEncoder
|
||
})
|
||
```
|
||
|
||
## 🐳 Docker & Cloud Deployment
|
||
|
||
**Deploy Brainy to any cloud provider with embedded models for maximum performance and reliability.**
|
||
|
||
### Quick Docker Setup
|
||
|
||
1. **Install models package:**
|
||
```bash
|
||
npm install @soulcraft/brainy-models
|
||
```
|
||
|
||
2. **Add to your Dockerfile:**
|
||
```dockerfile
|
||
# Extract models during build (zero configuration!)
|
||
RUN npm run extract-models
|
||
|
||
# Include models in final image
|
||
COPY --from=builder /app/models ./models
|
||
```
|
||
|
||
3. **Deploy anywhere:**
|
||
```bash
|
||
# Works on all cloud providers
|
||
gcloud run deploy --source . # Google Cloud Run
|
||
aws ecs create-service ... # AWS ECS/Fargate
|
||
az container create ... # Azure Container Instances
|
||
wrangler publish # Cloudflare Workers
|
||
```
|
||
|
||
### Universal Dockerfile Template
|
||
|
||
```dockerfile
|
||
FROM node:24-alpine AS builder
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm ci
|
||
COPY . .
|
||
RUN npm run extract-models # ← Automatic model extraction
|
||
RUN npm run build
|
||
|
||
FROM node:24-alpine AS production
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm ci --only=production --omit=optional
|
||
COPY --from=builder /app/dist ./dist
|
||
COPY --from=builder /app/models ./models # ← Models included
|
||
CMD ["node", "dist/server.js"]
|
||
```
|
||
|
||
### Benefits
|
||
|
||
- **⚡ 7x Faster Cold Starts** - No model download delays
|
||
- **🌐 Universal Compatibility** - Same Dockerfile works on all clouds
|
||
- **🔒 Offline Ready** - No external dependencies at runtime
|
||
- **📦 Zero Configuration** - Automatic model detection
|
||
- **🛡️ Enhanced Security** - No network calls for model loading
|
||
|
||
**📖 Complete Guide:** See [docs/docker-deployment.md](./docs/docker-deployment.md) for detailed examples covering Google Cloud Run, AWS Lambda/ECS, Azure Container Instances, Cloudflare Workers, and more.
|
||
|
||
### 📦 Modern ES Modules Architecture
|
||
|
||
Brainy now uses individual ES modules instead of large bundles, providing better optimization for modern frameworks:
|
||
|
||
- **Better tree-shaking**: Frameworks import only the specific functions you use
|
||
- **Smaller final apps**: Your bundled application only includes what you actually need
|
||
- **Faster development builds**: No complex bundling during development
|
||
- **Better debugging**: Source maps point to individual files, not large bundles
|
||
|
||
This change reduced the package size significantly while improving compatibility with Angular, React, Vue, and other modern framework build systems.
|
||
|
||
## 🧬 The Power of Nouns & Verbs
|
||
|
||
Brainy uses a **graph-based data model** that mirrors how humans think - with **Nouns** (entities) connected by **Verbs
|
||
** (relationships). This isn't just vectors in a void; it's structured, meaningful data.
|
||
|
||
### 📝 Nouns (What Things Are)
|
||
|
||
Nouns are your entities - the "things" in your data. Each noun has:
|
||
|
||
- A unique ID
|
||
- A vector representation (for similarity search)
|
||
- A type (Person, Document, Concept, etc.)
|
||
- Custom metadata
|
||
|
||
**Available Noun Types:**
|
||
|
||
| Category | Types | Use For |
|
||
|---------------------|-------------------------------------------------------------------|-------------------------------------------------------|
|
||
| **Core Entities** | `Person`, `Organization`, `Location`, `Thing`, `Concept`, `Event` | People, companies, places, objects, ideas, happenings |
|
||
| **Digital Content** | `Document`, `Media`, `File`, `Message`, `Content` | PDFs, images, videos, emails, posts, generic content |
|
||
| **Collections** | `Collection`, `Dataset` | Groups of items, structured data sets |
|
||
| **Business** | `Product`, `Service`, `User`, `Task`, `Project` | E-commerce, SaaS, project management |
|
||
| **Descriptive** | `Process`, `State`, `Role` | Workflows, conditions, responsibilities |
|
||
|
||
### 🔗 Verbs (How Things Connect)
|
||
|
||
Verbs are your relationships - they give meaning to connections. Not just "these vectors are similar" but "this OWNS
|
||
that" or "this CAUSES that".
|
||
|
||
**Available Verb Types:**
|
||
|
||
| Category | Types | Examples |
|
||
|----------------|----------------------------------------------------------------------|------------------------------------------|
|
||
| **Core** | `RelatedTo`, `Contains`, `PartOf`, `LocatedAt`, `References` | Generic relations, containment, location |
|
||
| **Temporal** | `Precedes`, `Succeeds`, `Causes`, `DependsOn`, `Requires` | Time sequences, causality, dependencies |
|
||
| **Creation** | `Creates`, `Transforms`, `Becomes`, `Modifies`, `Consumes` | Creation, change, consumption |
|
||
| **Ownership** | `Owns`, `AttributedTo`, `CreatedBy`, `BelongsTo` | Ownership, authorship, belonging |
|
||
| **Social** | `MemberOf`, `WorksWith`, `FriendOf`, `Follows`, `Likes`, `ReportsTo` | Social networks, organizations |
|
||
| **Functional** | `Describes`, `Implements`, `Validates`, `Triggers`, `Serves` | Functions, implementations, services |
|
||
|
||
### 💡 Why This Matters
|
||
|
||
```javascript
|
||
// Traditional vector DB: Just similarity
|
||
const similar = await vectorDB.search(embedding, 10)
|
||
// Result: [vector1, vector2, ...] - What do these mean? 🤷
|
||
|
||
// Brainy: Similarity + Meaning + Relationships
|
||
const catId = await brainy.add("Siamese cat", {
|
||
noun: NounType.Thing,
|
||
breed: "Siamese"
|
||
})
|
||
const ownerId = await brainy.add("John Smith", {
|
||
noun: NounType.Person
|
||
})
|
||
await brainy.addVerb(ownerId, catId, {
|
||
verb: VerbType.Owns,
|
||
since: "2020-01-01"
|
||
})
|
||
|
||
// Now you can search with context!
|
||
const johnsPets = await brainy.getVerbsBySource(ownerId, VerbType.Owns)
|
||
const catOwners = await brainy.getVerbsByTarget(catId, VerbType.Owns)
|
||
```
|
||
|
||
## 🌍 Distributed Mode (New!)
|
||
|
||
Brainy now supports **distributed deployments** with multiple specialized instances sharing the same data. Perfect for
|
||
scaling your AI applications across multiple servers.
|
||
|
||
### Distributed Setup
|
||
|
||
```javascript
|
||
// Single instance (no change needed!)
|
||
const brainy = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } }
|
||
})
|
||
|
||
// Distributed mode requires explicit role configuration
|
||
// Option 1: Via environment variable
|
||
process.env.BRAINY_ROLE = 'writer' // or 'reader' or 'hybrid'
|
||
const brainy = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } },
|
||
distributed: true
|
||
})
|
||
|
||
// Option 2: Via configuration
|
||
const writer = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } },
|
||
distributed: { role: 'writer' } // Handles data ingestion
|
||
})
|
||
|
||
const reader = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } },
|
||
distributed: { role: 'reader' } // Optimized for queries
|
||
})
|
||
|
||
// Option 3: Via read/write mode (role auto-inferred)
|
||
const writer = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } },
|
||
writeOnly: true, // Automatically becomes 'writer' role
|
||
distributed: true
|
||
})
|
||
|
||
const reader = createAutoBrainy({
|
||
storage: { s3Storage: { bucketName: 'my-bucket' } },
|
||
readOnly: true, // Automatically becomes 'reader' role
|
||
distributed: true
|
||
})
|
||
```
|
||
|
||
### Key Distributed Features
|
||
|
||
**🎯 Explicit Role Configuration**
|
||
|
||
- Roles must be explicitly set (no dangerous auto-assignment)
|
||
- Can use environment variables, config, or read/write modes
|
||
- Clear separation between writers and readers
|
||
|
||
**#️⃣ Hash-Based Partitioning**
|
||
|
||
- Handles multiple writers with different data types
|
||
- Even distribution across partitions
|
||
- No semantic conflicts with mixed data
|
||
|
||
**🏷️ Domain Tagging**
|
||
|
||
- Automatic domain detection (medical, legal, product, etc.)
|
||
- Filter searches by domain
|
||
- Logical separation without complexity
|
||
|
||
```javascript
|
||
// Data is automatically tagged with domains
|
||
await brainy.add({
|
||
symptoms: "fever",
|
||
diagnosis: "flu"
|
||
}, metadata) // Auto-tagged as 'medical'
|
||
|
||
// Search within specific domains
|
||
const medicalResults = await brainy.search(query, 10, {
|
||
filter: { domain: 'medical' }
|
||
})
|
||
```
|
||
|
||
**📊 Health Monitoring**
|
||
|
||
- Real-time health metrics
|
||
- Automatic dead instance cleanup
|
||
- Performance tracking
|
||
|
||
```javascript
|
||
// Get health status
|
||
const health = brainy.getHealthStatus()
|
||
// {
|
||
// status: 'healthy',
|
||
// role: 'reader',
|
||
// vectorCount: 1000000,
|
||
// cacheHitRate: 0.95,
|
||
// requestsPerSecond: 150
|
||
// }
|
||
```
|
||
|
||
**⚡ Role-Optimized Performance**
|
||
|
||
- **Readers**: 80% memory for cache, aggressive prefetching
|
||
- **Writers**: Optimized write batching, minimal cache
|
||
- **Hybrid**: Adaptive based on workload
|
||
|
||
### Deployment Examples
|
||
|
||
**Docker Compose**
|
||
|
||
```yaml
|
||
services:
|
||
writer:
|
||
image: myapp
|
||
environment:
|
||
BRAINY_ROLE: writer # Optional - auto-detects
|
||
|
||
reader:
|
||
image: myapp
|
||
environment:
|
||
BRAINY_ROLE: reader # Optional - auto-detects
|
||
scale: 5
|
||
```
|
||
|
||
**Kubernetes**
|
||
|
||
```yaml
|
||
# Automatically detects role from deployment type
|
||
apiVersion: apps/v1
|
||
kind: Deployment
|
||
metadata:
|
||
name: brainy-readers
|
||
spec:
|
||
replicas: 10 # Multiple readers
|
||
template:
|
||
spec:
|
||
containers:
|
||
- name: app
|
||
image: myapp
|
||
# Role auto-detected as 'reader' (multiple replicas)
|
||
```
|
||
|
||
**Benefits**
|
||
|
||
- ✅ **50-70% faster searches** with parallel readers
|
||
- ✅ **No coordination complexity** - Shared JSON config in S3
|
||
- ✅ **Zero downtime scaling** - Add/remove instances anytime
|
||
- ✅ **Automatic failover** - Dead instances cleaned up automatically
|
||
|
||
## 🤔 Why Choose Brainy?
|
||
|
||
### vs. Traditional Databases
|
||
|
||
❌ **PostgreSQL with pgvector** - Requires complex setup, tuning, and DevOps expertise
|
||
✅ **Brainy** - Zero config, auto-optimizes, works everywhere from browser to cloud
|
||
|
||
### vs. Vector Databases
|
||
|
||
❌ **Pinecone/Weaviate/Qdrant** - Cloud-only, expensive, vendor lock-in
|
||
✅ **Brainy** - Run locally, in browser, or cloud. Your choice, your data
|
||
|
||
### vs. Graph Databases
|
||
|
||
❌ **Neo4j** - Great for graphs, no vector support
|
||
✅ **Brainy** - Vectors + graphs in one. Best of both worlds
|
||
|
||
### vs. DIY Solutions
|
||
|
||
❌ **Building your own** - Months of work, optimization nightmares
|
||
✅ **Brainy** - Production-ready in 30 seconds
|
||
|
||
## 🚀 Getting Started in 30 Seconds
|
||
|
||
### React
|
||
|
||
```jsx
|
||
import { createAutoBrainy } from 'brainy'
|
||
import { useEffect, useState } from 'react'
|
||
|
||
function SemanticSearch() {
|
||
const [brainy] = useState(() => createAutoBrainy())
|
||
const [results, setResults] = useState([])
|
||
|
||
const search = async (query) => {
|
||
const items = await brainy.searchText(query, 10)
|
||
setResults(items)
|
||
}
|
||
|
||
return (
|
||
<input onChange={(e) => search(e.target.value)}
|
||
placeholder="Search by meaning..." />
|
||
)
|
||
}
|
||
```
|
||
|
||
### Angular
|
||
|
||
```typescript
|
||
import { Component, OnInit } from '@angular/core'
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
@Component({
|
||
selector: 'app-search',
|
||
template: `
|
||
<input (input)="search($event.target.value)"
|
||
placeholder="Semantic search...">
|
||
<div *ngFor="let result of results">
|
||
{{ result.text }}
|
||
</div>
|
||
`
|
||
})
|
||
export class SearchComponent implements OnInit {
|
||
brainy = createAutoBrainy()
|
||
results = []
|
||
|
||
async search(query: string) {
|
||
this.results = await this.brainy.searchText(query, 10)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Vue 3
|
||
|
||
```vue
|
||
|
||
<script setup>
|
||
import { createAutoBrainy } from 'brainy'
|
||
import { ref } from 'vue'
|
||
|
||
const brainy = createAutoBrainy()
|
||
const results = ref([])
|
||
|
||
const search = async (query) => {
|
||
results.value = await brainy.searchText(query, 10)
|
||
}
|
||
</script>
|
||
|
||
<template>
|
||
<input @input="search($event.target.value)"
|
||
placeholder="Find similar content...">
|
||
<div v-for="result in results" :key="result.id">
|
||
{{ result.text }}
|
||
</div>
|
||
</template>
|
||
```
|
||
|
||
### Svelte
|
||
|
||
```svelte
|
||
<script>
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
const brainy = createAutoBrainy()
|
||
let results = []
|
||
|
||
async function search(e) {
|
||
results = await brainy.searchText(e.target.value, 10)
|
||
}
|
||
</script>
|
||
|
||
<input on:input={search} placeholder="AI-powered search...">
|
||
{#each results as result}
|
||
<div>{result.text}</div>
|
||
{/each}
|
||
```
|
||
|
||
### Next.js (App Router)
|
||
|
||
```jsx
|
||
// app/search/page.js
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
export default function SearchPage() {
|
||
async function search(formData) {
|
||
'use server'
|
||
const brainy = createAutoBrainy({ bucketName: 'vectors' })
|
||
const query = formData.get('query')
|
||
return await brainy.searchText(query, 10)
|
||
}
|
||
|
||
return (
|
||
<form action={search}>
|
||
<input name="query" placeholder="Search..." />
|
||
<button type="submit">Search</button>
|
||
</form>
|
||
)
|
||
}
|
||
```
|
||
|
||
### Node.js / Bun / Deno
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
const brainy = createAutoBrainy()
|
||
|
||
// Add some data
|
||
await brainy.add("TypeScript is a typed superset of JavaScript", {
|
||
category: 'programming'
|
||
})
|
||
|
||
// Search for similar content
|
||
const results = await brainy.searchText("JavaScript with types", 5)
|
||
console.log(results)
|
||
```
|
||
|
||
### 🌍 Framework-First, Runs Everywhere
|
||
|
||
**Brainy is designed for modern frameworks** with automatic environment detection and storage selection:
|
||
|
||
**✨ Supported environments:**
|
||
- ⚛️ **React/Vue/Angular** - Framework-optimized builds with proper bundling
|
||
- 🟢 **Node.js/Deno/Bun** - Full server-side capabilities
|
||
- ⚡ **Serverless/Edge** - Optimized for cold starts and minimal footprint
|
||
- 🧵 **Web/Worker threads** - Thread-safe, shared storage
|
||
|
||
**🗄️ Auto-selected storage:**
|
||
- 🌐 **OPFS** - Browser frameworks (persistent, fast)
|
||
- 📁 **FileSystem** - Node.js servers (local development)
|
||
- ☁️ **S3/R2/GCS** - Production, serverless, distributed deployments
|
||
- 💾 **Memory** - Edge workers, testing, temporary data
|
||
|
||
**🚀 Framework benefits:**
|
||
- ✅ **Proper bundling** - Handles dynamic imports and dependencies correctly
|
||
- ✅ **Type safety** - Full TypeScript integration and IntelliSense
|
||
- ✅ **State management** - Reactive updates and component lifecycle
|
||
- ✅ **Production ready** - Tree-shaking, optimization, error boundaries
|
||
|
||
**Note:** We focus on framework support for reliability. Vanilla JS had too many module resolution issues.
|
||
|
||
### Cloudflare Workers
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
export default {
|
||
async fetch(request, env) {
|
||
const brainy = createAutoBrainy({
|
||
bucketName: env.R2_BUCKET
|
||
})
|
||
|
||
const url = new URL(request.url)
|
||
const query = url.searchParams.get('q')
|
||
|
||
const results = await brainy.searchText(query, 10)
|
||
return Response.json(results)
|
||
}
|
||
}
|
||
```
|
||
|
||
### AWS Lambda
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
export const handler = async (event) => {
|
||
const brainy = createAutoBrainy({
|
||
bucketName: process.env.S3_BUCKET
|
||
})
|
||
|
||
const results = await brainy.searchText(event.query, 10)
|
||
|
||
return {
|
||
statusCode: 200,
|
||
body: JSON.stringify(results)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Azure Functions
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
module.exports = async function(context, req) {
|
||
const brainy = createAutoBrainy({
|
||
bucketName: process.env.AZURE_STORAGE_CONTAINER
|
||
})
|
||
|
||
const results = await brainy.searchText(req.query.q, 10)
|
||
|
||
context.res = {
|
||
body: results
|
||
}
|
||
}
|
||
```
|
||
|
||
### Google Cloud Functions
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
export const searchHandler = async (req, res) => {
|
||
const brainy = createAutoBrainy({
|
||
bucketName: process.env.GCS_BUCKET
|
||
})
|
||
|
||
const results = await brainy.searchText(req.query.q, 10)
|
||
res.json(results)
|
||
}
|
||
```
|
||
|
||
### Google Cloud Run
|
||
|
||
```dockerfile
|
||
# Dockerfile
|
||
FROM node:20-alpine
|
||
USER node
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm install brainy
|
||
COPY . .
|
||
CMD ["node", "server.js"]
|
||
```
|
||
|
||
```javascript
|
||
// server.js
|
||
import { createAutoBrainy } from 'brainy'
|
||
import express from 'express'
|
||
|
||
const app = express()
|
||
const brainy = createAutoBrainy({
|
||
bucketName: process.env.GCS_BUCKET
|
||
})
|
||
|
||
app.get('/search', async (req, res) => {
|
||
const results = await brainy.searchText(req.query.q, 10)
|
||
res.json(results)
|
||
})
|
||
|
||
const port = process.env.PORT || 8080
|
||
app.listen(port, () => console.log(`Brainy on Cloud Run: ${port}`))
|
||
```
|
||
|
||
```bash
|
||
# Deploy to Cloud Run
|
||
gcloud run deploy brainy-api \
|
||
--source . \
|
||
--platform managed \
|
||
--region us-central1 \
|
||
--allow-unauthenticated
|
||
```
|
||
|
||
### Vercel Edge Functions
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
export const config = {
|
||
runtime: 'edge'
|
||
}
|
||
|
||
export default async function handler(request) {
|
||
const brainy = createAutoBrainy()
|
||
const { searchParams } = new URL(request.url)
|
||
const query = searchParams.get('q')
|
||
|
||
const results = await brainy.searchText(query, 10)
|
||
return Response.json(results)
|
||
}
|
||
```
|
||
|
||
### Netlify Functions
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
export async function handler(event, context) {
|
||
const brainy = createAutoBrainy()
|
||
const query = event.queryStringParameters.q
|
||
|
||
const results = await brainy.searchText(query, 10)
|
||
|
||
return {
|
||
statusCode: 200,
|
||
body: JSON.stringify(results)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Supabase Edge Functions
|
||
|
||
```typescript
|
||
import { createAutoBrainy } from 'brainy'
|
||
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
|
||
|
||
serve(async (req) => {
|
||
const brainy = createAutoBrainy()
|
||
const url = new URL(req.url)
|
||
const query = url.searchParams.get('q')
|
||
|
||
const results = await brainy.searchText(query, 10)
|
||
|
||
return new Response(JSON.stringify(results), {
|
||
headers: { 'Content-Type': 'application/json' }
|
||
})
|
||
})
|
||
```
|
||
|
||
### Docker Container
|
||
|
||
```dockerfile
|
||
FROM node:20-alpine
|
||
USER node
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm install brainy
|
||
COPY . .
|
||
|
||
CMD ["node", "server.js"]
|
||
```
|
||
|
||
```javascript
|
||
// server.js
|
||
import { createAutoBrainy } from 'brainy'
|
||
import express from 'express'
|
||
|
||
const app = express()
|
||
const brainy = createAutoBrainy()
|
||
|
||
app.get('/search', async (req, res) => {
|
||
const results = await brainy.searchText(req.query.q, 10)
|
||
res.json(results)
|
||
})
|
||
|
||
app.listen(3000, () => console.log('Brainy running on port 3000'))
|
||
```
|
||
|
||
### Kubernetes
|
||
|
||
```yaml
|
||
apiVersion: apps/v1
|
||
kind: Deployment
|
||
metadata:
|
||
name: brainy-api
|
||
spec:
|
||
replicas: 3
|
||
template:
|
||
spec:
|
||
containers:
|
||
- name: brainy
|
||
image: your-registry/brainy-api:latest
|
||
env:
|
||
- name: S3_BUCKET
|
||
value: "your-vector-bucket"
|
||
```
|
||
|
||
### Railway.app
|
||
|
||
```javascript
|
||
// server.js
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
const brainy = createAutoBrainy({
|
||
bucketName: process.env.RAILWAY_VOLUME_NAME
|
||
})
|
||
|
||
// Railway automatically handles the rest!
|
||
```
|
||
|
||
### Render.com
|
||
|
||
```yaml
|
||
# render.yaml
|
||
services:
|
||
- type: web
|
||
name: brainy-api
|
||
env: node
|
||
buildCommand: npm install brainy
|
||
startCommand: node server.js
|
||
envVars:
|
||
- key: BRAINY_STORAGE
|
||
value: persistent-disk
|
||
```
|
||
|
||
## 🚀 Quick Examples
|
||
|
||
### Basic Usage
|
||
|
||
```javascript
|
||
import { BrainyData, NounType, VerbType } from 'brainy'
|
||
|
||
// Initialize
|
||
const db = new BrainyData()
|
||
await db.init()
|
||
|
||
// Add data (automatically vectorized)
|
||
const catId = await db.add("Cats are independent pets", {
|
||
noun: NounType.Thing,
|
||
category: 'animal'
|
||
})
|
||
|
||
// Search for similar items
|
||
const results = await db.searchText("feline pets", 5)
|
||
|
||
// Add relationships
|
||
await db.addVerb(catId, dogId, {
|
||
verb: VerbType.RelatedTo,
|
||
description: 'Both are pets'
|
||
})
|
||
```
|
||
|
||
### AutoBrainy (Recommended)
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
|
||
// Everything auto-configured!
|
||
const brainy = createAutoBrainy()
|
||
|
||
// Just start using it
|
||
await brainy.addVector({ id: '1', vector: [0.1, 0.2, 0.3], text: 'Hello' })
|
||
const results = await brainy.search([0.1, 0.2, 0.3], 10)
|
||
```
|
||
|
||
### Scenario-Based Setup
|
||
|
||
```javascript
|
||
import { createQuickBrainy } from 'brainy'
|
||
|
||
// Choose your scale: 'small', 'medium', 'large', 'enterprise'
|
||
const brainy = await createQuickBrainy('large', {
|
||
bucketName: 'my-vector-db'
|
||
})
|
||
```
|
||
|
||
### With Offline Models
|
||
|
||
```javascript
|
||
import { createAutoBrainy } from 'brainy'
|
||
import { BundledUniversalSentenceEncoder } from '@soulcraft/brainy-models'
|
||
|
||
// Use bundled model for offline operation
|
||
const brainy = createAutoBrainy({
|
||
embeddingModel: BundledUniversalSentenceEncoder,
|
||
// Model loads from local files, no network needed!
|
||
})
|
||
|
||
// Works exactly the same, but 100% offline
|
||
await brainy.add("This works without internet!", {
|
||
noun: NounType.Content
|
||
})
|
||
```
|
||
|
||
## 🌐 Live Demo
|
||
|
||
**[Try the interactive demo](https://soulcraft-research.github.io/brainy/demo/index.html)** - See Brainy in action with
|
||
animations and examples.
|
||
|
||
## 🔧 Environment Support
|
||
|
||
| Environment | Storage | Threading | Auto-Configured |
|
||
|----------------|---------------|----------------|-----------------|
|
||
| Browser | OPFS | Web Workers | ✅ |
|
||
| Node.js | FileSystem/S3 | Worker Threads | ✅ |
|
||
| Serverless | Memory/S3 | Limited | ✅ |
|
||
| Edge Functions | Memory/KV | Limited | ✅ |
|
||
|
||
## 📚 Documentation
|
||
|
||
### Getting Started
|
||
|
||
- [**Quick Start Guide**](docs/getting-started/) - Get up and running in minutes
|
||
- [**Installation**](docs/getting-started/installation.md) - Detailed setup instructions
|
||
- [**Environment Setup**](docs/getting-started/environment-setup.md) - Platform-specific configuration
|
||
|
||
### User Guides
|
||
|
||
- [**Search and Metadata**](docs/user-guides/) - Advanced search techniques
|
||
- [**JSON Document Search**](docs/guides/json-document-search.md) - Field-based searching
|
||
- [**Production Migration**](docs/guides/production-migration-guide.md) - Deployment best practices
|
||
|
||
### API Reference
|
||
|
||
- [**Core API**](docs/api-reference/) - Complete method reference
|
||
- [**Configuration Options**](docs/api-reference/configuration.md) - All configuration parameters
|
||
|
||
### Optimization & Scaling
|
||
|
||
- [**Performance Features Guide**](docs/PERFORMANCE_FEATURES.md) - Advanced caching, auto-configuration, and
|
||
optimization
|
||
- [**Large-Scale Optimizations**](docs/optimization-guides/) - Handle millions of vectors
|
||
- [**Memory Management**](docs/optimization-guides/memory-optimization.md) - Efficient resource usage
|
||
- [**S3 Migration Guide**](docs/optimization-guides/s3-migration-guide.md) - Cloud storage setup
|
||
|
||
### Examples & Patterns
|
||
|
||
- [**Code Examples**](docs/examples/) - Real-world usage patterns
|
||
- [**Integrations**](docs/examples/integrations.md) - Third-party services
|
||
- [**Performance Patterns**](docs/examples/performance.md) - Optimization techniques
|
||
|
||
### Technical Documentation
|
||
|
||
- [**Architecture Overview**](docs/technical/) - System design and internals
|
||
- [**Testing Guide**](docs/technical/TESTING.md) - Testing strategies
|
||
- [**Statistics & Monitoring**](docs/technical/STATISTICS.md) - Performance tracking
|
||
|
||
## 🤝 Contributing
|
||
|
||
We welcome contributions! Please see:
|
||
|
||
- [Contributing Guidelines](CONTRIBUTING.md)
|
||
- [Developer Documentation](docs/development/DEVELOPERS.md)
|
||
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
||
|
||
## 📄 License
|
||
|
||
[MIT](LICENSE)
|
||
|
||
## 🔗 Related Projects
|
||
|
||
- [**Cartographer**](https://github.com/sodal-project/cartographer) - Standardized interfaces for Brainy
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<strong>Ready to build something amazing? Get started with Brainy today!</strong>
|
||
</div>
|