docs: consolidate and archive redundant documentation
- Archived 13 API design iterations to docs/api-design-archive/ - Consolidated augmentation docs to docs/augmentations-archive/ - Maintained ONE definitive API doc at docs/api/README.md - Cleaned up documentation structure for 2.0 release - Preserved all historical documents for reference
This commit is contained in:
parent
ef8f35ec2a
commit
994276f09f
35 changed files with 444 additions and 239 deletions
95
docs/api-design-archive/API-CRITICAL-FIXES.md
Normal file
95
docs/api-design-archive/API-CRITICAL-FIXES.md
Normal 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-archive/API-QUICK-REFERENCE.md
Normal file
62
docs/api-design-archive/API-QUICK-REFERENCE.md
Normal 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-archive/API-REFERENCE.md
Normal file
277
docs/api-design-archive/API-REFERENCE.md
Normal 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 + Metadata 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' }}) // Metadata 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-archive/BRAINY-2.0-COMPLETE-API.md
Normal file
220
docs/api-design-archive/BRAINY-2.0-COMPLETE-API.md
Normal 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+Metadata) 🧠
|
||||
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?) // Metadata-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 + Metadata 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-archive/BRAINY-2.0-CORRECT-API.md
Normal file
268
docs/api-design-archive/BRAINY-2.0-CORRECT-API.md
Normal 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'},
|
||||
|
||||
// Metadata 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 + Metadata
|
||||
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-archive/BRAINY-2.0-DETAILED-API.md
Normal file
376
docs/api-design-archive/BRAINY-2.0-DETAILED-API.md
Normal 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
|
||||
|
||||
// Metadata 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-archive/BRAINY-2.0-FINAL-API.md
Normal file
260
docs/api-design-archive/BRAINY-2.0-FINAL-API.md
Normal 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 + Metadata 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
|
||||
243
docs/api-design-archive/BRAINY-2.0-FINAL-CORRECT-API.md
Normal file
243
docs/api-design-archive/BRAINY-2.0-FINAL-CORRECT-API.md
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
# 🧠 Brainy 2.0 Final API Reference
|
||||
|
||||
> **The definitive API - Clean, Correct, Complete**
|
||||
|
||||
## ✅ KEY CORRECTIONS FROM REVIEW:
|
||||
1. **Brainy Operators (NOT MongoDB)** - `greaterThan` not `$gt`
|
||||
2. **Neural API is complete** - All methods available via `brain.neural`
|
||||
3. **Code is correct** - Implementation uses right operators, just docs were wrong
|
||||
4. **Nothing lost** - All features still present, just reorganized
|
||||
|
||||
---
|
||||
|
||||
## 📚 CORE DATA OPERATIONS
|
||||
|
||||
### Nouns
|
||||
```typescript
|
||||
// Single
|
||||
addNoun(textOrVector, metadata?) // Auto-embeds text!
|
||||
getNoun(id)
|
||||
updateNoun(id, textOrVector?, metadata?)
|
||||
deleteNoun(id)
|
||||
hasNoun(id)
|
||||
|
||||
// Metadata
|
||||
getNounMetadata(id)
|
||||
updateNounMetadata(id, metadata)
|
||||
getNounWithVerbs(id)
|
||||
|
||||
// Batch
|
||||
addNouns(items[])
|
||||
getNouns(idsOrOptions) // Unified: IDs, filter, or pagination
|
||||
deleteNouns(ids[])
|
||||
```
|
||||
|
||||
### Verbs
|
||||
```typescript
|
||||
addVerb(source, target, type, metadata?)
|
||||
getVerb(id)
|
||||
deleteVerb(id)
|
||||
getVerbsBySource(sourceId)
|
||||
getVerbsByTarget(targetId)
|
||||
getVerbsByType(type)
|
||||
```
|
||||
|
||||
## 🔍 SEARCH
|
||||
|
||||
Just TWO methods - simple and powerful:
|
||||
|
||||
```typescript
|
||||
search(query, k?) // Convenience: same as find({like: query, limit: k})
|
||||
find(query) // TRIPLE INTELLIGENCE: Vector + Graph + Metadata
|
||||
```
|
||||
|
||||
### Find Query (with CORRECT Brainy Operators):
|
||||
```typescript
|
||||
find({
|
||||
// Vector
|
||||
like: 'text' | vector | {id: 'noun-id'},
|
||||
|
||||
// Fields (BRAINY operators, NOT MongoDB!)
|
||||
where: {
|
||||
field: value, // Direct equality
|
||||
field: {
|
||||
equals: value,
|
||||
greaterThan: value, // NOT $gt
|
||||
lessThan: value, // NOT $lt
|
||||
greaterEqual: value,
|
||||
lessEqual: value,
|
||||
oneOf: [values], // NOT $in
|
||||
notOneOf: [values], // NOT $nin
|
||||
contains: value,
|
||||
startsWith: value,
|
||||
endsWith: value,
|
||||
matches: pattern, // NOT $regex
|
||||
between: [min, max]
|
||||
}
|
||||
},
|
||||
|
||||
// Graph
|
||||
connected: {
|
||||
to: 'id',
|
||||
from: 'id',
|
||||
via: 'type',
|
||||
depth: 2
|
||||
},
|
||||
|
||||
// Control
|
||||
limit: 10,
|
||||
offset: 0,
|
||||
explain: true
|
||||
})
|
||||
```
|
||||
|
||||
## 🧠 NEURAL API
|
||||
|
||||
Complete and available via `brain.neural`:
|
||||
|
||||
```typescript
|
||||
brain.neural.similar(a, b) // Similarity 0-1
|
||||
brain.neural.clusters() // Auto-clustering
|
||||
brain.neural.hierarchy(id) // Semantic tree
|
||||
brain.neural.neighbors(id, k?) // K-nearest
|
||||
brain.neural.outliers(threshold?) // Outlier detection
|
||||
brain.neural.semanticPath(from, to) // Path finding
|
||||
brain.neural.visualize(options?) // For D3/Cytoscape/GraphML
|
||||
|
||||
// Performance
|
||||
brain.neural.clusterFast() // O(n) HNSW
|
||||
brain.neural.clusterLarge() // Million+ items
|
||||
brain.neural.clusterStream() // Progressive
|
||||
```
|
||||
|
||||
### Visualization Format:
|
||||
```typescript
|
||||
brain.neural.visualize({
|
||||
maxNodes: 100,
|
||||
dimensions: 2,
|
||||
algorithm: 'force',
|
||||
includeEdges: true
|
||||
})
|
||||
// Returns: {
|
||||
// format: 'd3' | 'cytoscape' | 'graphml',
|
||||
// nodes: [...], edges: [...], layout: {...}
|
||||
// }
|
||||
```
|
||||
|
||||
## 📥 IMPORT
|
||||
|
||||
Simple, AI-powered:
|
||||
|
||||
```typescript
|
||||
brain.neuralImport(data, options?) // Auto-detects format!
|
||||
// Options: {
|
||||
// confidenceThreshold: 0.7,
|
||||
// autoApply: false,
|
||||
// skipDuplicates: true
|
||||
// }
|
||||
```
|
||||
|
||||
## 🎯 INTELLIGENCE
|
||||
|
||||
```typescript
|
||||
// Verb Scoring
|
||||
provideFeedbackForVerbScoring(feedback)
|
||||
getVerbScoringStats()
|
||||
exportVerbScoringLearningData()
|
||||
importVerbScoringLearningData(data)
|
||||
|
||||
// Embeddings
|
||||
embed(text) // Generate vector
|
||||
calculateSimilarity(a, b, metric?) // Compare
|
||||
```
|
||||
|
||||
## 🔄 SYNC
|
||||
|
||||
```typescript
|
||||
// Remote
|
||||
connectToRemoteServer(url)
|
||||
disconnectFromRemoteServer()
|
||||
isConnectedToRemoteServer()
|
||||
|
||||
// Real-time
|
||||
enableRealtimeUpdates(config)
|
||||
disableRealtimeUpdates()
|
||||
checkForUpdatesNow()
|
||||
|
||||
// Search modes
|
||||
searchLocal(query, k?)
|
||||
searchRemote(query, k?)
|
||||
searchCombined(query, k?)
|
||||
```
|
||||
|
||||
## 📊 MONITORING
|
||||
|
||||
```typescript
|
||||
size() // Total nouns
|
||||
getStatistics() // Full stats
|
||||
getHealthStatus() // Health
|
||||
getCacheStats() // Cache
|
||||
clearCache() // Clear
|
||||
```
|
||||
|
||||
## ⚙️ CONFIGURATION
|
||||
|
||||
```typescript
|
||||
// Modes
|
||||
setReadOnly(bool)
|
||||
setWriteOnly(bool)
|
||||
setFrozen(bool)
|
||||
|
||||
// Augmentations
|
||||
augmentations.register(aug)
|
||||
augmentations.list()
|
||||
augmentations.get(name)
|
||||
```
|
||||
|
||||
## 💾 DATA MANAGEMENT
|
||||
|
||||
```typescript
|
||||
clear(options?) // Clear all
|
||||
clearNouns() // Nouns only
|
||||
clearVerbs() // Verbs only
|
||||
backup() // Create backup
|
||||
restore(backup) // Restore
|
||||
rebuildMetadataIndex() // Rebuild index
|
||||
```
|
||||
|
||||
## 🚀 LIFECYCLE
|
||||
|
||||
```typescript
|
||||
const brain = new BrainyData({
|
||||
storage: 'auto', // auto | memory | filesystem | s3
|
||||
dimensions: 384,
|
||||
cache: true,
|
||||
index: true
|
||||
})
|
||||
|
||||
await brain.init() // REQUIRED!
|
||||
await brain.shutdown() // Cleanup
|
||||
|
||||
// Static
|
||||
BrainyData.preloadModel() // Preload
|
||||
BrainyData.warmup() // Warmup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✨ What Makes Brainy 2.0 Special:
|
||||
|
||||
1. **Zero-Config** - Works instantly, no setup
|
||||
2. **Auto-Embedding** - Text automatically becomes vectors
|
||||
3. **Triple Intelligence** - Vector + Graph + Metadata combined
|
||||
4. **Brainy Operators** - Clean, legal, no MongoDB style
|
||||
5. **Complete Neural API** - All clustering/viz features
|
||||
6. **Simple Import** - One method, auto-detects everything
|
||||
7. **Clean Architecture** - Augmentations for extensibility
|
||||
|
||||
## 🎯 Remember:
|
||||
- **NO $operators** - We use readable names (legal requirement)
|
||||
- **search() is simple** - Just wraps find({like: query})
|
||||
- **find() is powerful** - Full Triple Intelligence
|
||||
- **neural API complete** - All methods via brain.neural
|
||||
- **Everything included** - No premium features, all MIT
|
||||
149
docs/api-design-archive/BRAINY-2.0-SIMPLIFIED-API.md
Normal file
149
docs/api-design-archive/BRAINY-2.0-SIMPLIFIED-API.md
Normal 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' })
|
||||
|
||||
// Metadata 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' }, // Metadata 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 metadata 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 }`
|
||||
- Metadata 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-archive/BRAINY-2.0-UNIFIED-API.md
Normal file
343
docs/api-design-archive/BRAINY-2.0-UNIFIED-API.md
Normal 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 + Metadata 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 + Metadata 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-archive/COMPLETE-PUBLIC-API.md
Normal file
227
docs/api-design-archive/COMPLETE-PUBLIC-API.md
Normal 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) // Metadata-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-archive/CRITICAL-API-AUDIT.md
Normal file
185
docs/api-design-archive/CRITICAL-API-AUDIT.md
Normal 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-archive/FINAL-2.0-PUBLIC-API.md
Normal file
210
docs/api-design-archive/FINAL-2.0-PUBLIC-API.md
Normal 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+Metadata) 🧠
|
||||
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?) // Metadata-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 + Metadata search
|
||||
- Most powerful search capability in one simple method
|
||||
28
docs/api-design-archive/README.md
Normal file
28
docs/api-design-archive/README.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# API Design Archive
|
||||
|
||||
This directory contains historical API design documents from the Brainy 2.0 development process.
|
||||
|
||||
## Purpose
|
||||
These documents represent the iterative refinement of the Brainy 2.0 API during development. They are preserved here for historical reference and to document the design decisions made along the way.
|
||||
|
||||
## Current API Documentation
|
||||
The definitive API documentation is now located at:
|
||||
- **`/docs/api/README.md`** - The ONE official API reference
|
||||
|
||||
## Archived Documents
|
||||
These documents show the evolution of the API design:
|
||||
- Various iterations of API structure
|
||||
- Exploration of different naming conventions
|
||||
- Refinement of the Triple Intelligence concept
|
||||
- Transition from MongoDB operators to Brainy operators
|
||||
- Evolution of the Neural API
|
||||
|
||||
## Key Decisions Made
|
||||
1. **Terminology**: Vector + Graph + Metadata (not Field)
|
||||
2. **Operators**: Brainy operators (greaterThan, lessThan) not MongoDB ($gt, $lt)
|
||||
3. **Methods**: Specific noun/verb naming (addNoun, getNoun)
|
||||
4. **Unification**: Single getNouns() method instead of multiple variants
|
||||
5. **Neural API**: Complete clustering and visualization features
|
||||
|
||||
## Note
|
||||
These documents are archived, not deleted, to preserve the development history and rationale behind API decisions.
|
||||
Loading…
Add table
Add a link
Reference in a new issue