feat: v5.1.0 - VFS auto-initialization and complete API documentation
BREAKING CHANGES: - VFS API changed from brain.vfs() (method) to brain.vfs (property) - VFS now auto-initializes during brain.init() - no separate vfs.init() needed Features: - VFS auto-initialization with property access pattern - Complete TypeAware COW support verification (all 20 methods) - Comprehensive API documentation (docs/api/README.md) - All 7 storage adapters verified with COW support Bug Fixes: - CLI now properly initializes brain before VFS operations - Fixed infinite recursion in VFS initialization - All VFS CLI commands updated to modern API Documentation: - Created comprehensive, verified API reference - Consolidated documentation structure (deleted redundant quick starts) - Updated all VFS docs to v5.1.0 patterns - Fixed all internal documentation links Verification: - Memory Storage: 23/24 tests (95.8%) - FileSystem Storage: 9/9 tests (100%) - VFS Auto-Init: 7/7 tests (100%) - Zero fake code confirmed
This commit is contained in:
parent
5e16f9e5e8
commit
d4c9f71345
20 changed files with 2306 additions and 1343 deletions
|
|
@ -1,392 +0,0 @@
|
|||
# 🚀 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! 🚀**
|
||||
|
|
@ -26,7 +26,7 @@ Welcome to the comprehensive documentation for Brainy, the multi-dimensional AI
|
|||
## Quick Links
|
||||
|
||||
### Getting Started
|
||||
- [Quick Start Guide](./guides/getting-started.md) - Get up and running in minutes
|
||||
- [API Reference](./api/README.md) - Complete API documentation (start here!)
|
||||
- [Enterprise for Everyone](./guides/enterprise-for-everyone.md) - **No limits, no tiers, everything free**
|
||||
- [Natural Language Queries](./guides/natural-language.md) - Query with plain English
|
||||
|
||||
|
|
@ -111,9 +111,8 @@ const results = await brain.find("highly rated technology articles by researcher
|
|||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [Getting Started](./guides/getting-started.md) | 5-minute setup guide - install, configure, first query |
|
||||
| [API Reference](./api/README.md) | **START HERE** - Complete API documentation with examples |
|
||||
| [VFS Quick Start](./vfs/QUICK_START.md) | Virtual filesystem in 30 seconds |
|
||||
| [Quick Start](./QUICK-START.md) | Alternative quick start guide |
|
||||
|
||||
### 🆕 v4.0.0 Migration & Optimization
|
||||
|
||||
|
|
@ -259,7 +258,6 @@ docs/
|
|||
├── MIGRATION-V3-TO-V4.md # v4.0.0 migration guide
|
||||
│
|
||||
├── guides/ # User guides
|
||||
│ ├── getting-started.md
|
||||
│ ├── natural-language.md
|
||||
│ ├── neural-api.md
|
||||
│ ├── import-anything.md
|
||||
|
|
|
|||
1517
docs/api/README.md
1517
docs/api/README.md
File diff suppressed because it is too large
Load diff
|
|
@ -442,4 +442,4 @@ Brainy is more than software—it's a movement to democratize enterprise technol
|
|||
- [Zero Configuration](../architecture/zero-config.md)
|
||||
- [Augmentations System](../architecture/augmentations.md)
|
||||
- [Architecture Overview](../architecture/overview.md)
|
||||
- [Getting Started](./getting-started.md)
|
||||
- [API Reference](../api/README.md)
|
||||
|
|
@ -1,333 +0,0 @@
|
|||
# Getting Started with Brainy
|
||||
|
||||
This guide will help you get up and running with Brainy, the multi-dimensional AI database that combines vector similarity, graph relationships, and metadata filtering.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @soulcraft/brainy
|
||||
```
|
||||
|
||||
## Basic Setup
|
||||
|
||||
### Simple Initialization
|
||||
|
||||
```typescript
|
||||
import { Brainy } from '@soulcraft/brainy'
|
||||
|
||||
// Create a new Brainy instance with defaults
|
||||
const brain = new Brainy()
|
||||
|
||||
// Initialize (downloads models if needed)
|
||||
await brain.init()
|
||||
|
||||
// You're ready to go!
|
||||
```
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
// Storage configuration
|
||||
storage: {
|
||||
type: 'filesystem', // or 's3', 'opfs'
|
||||
path: './my-data'
|
||||
},
|
||||
|
||||
// Vector configuration
|
||||
vectors: {
|
||||
dimensions: 384,
|
||||
model: 'all-MiniLM-L6-v2'
|
||||
},
|
||||
|
||||
// Performance tuning
|
||||
cache: {
|
||||
enabled: true,
|
||||
maxSize: 1000
|
||||
}
|
||||
})
|
||||
|
||||
await brain.init()
|
||||
```
|
||||
|
||||
## Your First Operations
|
||||
|
||||
### Adding Data
|
||||
|
||||
```typescript
|
||||
// Add entities (nouns) with automatic embedding generation
|
||||
const id = await brain.add("The quick brown fox jumps over the lazy dog", {
|
||||
category: "demo",
|
||||
timestamp: Date.now()
|
||||
})
|
||||
|
||||
console.log(`Added noun with ID: ${id}`)
|
||||
|
||||
// Add relationships (verbs) between entities
|
||||
const sourceId = await brain.add("John Smith", { nounType: 'person' })
|
||||
const targetId = await brain.add("TechCorp", { nounType: 'organization' })
|
||||
await brain.relate(sourceId, targetId, "works_at", {
|
||||
position: "Engineer",
|
||||
since: "2024"
|
||||
})
|
||||
```
|
||||
|
||||
### Searching
|
||||
|
||||
```typescript
|
||||
// Simple semantic search
|
||||
const results = await brain.search("fast animals")
|
||||
|
||||
results.forEach(result => {
|
||||
console.log(`Found: ${result.content} (score: ${result.score})`)
|
||||
})
|
||||
```
|
||||
|
||||
### Advanced Queries with find()
|
||||
|
||||
```typescript
|
||||
// Natural language queries - Brainy understands intent!
|
||||
const results = await brain.find("show me technology articles about AI from 2023")
|
||||
// Automatically interprets: topic, category, and time range
|
||||
|
||||
// Structured queries with vector similarity and metadata filtering
|
||||
const structured = await brain.find({
|
||||
like: "artificial intelligence",
|
||||
where: {
|
||||
category: "technology",
|
||||
year: { $gte: 2023 }
|
||||
},
|
||||
limit: 10
|
||||
})
|
||||
|
||||
// Complex natural language with multiple filters
|
||||
const complex = await brain.find("financial reports from Q3 2024 with revenue over 1M")
|
||||
// Automatically extracts: document type, date range, numeric filters
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Semantic Search Engine
|
||||
|
||||
```typescript
|
||||
// Index documents
|
||||
const documents = [
|
||||
{ title: "Introduction to AI", content: "AI is transforming..." },
|
||||
{ title: "Machine Learning Basics", content: "ML algorithms..." },
|
||||
{ title: "Deep Learning", content: "Neural networks..." }
|
||||
]
|
||||
|
||||
for (const doc of documents) {
|
||||
await brain.add(doc.content, {
|
||||
title: doc.title,
|
||||
type: "document"
|
||||
})
|
||||
}
|
||||
|
||||
// Search semantically
|
||||
const results = await brain.search("how do neural networks work")
|
||||
```
|
||||
|
||||
### 2. Recommendation System
|
||||
|
||||
```typescript
|
||||
// Add user interactions as nouns
|
||||
const interactionId = await brain.add("user viewed product", {
|
||||
userId: "user123",
|
||||
productId: "product456",
|
||||
action: "view",
|
||||
timestamp: Date.now()
|
||||
})
|
||||
|
||||
// Create relationships between users and products
|
||||
const userId = await brain.add("user123", { nounType: 'user' })
|
||||
const productId = await brain.add("product456", { nounType: 'product' })
|
||||
await brain.relate(userId, productId, "viewed", {
|
||||
timestamp: Date.now()
|
||||
})
|
||||
|
||||
// Natural language query for recommendations
|
||||
const recommendations = await brain.find("products similar to what user123 viewed recently")
|
||||
|
||||
// Or structured query for similar users
|
||||
const similar = await brain.find({
|
||||
like: "user123 interests",
|
||||
where: { action: "view" },
|
||||
limit: 5
|
||||
})
|
||||
```
|
||||
|
||||
### 3. Knowledge Graph
|
||||
|
||||
```typescript
|
||||
// Add entities (nouns) to the knowledge graph
|
||||
const personId = await brain.add("John Smith, Software Engineer", {
|
||||
type: "person",
|
||||
role: "engineer"
|
||||
})
|
||||
|
||||
const companyId = await brain.add("TechCorp, Innovation Leader", {
|
||||
type: "company",
|
||||
industry: "technology"
|
||||
})
|
||||
|
||||
// Create relationship
|
||||
await brain.relate(personId, companyId, "works_at", {
|
||||
since: "2020",
|
||||
position: "Senior Engineer"
|
||||
})
|
||||
|
||||
// Natural language query for relationships
|
||||
const colleagues = await brain.find("people who work at TechCorp")
|
||||
|
||||
// Or structured query for specific relationships
|
||||
const results = await brain.find({
|
||||
connected: {
|
||||
from: personId,
|
||||
type: "works_at"
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### 4. Real-time Data Processing
|
||||
|
||||
```typescript
|
||||
// Configure for streaming
|
||||
const brain = new Brainy({
|
||||
augmentations: [
|
||||
new EntityRegistryAugmentation(), // Deduplication
|
||||
new BatchProcessingAugmentation({ batchSize: 100 }) // Batching
|
||||
]
|
||||
})
|
||||
|
||||
// Process streaming data
|
||||
async function processStream(item) {
|
||||
// Entity registry prevents duplicate nouns
|
||||
const id = await brain.add(item.content, {
|
||||
externalId: item.id,
|
||||
timestamp: item.timestamp
|
||||
})
|
||||
|
||||
// Real-time natural language queries
|
||||
if (item.urgent) {
|
||||
const related = await brain.find(`urgent items similar to ${item.content}`)
|
||||
// Process related items...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Storage Options
|
||||
|
||||
### Development (FileSystem)
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
storage: { type: 'filesystem', path: '/tmp/brainy-dev' }
|
||||
})
|
||||
// Fast, persistent, perfect for testing
|
||||
```
|
||||
|
||||
### Production (FileSystem)
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
path: '/var/lib/brainy'
|
||||
}
|
||||
})
|
||||
// Persistent, efficient, server-ready
|
||||
```
|
||||
|
||||
### Cloud (S3)
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
storage: {
|
||||
type: 's3',
|
||||
bucket: 'my-brainy-data',
|
||||
region: 'us-east-1'
|
||||
}
|
||||
})
|
||||
// Scalable, distributed, cloud-native
|
||||
```
|
||||
|
||||
### Browser (OPFS)
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
storage: { type: 'opfs' }
|
||||
})
|
||||
// Browser-native, persistent, offline-capable
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### 1. Use Batch Operations
|
||||
```typescript
|
||||
// Good - batch operations for nouns
|
||||
const items = ["item1", "item2", "item3"]
|
||||
for (const item of items) {
|
||||
await brain.add(item, { batch: true })
|
||||
}
|
||||
|
||||
// Create relationships efficiently
|
||||
const relationships = [
|
||||
{ source: id1, target: id2, type: "related" },
|
||||
{ source: id2, target: id3, type: "similar" }
|
||||
]
|
||||
for (const rel of relationships) {
|
||||
await brain.relate(rel.source, rel.target, rel.type)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Enable Caching
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
cache: {
|
||||
enabled: true,
|
||||
maxSize: 1000,
|
||||
ttl: 300000 // 5 minutes
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### 3. Use Appropriate Limits
|
||||
```typescript
|
||||
// Always specify reasonable limits
|
||||
const results = await brain.search("query", {
|
||||
limit: 20 // Don't fetch more than needed
|
||||
})
|
||||
```
|
||||
|
||||
### 4. Index Frequently Queried Fields
|
||||
```typescript
|
||||
const brain = new Brainy({
|
||||
indexedFields: ['category', 'userId', 'timestamp']
|
||||
})
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await brain.add("content", metadata)
|
||||
} catch (error) {
|
||||
if (error.code === 'STORAGE_FULL') {
|
||||
console.error('Storage is full')
|
||||
} else if (error.code === 'INVALID_INPUT') {
|
||||
console.error('Invalid input:', error.message)
|
||||
} else {
|
||||
console.error('Unexpected error:', error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Architecture Overview](../architecture/overview.md) - Understand the system design
|
||||
- [Triple Intelligence](../architecture/triple-intelligence.md) - Advanced query capabilities
|
||||
- [API Reference](../api/README.md) - Complete API documentation
|
||||
- [Examples](https://github.com/brainy-org/brainy/tree/main/examples) - More code examples
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/brainy-org/brainy/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/brainy-org/brainy/discussions)
|
||||
- **Examples**: Check the `/examples` directory
|
||||
|
|
@ -280,5 +280,4 @@ While powerful, the NLP system has some limitations:
|
|||
## Next Steps
|
||||
|
||||
- [Triple Intelligence Architecture](../architecture/triple-intelligence.md)
|
||||
- [API Reference](../api/README.md)
|
||||
- [Getting Started Guide](./getting-started.md)
|
||||
- [API Reference](../api/README.md)
|
||||
|
|
@ -28,11 +28,7 @@ const brain = new Brainy({
|
|||
}
|
||||
})
|
||||
|
||||
await brain.init()
|
||||
|
||||
// ✅ CORRECT: Initialize VFS
|
||||
const vfs = brain.vfs()
|
||||
await vfs.init()
|
||||
await brain.init() // VFS auto-initialized!
|
||||
|
||||
console.log('🎉 VFS ready!')
|
||||
```
|
||||
|
|
@ -50,9 +46,9 @@ const badItems = allNodes.filter(node => node.path.startsWith(dirPath))
|
|||
**✅ CORRECT - Use tree-aware methods:**
|
||||
```typescript
|
||||
// ✅ Method 1: Get direct children (recommended for UI)
|
||||
async function loadDirectoryContents(path: string) {
|
||||
async function loadDirectoryContents(brain: Brainy, path: string) {
|
||||
try {
|
||||
const children = await vfs.getDirectChildren(path)
|
||||
const children = await brain.vfs.getDirectChildren(path)
|
||||
|
||||
// Sort directories first, then files
|
||||
return children.sort((a, b) => {
|
||||
|
|
@ -67,8 +63,8 @@ async function loadDirectoryContents(path: string) {
|
|||
}
|
||||
|
||||
// ✅ Method 2: Get complete tree structure (for full trees)
|
||||
async function loadFullTree(path: string) {
|
||||
const tree = await vfs.getTreeStructure(path, {
|
||||
async function loadFullTree(brain: Brainy, path: string) {
|
||||
const tree = await brain.vfs.getTreeStructure(path, {
|
||||
maxDepth: 3, // Prevent deep recursion
|
||||
includeHidden: false, // Skip hidden files
|
||||
sort: 'name'
|
||||
|
|
@ -77,8 +73,8 @@ async function loadFullTree(path: string) {
|
|||
}
|
||||
|
||||
// ✅ Method 3: Get detailed path info
|
||||
async function inspectPath(path: string) {
|
||||
const info = await vfs.inspect(path)
|
||||
async function inspectPath(brain: Brainy, path: string) {
|
||||
const info = await brain.vfs.inspect(path)
|
||||
return {
|
||||
isDirectory: info.node.metadata.vfsType === 'directory',
|
||||
children: info.children,
|
||||
|
|
@ -92,8 +88,8 @@ async function inspectPath(path: string) {
|
|||
|
||||
```typescript
|
||||
// ✅ Find files by content, not just filename
|
||||
async function searchFiles(query: string, basePath: string = '/') {
|
||||
const results = await vfs.search(query, {
|
||||
async function searchFiles(brain: Brainy, query: string, basePath: string = '/') {
|
||||
const results = await brain.vfs.search(query, {
|
||||
path: basePath, // Limit search to specific directory
|
||||
limit: 50, // Reasonable limit
|
||||
type: 'file' // Only search files, not directories
|
||||
|
|
@ -122,37 +118,34 @@ import React, { useState, useEffect } from 'react'
|
|||
import { Brainy } from '@soulcraft/brainy'
|
||||
|
||||
export function FileExplorer() {
|
||||
const [vfs, setVfs] = useState(null)
|
||||
const [brain, setBrain] = useState(null)
|
||||
const [currentPath, setCurrentPath] = useState('/')
|
||||
const [items, setItems] = useState([])
|
||||
const [loading, setLoading] = useState(true)
|
||||
const [searchQuery, setSearchQuery] = useState('')
|
||||
|
||||
// Initialize VFS
|
||||
// Initialize Brainy (VFS auto-initialized!)
|
||||
useEffect(() => {
|
||||
async function initVFS() {
|
||||
const brain = new Brainy({
|
||||
async function initBrainy() {
|
||||
const brainInstance = new Brainy({
|
||||
storage: { type: 'filesystem', path: './brainy-data' }
|
||||
})
|
||||
await brain.init()
|
||||
await brainInstance.init() // VFS ready after this!
|
||||
|
||||
const vfsInstance = brain.vfs()
|
||||
await vfsInstance.init()
|
||||
|
||||
setVfs(vfsInstance)
|
||||
setBrain(brainInstance)
|
||||
setLoading(false)
|
||||
}
|
||||
initVFS()
|
||||
initBrainy()
|
||||
}, [])
|
||||
|
||||
// Load directory contents
|
||||
const loadDirectory = async (path: string) => {
|
||||
if (!vfs) return
|
||||
if (!brain) return
|
||||
|
||||
setLoading(true)
|
||||
try {
|
||||
// ✅ CORRECT: Use getDirectChildren to prevent recursion
|
||||
const children = await vfs.getDirectChildren(path)
|
||||
const children = await brain.vfs.getDirectChildren(path)
|
||||
|
||||
// Sort directories first
|
||||
const sorted = children.sort((a, b) => {
|
||||
|
|
@ -173,14 +166,14 @@ export function FileExplorer() {
|
|||
|
||||
// Search files
|
||||
const handleSearch = async () => {
|
||||
if (!vfs || !searchQuery.trim()) {
|
||||
if (!brain || !searchQuery.trim()) {
|
||||
loadDirectory(currentPath)
|
||||
return
|
||||
}
|
||||
|
||||
setLoading(true)
|
||||
try {
|
||||
const results = await vfs.search(searchQuery, {
|
||||
const results = await brain.vfs.search(searchQuery, {
|
||||
path: currentPath,
|
||||
limit: 100
|
||||
})
|
||||
|
|
@ -194,13 +187,13 @@ export function FileExplorer() {
|
|||
|
||||
// Initial load
|
||||
useEffect(() => {
|
||||
if (vfs) {
|
||||
if (brain) {
|
||||
loadDirectory('/')
|
||||
}
|
||||
}, [vfs])
|
||||
}, [brain])
|
||||
|
||||
if (loading && !vfs) {
|
||||
return <div>Initializing VFS...</div>
|
||||
if (loading && !brain) {
|
||||
return <div>Initializing Brainy...</div>
|
||||
}
|
||||
|
||||
return (
|
||||
|
|
@ -301,16 +294,16 @@ npm install @soulcraft/brainy@latest # Update if needed
|
|||
|
||||
### "VFS not initialized" errors
|
||||
```typescript
|
||||
// Always await both init() calls
|
||||
// v5.1.0+: Just await brain.init() - VFS is auto-initialized!
|
||||
await brain.init()
|
||||
const vfs = brain.vfs()
|
||||
await vfs.init() // Don't forget this!
|
||||
// VFS ready - use brain.vfs directly
|
||||
await brain.vfs.writeFile('/test.txt', 'data')
|
||||
```
|
||||
|
||||
### Slow directory loading
|
||||
```typescript
|
||||
// Add pagination for large directories
|
||||
const children = await vfs.getDirectChildren(path, {
|
||||
const children = await brain.vfs.getDirectChildren(path, {
|
||||
limit: 100, // Load only first 100 items
|
||||
offset: 0 // Start from beginning
|
||||
})
|
||||
|
|
@ -319,7 +312,7 @@ const children = await vfs.getDirectChildren(path, {
|
|||
### Search not finding files
|
||||
```typescript
|
||||
// Make sure files are imported into VFS first
|
||||
await vfs.importDirectory('./my-files', {
|
||||
await brain.vfs.importDirectory('./my-files', {
|
||||
recursive: true,
|
||||
extractMetadata: true // Enable content understanding
|
||||
})
|
||||
|
|
|
|||
|
|
@ -1,69 +1,79 @@
|
|||
# VFS Initialization Guide
|
||||
# VFS Initialization Guide (v5.1.0+)
|
||||
|
||||
## Quick Start
|
||||
|
||||
The Brainy VFS requires proper initialization before use. Here's the correct pattern:
|
||||
The Brainy VFS is automatically initialized during `brain.init()`. No separate initialization needed!
|
||||
|
||||
```javascript
|
||||
import { Brainy } from '@soulcraft/brainy'
|
||||
|
||||
// Step 1: Create and initialize Brainy
|
||||
// Create and initialize Brainy
|
||||
const brain = new Brainy({
|
||||
storage: { type: 'filesystem', path: './data' }
|
||||
})
|
||||
await brain.init() // VFS is auto-initialized here!
|
||||
|
||||
// Use VFS immediately - it's a property, not a method!
|
||||
await brain.vfs.writeFile('/test.txt', 'Hello World')
|
||||
const files = await brain.vfs.readdir('/')
|
||||
```
|
||||
|
||||
## What Changed in v5.1.0?
|
||||
|
||||
### Before (v4.x and early v5.0.0):
|
||||
```javascript
|
||||
const brain = new Brainy(...)
|
||||
await brain.init()
|
||||
|
||||
// Step 2: Get VFS instance (it's a METHOD, not a property!)
|
||||
const vfs = brain.vfs() // ✅ Correct: method call with ()
|
||||
|
||||
// Step 3: Initialize VFS (THIS IS REQUIRED!)
|
||||
await vfs.init() // Creates the root directory
|
||||
|
||||
// Now you can use VFS
|
||||
await vfs.writeFile('/test.txt', 'Hello World')
|
||||
const files = await vfs.readdir('/')
|
||||
const vfs = brain.vfs() // ❌ Method call
|
||||
await vfs.init() // ❌ Separate initialization
|
||||
await vfs.writeFile(...)
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Mistake 1: Accessing VFS as Property
|
||||
### After (v5.1.0+):
|
||||
```javascript
|
||||
// WRONG - vfs is a method, not a property
|
||||
const vfs = brain.vfs // Missing parentheses!
|
||||
const brain = new Brainy(...)
|
||||
await brain.init() // VFS auto-initialized!
|
||||
|
||||
await brain.vfs.writeFile(...) // ✅ Property access, just works!
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Forgetting to Initialize VFS
|
||||
### Key Changes:
|
||||
1. **`vfs()` → `vfs`**: Method call becomes property access
|
||||
2. **Auto-initialization**: VFS initialized during `brain.init()`
|
||||
3. **Zero complexity**: No separate `vfs.init()` call needed
|
||||
4. **Consistent pattern**: VFS treated like any other brain API
|
||||
|
||||
## Migration from v4.x/v5.0.0
|
||||
|
||||
### Old Pattern (DEPRECATED):
|
||||
```javascript
|
||||
const vfs = brain.vfs()
|
||||
// Missing: await vfs.init()
|
||||
await vfs.writeFile('/test.txt', 'data') // Error: VFS not initialized
|
||||
await vfs.init()
|
||||
await vfs.writeFile('/test.txt', 'data')
|
||||
```
|
||||
|
||||
### ❌ Mistake 3: Not Waiting for Initialization
|
||||
### New Pattern (v5.1.0+):
|
||||
```javascript
|
||||
const vfs = brain.vfs()
|
||||
vfs.init() // Missing await!
|
||||
await vfs.readdir('/') // Error: VFS not initialized (init still running)
|
||||
// Just remove the () and init() call
|
||||
await brain.vfs.writeFile('/test.txt', 'data')
|
||||
```
|
||||
|
||||
## Why Initialization is Required
|
||||
## Why Auto-Initialization?
|
||||
|
||||
The VFS `init()` method performs critical setup:
|
||||
VFS stores files as entities and relationships in the same graph as everything else. There's no reason to treat it differently! Auto-initialization:
|
||||
|
||||
1. **Creates the root directory entity** in Brainy's graph database
|
||||
2. **Initializes the PathResolver** for efficient path lookups
|
||||
3. **Sets up caching layers** for performance
|
||||
4. **Starts background tasks** for maintenance
|
||||
5. **Configures storage adapters** based on your settings
|
||||
|
||||
Without initialization, the root directory (`/`) doesn't exist, which is why operations fail with "Not a directory: /" errors.
|
||||
- ✅ **Simpler API**: One less step to remember
|
||||
- ✅ **Fewer errors**: Can't forget to initialize
|
||||
- ✅ **More intuitive**: Property access feels natural
|
||||
- ✅ **Consistent**: Matches how other brain APIs work
|
||||
|
||||
## Complete Example
|
||||
|
||||
```javascript
|
||||
import { Brainy } from '@soulcraft/brainy'
|
||||
|
||||
async function setupVFS() {
|
||||
async function useVFS() {
|
||||
// Initialize Brainy
|
||||
const brain = new Brainy({
|
||||
storage: {
|
||||
|
|
@ -71,44 +81,22 @@ async function setupVFS() {
|
|||
path: './brainy-data'
|
||||
}
|
||||
})
|
||||
await brain.init()
|
||||
await brain.init() // VFS ready after this!
|
||||
|
||||
// Get and initialize VFS
|
||||
const vfs = brain.vfs()
|
||||
await vfs.init()
|
||||
// Use VFS immediately
|
||||
await brain.vfs.writeFile('/readme.txt', 'Welcome to VFS!')
|
||||
await brain.vfs.mkdir('/documents')
|
||||
|
||||
// Verify initialization
|
||||
const rootExists = await vfs.exists('/')
|
||||
console.log('Root directory exists:', rootExists) // true
|
||||
const files = await brain.vfs.readdir('/')
|
||||
console.log('Files in root:', files.map(f => f.name))
|
||||
|
||||
const stats = await vfs.stat('/')
|
||||
console.log('Root is directory:', stats.isDirectory()) // true
|
||||
|
||||
// Now use VFS normally
|
||||
await vfs.writeFile('/readme.txt', 'Welcome to VFS!')
|
||||
await vfs.mkdir('/documents')
|
||||
|
||||
const files = await vfs.readdir('/')
|
||||
console.log('Files in root:', files) // ['readme.txt', 'documents']
|
||||
|
||||
return vfs
|
||||
const content = await brain.vfs.readFile('/readme.txt')
|
||||
console.log('File content:', content.toString())
|
||||
}
|
||||
|
||||
setupVFS().catch(console.error)
|
||||
useVFS().catch(console.error)
|
||||
```
|
||||
|
||||
## Error Messages
|
||||
|
||||
If you see this error:
|
||||
```
|
||||
VFS not initialized. You must call await vfs.init() after getting the VFS instance.
|
||||
Example:
|
||||
const vfs = brain.vfs() // Note: vfs() is a method, not a property
|
||||
await vfs.init() // This creates the root directory
|
||||
```
|
||||
|
||||
It means you forgot to initialize VFS. Follow the example in the error message.
|
||||
|
||||
## TypeScript Usage
|
||||
|
||||
```typescript
|
||||
|
|
@ -116,87 +104,87 @@ import { Brainy, VirtualFileSystem } from '@soulcraft/brainy'
|
|||
|
||||
class FileManager {
|
||||
private brain: Brainy
|
||||
private vfs: VirtualFileSystem | null = null
|
||||
|
||||
async initialize(): Promise<void> {
|
||||
// Initialize Brainy
|
||||
this.brain = new Brainy({
|
||||
storage: { type: 'filesystem' }
|
||||
})
|
||||
await this.brain.init()
|
||||
|
||||
// Initialize VFS
|
||||
this.vfs = this.brain.vfs()
|
||||
await this.vfs.init()
|
||||
// VFS is ready! No separate initialization needed
|
||||
}
|
||||
|
||||
async writeFile(path: string, content: string): Promise<void> {
|
||||
if (!this.vfs) {
|
||||
if (!this.brain) {
|
||||
throw new Error('FileManager not initialized. Call initialize() first.')
|
||||
}
|
||||
await this.vfs.writeFile(path, content)
|
||||
// Use VFS as property
|
||||
await this.brain.vfs.writeFile(path, content)
|
||||
}
|
||||
|
||||
async listFiles(path: string): Promise<string[]> {
|
||||
const entries = await this.brain.vfs.readdir(path)
|
||||
return entries.map(e => e.name)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Auto-Initialization Pattern (Optional)
|
||||
## Error Messages
|
||||
|
||||
If you want VFS to auto-initialize on first use:
|
||||
If you see this error:
|
||||
```
|
||||
Brainy not initialized. Call init() first.
|
||||
```
|
||||
|
||||
It means you tried to use VFS before calling `brain.init()`. Always initialize Brainy first:
|
||||
|
||||
```javascript
|
||||
class AutoInitVFS {
|
||||
constructor(config) {
|
||||
this.brain = new Brainy(config)
|
||||
this.vfs = null
|
||||
this.initPromise = null
|
||||
}
|
||||
await brain.init() // Required!
|
||||
await brain.vfs.writeFile(...) // Now this works
|
||||
```
|
||||
|
||||
async ensureInit() {
|
||||
if (!this.initPromise) {
|
||||
this.initPromise = this._initialize()
|
||||
}
|
||||
await this.initPromise
|
||||
}
|
||||
## Fork Support (v5.0.0+)
|
||||
|
||||
async _initialize() {
|
||||
await this.brain.init()
|
||||
this.vfs = this.brain.vfs()
|
||||
await this.vfs.init()
|
||||
}
|
||||
VFS works seamlessly with Brainy's Copy-on-Write (COW) fork feature:
|
||||
|
||||
// Wrap all VFS methods
|
||||
async writeFile(path, data) {
|
||||
await this.ensureInit()
|
||||
return this.vfs.writeFile(path, data)
|
||||
}
|
||||
```javascript
|
||||
const brain = new Brainy({ storage: { type: 'memory' } })
|
||||
await brain.init()
|
||||
|
||||
async readdir(path) {
|
||||
await this.ensureInit()
|
||||
return this.vfs.readdir(path)
|
||||
}
|
||||
}
|
||||
// Create files in parent
|
||||
await brain.vfs.writeFile('/config.json', '{"version": 1}')
|
||||
|
||||
// Usage - no explicit init needed
|
||||
const vfs = new AutoInitVFS({ storage: { type: 'memory' } })
|
||||
await vfs.writeFile('/test.txt', 'Auto-init works!')
|
||||
// Fork inherits parent's files
|
||||
const fork = await brain.fork('experiment')
|
||||
const files = await fork.vfs.readdir('/') // Sees parent's config.json!
|
||||
|
||||
// Fork modifications are isolated
|
||||
await fork.vfs.writeFile('/test.txt', 'Fork only')
|
||||
await brain.vfs.readdir('/') // Parent doesn't see test.txt
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Why doesn't VFS auto-initialize?
|
||||
A: Explicit initialization gives you control over when the root directory is created and when background tasks start. This prevents unexpected side effects and makes the initialization cost visible.
|
||||
### Q: Do I need to call `vfs.init()` anymore?
|
||||
**A:** No! VFS is automatically initialized during `brain.init()` in v5.1.0+.
|
||||
|
||||
### Q: Can I reinitialize VFS?
|
||||
A: No, VFS can only be initialized once per instance. If you need to reset, create a new Brainy instance.
|
||||
### Q: Why did the API change from `vfs()` to `vfs`?
|
||||
**A:** VFS uses the same entity/relationship graph as everything else. There's no reason to treat it differently from other brain APIs.
|
||||
|
||||
### Q: What happens if Brainy isn't initialized?
|
||||
A: VFS initialization will fail. Always initialize Brainy first with `await brain.init()`.
|
||||
### Q: Will my old code break?
|
||||
**A:** If you're using `brain.vfs()` or `await vfs.init()`, you'll need to update to the new pattern. The migration is simple - just remove the `()` and `init()` calls.
|
||||
|
||||
### Q: Is the initialization pattern the same for all storage types?
|
||||
A: Yes, whether using memory, filesystem, S3, or R2 storage, the initialization pattern is identical.
|
||||
### Q: Can I still configure VFS?
|
||||
**A:** Yes, VFS configuration is passed through `brain.init()` config. The VFS-specific options are applied during auto-initialization.
|
||||
|
||||
### Q: Does this work with all storage adapters?
|
||||
**A:** Yes! VFS auto-initialization works with all storage adapters: Memory, FileSystem, OPFS, S3, R2, Azure Blob, and Google Cloud Storage.
|
||||
|
||||
### Q: What if I need multiple VFS instances?
|
||||
**A:** Each Brainy instance has its own VFS. Create multiple Brainy instances if you need multiple VFS instances.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [VFS Quick Start](./QUICK_START.md) - 5-minute setup guide
|
||||
- [VFS API Guide](./VFS_API_GUIDE.md) - Complete API reference
|
||||
- [Common Patterns](./COMMON_PATTERNS.md) - Best practices and patterns
|
||||
- [Common Patterns](./COMMON_PATTERNS.md) - Best practices and patterns
|
||||
- [Instant Fork](../features/instant-fork.md) - VFS + Copy-on-Write
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue