David Snelling
196690863d
- Fixed imports in examples/tests/ to use correct Brainy import - Fixed imports in tests/benchmarks/ to use correct paths - Updated bin/brainy-interactive.js to use Brainy instead of BrainyData - Corrected documentation references throughout codebase - Removed duplicate imports in benchmark files - All files now consistently use 'Brainy' class from dist/index.js
392 lines
No EOL
8.5 KiB
Markdown
392 lines
No EOL
8.5 KiB
Markdown
# 🚀 Brainy Quick Start Guide
|
||
|
||
Get up and running with Brainy in 5 minutes!
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
npm install @soulcraft/brainy
|
||
```
|
||
|
||
Or install globally for CLI access:
|
||
```bash
|
||
npm install -g brainy
|
||
```
|
||
|
||
## Basic Usage
|
||
|
||
### 1. Initialize Brainy
|
||
|
||
```javascript
|
||
import { Brainy, NounType } from '@soulcraft/brainy'
|
||
|
||
const brain = new Brainy()
|
||
await brain.init()
|
||
```
|
||
|
||
That's it! No configuration needed. Brainy automatically:
|
||
- Downloads embedding models (first time only)
|
||
- Sets up storage (in-memory by default)
|
||
- Initializes all augmentations
|
||
- Configures optimal settings
|
||
|
||
### 2. Add Your First Data
|
||
|
||
```javascript
|
||
// Add a simple string
|
||
await brain.add("JavaScript is a versatile programming language", { nounType: NounType.Concept })
|
||
|
||
// Add with metadata
|
||
await brain.add("React is a JavaScript library", {
|
||
nounType: NounType.Concept,
|
||
type: "library",
|
||
category: "frontend",
|
||
popularity: "high"
|
||
})
|
||
|
||
// Add structured data
|
||
await brain.add({
|
||
title: "Introduction to TypeScript",
|
||
content: "TypeScript adds static typing to JavaScript",
|
||
author: "John Doe"
|
||
}, {
|
||
nounType: NounType.Document,
|
||
type: "article",
|
||
date: "2024-01-15"
|
||
})
|
||
```
|
||
|
||
### 3. Search Your Data
|
||
|
||
```javascript
|
||
// Simple vector search
|
||
const results = await brain.search("programming languages")
|
||
|
||
// Natural language query
|
||
const articles = await brain.find("recent articles about TypeScript")
|
||
|
||
// With metadata filtering
|
||
const libraries = await brain.search("JavaScript", {
|
||
metadata: { type: "library" },
|
||
limit: 5
|
||
})
|
||
```
|
||
|
||
## Real-World Examples
|
||
|
||
### Example 1: Document Search System
|
||
|
||
```javascript
|
||
import { Brainy, NounType } from '@soulcraft/brainy'
|
||
import fs from 'fs'
|
||
|
||
const brain = new Brainy({
|
||
storage: {
|
||
type: 'filesystem',
|
||
path: './document-index'
|
||
}
|
||
})
|
||
await brain.init()
|
||
|
||
// Index documents
|
||
const documents = [
|
||
{ file: 'api-guide.md', content: fs.readFileSync('./docs/api-guide.md', 'utf8') },
|
||
{ file: 'tutorial.md', content: fs.readFileSync('./docs/tutorial.md', 'utf8') },
|
||
{ file: 'faq.md', content: fs.readFileSync('./docs/faq.md', 'utf8') }
|
||
]
|
||
|
||
for (const doc of documents) {
|
||
await brain.add(doc.content, {
|
||
nounType: NounType.Document,
|
||
filename: doc.file,
|
||
type: 'documentation',
|
||
indexed: new Date().toISOString()
|
||
})
|
||
}
|
||
|
||
// Search documents
|
||
const results = await brain.find("how to authenticate users")
|
||
console.log(`Found ${results.length} relevant documents:`)
|
||
results.forEach(r => console.log(`- ${r.metadata.filename} (${(r.score * 100).toFixed(1)}% match)`))
|
||
```
|
||
|
||
### Example 2: AI Chat with Memory
|
||
|
||
```javascript
|
||
import { Brainy, NounType } from '@soulcraft/brainy'
|
||
|
||
const brain = new Brainy()
|
||
await brain.init()
|
||
|
||
class ChatWithMemory {
|
||
constructor(brain) {
|
||
this.brain = brain
|
||
this.sessionId = Date.now().toString()
|
||
}
|
||
|
||
async addMessage(role, content) {
|
||
await this.brain.add(content, {
|
||
nounType: NounType.Message,
|
||
role,
|
||
sessionId: this.sessionId,
|
||
timestamp: Date.now()
|
||
})
|
||
}
|
||
|
||
async getContext(query, limit = 5) {
|
||
// Find relevant previous messages
|
||
const relevant = await this.brain.find(query, { limit })
|
||
return relevant.map(r => ({
|
||
role: r.metadata.role,
|
||
content: r.content
|
||
}))
|
||
}
|
||
|
||
async chat(userMessage) {
|
||
// Store user message
|
||
await this.addMessage('user', userMessage)
|
||
|
||
// Get relevant context
|
||
const context = await this.getContext(userMessage)
|
||
|
||
// Your AI logic here (OpenAI, Anthropic, etc.)
|
||
const aiResponse = await callYourAI(userMessage, context)
|
||
|
||
// Store AI response
|
||
await this.addMessage('assistant', aiResponse)
|
||
|
||
return aiResponse
|
||
}
|
||
}
|
||
|
||
const chat = new ChatWithMemory(brain)
|
||
const response = await chat.chat("What did we discuss about JavaScript?")
|
||
```
|
||
|
||
### Example 3: Semantic Code Search
|
||
|
||
```javascript
|
||
import { Brainy, NounType } from '@soulcraft/brainy'
|
||
import { glob } from 'glob'
|
||
import fs from 'fs'
|
||
|
||
const brain = new Brainy()
|
||
await brain.init()
|
||
|
||
// Index all JavaScript files
|
||
const files = await glob('src/**/*.js')
|
||
for (const file of files) {
|
||
const content = fs.readFileSync(file, 'utf8')
|
||
|
||
// Extract functions
|
||
const functions = content.match(/function\s+(\w+)|const\s+(\w+)\s*=/g) || []
|
||
|
||
await brain.add(content, {
|
||
nounType: NounType.File,
|
||
file,
|
||
type: 'code',
|
||
language: 'javascript',
|
||
functions: functions.map(f => f.replace(/function\s+|const\s+|=/g, '').trim())
|
||
})
|
||
}
|
||
|
||
// Search for code
|
||
const results = await brain.find("authentication middleware")
|
||
console.log('Relevant code files:')
|
||
results.forEach(r => {
|
||
console.log(`\n${r.metadata.file}:`)
|
||
console.log(` Functions: ${r.metadata.functions.join(', ')}`)
|
||
console.log(` Relevance: ${(r.score * 100).toFixed(1)}%`)
|
||
})
|
||
```
|
||
|
||
## CLI Quick Examples
|
||
|
||
```bash
|
||
# Add data from CLI
|
||
brainy add "React is a JavaScript library for building UIs"
|
||
|
||
# Search
|
||
brainy search "JavaScript frameworks"
|
||
|
||
# Natural language find
|
||
brainy find "popular frontend libraries"
|
||
|
||
# Interactive chat mode
|
||
brainy chat
|
||
|
||
# Import JSON data
|
||
brainy import data.json
|
||
|
||
# Export your brain
|
||
brainy export --format json > backup.json
|
||
|
||
# Check status
|
||
brainy status
|
||
```
|
||
|
||
## Advanced Features
|
||
|
||
### Triple Intelligence Query
|
||
|
||
```javascript
|
||
// Combine vector search + metadata filters + graph relationships
|
||
const results = await brain.find({
|
||
like: "React", // Vector similarity
|
||
where: { // Metadata filtering
|
||
type: "library",
|
||
popularity: "high",
|
||
year: { greaterThan: 2015 }
|
||
},
|
||
related: { // Graph relationships
|
||
to: "JavaScript",
|
||
depth: 2
|
||
}
|
||
}, {
|
||
limit: 10,
|
||
includeContent: true
|
||
})
|
||
```
|
||
|
||
### Pagination
|
||
|
||
```javascript
|
||
// Cursor-based pagination for large result sets
|
||
let cursor = null
|
||
do {
|
||
const results = await brain.search("programming", {
|
||
limit: 100,
|
||
cursor
|
||
})
|
||
|
||
// Process batch
|
||
results.forEach(processResult)
|
||
|
||
cursor = results.nextCursor
|
||
} while (cursor)
|
||
```
|
||
|
||
### Performance Optimization
|
||
|
||
```javascript
|
||
// Pre-filter with metadata for faster searches
|
||
const results = await brain.search("*", {
|
||
metadata: {
|
||
type: "article",
|
||
category: "tech",
|
||
date: { greaterThan: "2024-01-01" }
|
||
},
|
||
limit: 1000
|
||
})
|
||
```
|
||
|
||
## Storage Options
|
||
|
||
### Memory (Testing)
|
||
```javascript
|
||
const brain = new Brainy() // Default
|
||
```
|
||
|
||
### FileSystem (Development)
|
||
```javascript
|
||
const brain = new Brainy({
|
||
storage: {
|
||
type: 'filesystem',
|
||
path: './brain-data'
|
||
}
|
||
})
|
||
```
|
||
|
||
### Browser (OPFS)
|
||
```javascript
|
||
const brain = new Brainy({
|
||
storage: { type: 'opfs' }
|
||
})
|
||
```
|
||
|
||
### S3 (Production)
|
||
```javascript
|
||
const brain = new Brainy({
|
||
storage: {
|
||
type: 's3',
|
||
bucket: 'my-brain-bucket',
|
||
region: 'us-east-1',
|
||
credentials: {
|
||
accessKeyId: process.env.AWS_ACCESS_KEY,
|
||
secretAccessKey: process.env.AWS_SECRET_KEY
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
## Tips & Best Practices
|
||
|
||
1. **Use metadata liberally** - It enables O(log n) filtering
|
||
2. **Batch operations when possible** - Use `import()` for bulk data
|
||
3. **Enable caching for production** - Automatic with default settings
|
||
4. **Use cursor pagination** - For large result sets
|
||
5. **Leverage natural language** - `find()` understands context
|
||
|
||
## Common Patterns
|
||
|
||
### Similarity Search
|
||
```javascript
|
||
// Find similar items to an existing one
|
||
const item = await brain.getNoun(id)
|
||
const similar = await brain.search(item.content, { limit: 5 })
|
||
```
|
||
|
||
### Time-based Queries
|
||
```javascript
|
||
// Recent items
|
||
const recent = await brain.search("*", {
|
||
metadata: {
|
||
timestamp: { greaterThan: Date.now() - 86400000 } // Last 24 hours
|
||
}
|
||
})
|
||
```
|
||
|
||
### Category Browsing
|
||
```javascript
|
||
// Get all items in a category
|
||
const category = await brain.search("*", {
|
||
metadata: { category: "tutorials" },
|
||
limit: 100
|
||
})
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### Models not loading?
|
||
```bash
|
||
# Clear cache and re-download
|
||
rm -rf ~/.cache/brainy
|
||
npm run download-models
|
||
```
|
||
|
||
### Slow initialization?
|
||
- First run downloads models (~25MB)
|
||
- Subsequent runs use cache (< 500ms)
|
||
- Use `storage: { type: 'memory' }` for testing
|
||
|
||
### Out of memory?
|
||
- Use filesystem or S3 storage for large datasets
|
||
- Enable worker threads (automatic in Node.js)
|
||
- Increase Node memory: `NODE_OPTIONS='--max-old-space-size=4096'`
|
||
|
||
## Next Steps
|
||
|
||
- 📖 Read the [full documentation](../README.md)
|
||
- 🏗️ Learn about [augmentations](augmentations/README.md)
|
||
- 🧠 Understand [Triple Intelligence](architecture/triple-intelligence.md)
|
||
- ☁️ Explore [Brain Cloud](https://soulcraft.com)
|
||
|
||
## Get Help
|
||
|
||
- GitHub Issues: [github.com/brainy-org/brainy](https://github.com/brainy-org/brainy)
|
||
- Documentation: [Full Docs](../README.md)
|
||
- Examples: [/examples](../../examples)
|
||
|
||
---
|
||
|
||
**Ready to build something amazing? You're all set! 🚀** |