soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

ORGANIZE: Move documentation to proper directories

Browse source 
- Moved API design docs to docs/api-design/
- Moved planning docs to docs/planning/
- Root now only contains standard repo files (README, LICENSE, etc.)
- Keeps CLAUDE.md and PLAN.md uncommitted for privacy

Clean root directory for better project organization.
This commit is contained in:
David Snelling 2025-08-25 09:53:41 -07:00
parent 26c7d61185
commit 2c4b34e9fb
19 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

95
docs/api-design/API-CRITICAL-FIXES.md Normal file
View file

@ -0,0 +1,95 @@
# 🚨 CRITICAL API FIXES NEEDED FOR BRAINY 2.0
## 1. ❌ WRONG: MongoDB Operators (Legal Risk!)
We accidentally introduced MongoDB-style operators which we specifically avoided for legal reasons!
### MUST REPLACE:
```typescript
// ❌ WRONG (MongoDB style)
where: {
field: {$in: [values]},
field: {$gt: value},
field: {$regex: pattern}
}
// ✅ CORRECT (Brainy style)
where: {
field: {oneOf: [values]},
field: {greaterThan: value},
field: {matches: pattern}
}
```
### Complete Operator Mapping:
- `$eq` → `equals` or `is`
- `$ne` → `notEquals`
- `$gt` → `greaterThan`
- `$gte` → `greaterEqual`
- `$lt` → `lessThan`
- `$lte` → `lessEqual`
- `$in` → `oneOf`
- `$nin` → `notOneOf`
- `$regex` → `matches`
- `$contains` → `contains`
- (NEW) → `startsWith`
- (NEW) → `endsWith`
- (NEW) → `between`
## 2. 📊 Missing Neural API Features
The backup shows we had extensive neural capabilities:
```typescript
brain.neural.similar(a, b) // Semantic similarity
brain.neural.clusters() // Auto-clustering
brain.neural.hierarchy(id) // Semantic hierarchy
brain.neural.neighbors(id) // Neighbor graph
brain.neural.outliers() // Outlier detection
brain.neural.semanticPath(a, b) // Path finding
brain.neural.visualize() // Visualization data
```
## 3. 🔄 Missing Triple Intelligence Features
We need to ensure Triple Intelligence has all its features:
- Query optimization
- Progressive filtering
- Parallel execution
- Query learning/caching
- Explanations
## 4. 🧩 Missing Augmentation Features
- Synapses (Notion, Slack, Salesforce connectors)
- Conduits (Brainy-to-Brainy sync)
- Real-time bidirectional sync
## 5. 📥 Missing Import/Export Features
- Neural import with entity extraction
- CSV import with AI parsing
- JSON flattening and structure detection
- Batch neural processing
## 6. 🎯 API Simplification Issues
While simplifying, we may have lost:
- Verb scoring intelligence
- Clustering management
- Performance monitoring
- Health checks
- Statistics collection
## 7. 🔍 Search Method Confusion
Need to clarify:
- `search(query)` = simple convenience for `find({like: query})`
- `find(query)` = full Triple Intelligence
- Remove duplicate methods like `searchByNounTypes`, etc.
## IMMEDIATE ACTIONS:
1. Replace ALL MongoDB operators with Brainy operators
2. Restore neural API with all methods
3. Ensure Triple Intelligence is complete
4. Verify augmentation system works
5. Test import/export capabilities
6. Document the clean API properly
## BACKUP LOCATIONS:
- `/home/dpsifr/Projects/BACKUP/brainy (Copy)` - Full backup
- `/home/dpsifr/Projects/BACKUP/brainy-clean` - Clean version
- `/home/dpsifr/Projects/brainy (Copy)` - Another backup

62
docs/api-design/API-QUICK-REFERENCE.md Normal file
View file

@ -0,0 +1,62 @@
# 🧠 Brainy 2.0 Quick Reference Card
## Core Operations
```typescript
// Nouns
await brain.addNoun(vector, metadata) // Create
await brain.getNoun(id) // Read
await brain.updateNoun(id, vector?, meta?) // Update
await brain.deleteNoun(id) // Delete
// Verbs
await brain.addVerb(source, target, type) // Create relationship
await brain.getVerb(id) // Get relationship
await brain.deleteVerb(id) // Delete relationship
// Metadata
await brain.getNounMetadata(id) // Get metadata only
await brain.updateNounMetadata(id, meta) // Update metadata only
await brain.hasNoun(id) // Check existence
```
## Search
```typescript
await brain.search(query, k?) // Vector search
await brain.searchText('natural language') // NLP search
await brain.findSimilar(id, k?) // Similarity search
await brain.find(tripleQuery) // Triple Intelligence 🧠
```
## Graph
```typescript
await brain.getConnections(id) // All connections
await brain.getVerbsBySource(id) // Outgoing
await brain.getVerbsByTarget(id) // Incoming
await brain.getVerbsByType(type) // By type
```
## Management
```typescript
brain.getCacheStats() // Cache stats
brain.clearCache() // Clear cache
brain.size() // Total count
await brain.getStats() // All statistics
await brain.clear() // Clear all data
```
## Lifecycle
```typescript
const brain = new BrainyData() // Create
await brain.init() // Initialize
await brain.shutdown() // Cleanup
```
## Configuration
```typescript
new BrainyData({
storage: 'auto', // auto | memory | filesystem | s3
cache: true, // Enable caching
index: true, // Enable indexing
dimensions: 384 // Vector dimensions
})
```

277
docs/api-design/API-REFERENCE.md Normal file
View file

@ -0,0 +1,277 @@
# 🧠 Brainy 2.0 API Reference
> **Philosophy**: Every method is specific, clear, and purposeful. No ambiguity, no duplicates.
## 📚 Core Data Operations
### Nouns (Vectors with Metadata)
```typescript
// Create
await brain.addNoun(vector, metadata) // Add single noun
await brain.addNouns(items[]) // Add multiple nouns
// Read
await brain.getNoun(id) // Get single noun
await brain.getNouns(filter?) // Get multiple nouns
await brain.getNounWithVerbs(id) // Get noun + relationships
// Update
await brain.updateNoun(id, vector?, metadata?) // Update noun
await brain.updateNounMetadata(id, metadata) // Update metadata only
// Delete
await brain.deleteNoun(id) // Delete single noun
await brain.deleteNouns(ids[]) // Delete multiple nouns
```
### Verbs (Relationships)
```typescript
// Create
await brain.addVerb(source, target, type, metadata?) // Add relationship
// Read
await brain.getVerb(id) // Get single verb
await brain.getVerbs(filter?) // Get multiple verbs
await brain.getVerbsBySource(sourceId) // Get outgoing relationships
await brain.getVerbsByTarget(targetId) // Get incoming relationships
await brain.getVerbsByType(type) // Get by relationship type
// Delete
await brain.deleteVerb(id) // Delete relationship
await brain.deleteVerbs(ids[]) // Delete multiple relationships
```
## 🔍 Search Operations
### Vector Search
```typescript
await brain.search(query, k?, options?) // Primary search method
await brain.searchText(text, k?, options?) // Natural language search
await brain.findSimilar(id, k?, options?) // Find similar to existing noun
await brain.searchWithCursor(query, cursor) // Paginated search
```
### Advanced Search
```typescript
await brain.searchByNounTypes(types[], query) // Filter by noun types
await brain.searchByMetadata(filter, query?) // Filter by metadata
await brain.searchWithinNouns(ids[], query) // Search within specific nouns
```
### Triple Intelligence 🧠
```typescript
await brain.find(query) // Unified Vector + Graph + Field search
// Examples:
await brain.find('documents about AI') // Natural language
await brain.find({ like: 'sample-id' }) // Similar to ID
await brain.find({ where: { type: 'doc' }}) // Field filter
await brain.find({ connected: { to: id }}) // Graph traversal
```
## 🕸️ Graph Operations
```typescript
await brain.getConnections(id, depth?) // Get all connections
await brain.findPath(sourceId, targetId) // Find path between nouns
await brain.getNeighbors(id, hops?) // Get graph neighbors
```
## 📊 Metadata & Filtering
```typescript
await brain.getNounMetadata(id) // Get metadata only
await brain.getFilterableFields() // Get indexed fields
await brain.getFieldValues(field) // Get unique values for field
```
## 🚀 Performance & Optimization
### Cache Management
```typescript
brain.getCacheStats() // Get cache statistics
brain.clearCache() // Clear search cache
```
### Statistics
```typescript
await brain.getStats() // Complete statistics
await brain.getServiceStats(service?) // Service-specific stats
brain.getHealthStatus() // System health
brain.size() // Total noun count
```
### Intelligent Features
```typescript
// Verb Scoring
await brain.trainVerbScoring(feedback) // Provide training feedback
brain.getVerbScoringStats() // Get scoring statistics
// Real-time Updates
brain.enableRealtimeUpdates(config) // Enable live sync
brain.disableRealtimeUpdates() // Disable live sync
await brain.syncNow() // Manual sync
```
## 🌐 Distributed Operations
```typescript
// Remote Connections
await brain.connectRemote(url, options?) // Connect to remote instance
await brain.disconnectRemote() // Disconnect from remote
brain.isRemoteConnected() // Check connection status
// Search Modes
await brain.searchLocal(query) // Search local only
await brain.searchRemote(query) // Search remote only
await brain.searchHybrid(query) // Search both
// Operational Modes
brain.setReadOnly(enabled) // Toggle read-only mode
brain.setWriteOnly(enabled) // Toggle write-only mode
brain.freeze() // Freeze all modifications
brain.unfreeze() // Unfreeze modifications
```
## 💾 Import/Export
```typescript
await brain.backup() // Create full backup
await brain.restore(backup) // Restore from backup
await brain.importData(data, format) // Import external data
await brain.exportData(format) // Export data
```
## 🧹 Data Management
```typescript
await brain.clearNouns(options?) // Clear all nouns
await brain.clearVerbs(options?) // Clear all verbs
await brain.clearAll(options?) // Clear everything
await brain.rebuildIndex() // Rebuild metadata index
```
## 🔧 Utilities
```typescript
// Embeddings
await brain.embed(text) // Generate embedding
await brain.embedBatch(texts[]) // Batch embeddings
// Similarity
await brain.calculateSimilarity(a, b) // Compare vectors
await brain.calculateDistance(a, b, metric?) // Calculate distance
// Encryption (if configured)
await brain.encrypt(data) // Encrypt data
await brain.decrypt(data) // Decrypt data
```
## 🎯 Lifecycle
```typescript
// Initialization
const brain = new BrainyData(config?) // Create instance
await brain.init() // Initialize (required!)
// Cleanup
await brain.shutdown() // Graceful shutdown
await brain.cleanup() // Clean up resources
```
## ⚡ Static Methods
```typescript
// Model Management
await BrainyData.preloadModel(options?) // Preload ML model
await BrainyData.warmup(options?) // Warmup system
// Utilities
BrainyData.version // Get version
BrainyData.checkEnvironment() // Check environment support
```
## 🎨 Configuration
```typescript
const brain = new BrainyData({
// Storage
storage: 'memory' | 'filesystem' | 's3' | 'auto',
// Performance
cache: true, // Enable caching
index: true, // Enable metadata indexing
metrics: true, // Enable metrics collection
// Distributed
distributed: {
mode: 'reader' | 'writer' | 'hybrid',
partitions: 8
},
// Advanced
dimensions: 384, // Vector dimensions
similarity: 'cosine', // Similarity metric
verbose: false // Logging verbosity
})
```
## 📝 Quick Examples
```typescript
// Simple usage
const brain = new BrainyData()
await brain.init()
// Add data
const id = await brain.addNoun(vector, {
title: 'My Document',
type: 'article'
})
// Search
const results = await brain.search('AI research', 10)
// Graph relationships
await brain.addVerb(id1, id2, 'references')
const connections = await brain.getConnections(id1)
// Triple Intelligence
const insights = await brain.find({
like: 'sample-doc',
where: { type: 'article' },
connected: { to: id1, via: 'references' }
})
// Cleanup
await brain.shutdown()
```
## 🚨 Important: No Aliases!
Brainy 2.0 follows a **ONE METHOD, ONE PURPOSE** philosophy:
- No duplicate methods
- No confusing aliases
- Clear, specific naming
- If you need the old methods for migration, they're now private
## 🚀 What Changed from 1.x
### Now Private (Use New Methods)
- `add()` → Use `addNoun()`
- `get()` → Use `getNoun()`
- `delete()` → Use `deleteNoun()`
- `update()` → Use `updateNoun()`
- `updateMetadata()` → Use `updateNounMetadata()`
- `getMetadata()` → Use `getNounMetadata()`
- `relate()` / `connect()` → Use `addVerb()`
- `has()` / `exists()` → Use `hasNoun()`
- `clearAll()` → Use `clear()`
- `addItem()` / `addToBoth()` → Removed
### New in 2.0
- `find()` - Triple Intelligence search
- `getNounWithVerbs()` - Get noun with relationships
- `searchText()` - Natural language search
- `trainVerbScoring()` - Intelligent scoring
- Real-time sync capabilities
- Distributed operations

220
docs/api-design/BRAINY-2.0-COMPLETE-API.md Normal file
View file

@ -0,0 +1,220 @@
# 🧠 Brainy 2.0 Complete Public API
> **Clean, Specific, Beautiful** - Every method has ONE clear purpose.
## 📚 NOUNS (Vectors with Metadata)
```typescript
// Single Operations
addNoun(vector, metadata?) // Add one noun
getNoun(id) // Get one noun by ID
updateNoun(id, vector?, metadata?) // Update entire noun
updateNounMetadata(id, metadata) // Update metadata only
getNounMetadata(id) // Get metadata only
getNounWithVerbs(id) // Get noun with all relationships
deleteNoun(id) // Delete one noun
hasNoun(id) // Check if noun exists
// Batch Operations
addNouns(items[]) // Add multiple nouns
getNouns(idsOrOptions) // Get multiple nouns (unified method)
// getNouns(['id1', 'id2']) // Get by specific IDs
// getNouns({ filter: {...} }) // Get with filters
// getNouns({ limit: 10, offset: 20 }) // Get with pagination
deleteNouns(ids[]) // Delete multiple nouns
```
## 🔗 VERBS (Relationships)
```typescript
// Single Operations
addVerb(source, target, type, metadata?) // Create relationship
getVerb(id) // Get one verb by ID
deleteVerb(id) // Delete one verb
// Batch Operations
addVerbs(verbs[]) // Add multiple relationships
getVerbs(filter?) // Get filtered verbs
getVerbsBySource(sourceId) // Get outgoing relationships
getVerbsByTarget(targetId) // Get incoming relationships
getVerbsByType(type) // Get by relationship type
deleteVerbs(ids[]) // Delete multiple verbs
```
## 🔍 SEARCH
```typescript
// Core Search
search(query, k?, options?) // Primary vector search
searchText(text, k?, options?) // Natural language search
find(query) // Triple Intelligence (Vector+Graph+Field) 🧠
findSimilar(id, k?, options?) // Find similar to existing noun
// Advanced Search
searchByNounTypes(types[], query, k?) // Filter by noun types
searchWithinItems(query, ids[], k?) // Search within specific nouns
searchWithCursor(query, cursor) // Paginated search
searchByStandardField(field, value, k?) // Field-based search
// Graph Search
searchVerbs(query, options?) // Search relationships
searchNounsByVerbs(conditions) // Find nouns by relationships
// Distributed Search
searchLocal(query, k?) // Search local instance only
searchRemote(query, k?) // Search remote instance only
searchCombined(query, k?) // Search both local and remote
```
## 📊 METADATA & FILTERING
```typescript
getFilterFields() // Get all indexed fields
getFilterValues(field) // Get unique values for a field
getAvailableFieldNames() // Get available field names
getStandardFieldMappings() // Get standard field mappings
```
## 🚀 PERFORMANCE & MONITORING
```typescript
// Cache
getCacheStats() // Get cache statistics
clearCache() // Clear search cache
// Statistics
size() // Total noun count
getStatistics(options?) // Comprehensive statistics
getServiceStatistics(service) // Per-service statistics
listServices() // List all services
flushStatistics() // Persist statistics to storage
// Health
getHealthStatus() // System health check
status() // Full status report
```
## ⚙️ CONFIGURATION
```typescript
// Operational Modes
isReadOnly() / setReadOnly(bool) // Read-only mode
isWriteOnly() / setWriteOnly(bool) // Write-only mode
isFrozen() / setFrozen(bool) // Freeze all modifications
// Real-time Sync
enableRealtimeUpdates(config) // Enable live synchronization
disableRealtimeUpdates() // Disable synchronization
getRealtimeUpdateConfig() // Get current config
checkForUpdatesNow() // Manual sync trigger
// Remote Connection
connectToRemoteServer(url, options?) // Connect to remote instance
disconnectFromRemoteServer() // Disconnect from remote
isConnectedToRemoteServer() // Check connection status
```
## 🧠 INTELLIGENCE
```typescript
// Verb Scoring
provideFeedbackForVerbScoring(feedback) // Train relationship scoring
getVerbScoringStats() // Get scoring statistics
exportVerbScoringLearningData() // Export training data
importVerbScoringLearningData(data) // Import training data
// Embeddings
embed(text) // Generate embedding vector
calculateSimilarity(a, b, metric?) // Calculate vector similarity
```
## 💾 DATA MANAGEMENT
```typescript
// Clear Operations
clear(options?) // Clear all data
clearNouns(options?) // Clear all nouns only
clearVerbs(options?) // Clear all verbs only
// Backup & Restore
backup() // Create full backup
restore(backup) // Restore from backup
// Import/Export
import(data, format) // Import external data
importSparseData(data) // Import sparse format
// Index Management
rebuildMetadataIndex() // Rebuild metadata index
```
## 🔒 SECURITY
```typescript
encryptData(data) // Encrypt data
decryptData(data) // Decrypt data
```
## 🎲 UTILITIES
```typescript
generateRandomGraph(nodes, edges) // Generate test graph data
```
## 🚀 LIFECYCLE
```typescript
// Instance Methods
new BrainyData(config?) // Create instance
init() // Initialize (REQUIRED!)
shutDown() // Graceful shutdown
cleanup() // Clean up resources
// Static Methods
BrainyData.preloadModel(options?) // Preload ML model
BrainyData.warmup(options?) // Warmup system
```
## 📐 PROPERTIES (Read-only)
```typescript
dimensions // Vector dimensions
maxConnections // HNSW max connections
efConstruction // HNSW ef construction
initialized // Is initialized?
```
---
## 📝 Key Changes in 2.0
### ✅ Simplified & Unified
- `getNouns()` now handles ALL plural queries (by IDs, filters, or pagination)
- No more `getNounsByIds()`, `queryNouns()`, `getBatch()` - just `getNouns()`
- Clear singular vs plural: `getNoun()` for one, `getNouns()` for many
### ✅ Specific Naming
- Always specify noun/verb: `addNoun()` not `add()`
- No aliases or duplicates
- One method, one purpose
### ✅ Private Legacy Methods
These are now private (use new methods above):
- `add()`, `get()`, `delete()`, `update()`
- `relate()`, `connect()`, `has()`, `exists()`
- `getMetadata()`, `updateMetadata()`
- `addItem()`, `addToBoth()`, `addBatch()`, `getBatch()`
### ✅ Triple Intelligence
- New `find()` method unifies Vector + Graph + Field search
- Most powerful search capability in one simple method
### ✅ Zero-Configuration
- Everything works instantly with sensible defaults
- Optional configuration only for advanced users
- No complex setup required
### ✅ Clean Architecture
- Augmentation system for extensibility
- All features included (no premium tiers)
- Beautiful developer experience

268
docs/api-design/BRAINY-2.0-CORRECT-API.md Normal file
View file

@ -0,0 +1,268 @@
# 🧠 Brainy 2.0 CORRECT API Reference
> **The actual API we need, with all features, correct operators, and proper methods**
## 📚 CORE DATA OPERATIONS
### Nouns (Vectors with Metadata)
```typescript
// Single Operations
addNoun(textOrVector, metadata?) // Auto-embeds text
getNoun(id) // Get one noun
updateNoun(id, textOrVector?, metadata?) // Update noun
deleteNoun(id) // Delete noun
hasNoun(id) // Check existence
// Metadata
getNounMetadata(id) // Metadata only
updateNounMetadata(id, metadata) // Update metadata
getNounWithVerbs(id) // With relationships
// Batch
addNouns(items[]) // Add multiple
getNouns(idsOrOptions) // Get multiple (unified)
deleteNouns(ids[]) // Delete multiple
```
### Verbs (Relationships)
```typescript
addVerb(source, target, type, metadata?) // Create relationship
getVerb(id) // Get verb
deleteVerb(id) // Delete verb
getVerbsBySource(sourceId) // Outgoing
getVerbsByTarget(targetId) // Incoming
getVerbsByType(type) // By type
```
## 🔍 SEARCH (Simplified & Powerful)
```typescript
// Just TWO search methods:
search(query, k?) // Simple convenience
find(query) // TRIPLE INTELLIGENCE 🧠
```
### Find Query Structure (with CORRECT Brainy Operators):
```typescript
find({
// Vector search
like: 'text' | vector | {id: 'noun-id'},
// Field filtering with BRAINY OPERATORS (NOT MongoDB!)
where: {
// Direct equality
field: value,
// Brainy operators (NO $ prefix!)
field: {
equals: value, // Exact match
notEquals: value, // Not equal
greaterThan: value, // Greater than
greaterEqual: value, // Greater or equal
lessThan: value, // Less than
lessEqual: value, // Less or equal
oneOf: [values], // In array (NOT $in)
notOneOf: [values], // Not in array
contains: value, // Contains (arrays/strings)
startsWith: value, // String starts with
endsWith: value, // String ends with
matches: pattern, // Pattern match (NOT $regex)
between: [min, max] // Between two values
}
},
// Graph traversal
connected: {
to: 'id',
from: 'id',
via: 'type',
depth: 2
},
// Control
limit: 10,
offset: 0,
explain: true
})
```
## 🧠 NEURAL API (Complete)
```typescript
// Access via brain.neural
brain.neural.similar(a, b) // Semantic similarity
brain.neural.clusters(options?) // Auto-clustering
brain.neural.hierarchy(id) // Semantic hierarchy
brain.neural.neighbors(id, k?) // K nearest neighbors
brain.neural.outliers(threshold?) // Outlier detection
brain.neural.semanticPath(from, to) // Path finding
brain.neural.visualize(options?) // Visualization data
// Enterprise performance methods
brain.neural.clusterFast(options?) // O(n) HNSW clustering
brain.neural.clusterLarge(options?) // Million-item clustering
brain.neural.clusterStream(options?) // Progressive streaming
```
### Visualization Data Format:
```typescript
brain.neural.visualize({
maxNodes: 100,
dimensions: 2 | 3,
algorithm: 'force' | 'hierarchical' | 'radial',
includeEdges: true
})
// Returns:
{
format: 'd3' | 'cytoscape' | 'graphml',
nodes: [{
id: string,
x: number,
y: number,
z?: number,
label: string,
cluster?: number,
metadata: any
}],
edges: [{
source: string,
target: string,
type: string,
weight?: number
}],
layout: {
dimensions: 2 | 3,
algorithm: string,
bounds: {min: [x,y,z], max: [x,y,z]}
}
}
```
## 📥 NEURAL IMPORT (Simple & Powerful)
```typescript
// One simple method for smart import
brain.neuralImport(data, options?)
// Options:
{
confidenceThreshold: 0.7, // Min confidence for entities
autoApply: false, // Auto-add to database
enableWeights: true, // Use confidence weights
previewOnly: false, // Just preview, don't import
skipDuplicates: true, // Skip existing entities
format?: 'auto' | 'csv' | 'json' | 'text' // Auto-detect by default
}
// Returns:
{
detectedEntities: [{
suggestedId: string,
nounType: string,
confidence: number,
originalData: any
}],
detectedRelationships: [{
sourceId: string,
targetId: string,
verbType: string,
confidence: number
}],
confidence: number, // Overall confidence
insights: string[], // AI insights
preview: string // Human-readable preview
}
```
## 🎯 VERB SCORING
```typescript
brain.verbScoring.train(feedback) // Train model
brain.verbScoring.getScore(verbId) // Get score
brain.verbScoring.export() // Export training
brain.verbScoring.import(data) // Import training
brain.verbScoring.stats() // Statistics
```
## 🔄 SYNC & DISTRIBUTION
### Conduits (Brainy-to-Brainy)
```typescript
brain.conduit.establish(url) // Connect to another Brainy
brain.conduit.sync() // Sync data
brain.conduit.close() // Disconnect
```
### Synapses (External Platforms)
```typescript
brain.synapse.notion.connect(config) // Notion integration
brain.synapse.slack.connect(config) // Slack integration
brain.synapse.salesforce.connect(config) // Salesforce
brain.synapse.custom(name, config) // Custom platform
```
## 📊 MONITORING & STATS
```typescript
brain.size() // Total nouns
brain.stats() // Full statistics
brain.health() // Health check
brain.cache.stats() // Cache stats
brain.cache.clear() // Clear cache
```
## 💾 DATA MANAGEMENT
```typescript
brain.clear(options?) // Clear all
brain.clearNouns() // Clear nouns only
brain.clearVerbs() // Clear verbs only
brain.backup() // Create backup
brain.restore(backup) // Restore
```
## 🚀 LIFECYCLE
```typescript
const brain = new BrainyData(config?) // Create
await brain.init() // Initialize (REQUIRED!)
await brain.shutdown() // Cleanup
// Configuration
{
storage: 'auto' | 'memory' | 'filesystem' | 's3',
dimensions: 384,
cache: true,
index: true,
augmentations: []
}
```
## ⚙️ EMBEDDINGS
```typescript
brain.embed(text) // Generate embedding
brain.similarity(a, b) // Calculate similarity
```
## 🎲 UTILITIES
```typescript
brain.generateRandomGraph(nodes, edges) // Test data
```
---
## ✅ KEY CORRECTIONS FROM MISTAKES:
1. **NO MongoDB operators** - We use Brainy operators (legal reasons)
2. **Neural API is complete** - All clustering, visualization methods
3. **Simple neuralImport** - One method, smart detection
4. **Visualization exports** - For D3, Cytoscape, GraphML
5. **search() is just convenience** - Not a complete alias
6. **find() has Triple Intelligence** - Vector + Graph + Field
7. **Proper operator names** - greaterThan not $gt
8. **Complete clustering API** - Fast, large, streaming options
9. **Synapses and Conduits** - External and internal sync
10. **Verb scoring** - Intelligent relationship scoring

376
docs/api-design/BRAINY-2.0-DETAILED-API.md Normal file
View file

@ -0,0 +1,376 @@
# 🧠 Brainy 2.0 Detailed API Reference
> **Complete API with full parameter descriptions**
## 📚 CORE DATA OPERATIONS
### Nouns (Vectors with Metadata)
#### `addNoun(textOrVector, metadata?)`
Add a single noun to the database
- **textOrVector**: `string | number[]` - Text to auto-embed OR pre-computed vector
- **metadata**: `object` (optional) - Associated metadata
- **Returns**: `Promise<string>` - The ID of the created noun
#### `getNoun(id)`
Retrieve a single noun by ID
- **id**: `string` - The noun's unique identifier
- **Returns**: `Promise<VectorDocument | null>` - The noun with vector and metadata
#### `updateNoun(id, textOrVector?, metadata?)`
Update an existing noun
- **id**: `string` - The noun's ID to update
- **textOrVector**: `string | number[]` (optional) - New text/vector
- **metadata**: `object` (optional) - New metadata (merged with existing)
- **Returns**: `Promise<void>`
#### `deleteNoun(id)`
Delete a single noun
- **id**: `string` - The noun's ID to delete
- **Returns**: `Promise<boolean>` - True if deleted
#### `hasNoun(id)`
Check if a noun exists
- **id**: `string` - The noun's ID to check
- **Returns**: `Promise<boolean>` - True if exists
#### `getNounMetadata(id)`
Get only the metadata of a noun (no vector)
- **id**: `string` - The noun's ID
- **Returns**: `Promise<object | null>` - Just the metadata
#### `updateNounMetadata(id, metadata)`
Update only the metadata of a noun
- **id**: `string` - The noun's ID
- **metadata**: `object` - New metadata (replaces existing)
- **Returns**: `Promise<void>`
#### `getNounWithVerbs(id)`
Get a noun with all its relationships
- **id**: `string` - The noun's ID
- **Returns**: `Promise<{noun: VectorDocument, verbs: Verb[]}>` - Noun and relationships
#### `addNouns(items[])`
Add multiple nouns in batch
- **items**: `Array<{vector: number[] | string, metadata?: object}>` - Array of nouns
- **Returns**: `Promise<string[]>` - Array of created IDs
#### `getNouns(idsOrOptions)`
Get multiple nouns (unified method)
- **idsOrOptions**: Can be one of:
- `string[]` - Array of IDs to fetch
- `{filter: object}` - Filter by metadata fields
- `{limit: number, offset: number}` - Pagination
- **Returns**: `Promise<VectorDocument[]>` - Array of nouns
#### `deleteNouns(ids[])`
Delete multiple nouns
- **ids**: `string[]` - Array of IDs to delete
- **Returns**: `Promise<boolean[]>` - Success status for each
---
### Verbs (Relationships)
#### `addVerb(source, target, type, metadata?)`
Create a relationship between nouns
- **source**: `string` - Source noun ID
- **target**: `string` - Target noun ID
- **type**: `string` - Relationship type (e.g., 'references', 'contains')
- **metadata**: `object` (optional) - Relationship metadata
- **Returns**: `Promise<string>` - The verb ID
#### `getVerb(id)`
Get a single relationship
- **id**: `string` - The verb's ID
- **Returns**: `Promise<Verb | null>` - The relationship
#### `deleteVerb(id)`
Delete a relationship
- **id**: `string` - The verb's ID
- **Returns**: `Promise<boolean>` - True if deleted
#### `getVerbsBySource(sourceId)`
Get all outgoing relationships from a noun
- **sourceId**: `string` - The source noun's ID
- **Returns**: `Promise<Verb[]>` - Array of relationships
#### `getVerbsByTarget(targetId)`
Get all incoming relationships to a noun
- **targetId**: `string` - The target noun's ID
- **Returns**: `Promise<Verb[]>` - Array of relationships
#### `getVerbsByType(type)`
Get all relationships of a specific type
- **type**: `string` - The relationship type
- **Returns**: `Promise<Verb[]>` - Array of relationships
---
## 🔍 SEARCH & INTELLIGENCE
### Core Search Methods
#### `search(query, k?)`
Simple vector similarity search (convenience wrapper)
- **query**: `string | number[]` - Text query or vector
- **k**: `number` (default: 10) - Number of results
- **Returns**: `Promise<SearchResult[]>` - Ranked results with scores
- **Note**: Equivalent to `find({like: query, limit: k})`
#### `find(query)`
**TRIPLE INTELLIGENCE** - The ultimate search method
- **query**: `object` - Complex query object supporting:
```typescript
{
// Vector similarity
like?: string | number[] | {id: string}, // Text, vector, or noun ID
// Field filtering
where?: {
field: value, // Exact match
field: {$in: [values]}, // In array
field: {$gt: value}, // Greater than
field: {$regex: pattern} // Pattern match
},
// Graph traversal
connected?: {
to?: string, // Target noun ID
from?: string, // Source noun ID
via?: string, // Relationship type
depth?: number // Traversal depth (default: 1)
},
// Control
limit?: number, // Max results (default: 10)
offset?: number, // Skip results
threshold?: number // Min similarity score
}
```
- **Returns**: `Promise<EnhancedSearchResult[]>` - Results with scores and explanations
#### `findSimilar(id, k?)`
Find nouns similar to an existing noun
- **id**: `string` - Reference noun ID
- **k**: `number` (default: 10) - Number of results
- **Returns**: `Promise<SearchResult[]>` - Similar nouns
---
### Neural API
#### `neural.search(query, options?)`
Neural-enhanced semantic search
- **query**: `string` - Natural language query
- **options**: `{expand?: boolean, rerank?: boolean}` - Enhancement options
- **Returns**: `Promise<NeuralSearchResult[]>` - Enhanced results
#### `neural.cluster(options?)`
Automatic clustering of nouns
- **options**: `{k?: number, method?: 'kmeans'|'dbscan', minSize?: number}`
- **Returns**: `Promise<Cluster[]>` - Generated clusters
#### `neural.extract(text)`
Extract entities from text
- **text**: `string` - Text to analyze
- **Returns**: `Promise<{entities: Entity[], relationships: Relationship[]}>`
#### `neural.summarize(ids[])`
Generate summary from multiple nouns
- **ids**: `string[]` - Noun IDs to summarize
- **Returns**: `Promise<string>` - Generated summary
#### `neural.analyze(id)`
Deep analysis of a noun
- **id**: `string` - Noun ID to analyze
- **Returns**: `Promise<Analysis>` - Detailed analysis
#### `neural.compare(id1, id2)`
Semantic comparison of two nouns
- **id1**: `string` - First noun ID
- **id2**: `string` - Second noun ID
- **Returns**: `Promise<{similarity: number, differences: string[], commonalities: string[]}>`
#### `neural.topics(options?)`
Topic modeling across all nouns
- **options**: `{k?: number, method?: 'lda'|'nmf'}` - Topic extraction options
- **Returns**: `Promise<Topic[]>` - Discovered topics
#### `neural.patterns(options?)`
Pattern detection in data
- **options**: `{minSupport?: number, minConfidence?: number}`
- **Returns**: `Promise<Pattern[]>` - Detected patterns
---
## 📥 IMPORT/EXPORT
### Neural Import
#### `neuralImport(data, options?)`
Smart AI-powered data import
- **data**: `any` - Data to import (auto-detects format)
- **options**: `{autoExtract?: boolean, autoRelate?: boolean, batchSize?: number}`
- **Returns**: `Promise<{nouns: string[], verbs: string[]}>`
#### `neuralImport.csv(file, options?)`
Import CSV with intelligent parsing
- **file**: `string | Buffer` - CSV file path or content
- **options**: `{headers?: boolean, delimiter?: string, embedColumns?: string[]}`
- **Returns**: `Promise<ImportResult>`
#### `neuralImport.json(data, options?)`
Import JSON with structure detection
- **data**: `object | string` - JSON data or string
- **options**: `{flatten?: boolean, keyPaths?: string[]}`
- **Returns**: `Promise<ImportResult>`
#### `neuralImport.text(text, options?)`
Import text with NLP processing
- **text**: `string` - Raw text
- **options**: `{chunk?: boolean, chunkSize?: number, extractEntities?: boolean}`
- **Returns**: `Promise<ImportResult>`
---
## 🔄 SYNC & DISTRIBUTION
### Real-time Sync
#### `sync.enable(config)`
Enable real-time synchronization
- **config**: `{url: string, interval?: number, bidirectional?: boolean}`
- **Returns**: `Promise<void>`
#### `sync.disable()`
Disable synchronization
- **Returns**: `Promise<void>`
#### `sync.now()`
Trigger manual sync
- **Returns**: `Promise<SyncResult>`
#### `sync.status()`
Get sync status
- **Returns**: `Promise<{enabled: boolean, lastSync: Date, pending: number}>`
---
### Remote Operations
#### `remote.connect(url, options?)`
Connect to remote Brainy instance
- **url**: `string` - Remote instance URL
- **options**: `{auth?: string, timeout?: number, retry?: boolean}`
- **Returns**: `Promise<Connection>`
#### `remote.search(query)`
Search remote instance
- **query**: `any` - Same as find() query
- **Returns**: `Promise<SearchResult[]>`
---
## 🧠 INTELLIGENCE FEATURES
### Verb Scoring
#### `verbScoring.train(feedback)`
Train the verb scoring model
- **feedback**: `{verbId: string, score: number, context?: object}`
- **Returns**: `Promise<void>`
#### `verbScoring.getScore(verbId)`
Get intelligent score for a verb
- **verbId**: `string` - The verb to score
- **Returns**: `Promise<number>` - Score between 0-1
#### `verbScoring.export()`
Export training data
- **Returns**: `Promise<TrainingData>`
#### `verbScoring.import(data)`
Import training data
- **data**: `TrainingData` - Previously exported data
- **Returns**: `Promise<void>`
---
### Embeddings
#### `embed(text)`
Generate embedding vector for text
- **text**: `string` - Text to embed
- **Returns**: `Promise<number[]>` - Embedding vector
#### `embedBatch(texts[])`
Generate embeddings for multiple texts
- **texts**: `string[]` - Array of texts
- **Returns**: `Promise<number[][]>` - Array of vectors
#### `similarity(a, b, metric?)`
Calculate similarity between vectors or texts
- **a**: `string | number[]` - First item
- **b**: `string | number[]` - Second item
- **metric**: `'cosine' | 'euclidean' | 'manhattan'` (default: 'cosine')
- **Returns**: `Promise<number>` - Similarity score
---
## 📊 MONITORING & PERFORMANCE
#### `size()`
Get total noun count
- **Returns**: `number` - Total nouns in database
#### `stats()`
Get comprehensive statistics
- **Returns**: `Promise<Statistics>` - Detailed stats
#### `health()`
System health check
- **Returns**: `Promise<{status: 'healthy'|'degraded'|'unhealthy', details: object}>`
#### `cache.stats()`
Get cache statistics
- **Returns**: `CacheStats` - Hit rates, size, etc.
#### `cache.clear()`
Clear all caches
- **Returns**: `void`
---
## 🚀 LIFECYCLE
#### `new BrainyData(config?)`
Create new Brainy instance
- **config**: `object` (optional)
```typescript
{
storage?: 'auto' | 'memory' | 'filesystem' | 's3',
dimensions?: number, // Vector dimensions (default: 384)
cache?: boolean, // Enable caching (default: true)
index?: boolean, // Enable indexing (default: true)
verbose?: boolean, // Verbose logging (default: false)
augmentations?: Augmentation[] // Custom augmentations
}
```
#### `init()`
Initialize the instance (REQUIRED!)
- **Returns**: `Promise<void>`
- **Note**: Must be called before any operations
#### `shutdown()`
Graceful shutdown
- **Returns**: `Promise<void>` - Saves state and closes connections
---
## 📐 READ-ONLY PROPERTIES
- **dimensions**: `number` - Vector dimensions
- **initialized**: `boolean` - Whether init() was called
- **mode**: `string` - Current operational mode

260
docs/api-design/BRAINY-2.0-FINAL-API.md Normal file
View file

@ -0,0 +1,260 @@
# 🧠 Brainy 2.0 Final Complete API
> **Clean, Powerful, Complete** - All features, beautifully organized.
## 📚 CORE DATA
### Nouns (Vectors with Metadata)
```typescript
// Single Operations
addNoun(textOrVector, metadata?) // Add noun (auto-embeds text!)
getNoun(id) // Get one noun
updateNoun(id, textOrVector?, metadata?) // Update noun
deleteNoun(id) // Delete noun
hasNoun(id) // Check if exists
// Metadata Operations
getNounMetadata(id) // Get metadata only
updateNounMetadata(id, metadata) // Update metadata only
getNounWithVerbs(id) // Get noun with relationships
// Batch Operations
addNouns(items[]) // Add multiple nouns
getNouns(idsOrOptions) // Get multiple nouns (unified)
deleteNouns(ids[]) // Delete multiple nouns
```
### Verbs (Relationships)
```typescript
addVerb(source, target, type, metadata?) // Create relationship
getVerb(id) // Get verb
deleteVerb(id) // Delete verb
getVerbsBySource(sourceId) // Outgoing relationships
getVerbsByTarget(targetId) // Incoming relationships
getVerbsByType(type) // By relationship type
```
## 🔍 SEARCH & INTELLIGENCE
### Core Search
```typescript
search(query, k?) // Simple vector search
find(query) // TRIPLE INTELLIGENCE 🧠
findSimilar(id, k?) // Find similar to noun
```
### Neural API
```typescript
neural.search(query) // Neural-enhanced search
neural.cluster(options?) // Automatic clustering
neural.extract(text) // Entity extraction
neural.summarize(ids[]) // Summarize nouns
neural.analyze(id) // Deep analysis
neural.compare(id1, id2) // Semantic comparison
neural.topics() // Topic modeling
neural.patterns() // Pattern detection
```
### Clustering
```typescript
clusters.create(options?) // Create clusters
clusters.get(id) // Get cluster
clusters.list() // List all clusters
clusters.addToCluster(clusterId, nounId) // Add to cluster
clusters.optimize() // Re-optimize clusters
clusters.suggest(nounId) // Suggest best cluster
```
## 🧠 INTELLIGENCE FEATURES
### Triple Intelligence
```typescript
tripleIntelligence.analyze(query) // Combined V+G+F analysis
tripleIntelligence.explain(results) // Explain search results
tripleIntelligence.optimize(query) // Query optimization
```
### Verb Scoring
```typescript
verbScoring.train(feedback) // Train scoring model
verbScoring.getScore(verb) // Get verb score
verbScoring.export() // Export training data
verbScoring.import(data) // Import training data
verbScoring.stats() // Get statistics
```
### Embeddings
```typescript
embed(text) // Generate embedding
embedBatch(texts[]) // Batch embeddings
similarity(a, b) // Calculate similarity
distance(a, b, metric?) // Calculate distance
```
## 📥 IMPORT/EXPORT
### Neural Import
```typescript
neuralImport(data, options?) // Smart data import
neuralImport.csv(file, options?) // Import CSV with AI
neuralImport.json(data, options?) // Import JSON with AI
neuralImport.text(text, options?) // Import text with NLP
neuralImport.url(url, options?) // Import from URL
neuralImport.batch(items[], options?) // Batch neural import
```
### Data Management
```typescript
import(data, format) // Standard import
export(format) // Export data
importSparse(data) // Import sparse format
backup() // Create backup
restore(backup) // Restore backup
```
## 🔄 SYNC & DISTRIBUTION
### Real-time Sync
```typescript
sync.enable(config) // Enable real-time sync
sync.disable() // Disable sync
sync.now() // Manual sync
sync.status() // Sync status
```
### Remote Operations
```typescript
remote.connect(url, options?) // Connect to remote
remote.disconnect() // Disconnect
remote.search(query) // Search remote
remote.sync() // Sync with remote
```
### Conduits (Brainy-to-Brainy)
```typescript
conduit.establish(url) // Create conduit
conduit.send(data) // Send via conduit
conduit.receive(callback) // Receive data
conduit.close() // Close conduit
```
### Synapses (External Platforms)
```typescript
synapse.notion.connect(config) // Connect to Notion
synapse.slack.connect(config) // Connect to Slack
synapse.salesforce.connect(config) // Connect to Salesforce
synapse.custom(platform, config) // Custom platform
```
## 📊 ANALYTICS & MONITORING
### Statistics
```typescript
size() // Total count
stats() // Full statistics
stats.byService(service) // Per-service stats
stats.byType(type) // Per-type stats
health() // Health check
```
### Performance
```typescript
cache.stats() // Cache statistics
cache.clear() // Clear cache
cache.optimize() // Optimize cache
index.rebuild() // Rebuild index
index.optimize() // Optimize index
```
### Monitoring
```typescript
monitor.enable() // Enable monitoring
monitor.metrics() // Get metrics
monitor.alerts() // Get alerts
monitor.logs(options?) // Get logs
```
## ⚙️ CONFIGURATION
### Operational Modes
```typescript
setReadOnly(bool) // Read-only mode
setWriteOnly(bool) // Write-only mode
setFrozen(bool) // Freeze all changes
getMode() // Current mode
```
### Augmentations
```typescript
augmentations.register(augmentation) // Add augmentation
augmentations.list() // List all
augmentations.get(name) // Get by name
augmentations.enable(name) // Enable
augmentations.disable(name) // Disable
```
## 🔧 UTILITIES
### Data Operations
```typescript
clear(options?) // Clear all
clearNouns() // Clear nouns
clearVerbs() // Clear verbs
generateRandomGraph(nodes, edges) // Generate test data
```
### Field Management
```typescript
fields.list() // List indexed fields
fields.values(field) // Get unique values
fields.add(field) // Add field to index
fields.remove(field) // Remove from index
```
## 🚀 LIFECYCLE
```typescript
// Creation & Initialization
new BrainyData(config?) // Create instance
init() // Initialize (REQUIRED!)
warmup() // Warmup caches
// Cleanup
shutdown() // Graceful shutdown
cleanup() // Clean resources
// Static Methods
BrainyData.preloadModel() // Preload ML model
BrainyData.version // Get version
```
## 📐 PROPERTIES
```typescript
dimensions // Vector dimensions (readonly)
initialized // Is initialized (readonly)
mode // Current mode (readonly)
```
---
## 🎯 Key Features Preserved
✅ **Neural Import** - Smart AI-powered data import
✅ **Clustering** - Automatic and manual clustering
✅ **Triple Intelligence** - Vector + Graph + Field combined
✅ **Verb Scoring** - Intelligent relationship scoring
✅ **Synapses** - External platform connectors
✅ **Conduits** - Brainy-to-Brainy sync
✅ **Neural API** - Advanced AI operations
✅ **Real-time Sync** - Live data synchronization
✅ **Monitoring** - Performance and health tracking
## 🚀 What's New in 2.0
1. **Auto-embedding** - `addNoun()` accepts text directly
2. **Unified `find()`** - One method for all complex queries
3. **Neural API** - Powerful AI operations built-in
4. **Augmentation System** - Extensible architecture
5. **Clean naming** - Specific noun/verb terminology
6. **No duplicates** - One method per operation

149
docs/api-design/BRAINY-2.0-SIMPLIFIED-API.md Normal file
View file

@ -0,0 +1,149 @@
# 🧠 Brainy 2.0 Simplified Public API
> **Ultra-clean, Simple, Powerful** - Minimal methods, maximum capability.
## 📚 NOUNS (Data with Vectors)
```typescript
// Single Operations
addNoun(textOrVector, metadata?) // Add noun (auto-embeds text!)
getNoun(id) // Get one noun
updateNoun(id, textOrVector?, metadata?) // Update noun
deleteNoun(id) // Delete noun
hasNoun(id) // Check if exists
// Metadata Operations
getNounMetadata(id) // Get metadata only
updateNounMetadata(id, metadata) // Update metadata only
getNounWithVerbs(id) // Get noun with relationships
// Batch Operations
addNouns(items[]) // Add multiple nouns
getNouns(idsOrOptions) // Get multiple nouns (unified)
deleteNouns(ids[]) // Delete multiple nouns
```
## 🔗 VERBS (Relationships)
```typescript
// Core Operations
addVerb(source, target, type, metadata?) // Create relationship
getVerb(id) // Get verb
deleteVerb(id) // Delete verb
// Queries
getVerbsBySource(sourceId) // Outgoing relationships
getVerbsByTarget(targetId) // Incoming relationships
getVerbsByType(type) // By relationship type
```
## 🔍 SEARCH (One Method to Rule Them All)
```typescript
// THE ONLY SEARCH METHODS YOU NEED:
search(query, k?) // Simple vector search (alias to find)
find(query) // TRIPLE INTELLIGENCE 🧠
```
### Find Query Examples:
```typescript
// Text search (auto-embeds)
find('documents about AI')
// Similar to existing noun
find({ like: 'noun-id-123' })
// Field filtering
find({ where: { type: 'article' }})
// Graph traversal
find({ connected: { to: 'id', via: 'references' }})
// Combined queries (Triple Intelligence!)
find({
like: 'sample-doc', // Vector similarity
where: { status: 'published' }, // Field filter
connected: { via: 'cites' }, // Graph relationships
limit: 10 // Pagination
})
```
## 📊 METADATA
```typescript
getFilterableFields() // Get indexed fields
getFieldValues(field) // Get unique values for field
```
## 🚀 PERFORMANCE
```typescript
// Cache
getCacheStats() // Cache statistics
clearCache() // Clear cache
// Stats
size() // Total count
getStatistics() // Full statistics
getHealthStatus() // Health check
```
## ⚙️ CONFIGURATION
```typescript
// Modes
setReadOnly(bool) // Read-only mode
setWriteOnly(bool) // Write-only mode
setFrozen(bool) // Freeze all changes
// Remote Sync
connectRemote(url) // Connect to remote
disconnectRemote() // Disconnect
syncNow() // Manual sync
```
## 💾 DATA MANAGEMENT
```typescript
clear(options?) // Clear all
clearNouns() // Clear nouns
clearVerbs() // Clear verbs
backup() // Create backup
restore(backup) // Restore backup
```
## 🚀 LIFECYCLE
```typescript
new BrainyData(config?) // Create
init() // Initialize (REQUIRED!)
shutdown() // Cleanup
```
---
## 🎯 Philosophy
### Why So Simple?
1. **`addNoun()` handles everything** - Text? Auto-embeds. Vector? Uses directly.
2. **`find()` is the ultimate search** - Combines vector, graph, and field search
3. **`search()` is just convenience** - Simple alias to `find()` for basic queries
4. **No duplicate methods** - One way to do each thing
### The Power of Find
The `find()` method is your Swiss Army knife:
- Text search → Auto-embeds and searches
- Vector search → `{ like: 'id' }` or `{ like: vector }`
- Field search → `{ where: { field: value }}`
- Graph search → `{ connected: { to/from: 'id' }}`
- Combine them all → Triple Intelligence!
### Zero Configuration
Everything just works:
- Text auto-embeds
- Vectors auto-index
- Metadata auto-indexes
- Relationships auto-optimize

343
docs/api-design/BRAINY-2.0-UNIFIED-API.md Normal file
View file

@ -0,0 +1,343 @@
# 🧠 Brainy 2.0 Unified Public API
> **The complete, accurate API based on actual implementation**
## 📚 CORE DATA OPERATIONS
### Nouns (Vectors with Metadata)
```typescript
// === SINGLE OPERATIONS ===
addNoun(textOrVector, metadata?) // Add noun (auto-embeds text)
getNoun(id) // Get one noun
updateNoun(id, textOrVector?, metadata?) // Update noun
deleteNoun(id) // Delete noun
hasNoun(id) // Check if exists
// === METADATA OPERATIONS ===
getNounMetadata(id) // Get metadata only
updateNounMetadata(id, metadata) // Update metadata only
getNounWithVerbs(id) // Get noun with relationships
// === BATCH OPERATIONS ===
addNouns(items[]) // Add multiple nouns
getNouns(idsOrOptions) // Get multiple (unified method)
// getNouns(['id1', 'id2']) // By IDs
// getNouns({filter: {...}}) // By filter
// getNouns({limit: 10, offset: 20}) // Paginated
deleteNouns(ids[]) // Delete multiple
```
### Verbs (Relationships)
```typescript
// === SINGLE OPERATIONS ===
addVerb(source, target, type, metadata?) // Create relationship
getVerb(id) // Get verb
deleteVerb(id) // Delete verb
// === QUERY OPERATIONS ===
getVerbsBySource(sourceId) // Outgoing relationships
getVerbsByTarget(targetId) // Incoming relationships
getVerbsByType(type) // By relationship type
getVerbs(filter?) // Get filtered verbs
deleteVerbs(ids[]) // Delete multiple
```
## 🔍 SEARCH & INTELLIGENCE
### Primary Search Methods
```typescript
// === TWO MAIN METHODS ===
search(query, k?) // Simple vector search
// Equivalent to: find({like: query, limit: k})
find(query) // TRIPLE INTELLIGENCE 🧠
// Combines Vector + Graph + Field search
```
### Find Query Structure
```typescript
find({
// === VECTOR SEARCH ===
like: 'text query' | vector | {id: 'noun-id'},
similar: 'text' | vector, // Alternative to 'like'
// === FIELD FILTERING (Brainy Operators) ===
where: {
// Direct equality
field: value,
// Brainy operators (CORRECT - NO MongoDB $)
field: {
equals: value, // Exact match
is: value, // Same as equals
greaterThan: value, // Greater than
lessThan: value, // Less than
oneOf: [values], // In array (NOT $in)
contains: value // Array/string contains
// Note: Additional operators can be added
}
},
// === GRAPH TRAVERSAL ===
connected: {
to: 'id' | ['id1', 'id2'], // Target nodes
from: 'id' | ['id1', 'id2'], // Source nodes
type: 'type' | ['type1'], // Relationship types
depth: 2, // Traversal depth
direction: 'in' | 'out' | 'both'
},
// === CONTROL OPTIONS ===
limit: 10, // Max results
offset: 0, // Skip results
explain: false, // Add explanations
boost: 'recent' | 'popular' // Result boosting
})
```
## 🧠 NEURAL API
Access via `brain.neural`:
```typescript
// === SIMILARITY & CLUSTERING ===
brain.neural.similar(a, b, options?) // Semantic similarity (0-1)
brain.neural.clusters(input?) // Auto-clustering
brain.neural.hierarchy(id) // Semantic hierarchy tree
brain.neural.neighbors(id, options?) // K-nearest neighbors
// === ANALYSIS ===
brain.neural.outliers(threshold?) // Outlier detection
brain.neural.semanticPath(from, to) // Find semantic path
// === VISUALIZATION ===
brain.neural.visualize(options?) // Export for visualization
// options: {
// maxNodes: 100,
// dimensions: 2 | 3,
// algorithm: 'force' | 'hierarchical' | 'radial',
// includeEdges: true
// }
// Returns: {
// format: 'd3' | 'cytoscape' | 'graphml',
// nodes: [...], edges: [...], layout: {...}
// }
// === PERFORMANCE METHODS ===
brain.neural.clusterFast(options?) // O(n) HNSW clustering
brain.neural.clusterLarge(options?) // Million+ items
brain.neural.clusterStream(options?) // Progressive streaming
```
## 📥 IMPORT & EXPORT
### Neural Import
```typescript
// === SMART IMPORT (from cortex) ===
brain.neuralImport(filePath, options?) // AI-powered import
// options: {
// confidenceThreshold: 0.7,
// autoApply: false,
// enableWeights: true,
// previewOnly: false,
// skipDuplicates: true
// }
// Returns: {
// detectedEntities: [...],
// detectedRelationships: [...],
// confidence: 0.85,
// insights: [...],
// preview: "..."
// }
```
### Standard Import/Export
```typescript
import(data, format) // Standard import
importSparseData(data) // Sparse format import
backup() // Create full backup
restore(backup) // Restore from backup
```
## 🎯 VERB SCORING
```typescript
// === INTELLIGENT SCORING ===
provideFeedbackForVerbScoring(feedback) // Train model
getVerbScoringStats() // Get statistics
exportVerbScoringLearningData() // Export training
importVerbScoringLearningData(data) // Import training
```
## 🔄 SYNC & DISTRIBUTION
### Remote Operations
```typescript
// === REMOTE CONNECTION ===
connectToRemoteServer(url, options?) // Connect to remote
disconnectFromRemoteServer() // Disconnect
isConnectedToRemoteServer() // Check status
// === SEARCH MODES ===
searchLocal(query, k?) // Local only
searchRemote(query, k?) // Remote only
searchCombined(query, k?) // Both sources
```
### Real-time Sync
```typescript
enableRealtimeUpdates(config) // Enable sync
disableRealtimeUpdates() // Disable sync
getRealtimeUpdateConfig() // Get config
checkForUpdatesNow() // Manual sync
```
## 📊 MONITORING & STATS
```typescript
// === STATISTICS ===
size() // Total noun count
getStatistics(options?) // Full statistics
getServiceStatistics(service) // Per-service stats
listServices() // List all services
flushStatistics() // Persist stats
// === HEALTH & CACHE ===
getHealthStatus() // System health
status() // Full status report
getCacheStats() // Cache statistics
clearCache() // Clear all caches
```
## ⚙️ CONFIGURATION
### Operational Modes
```typescript
// === MODE CONTROL ===
isReadOnly() / setReadOnly(bool) // Read-only mode
isWriteOnly() / setWriteOnly(bool) // Write-only mode
isFrozen() / setFrozen(bool) // Freeze all changes
```
### Augmentations
```typescript
// === AUGMENTATION SYSTEM ===
augmentations.register(augmentation) // Add augmentation
augmentations.list() // List all
augmentations.get(name) // Get by name
```
## 💾 DATA MANAGEMENT
```typescript
// === CLEAR OPERATIONS ===
clear(options?) // Clear all data
clearNouns(options?) // Clear nouns only
clearVerbs(options?) // Clear verbs only
// === INDEX MANAGEMENT ===
rebuildMetadataIndex() // Rebuild index
getFilterFields() // Get indexed fields
getFilterValues(field) // Get unique values
```
## 🧬 EMBEDDINGS & SIMILARITY
```typescript
embed(text) // Generate embedding
calculateSimilarity(a, b, metric?) // Calculate similarity
// metric: 'cosine' | 'euclidean' | 'manhattan'
```
## 🔒 SECURITY
```typescript
encryptData(data) // Encrypt data
decryptData(data) // Decrypt data
```
## 🎲 UTILITIES
```typescript
generateRandomGraph(nodes, edges) // Generate test data
getAvailableFieldNames() // Get field names
getStandardFieldMappings() // Get field mappings
```
## 🚀 LIFECYCLE
```typescript
// === INITIALIZATION ===
const brain = new BrainyData(config?) // Create instance
await brain.init() // Initialize (REQUIRED!)
await brain.shutDown() // Graceful shutdown
await brain.cleanup() // Clean resources
// === STATIC METHODS ===
BrainyData.preloadModel(options?) // Preload ML model
BrainyData.warmup(options?) // Warmup system
```
### Configuration Options
```typescript
new BrainyData({
// Storage
storage: 'auto' | 'memory' | 'filesystem' | 's3' | {
adapter: 'custom',
// ... storage options
},
// Vector configuration
dimensions: 384, // Vector dimensions
similarity: 'cosine', // Similarity metric
// Performance
cache: true, // Enable caching
index: true, // Enable indexing
metrics: true, // Enable metrics
// Advanced
augmentations: [...], // Custom augmentations
verbose: false // Logging verbosity
})
```
## 📐 READ-ONLY PROPERTIES
```typescript
brain.dimensions // Vector dimensions
brain.maxConnections // HNSW max connections
brain.efConstruction // HNSW ef construction
brain.initialized // Is initialized?
```
---
## ✅ KEY POINTS:
1. **Brainy Operators** - NOT MongoDB style ($gt, $lt)
2. **Neural API** - Complete with visualization export
3. **Simple Search** - Just `search()` and `find()`
4. **Triple Intelligence** - Vector + Graph + Field in `find()`
5. **Auto-embedding** - `addNoun()` accepts text directly
6. **Unified Methods** - `getNouns()` handles all plural queries
7. **Clean Architecture** - Augmentation system for extensibility
## ⚠️ IMPORTANT NOTES:
- **NO MongoDB operators** - We use `greaterThan` not `$gt` (legal reasons)
- **Neural API is via brain.neural** - All clustering/viz methods available
- **search() is convenience** - Just wraps `find({like: query})`
- **find() is powerful** - Full Triple Intelligence capabilities
- **One import method** - `neuralImport()` auto-detects format

227
docs/api-design/COMPLETE-PUBLIC-API.md Normal file
View file

@ -0,0 +1,227 @@
# 🧠 Brainy 2.0 Complete Public API
> **ONE METHOD, ONE PURPOSE** - No duplicates, no aliases, just clean specific methods.
## 📚 NOUNS (Vectors with Metadata)
### Single Operations
```typescript
addNoun(vector, metadata?) // Add one noun
getNoun(id) // Get one noun
updateNoun(id, vector?, metadata?) // Update noun
updateNounMetadata(id, metadata) // Update metadata only
getNounMetadata(id) // Get metadata only
deleteNoun(id) // Delete one noun
hasNoun(id) // Check if exists
getNounWithVerbs(id) // Get with relationships
```
### Batch Operations
```typescript
addNouns(items[]) // Add multiple nouns
getNounsByIds(ids[]) // Get multiple by IDs
deleteNouns(ids[]) // Delete multiple nouns
queryNouns(options) // Query with filters/pagination
```
## 🔗 VERBS (Relationships)
### Single Operations
```typescript
addVerb(source, target, type, metadata?) // Add relationship
getVerb(id) // Get one verb
deleteVerb(id) // Delete one verb
```
### Batch Operations
```typescript
addVerbs(verbs[]) // Add multiple verbs
getVerbs(filter?) // Get filtered verbs
deleteVerbs(ids[]) // Delete multiple verbs
getVerbsBySource(sourceId) // Get outgoing relationships
getVerbsByTarget(targetId) // Get incoming relationships
getVerbsByType(type) // Get by relationship type
```
## 🔍 SEARCH
### Vector Search
```typescript
search(query, k?, options?) // Primary vector search
searchText(text, k?, options?) // Natural language search
findSimilar(id, k?, options?) // Find similar to noun
searchWithCursor(query, cursor) // Paginated search
```
### Advanced Search
```typescript
find(query) // Triple Intelligence 🧠
searchByNounTypes(types[], query) // Filter by noun types
searchWithinItems(query, ids[], k?) // Search within specific nouns
searchVerbs(query) // Search relationships
searchNounsByVerbs(conditions) // Graph-based noun search
searchByStandardField(field, value) // Field-based search
```
### Distributed Search
```typescript
searchLocal(query) // Local only
searchRemote(query) // Remote only
searchCombined(query) // Both sources
```
## 📊 GRAPH OPERATIONS
```typescript
getConnections(id, depth?) // Get all connections
getVerbsBySource(sourceId) // Outgoing edges
getVerbsByTarget(targetId) // Incoming edges
getVerbsByType(type) // Filter by type
```
## 🎯 PERFORMANCE & STATS
### Cache
```typescript
getCacheStats() // Cache statistics
clearCache() // Clear search cache
```
### Statistics
```typescript
size() // Total noun count
getStatistics(options?) // Complete statistics
getServiceStatistics(service) // Per-service stats
listServices() // List all services
flushStatistics() // Flush to storage
```
### Health & Status
```typescript
getHealthStatus() // System health
status() // Full status report
```
## 🔧 CONFIGURATION & MODES
### Operational Modes
```typescript
isReadOnly() / setReadOnly(bool) // Read-only mode
isWriteOnly() / setWriteOnly(bool) // Write-only mode
isFrozen() / setFrozen(bool) // Freeze modifications
```
### Real-time Updates
```typescript
enableRealtimeUpdates(config) // Enable live sync
disableRealtimeUpdates() // Disable sync
getRealtimeUpdateConfig() // Get config
checkForUpdatesNow() // Manual sync
```
### Remote Connection
```typescript
connectToRemoteServer(url, options?) // Connect remote
disconnectFromRemoteServer() // Disconnect
isConnectedToRemoteServer() // Check connection
```
## 🧠 INTELLIGENCE FEATURES
### Verb Scoring
```typescript
provideFeedbackForVerbScoring(feedback) // Train scoring
getVerbScoringStats() // Get statistics
exportVerbScoringLearningData() // Export training
importVerbScoringLearningData(data) // Import training
```
### Embeddings
```typescript
embed(text) // Generate embedding
calculateSimilarity(a, b) // Compare vectors
```
## 💾 DATA MANAGEMENT
### Clear Operations
```typescript
clear(options?) // Clear all data
clearNouns(options?) // Clear all nouns
clearVerbs(options?) // Clear all verbs
```
### Import/Export
```typescript
backup() // Create backup
restore(backup) // Restore backup
import(data, format) // Import data
importSparseData(data) // Import sparse
```
### Index Management
```typescript
rebuildMetadataIndex() // Rebuild index
getFilterFields() // Get indexed fields
getFilterValues(field) // Get field values
```
## 🔒 SECURITY
```typescript
encryptData(data) // Encrypt
decryptData(data) // Decrypt
```
## 🎲 UTILITIES
```typescript
generateRandomGraph(nodes, edges) // Generate test data
getAvailableFieldNames() // Available fields
getStandardFieldMappings() // Field mappings
```
## 🚀 LIFECYCLE
### Instance Methods
```typescript
init() // Initialize (required!)
shutDown() // Graceful shutdown
cleanup() // Clean resources
```
### Static Methods
```typescript
BrainyData.preloadModel(options?) // Preload ML model
BrainyData.warmup(options?) // Warmup system
```
## 📐 PROPERTIES
```typescript
dimensions // Vector dimensions (readonly)
maxConnections // HNSW max connections (readonly)
efConstruction // HNSW ef construction (readonly)
initialized // Is initialized (readonly)
```
## ❌ REMOVED/PRIVATE IN 2.0
These methods are now **private** - use the new specific methods above:
- ~~add()~~ → Use `addNoun()`
- ~~get()~~ → Use `getNoun()`
- ~~delete()~~ → Use `deleteNoun()`
- ~~update()~~ → Use `updateNoun()`
- ~~relate()~~ → Use `addVerb()`
- ~~connect()~~ → Use `addVerb()`
- ~~has()~~ → Use `hasNoun()`
- ~~exists()~~ → Use `hasNoun()`
- ~~getMetadata()~~ → Use `getNounMetadata()`
- ~~updateMetadata()~~ → Use `updateNounMetadata()`
- ~~clearAll()~~ → Use `clear()`
- ~~addItem()~~ → Removed
- ~~addToBoth()~~ → Removed
- ~~addBatch()~~ → Use `addNouns()`
- ~~getBatch()~~ → Use `getNounsByIds()`
- ~~getNouns()~~ with IDs → Use `getNounsByIds()`
- ~~getNouns()~~ with filters → Use `queryNouns()`

185
docs/api-design/CRITICAL-API-AUDIT.md Normal file
View file

@ -0,0 +1,185 @@
# 🚨 CRITICAL API AUDIT - What We Changed & Lost
## 📅 Timeline of Changes (Friday-Saturday)
### Friday Changes:
1. Started unifying augmentation system to single BrainyAugmentation interface
2. Made old methods (add, get, delete) private
3. Created new specific methods (addNoun, getNoun, deleteNoun)
4. Started removing backward compatibility
### Saturday Changes:
1. Combined getNounsByIds and queryNouns into single getNouns method
2. Simplified search API (may have oversimplified!)
3. Accidentally introduced MongoDB operators ($gt, $in, etc.)
4. May have removed critical features while "simplifying"
## ❌ CRITICAL MISTAKES WE MADE:
### 1. **MongoDB Operators (LEGAL RISK!)**
```typescript
// ❌ WRONG - We accidentally added:
where: { field: {$gt: value} }
// ✅ CORRECT - Should be:
where: { field: {greaterThan: value} }
```
### 2. **Lost Neural API Methods**
```typescript
// ❌ MISSING - These were removed or not properly exposed:
brain.neural.similar(a, b)
brain.neural.clusters()
brain.neural.hierarchy(id)
brain.neural.neighbors(id)
brain.neural.outliers()
brain.neural.semanticPath(from, to)
brain.neural.visualize() // Critical for external tools!
brain.neural.clusterFast() // O(n) performance
brain.neural.clusterLarge() // Million-item support
```
### 3. **Lost Import Capabilities**
```typescript
// ❌ WRONG - We made it too complex:
neuralImport.csv()
neuralImport.json()
neuralImport.text()
// ✅ CORRECT - Should be ONE simple method:
brain.neuralImport(data, options?) // Auto-detects format!
```
### 4. **Lost Clustering for Visualization**
The visualization data format for external tools (D3, Cytoscape, GraphML) is missing!
```typescript
// ❌ MISSING - Critical for external visualization:
{
format: 'd3' | 'cytoscape' | 'graphml',
nodes: [...],
edges: [...],
layout: {...}
}
```
### 5. **Oversimplified Search**
```typescript
// ❌ REMOVED too many methods:
searchByNounTypes()
searchWithinItems()
searchByStandardField()
searchVerbs()
searchNounsByVerbs()
// ✅ BUT this is actually OK if find() handles everything!
// Just need to ensure find() is complete
```
## 🔍 COMPARISON: Backup vs Current
### Methods in BACKUP but NOT in current:
```typescript
// From backup's brainyData.ts:
brain.neural // ❌ Not properly exposed
brain.visualize() // ❌ Missing
brain.clusters() // ❌ Missing
brain.similar() // ❌ Missing
brain.neuralImport() // ❌ Wrong implementation
// Operators in backup:
greaterThan, lessThan, equals // ❌ Replaced with $gt, $lt, $eq
oneOf, contains, matches // ❌ Replaced with $in, $contains, $regex
```
### Methods we ADDED (some good, some questionable):
```typescript
// New specific methods (GOOD ✅):
addNoun(), getNoun(), deleteNoun()
// Unified method (GOOD if complete ✅):
getNouns(idsOrOptions)
// But lost flexibility (BAD ❌):
- Can't do complex queries easily
- Lost specific search methods
```
## 📊 Feature Comparison Table
| Feature | Backup | Current | Status |
|---------|---------|---------|---------|
| **Operators** | greaterThan, lessThan | $gt, $lt | ❌ WRONG |
| **Neural API** | Complete (10+ methods) | Missing/Hidden | ❌ BROKEN |
| **Clustering** | Full support | Missing | ❌ LOST |
| **Visualization** | D3/Cytoscape export | None | ❌ LOST |
| **Import** | Simple neuralImport() | Complex multi-method | ❌ WRONG |
| **Search** | Multiple specific | Simplified to 2 | ⚠️ OK if complete |
| **Verb Scoring** | Full intelligence | Partial | ⚠️ CHECK |
| **Synapses** | External connectors | Unknown | ⚠️ CHECK |
| **Conduits** | Brainy-to-Brainy | Partial | ⚠️ CHECK |
## 🔧 WHAT WE NEED TO FIX IMMEDIATELY:
### Priority 1 (CRITICAL):
1. **Replace ALL MongoDB operators with Brainy operators**
- This is a legal requirement!
- greaterThan not $gt
2. **Restore Neural API completely**
- brain.neural must have all methods
- Visualization MUST work for external tools
3. **Fix neuralImport to be simple**
- ONE method that auto-detects
- Not multiple complex methods
### Priority 2 (IMPORTANT):
4. **Restore clustering APIs**
- For visualization tools
- For analysis
5. **Verify Triple Intelligence is complete**
- find() must handle everything
- All operators must work
6. **Check augmentation system**
- Synapses (external)
- Conduits (internal)
## 🎯 RECOVERY PLAN:
### Step 1: Fix Operators (LEGAL REQUIREMENT)
- [ ] Find all $gt, $lt, $in, $regex references
- [ ] Replace with greaterThan, lessThan, oneOf, matches
- [ ] Update all documentation
### Step 2: Restore Neural API
- [ ] Ensure brain.neural is properly exposed
- [ ] All methods available: similar, clusters, hierarchy, etc.
- [ ] Visualization must return proper format
### Step 3: Fix Import
- [ ] Single neuralImport() method
- [ ] Auto-detection of format
- [ ] Simple options
### Step 4: Verify Nothing Lost
- [ ] Compare method-by-method with backup
- [ ] Test all features
- [ ] Update documentation
## 💡 LESSONS LEARNED:
1. **Don't oversimplify** - We lost important features
2. **Check legal requirements** - MongoDB operators were avoided for a reason
3. **Preserve all features** - Even if reorganizing
4. **Test against backup** - Always compare functionality
5. **Document changes** - Track what and why
## 🚀 NEXT ACTIONS:
1. STOP all other work
2. Fix operators IMMEDIATELY (legal risk)
3. Restore neural API completely
4. Test everything works
5. Document the final API properly

210
docs/api-design/FINAL-2.0-PUBLIC-API.md Normal file
View file

@ -0,0 +1,210 @@
# 🧠 Brainy 2.0 Final Public API
> **Clean, Specific, Beautiful** - Every method has ONE clear purpose.
## 📚 NOUNS (Vectors with Metadata)
```typescript
// Single Operations
addNoun(vector, metadata?) // Add one noun
getNoun(id) // Get one noun by ID
updateNoun(id, vector?, metadata?) // Update entire noun
updateNounMetadata(id, metadata) // Update metadata only
getNounMetadata(id) // Get metadata only
getNounWithVerbs(id) // Get noun with all relationships
deleteNoun(id) // Delete one noun
hasNoun(id) // Check if noun exists
// Batch Operations
addNouns(items[]) // Add multiple nouns
getNouns(idsOrOptions) // Get multiple nouns (by IDs or query)
// getNouns(['id1', 'id2']) // Get by specific IDs
// getNouns({ filter: {...} }) // Get with filters
// getNouns({ limit: 10, offset: 20 }) // Get with pagination
deleteNouns(ids[]) // Delete multiple nouns
```
## 🔗 VERBS (Relationships)
```typescript
// Single Operations
addVerb(source, target, type, metadata?) // Create relationship
getVerb(id) // Get one verb by ID
deleteVerb(id) // Delete one verb
// Batch Operations
addVerbs(verbs[]) // Add multiple relationships
getVerbs(filter?) // Get filtered verbs
getVerbsBySource(sourceId) // Get outgoing relationships
getVerbsByTarget(targetId) // Get incoming relationships
getVerbsByType(type) // Get by relationship type
deleteVerbs(ids[]) // Delete multiple verbs
```
## 🔍 SEARCH
```typescript
// Core Search
search(query, k?, options?) // Primary vector search
searchText(text, k?, options?) // Natural language search
find(query) // Triple Intelligence (Vector+Graph+Field) 🧠
findSimilar(id, k?, options?) // Find similar to existing noun
// Advanced Search
searchByNounTypes(types[], query, k?) // Filter by noun types
searchWithinItems(query, ids[], k?) // Search within specific nouns
searchWithCursor(query, cursor) // Paginated search
searchByStandardField(field, value, k?) // Field-based search
// Graph Search
searchVerbs(query, options?) // Search relationships
searchNounsByVerbs(conditions) // Find nouns by relationships
// Distributed Search
searchLocal(query, k?) // Search local instance only
searchRemote(query, k?) // Search remote instance only
searchCombined(query, k?) // Search both local and remote
```
## 📊 METADATA & FILTERING
```typescript
getFilterFields() // Get all indexed fields
getFilterValues(field) // Get unique values for a field
getAvailableFieldNames() // Get available field names
getStandardFieldMappings() // Get standard field mappings
```
## 🚀 PERFORMANCE & MONITORING
```typescript
// Cache
getCacheStats() // Get cache statistics
clearCache() // Clear search cache
// Statistics
size() // Total noun count
getStatistics(options?) // Comprehensive statistics
getServiceStatistics(service) // Per-service statistics
listServices() // List all services
flushStatistics() // Persist statistics to storage
// Health
getHealthStatus() // System health check
status() // Full status report
```
## ⚙️ CONFIGURATION
```typescript
// Operational Modes
isReadOnly() / setReadOnly(bool) // Read-only mode
isWriteOnly() / setWriteOnly(bool) // Write-only mode
isFrozen() / setFrozen(bool) // Freeze all modifications
// Real-time Sync
enableRealtimeUpdates(config) // Enable live synchronization
disableRealtimeUpdates() // Disable synchronization
getRealtimeUpdateConfig() // Get current config
checkForUpdatesNow() // Manual sync trigger
// Remote Connection
connectToRemoteServer(url, options?) // Connect to remote instance
disconnectFromRemoteServer() // Disconnect from remote
isConnectedToRemoteServer() // Check connection status
```
## 🧠 INTELLIGENCE
```typescript
// Verb Scoring
provideFeedbackForVerbScoring(feedback) // Train relationship scoring
getVerbScoringStats() // Get scoring statistics
exportVerbScoringLearningData() // Export training data
importVerbScoringLearningData(data) // Import training data
// Embeddings
embed(text) // Generate embedding vector
calculateSimilarity(a, b, metric?) // Calculate vector similarity
```
## 💾 DATA MANAGEMENT
```typescript
// Clear Operations
clear(options?) // Clear all data
clearNouns(options?) // Clear all nouns only
clearVerbs(options?) // Clear all verbs only
// Backup & Restore
backup() // Create full backup
restore(backup) // Restore from backup
// Import/Export
import(data, format) // Import external data
importSparseData(data) // Import sparse format
// Index Management
rebuildMetadataIndex() // Rebuild metadata index
```
## 🔒 SECURITY
```typescript
encryptData(data) // Encrypt data
decryptData(data) // Decrypt data
```
## 🎲 UTILITIES
```typescript
generateRandomGraph(nodes, edges) // Generate test graph data
```
## 🚀 LIFECYCLE
```typescript
// Instance Methods
new BrainyData(config?) // Create instance
init() // Initialize (REQUIRED!)
shutDown() // Graceful shutdown
cleanup() // Clean up resources
// Static Methods
BrainyData.preloadModel(options?) // Preload ML model
BrainyData.warmup(options?) // Warmup system
```
## 📐 PROPERTIES (Read-only)
```typescript
dimensions // Vector dimensions
maxConnections // HNSW max connections
efConstruction // HNSW ef construction
initialized // Is initialized?
```
---
## 📝 Key Changes in 2.0
### ✅ Simplified & Unified
- `getNouns()` now handles ALL plural queries (by IDs, filters, or pagination)
- No more `getNounsByIds()`, `queryNouns()`, `getBatch()` - just `getNouns()`
- Clear singular vs plural: `getNoun()` for one, `getNouns()` for many
### ✅ Specific Naming
- Always specify noun/verb: `addNoun()` not `add()`
- No aliases or duplicates
- One method, one purpose
### ✅ Private Legacy Methods
These are now private (use new methods above):
- `add()`, `get()`, `delete()`, `update()`
- `relate()`, `connect()`, `has()`, `exists()`
- `getMetadata()`, `updateMetadata()`
- `addItem()`, `addToBoth()`, `addBatch()`, `getBatch()`
### ✅ Triple Intelligence
- New `find()` method unifies Vector + Graph + Field search
- Most powerful search capability in one simple method