brainy/docs/api-design-archive/BRAINY-2.0-DETAILED-API.md

🧠 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:

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

  {
    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