brainy/src/utils/recallPreset.ts

/**
 * @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. Power users may
 * override any of these via `config.vector.advanced.hnsw` — the preset is the
 * floor, explicit overrides win.
 */
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 first, then layers
 * the optional `advanced.hnsw` overrides so explicit knobs always win.
 *
 * 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 preset + overrides.
 */
export function resolveJsHnswConfig(
  vectorConfig?: { recall?: RecallPreset; advanced?: { hnsw?: Partial<HNSWConfig> } }
): Pick<HNSWConfig, 'M' | 'efConstruction' | 'efSearch' | 'ml'> {
  const preset = resolveRecallHnswKnobs(vectorConfig?.recall)
  const overrides = vectorConfig?.advanced?.hnsw ?? {}
  return {
    M: overrides.M ?? preset.M,
    efConstruction: overrides.efConstruction ?? preset.efConstruction,
    efSearch: overrides.efSearch ?? preset.efSearch,
    ml: overrides.ml ?? 16,
  }
}