brainy/docs/api-design/BRAINY-2.0-COMPLETE-API.md

🧠 Brainy 2.0 Complete Public API

Clean, Specific, Beautiful - Every method has ONE clear purpose.

📚 NOUNS (Vectors with Metadata)

// 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)

// 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

// Core Search
search(query, k?, options?)                 // Primary vector search
searchText(text, k?, options?)              // Natural language search
find(query)                                 // Triple Intelligence (Vector+Graph+Field) 🧠
findSimilar(id, k?, options?)              // Find similar to existing noun

// Advanced Search
searchByNounTypes(types[], query, k?)      // Filter by noun types
searchWithinItems(query, ids[], k?)        // Search within specific nouns
searchWithCursor(query, cursor)            // Paginated search
searchByStandardField(field, value, k?)    // Field-based search

// Graph Search
searchVerbs(query, options?)               // Search relationships
searchNounsByVerbs(conditions)             // Find nouns by relationships

// Distributed Search
searchLocal(query, k?)                     // Search local instance only
searchRemote(query, k?)                    // Search remote instance only
searchCombined(query, k?)                  // Search both local and remote

📊 METADATA & FILTERING

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

// 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

// 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

// 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

// 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

encryptData(data)                         // Encrypt data
decryptData(data)                         // Decrypt data

🎲 UTILITIES

generateRandomGraph(nodes, edges)         // Generate test graph data

🚀 LIFECYCLE

// 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)

dimensions                                // Vector dimensions
maxConnections                           // HNSW max connections
efConstruction                           // HNSW ef construction
initialized                              // Is initialized?

---

📝 Key Changes in 2.0

✅ Simplified & Unified

• getNouns() now handles ALL plural queries (by IDs, filters, or pagination)
• No more getNounsByIds(), queryNouns(), getBatch() - just getNouns()
• Clear singular vs plural: getNoun() for one, getNouns() for many

✅ Specific Naming

• Always specify noun/verb: addNoun() not add()
• No aliases or duplicates
• One method, one purpose

✅ Private Legacy Methods

These are now private (use new methods above):

• add(), get(), delete(), update()
• relate(), connect(), has(), exists()
• getMetadata(), updateMetadata()
• addItem(), addToBoth(), addBatch(), getBatch()

✅ Triple Intelligence

• New find() method unifies Vector + Graph + Field search
• Most powerful search capability in one simple method

✅ Zero-Configuration

• Everything works instantly with sensible defaults
• Optional configuration only for advanced users
• No complex setup required

✅ Clean Architecture

• Augmentation system for extensibility
• All features included (no premium tiers)
• Beautiful developer experience