brainbank 0.7.0 → 0.8.0

package/src/providers/pruners/haiku-expander.ts

@@ -0,0 +1,152 @@
+/**
+ * BrainBank — Haiku Expander
+ *
+ * LLM-powered context expansion using Anthropic's Haiku 4.5 model.
+ * After search + pruning, reviews a manifest of available chunks
+ * and requests additional IDs to include.
+ *
+ * Flow:
+ *   1. Receives lightweight manifest (~20 chars per chunk)
+ *   2. Haiku selects additional chunk IDs (just numbers, fast)
+ *   3. Caller fetches those chunks from DB and splices into results
+ *
+ * Designed for minimal token usage:
+ *   - Input: ~2,000-3,000 tokens (manifest)
+ *   - Output: ~50-100 tokens (ID array)
+ *   - Cost: ~$0.001 per call
+ *   - Latency: ~300-600ms
+ *
+ * Fail-open: any error returns empty array (no expansion).
+ */
+
+import type { Expander, ExpanderManifestItem, ExpanderResult } from '@/types.ts';
+
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+
+export interface HaikuExpanderOptions {
+    /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-haiku-4-5-20251001 */
+    model?: string;
+}
+
+export class HaikuExpander implements Expander {
+    private readonly _apiKey: string;
+    private readonly _model: string;
+
+    constructor(options: HaikuExpanderOptions = {}) {
+        this._apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '';
+        this._model = options.model ?? DEFAULT_MODEL;
+
+        if (!this._apiKey) {
+            throw new Error(
+                'HaikuExpander: No API key provided. Set ANTHROPIC_API_KEY env var or pass apiKey option.',
+            );
+        }
+    }
+
+    async expand(
+        query: string,
+        currentIds: number[],
+        manifest: ExpanderManifestItem[],
+    ): Promise<ExpanderResult> {
+        if (manifest.length === 0) return { ids: [] };
+
+        // Filter out chunks already in results
+        const currentSet = new Set(currentIds);
+        const available = manifest.filter(m => !currentSet.has(m.id));
+        if (available.length === 0) return { ids: [] };
+
+        // Build compact manifest string
+        const manifestLines = available.map(m =>
+            `#${m.id} ${m.filePath} | ${m.chunkType} ${m.name} ${m.lines}`
+        ).join('\n');
+
+        const currentSummary = manifest
+            .filter(m => currentSet.has(m.id))
+            .map(m => `#${m.id} ${m.filePath} | ${m.chunkType} ${m.name}`)
+            .join('\n');
+
+        const prompt =
+            `Task: "${query}"\n\n` +
+            `Already included chunks:\n${currentSummary}\n\n` +
+            `Available chunks NOT yet included:\n${manifestLines}\n\n` +
+            `You are a code context expander. The search already found the "included" chunks above.\n` +
+            `Review the "available" chunks and select any that would help an AI agent complete the task.\n\n` +
+            `Rules:\n` +
+            `- Select chunks that are structurally related (called by, imported by, or extend included code)\n` +
+            `- Select type definitions, interfaces, or configs needed to understand included code\n` +
+            `- Select initialization or setup code if the task involves debugging or modifying a feature\n` +
+            `- Do NOT select test files, documentation, or unrelated utilities\n` +
+            `- Be selective: only include chunks that fill clear gaps. Quality over quantity.\n` +
+            `- If nothing useful is available, return an empty ids array\n\n` +
+            `Respond with ONLY a JSON object:\n` +
+            `{ "ids": [42, 17, 89], "note": "Brief 1-2 sentence observation about the codebase relevant to the task" }\n\n` +
+            `The "note" is optional — use it to mention things like missing files, architectural patterns, ` +
+            `deprecated modules, or important relationships you noticed. If nothing notable, omit it.\n` +
+            `If nothing to add: { "ids": [] }`;
+
+        try {
+            const response = await fetch('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this._apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify({
+                    model: this._model,
+                    max_tokens: 512,
+                    messages: [{
+                        role: 'user',
+                        content: prompt,
+                    }],
+                }),
+            });
+
+            if (!response.ok) {
+                return { ids: [] };
+            }
+
+            const data = await response.json() as {
+                content: { type: string; text: string }[];
+            };
+
+            const text = data.content?.[0]?.text ?? '';
+            return this._parseResponse(text, available);
+        } catch {
+            return { ids: [] };
+        }
+    }
+
+    /** Parse Haiku response — handles both `{ ids, note }` and bare `[...]` formats. */
+    private _parseResponse(text: string, available: ExpanderManifestItem[]): ExpanderResult {
+        const validIds = new Set(available.map(m => m.id));
+
+        // Try JSON object first: { "ids": [...], "note": "..." }
+        const objMatch = text.match(/\{[\s\S]*"ids"\s*:\s*\[[\d\s,]*\][\s\S]*\}/);
+        if (objMatch) {
+            try {
+                const parsed = JSON.parse(objMatch[0]) as { ids: number[]; note?: string };
+                const ids = parsed.ids.filter(id => validIds.has(id));
+                const note = parsed.note?.trim() || undefined;
+                return { ids, note };
+            } catch {
+                // Fall through to array parsing
+            }
+        }
+
+        // Fallback: bare array [42, 17, 89]
+        const arrMatch = text.match(/\[[\d\s,]*\]/);
+        if (arrMatch) {
+            const ids = (JSON.parse(arrMatch[0]) as number[]).filter(id => validIds.has(id));
+            return { ids };
+        }
+
+        return { ids: [] };
+    }
+
+    async close(): Promise<void> {
+        // No resources to release (stateless HTTP)
+    }
+}

package/src/providers/pruners/haiku-pruner.ts

@@ -0,0 +1,112 @@
+/**
+ * BrainBank — Haiku Pruner
+ *
+ * LLM-based noise filter using Anthropic's Haiku 4.5 model.
+ * Binary classification: for each search result, Haiku decides
+ * "relevant" or "noise" based on filePath, metadata, and full
+ * file content (capped at ~8K chars per item by prune.ts).
+ *
+ * Latency: ~300-600ms.
+ */
+
+import type { Pruner, PrunerItem } from '@/types.ts';
+
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+
+export interface HaikuPrunerOptions {
+    /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-haiku-4-5-20251001 */
+    model?: string;
+}
+
+export class HaikuPruner implements Pruner {
+    private readonly _apiKey: string;
+    private readonly _model: string;
+
+    constructor(options: HaikuPrunerOptions = {}) {
+        this._apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '';
+        this._model = options.model ?? DEFAULT_MODEL;
+
+        if (!this._apiKey) {
+            throw new Error(
+                'HaikuPruner: No API key provided. Set ANTHROPIC_API_KEY env var or pass apiKey option.',
+            );
+        }
+    }
+
+    async prune(query: string, items: PrunerItem[]): Promise<number[]> {
+        if (items.length === 0) return [];
+        if (items.length === 1) return [items[0].id];
+
+        const itemLines = items.map(item => {
+            // Only show useful metadata fields (skip raw scores, IDs, large arrays)
+            const SKIP_KEYS = new Set(['id', 'chunkIds', 'rrfScore', 'filePath']);
+            const meta = Object.entries(item.metadata)
+                .filter(([k, v]) => v !== undefined && v !== null && !SKIP_KEYS.has(k))
+                .map(([k, v]) => `${k}=${v}`)
+                .join(' | ');
+            return `#${item.id} ${item.filePath} | ${meta}\n${item.preview}`;
+        }).join('\n---\n');
+
+        const prompt =
+            `Query: "${query}"\n\nSearch results (full file content):\n${itemLines}\n\n` +
+            `You are a precision search filter and ranker. You have the FULL source code of each file.\n` +
+            `Return a JSON array of #IDs to KEEP, ordered by relevance (most relevant FIRST).\n\n` +
+            `Rules:\n` +
+            `- Understand the SPECIFIC system/feature the query targets. Don't match on shared vocabulary alone.\n` +
+            `  Example: "snackbar toast notification" targets the toast popup system, NOT a notification center/bell icon.\n` +
+            `- KEEP files that directly implement, define types for, or configure the queried system.\n` +
+            `- KEEP files where the queried system is mounted, initialized, or composed into a workflow.\n` +
+            `- DROP files that only CONSUME the system (e.g. a component that calls showNotification once but has 400 lines of unrelated logic).\n` +
+            `- DROP files that implement a DIFFERENT system sharing similar vocabulary.\n` +
+            `- DROP infrastructure/boilerplate (font loaders, theme definitions, CSS-only layout shells) unless they directly configure the queried feature.\n` +
+            `- Aim for 40-70% keep rate. Returning fewer, highly relevant files is BETTER than returning many tangential ones.\n` +
+            `- ORDER: core implementation → types/config → mount points → peripheral.\n\n` +
+            `Respond with ONLY the JSON array. Example: [3, 0, 5, 1]`;
+
+        try {
+            const response = await fetch('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this._apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify({
+                    model: this._model,
+                    max_tokens: 512,
+                    messages: [{
+                        role: 'user',
+                        content: prompt,
+                    }],
+                }),
+            });
+
+            if (!response.ok) {
+                // API error → fail-open, return all
+                return items.map(i => i.id);
+            }
+
+            const data = await response.json() as {
+                content: { type: string; text: string }[];
+            };
+
+            const text = data.content?.[0]?.text ?? '';
+            // Haiku may wrap in ```json ... ``` — extract any JSON array
+            const match = text.match(/\[[\d\s,]+\]/);
+            if (!match) return items.map(i => i.id);
+
+            const keepIds = JSON.parse(match[0]) as number[];
+            const validIds = new Set(items.map(i => i.id));
+            return keepIds.filter(id => validIds.has(id));
+        } catch {
+            // Network error → fail-open, return all
+            return items.map(i => i.id);
+        }
+    }
+
+    async close(): Promise<void> {
+        // No resources to release (stateless HTTP)
+    }
+}

package/src/providers/rerankers/qwen3-reranker.ts

@@ -0,0 +1,180 @@
+/**
+ * BrainBank — Qwen3 Local Reranker
+ * 
+ * Cross-encoder reranker using Qwen3-Reranker-0.6B via node-llama-cpp.
+ * Auto-downloads the GGUF model from HuggingFace (~640MB, cached).
+ * 
+ * Based on QMD's reranker architecture:
+ * - Lazy model loading (loads on first rank() call)
+ * - Flash attention for 20× less VRAM
+ * - Document deduplication (identical texts scored once)
+ * - Tokenizer-based truncation for oversized documents
+ */
+
+import type { Reranker } from '@/types.ts';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+
+/** Minimal interface for node-llama-cpp model methods used by the reranker. */
+interface LlamaModel {
+    tokenize(text: string): number[];
+    detokenize(tokens: number[]): string;
+    createRankingContext(opts: { contextSize: number; flashAttention?: boolean }): Promise<LlamaRankingContext>;
+    dispose?(): Promise<void>;
+}
+
+/** Minimal interface for node-llama-cpp ranking context. */
+interface LlamaRankingContext {
+    rankAll(query: string, documents: string[]): Promise<number[]>;
+    dispose(): Promise<void>;
+}
+
+/** Engine returned by getLlama(). */
+interface LlamaEngine {
+    loadModel(opts: { modelPath: string }): Promise<LlamaModel>;
+}
+
+/** Shape of the node-llama-cpp module used here. */
+interface NodeLlamaCppModule {
+    getLlama(): Promise<LlamaEngine>;
+    resolveModelFile(uri: string, cacheDir: string): Promise<string>;
+}
+
+// Default model — Qwen3-Reranker-0.6B quantized to Q8_0 (~640MB)
+const DEFAULT_MODEL_URI = 'hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf';
+
+// Context size for reranking (Qwen3 template ~200 tokens overhead + query + doc)
+const CONTEXT_SIZE = 2048;
+
+// Cache directory for downloaded models
+const MODEL_CACHE_DIR = join(homedir(), '.cache', 'brainbank', 'models');
+
+export interface Qwen3RerankerOptions {
+    /** HuggingFace model URI. Default: Qwen3-Reranker-0.6B-Q8_0 */
+    modelUri?: string;
+    /** Model cache directory. Default: ~/.cache/brainbank/models/ */
+    cacheDir?: string;
+    /** Context size for ranking. Default: 2048 */
+    contextSize?: number;
+}
+
+export class Qwen3Reranker implements Reranker {
+    private readonly _modelUri: string;
+    private readonly _cacheDir: string;
+    private readonly _contextSize: number;
+
+    private _model: LlamaModel | null = null;
+    private _context: LlamaRankingContext | null = null;
+    private _loadPromise: Promise<void> | null = null;
+
+    constructor(options: Qwen3RerankerOptions = {}) {
+        this._modelUri = options.modelUri ?? DEFAULT_MODEL_URI;
+        this._cacheDir = options.cacheDir ?? MODEL_CACHE_DIR;
+        this._contextSize = options.contextSize ?? CONTEXT_SIZE;
+    }
+
+    /**
+     * Lazy-load the reranker model and create a ranking context.
+     * Model is auto-downloaded from HuggingFace on first use.
+     */
+    private async _ensureLoaded(): Promise<void> {
+        if (this._context) return;
+        if (this._loadPromise) {
+            await this._loadPromise;
+            return;
+        }
+
+        this._loadPromise = (async () => {
+            try {
+                // Dynamic import — node-llama-cpp is an optional peer dependency.
+                // String indirection prevents DTS from resolving the specifier at build time.
+                const llamaModule = 'node-llama-cpp';
+                const { getLlama, resolveModelFile } = await import(/* webpackIgnore: true */ llamaModule) as NodeLlamaCppModule;
+
+                // Ensure cache directory exists
+                if (!existsSync(this._cacheDir)) {
+                    mkdirSync(this._cacheDir, { recursive: true });
+                }
+
+                // Download model if needed (resolveModelFile handles caching)
+                const modelPath = await resolveModelFile(this._modelUri, this._cacheDir);
+
+                // Initialize llama engine
+                const llama = await getLlama();
+
+                // Load model
+                this._model = await llama.loadModel({ modelPath });
+
+                try {
+                    this._context = await this._model!.createRankingContext({
+                        contextSize: this._contextSize,
+                        flashAttention: true,
+                    });
+                } catch {
+                    // Flash attention might not be supported — retry without it
+                    this._context = await this._model!.createRankingContext({
+                        contextSize: this._contextSize,
+                    });
+                }
+            } finally {
+                this._loadPromise = null;
+            }
+        })();
+
+        await this._loadPromise;
+    }
+
+    /**
+     * Score each document's relevance to the query.
+     * Returns scores (0.0 - 1.0) in same order as input documents.
+     * 
+     * Deduplicates identical documents to avoid redundant computation.
+     */
+    async rank(query: string, documents: string[]): Promise<number[]> {
+        if (documents.length === 0) return [];
+
+        await this._ensureLoaded();
+
+        // Deduplicate — identical texts get scored once
+        const uniqueTexts = [...new Set(documents)];
+        const textToScore = new Map<string, number>();
+
+        // Truncate documents that exceed context size
+        const truncated = uniqueTexts.map(text => {
+            if (this._model) {
+                const tokens = this._model.tokenize(text);
+                // Budget: contextSize - ~200 overhead - query tokens
+                const queryTokens = this._model.tokenize(query).length;
+                const maxDocTokens = this._contextSize - 200 - queryTokens;
+                if (tokens.length > maxDocTokens && maxDocTokens > 0) {
+                    return this._model.detokenize(tokens.slice(0, maxDocTokens));
+                }
+            }
+            return text;
+        });
+
+        // Rank all unique documents at once
+        const scores: number[] = await this._context!.rankAll(query, truncated);
+
+        // Map scores back
+        for (let i = 0; i < uniqueTexts.length; i++) {
+            textToScore.set(uniqueTexts[i], scores[i] ?? 0);
+        }
+
+        // Return scores in original document order
+        return documents.map(doc => textToScore.get(doc) ?? 0);
+    }
+
+    /** Release model resources. */
+    async close(): Promise<void> {
+        if (this._context) {
+            await this._context.dispose();
+            this._context = null;
+        }
+        if (this._model) {
+            await this._model.dispose?.();
+            this._model = null;
+        }
+    }
+}

package/src/providers/vector/hnsw-index.ts

@@ -0,0 +1,174 @@
+/**
+ * BrainBank — HNSW Vector Index
+ * 
+ * Wraps hnswlib-node for O(log n) approximate nearest neighbor search.
+ * M=16 connections, ef=200 construction, ef=50 search by default.
+ * 150x faster than brute force at 1M vectors.
+ *
+ * Supports disk persistence: save(path) / tryLoad(path, count)
+ * to skip costly vector-by-vector rebuild on startup.
+ */
+
+import type { VectorIndex, SearchHit } from '@/types.ts';
+
+import { existsSync } from 'node:fs';
+
+/** Shape of the HNSW index from hnswlib-node. */
+interface HnswlibIndex {
+    initIndex(maxElements: number, M: number, efConstruction: number): void;
+    setEf(ef: number): void;
+    addPoint(vector: number[], id: number): void;
+    markDelete(id: number): void;
+    searchKnn(vector: number[], k: number): { neighbors: number[]; distances: number[] };
+    writeIndexSync(path: string): void;
+    readIndexSync(path: string): void;
+    getCurrentCount(): number;
+    getIdsList(): number[];
+}
+
+/** Shape of the hnswlib-node module (supports default + named exports). */
+interface HnswlibModule {
+    default?: { HierarchicalNSW: new (space: 'cosine' | 'l2' | 'ip', dims: number) => HnswlibIndex };
+    HierarchicalNSW?: new (space: 'cosine' | 'l2' | 'ip', dims: number) => HnswlibIndex;
+}
+
+export class HNSWIndex implements VectorIndex {
+    private _index: HnswlibIndex | null = null;
+    private _lib: HnswlibModule | null = null;
+    private _ids = new Set<number>();
+
+    constructor(
+        private _dims: number,
+        private _maxElements: number = 2_000_000,
+        private _M: number = 16,
+        private _efConstruction: number = 200,
+        private _efSearch: number = 50,
+    ) {}
+
+    /**
+     * Initialize the HNSW index.
+     * Must be called before add/search.
+     */
+    async init(): Promise<this> {
+        this._lib = await import('hnswlib-node');
+        this._createIndex();
+        return this;
+    }
+
+    /**
+     * Reinitialize the index in-place, clearing all vectors.
+     * Required after reembed or full re-index to avoid duplicate IDs.
+     * init() must have been called first.
+     */
+    reinit(): void {
+        if (!this._lib) throw new Error('HNSW not initialized — call init() first');
+        this._createIndex();
+    }
+
+    private _createIndex(): void {
+        if (!this._lib) throw new Error('HNSW lib not loaded');
+        const HNSW = this._lib.default?.HierarchicalNSW ?? this._lib.HierarchicalNSW;
+        if (!HNSW) throw new Error('HierarchicalNSW not found in hnswlib-node module');
+        this._index = new HNSW('cosine', this._dims);
+        this._index.initIndex(this._maxElements, this._M, this._efConstruction);
+        this._index.setEf(this._efSearch);
+        this._ids = new Set();
+    }
+
+    /** Maximum capacity of this index. */
+    get maxElements(): number { return this._maxElements; }
+
+    /**
+     * Add a vector with an integer ID.
+     * The vector should be pre-normalized for cosine distance.
+     */
+    add(vector: Float32Array, id: number): void {
+        if (!this._index) throw new Error('HNSW index not initialized — call init() first');
+        if (this._ids.has(id)) return; // idempotent: skip duplicates
+        if (this._ids.size >= this._maxElements) {
+            throw new Error(
+                `HNSW index full (${this._maxElements} elements). ` +
+                `Increase maxElements in config or prune old data.`
+            );
+        }
+        this._index.addPoint(Array.from(vector), id);
+        this._ids.add(id);
+    }
+
+    /**
+     * Mark a vector as deleted so it no longer appears in searches.
+     * Uses hnswlib-node markDelete under the hood.
+     * Safe to call with an ID that doesn't exist.
+     */
+    remove(id: number): void {
+        if (!this._index || this._ids.size === 0) return;
+        if (!this._ids.has(id)) return;
+        try {
+            this._index.markDelete(id);
+            this._ids.delete(id);
+        } catch {
+            // ID not found — ignore silently
+        }
+    }
+
+    /**
+     * Search for the k nearest neighbors.
+     * Returns results sorted by score (highest first).
+     * Score is 1 - cosine_distance (1.0 = identical).
+     */
+    search(query: Float32Array, k: number): SearchHit[] {
+        if (!this._index || this._ids.size === 0) return [];
+
+        const actualK = Math.min(k, this._ids.size);
+        const result = this._index.searchKnn(Array.from(query), actualK);
+
+        return result.neighbors.map((id: number, i: number) => ({
+            id,
+            score: 1 - result.distances[i],
+        }));
+    }
+
+    /** Number of vectors in the index. */
+    get size(): number {
+        return this._ids.size;
+    }
+
+    /**
+     * Save the HNSW graph to disk.
+     * The file can be loaded later with tryLoad() to skip vector-by-vector insertion.
+     */
+    save(path: string): void {
+        if (!this._index || this._ids.size === 0) return;
+        this._index.writeIndexSync(path);
+    }
+
+    /**
+     * Try to load a previously saved HNSW index from disk.
+     * Returns true if loaded successfully, false if stale or missing.
+     * @param path File path to the saved index
+     * @param expectedCount Expected number of vectors (from SQLite) — used to detect staleness
+     */
+    tryLoad(path: string, expectedCount: number): boolean {
+        if (!this._index || !existsSync(path)) return false;
+
+        try {
+            this._index.readIndexSync(path);
+            const loadedCount = this._index.getCurrentCount();
+
+            // Stale: vector count in DB differs from saved index
+            if (loadedCount !== expectedCount) {
+                this.reinit();
+                return false;
+            }
+
+            // Rebuild _ids set from the loaded index
+            const ids = this._index.getIdsList();
+            this._ids = new Set(ids);
+            this._index.setEf(this._efSearch);
+            return true;
+        } catch {
+            this.reinit();
+            return false;
+        }
+    }
+}