@seanhogg/builderforce-memory 2026.9.29 → 2026.9.30

package/dist/retrieval/mmr.js

@@ -0,0 +1,94 @@
+/**
+ * Maximal Marginal Relevance — ONE greedy selection loop, two similarity bases.
+ *
+ * MMR reranks a relevance-ordered list so the top of it is not five near-duplicates:
+ * each step picks the candidate maximising `λ·relevance − (1−λ)·max sim(candidate,
+ * already-selected)`. λ=1 is pure relevance; lower λ buys diversity.
+ *
+ * What differs between callers is only what "similar" means:
+ *   • {@link maximalMarginalRelevance} — cosine over embedding vectors, relevance =
+ *     cosine to the query vector. For retrievers that hold vectors;
+ *   • {@link textMaximalMarginalRelevance} — Jaccard over word tokens, relevance =
+ *     the candidate's own score min-max normalised onto [0,1]. For retrievers that
+ *     only have text and a fused score (an FTS5 + sqlite-vec hybrid, say).
+ *
+ * Both run {@link mmrSelect}, so the selection rule itself exists once.
+ *
+ * Pure and zero-dependency.
+ */
+import { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
+/** Greedy MMR selection. Returns the picked candidates in pick order. */
+export function mmrSelect(items, opts) {
+    const lambda = opts.lambda ?? 0.7;
+    const limit = Math.min(opts.topK ?? items.length, items.length);
+    const remaining = [...items];
+    const relevance = new Map();
+    for (const item of remaining)
+        relevance.set(item, opts.relevance(item));
+    const selected = [];
+    while (selected.length < limit && remaining.length > 0) {
+        let bestIdx = -1;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const candidate = remaining[i];
+            let maxSimToSelected = 0;
+            for (const s of selected) {
+                const sim = opts.similarity(candidate, s);
+                if (sim > maxSimToSelected)
+                    maxSimToSelected = sim;
+            }
+            const score = lambda * relevance.get(candidate) - (1 - lambda) * maxSimToSelected;
+            const wins = score > bestScore
+                || (score === bestScore && bestIdx >= 0 && opts.tieScore !== undefined
+                    && opts.tieScore(candidate) > opts.tieScore(remaining[bestIdx]));
+            if (wins) {
+                bestScore = score;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx < 0)
+            break;
+        selected.push(remaining.splice(bestIdx, 1)[0]);
+    }
+    return selected;
+}
+/**
+ * Vector MMR. Selects up to `topK` candidates by cosine relevance to `queryVec`,
+ * penalising cosine similarity to what is already selected. Candidates without
+ * vectors should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export function maximalMarginalRelevance(queryVec, candidates, topK, lambda = 0.7) {
+    return mmrSelect(candidates, {
+        relevance: (c) => cosineSimilarity(queryVec, c.vector),
+        similarity: (a, b) => cosineSimilarity(a.vector, b.vector),
+        lambda,
+        topK,
+    }).map((c) => c.id);
+}
+/**
+ * Text MMR. Reorders every item, judging diversity by Jaccard similarity of word
+ * tokens, and relevance by the item's `score` min-max normalised onto [0,1] (all
+ * equal → 1). An exact tie goes to the higher raw score. `lambda` is clamped to
+ * [0,1]; at 1 this is a plain score sort.
+ */
+export function textMaximalMarginalRelevance(items, lambda = 0.7) {
+    if (items.length <= 1)
+        return [...items];
+    const l = Math.max(0, Math.min(1, lambda));
+    if (l === 1)
+        return [...items].sort((a, b) => b.score - a.score);
+    const tokens = new Map();
+    for (const item of items)
+        tokens.set(item.id, new Set(tokenize(item.content)));
+    const tokensOf = (item) => tokens.get(item.id) ?? new Set(tokenize(item.content));
+    const scores = items.map((i) => i.score);
+    const min = Math.min(...scores);
+    const range = Math.max(...scores) - min;
+    return mmrSelect(items, {
+        relevance: (item) => (range === 0 ? 1 : (item.score - min) / range),
+        similarity: (a, b) => jaccardSimilarity(tokensOf(a), tokensOf(b)),
+        lambda: l,
+        tieScore: (item) => item.score,
+    });
+}
+//# sourceMappingURL=mmr.js.map

package/dist/retrieval/mmr.js.map

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

package/dist/retrieval/weightedFusion.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Weighted-score fusion — the ONE formula for fusing a semantic arm with a lexical
+ * arm by SCORE, where {@link ./fusion reciprocalRankFusion} fuses by RANK.
+ *
+ * Score fusion is the choice when two different engines must rank the same way: an
+ * on-prem `sqlite-vec` cosine + FTS5/BM25 pair and a cloud pgvector cosine + ILIKE
+ * pair answer the same question, and a weighted sum of scores already on roughly
+ * [0,1] makes "recall ranks the same everywhere" a property of one function.
+ *
+ * Union semantics: a candidate found by only one arm scores 0 on the other rather
+ * than being dropped, because "the lexical arm did not match" is evidence about the
+ * query's wording, not about the candidate's relevance.
+ *
+ * Pure and zero-dependency.
+ */
+/** Weight on the semantic arm when a caller states none. */
+export declare const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
+/** Weight on the lexical arm when a caller states none. */
+export declare const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;
+export interface HybridWeights {
+    vectorWeight: number;
+    textWeight: number;
+}
+/**
+ * Renormalise a pair of weights so it sums to 1 — a fused score is only comparable
+ * across queries if the weights always sum the same. A degenerate pair (both zero
+ * or non-finite) falls back to the defaults.
+ *
+ * The pair is a RATIO, so only the lower bound is clamped: `(3, 1)` means "three
+ * parts semantic to one part lexical" and must come back as 0.75/0.25, not be
+ * capped into an even split. Normalisation is what bounds the result.
+ */
+export declare function normalizeHybridWeights(vectorWeight?: number, textWeight?: number): HybridWeights;
+/** One candidate's per-arm scores, both already normalised to roughly [0,1]. */
+export interface HybridArmScores {
+    vectorScore?: number;
+    textScore?: number;
+}
+/** The fused score for one candidate under the given (already normalised) weights. */
+export declare function hybridScore(scores: HybridArmScores, weights: HybridWeights): number;
+/**
+ * Map a BM25 rank (lower is better, unbounded — FTS5's `bm25()`) onto a (0,1]
+ * score so it can be summed with a cosine similarity. A non-finite rank is treated
+ * as very poor rather than as an error.
+ */
+export declare function bm25RankToScore(rank: number): number;
+/**
+ * Fuse two arms keyed by a caller-supplied id and return the candidates ordered
+ * best-first. `merge` builds the output row from the winning payload of each id;
+ * later duplicates of the same id keep the first payload seen (arm order decides).
+ */
+export declare function fuseHybridArms<TVector extends {
+    id: string;
+}, TText extends {
+    id: string;
+}, TOut>(params: {
+    vector: readonly TVector[];
+    text: readonly TText[];
+    vectorScoreOf: (row: TVector) => number;
+    textScoreOf: (row: TText) => number;
+    merge: (row: TVector | TText, score: number) => TOut;
+    weights?: Partial<HybridWeights>;
+}): TOut[];
+//# sourceMappingURL=weightedFusion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"weightedFusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/weightedFusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,2DAA2D;AAC3D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAUhG;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAInF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,EAAE;IACvG,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,KAAK,EAAE,CAAC;IACvB,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,MAAM,CAAC;IACpC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACpC,GAAG,IAAI,EAAE,CAkBT"}

package/dist/retrieval/weightedFusion.js

@@ -0,0 +1,80 @@
+/**
+ * Weighted-score fusion — the ONE formula for fusing a semantic arm with a lexical
+ * arm by SCORE, where {@link ./fusion reciprocalRankFusion} fuses by RANK.
+ *
+ * Score fusion is the choice when two different engines must rank the same way: an
+ * on-prem `sqlite-vec` cosine + FTS5/BM25 pair and a cloud pgvector cosine + ILIKE
+ * pair answer the same question, and a weighted sum of scores already on roughly
+ * [0,1] makes "recall ranks the same everywhere" a property of one function.
+ *
+ * Union semantics: a candidate found by only one arm scores 0 on the other rather
+ * than being dropped, because "the lexical arm did not match" is evidence about the
+ * query's wording, not about the candidate's relevance.
+ *
+ * Pure and zero-dependency.
+ */
+/** Weight on the semantic arm when a caller states none. */
+export const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
+/** Weight on the lexical arm when a caller states none. */
+export const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;
+/**
+ * Renormalise a pair of weights so it sums to 1 — a fused score is only comparable
+ * across queries if the weights always sum the same. A degenerate pair (both zero
+ * or non-finite) falls back to the defaults.
+ *
+ * The pair is a RATIO, so only the lower bound is clamped: `(3, 1)` means "three
+ * parts semantic to one part lexical" and must come back as 0.75/0.25, not be
+ * capped into an even split. Normalisation is what bounds the result.
+ */
+export function normalizeHybridWeights(vectorWeight, textWeight) {
+    const clamp = (n, fallback) => typeof n === 'number' && Number.isFinite(n) ? Math.max(0, n) : fallback;
+    const v = clamp(vectorWeight, DEFAULT_HYBRID_VECTOR_WEIGHT);
+    const t = clamp(textWeight, DEFAULT_HYBRID_TEXT_WEIGHT);
+    const sum = v + t;
+    if (sum <= 0) {
+        return { vectorWeight: DEFAULT_HYBRID_VECTOR_WEIGHT, textWeight: DEFAULT_HYBRID_TEXT_WEIGHT };
+    }
+    return { vectorWeight: v / sum, textWeight: t / sum };
+}
+/** The fused score for one candidate under the given (already normalised) weights. */
+export function hybridScore(scores, weights) {
+    const v = Number.isFinite(scores.vectorScore) ? scores.vectorScore : 0;
+    const t = Number.isFinite(scores.textScore) ? scores.textScore : 0;
+    return weights.vectorWeight * v + weights.textWeight * t;
+}
+/**
+ * Map a BM25 rank (lower is better, unbounded — FTS5's `bm25()`) onto a (0,1]
+ * score so it can be summed with a cosine similarity. A non-finite rank is treated
+ * as very poor rather than as an error.
+ */
+export function bm25RankToScore(rank) {
+    const normalized = Number.isFinite(rank) ? Math.max(0, rank) : 999;
+    return 1 / (1 + normalized);
+}
+/**
+ * Fuse two arms keyed by a caller-supplied id and return the candidates ordered
+ * best-first. `merge` builds the output row from the winning payload of each id;
+ * later duplicates of the same id keep the first payload seen (arm order decides).
+ */
+export function fuseHybridArms(params) {
+    const weights = normalizeHybridWeights(params.weights?.vectorWeight, params.weights?.textWeight);
+    const byId = new Map();
+    for (const row of params.vector) {
+        byId.set(row.id, { row, scores: { vectorScore: params.vectorScoreOf(row), textScore: 0 } });
+    }
+    for (const row of params.text) {
+        const existing = byId.get(row.id);
+        if (existing)
+            existing.scores.textScore = params.textScoreOf(row);
+        else
+            byId.set(row.id, { row, scores: { vectorScore: 0, textScore: params.textScoreOf(row) } });
+    }
+    return [...byId.values()]
+        .map((entry) => {
+        const score = hybridScore(entry.scores, weights);
+        return { out: params.merge(entry.row, score), score };
+    })
+        .sort((a, b) => b.score - a.score)
+        .map((entry) => entry.out);
+}
+//# sourceMappingURL=weightedFusion.js.map

package/dist/retrieval/weightedFusion.js.map

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

package/dist/similarity/index.d.ts

@@ -10,10 +10,12 @@ export declare function tokenize(text: string): string[];
 /** Jaccard similarity between two token sets: |A ∩ B| / |A ∪ B|. */
 export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
 /**
- * Cosine similarity between two vectors in the range [-1, 1] (0 when either is a
- * zero vector). Compares over the shorter length when lengths differ. Vectors
+ * Cosine similarity between two vectors in the range [-1, 1] (0 when either is empty
+ * or a zero vector). Compares over the shorter length when lengths differ. Vectors
  * from MambaSession.embed() are already L2-normalised — this reduces to a dot
- * product — but we normalise defensively for vectors from other sources.
+ * product — but we normalise defensively for vectors from other sources. Takes any
+ * numeric array, so a `Float32Array` embedding and a JSON-decoded `number[]` (a
+ * pgvector row, a KV entry) go through the same function.
  */
-export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/similarity/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CASxE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAUzE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/similarity/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CASxE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAUnF"}

package/dist/similarity/index.js

@@ -23,10 +23,12 @@ export function jaccardSimilarity(a, b) {
     return intersection / union;
 }
 /**
- * Cosine similarity between two vectors in the range [-1, 1] (0 when either is a
- * zero vector). Compares over the shorter length when lengths differ. Vectors
+ * Cosine similarity between two vectors in the range [-1, 1] (0 when either is empty
+ * or a zero vector). Compares over the shorter length when lengths differ. Vectors
  * from MambaSession.embed() are already L2-normalised — this reduces to a dot
- * product — but we normalise defensively for vectors from other sources.
+ * product — but we normalise defensively for vectors from other sources. Takes any
+ * numeric array, so a `Float32Array` embedding and a JSON-decoded `number[]` (a
+ * pgvector row, a KV entry) go through the same function.
  */
 export function cosineSimilarity(a, b) {
     const n = Math.min(a.length, b.length);

package/dist/similarity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/similarity/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,CAAc,EAAE,CAAc;IAC5D,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,YAAY,EAAE,CAAC;IACrC,CAAC;IACD,8DAA8D;IAC9D,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,YAAY,CAAC;IAC7C,OAAO,YAAY,GAAG,KAAK,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAe,EAAE,CAAe;IAC7D,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,GAAG,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzB,GAAG,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,EAAE,IAAK,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,EAAE,IAAK,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5C,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC;AACzC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/similarity/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,CAAc,EAAE,CAAc;IAC5D,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,YAAY,EAAE,CAAC;IACrC,CAAC;IACD,8DAA8D;IAC9D,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,YAAY,CAAC;IAC7C,OAAO,YAAY,GAAG,KAAK,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAoB,EAAE,CAAoB;IACvE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,GAAG,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzB,GAAG,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,EAAE,IAAK,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,EAAE,IAAK,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5C,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC;AACzC,CAAC"}

package/dist/wire/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * LLM wire primitives — the protocol-level pieces every client of an
+ * OpenAI/Anthropic/Gemini-style HTTP API needs, in ONE place:
+ *
+ *   • Server-Sent-Events `data:` framing — one line rule ({@link parseSseDataLine}),
+ *     applied to a whole buffered body ({@link parseSseDataFrames}) or to a live
+ *     byte stream ({@link readSseDataFrames});
+ *   • token-usage field reading across vendor shapes ({@link readUsageFields}) and
+ *     the Anthropic streaming usage fold ({@link AnthropicStreamUsage}).
+ *
+ * The package's bridges and the Builderforce gateway both frame and meter with
+ * these, so a fix to the line rule (a spaceless `data:{…}` frame, say) lands once.
+ * Zero-dependency and engine-free: the `@seanhogg/builderforce-memory/wire` subpath.
+ */
+export { parseSseDataLine, parseSseDataFrames, readSseDataFrames, isSseDoneLine } from './sse.js';
+export { finiteNumber, readUsageFields, AnthropicStreamUsage } from './usage.js';
+export type { UsageFields, AnthropicUsageTotals } from './usage.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wire/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClG,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACjF,YAAY,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/wire/index.js

@@ -0,0 +1,17 @@
+/**
+ * LLM wire primitives — the protocol-level pieces every client of an
+ * OpenAI/Anthropic/Gemini-style HTTP API needs, in ONE place:
+ *
+ *   • Server-Sent-Events `data:` framing — one line rule ({@link parseSseDataLine}),
+ *     applied to a whole buffered body ({@link parseSseDataFrames}) or to a live
+ *     byte stream ({@link readSseDataFrames});
+ *   • token-usage field reading across vendor shapes ({@link readUsageFields}) and
+ *     the Anthropic streaming usage fold ({@link AnthropicStreamUsage}).
+ *
+ * The package's bridges and the Builderforce gateway both frame and meter with
+ * these, so a fix to the line rule (a spaceless `data:{…}` frame, say) lands once.
+ * Zero-dependency and engine-free: the `@seanhogg/builderforce-memory/wire` subpath.
+ */
+export { parseSseDataLine, parseSseDataFrames, readSseDataFrames, isSseDoneLine } from './sse.js';
+export { finiteNumber, readUsageFields, AnthropicStreamUsage } from './usage.js';
+//# sourceMappingURL=index.js.map

package/dist/wire/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wire/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClG,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/wire/sse.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-Sent-Events `data:` framing.
+ *
+ * Every consumer of an SSE LLM stream does the same line-level dance: trim the line,
+ * keep only `data:` frames, skip empty payloads, `JSON.parse` the rest and skip
+ * anything malformed — and stop at the `[DONE]` sentinel, which ends an
+ * OpenAI-style stream (anything after it is not part of the response).
+ *
+ * The line rule is `slice(5).trim()`, which accepts both `data: {…}` and the
+ * spaceless `data:{…}` some providers emit — `slice(6)` silently drops the latter.
+ *
+ * Pure and defensive: a malformed frame is skipped, never thrown.
+ */
+/**
+ * One SSE line's decoded JSON payload, or `undefined` when the line is not a usable
+ * data frame (not a `data:` line, the `[DONE]` sentinel, empty, or malformed JSON).
+ */
+export declare function parseSseDataLine(line: string): unknown | undefined;
+/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
+export declare function isSseDoneLine(line: string): boolean;
+/** Every parsed `data:` frame of a whole, already-buffered SSE body, up to `[DONE]`. */
+export declare function parseSseDataFrames(raw: string): Generator<unknown>;
+/**
+ * Every parsed `data:` frame of a live SSE byte stream, as it arrives, up to `[DONE]`.
+ * A frame split across chunks is held until its line completes; the reader lock is
+ * released however iteration ends.
+ */
+export declare function readSseDataFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<unknown>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/wire/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/wire/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAUlE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,wFAAwF;AACxF,wBAAiB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAMnE;AAED;;;;GAIG;AACH,wBAAuB,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAuBlG"}

package/dist/wire/sse.js

@@ -0,0 +1,81 @@
+/**
+ * Server-Sent-Events `data:` framing.
+ *
+ * Every consumer of an SSE LLM stream does the same line-level dance: trim the line,
+ * keep only `data:` frames, skip empty payloads, `JSON.parse` the rest and skip
+ * anything malformed — and stop at the `[DONE]` sentinel, which ends an
+ * OpenAI-style stream (anything after it is not part of the response).
+ *
+ * The line rule is `slice(5).trim()`, which accepts both `data: {…}` and the
+ * spaceless `data:{…}` some providers emit — `slice(6)` silently drops the latter.
+ *
+ * Pure and defensive: a malformed frame is skipped, never thrown.
+ */
+/**
+ * One SSE line's decoded JSON payload, or `undefined` when the line is not a usable
+ * data frame (not a `data:` line, the `[DONE]` sentinel, empty, or malformed JSON).
+ */
+export function parseSseDataLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('data:'))
+        return undefined;
+    const data = trimmed.slice(5).trim();
+    if (!data || data === '[DONE]')
+        return undefined;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
+export function isSseDoneLine(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith('data:') && trimmed.slice(5).trim() === '[DONE]';
+}
+/** Every parsed `data:` frame of a whole, already-buffered SSE body, up to `[DONE]`. */
+export function* parseSseDataFrames(raw) {
+    for (const line of raw.split('\n')) {
+        if (isSseDoneLine(line))
+            return;
+        const parsed = parseSseDataLine(line);
+        if (parsed !== undefined)
+            yield parsed;
+    }
+}
+/**
+ * Every parsed `data:` frame of a live SSE byte stream, as it arrives, up to `[DONE]`.
+ * A frame split across chunks is held until its line completes; the reader lock is
+ * released however iteration ends.
+ */
+export async function* readSseDataFrames(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop(); // split() always yields ≥1 element
+            for (const line of lines) {
+                if (isSseDoneLine(line))
+                    return;
+                const parsed = parseSseDataLine(line);
+                if (parsed !== undefined)
+                    yield parsed;
+            }
+        }
+        buffer += decoder.decode();
+        const tail = parseSseDataLine(buffer);
+        if (tail !== undefined)
+            yield tail;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/wire/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/wire/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,IAAY;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,QAAQ,CAAC;AAC/E,CAAC;AAED,wFAAwF;AACxF,MAAM,SAAS,CAAC,CAAC,kBAAkB,CAAC,GAAW;IAC3C,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,aAAa,CAAC,IAAI,CAAC;YAAE,OAAO;QAChC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,MAAM,CAAC;IAC3C,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,iBAAiB,CAAC,IAAgC;IACrE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;YACV,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAY,CAAC,CAAC,mCAAmC;YACnE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,aAAa,CAAC,IAAI,CAAC;oBAAE,OAAO;gBAChC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;gBACtC,IAAI,MAAM,KAAK,SAAS;oBAAE,MAAM,MAAM,CAAC;YAC3C,CAAC;QACL,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,CAAC;IACvC,CAAC;YAAS,CAAC;QACP,MAAM,CAAC,WAAW,EAAE,CAAC;IACzB,CAAC;AACL,CAAC"}

package/dist/wire/usage.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Token-usage reading across vendor shapes.
+ *
+ * Two wire shapes reach a client: OpenAI-style `prompt_tokens`/`completion_tokens`
+ * (cached reads under `prompt_tokens_details.cached_tokens`, INCLUDED in
+ * `prompt_tokens`) and Anthropic-style `input_tokens`/`output_tokens` (cache reads
+ * and writes as separate top-level fields, EXCLUDED from `input_tokens`).
+ * {@link readUsageFields} reads either into one set of optional fields, keeping
+ * "absent" distinct from 0; each consumer then maps them to its own accounting.
+ *
+ * Streaming Anthropic responses split usage across events — input and cache on
+ * `message_start.message.usage`, output accumulating on `message_delta.usage` — and
+ * every count is cumulative, so {@link AnthropicStreamUsage} keeps the largest seen.
+ */
+/** A finite number, or `undefined` for null/undefined/non-numeric input. */
+export declare function finiteNumber(v: unknown): number | undefined;
+/** Usage as the vendor reported it. Every field is absent when the vendor omitted it. */
+export interface UsageFields {
+    /** `prompt_tokens`, else `input_tokens`. */
+    promptTokens?: number;
+    /** `completion_tokens`, else `output_tokens`. */
+    completionTokens?: number;
+    totalTokens?: number;
+    /** `cache_read_input_tokens`, else `prompt_tokens_details.cached_tokens`. */
+    cacheReadTokens?: number;
+    /** `cache_creation_input_tokens`. */
+    cacheCreationTokens?: number;
+}
+/** Reads a vendor `usage` object of either shape. Anything that is not an object reads as empty. */
+export declare function readUsageFields(u: unknown): UsageFields;
+/** The totals of one Anthropic stream. Input excludes both cache counts. */
+export interface AnthropicUsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** `message_start.message.model`, when the stream named it. */
+    model?: string;
+}
+/** Folds the usage events of one Anthropic Messages stream. Feed it every parsed frame. */
+export declare class AnthropicStreamUsage {
+    private readonly totals;
+    observe(frame: unknown): void;
+    result(): AnthropicUsageTotals;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/wire/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/wire/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI3D;AAED,yFAAyF;AACzF,MAAM,WAAW,WAAW;IACxB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,oGAAoG;AACpG,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,CAoBvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2FAA2F;AAC3F,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyG;IAEhI,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAmB7B,MAAM,IAAI,oBAAoB;CAGjC"}

package/dist/wire/usage.js

@@ -0,0 +1,78 @@
+/**
+ * Token-usage reading across vendor shapes.
+ *
+ * Two wire shapes reach a client: OpenAI-style `prompt_tokens`/`completion_tokens`
+ * (cached reads under `prompt_tokens_details.cached_tokens`, INCLUDED in
+ * `prompt_tokens`) and Anthropic-style `input_tokens`/`output_tokens` (cache reads
+ * and writes as separate top-level fields, EXCLUDED from `input_tokens`).
+ * {@link readUsageFields} reads either into one set of optional fields, keeping
+ * "absent" distinct from 0; each consumer then maps them to its own accounting.
+ *
+ * Streaming Anthropic responses split usage across events — input and cache on
+ * `message_start.message.usage`, output accumulating on `message_delta.usage` — and
+ * every count is cumulative, so {@link AnthropicStreamUsage} keeps the largest seen.
+ */
+/** A finite number, or `undefined` for null/undefined/non-numeric input. */
+export function finiteNumber(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** Reads a vendor `usage` object of either shape. Anything that is not an object reads as empty. */
+export function readUsageFields(u) {
+    const out = {};
+    if (!u || typeof u !== 'object')
+        return out;
+    const usage = u;
+    const prompt = finiteNumber(usage['prompt_tokens'] ?? usage['input_tokens']);
+    const completion = finiteNumber(usage['completion_tokens'] ?? usage['output_tokens']);
+    const total = finiteNumber(usage['total_tokens']);
+    if (prompt !== undefined)
+        out.promptTokens = prompt;
+    if (completion !== undefined)
+        out.completionTokens = completion;
+    if (total !== undefined)
+        out.totalTokens = total;
+    const details = usage['prompt_tokens_details'];
+    const cachedFromDetails = details && typeof details === 'object'
+        ? finiteNumber(details['cached_tokens'])
+        : undefined;
+    const cacheRead = finiteNumber(usage['cache_read_input_tokens']) ?? cachedFromDetails;
+    const cacheCreation = finiteNumber(usage['cache_creation_input_tokens']);
+    if (cacheRead !== undefined)
+        out.cacheReadTokens = cacheRead;
+    if (cacheCreation !== undefined)
+        out.cacheCreationTokens = cacheCreation;
+    return out;
+}
+/** Folds the usage events of one Anthropic Messages stream. Feed it every parsed frame. */
+export class AnthropicStreamUsage {
+    totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+    observe(frame) {
+        if (!frame || typeof frame !== 'object')
+            return;
+        const ev = frame;
+        let usage;
+        if (ev.type === 'message_start') {
+            usage = ev.message?.usage;
+            if (typeof ev.message?.model === 'string')
+                this.totals.model = ev.message.model;
+        }
+        else if (ev.type === 'message_delta') {
+            usage = ev.usage;
+        }
+        if (!usage || typeof usage !== 'object')
+            return;
+        const u = usage;
+        const keep = (current, v) => Math.max(current, finiteNumber(v) ?? 0);
+        this.totals.inputTokens = keep(this.totals.inputTokens, u['input_tokens']);
+        this.totals.outputTokens = keep(this.totals.outputTokens, u['output_tokens']);
+        this.totals.cacheReadTokens = keep(this.totals.cacheReadTokens, u['cache_read_input_tokens']);
+        this.totals.cacheCreationTokens = keep(this.totals.cacheCreationTokens, u['cache_creation_input_tokens']);
+    }
+    result() {
+        return { ...this.totals };
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/wire/usage.js.map

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