@seanhogg/builderforce-memory 2026.7.14 → 2026.9.28

package/dist/rag/EnterpriseRetriever.d.ts

@@ -0,0 +1,114 @@
+/**
+ * rag/EnterpriseRetriever.ts — hybrid, tenant-scoped, cited retrieval.
+ *
+ * The gap between a RAG demo and an enterprise RAG system is not the embedding
+ * model. It is these five properties, all of which live here:
+ *
+ *   1. **Scoped.** Every read carries an {@link AccessScope} that is compiled into
+ *      the database query. There is no code path that reads unscoped, so a
+ *      cross-tenant answer is not something a caller can cause by forgetting.
+ *   2. **Hybrid.** Dense retrieval alone misses exact tokens — error codes, SKUs,
+ *      contract clause numbers, function names. Lexical search alone misses
+ *      paraphrase. RRF over both, then MMR for diversity, then an optional
+ *      reranker.
+ *   3. **Honest about degradation.** When the store has no lexical index the
+ *      retrieval is dense-only and SAYS so on the span and in the result, instead
+ *      of quietly returning worse answers.
+ *   4. **Cited.** Every passage carries its source id, title and URI, and the
+ *      prompt builder numbers them, so an answer can be checked. An uncitable
+ *      answer is an unauditable one, and enterprises audit.
+ *   5. **Traced and costed.** Retrieval and generation are spans under one trace,
+ *      with token counts and cost, so "why was this answer bad" and "why did this
+ *      cost that" are answerable from the same record.
+ */
+import type { TransformerBridge } from '../bridges/TransformerBridge.js';
+import type { Span, Tracer } from '../telemetry/Tracer.js';
+import type { AccessScope, MetadataFilter, VectorStore } from '../vectorstore/types.js';
+/** Reranker port — a cross-encoder, an LLM judge, or a hosted rerank endpoint. */
+export type Reranker = (query: string, passages: readonly RetrievedPassage[]) => Promise<readonly RetrievedPassage[]>;
+export interface RetrievedPassage {
+    id: string;
+    text: string;
+    /** Fused relevance score. */
+    score: number;
+    sourceId: string;
+    title?: string;
+    uri?: string;
+    metadata: Record<string, unknown>;
+}
+export type RetrievalMode = 'hybrid' | 'dense-only' | 'keyword-only' | 'empty';
+export interface RetrievalResult {
+    passages: RetrievedPassage[];
+    /** What actually ran — `dense-only` means the store had no lexical index. */
+    mode: RetrievalMode;
+    /** Candidates considered before fusion and truncation. */
+    candidatesConsidered: number;
+    traceId?: string;
+}
+export interface RetrieveOptions {
+    /** Tenant/ACL scope. Required unless the retriever was built with a default. */
+    scope?: AccessScope;
+    /** Extra metadata predicate, AND-ed with the scope. */
+    filter?: MetadataFilter;
+    /** Passages returned. Default 5. */
+    topK?: number;
+    /** Candidates pulled from each retrieval arm before fusion. Default `topK * 4`. */
+    candidateK?: number;
+    /** Drop passages below this fused score after normalisation. Default 0. */
+    minScore?: number;
+    /** Parent span, so retrieval nests under the agent turn that asked for it. */
+    parent?: Span;
+}
+export interface EnterpriseRetrieverOptions {
+    store: VectorStore;
+    /** Embeds the query. Omit for keyword-only retrieval. */
+    embed?: (text: string) => Promise<Float32Array>;
+    /** Applied to the fused list before truncation. */
+    reranker?: Reranker;
+    /** Default scope, when a deployment is single-tenant or scope comes from context. */
+    defaultScope?: AccessScope;
+    /** RRF weight for the dense arm. Default 1. */
+    denseWeight?: number;
+    /** RRF weight for the lexical arm. Default 1. */
+    keywordWeight?: number;
+    /** MMR relevance/diversity trade-off; 1 is pure relevance. Default 0.7. */
+    mmrLambda?: number;
+    /** Disable the MMR diversity pass. Default false. */
+    disableDiversity?: boolean;
+    tracer?: Tracer;
+}
+export declare class EnterpriseRetriever {
+    private readonly _store;
+    private readonly _embed;
+    private readonly _reranker;
+    private readonly _defaultScope;
+    private readonly _denseWeight;
+    private readonly _keywordWeight;
+    private readonly _mmrLambda;
+    private readonly _diversity;
+    private readonly _tracer;
+    constructor(opts: EnterpriseRetrieverOptions);
+    retrieve(query: string, opts?: RetrieveOptions): Promise<RetrievalResult>;
+    /**
+     * Retrieve, then answer strictly from what was retrieved.
+     *
+     * The system prompt forbids answering beyond the passages and requires
+     * `[n]` citations. That is not decoration: an enterprise deployment is judged
+     * on whether a wrong answer is *detectable*, and an uncited claim is not.
+     */
+    answer(query: string, bridge: TransformerBridge, opts?: RetrieveOptions & {
+        systemPrompt?: string;
+        maxTokens?: number;
+        model?: string;
+    }): Promise<{
+        answer: string;
+        result: RetrievalResult;
+    }>;
+    private _fuse;
+    private _diversify;
+}
+export declare const GROUNDED_SYSTEM_PROMPT: string;
+export declare const NO_EVIDENCE_ANSWER: string;
+/** Renders passages as a numbered, citable evidence block. */
+export declare function buildGroundedPrompt(query: string, passages: readonly RetrievedPassage[]): string;
+//# sourceMappingURL=EnterpriseRetriever.d.ts.map

package/dist/rag/EnterpriseRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnterpriseRetriever.d.ts","sourceRoot":"","sources":["../../src/rag/EnterpriseRetriever.ts"],"names":[],"mappings":"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"}

package/dist/rag/EnterpriseRetriever.js

@@ -0,0 +1,240 @@
+/**
+ * rag/EnterpriseRetriever.ts — hybrid, tenant-scoped, cited retrieval.
+ *
+ * The gap between a RAG demo and an enterprise RAG system is not the embedding
+ * model. It is these five properties, all of which live here:
+ *
+ *   1. **Scoped.** Every read carries an {@link AccessScope} that is compiled into
+ *      the database query. There is no code path that reads unscoped, so a
+ *      cross-tenant answer is not something a caller can cause by forgetting.
+ *   2. **Hybrid.** Dense retrieval alone misses exact tokens — error codes, SKUs,
+ *      contract clause numbers, function names. Lexical search alone misses
+ *      paraphrase. RRF over both, then MMR for diversity, then an optional
+ *      reranker.
+ *   3. **Honest about degradation.** When the store has no lexical index the
+ *      retrieval is dense-only and SAYS so on the span and in the result, instead
+ *      of quietly returning worse answers.
+ *   4. **Cited.** Every passage carries its source id, title and URI, and the
+ *      prompt builder numbers them, so an answer can be checked. An uncitable
+ *      answer is an unauditable one, and enterprises audit.
+ *   5. **Traced and costed.** Retrieval and generation are spans under one trace,
+ *      with token counts and cost, so "why was this answer bad" and "why did this
+ *      cost that" are answerable from the same record.
+ */
+import { maximalMarginalRelevance, reciprocalRankFusion } from '../retrieval/fusion.js';
+import { SOURCE_ID_FIELD, TITLE_FIELD, URI_FIELD, } from '../ingest/types.js';
+export class EnterpriseRetriever {
+    _store;
+    _embed;
+    _reranker;
+    _defaultScope;
+    _denseWeight;
+    _keywordWeight;
+    _mmrLambda;
+    _diversity;
+    _tracer;
+    constructor(opts) {
+        this._store = opts.store;
+        this._embed = opts.embed;
+        this._reranker = opts.reranker;
+        this._defaultScope = opts.defaultScope;
+        this._denseWeight = opts.denseWeight ?? 1;
+        this._keywordWeight = opts.keywordWeight ?? 1;
+        this._mmrLambda = opts.mmrLambda ?? 0.7;
+        this._diversity = !opts.disableDiversity;
+        this._tracer = opts.tracer;
+    }
+    async retrieve(query, opts = {}) {
+        const topK = Math.max(1, opts.topK ?? 5);
+        const candidateK = Math.max(topK, opts.candidateK ?? topK * 4);
+        const scope = opts.scope ?? this._defaultScope;
+        const span = this._tracer?.startSpan('retrieval.hybrid', {
+            kind: 'retrieval',
+            ...(opts.parent ? { parent: opts.parent } : {}),
+            attributes: {
+                'retrieval.store': this._store.name,
+                'retrieval.top_k': topK,
+                'retrieval.tenant': scope?.tenantId ?? 'unscoped',
+            },
+        });
+        try {
+            const queryVector = this._embed ? await this._embed(query) : undefined;
+            const base = {
+                text: query,
+                topK: candidateK,
+                ...(opts.filter ? { filter: opts.filter } : {}),
+                ...(scope ? { scope } : {}),
+                includeVectors: this._diversity,
+            };
+            // Both arms run concurrently: they hit different indexes and the
+            // sequential version doubles p95 latency for nothing.
+            const [dense, keyword] = await Promise.all([
+                queryVector
+                    ? this._store.query({ ...base, vector: queryVector })
+                    : Promise.resolve([]),
+                this._store.keywordSearch
+                    ? this._store.keywordSearch(base)
+                    : Promise.resolve([]),
+            ]);
+            const mode = pickMode(dense.length > 0, keyword.length > 0, Boolean(this._store.keywordSearch));
+            const byId = new Map();
+            for (const match of [...dense, ...keyword]) {
+                if (!byId.has(match.id))
+                    byId.set(match.id, match);
+            }
+            let ordered = this._fuse(dense, keyword, byId);
+            if (this._diversity && queryVector && ordered.length > topK) {
+                ordered = this._diversify(queryVector, ordered, byId, topK);
+            }
+            let passages = ordered.slice(0, Math.max(topK, this._reranker ? candidateK : topK))
+                .map((hit) => toPassage(byId.get(hit.id), hit.score));
+            if (this._reranker && passages.length > 0) {
+                passages = [...await this._reranker(query, passages)];
+            }
+            if (opts.minScore !== undefined) {
+                passages = passages.filter((p) => p.score >= opts.minScore);
+            }
+            passages = passages.slice(0, topK);
+            span?.setAttributes({
+                'retrieval.mode': mode,
+                'retrieval.candidates': byId.size,
+                'retrieval.returned': passages.length,
+                'retrieval.dense_hits': dense.length,
+                'retrieval.keyword_hits': keyword.length,
+                'retrieval.reranked': Boolean(this._reranker),
+            });
+            span?.end('ok');
+            const result = {
+                passages,
+                mode,
+                candidatesConsidered: byId.size,
+            };
+            if (span)
+                result.traceId = span.traceId;
+            return result;
+        }
+        catch (err) {
+            span?.fail(err);
+            throw err;
+        }
+    }
+    /**
+     * Retrieve, then answer strictly from what was retrieved.
+     *
+     * The system prompt forbids answering beyond the passages and requires
+     * `[n]` citations. That is not decoration: an enterprise deployment is judged
+     * on whether a wrong answer is *detectable*, and an uncited claim is not.
+     */
+    async answer(query, bridge, opts = {}) {
+        const span = this._tracer?.startSpan('rag.answer', {
+            kind: 'agent',
+            ...(opts.parent ? { parent: opts.parent } : {}),
+        });
+        try {
+            const result = await this.retrieve(query, { ...opts, ...(span ? { parent: span } : {}) });
+            if (result.passages.length === 0) {
+                // Refusing beats hallucinating: with no evidence there is nothing to
+                // ground an answer in, and a confident answer here is the exact
+                // failure enterprises cite when a pilot is killed.
+                span?.setAttribute('rag.refused', true);
+                span?.end('ok');
+                return { answer: NO_EVIDENCE_ANSWER, result };
+            }
+            const prompt = buildGroundedPrompt(query, result.passages);
+            const answer = await bridge.generate(prompt, {
+                systemPrompt: opts.systemPrompt ?? GROUNDED_SYSTEM_PROMPT,
+                ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+                ...(opts.model !== undefined ? { model: opts.model } : {}),
+            });
+            span?.setAttributes({ 'rag.passages': result.passages.length, 'rag.mode': result.mode });
+            span?.end('ok');
+            return { answer, result };
+        }
+        catch (err) {
+            span?.fail(err);
+            throw err;
+        }
+    }
+    _fuse(dense, keyword, byId) {
+        const lists = [];
+        if (dense.length)
+            lists.push({ ids: dense.map((m) => m.id), weight: this._denseWeight });
+        if (keyword.length)
+            lists.push({ ids: keyword.map((m) => m.id), weight: this._keywordWeight });
+        if (lists.length === 0)
+            return [];
+        if (lists.length === 1) {
+            // One arm: keep the store's own similarity rather than replacing it with
+            // an RRF score, which carries no meaning for a single list.
+            const only = dense.length ? dense : keyword;
+            return only.map((m) => ({ id: m.id, score: m.score }));
+        }
+        const fused = reciprocalRankFusion(lists);
+        const best = fused[0]?.score ?? 1;
+        // RRF scores live on a tiny arbitrary scale (~1/60); normalising to [0,1]
+        // keeps `minScore` meaning the same thing on one arm or two.
+        return fused
+            .filter((hit) => byId.has(hit.id))
+            .map((hit) => ({ id: hit.id, score: best > 0 ? hit.score / best : 0 }));
+    }
+    _diversify(queryVector, ordered, byId, topK) {
+        const candidates = ordered
+            .map((hit) => ({ id: hit.id, vector: byId.get(hit.id)?.vector }))
+            .filter((c) => Boolean(c.vector));
+        // Without stored vectors MMR cannot run; keeping the fused order is the
+        // correct degradation, not an error.
+        if (candidates.length < 2)
+            return ordered;
+        const scores = new Map(ordered.map((hit) => [hit.id, hit.score]));
+        const picked = maximalMarginalRelevance(queryVector, candidates, topK, this._mmrLambda);
+        const pickedSet = new Set(picked);
+        return [
+            ...picked.map((id) => ({ id, score: scores.get(id) ?? 0 })),
+            ...ordered.filter((hit) => !pickedSet.has(hit.id)),
+        ];
+    }
+}
+function pickMode(hasDense, hasKeyword, storeHasKeyword) {
+    if (hasDense && hasKeyword)
+        return 'hybrid';
+    if (hasDense)
+        return 'dense-only';
+    if (hasKeyword)
+        return 'keyword-only';
+    return storeHasKeyword ? 'empty' : 'dense-only';
+}
+function toPassage(match, score) {
+    const metadata = match.metadata;
+    const passage = {
+        id: match.id,
+        text: match.text,
+        score,
+        sourceId: String(metadata[SOURCE_ID_FIELD] ?? match.id),
+        metadata,
+    };
+    const title = metadata[TITLE_FIELD];
+    if (typeof title === 'string')
+        passage.title = title;
+    const uri = metadata[URI_FIELD];
+    if (typeof uri === 'string')
+        passage.uri = uri;
+    return passage;
+}
+export const GROUNDED_SYSTEM_PROMPT = 'You answer strictly from the numbered passages provided. ' +
+    'Cite every claim with the passage number in square brackets, e.g. [2]. ' +
+    'If the passages do not contain the answer, say so plainly and name what is missing. ' +
+    'Never rely on knowledge that is not in the passages.';
+export const NO_EVIDENCE_ANSWER = 'No indexed passage matched this question within the caller\'s access scope, ' +
+    'so there is nothing to ground an answer in.';
+/** Renders passages as a numbered, citable evidence block. */
+export function buildGroundedPrompt(query, passages) {
+    const evidence = passages
+        .map((p, i) => {
+        const label = p.title ?? p.sourceId;
+        const uri = p.uri ? ` (${p.uri})` : '';
+        return `[${i + 1}] ${label}${uri}\n${p.text}`;
+    })
+        .join('\n\n');
+    return `Passages:\n\n${evidence}\n\nQuestion: ${query}\n\nAnswer, citing passages by number:`;
+}
+//# sourceMappingURL=EnterpriseRetriever.js.map

package/dist/rag/EnterpriseRetriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnterpriseRetriever.js","sourceRoot":"","sources":["../../src/rag/EnterpriseRetriever.ts"],"names":[],"mappings":"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"}

package/dist/rag/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * rag — enterprise retrieval: hybrid, tenant/ACL scoped, cited, traced.
+ */
+export { EnterpriseRetriever, buildGroundedPrompt, GROUNDED_SYSTEM_PROMPT, NO_EVIDENCE_ANSWER, } from './EnterpriseRetriever.js';
+export type { EnterpriseRetrieverOptions, RetrieveOptions, RetrievalResult, RetrievalMode, RetrievedPassage, Reranker, } from './EnterpriseRetriever.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/rag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rag/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACR,0BAA0B,EAC1B,eAAe,EACf,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,QAAQ,GACX,MAAM,0BAA0B,CAAC"}

package/dist/rag/index.js

@@ -0,0 +1,5 @@
+/**
+ * rag — enterprise retrieval: hybrid, tenant/ACL scoped, cited, traced.
+ */
+export { EnterpriseRetriever, buildGroundedPrompt, GROUNDED_SYSTEM_PROMPT, NO_EVIDENCE_ANSWER, } from './EnterpriseRetriever.js';
+//# sourceMappingURL=index.js.map

package/dist/rag/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rag/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,GACrB,MAAM,0BAA0B,CAAC"}

package/dist/retrieval/bm25.d.ts

@@ -6,13 +6,35 @@
  * Fusing the two (see {@link ./fusion}) is what lifts the memory layer from
  * "cosine only" to a hybrid retriever on par with Weaviate-style search.
  *
- * Pure and zero-dependency — reuses the shared `tokenize` from ../similarity.
+ * Two things are separable here and are kept separate on purpose:
+ *
+ *   • the SCORING CORE ({@link bm25Idf}, {@link bm25LengthNorm}, {@link bm25TermScore})
+ *     — the Okapi formula itself, which is the same wherever lexical relevance is
+ *     scored, whether the index is built inline from raw text or read out of a
+ *     precomputed per-field term table (BM25F). Exported so a consumer with its own
+ *     index shape reuses the maths instead of restating it and drifting from it;
+ *   • the TOKENIZER — which is genuinely corpus-specific. Prose wants stopword
+ *     removal and stemming; identifiers and error codes want neither. So the
+ *     tokenizer is an injectable {@link Bm25Options.tokenize} hook defaulting to the
+ *     package's plain `tokenize`, rather than a second copy of BM25 growing around
+ *     each specialisation.
+ *
+ * Pure and zero-dependency.
  */
+/** Splits text into the terms BM25 scores over. */
+export type Bm25Tokenizer = (text: string) => string[];
 export interface Bm25Options {
     /** Term-frequency saturation. Higher = TF matters more. Default 1.5. */
     k1?: number;
     /** Length normalisation, 0..1. Higher = penalise long docs more. Default 0.75. */
     b?: number;
+    /**
+     * Tokenizer for both the query and the documents. Default is the package's plain
+     * `tokenize` (lowercase word split), which preserves identifiers verbatim. Supply
+     * a stemming/stopword tokenizer when the corpus is prose — the SAME function must
+     * be used for query and documents or nothing will match.
+     */
+    tokenize?: Bm25Tokenizer;
 }
 export interface Bm25Doc {
     id: string;
@@ -22,6 +44,31 @@ export interface Bm25Hit {
     id: string;
     score: number;
 }
+/** Term-frequency saturation used when {@link Bm25Options.k1} is omitted. */
+export declare const BM25_DEFAULT_K1 = 1.5;
+/** Length normalisation used when {@link Bm25Options.b} is omitted. */
+export declare const BM25_DEFAULT_B = 0.75;
+/**
+ * Inverse document frequency with the +1 smoothing variant, which is always
+ * non-negative — the unsmoothed form goes negative for a term present in more than
+ * half the corpus, which subtracts score for a MATCH.
+ */
+export declare function bm25Idf(documentCount: number, documentFrequency: number): number;
+/**
+ * The document-length penalty `1 - b + b·(len/avgdl)`, factored out because it is
+ * per-DOCUMENT: computing it once and reusing it across the query's terms is what
+ * keeps scoring O(terms) rather than O(terms) divisions of the same quotient.
+ */
+export declare function bm25LengthNorm(length: number, averageLength: number, b?: number): number;
+/**
+ * One term's contribution: `idf · f(k1+1) / (f + k1·lengthNorm)`.
+ *
+ * `frequency` is whatever the caller counts as the term's occurrence weight — a raw
+ * count for plain BM25, or a field-weighted sum for BM25F. Combining fields BEFORE
+ * saturation (rather than saturating each field and summing) is what makes BM25F
+ * behave like BM25 over a weighted document.
+ */
+export declare function bm25TermScore(frequency: number, idf: number, lengthNorm: number, k1?: number): number;
 /**
  * Scores every document against `query` with Okapi BM25, returning hits sorted by
  * descending score (documents with no query-term overlap score 0 and are dropped).

package/dist/retrieval/bm25.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bm25.d.ts","sourceRoot":"","sources":["../../src/retrieval/bm25.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,WAAW;IACxB,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,CAAC,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,EAAE,CA8C5F"}
+{"version":3,"file":"bm25.d.ts","sourceRoot":"","sources":["../../src/retrieval/bm25.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;AAEvD,MAAM,WAAW,WAAW;IACxB,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,CAAC,CAAC,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC5B;AAED,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,uEAAuE;AACvE,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAIhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,GAAE,MAAuB,GAAG,MAAM,CAGxG;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,GAAE,MAAwB,GAAG,MAAM,CAGtH;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,EAAE,CA0C5F"}

package/dist/retrieval/bm25.js

@@ -6,9 +6,58 @@
  * Fusing the two (see {@link ./fusion}) is what lifts the memory layer from
  * "cosine only" to a hybrid retriever on par with Weaviate-style search.
  *
- * Pure and zero-dependency — reuses the shared `tokenize` from ../similarity.
+ * Two things are separable here and are kept separate on purpose:
+ *
+ *   • the SCORING CORE ({@link bm25Idf}, {@link bm25LengthNorm}, {@link bm25TermScore})
+ *     — the Okapi formula itself, which is the same wherever lexical relevance is
+ *     scored, whether the index is built inline from raw text or read out of a
+ *     precomputed per-field term table (BM25F). Exported so a consumer with its own
+ *     index shape reuses the maths instead of restating it and drifting from it;
+ *   • the TOKENIZER — which is genuinely corpus-specific. Prose wants stopword
+ *     removal and stemming; identifiers and error codes want neither. So the
+ *     tokenizer is an injectable {@link Bm25Options.tokenize} hook defaulting to the
+ *     package's plain `tokenize`, rather than a second copy of BM25 growing around
+ *     each specialisation.
+ *
+ * Pure and zero-dependency.
  */
 import { tokenize } from '../similarity/index.js';
+/** Term-frequency saturation used when {@link Bm25Options.k1} is omitted. */
+export const BM25_DEFAULT_K1 = 1.5;
+/** Length normalisation used when {@link Bm25Options.b} is omitted. */
+export const BM25_DEFAULT_B = 0.75;
+/**
+ * Inverse document frequency with the +1 smoothing variant, which is always
+ * non-negative — the unsmoothed form goes negative for a term present in more than
+ * half the corpus, which subtracts score for a MATCH.
+ */
+export function bm25Idf(documentCount, documentFrequency) {
+    const n = Math.max(documentCount, 1);
+    const df = Math.max(0, Math.min(documentFrequency, n));
+    return Math.log(1 + (n - df + 0.5) / (df + 0.5));
+}
+/**
+ * The document-length penalty `1 - b + b·(len/avgdl)`, factored out because it is
+ * per-DOCUMENT: computing it once and reusing it across the query's terms is what
+ * keeps scoring O(terms) rather than O(terms) divisions of the same quotient.
+ */
+export function bm25LengthNorm(length, averageLength, b = BM25_DEFAULT_B) {
+    const avg = averageLength > 0 ? averageLength : 1;
+    return 1 - b + b * (Math.max(0, length) / avg);
+}
+/**
+ * One term's contribution: `idf · f(k1+1) / (f + k1·lengthNorm)`.
+ *
+ * `frequency` is whatever the caller counts as the term's occurrence weight — a raw
+ * count for plain BM25, or a field-weighted sum for BM25F. Combining fields BEFORE
+ * saturation (rather than saturating each field and summing) is what makes BM25F
+ * behave like BM25 over a weighted document.
+ */
+export function bm25TermScore(frequency, idf, lengthNorm, k1 = BM25_DEFAULT_K1) {
+    if (frequency <= 0)
+        return 0;
+    return (idf * (frequency * (k1 + 1))) / (frequency + k1 * lengthNorm);
+}
 /**
  * Scores every document against `query` with Okapi BM25, returning hits sorted by
  * descending score (documents with no query-term overlap score 0 and are dropped).
@@ -16,12 +65,13 @@ import { tokenize } from '../similarity/index.js';
  * store / a vector pre-filter) this is O(N·terms) and needs no persistence.
  */
 export function bm25Search(query, docs, opts = {}) {
-    const k1 = opts.k1 ?? 1.5;
-    const b = opts.b ?? 0.75;
+    const k1 = opts.k1 ?? BM25_DEFAULT_K1;
+    const b = opts.b ?? BM25_DEFAULT_B;
+    const split = opts.tokenize ?? tokenize;
     const N = docs.length;
     if (N === 0)
         return [];
-    const queryTerms = new Set(tokenize(query));
+    const queryTerms = new Set(split(query));
     if (queryTerms.size === 0)
         return [];
     // Per-doc term frequencies + document lengths.
@@ -29,7 +79,7 @@ export function bm25Search(query, docs, opts = {}) {
     const df = new Map();
     let totalLen = 0;
     for (const doc of docs) {
-        const tokens = tokenize(doc.text);
+        const tokens = split(doc.text);
         const tf = new Map();
         for (const t of tokens)
             tf.set(t, (tf.get(t) ?? 0) + 1);
@@ -40,22 +90,18 @@ export function bm25Search(query, docs, opts = {}) {
         totalLen += tokens.length;
     }
     const avgdl = totalLen / N || 1;
-    // idf with the +1 smoothing variant (always non-negative).
     const idf = new Map();
-    for (const term of queryTerms) {
-        const n = df.get(term) ?? 0;
-        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
-    }
+    for (const term of queryTerms)
+        idf.set(term, bm25Idf(N, df.get(term) ?? 0));
     const hits = [];
     for (const d of docTerms) {
+        const lengthNorm = bm25LengthNorm(d.len, avgdl, b);
         let score = 0;
         for (const term of queryTerms) {
             const f = d.tf.get(term);
             if (!f)
                 continue;
-            const numer = f * (k1 + 1);
-            const denom = f + k1 * (1 - b + b * (d.len / avgdl));
-            score += idf.get(term) * (numer / denom);
+            score += bm25TermScore(f, idf.get(term), lengthNorm, k1);
         }
         if (score > 0)
             hits.push({ id: d.id, score });

package/dist/retrieval/bm25.js.map

@@ -1 +1 @@
-{"version":3,"file":"bm25.js","sourceRoot":"","sources":["../../src/retrieval/bm25.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bm25.js","sourceRoot":"","sources":["../../src/retrieval/bm25.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/index.d.ts

@@ -7,8 +7,8 @@
  */
 export { chunkText } from './chunk.js';
 export type { Chunk, ChunkOptions } from './chunk.js';
-export { bm25Search } from './bm25.js';
-export type { Bm25Doc, Bm25Hit, Bm25Options } from './bm25.js';
+export { bm25Search, bm25Idf, bm25LengthNorm, bm25TermScore, BM25_DEFAULT_K1, BM25_DEFAULT_B } from './bm25.js';
+export type { Bm25Doc, Bm25Hit, Bm25Options, Bm25Tokenizer } from './bm25.js';
 export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
 export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
 export { hybridRetrieve } from './HybridRetriever.js';

package/dist/retrieval/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChH,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/retrieval/index.js

@@ -6,7 +6,7 @@
  * browser, Node, and the SSM runtime alike.
  */
 export { chunkText } from './chunk.js';
-export { bm25Search } from './bm25.js';
+export { bm25Search, bm25Idf, bm25LengthNorm, bm25TermScore, BM25_DEFAULT_K1, BM25_DEFAULT_B } from './bm25.js';
 export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
 export { hybridRetrieve } from './HybridRetriever.js';
 export { HnswIndex, denseSearch } from './hnsw.js';

package/dist/retrieval/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhH,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}