CHECKPOINT: Brainy 2.0 API refactor - pre-fixes state
Current state: - Unified augmentation system to BrainyAugmentation interface - Changed methods to specific noun/verb naming (addNoun, getNoun, etc) - Made old methods private - Combined getNouns into single unified method - Neural API exists and is complete - Triple Intelligence uses correct Brainy operators (not MongoDB) Issues identified: - Documentation incorrectly shows MongoDB operators (code is correct) - Need to ensure all features are properly exposed - Need to verify nothing was lost in simplification This commit serves as a rollback point before applying fixes.
This commit is contained in:
commit
26c7d61185
279 changed files with 177945 additions and 0 deletions
206
docs/augmentations/README.md
Normal file
206
docs/augmentations/README.md
Normal file
|
|
@ -0,0 +1,206 @@
|
|||
# Brainy Augmentations
|
||||
|
||||
Augmentations are the core extensibility mechanism in Brainy. They allow you to modify, enhance, and extend Brainy's behavior without changing the core code.
|
||||
|
||||
## Core Principle: One Interface, Infinite Possibilities
|
||||
|
||||
Every augmentation implements the same simple `BrainyAugmentation` interface:
|
||||
|
||||
```typescript
|
||||
interface BrainyAugmentation {
|
||||
name: string
|
||||
timing: 'before' | 'after' | 'around' | 'replace'
|
||||
operations: string[]
|
||||
priority: number
|
||||
initialize(context): Promise<void>
|
||||
execute(operation, params, next): Promise<any>
|
||||
}
|
||||
```
|
||||
|
||||
This single interface can handle EVERYTHING - from adding AI capabilities to exposing APIs to replacing storage backends.
|
||||
|
||||
## Available Augmentations
|
||||
|
||||
### 🧠 Data Processing
|
||||
Augmentations that enhance how data is processed and stored.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **NeuralImportAugmentation** | AI-powered entity and relationship extraction | `before` | ✅ Production |
|
||||
| **EntityRegistryAugmentation** | High-performance entity deduplication | `before` | ✅ Production |
|
||||
| **BatchProcessingAugmentation** | Optimizes bulk operations | `around` | ✅ Production |
|
||||
| **IntelligentVerbScoringAugmentation** | Learns relationship importance over time | `after` | ✅ Production |
|
||||
|
||||
### 🔌 External Connections (Synapses)
|
||||
Connect Brainy to external services and data sources.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **NotionSynapse** | Sync with Notion databases | `after` | 📝 Example |
|
||||
| **SalesforceSynapse** | Connect to Salesforce CRM | `after` | 📝 Example |
|
||||
| **SlackSynapse** | Import Slack conversations | `after` | 📝 Example |
|
||||
| **GoogleDriveSynapse** | Sync Google Drive documents | `after` | 📝 Example |
|
||||
|
||||
### 🌐 API Exposure
|
||||
Expose Brainy through various protocols.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **APIServerAugmentation** | REST, WebSocket, and MCP server | `after` | ✅ Production |
|
||||
| **GraphQLAugmentation** | GraphQL API endpoint | `after` | 🚧 Planned |
|
||||
| **gRPCAugmentation** | gRPC service | `after` | 🚧 Planned |
|
||||
|
||||
### 💾 Storage Backends
|
||||
Replace or enhance the storage layer.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **WALAugmentation** | Write-ahead logging for durability | `around` | ✅ Production |
|
||||
| **S3StorageAugmentation** | Use S3 as storage backend | `replace` | 📝 Example |
|
||||
| **RedisAugmentation** | Redis caching layer | `around` | 📝 Example |
|
||||
| **PostgresAugmentation** | PostgreSQL persistence | `replace` | 📝 Example |
|
||||
|
||||
### 🔄 Real-time & Sync
|
||||
Handle real-time updates and synchronization.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **WebSocketConduitAugmentation** | WebSocket client connections | `after` | ⚠️ Legacy |
|
||||
| **ServerSearchAugmentation** | Connect to remote Brainy servers | `after` | ⚠️ Legacy |
|
||||
| **TeamCoordinationAugmentation** | Multi-agent synchronization | `after` | 📝 Example |
|
||||
|
||||
### 🛡️ Infrastructure
|
||||
Core infrastructure and reliability features.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **ConnectionPoolAugmentation** | Optimize cloud storage connections | `before` | ✅ Production |
|
||||
| **RequestDeduplicatorAugmentation** | Prevent duplicate concurrent requests | `before` | ✅ Production |
|
||||
| **TransactionAugmentation** | ACID transaction support | `around` | 🚧 Planned |
|
||||
| **CacheAugmentation** | Multi-level caching | `around` | ✅ Production |
|
||||
|
||||
### 📊 Monitoring & Analytics
|
||||
Track and analyze Brainy's behavior.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **MetricsAugmentation** | Prometheus metrics | `after` | 📝 Example |
|
||||
| **LoggingAugmentation** | Structured logging | `after` | 📝 Example |
|
||||
| **TracingAugmentation** | Distributed tracing | `around` | 🚧 Planned |
|
||||
|
||||
### 🤖 AI & Chat
|
||||
AI-powered interfaces and chat capabilities.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **ChatInterfaceAugmentation** | Natural language interface | `before` | 📝 Example |
|
||||
| **MCPAgentMemoryAugmentation** | AI agent memory via MCP | `after` | 📝 Example |
|
||||
| **LLMQueryAugmentation** | LLM-enhanced queries | `before` | 📝 Example |
|
||||
|
||||
### 📈 Visualization
|
||||
Visual representations of data.
|
||||
|
||||
| Augmentation | Description | Timing | Status |
|
||||
|-------------|-------------|--------|--------|
|
||||
| **GraphVisualizationAugmentation** | Real-time graph visualization | `after` | 📝 Example |
|
||||
| **DashboardAugmentation** | Web-based dashboard | `after` | 🚧 Planned |
|
||||
|
||||
## Status Legend
|
||||
|
||||
- ✅ **Production**: Fully implemented and tested
|
||||
- 📝 **Example**: Example implementation available
|
||||
- 🚧 **Planned**: On the roadmap
|
||||
- ⚠️ **Legacy**: Being replaced by newer augmentations
|
||||
|
||||
## Using Augmentations
|
||||
|
||||
### Zero-Config Approach
|
||||
|
||||
```typescript
|
||||
const brain = new BrainyData()
|
||||
|
||||
// Just register augmentations - they work automatically!
|
||||
brain.augmentations.register(new WALAugmentation())
|
||||
brain.augmentations.register(new EntityRegistryAugmentation())
|
||||
brain.augmentations.register(new APIServerAugmentation())
|
||||
|
||||
await brain.init()
|
||||
```
|
||||
|
||||
### With Configuration
|
||||
|
||||
```typescript
|
||||
const brain = new BrainyData()
|
||||
|
||||
brain.augmentations.register(
|
||||
new APIServerAugmentation({
|
||||
port: 8080,
|
||||
auth: { required: true }
|
||||
})
|
||||
)
|
||||
|
||||
await brain.init()
|
||||
```
|
||||
|
||||
## Creating Custom Augmentations
|
||||
|
||||
See [Creating Custom Augmentations](./creating-augmentations.md) for a complete guide.
|
||||
|
||||
Quick example:
|
||||
|
||||
```typescript
|
||||
class MyAugmentation extends BaseAugmentation {
|
||||
readonly name = 'my-augmentation'
|
||||
readonly timing = 'after'
|
||||
readonly operations = ['add', 'search']
|
||||
readonly priority = 50
|
||||
|
||||
async execute<T>(operation: string, params: any, next: () => Promise<T>): Promise<T> {
|
||||
console.log(`Before ${operation}`)
|
||||
const result = await next()
|
||||
console.log(`After ${operation}`)
|
||||
return result
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Augmentation Timing
|
||||
|
||||
### `before`
|
||||
Executes before the main operation. Used for:
|
||||
- Input validation
|
||||
- Data transformation
|
||||
- Authentication checks
|
||||
|
||||
### `after`
|
||||
Executes after the main operation. Used for:
|
||||
- Broadcasting updates
|
||||
- Syncing to external services
|
||||
- Logging and metrics
|
||||
|
||||
### `around`
|
||||
Wraps the main operation. Used for:
|
||||
- Transactions
|
||||
- Caching
|
||||
- Error handling
|
||||
|
||||
### `replace`
|
||||
Completely replaces the main operation. Used for:
|
||||
- Alternative storage backends
|
||||
- Mock implementations
|
||||
- Proxy operations
|
||||
|
||||
## Priority System
|
||||
|
||||
Higher numbers execute first:
|
||||
- **100**: Critical system operations
|
||||
- **50**: Performance optimizations
|
||||
- **10**: Enhancement features
|
||||
- **1**: Optional features
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [API Server Augmentation](./api-server.md) - Complete API server documentation
|
||||
- [Creating Augmentations](./creating-augmentations.md) - How to build your own
|
||||
- [Augmentation Examples](../AUGMENTATION-EXAMPLES.md) - Real-world examples
|
||||
- [Architecture Overview](../COMPLETE-ARCHITECTURE-VISION.md) - System architecture
|
||||
Loading…
Add table
Add a link
Reference in a new issue