brainy/docs/api/README.md

API Reference

Complete API documentation for Brainy's multi-dimensional AI database.

Core APIs

BrainyData

The main entry point for all operations.

Triple Intelligence

Unified query system for vector, graph, and field search.

Storage

Storage adapter interfaces and implementations.

Entity Registry

High-performance entity deduplication system.

Neural API

Natural language processing and similarity operations.

Quick Reference

Initialization

import { BrainyData } from 'brainy'

const brain = new BrainyData({
  storage: { type: 'filesystem', path: './data' },
  vectors: { dimensions: 384 }
})

await brain.init()

Basic Operations

Add Entities (Nouns) and Relationships (Verbs)

// Add entities (nouns) with automatic embedding
const id = await brain.addNoun("Machine learning is fascinating", {
  category: "technology",
  timestamp: Date.now()
})

// Add relationships (verbs) between entities
const sourceId = await brain.addNoun("Research Paper")
const targetId = await brain.addNoun("Neural Networks")
await brain.addVerb(sourceId, targetId, "discusses", {
  confidence: 0.95,
  section: "methodology"
})

// Batch operations
const entities = ["Entity 1", "Entity 2", "Entity 3"]
for (const entity of entities) {
  await brain.addNoun(entity, { type: "batch" })
}

Search and Find

// Simple semantic search
const results = await brain.search("AI and machine learning")

// Natural language queries with find()
const nlpResults = await brain.find("research papers about neural networks from 2024")
// Automatically interprets: document type, topic, and time range

// Advanced triple intelligence search with structured query
const structured = await brain.find({
  like: "neural networks",
  where: { category: "research" },
  connected: { to: "team-id", depth: 2 },
  limit: 20
})

// Complex natural language with multiple conditions
const complex = await brain.find("highly cited papers on deep learning with over 100 citations published in Nature")
// Automatically extracts: citation count, topic, publication venue

Get and Update

// Get noun by ID
const noun = await brain.getNoun("noun-id")

// Get verb (relationship) by ID
const verb = await brain.getVerb("verb-id")

// Update noun metadata
await brain.updateNounMetadata("noun-id", {
  verified: true,
  lastModified: Date.now()
})

// Delete noun (soft delete by default)
await brain.deleteNoun("noun-id")

// Delete verb (relationship)
await brain.deleteVerb("verb-id")

Advanced Features

Augmentations

import { 
  WALAugmentation,
  EntityRegistryAugmentation,
  BatchProcessingAugmentation 
} from 'brainy'

const brain = new BrainyData({
  augmentations: [
    new WALAugmentation(),
    new EntityRegistryAugmentation({ maxCacheSize: 100000 }),
    new BatchProcessingAugmentation({ batchSize: 100 })
  ]
})

Event System

brain.on('addNoun', (noun) => {
  console.log('Noun added:', noun.id)
})

brain.on('addVerb', (verb) => {
  console.log('Relationship created:', verb.type)
})

brain.on('search', (query, results) => {
  console.log(`Search for "${query}" returned ${results.length} results`)
})

brain.on('error', (error) => {
  console.error('Error occurred:', error)
})

Statistics

const stats = await brain.statistics()
console.log(`
  Total items: ${stats.totalItems}
  Index size: ${stats.indexSize}
  Average query time: ${stats.avgQueryTime}ms
`)

Type Definitions

Core Types

interface SearchResult {
  id: string
  score: number
  content?: string
  metadata?: Record<string, any>
}

interface TripleQuery {
  like?: string | Vector | any
  where?: Record<string, any>
  connected?: ConnectionQuery
  limit?: number
  threshold?: number
}

interface Vector {
  values: number[]
  dimensions: number
}

Error Handling

All methods follow consistent error handling:

try {
  await brain.addNoun("content", metadata)
} catch (error) {
  if (error.code === 'STORAGE_ERROR') {
    // Handle storage issues
  } else if (error.code === 'VALIDATION_ERROR') {
    // Handle validation issues
  }
}

Performance Guidelines

Batching

Always use batch operations for bulk data:

// Good - efficient batch processing
const items = ["item1", "item2", "item3"]
for (const item of items) {
  await brain.addNoun(item, { batch: true })
}

// For relationships
const relationships = [
  { source: id1, target: id2, type: "related" },
  { source: id2, target: id3, type: "similar" }
]
for (const rel of relationships) {
  await brain.addVerb(rel.source, rel.target, rel.type)
}

Caching

Configure caching for your use case:

const brain = new BrainyData({
  cache: {
    search: { maxSize: 100, ttl: 60000 },
    metadata: { maxSize: 1000, ttl: 300000 }
  }
})

Indexing

Ensure fields used in queries are indexed:

// Configure indexed fields
const brain = new BrainyData({
  indexedFields: ['category', 'author', 'timestamp']
})

Migration from v1.x

See the Migration Guide for upgrading from Brainy 1.x to 2.0.