David Snelling
00d3203d68
The distributed-clustering subsystem never ran in production: it was inert, orphaned dead code (faked consensus, stub replication, no live wiring, and it did not interoperate with the 8.0 Db API). Brainy 8.0 is a single-process library. Scale is single-process + the optional native provider (@soulcraft/cortex, on-disk DiskANN to 10B+ vectors) + per-tenant pools + horizontal read scaling (many reader processes, one writer). Removed: - src/distributed/ entirely (coordinator, shardManager, cacheSync, readWriteSeparation, queryPlanner, healthMonitor, configManager, hashPartitioner, shardMigration, domainDetector, storageDiscovery, http/network transports). ReaderMode/HybridMode relocated to src/storage/operationalModes.ts (slimmed to the live surface). - src/types/distributedTypes.ts; config.distributed field + JSDoc; coreTypes distributedConfig; memoryStorage distributedConfig persistence. - DistributedRole enum + src/config/distributedPresets.ts and the orphaned src/config/extensibleConfig.ts (config/augmentation registry built on removed cloud adapters + distributed presets), plus their src/index.ts re-exports. - 13 BRAINY_* cluster env vars; the storage setDistributedComponents hook; enableDistributedSearch (dead config flag); the metadata partition field; the distributed_ reserved key prefix. - Orphaned src/storage/readOnlyOptimizations.ts (zero importers). - Tests targeting the subsystem: distributed-demo, distributed-cluster helper, distributed-transactions, sharding-transactions. - Docs: EXTENDING_STORAGE.md (deleted); scrubbed distributed/cluster/Raft/ shard-manager/multi-node prose from v3-features, enterprise-for-everyone, augmentations-actual, complete-feature-list, vfs/README, vfs/ROADMAP, vfs/VFS_CORE, capacity-planning, transactions, MIGRATION-V3-TO-V4, storage-architecture; reframed scale prose to the 8.0 model. Kept: src/storage/sharding.ts (local-disk 256-bucket directory sharding via getShardIdFromUuid — used live by baseStorage, unrelated to clustering); the multi-process mode: 'reader' | 'writer' roles; semantic/HNSW clustering. RELEASES.md: added a removed-surfaces row documenting the cut and the 8.0 scale model.
130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# Brainy Documentation
|
|
|
|
> The multi-dimensional AI database with Triple Intelligence — vector search, graph traversal, and metadata filtering in one unified API.
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
|
|
|
|
const brain = new Brainy()
|
|
await brain.init()
|
|
|
|
// Add entities — data is embedded for semantic search, metadata is indexed for filtering
|
|
const id = await brain.add({
|
|
data: 'Revolutionary AI Breakthrough',
|
|
type: NounType.Document,
|
|
metadata: { category: 'technology', rating: 4.8 }
|
|
})
|
|
|
|
// Search with Triple Intelligence
|
|
const results = await brain.find({
|
|
query: 'artificial intelligence', // Semantic search (on data)
|
|
where: { rating: { greaterThan: 4.0 } }, // Metadata filter
|
|
connected: { from: authorId, depth: 2 } // Graph traversal
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Core Documentation
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| **[API Reference](./api/README.md)** | Complete API documentation — **start here** |
|
|
| **[Data Model](./DATA_MODEL.md)** | Entity structure, data vs metadata, storage fields |
|
|
| **[Query Operators](./QUERY_OPERATORS.md)** | All BFO operators with examples and indexed/in-memory matrix |
|
|
| [Find System](./FIND_SYSTEM.md) | Natural language `find()` and hybrid search details |
|
|
| [Consistency Model](./concepts/consistency-model.md) | The Db API guarantees — snapshot isolation, atomic transactions, time travel |
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Architecture Overview](./architecture/overview.md) | High-level system design |
|
|
| [Triple Intelligence](./architecture/triple-intelligence.md) | Vector + Graph + Metadata unified query |
|
|
| [Noun-Verb Taxonomy](./architecture/noun-verb-taxonomy.md) | 42 nouns + 127 verbs type system |
|
|
| [Stage 3 Canonical Taxonomy](./STAGE3-CANONICAL-TAXONOMY.md) | Complete type reference |
|
|
| [Storage Architecture](./architecture/storage-architecture.md) | Storage adapters and optimization |
|
|
| [Index Architecture](./architecture/index-architecture.md) | Vector, Graph, and Metadata indexing |
|
|
| [Zero Configuration](./architecture/zero-config.md) | Auto-adapts to any environment |
|
|
|
|
---
|
|
|
|
## Virtual Filesystem (VFS)
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [VFS Quick Start](./vfs/QUICK_START.md) | Get started in 30 seconds |
|
|
| [VFS Core](./vfs/VFS_CORE.md) | Core concepts and architecture |
|
|
| [VFS API Guide](./vfs/VFS_API_GUIDE.md) | Complete VFS API reference |
|
|
| [Common Patterns](./vfs/COMMON_PATTERNS.md) | VFS usage patterns |
|
|
|
|
See [vfs/](./vfs/) for the complete VFS documentation set.
|
|
|
|
---
|
|
|
|
## Guides
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Import Anything](./guides/import-anything.md) | CSV, Excel, PDF, URL imports |
|
|
| [Snapshots & Time Travel](./guides/snapshots-and-time-travel.md) | Backups, restore, what-if analysis, audit trails |
|
|
| [Natural Language](./guides/natural-language.md) | Query in plain English |
|
|
| [Neural API](./guides/neural-api.md) | AI-powered features |
|
|
| [Enterprise for Everyone](./guides/enterprise-for-everyone.md) | No limits, no tiers |
|
|
| [Framework Integration](./guides/framework-integration.md) | React, Vue, Angular, Svelte |
|
|
|
|
---
|
|
|
|
## Storage & Deployment
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Storage Architecture](./architecture/storage-architecture.md) | Filesystem and memory adapters, on-disk artifact layout, operator-layer backup |
|
|
| [Capacity Planning](./operations/capacity-planning.md) | Scale to millions of entities |
|
|
|
|
---
|
|
|
|
## Plugins
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Plugins](./PLUGINS.md) | Plugin system overview — providers, `plugins` config, `brain.use()` |
|
|
|
|
---
|
|
|
|
## Performance & Scaling
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Performance](./PERFORMANCE.md) | Optimization techniques |
|
|
| [Scaling](./SCALING.md) | Scale to billions of entities |
|
|
| [Batching](./BATCHING.md) | Batch operations guide |
|
|
|
|
---
|
|
|
|
## Migration & Reference
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [v3 to v4 Migration](./MIGRATION-V3-TO-V4.md) | Upgrade guide |
|
|
| [Release Guide](./RELEASE-GUIDE.md) | How to release new versions |
|
|
| [Production Architecture](./PRODUCTION_SERVICE_ARCHITECTURE.md) | Ops reference |
|
|
|
|
---
|
|
|
|
## Internal
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Audit Report](./internal/AUDIT_REPORT.md) | Feature audit |
|
|
| [Honest Status](./internal/HONEST_STATUS.md) | Actual implementation status |
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Brainy is MIT licensed. See [LICENSE](../LICENSE) for details.
|