@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/src/router/memory-distillation.ts

@@ -0,0 +1,249 @@
+/**
+ * router/memory-distillation.ts — RETRIEVE → JUDGE → DISTILL →
+ * CONSOLIDATE (ADR-174) as a pure TypeScript module.
+ *
+ * v6.4.0 — ported from ruflo `@claude-flow/neural/src/reasoning-bank.ts`
+ * (the 4-step pipeline) + ADR-174 (provenance-tiered promote gate).
+ *
+ * This is the $0 default path — deterministic, no LLM, no I/O.
+ * Living inside the SDK (rather than the dashboard .mjs files) so
+ * the `memory_distill` MCP tool can call it via a static TypeScript
+ * import without crossing the ESM/CJS boundary at runtime.
+ *
+ * The dashboard's `bizar-dash/src/server/memory-{distillation,
+ * consolidator}.mjs` re-export the same semantics and add the
+ * vault I/O (read notes, write promoted patterns back). Both paths
+ * agree on the `Pattern` shape so the schema is one-of.
+ */
+
+export const PROVENANCE_TIERS = [
+  "oracle:test-exec",
+  "proxy:structural",
+  "judge:fable",
+] as const;
+
+export type ProvenanceTier = (typeof PROVENANCE_TIERS)[number];
+
+export interface MemoryEntryLike {
+  memory_id?: string;
+  id?: string;
+  path?: string;
+  relPath?: string;
+  frontmatter?: Record<string, unknown>;
+  body?: string;
+  kind?: string;
+  type?: string;
+  created?: string;
+  createdAt?: string;
+  tags?: unknown;
+}
+
+export interface Retrieval {
+  complexity: "simple" | "moderate" | "complex";
+  testExec: boolean;
+  hasCodeBlock: boolean;
+  length: number;
+}
+
+export interface Pattern {
+  id: string;
+  kind: "pattern";
+  summary: string;
+  uses: string[];
+  evidence: string[];
+  provenance_tier: ProvenanceTier;
+  promoted: boolean;
+  score: number;
+}
+
+export interface DistillationResult {
+  patterns: Pattern[];
+  promoted: Pattern[];
+  byTier: Record<ProvenanceTier, number>;
+}
+
+const COMPLEXITY_SIMPLE_MAX = 600;
+const COMPLEXITY_MODERATE_MAX = 2400;
+
+function firstLine(s: string): string {
+  if (!s) return "";
+  const i = s.indexOf("\n");
+  return (i < 0 ? s : s.slice(0, i)).trim();
+}
+
+function snippet(body: string): string {
+  const cleaned = body.replace(/\s+/g, " ").trim();
+  return cleaned.length <= 200 ? cleaned : cleaned.slice(0, 200) + "…";
+}
+
+function shorten(s: string): string {
+  let h = 5381 >>> 0;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  }
+  return h.toString(36).slice(0, 10);
+}
+
+function wordSet(s: string): Set<string> {
+  const out = new Set<string>();
+  const norm = (s || "").toLowerCase().replace(/[^a-z0-9\s]+/g, " ");
+  for (const w of norm.split(/\s+/)) {
+    if (w.length > 2) out.add(w);
+  }
+  return out;
+}
+
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter += 1;
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+function dedupe<T>(arr: T[]): T[] {
+  const seen = new Set<T>();
+  const out: T[] = [];
+  for (const x of arr) if (!seen.has(x)) { seen.add(x); out.push(x); }
+  return out;
+}
+
+export function retrieve(entry: MemoryEntryLike): Retrieval {
+  const body = String(entry?.body ?? "");
+  const fm = entry?.frontmatter ?? {};
+  const hasCodeBlock = /```/.test(body);
+  const tagsArr = Array.isArray(fm.tags) ? fm.tags : [];
+  const testExec =
+    Boolean(fm.test_exec) ||
+    Boolean(fm.testExec) ||
+    tagsArr.some((t) => String(t).includes("test-exec")) ||
+    String(fm.kind ?? "") === "feedback";
+  const len = body.length;
+  let complexity: Retrieval["complexity"];
+  if (hasCodeBlock || len > COMPLEXITY_MODERATE_MAX) complexity = "complex";
+  else if (len > COMPLEXITY_SIMPLE_MAX) complexity = "moderate";
+  else complexity = "simple";
+  return { complexity, testExec, hasCodeBlock, length: len };
+}
+
+export function judge(_entry: MemoryEntryLike, retrieval: Retrieval): ProvenanceTier {
+  if (retrieval.testExec) return "oracle:test-exec";
+  return "proxy:structural";
+}
+
+export function distill(entry: MemoryEntryLike): Omit<Pattern, "provenance_tier" | "promoted" | "score"> | null {
+  const fm = entry?.frontmatter ?? {};
+  const body = String(entry?.body ?? "").trim();
+  const id = String(entry?.memory_id ?? entry?.id ?? entry?.path ?? entry?.relPath ?? "");
+  const kindRaw = String(fm.kind ?? entry?.kind ?? entry?.type ?? "").toLowerCase();
+
+  if (kindRaw === "coding_convention" || kindRaw === "bug_pattern") {
+    return {
+      id: `pat_${shorten(id || body.slice(0, 24))}`,
+      kind: "pattern",
+      summary: firstLine(body) || "(empty)",
+      uses: id ? [id] : [],
+      evidence: [snippet(body)],
+    };
+  }
+
+  const head = firstLine(body).toLowerCase();
+  if (
+    kindRaw === "task_summary" ||
+    kindRaw === "session_summary" ||
+    /\bpattern\s*:/.test(head) ||
+    /^\s*(use|avoid|do|don't)\s*:/.test(head)
+  ) {
+    return {
+      id: `pat_${shorten(id || head.replace(/\W+/g, " ").slice(0, 24))}`,
+      kind: "pattern",
+      summary: firstLine(body) || "(empty)",
+      uses: id ? [id] : [],
+      evidence: [snippet(body)],
+    };
+  }
+  return null;
+}
+
+/**
+ * Distillation candidates carry their tier separately; we shift it on
+ * to `provenance_tier` here and set the `promoted` flag.
+ */
+interface Candidate {
+  id: string;
+  kind: "pattern";
+  summary: string;
+  uses: string[];
+  evidence: string[];
+  _tier: ProvenanceTier;
+}
+
+export function runDistillation(entries: MemoryEntryLike[]): DistillationResult {
+  const empty = {
+    patterns: [] as Pattern[],
+    promoted: [] as Pattern[],
+    byTier: { "oracle:test-exec": 0, "proxy:structural": 0, "judge:fable": 0 } as Record<ProvenanceTier, number>,
+  };
+  if (!Array.isArray(entries) || entries.length === 0) return empty;
+
+  const candidates: Candidate[] = [];
+  for (const entry of entries) {
+    const retrieval = retrieve(entry);
+    const tier = judge(entry, retrieval);
+    const pattern = distill(entry);
+    if (!pattern) continue;
+    candidates.push({ ...pattern, _tier: tier });
+  }
+
+  // Cluster by Jaccard similarity ≥ 0.5 over (summary + evidence).
+  const groups: { rep: Candidate; members: Candidate[] }[] = [];
+  for (const c of candidates) {
+    const ws = wordSet(c.summary + " " + c.evidence.join(" "));
+    let placed = false;
+    for (const g of groups) {
+      const gs = wordSet(g.rep.summary + " " + g.rep.evidence.join(" "));
+      if (jaccard(ws, gs) >= 0.5) {
+        g.members.push(c);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) groups.push({ rep: c, members: [c] });
+  }
+
+  const byTier: Record<ProvenanceTier, number> = {
+    "oracle:test-exec": 0,
+    "proxy:structural": 0,
+    "judge:fable": 0,
+  };
+  const patterns: Pattern[] = [];
+  for (const g of groups) {
+    const usesSet = new Set<string>();
+    const evidence: string[] = [];
+    for (const m of g.members) {
+      for (const u of m.uses ?? []) usesSet.add(u);
+      for (const e of m.evidence ?? []) evidence.push(e);
+    }
+    const tiers = g.members.map((m) => m._tier);
+    let tier: ProvenanceTier = "proxy:structural";
+    if (tiers.includes("oracle:test-exec")) tier = "oracle:test-exec";
+    else if (tiers.includes("judge:fable")) tier = "judge:fable";
+
+    const promoted = usesSet.size >= 1 && (tier === "oracle:test-exec" || tier === "judge:fable");
+    const pattern: Pattern = {
+      id: g.rep.id,
+      kind: "pattern",
+      summary: g.rep.summary,
+      uses: Array.from(usesSet),
+      evidence: dedupe(evidence).slice(0, 5),
+      provenance_tier: tier,
+      promoted,
+      score: 0.5 + usesSet.size * 0.1,
+    };
+    patterns.push(pattern);
+    byTier[tier] += 1;
+  }
+
+  const promoted = patterns.filter((p) => p.promoted);
+  return { patterns, promoted, byTier };
+}

package/packages/sdk/src/router/model-router.ts

@@ -0,0 +1,235 @@
+/**
+ * router/model-router.ts — Adaptive model-tier router.
+ *
+ * v6.4.0 — ported from ruflo `model-router.ts` (Thompson-sampling bandit,
+ * ADR-026 + ADR-143). Trims the surface to what Bizar needs:
+ *
+ *   - 3 tiers:  `flash` (cheap),  `mid` (default),  `expensive`
+ *   - Per-tier Beta(α, β) priors, updated by `recordOutcome()`.
+ *   - Marsaglia-Tsang Gamma sampler + Box-Muller normal → sample from Beta
+ *     by drawing two Gamma(shape, 1) variates and dividing.
+ *   - Tier-1 codemod short-circuit: if `detectCodemodIntent()` says the
+ *     prompt is codemod-eligible, we return `{tier: 'flash'}` with
+ *     confidence 1.0 and tag `codemodIntent` on the result. This is the
+ *     $0 path — no model call required.
+ *
+ * The tier names match Bizar's actual model lineup
+ * (`m2.7-flash`, `m2.7`, `m3`). The ruflo vocabulary uses
+ * `haiku / sonnet / opus`; we rename to `flash / mid / expensive`
+ * so future call-site code reads naturally.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import { detectCodemodIntent } from "./codemod-intent.js";
+
+export type ModelTier = "flash" | "mid" | "expensive";
+
+export interface RouteDecision {
+  tier: ModelTier;
+  confidence: number;
+  codemodIntent?: "var-to-const" | "remove-console" | "add-logging";
+}
+
+export interface BetaPrior {
+  alpha: number;
+  beta: number;
+}
+
+const TIERS: ModelTier[] = ["flash", "mid", "expensive"];
+
+/**
+ * Default priors — slight optimism for `flash` (so it gets tried for
+ * cheap prompts), uniform for `mid`, slight pessimism for `expensive`
+ * (it should have to earn its keep). Adjust here, not at the call site.
+ */
+const DEFAULT_PRIORS: Record<ModelTier, BetaPrior> = {
+  flash:     { alpha: 2, beta: 1 }, // mean 2/3 ≈ 0.67
+  mid:       { alpha: 1, beta: 1 }, // mean 0.5
+  expensive: { alpha: 1, beta: 2 }, // mean 1/3 ≈ 0.33
+};
+
+export class ModelRouter {
+  private priors: Record<ModelTier, BetaPrior>;
+  private rngState: number;
+
+  constructor(opts?: { priors?: Partial<Record<ModelTier, BetaPrior>>; seed?: number }) {
+    this.priors = {
+      flash:     { ...DEFAULT_PRIORS.flash,     ...(opts?.priors?.flash     ?? {}) },
+      mid:       { ...DEFAULT_PRIORS.mid,       ...(opts?.priors?.mid       ?? {}) },
+      expensive: { ...DEFAULT_PRIORS.expensive, ...(opts?.priors?.expensive ?? {}) },
+    };
+    // LCG seed for reproducible sampling in tests. Default uses
+    // Math.random() when seed is not provided.
+    this.rngState = (opts?.seed ?? 0) | 0;
+  }
+
+  /** Read-only access for telemetry / tests. */
+  getPriors(): Record<ModelTier, BetaPrior> {
+    return {
+      flash: { ...this.priors.flash },
+      mid: { ...this.priors.mid },
+      expensive: { ...this.priors.expensive },
+    };
+  }
+
+  /**
+   * Pick a tier for `prompt`. Codemod-eligible prompts short-circuit
+   * to `flash` (the Tier-1 $0 path). Otherwise we Thompson-sample each
+   * tier and return the highest sample, with confidence = max_sample
+   * (the posterior mean is `α/(α+β)`, and the max-sampled value is a
+   * lower bound on the probability that this tier beats the others).
+   */
+  route(prompt: string): RouteDecision {
+    // Tier-1 codemod short-circuit ($0).
+    const cm = detectCodemodIntent(prompt);
+    if (cm !== null) {
+      return { tier: "flash", confidence: 1.0, codemodIntent: cm.intent };
+    }
+
+    let best: { tier: ModelTier; sample: number } | null = null;
+    for (const tier of TIERS) {
+      const prior = this.priors[tier];
+      const sample = this.sampleBeta(prior.alpha, prior.beta);
+      if (best === null || sample > best.sample) {
+        best = { tier, sample };
+      }
+    }
+    const confidence = clamp01(best ? best.sample : 0.5);
+    return { tier: best ? best.tier : "mid", confidence };
+  }
+
+  /**
+   * Update the per-tier prior after observing the outcome of a call.
+   * `success === true` increments α; `success === false` increments β.
+   * Cost-adjusted (ruflo ADR-026 §BANDIT_REWARDS):
+   * - flash-success:    +1.0 → α++           (cheap wins are gold)
+   * - mid-success:      +0.7 → α += 0.7      (still good)
+   * - expensive-success:+0.4 → α += 0.4      (expensive wins are wasteful)
+   * - any failure:      β ++
+   *
+   * The fractional updates work fine with the Beta sampler.
+   */
+  recordOutcome(tier: ModelTier, success: boolean): void {
+    const prior = this.priors[tier];
+    if (!prior) return;
+    if (success) {
+      const reward = tier === "flash" ? 1.0 : tier === "mid" ? 0.7 : 0.4;
+      prior.alpha += reward;
+    } else {
+      prior.beta += 1;
+    }
+  }
+
+  // -----------------------------------------------------------------
+  // Sampling primitives (lifted from ruflo model-router.ts).
+  // Marsaglia-Tsang Gamma + Box-Muller normal. Module-local so we
+  // don't pull a stats library for one sampler.
+  // -----------------------------------------------------------------
+
+  /** Seeded or Math.random()-backed uniform in [0,1). */
+  private random(): number {
+    if (this.rngState !== 0) {
+      // LCG (Numerical Recipes). Period ~2^32.
+      this.rngState = (this.rngState * 1664525 + 1013904223) | 0;
+      const u = (this.rngState >>> 0) / 0xffffffff;
+      return u || 1e-12;
+    }
+    return Math.random() || 1e-12;
+  }
+
+  /** Box-Muller standard normal sample. */
+  private sampleStandardNormal(): number {
+    const u1 = this.random();
+    const u2 = this.random();
+    return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  }
+
+  /** Marsaglia-Tsang Gamma sample for shape α≥1 (with boost for α<1). */
+  private sampleGamma(alpha: number): number {
+    if (alpha < 1) {
+      const u = this.random();
+      return this.sampleGamma(alpha + 1) * Math.pow(u, 1 / alpha);
+    }
+    const d = alpha - 1 / 3;
+    const c = 1 / Math.sqrt(9 * d);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      let x = this.sampleStandardNormal();
+      let v = 1 + c * x;
+      if (v <= 0) continue;
+      v = v * v * v;
+      const u = this.random();
+      const xx = x * x;
+      if (u < 1 - 0.0331 * xx * xx) return d * v;
+      if (Math.log(u) < 0.5 * xx + d * (1 - v + Math.log(v))) return d * v;
+    }
+  }
+
+  /** Sample from Beta(α, β) via two Gamma draws. */
+  private sampleBeta(alpha: number, beta: number): number {
+    const x = this.sampleGamma(alpha);
+    const y = this.sampleGamma(beta);
+    const denom = x + y;
+    if (denom <= 0) return alpha / (alpha + beta);
+    return x / denom;
+  }
+
+  // -----------------------------------------------------------------
+  // Persistence (ADR-174 invariant: router state survives restarts).
+  // We avoid native deps — `.harness/router-state.json` is the
+  // canonical store; loading is best-effort and falls back to
+  // defaults if the file is missing or corrupt.
+  // -----------------------------------------------------------------
+
+  /** JSON snapshot of the current per-tier priors + RNG seed. */
+  snapshot(): RouterStateSnapshot {
+    return {
+      version: 1,
+      priors: this.getPriors(),
+      rngSeed: this.rngState,
+    };
+  }
+
+  /** Restore from a snapshot; defaults applied where fields are missing. */
+  static fromSnapshot(snap: Partial<RouterStateSnapshot>): ModelRouter {
+    return new ModelRouter({
+      priors: snap.priors,
+      seed: snap.rngSeed,
+    });
+  }
+
+  /** Persist state to `path`. Creates parent dirs as needed. */
+  saveTo(path: string): void {
+    const fp = isAbsolute(path) ? path : resolve(path);
+    mkdirSync(dirname(fp), { recursive: true });
+    writeFileSync(fp, JSON.stringify(this.snapshot(), null, 2), "utf-8");
+  }
+
+  /** Load state from `path`. Returns a default router if file is
+   *  missing or unparseable. Does NOT throw. */
+  static loadFrom(path: string): ModelRouter {
+    try {
+      if (!existsSync(path)) return new ModelRouter();
+      const raw = readFileSync(path, "utf-8");
+      const snap = JSON.parse(raw) as Partial<RouterStateSnapshot>;
+      return ModelRouter.fromSnapshot(snap);
+    } catch {
+      return new ModelRouter();
+    }
+  }
+}
+
+export interface RouterStateSnapshot {
+  version: number;
+  priors: Record<ModelTier, BetaPrior>;
+  rngSeed: number;
+}
+
+function clamp01(n: number): number {
+  if (Number.isNaN(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}