@octoseq/mir 0.1.0-main.2e286ce

package/src/search/featureVectorV1.ts

@@ -0,0 +1,123 @@
+import type { MirFingerprintV1 } from "./fingerprintV1";
+
+export type MirFeatureVectorSlice = {
+    offset: number;
+    length: number;
+};
+
+export type MirFeatureVectorLayoutV1 = {
+    dim: number;
+
+    // Foreground (query-length) window features
+    melMeanFg: MirFeatureVectorSlice;
+    melVarianceFg: MirFeatureVectorSlice;
+    onsetFg: MirFeatureVectorSlice;
+    mfccMeanFg?: MirFeatureVectorSlice;
+    mfccVarianceFg?: MirFeatureVectorSlice;
+
+    // Local contrast features (foreground - background-without-foreground)
+    melContrast?: MirFeatureVectorSlice;
+    onsetContrast?: MirFeatureVectorSlice;
+    mfccMeanContrast?: MirFeatureVectorSlice;
+    mfccVarianceContrast?: MirFeatureVectorSlice;
+};
+
+export function makeFeatureVectorLayoutV1(params: {
+    melDim: number;
+    mfccDim?: number;
+    includeContrast?: boolean;
+}): MirFeatureVectorLayoutV1 {
+    const melDim = Math.max(0, params.melDim);
+    const mfccDim = Math.max(0, params.mfccDim ?? 0);
+    const includeContrast = params.includeContrast ?? true;
+
+    let offset = 0;
+    const melMeanFg: MirFeatureVectorSlice = { offset, length: melDim };
+    offset += melDim;
+
+    const melVarianceFg: MirFeatureVectorSlice = { offset, length: melDim };
+    offset += melDim;
+
+    const onsetFg: MirFeatureVectorSlice = { offset, length: 3 };
+    offset += 3;
+
+    const layout: MirFeatureVectorLayoutV1 = { dim: 0, melMeanFg, melVarianceFg, onsetFg };
+
+    if (mfccDim > 0) {
+        layout.mfccMeanFg = { offset, length: mfccDim };
+        layout.mfccVarianceFg = { offset: offset + mfccDim, length: mfccDim };
+        offset += mfccDim * 2;
+    }
+
+    if (includeContrast) {
+        layout.melContrast = { offset, length: melDim };
+        offset += melDim;
+
+        layout.onsetContrast = { offset, length: 3 };
+        offset += 3;
+
+        if (mfccDim > 0) {
+            layout.mfccMeanContrast = { offset, length: mfccDim };
+            layout.mfccVarianceContrast = { offset: offset + mfccDim, length: mfccDim };
+            offset += mfccDim * 2;
+        }
+    }
+
+    layout.dim = offset;
+
+    return layout;
+}
+
+export function writeFingerprintToFeatureVectorRawV1(
+    fp: MirFingerprintV1,
+    out: Float32Array,
+    offset: number,
+    layout: MirFeatureVectorLayoutV1
+): void {
+    // Mel mean
+    for (let i = 0; i < layout.melMeanFg.length; i++) {
+        out[offset + layout.melMeanFg.offset + i] = fp.mel.mean[i] ?? 0;
+    }
+    // Mel variance
+    for (let i = 0; i < layout.melVarianceFg.length; i++) {
+        out[offset + layout.melVarianceFg.offset + i] = fp.mel.variance[i] ?? 0;
+    }
+    // Onset stats
+    out[offset + layout.onsetFg.offset + 0] = fp.onset.mean;
+    out[offset + layout.onsetFg.offset + 1] = fp.onset.max;
+    out[offset + layout.onsetFg.offset + 2] = fp.onset.peakDensityHz;
+
+    // Optional MFCC stats
+    if (layout.mfccMeanFg && layout.mfccVarianceFg) {
+        const mean = fp.mfcc?.mean;
+        const variance = fp.mfcc?.variance;
+        for (let i = 0; i < layout.mfccMeanFg.length; i++) {
+            out[offset + layout.mfccMeanFg.offset + i] = mean?.[i] ?? 0;
+        }
+        for (let i = 0; i < layout.mfccVarianceFg.length; i++) {
+            out[offset + layout.mfccVarianceFg.offset + i] = variance?.[i] ?? 0;
+        }
+    }
+
+    // Fingerprints do not include local contrast; ensure contrast blocks are deterministic zeros.
+    if (layout.melContrast) {
+        out.fill(0, offset + layout.melContrast.offset, offset + layout.melContrast.offset + layout.melContrast.length);
+    }
+    if (layout.onsetContrast) {
+        out.fill(0, offset + layout.onsetContrast.offset, offset + layout.onsetContrast.offset + layout.onsetContrast.length);
+    }
+    if (layout.mfccMeanContrast) {
+        out.fill(
+            0,
+            offset + layout.mfccMeanContrast.offset,
+            offset + layout.mfccMeanContrast.offset + layout.mfccMeanContrast.length
+        );
+    }
+    if (layout.mfccVarianceContrast) {
+        out.fill(
+            0,
+            offset + layout.mfccVarianceContrast.offset,
+            offset + layout.mfccVarianceContrast.offset + layout.mfccVarianceContrast.length
+        );
+    }
+}

package/src/search/fingerprintV1.ts

@@ -0,0 +1,230 @@
+import type { MelSpectrogram } from "../dsp/mel";
+import type { Features2D } from "../dsp/mfcc";
+import { peakPick } from "../dsp/peakPick";
+
+export type MirFingerprintV1 = {
+  version: "v1";
+
+  /** Query window time bounds (seconds) – informational/debug only. */
+  t0: number;
+  t1: number;
+
+  // A) Mel-spectrogram statistics
+  mel: {
+    /** Mean mel vector across frames (weighted by frame energy, then unit-normalised). */
+    mean: Float32Array;
+    /** Variance mel vector across frames (weighted by frame energy). */
+    variance: Float32Array;
+  };
+
+  // B) Transient/activity statistics
+  onset: {
+    mean: number;
+    max: number;
+    /** Peaks per second, computed using peakPick() on the onset envelope. */
+    peakDensityHz: number;
+  };
+
+  // Optional: MFCC statistics (coeffs 1–12, exclude C0)
+  mfcc?: {
+    mean: Float32Array;
+    variance: Float32Array;
+  };
+};
+
+export type FingerprintFrameWindow = {
+  startFrame: number;
+  endFrameExclusive: number;
+};
+
+function l2Norm(v: Float32Array): number {
+  let sum = 0;
+  for (let i = 0; i < v.length; i++) {
+    const x = v[i] ?? 0;
+    sum += x * x;
+  }
+  return Math.sqrt(sum);
+}
+
+function weightedStats(
+  frames: Float32Array[], // raw frames
+  start: number,
+  endExclusive: number,
+  dimHint = 0
+): { mean: Float32Array; variance: Float32Array } {
+  const nFrames = Math.max(0, endExclusive - start);
+
+  // Handle empty window deterministically.
+  const first = frames[start];
+  const dim = first ? first.length : dimHint;
+
+  const mean = new Float32Array(dim);
+  const variance = new Float32Array(dim);
+
+  if (nFrames <= 0 || dim <= 0) return { mean, variance };
+
+  // 1. Calculate weights (L2 norms) and total weight
+  const weights = new Float32Array(nFrames);
+  const normFrames: Float32Array[] = new Array(nFrames);
+  let totalWeight = 0;
+
+  for (let i = 0; i < nFrames; i++) {
+    const f = frames[start + i];
+    if (!f) {
+      normFrames[i] = new Float32Array(dim);
+      continue;
+    }
+    const w = l2Norm(f);
+    weights[i] = w;
+    totalWeight += w;
+
+    // Normalize frame for shape statistics
+    const nf = new Float32Array(dim);
+    const d = w > 1e-12 ? w : 1;
+    for (let j = 0; j < dim; j++) nf[j] = f[j]! / d;
+    normFrames[i] = nf;
+  }
+
+  // fallback if all silence
+  if (totalWeight <= 1e-12) totalWeight = 1;
+
+  // 2. Weighted Mean
+  // Mean = sum(w_i * x_i) / sum(w_i)
+  for (let i = 0; i < nFrames; i++) {
+    const w = weights[i];
+    const nf = normFrames[i];
+    if (!w || w <= 0) continue;
+    const scale = w / totalWeight;
+    for (let j = 0; j < dim; j++) {
+      mean[j]! += nf![j]! * scale;
+    }
+  }
+
+  // 3. Weighted Variance
+  // Var = sum(w_i * (x_i - mean)^2) / sum(w_i)
+  for (let i = 0; i < nFrames; i++) {
+    const w = weights[i];
+    const nf = normFrames[i];
+    if (!w || w <= 0) continue;
+    const scale = w / totalWeight;
+    for (let j = 0; j < dim; j++) {
+      const diff = nf![j]! - mean[j]!;
+      variance[j]! += diff * diff * scale;
+    }
+  }
+
+  return { mean, variance };
+}
+
+function findFrameWindow(times: Float32Array, t0: number, t1: number): FingerprintFrameWindow {
+  // times are frame-center times; we include frames where t is within [t0,t1].
+  let start = 0;
+  while (start < times.length && (times[start] ?? 0) < t0) start++;
+
+  let end = start;
+  while (end < times.length && (times[end] ?? 0) <= t1) end++;
+
+  return { startFrame: start, endFrameExclusive: Math.max(start, end) };
+}
+
+/**
+ * Compute a deterministic v1 fingerprint for a time region [t0, t1].
+ *
+ * Loudness independence:
+ * - Uses energy-weighted statistics. Loud frames contribute more to the shape.
+ * - Resulting mean vector is effectively the average energy distribution direction.
+ */
+export function fingerprintV1(params: {
+  t0: number;
+  t1: number;
+  mel: MelSpectrogram;
+  onsetEnvelope: { times: Float32Array; values: Float32Array };
+  mfcc?: Features2D; // { times, values: Float32Array[] }
+  peakPick?: {
+    minIntervalSec?: number;
+    threshold?: number;
+    adaptiveFactor?: number;
+  };
+}): MirFingerprintV1 {
+  const { t0, t1, mel, onsetEnvelope, mfcc } = params;
+
+  const tt0 = Math.min(t0, t1);
+  const tt1 = Math.max(t0, t1);
+  const dur = Math.max(1e-6, tt1 - tt0);
+
+  const melDimHint = mel.melBands.find((f) => f?.length)?.length ?? 0;
+
+  // --- Mel stats
+  const melWindow = findFrameWindow(mel.times, tt0, tt1);
+  // Be careful not to slice/copy excessively, but here we need array of arrays for helper
+  // melBands is Array<Float32Array>
+  const melStats = weightedStats(mel.melBands, melWindow.startFrame, melWindow.endFrameExclusive, melDimHint);
+
+  // --- Onset stats (1D)
+  // NOTE: onsetEnvelope times should align with mel.times (as computed today), but
+  // we don't assume perfect equality; we window by time.
+  let onsetSum = 0;
+  let onsetMax = -Infinity;
+  let onsetN = 0;
+  for (let i = 0; i < onsetEnvelope.times.length; i++) {
+    const t = onsetEnvelope.times[i] ?? 0;
+    if (t < tt0 || t > tt1) continue;
+    const v = onsetEnvelope.values[i] ?? 0;
+    onsetSum += v;
+    onsetN++;
+    if (v > onsetMax) onsetMax = v;
+  }
+  const onsetMean = onsetN > 0 ? onsetSum / onsetN : 0;
+  const onsetMaxSafe = Number.isFinite(onsetMax) ? onsetMax : 0;
+
+  // Peaks per second
+  const peaks = peakPick(onsetEnvelope.times, onsetEnvelope.values, {
+    minIntervalSec: params.peakPick?.minIntervalSec,
+    threshold: params.peakPick?.threshold,
+    adaptive: params.peakPick?.adaptiveFactor
+      ? { method: "meanStd", factor: params.peakPick.adaptiveFactor }
+      : undefined,
+    strict: true,
+  });
+  const peaksInWindow = peaks.filter((p) => p.time >= tt0 && p.time <= tt1);
+  const peakDensityHz = peaksInWindow.length / dur;
+
+  // --- Optional MFCC (coeffs 1..12)
+  let mfccStats: MirFingerprintV1["mfcc"] | undefined;
+  const mfccDimHint = mfcc?.values.find((f) => f?.length)?.length ?? 0;
+
+  if (mfcc) {
+    const mfccWindow = findFrameWindow(mfcc.times, tt0, tt1);
+
+    // Exclude C0 and clamp to 1..12 inclusive.
+    // We must pre-process standard frames to slices for weightedStats to consume.
+    // Or we just consume them and slice inside?
+    // weightedStats takes Float32Array[].
+    const mfccFramesSliced: Float32Array[] = [];
+    for (let i = mfccWindow.startFrame; i < mfccWindow.endFrameExclusive; i++) {
+      const full = mfcc.values[i] ?? new Float32Array(0);
+      const start = Math.min(1, full.length);
+      const end = Math.min(13, full.length);
+      mfccFramesSliced.push(full.subarray(start, end));
+    }
+
+    const s = weightedStats(mfccFramesSliced, 0, mfccFramesSliced.length, mfccDimHint ? Math.max(0, mfccDimHint - 1) : 0);
+    mfccStats = { mean: s.mean, variance: s.variance };
+  }
+
+  return {
+    version: "v1",
+    t0: tt0,
+    t1: tt1,
+    mel: {
+      mean: melStats.mean,
+      variance: melStats.variance,
+    },
+    onset: {
+      mean: onsetMean,
+      max: onsetMaxSafe,
+      peakDensityHz,
+    },
+    ...(mfccStats ? { mfcc: mfccStats } : {}),
+  };
+}

package/src/search/refinedModelV1.ts

@@ -0,0 +1,321 @@
+import type { MirFeatureVectorLayoutV1 } from "./featureVectorV1";
+
+export type MirRefinedModelKindV1 = "baseline" | "prototype" | "logistic";
+
+export type MirRefinedModelExplainV1 = {
+    kind: MirRefinedModelKindV1;
+    positives: number;
+    negatives: number;
+
+    /** L2 norms per feature group (useful as a cheap, stable explainability hook). */
+    weightL2?: {
+        mel: number;
+        melForeground: number;
+        melContrast?: number;
+        onset: number;
+        onsetForeground: number;
+        onsetContrast?: number;
+        mfcc?: number;
+        mfccForeground?: number;
+        mfccContrast?: number;
+    };
+
+    /** Training diagnostics (only for logistic). */
+    training?: {
+        iterations: number;
+        finalLoss: number;
+    };
+};
+
+export type MirLogisticModelV1 = {
+    kind: "logistic";
+    w: Float32Array;
+    b: number;
+    explain: MirRefinedModelExplainV1;
+};
+
+export type MirPrototypeModelV1 = {
+    kind: "prototype";
+    prototype: Float32Array;
+    explain: MirRefinedModelExplainV1;
+};
+
+export type MirBaselineModelV1 = {
+    kind: "baseline";
+    explain: MirRefinedModelExplainV1;
+};
+
+export type MirRefinedModelV1 = MirBaselineModelV1 | MirPrototypeModelV1 | MirLogisticModelV1;
+
+export type MirLogitContributionsByGroupV1 = {
+    logit: number;
+    bias: number;
+    mel: number;
+    melForeground: number;
+    melContrast?: number;
+    onset: number;
+    onsetForeground: number;
+    onsetContrast?: number;
+    mfcc?: number;
+    mfccForeground?: number;
+    mfccContrast?: number;
+};
+
+function clamp01(x: number): number {
+    return x <= 0 ? 0 : x >= 1 ? 1 : x;
+}
+
+function sigmoid(x: number): number {
+    // Prevent overflow in exp(); ±20 already saturates for our purposes.
+    const z = x > 20 ? 20 : x < -20 ? -20 : x;
+    return 1 / (1 + Math.exp(-z));
+}
+
+function dot(a: Float32Array, b: Float32Array): number {
+    const n = Math.min(a.length, b.length);
+    let s = 0;
+    for (let i = 0; i < n; i++) s += (a[i] ?? 0) * (b[i] ?? 0);
+    return s;
+}
+
+function sliceDot(w: Float32Array, x: Float32Array, offset: number, length: number): number {
+    const end = Math.min(w.length, x.length, offset + length);
+    let sum = 0;
+    for (let i = offset; i < end; i++) sum += (w[i] ?? 0) * (x[i] ?? 0);
+    return sum;
+}
+
+export function logitContributionsByGroupV1(
+    w: Float32Array,
+    b: number,
+    x: Float32Array,
+    layout: MirFeatureVectorLayoutV1
+): MirLogitContributionsByGroupV1 {
+    const melForeground =
+        sliceDot(w, x, layout.melMeanFg.offset, layout.melMeanFg.length) +
+        sliceDot(w, x, layout.melVarianceFg.offset, layout.melVarianceFg.length);
+    const melContrast = layout.melContrast ? sliceDot(w, x, layout.melContrast.offset, layout.melContrast.length) : 0;
+    const onsetForeground = sliceDot(w, x, layout.onsetFg.offset, layout.onsetFg.length);
+    const onsetContrast = layout.onsetContrast ? sliceDot(w, x, layout.onsetContrast.offset, layout.onsetContrast.length) : 0;
+
+    const mfccForeground =
+        layout.mfccMeanFg && layout.mfccVarianceFg
+            ? sliceDot(w, x, layout.mfccMeanFg.offset, layout.mfccMeanFg.length) +
+              sliceDot(w, x, layout.mfccVarianceFg.offset, layout.mfccVarianceFg.length)
+            : 0;
+    const mfccContrast =
+        layout.mfccMeanContrast && layout.mfccVarianceContrast
+            ? sliceDot(w, x, layout.mfccMeanContrast.offset, layout.mfccMeanContrast.length) +
+              sliceDot(w, x, layout.mfccVarianceContrast.offset, layout.mfccVarianceContrast.length)
+            : 0;
+
+    const mel = melForeground + melContrast;
+    const onset = onsetForeground + onsetContrast;
+    const mfcc = mfccForeground + mfccContrast;
+
+    const logit = mel + onset + mfcc + b;
+
+    return {
+        logit,
+        bias: b,
+        mel,
+        melForeground,
+        ...(layout.melContrast ? { melContrast } : {}),
+        onset,
+        onsetForeground,
+        ...(layout.onsetContrast ? { onsetContrast } : {}),
+        ...(layout.mfccMeanFg || layout.mfccMeanContrast
+            ? {
+                mfcc,
+                mfccForeground,
+                ...(layout.mfccMeanContrast ? { mfccContrast } : {}),
+            }
+            : {}),
+    };
+}
+
+function l2Norm(v: Float32Array): number {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        const x = v[i] ?? 0;
+        sum += x * x;
+    }
+    return Math.sqrt(sum);
+}
+
+function cosineSimilarity01(a: Float32Array, b: Float32Array): number {
+    const n = Math.min(a.length, b.length);
+    let ab = 0;
+    let aa = 0;
+    let bb = 0;
+    for (let i = 0; i < n; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        ab += x * y;
+        aa += x * x;
+        bb += y * y;
+    }
+    const denom = Math.sqrt(aa) * Math.sqrt(bb);
+    if (denom <= 0) return 0;
+    const cos = ab / denom;
+    const clamped = Math.max(-1, Math.min(1, cos));
+    return (clamped + 1) / 2;
+}
+
+function sliceSumSquares(w: Float32Array, offset: number, length: number): number {
+    let sum = 0;
+    const end = Math.min(w.length, offset + length);
+    for (let i = offset; i < end; i++) {
+        const x = w[i] ?? 0;
+        sum += x * x;
+    }
+    return sum;
+}
+
+export function summariseWeightL2ByGroup(w: Float32Array, layout: MirFeatureVectorLayoutV1): MirRefinedModelExplainV1["weightL2"] {
+    const melForegroundSq =
+        sliceSumSquares(w, layout.melMeanFg.offset, layout.melMeanFg.length) +
+        sliceSumSquares(w, layout.melVarianceFg.offset, layout.melVarianceFg.length);
+    const melContrastSq = layout.melContrast ? sliceSumSquares(w, layout.melContrast.offset, layout.melContrast.length) : 0;
+    const onsetForegroundSq = sliceSumSquares(w, layout.onsetFg.offset, layout.onsetFg.length);
+    const onsetContrastSq = layout.onsetContrast ? sliceSumSquares(w, layout.onsetContrast.offset, layout.onsetContrast.length) : 0;
+
+    const mfccForegroundSq =
+        layout.mfccMeanFg && layout.mfccVarianceFg
+            ? sliceSumSquares(w, layout.mfccMeanFg.offset, layout.mfccMeanFg.length) +
+              sliceSumSquares(w, layout.mfccVarianceFg.offset, layout.mfccVarianceFg.length)
+            : 0;
+    const mfccContrastSq =
+        layout.mfccMeanContrast && layout.mfccVarianceContrast
+            ? sliceSumSquares(w, layout.mfccMeanContrast.offset, layout.mfccMeanContrast.length) +
+              sliceSumSquares(w, layout.mfccVarianceContrast.offset, layout.mfccVarianceContrast.length)
+            : 0;
+
+    const mel = Math.sqrt(melForegroundSq + melContrastSq);
+    const onset = Math.sqrt(onsetForegroundSq + onsetContrastSq);
+    const mfcc = mfccForegroundSq + mfccContrastSq > 0 ? Math.sqrt(mfccForegroundSq + mfccContrastSq) : undefined;
+
+    return {
+        mel,
+        melForeground: Math.sqrt(melForegroundSq),
+        ...(melContrastSq > 0 ? { melContrast: Math.sqrt(melContrastSq) } : {}),
+        onset,
+        onsetForeground: Math.sqrt(onsetForegroundSq),
+        ...(onsetContrastSq > 0 ? { onsetContrast: Math.sqrt(onsetContrastSq) } : {}),
+        ...(mfcc != null
+            ? {
+                mfcc,
+                mfccForeground: Math.sqrt(mfccForegroundSq),
+                ...(mfccContrastSq > 0 ? { mfccContrast: Math.sqrt(mfccContrastSq) } : {}),
+            }
+            : {}),
+    };
+}
+
+export function trainLogisticModelV1(params: {
+    positives: Float32Array[];
+    negatives: Float32Array[];
+    layout: MirFeatureVectorLayoutV1;
+    options?: { iterations?: number; learningRate?: number; l2?: number };
+}): MirLogisticModelV1 {
+    const pos = params.positives;
+    const neg = params.negatives;
+    const dim = params.layout.dim;
+
+    // Small, deterministic batch GD: fast enough for < 50 samples and a few hundred dims.
+    const iterations = Math.max(1, params.options?.iterations ?? 80);
+    const learningRate = Math.max(1e-4, params.options?.learningRate ?? 0.15);
+    const l2 = Math.max(0, params.options?.l2 ?? 0.01);
+
+    const w = new Float32Array(dim);
+    let b = 0;
+
+    const posW = pos.length > 0 ? 0.5 / pos.length : 0;
+    const negW = neg.length > 0 ? 0.5 / neg.length : 0;
+
+    let lastLoss = Infinity;
+    let itersUsed = 0;
+
+    for (let iter = 0; iter < iterations; iter++) {
+        itersUsed = iter + 1;
+
+        const gradW = new Float32Array(dim);
+        let gradB = 0;
+        let loss = 0;
+
+        const accumulate = (x: Float32Array, y: 0 | 1, weight: number) => {
+            const s = dot(w, x) + b;
+            const p = sigmoid(s);
+            const err = p - y; // dL/ds for logistic loss
+
+            gradB += weight * err;
+            for (let j = 0; j < dim; j++) gradW[j] = (gradW[j] ?? 0) + weight * err * (x[j] ?? 0);
+
+            // Weighted cross-entropy loss
+            const pSafe = Math.min(1 - 1e-9, Math.max(1e-9, p));
+            loss += weight * (y ? -Math.log(pSafe) : -Math.log(1 - pSafe));
+        };
+
+        for (const x of pos) accumulate(x, 1, posW);
+        for (const x of neg) accumulate(x, 0, negW);
+
+        // L2 regularisation (do not regularise bias).
+        if (l2 > 0) {
+            for (let j = 0; j < dim; j++) {
+                gradW[j] = (gradW[j] ?? 0) + l2 * (w[j] ?? 0);
+            }
+            loss += (l2 * (l2Norm(w) ** 2)) / 2;
+        }
+
+        // Basic learning-rate decay helps stability on small datasets.
+        const lr = learningRate / (1 + iter * 0.01);
+        for (let j = 0; j < dim; j++) w[j] = (w[j] ?? 0) - lr * (gradW[j] ?? 0);
+        b -= lr * gradB;
+
+        if (Math.abs(lastLoss - loss) < 1e-6) break;
+        lastLoss = loss;
+    }
+
+    return {
+        kind: "logistic",
+        w,
+        b,
+        explain: {
+            kind: "logistic",
+            positives: pos.length,
+            negatives: neg.length,
+            weightL2: summariseWeightL2ByGroup(w, params.layout),
+            training: { iterations: itersUsed, finalLoss: Number.isFinite(lastLoss) ? lastLoss : 0 },
+        },
+    };
+}
+
+export function buildPrototypeModelV1(params: {
+    positives: Float32Array[];
+    layout: MirFeatureVectorLayoutV1;
+}): MirPrototypeModelV1 {
+    const dim = params.layout.dim;
+    const proto = new Float32Array(dim);
+
+    const n = Math.max(1, params.positives.length);
+    for (const x of params.positives) {
+        for (let j = 0; j < dim; j++) proto[j] = (proto[j] ?? 0) + (x[j] ?? 0) / n;
+    }
+
+    return {
+        kind: "prototype",
+        prototype: proto,
+        explain: {
+            kind: "prototype",
+            positives: params.positives.length,
+            negatives: 0,
+        },
+    };
+}
+
+export function scoreWithModelV1(model: MirRefinedModelV1, x: Float32Array): number {
+    if (model.kind === "baseline") return 0;
+    if (model.kind === "prototype") return clamp01(cosineSimilarity01(model.prototype, x));
+    // logistic
+    return clamp01(sigmoid(dot(model.w, x) + model.b));
+}