feat(docs): add comprehensive user guides and installation instructions for Brainy
This commit is contained in:
parent
8f6f657ba0
commit
24076c3eba
15 changed files with 1859 additions and 1 deletions
426
docs/examples/README.md
Normal file
426
docs/examples/README.md
Normal file
|
|
@ -0,0 +1,426 @@
|
|||
# Examples
|
||||
|
||||
Practical code examples and tutorials showing how to use Brainy in real-world applications.
|
||||
|
||||
## 🚀 Quick Examples
|
||||
|
||||
### Zero-Configuration Setup
|
||||
|
||||
```typescript
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
// Everything auto-configured!
|
||||
const brainy = createAutoBrainy()
|
||||
|
||||
// Add and search in 3 lines
|
||||
await brainy.addText('1', 'Machine learning is fascinating')
|
||||
await brainy.addText('2', 'Deep learning models are powerful')
|
||||
const results = await brainy.searchText('AI technology', 5)
|
||||
```
|
||||
|
||||
## 📚 Example Categories
|
||||
|
||||
### 🎯 [Basic Usage](basic-usage.md)
|
||||
Simple examples to get you started.
|
||||
|
||||
- First vector database
|
||||
- Adding and searching data
|
||||
- Text-based semantic search
|
||||
- Basic configuration
|
||||
|
||||
### 🏗️ [Advanced Patterns](advanced-patterns.md)
|
||||
Complex use cases and integration patterns.
|
||||
|
||||
- Batch operations and optimization
|
||||
- Custom embedding functions
|
||||
- Advanced search patterns
|
||||
- Performance monitoring
|
||||
|
||||
### 🔌 [Integrations](integrations.md)
|
||||
Third-party service integrations.
|
||||
|
||||
- Express.js API server
|
||||
- Next.js applications
|
||||
- AWS Lambda functions
|
||||
- Docker deployments
|
||||
|
||||
### ⚡ [Performance Examples](performance.md)
|
||||
Optimization and scaling examples.
|
||||
|
||||
- Large dataset handling
|
||||
- Memory optimization
|
||||
- S3 storage strategies
|
||||
- Performance benchmarking
|
||||
|
||||
### 🌐 [Real-World Applications](real-world.md)
|
||||
Complete application examples.
|
||||
|
||||
- Document search system
|
||||
- Recommendation engine
|
||||
- Knowledge base
|
||||
- Chatbot with semantic search
|
||||
|
||||
## 🎯 Use Case Examples
|
||||
|
||||
### Document Search System
|
||||
|
||||
```typescript
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
class DocumentSearchSystem {
|
||||
private brainy = createAutoBrainy({ bucketName: 'documents' })
|
||||
|
||||
async addDocument(id: string, title: string, content: string) {
|
||||
await this.brainy.addText(id, `${title} ${content}`, {
|
||||
title,
|
||||
content,
|
||||
addedAt: new Date().toISOString()
|
||||
})
|
||||
}
|
||||
|
||||
async searchDocuments(query: string, limit = 10) {
|
||||
return this.brainy.searchText(query, limit)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Recommendation Engine
|
||||
|
||||
```typescript
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
class RecommendationEngine {
|
||||
private brainy = createQuickBrainy('medium', { bucketName: 'recommendations' })
|
||||
|
||||
async addUserPreferences(userId: string, preferences: number[]) {
|
||||
await this.brainy.addVector({
|
||||
id: userId,
|
||||
vector: preferences,
|
||||
metadata: { type: 'user', lastUpdated: Date.now() }
|
||||
})
|
||||
}
|
||||
|
||||
async getRecommendations(userId: string) {
|
||||
const user = await this.brainy.get(userId)
|
||||
if (!user) return []
|
||||
|
||||
const similar = await this.brainy.search(user.vector, 10)
|
||||
return similar.filter(([id]) => id !== userId)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### API Server
|
||||
|
||||
```typescript
|
||||
import express from 'express'
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
const app = express()
|
||||
const brainy = createAutoBrainy({
|
||||
bucketName: process.env.S3_BUCKET_NAME
|
||||
})
|
||||
|
||||
app.use(express.json())
|
||||
|
||||
// Add vector endpoint
|
||||
app.post('/vectors', async (req, res) => {
|
||||
try {
|
||||
const { id, vector, metadata } = req.body
|
||||
await brainy.addVector({ id, vector, metadata })
|
||||
res.json({ success: true, id })
|
||||
} catch (error) {
|
||||
res.status(400).json({ error: error.message })
|
||||
}
|
||||
})
|
||||
|
||||
// Search endpoint
|
||||
app.get('/search', async (req, res) => {
|
||||
try {
|
||||
const { query, limit = 10 } = req.query
|
||||
const results = await brainy.searchText(query, parseInt(limit))
|
||||
res.json({ results })
|
||||
} catch (error) {
|
||||
res.status(400).json({ error: error.message })
|
||||
}
|
||||
})
|
||||
|
||||
// Performance metrics endpoint
|
||||
app.get('/metrics', async (req, res) => {
|
||||
const metrics = brainy.getPerformanceMetrics()
|
||||
res.json(metrics)
|
||||
})
|
||||
|
||||
app.listen(3000, () => {
|
||||
console.log('Vector search API running on port 3000')
|
||||
})
|
||||
```
|
||||
|
||||
## 🛠️ Framework Integration Examples
|
||||
|
||||
### Next.js Application
|
||||
|
||||
```typescript
|
||||
// pages/api/search.ts
|
||||
import { NextApiRequest, NextApiResponse } from 'next'
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
let brainy: any = null
|
||||
|
||||
async function getBrainy() {
|
||||
if (!brainy) {
|
||||
brainy = createAutoBrainy({
|
||||
bucketName: process.env.S3_BUCKET_NAME
|
||||
})
|
||||
}
|
||||
return brainy
|
||||
}
|
||||
|
||||
export default async function handler(
|
||||
req: NextApiRequest,
|
||||
res: NextApiResponse
|
||||
) {
|
||||
if (req.method === 'POST') {
|
||||
const { query } = req.body
|
||||
const brainy = await getBrainy()
|
||||
const results = await brainy.searchText(query, 10)
|
||||
res.json({ results })
|
||||
} else {
|
||||
res.setHeader('Allow', ['POST'])
|
||||
res.status(405).end(`Method ${req.method} Not Allowed`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### AWS Lambda Function
|
||||
|
||||
```typescript
|
||||
import { APIGatewayProxyHandler } from 'aws-lambda'
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
// Initialize outside handler for connection reuse
|
||||
const brainy = createAutoBrainy({
|
||||
bucketName: process.env.S3_BUCKET_NAME
|
||||
})
|
||||
|
||||
export const search: APIGatewayProxyHandler = async (event) => {
|
||||
try {
|
||||
const { query, limit = 10 } = JSON.parse(event.body || '{}')
|
||||
|
||||
const results = await brainy.searchText(query, limit)
|
||||
|
||||
return {
|
||||
statusCode: 200,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Access-Control-Allow-Origin': '*'
|
||||
},
|
||||
body: JSON.stringify({ results })
|
||||
}
|
||||
} catch (error) {
|
||||
return {
|
||||
statusCode: 500,
|
||||
body: JSON.stringify({ error: error.message })
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### React Hook
|
||||
|
||||
```typescript
|
||||
import { useState, useEffect } from 'react'
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
// Custom hook for vector search
|
||||
export function useVectorSearch() {
|
||||
const [brainy, setBrainy] = useState(null)
|
||||
const [loading, setLoading] = useState(true)
|
||||
|
||||
useEffect(() => {
|
||||
async function initBrainy() {
|
||||
const instance = createAutoBrainy()
|
||||
setBrainy(instance)
|
||||
setLoading(false)
|
||||
}
|
||||
initBrainy()
|
||||
}, [])
|
||||
|
||||
const search = async (query: string, limit = 10) => {
|
||||
if (!brainy) return []
|
||||
return brainy.searchText(query, limit)
|
||||
}
|
||||
|
||||
const addText = async (id: string, text: string) => {
|
||||
if (!brainy) return
|
||||
return brainy.addText(id, text)
|
||||
}
|
||||
|
||||
return { search, addText, loading, brainy }
|
||||
}
|
||||
|
||||
// Usage in component
|
||||
function SearchComponent() {
|
||||
const { search, addText, loading } = useVectorSearch()
|
||||
const [results, setResults] = useState([])
|
||||
|
||||
if (loading) return <div>Loading...</div>
|
||||
|
||||
const handleSearch = async (query: string) => {
|
||||
const searchResults = await search(query)
|
||||
setResults(searchResults)
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<input
|
||||
type="text"
|
||||
onChange={(e) => handleSearch(e.target.value)}
|
||||
placeholder="Search..."
|
||||
/>
|
||||
<ul>
|
||||
{results.map(([id, score]) => (
|
||||
<li key={id}>ID: {id}, Score: {score}</li>
|
||||
))}
|
||||
</ul>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## 🎮 Interactive Examples
|
||||
|
||||
### Browser Console Examples
|
||||
|
||||
Open browser dev tools and try these:
|
||||
|
||||
```javascript
|
||||
// Import Brainy in browser
|
||||
import('https://unpkg.com/@soulcraft/brainy').then(async ({ createAutoBrainy }) => {
|
||||
const brainy = createAutoBrainy()
|
||||
|
||||
// Add some test data
|
||||
await brainy.addText('1', 'JavaScript is a programming language')
|
||||
await brainy.addText('2', 'Python is great for data science')
|
||||
await brainy.addText('3', 'Machine learning uses algorithms')
|
||||
|
||||
// Search semantically
|
||||
const results = await brainy.searchText('coding languages', 2)
|
||||
console.log('Search results:', results)
|
||||
})
|
||||
```
|
||||
|
||||
### Node.js REPL Examples
|
||||
|
||||
```bash
|
||||
npm install @soulcraft/brainy
|
||||
node
|
||||
```
|
||||
|
||||
```javascript
|
||||
const { createAutoBrainy } = require('@soulcraft/brainy')
|
||||
|
||||
const brainy = createAutoBrainy()
|
||||
|
||||
// Add vectors
|
||||
brainy.addVector({ id: '1', vector: [0.1, 0.2, 0.3] })
|
||||
brainy.addVector({ id: '2', vector: [0.4, 0.5, 0.6] })
|
||||
|
||||
// Search
|
||||
brainy.search([0.1, 0.2, 0.3], 5).then(console.log)
|
||||
```
|
||||
|
||||
## 📊 Performance Examples
|
||||
|
||||
### Benchmarking
|
||||
|
||||
```typescript
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
async function benchmarkSearch() {
|
||||
const brainy = createAutoBrainy()
|
||||
|
||||
// Add test data
|
||||
console.log('Adding 10,000 vectors...')
|
||||
const addStart = Date.now()
|
||||
|
||||
for (let i = 0; i < 10000; i++) {
|
||||
await brainy.addVector({
|
||||
id: `vector-${i}`,
|
||||
vector: Array.from({ length: 512 }, () => Math.random())
|
||||
})
|
||||
}
|
||||
|
||||
const addTime = Date.now() - addStart
|
||||
console.log(`Added 10k vectors in ${addTime}ms`)
|
||||
|
||||
// Benchmark search
|
||||
console.log('Running search benchmark...')
|
||||
const searchStart = Date.now()
|
||||
|
||||
for (let i = 0; i < 100; i++) {
|
||||
const query = Array.from({ length: 512 }, () => Math.random())
|
||||
await brainy.search(query, 10)
|
||||
}
|
||||
|
||||
const searchTime = Date.now() - searchStart
|
||||
console.log(`100 searches completed in ${searchTime}ms`)
|
||||
console.log(`Average search time: ${searchTime / 100}ms`)
|
||||
|
||||
// Get performance metrics
|
||||
const metrics = brainy.getPerformanceMetrics()
|
||||
console.log('Performance metrics:', metrics)
|
||||
}
|
||||
|
||||
benchmarkSearch()
|
||||
```
|
||||
|
||||
### Memory Monitoring
|
||||
|
||||
```typescript
|
||||
import { createAutoBrainy } from '@soulcraft/brainy'
|
||||
|
||||
const brainy = createAutoBrainy()
|
||||
|
||||
// Monitor memory usage
|
||||
setInterval(() => {
|
||||
const metrics = brainy.getPerformanceMetrics()
|
||||
const memoryMB = metrics.memoryUsage / 1024 / 1024
|
||||
|
||||
console.log(`Memory usage: ${memoryMB.toFixed(1)}MB`)
|
||||
console.log(`Cache hit rate: ${(metrics.cacheHitRate * 100).toFixed(1)}%`)
|
||||
console.log(`Average search time: ${metrics.averageSearchTime.toFixed(1)}ms`)
|
||||
}, 10000) // Every 10 seconds
|
||||
```
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
- **[Getting Started](../getting-started/)** - Basic setup and first steps
|
||||
- **[User Guides](../user-guides/)** - Feature-specific documentation
|
||||
- **[API Reference](../api-reference/)** - Complete API documentation
|
||||
- **[Optimization Guides](../optimization-guides/)** - Performance tuning
|
||||
|
||||
## 🎯 Example Request Guidelines
|
||||
|
||||
**Need a specific example?** Open a [GitHub Issue](https://github.com/soulcraft-research/brainy/issues) with:
|
||||
|
||||
1. **Use Case**: What you're trying to build
|
||||
2. **Environment**: Browser, Node.js, serverless, etc.
|
||||
3. **Scale**: Expected dataset size and performance requirements
|
||||
4. **Integration**: Frameworks or services you're using
|
||||
|
||||
We'll create examples based on community needs!
|
||||
|
||||
## 💡 Contributing Examples
|
||||
|
||||
Have a great Brainy example? We'd love to include it!
|
||||
|
||||
1. Fork the repository
|
||||
2. Add your example to the appropriate section
|
||||
3. Include clear comments and documentation
|
||||
4. Test your example thoroughly
|
||||
5. Submit a pull request
|
||||
|
||||
---
|
||||
|
||||
**Ready to build something amazing with Brainy?** Start with the [Basic Usage](basic-usage.md) examples! 🚀
|
||||
Loading…
Add table
Add a link
Reference in a new issue