@polderlabs/bizar 6.3.0 → 7.0.0

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;
+}

package/packages/sdk/src/router/q-learning-router.ts

@@ -0,0 +1,304 @@
+/**
+ * router/q-learning-router.ts — Q-learning agent router.
+ *
+ * v6.4.0 — ported from ruflo `q-learning-router.ts` (8-action softmax
+ * agent-route over coder / tester / reviewer / …).
+ *
+ * Bizar has more than 8 named agents, so the action set is the 8 most
+ * commonly delegated targets from `Agent` tool calls (matches
+ * `.claude/agents/*.md` to first 8 names). Adding the full
+ * 12-agent space could be done in a follow-up but each new agent
+ * increases state-action coverage cost; 8 keeps the bandit honest.
+ *
+ *   - State: a 64-dim bag-of-words hash of the task string (FNV-1a
+ *     folded into 64 buckets). LRU-cached so repeated task patterns
+ *     are O(1).
+ *   - Action: one of `odin|frigg|vor|mimir|heimdall|thor|tyr|forseti`.
+ *   - Reward: `+1` on `recordOutcome(agent, true)`, `0` on false.
+ *   - Exploration: ε-greedy with ε = 0.1 (configurable).
+ *
+ * `selectAgent()` returns `{agent, confidence}`. `confidence` is the
+ * posterior mean of the picked action's Q-value clamped to [0,1].
+ *
+ * Tiny surface area by design — the
+ * `AgentRouteDecision` shape is what `model_route` /
+ * `agent_route` MCP tools expose.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+import { detectCodemodIntent } from "./codemod-intent.js";
+
+export const AGENT_ACTIONS: readonly string[] = [
+  "odin",
+  "frigg",
+  "vor",
+  "mimir",
+  "heimdall",
+  "thor",
+  "tyr",
+  "forseti",
+] as const;
+
+export type AgentName = (typeof AGENT_ACTIONS)[number];
+
+export interface AgentRouteDecision {
+  agent: string;
+  confidence: number;
+}
+
+export interface QLearningRouterOpts {
+  stateDim?: number;
+  epsilon?: number;
+  lruSize?: number;
+  seed?: number;
+}
+
+const DEFAULT_STATE_DIM = 64;
+const DEFAULT_EPSILON = 0.1;
+const DEFAULT_LRU = 256;
+
+const STOPWORDS = new Set([
+  "the", "a", "an", "and", "or", "but", "in", "on", "at", "to",
+  "for", "of", "with", "by", "is", "are", "be", "was", "were", "this",
+  "that", "it", "as", "if", "from", "into", "so", "than",
+]);
+
+export class QLearningRouter {
+  private readonly stateDim: number;
+  private readonly epsilon: number;
+  private readonly lruSize: number;
+  // Q[agentIdx][stateBucket] → mean reward for that bucket.
+  // Initialised to 0.5 (neutral). Updated by EMA on recordOutcome.
+  private readonly q: Float32Array[] = [];
+  private readonly counts: Uint32Array[] = [];
+  private readonly lru: Map<string, AgentRouteDecision> = new Map();
+  private rngState: number;
+
+  constructor(opts?: QLearningRouterOpts) {
+    this.stateDim = opts?.stateDim ?? DEFAULT_STATE_DIM;
+    this.epsilon = opts?.epsilon ?? DEFAULT_EPSILON;
+    this.lruSize = opts?.lruSize ?? DEFAULT_LRU;
+    this.rngState = (opts?.seed ?? 0) | 0;
+    for (let i = 0; i < AGENT_ACTIONS.length; i++) {
+      this.q.push(new Float32Array(this.stateDim).fill(0.5));
+      this.counts.push(new Uint32Array(this.stateDim));
+    }
+  }
+
+  /**
+   * Greedy ε-soft policy. Returns a cached decision when the same
+   * (task) hash has been seen recently (LRU bounded by `lruSize`).
+   * Codemod-eligible prompts short-circuit to `heimdall` (the
+   * routine-implementation agent) so they still get a "best" agent
+   * without paying the bandit lookup cost twice.
+   */
+  selectAgent(task: string): AgentRouteDecision {
+    if (!task || typeof task !== "string") {
+      return { agent: "odin", confidence: 0.5 };
+    }
+
+    // Tier-1 codemod-eligible prompt → deterministic safe pick.
+    const cm = detectCodemodIntent(task);
+    if (cm !== null) {
+      return { agent: "heimdall", confidence: 1.0 };
+    }
+
+    const bucket = this.bucketize(task);
+    const cacheKey = String(bucket);
+    const cached = this.lru.get(cacheKey);
+    if (cached) {
+      // Touch the LRU entry to mark recently used.
+      this.lru.delete(cacheKey);
+      this.lru.set(cacheKey, cached);
+      return cached;
+    }
+
+    let agentIdx: number;
+    let confidence = 0.5;
+    if (this.random() < this.epsilon) {
+      // Explore: uniformly at random.
+      agentIdx = Math.floor(this.random() * AGENT_ACTIONS.length) % AGENT_ACTIONS.length;
+      confidence = 0.25;
+    } else {
+      // Exploit: argmax Q for this bucket. Tie-break by lower count
+      // (prefer the less-tried action), then by the canonical order.
+      let bestQ = -Infinity;
+      let bestCount = Infinity;
+      const ties: number[] = [];
+      for (let i = 0; i < AGENT_ACTIONS.length; i++) {
+        const qv = this.q[i][bucket];
+        if (qv > bestQ) {
+          bestQ = qv; bestCount = this.counts[i][bucket]; ties.length = 0; ties.push(i);
+        } else if (qv === bestQ) {
+          const c = this.counts[i][bucket];
+          if (c < bestCount) { bestCount = c; ties.length = 0; ties.push(i); }
+          else ties.push(i);
+        }
+      }
+      agentIdx = ties[Math.floor(this.random() * ties.length)] ?? 0;
+      confidence = clamp01(bestQ);
+    }
+
+    const decision: AgentRouteDecision = {
+      agent: AGENT_ACTIONS[agentIdx],
+      confidence,
+    };
+
+    // Promote to LRU. LRU has a hard cap; evict oldest on overflow.
+    if (this.lru.size >= this.lruSize) {
+      const oldest = this.lru.keys().next().value;
+      if (oldest !== undefined) this.lru.delete(oldest);
+    }
+    this.lru.set(cacheKey, decision);
+    return decision;
+  }
+
+  /**
+   * EMA update of Q[agentIdx][bucket]. Uses the standard
+   *   Q ← Q + α (reward − Q)
+   * where α = 1 / (1 + count) — decreasing step size over time.
+   */
+  recordOutcome(agent: string, success: boolean): void {
+    const idx = AGENT_ACTIONS.indexOf(agent as AgentName);
+    if (idx < 0) return;
+    // Reward shape: +1 success, 0 failure, normalised to [0,1] in Q.
+    const reward = success ? 1.0 : 0.0;
+    for (let b = 0; b < this.stateDim; b++) {
+      const c = this.counts[idx][b] + 1;
+      this.counts[idx][b] = c;
+      const alpha = 1 / (1 + c);
+      this.q[idx][b] = this.q[idx][b] + alpha * (reward - this.q[idx][b]);
+    }
+  }
+
+  /** Read-only access for tests / telemetry. */
+  snapshot(): Array<{ agent: string; qMean: number; n: number }> {
+    return AGENT_ACTIONS.map((agent, i) => {
+      let total = 0;
+      let n = 0;
+      for (let b = 0; b < this.stateDim; b++) {
+        total += this.q[i][b];
+        n += this.counts[i][b];
+      }
+      return {
+        agent,
+        qMean: n === 0 ? 0.5 : total / this.stateDim,
+        n,
+      };
+    });
+  }
+
+  // -----------------------------------------------------------------
+  // Persistence — same JSON-file policy as the model router.
+  // -----------------------------------------------------------------
+
+  /** Stable on-disk serialisation: Q-table per agent, counts, seed. */
+  fullSnapshot(): QLearningSnapshot {
+    const q: number[][] = [];
+    const counts: number[][] = [];
+    for (let i = 0; i < AGENT_ACTIONS.length; i++) {
+      q.push(Array.from(this.q[i]));
+      counts.push(Array.from(this.counts[i]));
+    }
+    return {
+      version: 1,
+      stateDim: this.stateDim,
+      epsilon: this.epsilon,
+      q,
+      counts,
+      rngSeed: this.rngState,
+    };
+  }
+
+  static fromSnapshot(snap: Partial<QLearningSnapshot>): QLearningRouter {
+    const inst = new QLearningRouter({
+      stateDim: snap.stateDim,
+      epsilon: snap.epsilon,
+      seed: snap.rngSeed,
+    });
+    if (snap.q && snap.counts) {
+      const dim = inst.stateDim;
+      for (let i = 0; i < Math.min(snap.q.length, AGENT_ACTIONS.length); i++) {
+        const row = snap.q[i] ?? [];
+        const crows = snap.counts[i] ?? [];
+        for (let b = 0; b < Math.min(dim, row.length); b++) {
+          inst.q[i][b] = row[b];
+          inst.counts[i][b] = crows[b] ?? 0;
+        }
+      }
+    }
+    return inst;
+  }
+
+  saveTo(path: string): void {
+    const fp = isAbsolute(path) ? path : resolve(path);
+    mkdirSync(dirname(fp), { recursive: true });
+    writeFileSync(fp, JSON.stringify(this.fullSnapshot(), null, 2), "utf-8");
+  }
+
+  static loadFrom(path: string): QLearningRouter {
+    try {
+      if (!existsSync(path)) return new QLearningRouter();
+      const snap = JSON.parse(readFileSync(path, "utf-8")) as Partial<QLearningSnapshot>;
+      return QLearningRouter.fromSnapshot(snap);
+    } catch {
+      return new QLearningRouter();
+    }
+  }
+
+  // -----------------------------------------------------------------
+  // Helpers (FNV-1a bucketing + seeded RNG).
+  // -----------------------------------------------------------------
+
+  /** FNV-1a 32-bit hash, folded into [0, stateDim). Bag-of-words. */
+  private bucketize(text: string): number {
+    // Tokenise, drop stopwords.
+    const tokens = text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]+/g, " ")
+      .split(/\s+/)
+      .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+
+    // If everything was stopwords, the whole string is its own bucket.
+    const words = tokens.length > 0 ? tokens : [text.toLowerCase().trim()];
+
+    let acc = 2166136261 >>> 0; // FNV-1a init.
+    for (const w of words) {
+      let h = 2166136261 >>> 0;
+      for (let i = 0; i < w.length; i++) {
+        h ^= w.charCodeAt(i);
+        h = Math.imul(h, 16777619) >>> 0;
+      }
+      acc ^= h;
+      acc = Math.imul(acc + 0x9e3779b9, 16777619) >>> 0;
+    }
+    return acc % this.stateDim;
+  }
+
+  private random(): number {
+    if (this.rngState !== 0) {
+      this.rngState = (this.rngState * 1664525 + 1013904223) | 0;
+      const u = (this.rngState >>> 0) / 0xffffffff;
+      return u || 1e-12;
+    }
+    return Math.random() || 1e-12;
+  }
+}
+
+export interface QLearningSnapshot {
+  version: number;
+  stateDim: number;
+  epsilon: number;
+  q: number[][];
+  counts: number[][];
+  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;
+}