refactor(8.0): simplify config.vector to 3 knobs + fold persistMode (scaffold step 8)
Per user direction and BRAINY-8.0-RENAME-COORDINATION § G.2: the
`config.vector.advanced.{hnsw, diskann}` escape-hatch surface was
over-engineered. The 8.0 config surface collapses to **three knobs**:
```
config.vector = {
recall?: 'fast' | 'balanced' | 'accurate'
quantization?: { enabled?, bits?: 8 | 4 }
persistMode?: 'immediate' | 'deferred'
}
```
The algorithm-internal HNSW knobs (`M`, `efConstruction`, `efSearch`,
`ml`) and DiskANN knobs (`pqM`, `searchListSize`, `alpha`, …) are no
longer exposed at the public surface. The `recall` preset covers the
legitimate quality/latency tradeoff; algorithm-internal tuning is
intentionally hidden. If users need it later, we can add it back —
shipping with too few knobs is easier to evolve than shipping with too
many.
CHANGES
src/types/brainy.types.ts
- BrainyConfig.hnswPersistMode (7.x top-level) → BrainyConfig.vector.persistMode.
- BrainyConfig.vector — dropped `advanced.{hnsw, diskann}` sub-block.
- BrainyConfig.vector.quantization — dropped `rerankMultiplier` (hardcoded to 3).
- BrainyConfig.vector — dropped `vectorStorage: 'memory' | 'lazy'`. Brainy
always keeps vectors resident in 8.0; the lazy-eviction path was a
cloud-storage optimisation that's no longer needed (cloud adapters are gone).
- JSDoc tightened to reflect the closed-form contract.
src/utils/recallPreset.ts
- resolveJsHnswConfig() signature narrowed: accepts `{ recall? }` only
(no more `advanced` parameter).
src/brainy.ts
- normalizeConfig() — no longer carries `hnswPersistMode` on the resolved
config. Dropped the deprecated 'gcs-native' warning, the gcsStorage
HMAC-key warning, and the lenient storage-pairing block (dead code now
that cloud adapters are gone).
- resolveHNSWPersistMode() — collapsed to a one-liner:
`return this.config.vector?.persistMode ?? 'immediate'`. The cloud-vs-local
smart-default branching is no longer relevant (filesystem is the only
persistent backend in 8.0).
- setupIndex() — reads quantization fields from config.vector directly;
rerankMultiplier hardcoded to 3.
NO-OP scope
The recall preset's 'balanced' = brainy 7.x DEFAULT_CONFIG byte-for-byte,
so users who don't set recall get the same behavior. Users who set
config.hnsw.* in 7.x will need to migrate to config.vector.* per the
8.0 release notes; pure 7.x defaults users see no change.
VERIFICATION
- npx tsc --noEmit: clean
- npm test: 1408 / 1409 (same pre-existing test-isolation race condition
from step 7, not related to step 8)
This commit is contained in:
parent
0e6263a1bd
commit
8e767408d9
3 changed files with 68 additions and 105 deletions
|
|
@ -1110,72 +1110,58 @@ export interface BrainyConfig {
|
|||
batchWrites?: boolean // Enable write batching for better performance
|
||||
maxConcurrentOperations?: number // Limit concurrent file operations
|
||||
|
||||
// HNSW persistence mode
|
||||
// Controls when HNSW graph connections are persisted to storage
|
||||
// - 'immediate': Persist on every add (slow but durable, default for filesystem)
|
||||
// - 'deferred': Persist only on flush/close (fast, default for cloud storage)
|
||||
// Cloud storage (GCS/S3/R2/Azure) should use 'deferred' for 30-50× faster adds
|
||||
hnswPersistMode?: 'immediate' | 'deferred'
|
||||
|
||||
/**
|
||||
* Vector index configuration (Brainy 8.0).
|
||||
*
|
||||
* Algorithm-neutral surface. The `recall` preset means the same thing
|
||||
* whether Brainy's open-core JS HNSW path is in play or a native
|
||||
* acceleration provider has taken over the `'vector'` provider key:
|
||||
* - `'fast'` — minimum-latency search, accepts lower recall
|
||||
* - `'balanced'` — Brainy 7.x defaults, the right pick for almost everyone
|
||||
* - `'accurate'` — maximum recall, accepts higher latency
|
||||
*
|
||||
* Power users may override individual knobs via `advanced.hnsw` (the JS
|
||||
* path) or `advanced.diskann` (a native DiskANN-style provider). The
|
||||
* preset is the floor; explicit overrides win.
|
||||
* Three knobs. No escape hatch. The algorithm-internal HNSW knobs
|
||||
* (`M`, `efConstruction`, `efSearch`, `ml`, …) and DiskANN knobs
|
||||
* (`pqM`, `searchListSize`, `alpha`, …) are deliberately not exposed —
|
||||
* the `recall` preset covers the legitimate quality/latency tradeoff
|
||||
* range, and the open-core defaults match Brainy 7.x's defaults
|
||||
* byte-for-byte so a `'balanced'`-default upgrade is a no-op.
|
||||
*
|
||||
* **Closed-form contract** locked in handoff thread
|
||||
* BRAINY-8.0-RENAME-COORDINATION § A.2 (cortex-confirmed 2026-06-09).
|
||||
* BRAINY-8.0-RENAME-COORDINATION § A.2 + § G.2 (cortex-confirmed 2026-06-09).
|
||||
*/
|
||||
vector?: {
|
||||
/** Recall preset. Defaults to `'balanced'` when omitted. */
|
||||
/**
|
||||
* Recall preset.
|
||||
* - `'fast'` — minimum-latency search, accepts lower recall
|
||||
* - `'balanced'` (default) — Brainy 7.x defaults, the right pick for almost everyone
|
||||
* - `'accurate'` — maximum recall, accepts higher latency
|
||||
*
|
||||
* Means the same thing whether the open-core JS HNSW path is in play
|
||||
* or a native vector provider has taken over the `'vector'` provider
|
||||
* key — Brainy translates to HNSW knobs; native providers translate
|
||||
* to their own (e.g. DiskANN's `defaultLSearch` / `defaultPaddingFactor`).
|
||||
*/
|
||||
recall?: 'fast' | 'balanced' | 'accurate'
|
||||
|
||||
/**
|
||||
* Vector quantization. Independent of `recall` — it trades RAM for a
|
||||
* small recall hit at any preset. `bits: 8` is SQ8 (4× memory reduction,
|
||||
* ~0.4% recall loss). `bits: 4` is SQ4 (8× memory reduction, ~1-3% recall
|
||||
* loss). Both ship in the open-core path; cortex's `distance:sq8` /
|
||||
* `distance:sq4` SIMD providers accelerate them when available.
|
||||
*
|
||||
* Silently ignored on a native DiskANN-style provider path (it uses its
|
||||
* own PQ math); `strictConfig: 'warn'` flags this at init time.
|
||||
*/
|
||||
quantization?: {
|
||||
enabled?: boolean
|
||||
bits?: 8 | 4
|
||||
rerankMultiplier?: number
|
||||
}
|
||||
/** Vector storage mode. `'memory'` keeps vectors resident; `'lazy'` evicts after insert. */
|
||||
vectorStorage?: 'memory' | 'lazy'
|
||||
|
||||
/**
|
||||
* Power-user overrides. The recall preset works for 99% of users — use
|
||||
* these only if you've measured. `hnsw` overrides apply on the JS HNSW
|
||||
* path; `diskann` overrides apply when a DiskANN-style native provider
|
||||
* is in play. Both blocks are honored on their respective paths and
|
||||
* silently ignored on the other (a one-shot warning fires when
|
||||
* `strictConfig !== false`).
|
||||
* Vector persistence mode. `'immediate'` writes per-noun graph state on
|
||||
* every `add()`; durable but slower. `'deferred'` writes only on
|
||||
* `flush()` / `close()`; faster bulk ingest. Defaults to `'immediate'`
|
||||
* on filesystem storage (the only persistent backend in 8.0).
|
||||
*
|
||||
* Brainy 7.x called this `hnswPersistMode` at the top level. The 8.0
|
||||
* surface folds it under `config.vector` alongside `recall`.
|
||||
*/
|
||||
advanced?: {
|
||||
hnsw?: {
|
||||
M?: number
|
||||
efConstruction?: number
|
||||
efSearch?: number
|
||||
ml?: number
|
||||
}
|
||||
diskann?: {
|
||||
pqM?: number
|
||||
pqKsub?: number
|
||||
maxDegree?: number
|
||||
searchListSize?: number
|
||||
alpha?: number
|
||||
useMmapAdjacency?: boolean
|
||||
mmapAdjacencyPath?: string
|
||||
}
|
||||
}
|
||||
persistMode?: 'immediate' | 'deferred'
|
||||
}
|
||||
|
||||
// Memory management options
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue