@seanhogg/builderforce-memory 2026.9.29 → 2026.9.31

package/src/retrieval/HybridRetriever.ts

@@ -15,7 +15,8 @@
  */
 
 import { bm25Search, type Bm25Options } from './bm25.js';
-import { reciprocalRankFusion, maximalMarginalRelevance, type MmrCandidate } from './fusion.js';
+import { reciprocalRankFusion } from './fusion.js';
+import { maximalMarginalRelevance, type MmrCandidate } from './mmr.js';
 import { denseSearch } from './hnsw.js';
 
 export interface RetrievalCandidate {

package/src/retrieval/decay.ts

@@ -0,0 +1,29 @@
+/**
+ * Recency decay — exponential half-life down-weighting of an older result's score.
+ *
+ * `score · e^(−λ·age)` with `λ = ln2 / halfLife`, so a result `halfLife` days old
+ * keeps half its score. The maths is here; deciding how old a result IS (a dated
+ * file name, an mtime, a `created_at` column) and which results never decay stays
+ * with the caller, because that is a property of its corpus.
+ *
+ * Pure and zero-dependency.
+ */
+
+/** The decay rate for a half-life in days; 0 (no decay) for a non-positive or non-finite half-life. */
+export function toDecayLambda(halfLifeDays: number): number {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0) return 0;
+    return Math.LN2 / halfLifeDays;
+}
+
+/** The factor in (0,1] a score is multiplied by at `ageInDays` (negative ages count as 0). */
+export function calculateTemporalDecayMultiplier(params: { ageInDays: number; halfLifeDays: number }): number {
+    const lambda = toDecayLambda(params.halfLifeDays);
+    const clampedAge = Math.max(0, params.ageInDays);
+    if (lambda <= 0 || !Number.isFinite(clampedAge)) return 1;
+    return Math.exp(-lambda * clampedAge);
+}
+
+/** `score` decayed for its age. */
+export function applyTemporalDecayToScore(params: { score: number; ageInDays: number; halfLifeDays: number }): number {
+    return params.score * calculateTemporalDecayMultiplier(params);
+}

package/src/retrieval/fusion.ts

@@ -1,18 +1,13 @@
 /**
- * Rank fusion + diversity reranking.
- *
- *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
- *     rankings into one list without needing the two score scales to be
- *     commensurable — it fuses on RANK, not raw score. This is the standard,
- *     parameter-light way to combine hybrid retrieval signals.
- *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
- *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ * Reciprocal Rank Fusion (RRF) — merges rankings (dense vector, sparse BM25, …) into
+ * one list without needing their score scales to be commensurable: it fuses on
+ * RANK, not raw score. The standard, parameter-light way to combine hybrid signals.
+ * Score-based fusion lives in {@link ./weightedFusion}; diversity reranking in
+ * {@link ./mmr}.
  *
  * Pure and zero-dependency.
  */
 
-import { cosineSimilarity } from '../similarity/index.js';
-
 export interface RankedList {
     /** Ordered ids, most relevant first. */
     ids: string[];
@@ -25,60 +20,32 @@ export interface FusedHit {
     score: number;
 }
 
+/** The canonical TREC damping constant for {@link rrfTerm}. */
+export const RRF_DEFAULT_K = 60;
+
+/**
+ * One list's RRF contribution for the item at zero-based `rank`: `1 / (k + rank + 1)`.
+ * Exported for a ranker that blends the rank signal into a score of its own rather
+ * than fusing whole lists.
+ */
+export function rrfTerm(rank: number, k: number = RRF_DEFAULT_K): number {
+    return 1 / (k + rank + 1);
+}
+
 /**
  * Reciprocal Rank Fusion over any number of ranked lists.
  * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
  * contribution of low-ranked items; the canonical TREC value.
  */
-export function reciprocalRankFusion(lists: RankedList[], k = 60): FusedHit[] {
+export function reciprocalRankFusion(lists: RankedList[], k = RRF_DEFAULT_K): FusedHit[] {
     const acc = new Map<string, number>();
     for (const list of lists) {
         const weight = list.weight ?? 1;
         list.ids.forEach((id, rank) => {
-            acc.set(id, (acc.get(id) ?? 0) + weight / (k + rank + 1));
+            acc.set(id, (acc.get(id) ?? 0) + weight * rrfTerm(rank, k));
         });
     }
     return [...acc.entries()]
         .map(([id, score]) => ({ id, score }))
         .sort((a, b) => b.score - a.score);
 }
-
-export interface MmrCandidate {
-    id: string;
-    vector: Float32Array;
-}
-
-/**
- * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
- * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
- * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
- * should be filtered out by the caller (they cannot be MMR-scored).
- */
-export function maximalMarginalRelevance(
-    queryVec: Float32Array,
-    candidates: MmrCandidate[],
-    topK: number,
-    lambda = 0.7,
-): string[] {
-    const remaining = [...candidates];
-    const selected: MmrCandidate[] = [];
-    const relevance = new Map<string, number>();
-    for (const c of remaining) relevance.set(c.id, cosineSimilarity(queryVec, c.vector));
-
-    while (selected.length < topK && remaining.length > 0) {
-        let bestIdx = 0;
-        let bestScore = -Infinity;
-        for (let i = 0; i < remaining.length; i++) {
-            const c = remaining[i]!;
-            let maxSimToSelected = 0;
-            for (const s of selected) {
-                const sim = cosineSimilarity(c.vector, s.vector);
-                if (sim > maxSimToSelected) maxSimToSelected = sim;
-            }
-            const mmr = lambda * relevance.get(c.id)! - (1 - lambda) * maxSimToSelected;
-            if (mmr > bestScore) { bestScore = mmr; bestIdx = i; }
-        }
-        selected.push(remaining.splice(bestIdx, 1)[0]!);
-    }
-    return selected.map(s => s.id);
-}

package/src/retrieval/index.ts

@@ -1,19 +1,37 @@
 /**
- * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ * Retrieval layer — chunking, BM25, rank and score fusion, MMR, recency decay, the
+ * similarity primitives they rest on, and the HybridRetriever.
  *
- * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
- * dense+sparse search, reranking), implemented zero-dependency so they run in the
- * browser, Node, and the SSM runtime alike.
+ * Zero-dependency and engine-free: this is the `@seanhogg/builderforce-memory/retrieval`
+ * subpath, which a Cloudflare Worker, Node and the browser can all import without
+ * pulling the WebGPU engine. Every host ranks with THESE functions rather than a copy.
  */
 
+export { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
+
 export { chunkText } from './chunk.js';
 export type { Chunk, ChunkOptions } from './chunk.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 { reciprocalRankFusion, rrfTerm, RRF_DEFAULT_K } from './fusion.js';
+export type { RankedList, FusedHit } from './fusion.js';
+
+export { mmrSelect, maximalMarginalRelevance, textMaximalMarginalRelevance } from './mmr.js';
+export type { MmrSelectOptions, MmrCandidate, TextMmrItem } from './mmr.js';
+
+export {
+    DEFAULT_HYBRID_VECTOR_WEIGHT,
+    DEFAULT_HYBRID_TEXT_WEIGHT,
+    normalizeHybridWeights,
+    hybridScore,
+    bm25RankToScore,
+    fuseHybridArms,
+} from './weightedFusion.js';
+export type { HybridWeights, HybridArmScores } from './weightedFusion.js';
+
+export { toDecayLambda, calculateTemporalDecayMultiplier, applyTemporalDecayToScore } from './decay.js';
 
 export { hybridRetrieve } from './HybridRetriever.js';
 export type {

package/src/retrieval/mmr.ts

@@ -0,0 +1,126 @@
+/**
+ * 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';
+
+export interface MmrSelectOptions<T> {
+    /** Relevance of one candidate, on the same scale as {@link similarity}. */
+    relevance: (item: T) => number;
+    /** Similarity of two candidates. */
+    similarity: (a: T, b: T) => number;
+    /** 0 = maximum diversity, 1 = maximum relevance. Default 0.7. */
+    lambda?: number;
+    /** Stop after this many picks. Default: every candidate. */
+    topK?: number;
+    /**
+     * Breaks an exact MMR tie in favour of the higher value. Without it the earlier
+     * candidate wins, so input order decides.
+     */
+    tieScore?: (item: T) => number;
+}
+
+/** Greedy MMR selection. Returns the picked candidates in pick order. */
+export function mmrSelect<T>(items: readonly T[], opts: MmrSelectOptions<T>): T[] {
+    const lambda = opts.lambda ?? 0.7;
+    const limit = Math.min(opts.topK ?? items.length, items.length);
+    const remaining = [...items];
+    const relevance = new Map<T, number>();
+    for (const item of remaining) relevance.set(item, opts.relevance(item));
+
+    const selected: T[] = [];
+    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;
+}
+
+export interface MmrCandidate {
+    id: string;
+    vector: Float32Array;
+}
+
+/**
+ * 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: Float32Array,
+    candidates: MmrCandidate[],
+    topK: number,
+    lambda = 0.7,
+): string[] {
+    return mmrSelect(candidates, {
+        relevance: (c) => cosineSimilarity(queryVec, c.vector),
+        similarity: (a, b) => cosineSimilarity(a.vector, b.vector),
+        lambda,
+        topK,
+    }).map((c) => c.id);
+}
+
+export interface TextMmrItem {
+    id: string;
+    /** The candidate's fused relevance score (any scale — it is normalised here). */
+    score: number;
+    /** The text diversity is judged on. */
+    content: string;
+}
+
+/**
+ * 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<T extends TextMmrItem>(items: readonly T[], lambda = 0.7): T[] {
+    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<string, Set<string>>();
+    for (const item of items) tokens.set(item.id, new Set(tokenize(item.content)));
+    const tokensOf = (item: T) => 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,
+    });
+}

package/src/retrieval/weightedFusion.ts

@@ -0,0 +1,101 @@
+/**
+ * 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;
+
+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 function normalizeHybridWeights(vectorWeight?: number, textWeight?: number): HybridWeights {
+    const clamp = (n: number | undefined, fallback: number): number =>
+        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 };
+}
+
+/** 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 function hybridScore(scores: HybridArmScores, weights: HybridWeights): number {
+    const v = Number.isFinite(scores.vectorScore) ? (scores.vectorScore as number) : 0;
+    const t = Number.isFinite(scores.textScore) ? (scores.textScore as number) : 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: number): number {
+    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<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[] {
+    const weights = normalizeHybridWeights(params.weights?.vectorWeight, params.weights?.textWeight);
+    const byId = new Map<string, { row: TVector | TText; scores: HybridArmScores }>();
+    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);
+}

package/src/similarity/index.ts

@@ -24,12 +24,14 @@ export 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 function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+export function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number {
     const n = Math.min(a.length, b.length);
     let dot = 0, na = 0, nb = 0;
     for (let i = 0; i < n; i++) {

package/src/wire/chatClient.ts

@@ -0,0 +1,196 @@
+/**
+ * The OpenAI-compatible chat-completions client — ONE request builder, error mapping
+ * and stream reader for every caller that speaks `/chat/completions`: this package's
+ * `OpenAIBridge` / `FetchBridge`, and any host that reaches models through an
+ * OpenAI-compatible gateway (tools, streamed tool-call deltas, vendor extras).
+ *
+ * The body carries exactly what the request states — no sampling defaults are added
+ * here, so a routing gateway that picks the model and limits can be called with none.
+ * Callers that want defaults (the bridges) state them.
+ *
+ * Zero-dependency and engine-free (part of the `/wire` subpath).
+ */
+
+import { readSseDataFrames } from './sse.js';
+
+/** An OpenAI-compatible chat message. */
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Text, or an OpenAI multi-part array (text + `image_url`, …). */
+    content?: string | null | unknown[];
+    tool_calls?: unknown;
+    tool_call_id?: string;
+    [k: string]: unknown;
+}
+
+/** An OpenAI-compatible function-tool schema. */
+export interface ChatToolSchema {
+    type: 'function';
+    function: { name: string; description: string; parameters: Record<string, unknown> };
+}
+
+export interface ChatRequest {
+    messages: ChatMessage[];
+    tools?: ChatToolSchema[];
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    /**
+     * On a stream, ask for the closing usage block (`stream_options.include_usage`).
+     * Opt-in: not every OpenAI-compatible server accepts the field.
+     */
+    includeUsage?: boolean;
+    /** Vendor extras merged into the body last (a routing `provider`, `response_format`, …). */
+    extra?: Record<string, unknown>;
+}
+
+export interface ChatToolCall {
+    id?: string;
+    type?: string;
+    function?: { name?: string; arguments?: string };
+}
+
+export interface ChatResult {
+    /** The reply text ('' when there was none — e.g. a tool-call-only turn). */
+    content: string;
+    /** True when the server sent text content (a string), false when it sent none. */
+    hasTextContent: boolean;
+    toolCalls: ChatToolCall[];
+    finishReason?: string;
+    /** The model the server reports having used. */
+    model?: string;
+    /** The raw `usage` object, when the server sent one — read it with `readUsageFields`. */
+    usage?: unknown;
+}
+
+/** Incremental events of a streamed completion. */
+export type ChatStreamEvent =
+    | { type: 'text-delta'; delta: string }
+    | { type: 'tool-call'; index: number; id?: string; name?: string; argsDelta?: string }
+    | { type: 'done'; result: ChatResult };
+
+export interface ChatClient {
+    /** The OpenAI-style base, e.g. `https://api.openai.com/v1`; `/chat/completions` is appended. */
+    baseUrl: string;
+    apiKey: string;
+    /** Abort a request after this long. Default: no limit beyond the caller's signal. */
+    timeoutMs?: number;
+}
+
+/** A non-2xx answer, with the status and (bounded) body kept apart for the caller's message. */
+export class ChatCompletionError extends Error {
+    constructor(readonly status: number, readonly body: string) {
+        super(`chat completion failed with HTTP ${status}: ${body}`);
+        this.name = 'ChatCompletionError';
+    }
+}
+
+const ERROR_BODY_CHARS = 300;
+
+function chatBody(req: ChatRequest, stream: boolean): string {
+    return JSON.stringify({
+        ...(req.model ? { model: req.model } : {}),
+        messages: req.messages,
+        ...(req.tools?.length ? { tools: req.tools, tool_choice: 'auto' } : {}),
+        ...(typeof req.maxTokens === 'number' ? { max_tokens: req.maxTokens } : {}),
+        ...(typeof req.temperature === 'number' ? { temperature: req.temperature } : {}),
+        ...(typeof req.topP === 'number' ? { top_p: req.topP } : {}),
+        ...(stream ? { stream: true } : {}),
+        // Without include_usage a streamed response carries no usage block at all.
+        ...(stream && req.includeUsage ? { stream_options: { include_usage: true } } : {}),
+        ...(req.extra ?? {}),
+    });
+}
+
+async function post(client: ChatClient, req: ChatRequest, stream: boolean, signal?: AbortSignal): Promise<Response> {
+    const timeout = client.timeoutMs ? AbortSignal.timeout(client.timeoutMs) : undefined;
+    const res = await fetch(`${client.baseUrl.replace(/\/$/, '')}/chat/completions`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${client.apiKey}`,
+            ...(stream ? { Accept: 'text/event-stream' } : {}),
+        },
+        body: chatBody(req, stream),
+        signal: signal && timeout ? AbortSignal.any([signal, timeout]) : (signal ?? timeout),
+    });
+    if (!res.ok || (stream && !res.body)) {
+        const body = await res.text().catch(() => '');
+        throw new ChatCompletionError(res.status, body.slice(0, ERROR_BODY_CHARS));
+    }
+    return res;
+}
+
+/** One non-streamed completion. Throws {@link ChatCompletionError} on a non-2xx answer. */
+export async function chatComplete(client: ChatClient, req: ChatRequest, signal?: AbortSignal): Promise<ChatResult> {
+    const res = await post(client, req, false, signal);
+    const json = (await res.json().catch(() => null)) as {
+        model?: unknown;
+        usage?: unknown;
+        choices?: Array<{ message?: { content?: unknown; tool_calls?: unknown }; finish_reason?: string }>;
+    } | null;
+    const choice = json?.choices?.[0];
+    const msg = choice?.message;
+    return {
+        content: typeof msg?.content === 'string' ? msg.content : '',
+        hasTextContent: typeof msg?.content === 'string',
+        toolCalls: Array.isArray(msg?.tool_calls) ? (msg.tool_calls as ChatToolCall[]) : [],
+        finishReason: choice?.finish_reason,
+        ...(typeof json?.model === 'string' ? { model: json.model } : {}),
+        ...(json?.usage !== undefined ? { usage: json.usage } : {}),
+    };
+}
+
+/**
+ * A streamed completion as events: text and tool-call deltas as they arrive, then one
+ * `done` carrying the assembled result (tool-call arguments concatenated per index).
+ */
+export async function* chatStream(client: ChatClient, req: ChatRequest, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent> {
+    const res = await post(client, req, true, signal);
+    let content = '';
+    let finishReason: string | undefined;
+    let model: string | undefined;
+    let usage: unknown;
+    const calls: Array<{ id?: string; name?: string; args: string }> = [];
+
+    for await (const frame of readSseDataFrames(res.body!)) {
+        const chunk = frame as {
+            model?: unknown;
+            usage?: unknown;
+            choices?: Array<{
+                delta?: { content?: unknown; tool_calls?: Array<{ index?: number; id?: string; function?: { name?: string; arguments?: string } }> };
+                finish_reason?: string;
+            }>;
+        };
+        if (typeof chunk.model === 'string') model = chunk.model;
+        if (chunk.usage) usage = chunk.usage;
+        const choice = chunk.choices?.[0];
+        if (!choice) continue;
+        if (choice.finish_reason) finishReason = choice.finish_reason;
+        const delta = choice.delta;
+        if (typeof delta?.content === 'string' && delta.content) {
+            content += delta.content;
+            yield { type: 'text-delta', delta: delta.content };
+        }
+        for (const tc of Array.isArray(delta?.tool_calls) ? delta.tool_calls : []) {
+            const index = typeof tc.index === 'number' ? tc.index : 0;
+            const acc = (calls[index] ??= { args: '' });
+            if (tc.id) acc.id = tc.id;
+            if (tc.function?.name) acc.name = tc.function.name;
+            const argsDelta = tc.function?.arguments;
+            if (typeof argsDelta === 'string') acc.args += argsDelta;
+            yield { type: 'tool-call', index, id: tc.id, name: tc.function?.name, argsDelta };
+        }
+    }
+
+    const result: ChatResult = {
+        content,
+        hasTextContent: content !== '',
+        finishReason,
+        toolCalls: calls.filter(Boolean).map((t) => ({ id: t.id, type: 'function', function: { name: t.name, arguments: t.args } })),
+        ...(model ? { model } : {}),
+        ...(usage !== undefined ? { usage } : {}),
+    };
+    yield { type: 'done', result };
+}

package/src/wire/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { sseDataPayload, parseSseDataLine, parseSseDataFrames, readSseDataPayloads, readSseDataFrames, isSseDoneLine } from './sse.js';
+export { finiteNumber, readUsageFields, AnthropicStreamUsage } from './usage.js';
+export type { UsageFields, AnthropicUsageTotals } from './usage.js';
+export { chatComplete, chatStream, ChatCompletionError } from './chatClient.js';
+export type { ChatClient, ChatMessage, ChatToolSchema, ChatRequest, ChatToolCall, ChatResult, ChatStreamEvent } from './chatClient.js';