feat(8.0): API simplification — remove neural()/Db.search, one storage path key, integration→0
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:
parent
0c4a51c24e
commit
606445cd61
74 changed files with 712 additions and 7470 deletions
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue