David Snelling
8e767408d9
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)
90 lines
3.4 KiB
TypeScript
90 lines
3.4 KiB
TypeScript
/**
|
|
* @module utils/recallPreset
|
|
* @description Maps Brainy 8.0's algorithm-neutral `recall` preset to the
|
|
* underlying index-specific knobs. The same user-facing word (`'fast'` /
|
|
* `'balanced'` / `'accurate'`) means "the right thing happens" whether
|
|
* Brainy's open-core JS HNSW path is in play or a native acceleration
|
|
* provider (DiskANN-style) has taken over the `'vector'` provider key.
|
|
*
|
|
* **Public contract** — locked in handoff thread BRAINY-8.0-RENAME-COORDINATION
|
|
* § A.2 (cortex-confirmed 2026-06-09):
|
|
* - `'fast'` — minimum-latency search, accepts lower recall
|
|
* - `'balanced'` — Brainy 7.x defaults, the right pick for almost everyone
|
|
* - `'accurate'` — maximum recall, accepts higher latency
|
|
*
|
|
* Default when `recall` is omitted: `'balanced'`.
|
|
*
|
|
* **Knob mapping** — the JS HNSW preset values below match what Brainy 7.x
|
|
* shipped as defaults for `'balanced'`. Native acceleration providers (e.g.
|
|
* cortex's DiskANN wrapper) read the same `recall` value off the index
|
|
* config and translate it to their own internal knobs.
|
|
*/
|
|
|
|
import type { HNSWConfig } from '../coreTypes.js'
|
|
|
|
export type RecallPreset = 'fast' | 'balanced' | 'accurate'
|
|
|
|
/**
|
|
* The default preset when `config.vector.recall` is omitted. Matches Brainy
|
|
* 7.x's historical HNSW defaults exactly (`M=16`, `efConstruction=200`,
|
|
* `efSearch=50`).
|
|
*/
|
|
export const DEFAULT_RECALL: RecallPreset = 'balanced'
|
|
|
|
/**
|
|
* The set of HNSW knobs that the `recall` preset controls. Brainy 8.0 does
|
|
* not expose these directly — the preset is the only quality/latency knob
|
|
* surfaced on the public config. Algorithm-internal tuning is intentionally
|
|
* hidden behind the preset.
|
|
*/
|
|
export interface RecallHnswKnobs {
|
|
M: number
|
|
efConstruction: number
|
|
efSearch: number
|
|
}
|
|
|
|
/**
|
|
* Preset → JS HNSW knob tuples. The `'balanced'` entry equals Brainy 7.x's
|
|
* `DEFAULT_CONFIG` so a 7.x → 8.0 upgrade with no explicit `recall` value is
|
|
* a no-op.
|
|
*/
|
|
const HNSW_PRESETS: Readonly<Record<RecallPreset, Readonly<RecallHnswKnobs>>> = {
|
|
fast: { M: 16, efConstruction: 100, efSearch: 30 },
|
|
balanced: { M: 16, efConstruction: 200, efSearch: 50 },
|
|
accurate: { M: 32, efConstruction: 400, efSearch: 100 },
|
|
}
|
|
|
|
/**
|
|
* Resolve a preset name (or `undefined` for the default) to its underlying
|
|
* HNSW knob tuple.
|
|
*
|
|
* @param preset - The preset name, or `undefined` to use {@link DEFAULT_RECALL}.
|
|
* @returns The HNSW knob values for the preset.
|
|
*/
|
|
export function resolveRecallHnswKnobs(preset: RecallPreset | undefined): RecallHnswKnobs {
|
|
return HNSW_PRESETS[preset ?? DEFAULT_RECALL]
|
|
}
|
|
|
|
/**
|
|
* Resolve a Brainy 8.0 `VectorIndexConfig` into a concrete `HNSWConfig` for
|
|
* the open-core JS HNSW path. Applies the recall preset.
|
|
*
|
|
* Native acceleration providers do NOT use this function — they read
|
|
* `config.vector.recall` directly and apply their own preset table. This
|
|
* helper exists for Brainy's own JS HNSW implementation only.
|
|
*
|
|
* @param vectorConfig - The user-supplied `config.vector` block. May be omitted.
|
|
* @returns A complete `HNSWConfig` with `M`, `efConstruction`, `efSearch`, `ml`
|
|
* populated from the preset.
|
|
*/
|
|
export function resolveJsHnswConfig(
|
|
vectorConfig?: { recall?: RecallPreset }
|
|
): Pick<HNSWConfig, 'M' | 'efConstruction' | 'efSearch' | 'ml'> {
|
|
const preset = resolveRecallHnswKnobs(vectorConfig?.recall)
|
|
return {
|
|
M: preset.M,
|
|
efConstruction: preset.efConstruction,
|
|
efSearch: preset.efSearch,
|
|
ml: 16,
|
|
}
|
|
}
|