soulcraft/brainy
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

feat(8.0): API simplification — remove neural()/Db.search, one storage path key, integration→0

Browse source 
8.0 RC cleanup toward "one place per thing, zero-config, no deprecation":

- Remove the `brain.neural()` clustering namespace (ImprovedNeuralAPI + the dead
  legacy NeuralAPI + the neural CLI + neural-only types). Similarity is `find({vector})`
  / `similar({to})`; attribute grouping is the aggregation `GROUP BY` engine. The separate
  entity-extraction / smart-import feature (NeuralImport, NeuralEntityExtractor, SmartExtractor,
  NaturalLanguageProcessor, `brain.extract()`/`brain.nlp()`) is kept.
- Remove `Db.search()`; `find()` is the one query verb (accepts a bare string or FindParams).
  Fix the bundled MCP client, which called a non-existent `brain.search(query, limit)` →
  now `find({ query, limit })`.
- Storage config: collapse to one canonical top-level `path` key. The pre-8.0 aliases
  (`rootDirectory`, `options.*`, `fileSystemStorage.*`) are removed and now THROW with the
  exact rename instead of silently defaulting to `./brainy-data` on upgrade. A single resolver
  feeds createStorage, the 7.x→8.0 migration probe, and the plugin-factory handoff, so a native
  storage provider resolves the identical root (no split-brain).
- Fix `similar({ threshold })`: the min-similarity filter was silently dropped; it is now
  applied as a post-filter on `result.score` (the documented way to bound semantic results).
- Fix `vfs.rename()` on a directory: child path updates spread the entity vector into `update()`
  and failed dimension validation; they are metadata-only updates now.
- Fix `vfs.move()`: copy+delete orphaned the content-addressed content blob (the destination
  shared the source hash, then unlink removed it). `move()` now delegates to `rename()` — an
  in-place path change that preserves the blob and the entity id, for files and directories.
- Fix streaming import: the bulk fast path never flushed mid-import nor signalled queryability.
  Entity writes are now chunked by a progressive flush interval (100 → 1000 → 5000); each chunk
  flushes and emits `progress.queryable`, so imported data is queryable during the import.
- Sweep all docs, comments, and JSDoc for the removed/changed APIs.

Integration suite: 49 files / 588 passed / 0 failed. Unit: 80 files / 1456 passed, no type errors.
This commit is contained in:
David Snelling 2026-06-20 13:31:11 -07:00
parent 0c4a51c24e
commit 606445cd61
74 changed files with 712 additions and 7470 deletions
Download patch file Download diff file Expand all files Collapse all files

132
docs/api/README.md
View file

@ -956,7 +956,7 @@ closes the underlying instance.
```typescript
const db = await Brainy.load('/backups/2026-06-01')
const hits = await db.search('quarterly invoices')
const hits = await db.find({ query: 'quarterly invoices' })
await db.release()
```
@ -982,7 +982,7 @@ exactly that state.
```typescript
await db.get(id) // entity as of this generation
await db.find({ where: { status: 'open' } }) // full find() surface
await db.search('unpaid invoices') // semantic search as of this generation
await db.find({ query: 'unpaid invoices' }) // semantic search as of this generation
await db.related(entityId) // relationships as of this generation
await db.since(olderDb) // ids changed between two views
const whatIf = await db.with(ops) // speculative in-memory overlay
@ -1247,124 +1247,6 @@ const people = await brain.vfs.searchEntities({
---
## Neural API
Access advanced AI features via `brain.neural()` (method that returns NeuralAPI instance).
### `neural().similar(a, b, options?)` → `Promise<number | SimilarityResult>`
Calculate semantic similarity.
```typescript
// Simple similarity score
const score = await brain.neural().similar(
'renewable energy',
'sustainable power'
) // 0.87
// Detailed result
const result = await brain.neural().similar('text1', 'text2', {
detailed: true
})
console.log(result.score)
console.log(result.explanation)
```
---
### `neural().clusters(input?, options?)` → `Promise<SemanticCluster[]>`
Automatic clustering. Accepts a text query, an array of texts, or a `ClusteringOptions` object.
```typescript
const clusters = await brain.neural().clusters({
algorithm: 'kmeans', // 'auto' | 'hierarchical' | 'kmeans' | 'dbscan' | ...
maxClusters: 5,
minClusterSize: 3
})
clusters.forEach(cluster => {
console.log(cluster.label) // auto-generated label (when available)
console.log(cluster.members) // entity ids in the cluster
console.log(cluster.centroid) // centroid vector
})
```
---
### `neural().neighbors(id, options?)` → `Promise<NeighborsResult>`
Find nearest neighbors.
```typescript
const result = await brain.neural().neighbors(entityId, {
limit: 10,
minSimilarity: 0.7
})
```
**Options:** `limit?`, `radius?`, `minSimilarity?`, `includeMetadata?`, `sortBy?: 'similarity' | 'importance' | 'recency'`
---
### `neural().outliers(options?)` → `Promise<Outlier[]>`
Detect outlier entities.
```typescript
const outliers = await brain.neural().outliers({ threshold: 0.3 })
// Each outlier carries the entity id plus outlier scoring details
```
**Options:** `threshold?`, `method?: 'isolation' | 'statistical' | 'cluster-based'`, `minNeighbors?`, `includeReasons?`
---
### `neural().visualize(options?)` → `Promise<VizData>`
Generate visualization data.
```typescript
const vizData = await brain.neural().visualize({
maxNodes: 100,
dimensions: 3,
algorithm: 'force',
includeEdges: true
})
// Use with D3.js, Cytoscape, GraphML tools
```
---
### Performance Methods
#### `neural().clusterFast(options?)` → `Promise<SemanticCluster[]>`
Fast clustering for large datasets.
```typescript
const clusters = await brain.neural().clusterFast({
maxClusters: 10
})
```
**Options:** `level?` (hierarchy level), `maxClusters?`
---
#### `neural().clusterLarge(options?)` → `Promise<SemanticCluster[]>`
Sampling-based clustering for very large datasets.
```typescript
const clusters = await brain.neural().clusterLarge({
sampleSize: 1000,
strategy: 'diverse' // 'random' | 'diverse' | 'recent'
})
```
---
## Import & Export
### `import(source, options?)` → `Promise<ImportResult>`
@ -1463,7 +1345,7 @@ const brain = new Brainy({
// Storage configuration
storage: {
type: 'filesystem', // 'memory' | 'filesystem' | 'auto'
rootDirectory: './brainy-data'
path: './brainy-data'
},
// Vector index configuration (2 knobs)
@ -1510,14 +1392,14 @@ const brain = new Brainy({
const brain = new Brainy({
storage: {
type: 'filesystem',
rootDirectory: './brainy-data'
path: './brainy-data'
}
})
```
**Use case:** Node.js applications, single-node production deployments
For off-site backup, snapshot `rootDirectory` from your scheduler (`gsutil rsync`, `aws s3 sync`, `rclone`, or `tar`) — Brainy itself doesn't reach out to cloud object stores.
For off-site backup, snapshot `path` from your scheduler (`gsutil rsync`, `aws s3 sync`, `rclone`, or `tar`) — Brainy itself doesn't reach out to cloud object stores.
---
@ -1525,11 +1407,11 @@ For off-site backup, snapshot `rootDirectory` from your scheduler (`gsutil rsync
```typescript
const brain = new Brainy({
storage: { type: 'auto', rootDirectory: './brainy-data' }
storage: { type: 'auto', path: './brainy-data' }
})
```
Picks `'filesystem'` on Node with a writable `rootDirectory`, falls back to `'memory'` otherwise.
Picks `'filesystem'` on Node with a writable `path`, falls back to `'memory'` otherwise.
---