@seanhogg/builderforce-memory 2026.6.18

package/src/session/streaming.ts

@@ -0,0 +1,97 @@
+/**
+ * streaming.ts – AsyncIterable token streaming adapter for the MambaSession layer.
+ *
+ * Wraps the step-by-step generation loop from MambaModel so that each
+ * token is yielded immediately after sampling, enabling real-time streaming UIs.
+ */
+
+import type { HybridMambaModel, SamplingOptions } from '@seanhogg/builderforce-memory-engine';
+
+/** Minimum effective temperature — avoids division by zero in sampling. */
+const MIN_TEMPERATURE = 1e-7;
+
+/**
+ * Yields one token ID at a time, applying the same sampling logic as
+ * `MambaModel.generate()` but yielding each step incrementally.
+ */
+export async function* tokenStream(
+    model: HybridMambaModel,
+    promptIds: number[],
+    maxNewTokens: number,
+    samplingOpts: SamplingOptions = {},
+): AsyncGenerator<number> {
+    const { temperature = 1.0, topK = 50, topP = 0.9 } = samplingOpts;
+    const { vocabSize, eosId } = model.config;
+
+    // ids is declared const because the variable itself is never reassigned;
+    // ids.push() mutates the array contents, which const allows.
+    const ids = [...promptIds];
+
+    for (let step = 0; step < maxNewTokens; step++) {
+        const { logits } = await model.forward(
+            new Uint32Array(ids),
+            1,
+            ids.length,
+        );
+
+        // Only the last token position's logits are used for next-token prediction
+        const lastLogits = logits.slice(
+            (ids.length - 1) * vocabSize,
+            ids.length * vocabSize,
+        );
+
+        const nextId = sampleToken(lastLogits, { temperature, topK, topP });
+        ids.push(nextId);
+        yield nextId;
+
+        if (nextId === eosId) break;
+    }
+}
+
+// ── Sampling (mirrors the private helper in mamba_model.js) ──────────────────
+
+function sampleToken(
+    logits: Float32Array,
+    { temperature = 1.0, topK = 50, topP = 0.9 } = {},
+): number {
+    const n = logits.length;
+
+    // Temperature scaling
+    const scaled = new Float32Array(n);
+    for (let i = 0; i < n; i++) scaled[i] = logits[i]! / Math.max(temperature, MIN_TEMPERATURE);
+
+    // Softmax (numerically stable)
+    let maxL = -Infinity;
+    for (let i = 0; i < n; i++) if (scaled[i]! > maxL) maxL = scaled[i]!;
+    let sumE = 0;
+    const exps = new Float32Array(n);
+    for (let i = 0; i < n; i++) {
+        exps[i] = Math.exp(scaled[i]! - maxL);
+        sumE += exps[i]!;
+    }
+
+    // Top-K sort
+    const indices = Array.from({ length: n }, (_, i) => i)
+        .sort((a, b) => exps[b]! - exps[a]!);
+    const topKIndices = indices.slice(0, topK);
+
+    // Nucleus (Top-P) filtering
+    let cumSum = 0;
+    const nucleus: number[] = [];
+    for (const idx of topKIndices) {
+        cumSum += exps[idx]! / sumE;
+        nucleus.push(idx);
+        if (cumSum >= topP) break;
+    }
+
+    // Sample from nucleus
+    let nucleusSum = 0;
+    for (const idx of nucleus) nucleusSum += exps[idx]!;
+    const threshold = Math.random() * nucleusSum;
+    let acc = 0;
+    for (const idx of nucleus) {
+        acc += exps[idx]!;
+        if (acc >= threshold) return idx;
+    }
+    return nucleus[nucleus.length - 1]!;
+}

package/src/session/tokenizer.ts

@@ -0,0 +1,18 @@
+/**
+ * Tokenizer – pluggable tokenizer interface for MambaSession.
+ *
+ * Pass a custom implementation via `MambaSessionOptions.tokenizer` to bypass
+ * the default Qwen2.5-Coder BPETokenizer.  This is useful for:
+ *   - Unit-testing with a stub tokenizer (no network required)
+ *   - Using a pre-built tokenizer from HuggingFace Transformers.js
+ *   - Domain-specific vocabulary (e.g. code, biomedical, multilingual)
+ */
+
+export interface Tokenizer {
+    /** Encodes `text` into a sequence of token IDs. */
+    encode(text: string): number[];
+    /** Decodes a sequence of token IDs back to a string. */
+    decode(tokens: number[]): string;
+    /** The total number of tokens in this tokenizer's vocabulary. */
+    readonly vocabSize: number;
+}

package/src/similarity/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Text + vector similarity primitives.
+ *
+ * Shared by the MemoryStore (semantic recall) and the SemanticCache
+ * (embedding-keyed response cache) so the cosine/Jaccard maths live in exactly
+ * one place rather than being duplicated per consumer.
+ */
+
+/** Splits text into lowercase word tokens, removing punctuation. */
+export function tokenize(text: string): string[] {
+    return text.toLowerCase().split(/[\s\W]+/).filter(Boolean);
+}
+
+/** Jaccard similarity between two token sets: |A ∩ B| / |A ∪ B|. */
+export function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
+    if (a.size === 0 && b.size === 0) return 1;
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token)) intersection++;
+    }
+    // Both-empty is handled above, so `union` is always > 0 here.
+    const union = a.size + b.size - intersection;
+    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
+ * from MambaSession.embed() are already L2-normalised — this reduces to a dot
+ * product — but we normalise defensively for vectors from other sources.
+ */
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+    const n = Math.min(a.length, b.length);
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < n; i++) {
+        dot += a[i]! * b[i]!;
+        na  += a[i]! * a[i]!;
+        nb  += b[i]! * b[i]!;
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    return denom === 0 ? 0 : dot / denom;
+}