feat: add zero-configuration Brainy service template with augmentation-first architecture
- Implement WebSocket augmentation for real-time communication - Implement WebRTC augmentation for peer-to-peer connections - Implement HTTP augmentation as minimal REST fallback - Add auto-discovery augmentation for data pattern analysis - Add adaptive storage augmentation for intelligent resource management - Add environment adapter augmentation for universal compatibility - Template auto-detects environment (browser, Node.js, serverless, containers) - Intelligent transport selection (WebRTC → WebSocket → HTTP) - Automatic storage optimization (memory → filesystem → S3) - Zero configuration required - just npm start - Includes intelligent verb scoring by default - Works in any environment without configuration - Full documentation and examples included
This commit is contained in:
parent
c38c8de10a
commit
768acf66ad
30 changed files with 3548 additions and 0 deletions
407
examples/brainy-service-template/README.md
Normal file
407
examples/brainy-service-template/README.md
Normal file
|
|
@ -0,0 +1,407 @@
|
|||
# Brainy Service Template
|
||||
|
||||
**Zero-configuration, intelligent service template built with Brainy's native augmentation system.**
|
||||
|
||||
This template embodies Brainy's core tenets: **zero configuration**, **intelligent adaptation**, and **augmentation-first architecture**. It automatically adapts to any environment (browser, Node.js, serverless, containers) and uses WebRTC, WebSocket, and HTTP transport layers as needed.
|
||||
|
||||
## Features
|
||||
|
||||
🧠 **Zero Configuration**
|
||||
- Auto-detects optimal storage (memory → filesystem → S3)
|
||||
- Intelligent transport selection (WebRTC → WebSocket → HTTP)
|
||||
- Environment adaptation (browser, Node.js, serverless, containers)
|
||||
- Self-optimizing performance and caching
|
||||
|
||||
🔌 **Augmentation-First Architecture**
|
||||
- WebSocket Augmentation - Real-time queries and updates
|
||||
- WebRTC Augmentation - Peer-to-peer Brainy connections
|
||||
- HTTP Augmentation - Minimal REST API for universal access
|
||||
- Auto-Discovery Augmentation - Understand your data patterns
|
||||
- Adaptive Storage Augmentation - Intelligent resource management
|
||||
- Environment Adapter - Works everywhere automatically
|
||||
|
||||
🌐 **Universal Compatibility**
|
||||
- Browser (OPFS, IndexedDB, WebRTC peer-to-peer)
|
||||
- Node.js (filesystem, worker threads, clustering)
|
||||
- Serverless (memory, fast cold starts)
|
||||
- Docker/Containers (volumes, health checks)
|
||||
- Kubernetes (pod-aware, service mesh ready)
|
||||
- Edge computing (ultra-low latency, minimal footprint)
|
||||
|
||||
⚡ **Intelligent Features**
|
||||
- Intelligent Verb Scoring (enabled by default)
|
||||
- Automatic relationship weighting and confidence scoring
|
||||
- Learning from usage patterns and feedback
|
||||
- Real-time performance optimization
|
||||
- Data quality analysis and recommendations
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Zero-Config Instant Start
|
||||
|
||||
```bash
|
||||
# Copy template
|
||||
cp -r examples/brainy-service-template my-brainy-service
|
||||
cd my-brainy-service
|
||||
npm install
|
||||
|
||||
# Start with ZERO configuration - everything auto-detected!
|
||||
npm start
|
||||
```
|
||||
|
||||
**That's it!** The service automatically:
|
||||
- ✅ Detects your environment (Node.js, browser, container, etc.)
|
||||
- ✅ Chooses optimal storage (memory → filesystem → S3)
|
||||
- ✅ Enables best transport layers (WebRTC → WebSocket → HTTP)
|
||||
- ✅ Configures intelligent verb scoring
|
||||
- ✅ Sets up real-time capabilities
|
||||
- ✅ Optimizes performance for your hardware
|
||||
|
||||
### 2. Access Your Brainy Service
|
||||
|
||||
The service automatically provides multiple ways to interact:
|
||||
|
||||
```javascript
|
||||
// WebSocket (real-time, best performance)
|
||||
const ws = new WebSocket('ws://localhost:3001')
|
||||
ws.send(JSON.stringify({
|
||||
type: 'search',
|
||||
payload: { query: 'machine learning', limit: 10 }
|
||||
}))
|
||||
|
||||
// WebRTC (peer-to-peer, direct connection)
|
||||
// Client code automatically generated at http://localhost:3002
|
||||
|
||||
// HTTP (universal fallback)
|
||||
curl -X POST http://localhost:3000/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"query": "machine learning", "limit": 10}'
|
||||
```
|
||||
|
||||
### 3. Optional: Environment Variables
|
||||
|
||||
Only set these if you want to override the intelligent defaults:
|
||||
|
||||
```bash
|
||||
# Storage preference (auto-detected by default)
|
||||
export BRAINY_STORAGE_TYPE=s3
|
||||
export BRAINY_S3_BUCKET=my-brainy-data
|
||||
|
||||
# Transport preference (all enabled by default)
|
||||
export BRAINY_TRANSPORTS=websocket,http # disable WebRTC
|
||||
|
||||
# Port preference (3000 by default)
|
||||
export PORT=8080
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Entities
|
||||
- `POST /api/entities` - Create entity
|
||||
- `GET /api/entities/:id` - Get entity by ID
|
||||
- `PUT /api/entities/:id` - Update entity
|
||||
- `DELETE /api/entities/:id` - Delete entity
|
||||
- `GET /api/entities` - List entities (paginated)
|
||||
- `POST /api/entities/search` - Search entities
|
||||
|
||||
### Relationships
|
||||
- `POST /api/relationships` - Create relationship
|
||||
- `GET /api/relationships/:id` - Get relationship by ID
|
||||
- `PUT /api/relationships/:id` - Update relationship
|
||||
- `DELETE /api/relationships/:id` - Delete relationship
|
||||
- `GET /api/relationships` - List relationships (paginated)
|
||||
|
||||
### Intelligent Scoring (when enabled)
|
||||
- `POST /api/scoring/feedback/:id` - Provide feedback for learning
|
||||
- `GET /api/scoring/stats` - Get scoring statistics
|
||||
- `POST /api/scoring/export` - Export learning data
|
||||
- `POST /api/scoring/import` - Import learning data
|
||||
- `DELETE /api/scoring/stats` - Clear statistics
|
||||
- `POST /api/scoring/analyze` - Analyze relationship patterns
|
||||
- `GET /api/scoring/recommendations/:entityId` - Get recommendations
|
||||
|
||||
### Health & Monitoring
|
||||
- `GET /health` - Overall health check
|
||||
- `GET /health/liveness` - Kubernetes liveness probe
|
||||
- `GET /health/readiness` - Kubernetes readiness probe
|
||||
- `GET /health/metrics` - System metrics
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"service": {
|
||||
"name": "my-service",
|
||||
"port": 3000,
|
||||
"cors": {
|
||||
"enabled": true,
|
||||
"origins": ["http://localhost:3000"]
|
||||
}
|
||||
},
|
||||
"brainy": {
|
||||
"storage": {
|
||||
"type": "filesystem|memory|s3",
|
||||
"path": "./data",
|
||||
"s3": {
|
||||
"bucket": "my-bucket",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Features
|
||||
|
||||
```json
|
||||
{
|
||||
"brainy": {
|
||||
"features": {
|
||||
"intelligentVerbScoring": true,
|
||||
"realTimeUpdates": true,
|
||||
"distributedMode": false
|
||||
},
|
||||
"intelligentVerbScoring": {
|
||||
"enabled": true,
|
||||
"enableSemanticScoring": true,
|
||||
"enableFrequencyAmplification": true,
|
||||
"enableTemporalDecay": true,
|
||||
"temporalDecayRate": 0.01,
|
||||
"minWeight": 0.1,
|
||||
"maxWeight": 1.0,
|
||||
"baseConfidence": 0.5,
|
||||
"learningRate": 0.1
|
||||
},
|
||||
"cache": {
|
||||
"autoTune": true,
|
||||
"hotCacheMaxSize": 10000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Production (Local)
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker build -t my-brainy-service .
|
||||
docker run -p 3000:3000 my-brainy-service
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `NODE_ENV` | Environment | `development` |
|
||||
| `PORT` | Server port | `3000` |
|
||||
| `BRAINY_STORAGE_TYPE` | Storage type | `filesystem` |
|
||||
| `BRAINY_STORAGE_PATH` | Storage path | `./data` |
|
||||
| `BRAINY_INTELLIGENT_SCORING` | Enable scoring | `false` |
|
||||
| `LOG_LEVEL` | Logging level | `info` |
|
||||
|
||||
## Examples
|
||||
|
||||
### Adding Entities with Smart Relationships
|
||||
|
||||
```javascript
|
||||
// Add entities
|
||||
const person = await fetch('/entities', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
data: 'John is a senior software developer with expertise in React and Node.js',
|
||||
metadata: { type: 'person', name: 'John' }
|
||||
})
|
||||
})
|
||||
|
||||
const project = await fetch('/entities', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
data: 'E-commerce platform built with React and Node.js',
|
||||
metadata: { type: 'project', name: 'ShopApp' }
|
||||
})
|
||||
})
|
||||
|
||||
// Add relationship (with intelligent scoring if enabled)
|
||||
const relationship = await fetch('/relationships', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
sourceId: person.id,
|
||||
targetId: project.id,
|
||||
type: 'contributesTo',
|
||||
// weight is automatically computed if intelligent scoring is enabled
|
||||
metadata: { role: 'lead developer' }
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Providing Learning Feedback
|
||||
|
||||
```javascript
|
||||
// Correct a relationship weight (helps the system learn)
|
||||
await fetch(`/relationships/${relationshipId}/feedback`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
weight: 0.9, // corrected weight
|
||||
confidence: 0.85, // corrected confidence
|
||||
type: 'correction'
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Semantic Search
|
||||
|
||||
```javascript
|
||||
const results = await fetch('/entities/search', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
query: 'experienced React developer',
|
||||
limit: 10,
|
||||
threshold: 0.7
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
brainy-service-template/
|
||||
├── src/
|
||||
│ ├── controllers/
|
||||
│ │ ├── entities.js
|
||||
│ │ ├── relationships.js
|
||||
│ │ └── scoring.js
|
||||
│ ├── middleware/
|
||||
│ │ ├── auth.js
|
||||
│ │ ├── validation.js
|
||||
│ │ └── errorHandler.js
|
||||
│ ├── services/
|
||||
│ │ ├── brainyService.js
|
||||
│ │ └── scoringService.js
|
||||
│ ├── utils/
|
||||
│ │ ├── config.js
|
||||
│ │ ├── logger.js
|
||||
│ │ └── helpers.js
|
||||
│ └── app.js
|
||||
├── config/
|
||||
│ ├── default.json
|
||||
│ ├── development.json
|
||||
│ └── production.json
|
||||
├── docker/
|
||||
│ ├── Dockerfile
|
||||
│ └── docker-compose.yml
|
||||
├── tests/
|
||||
│ ├── integration/
|
||||
│ └── unit/
|
||||
└── docs/
|
||||
└── api.md
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
npm test
|
||||
|
||||
# Run with coverage
|
||||
npm run test:coverage
|
||||
|
||||
# Run integration tests
|
||||
npm run test:integration
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding Custom Endpoints
|
||||
|
||||
```javascript
|
||||
// src/controllers/custom.js
|
||||
export const customEndpoint = async (req, res) => {
|
||||
const { brainyService } = req.app.locals
|
||||
|
||||
// Your custom logic using Brainy
|
||||
const results = await brainyService.search(req.body.query)
|
||||
|
||||
res.json({ results })
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Augmentations
|
||||
|
||||
```javascript
|
||||
// src/services/customAugmentation.js
|
||||
import { ICognitionAugmentation } from '@soulcraft/brainy'
|
||||
|
||||
export class CustomAugmentation implements ICognitionAugmentation {
|
||||
// Your custom augmentation logic
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
The template includes built-in monitoring:
|
||||
|
||||
- **Health checks**: `/health` endpoint
|
||||
- **Metrics**: Request counts, response times, error rates
|
||||
- **Logging**: Structured JSON logging with correlation IDs
|
||||
- **Performance**: Automatic performance tracking for Brainy operations
|
||||
|
||||
## Production Considerations
|
||||
|
||||
### Security
|
||||
|
||||
- Input validation and sanitization
|
||||
- Rate limiting
|
||||
- CORS configuration
|
||||
- Environment-based secrets management
|
||||
|
||||
### Performance
|
||||
|
||||
- Connection pooling
|
||||
- Request caching
|
||||
- Automatic cache tuning
|
||||
- Background processing for heavy operations
|
||||
|
||||
### Reliability
|
||||
|
||||
- Graceful shutdown handling
|
||||
- Circuit breaker patterns
|
||||
- Retry logic with exponential backoff
|
||||
- Health checks for dependencies
|
||||
|
||||
## Support & Documentation
|
||||
|
||||
- [Brainy Documentation](../../docs/)
|
||||
- [Intelligent Verb Scoring Guide](../../docs/guides/intelligent-verb-scoring.md)
|
||||
- [API Reference](./docs/api.md)
|
||||
- [Configuration Examples](./config/)
|
||||
|
||||
## License
|
||||
|
||||
This template is provided under the same license as Brainy.
|
||||
Loading…
Add table
Add a link
Reference in a new issue